Agent 工具合同 v5¶

本设计约束 TraderHarness 中全部 30 个 Agent 工具。目标是让模型在首次调用前看懂参数， 调用失败后能在同一市场阶段完成纠错，并让运行结果可以从 Schema、轨迹和 replay 三个层面审计。

合同边界¶

• v5 是新运行的默认合同；v1–v4 继续使用历史描述、Schema、消息顺序和序列化规则，保证旧 cassette 可回放。
• 每个 v5 输入对象都设置 additionalProperties: false，所有字段带说明，并声明枚举、范围、默认值和条件必填关系。
• 每个工具描述都包含可复制的 arguments 示例、成功结果摘要和统一失败合同。
• 本地验证先于实体反遮罩和 handler 执行。参数无效时不会进入工具实现，更不会进入撮合路径。
• DeepSeek 兼容端点并不统一支持供应商侧 strict mode，因此 v5 在本地执行确定性 Schema 校验；这不改变 API 供应商。

成功结果统一增加 success: true。失败结果统一为：

{
  "success": false,
  "error": "给人和模型阅读的具体错误",
  "error_code": "稳定机器码",
  "retryable": true,
  "correction": {
    "tool": "工具名",
    "instruction": "同阶段如何修正",
    "valid_arguments_example": {},
    "received_arguments": {}
  }
}

retryable: true 的错误会保持为阶段内待办。Agent 必须让同一工具成功，或者在 complete_phase / finish_day 的 abandon_error_codes 中显式放弃并在摘要解释；否则市场时钟不推进。 结束工具本身也经过同一校验。收盘兜底最多进行三次可见纠错，失败会写入 _finish_day_protocol_failure 和轨迹，不再静默吞掉错误。

工具清单¶

证券代码字段统一要求复制完整可见代码。开启实体遮罩时，例如 SHM-000360 必须保留板块前缀； 只提交六位后缀产生歧义时，错误会返回 candidate_aliases 和完整的 retry_argument_choices。

大结果与沙箱¶

超过 3000 字符的 v5 工具结果不再截断原始 JSON 字符串。系统会逐级压缩数组和长文本，返回仍可解析的 JSON，并附 _truncation、原长度和缩小查询范围的说明。v1–v4 保留旧序列化以兼容 replay。

沙箱仍遵守项目的进程内、只读市场视图边界。v5 为 Python 字节码安装 deadline trace；超时后确认工作线程 退出，并返回 sandbox_timeout。API 访问同时受 Agent 卡工具 allowlist 约束：例如全市场日线需要 get_kline 权限，行为特征需要 screen_behavioral_cycle 或 get_kline 权限。沙箱仍不能读取 canonical dataset，也不能启动嵌套回测。

审计¶

自动合同测试遍历全部 30 个工具，验证工具目录、输入/输出合同、字段说明和调用示例一一对应；还覆盖：

• 无效类型、未知字段和缺失字段不会进入 handler；
• handler 的历史字符串错误会被规范化；
• 大结果压缩后仍是合法 JSON；
• 结束工具失败不能推进阶段；
• finish_day JSON 错误可自动重试；
• 沙箱真实死循环被终止；
• v2 内置真实数据 cassette 仍逐请求匹配。

验证命令：

.venv\Scripts\python.exe -m ruff check traderharness tests
.venv\Scripts\python.exe -m pytest tests --no-header -q
traderharness audit <artifact>