next-tjwater-agent/docs/execution-plan.md

# 调查报告与可选流程说明

水质投诉事件以证据和调查报告为成果，使用 `publish_task_report` 发布明确的 stage、outcome 与数据缺口。
报告可附 Mermaid 调查脉络，由前端以统一主题渲染 SVG；节点引用连接证据和业务动作。
Mermaid、todo 和可选的旧执行计划供人理解，不约束 Agent 调度，不决定调查结束。
事件调查不要求先发布计划。正文及图示中不接受 HTML、SVG 或脚本。

## 旧计划的兼容数据与状态

输入包含幂等 `request_id`、`title`、`reason`、`nodes` 和 `edges`。节点包含稳定 `id`、标题、执行主体
`agent | human`、说明、证据和状态：`pending | running | waiting | completed | failed | skipped | cancelled`。
边包含 `from`、`to`、条件标签 `label`。允许并行和条件分支；重试使用新节点，不形成循环依赖。
最多 40 个节点、80 条边；拒绝重复 ID、悬空依赖和环。完成状态必须提供证据；失败和等待必须说明原因。

工具先通过受信内部桥把计划写入 TJWater Server；后端拒绝会直接成为工具错误，模型必须修正后重试。
仅在后端写入成功且输入校验通过后发送 `execution_plan` 事件，且不会再异步重复写入。服务端分配
`schema_version: execution-plan@1`、`session_id`、递增 `revision` 和 `updated_at`。
更新必须保留原节点；不适用或取消的节点显式标记，已完成节点的标题及证据不能被改写。
更正完成结论时添加复核节点，并在 `reason` 中说明。

节点状态来自 Agent 显式上报，工具成功发布不等于业务动作完成。合成输入必须标识来源，
人工采样、复测、回访不得因 Agent 回复结束而自动完成。前端展示状态计数，不按时间计算百分比。

## 任务、协作与恢复

后台调查通过 `publish_task_progress` 按需整理 summary 与可选 graph_update，复用 Server `agent-artifacts` 写入。路线实质调整、重要结果或失败尝试需要留痕、归纳报告时更新即可，不要求逐步发布或实时同步。graph_update 只提交变化的 nodes 和显式 edges（source/target/label）；Server 累计保留路径并生成 Mermaid。node_id 稳定，可用 detail、证据及动作引用解释依据。可选 status 只接受 reference（参考步骤）、recorded（已有结果）、needs_input（待补充条件）、failed（尝试失败）、not_taken（未采用路线）；无标记时保持中性。recorded 不证明实际任务或现场动作完成，needs_input 不控制任务等待。失败路径保留，重试另建节点。需要接续旧图时读取 get_task_context(section="progress")；旧 pending/running 仅作参考，completed 表示已有结果，waiting/waiting_human 表示待补充条件，skipped/cancelled 表示未采用。summary 更新不清图，报告归档已有累计图；旧图原源码保留，未保存的旧进度无法补回。图示与实际任务、计算和工具执行状态独立，不调度 Agent。上面的旧执行计划字段只用于历史兼容，也不驱动 Mermaid 标记。

`publish_task_presentation` 仅允许 task_execution，通过 Server `presentation-events` 记录有限地图、图表及证据图层命令。run_id、任务和会话身份来自可信运行上下文；request_id 为模型提供的 UUID，相同操作重试复用。命令无需浏览器 capability 或实际显示回执，recorded 不代表已显示。图表引用真实证据，overlay 仅提供 evidence_id，由 Server 提取数据。前端 Dev 选择当前任务后实时跟随未来展示事件，关闭、切换或重连不回放旧展示，不启动新调查。

计划独立保存在现有 Session UI State 的 `executionPlans` 中，并随消息流发送。
`GET /api/v1/session/:session_id/stream` 的首个 `state` 事件返回运行中快照，
或已保存的 `execution_plans`。主对话断线不影响计划快照保存。前端支持历史版本查看及断线重连。
会话元数据以 `purpose` 区分普通聊天、后台任务执行和任务协作。普通历史列表默认仅返回
`ordinary_chat`；任务执行和协作会话只能用显式 purpose/task 过滤或从对应工况任务进入。
协作会话独立持久化用户与 Agent 的问答文本，由 TJWater Server 授权返回的计划、报告和证据快照解释判断，
不复制后台执行消息、工具调用轨迹或内部推理。

工况任务执行先读取后端 task context，再通过有限、可审计的数据源查询 SCADA、工作台或外围样板数据。
查询结果携带来源、时间、内容引用和 `origin`，合成数据必须明确标识；截断结果不能用来断言完整范围无异常。
报告和关键证据写回任务记录，计划可选。提议动作前先保存本轮 interim/concluded 报告；
提议成功后可在报告图示中关联返回的动作编号，再保存本轮 final 报告。
Server 根据当前轮次、当前会话的最终报告与真实动作决定运行收尾及是否待人工审核；
旧计划中的未完成节点不阻止事件调查结束。创建工单和下发命令只能生成待人工审批动作，Agent 无执行接口。

协作入口可传所选 report_revision。Server 返回 selected_report 与当前 task，两者分别表示
正在讨论的历史成果和当前实际状态。Agent 回答的 data-task_context 记录核验后的轮次与报告修订，
保留在流和消息历史中。工具重新读取上下文默认使用本次对话已选修订。
普通问题不改任务。仅用户明确提供的现场事实通过 add_task_human_evidence 保存；
假设、查询请求和补充事实的入口提示不能当作事实。重新排队成功只表示 queued，不表示 Agent 已开始调查。

执行会话使用两分钟任务租约并定期续租；计划或报告写回也会续租。执行进程中断后由后端租约恢复重新排队。
旧水质样板触发仍可使用事件随附的固定合成输入，但必须表述为外围样板输入，不能冒充实时查询结果。

## 验证与运行

Agent：`bun run check`，`bun test tests/routes/executionPlan.test.ts tests/routes/chatStream.test.ts tests/sessions`。
前端：`pnpm lint`、`pnpm typecheck`、`pnpm test`、`pnpm build`，以及
`pnpm test:browser tests/browser/peripheral-sample-panel.e2e.ts`。
浏览器覆盖嵌入 SVG、引用详情、报告更新与历史选择、键盘详情、320/375px 和实际动作审核。

运行实例需加载更新后的 Agent 代码和 OpenCode 工具配置。`embedded` 模式自动把内部工具桥密钥传给子进程；
`client` 模式要求 Agent 与外部 OpenCode 显式配置相同的 `AGENT_INTERNAL_TOKEN` 并重启两侧。
回退前端不会改变已保存工单；回退 Agent 前先保留 Session UI State 数据，新字段可被旧代码忽略。

## 调查报告契约

报告采用固定字段、增量扩展，不增加格式版本标签。完整规则见
[Server 调查报告契约](../../next-tjwater-server/docs/investigation-report-contract.md)。
事件调查中可由用户补齐的关键输入通过 `ask_task_user` 保存问题，右侧调查报告直接展示固定问答，无需预先发布报告或生成表单。问题为 pending 时当前 run 正常结束、任务进入 waiting_human；用户在报告内提交后原任务排队新 generation，继续读取 questions 中的回答。
只有查询与适用的人工补充均无法解决关键缺口、且无法形成必要判断或具体建议时，才以 final/insufficient_data 正常退出。计算等待、人工等待与执行故障按调查指令分别处理。
动作提议前先保存本轮 interim/concluded 报告，动作提议后继续必要分析，满足停止条件再保存 final 报告。
数据授权由系统配置，本场景不请求人工数据授权。