feat: upgrade investigation and presentation runtime

2026-10-30 17:30:19 +08:00
parent 3b52a0ddab
commit 6336157ff4
104 changed files with 6541 additions and 961 deletions
@@ -10,7 +10,7 @@
 | --- | --- | --- |
 | [agents/instruction.md](agents/instruction.md) | 公共数据规则及普通聊天、协作指令 | 配置生成器去除 frontmatter 后，设为 `instruction` Agent 的 system 指令 |
 | [agents/investigation.md](agents/investigation.md) | 后台调查协调规则 | 叠加公共业务指令，仅可信任务执行会话选择 |
-| [agents/investigation-reader.md](agents/investigation-reader.md) | 只读核查子代理的独立指令 | 单独加载，不继承普通聊天和调查主代理指令 |
+| `investigation-reader` | 无独立提示词文件的运行时只读子代理 | 主代理在每次 `subagent` 调用中提供 prompt；配置生成器只设置权限和工具白名单 |
 | [tjwater-plugin/package.json](tjwater-plugin/package.json) | 插件包名称、版本、描述和导出入口 | OpenCode 显式加载该目录包 |
 | [tjwater-plugin/index.ts](tjwater-plugin/index.ts) | 插件包入口 | 导出 `plugins/tjwater-tools.ts` 的默认插件 |
 | [plugins/tjwater-tools.ts](plugins/tjwater-tools.ts) | `tjwater.tools` 插件实现 | 注册业务与待办工具、沙箱、MCP 策略和内部 RPC |
@@ -26,9 +26,9 @@

 ## Prompt 组织与角色权限

-加载方式由 [opencode2-config.ts](../src/runtime/opencode2-config.ts) 决定，本次整理不改变加载机制：普通聊天使用 `instruction.md`，后台调查使用 `instruction.md` 加 `investigation.md`，只读子代理只使用 `investigation-reader.md`。
+加载方式由 [opencode2-config.ts](../src/runtime/opencode2-config.ts) 决定：普通聊天使用 `instruction.md`，后台调查使用 `instruction.md` 加 `investigation.md`。只读子代理不加载仓库提示词文件，具体 prompt 由主调查 Agent 在每次调用中编写。

-`instruction.md` 集中维护数据来源、限定查询、分析适用范围和消息语义，回答展示与人工补充事实标明仅适用于普通聊天、任务协作。`investigation.md` 只补充后台调查的委派、进度、Mermaid、展示、报告和收尾规则，不重复整套查询说明。reader 不继承公共文件，因此保留独立的查询与证据约束，不加载聊天展示或正式报告流程。
+`instruction.md` 集中维护数据来源、限定查询、分析适用范围和消息语义，回答展示与人工补充事实标明仅适用于普通聊天、任务协作。`investigation.md` 补充后台调查的委派、进度、Mermaid、展示、报告和收尾规则，并要求主代理为子任务写明问题、范围、时间窗、预期证据和返回格式。子代理的只读范围由运行时强制，不依赖独立 system prompt。

 | 角色 | 产品 MCP | 子代理 | 发布与通信 |
 | --- | --- | --- | --- |
@@ -40,21 +40,46 @@

 Prompt 负责引导行为，不替代权限检查。维护角色规则时同步核对 [task-agent-policy.ts](task-agent-policy.ts)、[项目 MCP 白名单](../src/runtime/product-mcp-tools.ts) 和服务端工具契约，不通过修改文字扩大权限。更新后需重新加载 Agent/OpenCode 运行时资产；client 模式需同步外部 OpenCode 配置，本次文档修改不代表运行中会话已加载新指令。

+### 提示词职责与收尾规则
+
+| 来源 | 负责的规则 |
+| --- | --- |
+| 公共 `instruction.md` | 数据来源、事实与假设、授权工具、查询范围，以及明确限定为普通聊天的展示和等待规则 |
+| 后台 `investigation.md` | 必要核查如何推进、计算等待、阶段报告、动作提议和唯一的调查停止条件 |
+| Server 的 `resources/work-order-skills/*/SKILL.md` | 各类事件的判断目标、参数来源、分析适用性与现场闭环要求，按任务上下文读取版本 |
+| MCP schema 与工具说明 | 合法参数、结果语义及真实能力，不把现场执行前置条件写成候选计算门槛 |
+| 任务入口消息 | 当前目标和上下文，引用上述规则，不重复编写缺数退出或提案后立即收尾的规则 |
+
+`concluded` 表示有依据的有限结论；`final` 表示本轮必要分析已完成或有依据地确认无法继续，两者分别判断。紧急核验建议可先通过 interim 报告和动作草稿提出，之后继续可执行的必要分析。现场确认约束实际处置及闭环，不阻止有明确假设的候选分析。
+
+维护时用下列情形核对各层表述是否一致；这是一组行为验收情形，静态检查通过不等于模型运行已通过验收。
+
+| 情形 | 预期行为 |
+| --- | --- |
+| 压力异常，目录首屏未见流量计 | 补齐相关目录覆盖及参数来源核查；无依据不硬填漏量，继续独立隔离及影响分析 |
+| 已有合理候选，现场尚未确诊 | 可计算候选隔离方案，现场阀门状态列为执行前核验条件 |
+| 已有现场核验草稿，必要分析仍可执行 | 保存 interim、提议动作后继续分析，不立即发布 final |
+| 必要计算 queued/running | 发布等待进度，交宿主等待并续跑，读取结果后再判断，不按缺数结束 |
+| 必要数据经查询无法补齐，或查询接口失败 | 前者若能由用户补齐则提问，回答仍无法补齐时按实际结论选择 outcome；后者按执行异常处理 |
+
 ## 当前工具目录

