feat(agent): improve investigation contracts and runtime readiness

2026-11-07 19:43:57 +08:00
parent c7b750b099
commit b8f7edb3ee
29 changed files with 1465 additions and 119 deletions
@@ -216,6 +216,12 @@ Agent 启动时也执行同一检查，失败则不监听 HTTP。常见结果如

 外部 OpenCode 还需通过 `serviceOpencodeConfig` 加载同一份模型配置、可信插件包 `.opencode/tjwater-plugin/` 和业务指令。其 `TJWATER_AGENT_WORKSPACE_ROOT` 必须与 Agent 的 `CONVERSATION_WORKSPACE_ROOT` 指向同一个绝对目录，同时设置 `TJWATER_AGENT_INTERNAL_BASE_URL` 指向 Agent 内部工具桥。只启动一个普通 OpenCode 服务不足以完成接入；缺少业务工具、模型检查 RPC 或目录绑定会导致预热失败。

+每次开始或恢复模型执行前，还会在该会话实际的工作目录核对工具目录和业务 MCP 连接，最多等待 20 秒；全局预热成功不能替代新工作目录的检查。短暂连接失败允许一次重连，授权缺失、禁用和配置错误直接报告。准备失败返回 `MCP_NOT_READY`，不让模型在缺少必要工具时进入调查，也不将此故障伪装成缺少调查报告。
+
+已授权的纯只读 MCP 查询遇到网络错误、429、502、503、504 或明确的暂时不可用结果时，最多尝试三次（首次加两次重试），间隔 100/300 毫秒；共享一次请求截止时间，取消会终止等待。每次沿用原调用编号并重新绑定查询上下文。计算提交和写操作不自动重放；后台计算状态列表继续使用已有轮询重试，避免叠加。401 仅允许一次凭据更新，403、参数错误及不兼容的身份或配置不靠重试绕过。
+
+OAuth 发现会主动向 MCP 发送不带凭据的请求来取得认证挑战，该步骤的 401 本身不代表业务查询失败。排查时应对齐具体任务、Agent 会话、工具调用和最终错误，区分工具目录未就绪、查询认证失败和结果读取失败。
+
 要保留已有服务进行隔离联调，可以使用仓库启动器：

 ```bash
@@ -528,7 +534,7 @@ TJWATER_ANSWER_UI_EVAL=1 bun run tests/integration/answer-ui-selection.ts

 ## 第一方产品 MCP 查询

-新增10项受控分析：标准水力模拟、爆管侦测、爆管定位、阀门隔离、DMA漏损识别、污染扩散、关阀影响、冲洗分析、调泵影响和压力监测点选址。普通项目会话与调查主Agent可按权限调用，reader保持只读。计算不保存正式方案或下发设备指令；调查结果和输入假设沿用证据链保存。长计算采用提交作业、查询状态、读取结果的队列流程。HTTP 返回预算由目录元数据和宿主管理，模型不再填写 `timeout_seconds`。Server 默认120秒、Agent默认180秒；Server上限240秒，Agent加60秒余量并封顶270秒，外层原生MCP总时限300秒。后台执行时限由服务端独立配置（默认3600秒），爆管定位没有单独的长超时。修改Server请求预算后需重启Agent以重新发现目录。状态查询遇到临时网络/服务错误最多退避重试3次，新完成作业会先返回模型处理；计算不会自动重试。每项目最多100个未结束作业，排队期限1小时，结果保留7天；结果过期保留任务记录与已归档证据。部署前追加Server的027队列生命周期迁移。能力、单位、模板隔离和发布边界见[分析工具说明](../next-tjwater-server/docs/mcp-analysis-tools.md)。
+新增10项受控分析：标准水力模拟、爆管侦测、爆管定位、阀门隔离、DMA漏损识别、污染扩散、关阀影响、冲洗分析、调泵影响和压力监测点选址。普通项目会话与调查主Agent可按权限调用，reader保持只读。计算不保存正式方案或下发设备指令；调查结果和输入假设沿用证据链保存。长计算采用提交作业、查询状态、读取结果的队列流程。HTTP 返回预算由目录元数据和宿主管理，模型不再填写 `timeout_seconds`。Server 默认120秒、Agent默认180秒；Server上限240秒，Agent加60秒余量并封顶270秒，外层原生MCP总时限300秒。后台执行时限由服务端独立配置（默认3600秒），爆管定位没有单独的长超时。修改Server请求预算后需重启Agent以重新发现目录。状态查询遇到临时网络/服务错误最多退避重试3次，新完成作业会先返回模型处理；计算不会自动重试。每项目最多100个未结束作业，排队任务保留至领取或显式取消，结果保留7天；结果过期保留任务记录与已归档证据。部署前追加Server的027队列生命周期和030移除排队过期列迁移。能力、单位、模板隔离和发布边界见[分析工具说明](../next-tjwater-server/docs/mcp-analysis-tools.md)。

 本地开发手动启动Agent，读取项目 `.local.env`，已有系统环境变量优先。MCP随Server运行。仓库保留 [tjwater-agent.service](infra/systemd/tjwater-agent.service) 作为可选部署模板；用户级Server/Agent服务已移除，不与手动进程同时启用。选择systemd部署时，私有 `~/.config/next-tjwater/agent.env` 会覆盖项目同名配置，必须与Server及前端的认证环境一致，并复用已有原生会话数据库。