-`tjwater.tools` 显式注册 20 个工具；描述清单中的 `plugins[].tool_groups` 按下表列出准确 ID。插件内部 RPC `list`、`mcp`、`check_models` 和 `read_todos` 供宿主使用，不是模型工具。
+`tjwater.tools` 显式注册 22 个工具；描述清单中的 `plugins[].tool_groups` 按下表列出准确 ID。插件内部 RPC `list`、`mcp`、`check_models` 和 `read_todos` 供宿主使用，不是模型工具。

 | 用途 | 插件工具 |
 | --- | --- |
 | 回答组织与收尾 | `present_answer`、`final_answer` |
-| 地图、图表与监测展示 | `locate_features`、`zoom_to_map`、`show_chart`、`view_history`、`render_scada_analysis`、`clear_scada_analysis` |
+| 宿主持久化提问 | 聊天 `ask_user`；后台调查 `ask_task_user` |
+| 地图、图表与监测展示 | `present_view`（十种受控 command） |
 | 调查进度、展示与报告 | `publish_task_progress`、`publish_task_presentation`、`publish_task_report`、`publish_execution_plan` |
 | 人工证据、动作提议与授权申请 | `add_task_human_evidence`、`propose_task_action`、`request_task_data_access` |
 | 调查讨论写入 | `send_task_message`、`reply_agent_message` |
 | 完整读写管理接口 | `memory_manager`、`skill_manager` |
 | 当前会话待办写入 | `todowrite` |

-`view_history` 是带数据读取的历史曲线展示动作，保留插件形式；纯数据查询使用 `mcp_tjwater_query_element_history`。`present_answer` 发布本地界面，不等待浏览器回执；地图/图表动作遵循各自的回执契约。后台 `publish_task_presentation` 记录展示请求，不能把记录成功解释为浏览器已显示。
+历史曲线先通过 `mcp_tjwater_query_element_history` 查询，再通过 `present_view` 的 open_chart 命令展示。`present_answer` 发布本地界面，不等待浏览器回执；地图/图表动作遵循各自的回执契约。后台 `publish_task_presentation` 记录展示请求，不能把记录成功解释为浏览器已显示。
+
+普通聊天和任务协作声明 `host-question@1` 后，目录提供 `ask_user` 并隐藏原生 question。可信工具桥持久保存问题，工具执行门禁拒绝与提问并行的调用及等待期间的新调用；宿主在工具完成后确认原生轮次 idle。答案通过原会话 Responses 通道继续，不冒充原生工具返回值。后台任务、学习上下文和旧客户端不启用聊天提问工具；业务审批不受此工具替代。后台调查使用 `ask_task_user`，通过 Server 保存问题并产生 human_input_required 通知。固定问答放在右侧调查报告的“补充回答”中，通知打开该报告，提交直接调用任务回答接口；左侧 Agent 保留自由讨论与追问。当前 run 正常结束，任务进入 waiting_human，回答后原任务排队新 generation，答案从任务上下文 questions 分节读取。用户回答不自动写成现场证据。部署前须在项目业务库执行 Server 的 `resources/sql/028_task_questions.sql`。

 OpenCode 原生工具包括文件工具 `read`、`glob`、`grep`、`edit`、`write`、`patch`，会话沙箱 `shell`，网页工具 `websearch`、`webfetch`，以及 `skill`、`question` 和受限 `subagent`。保留 `opencode_models`、`opencode_session_move`、`opencode_session_rename`、三个 `opencode_worktree_*` 管理工具及两个 MCP 资源工具；完整 ID 见描述清单的 `native_tools`。这些目录项不代表每种会话都能执行，最终由权限、审批、会话归属及沙箱决定。原生浏览器自动化工具已禁用。

@@ -188,6 +213,16 @@ MCP 策略变更使用 MCP 相关测试，实际连接联调可选择根目录 R
 `plugins/tjwater-tools.ts`。更新后需要重新加载 Agent/OpenCode 的可信插件资产。
 发现验证使用 `bun run tests/integration/answer-ui-smoke.ts`，从 Agent 仓库根目录运行。

+聊天 UI 的选择规则常驻于 `agents/instruction.md`：对象比较与数值趋势优先使用
+`present_answer` 的 Table、Chart，简单问答保留文字。工作台地图操作与用户要求打开的
+独立图表使用 `present_view`。工具描述包含可执行校验的最小发布示例；最终组件直接
+显式指定 `phase=final`，并由 `final_answer` 的正文锚点及引用列表保留。
+本规则不依赖动态 Skill 的读取，也不改变后台调查的发布渠道。
+
+`bun test tests/chat/answer-ui-examples.test.ts` 校验示例是否能通过真实发布契约。
+自然问题选择验收使用 `TJWATER_ANSWER_UI_EVAL=1 bun run tests/integration/answer-ui-selection.ts`，
+会调用真实模型；隔离环境、范围和可选模型参数见 [根目录 README](../README.md)。
+
 ## 第一方查询与分析 MCP

 配置构建器在插件列表末尾添加 `-opencode.browser` 和 `-opencode.browser.*`，禁用原生浏览器插件及其子插件，并拒绝 `browser` / `browser_*` 权限。`present_answer`、地图/图表/SCADA 前端动作、任务展示发布和记忆/技能管理插件继续保留；它们使用各自的业务协议，不依赖原生浏览器自动化工具。