5.4 KiB
调查报告与可选流程说明
水质投诉事件以证据和调查报告为成果，使用 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 回复结束而自动完成。前端展示状态计数，不按时间计算百分比。
任务、协作与恢复
计划独立保存在现有 Session UI State 的 executionPlans 中，并随消息流发送。
GET /api/v1/agent/chat/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 调查报告契约。 数据缺失不再保持 waiting：关键缺口导致 final/insufficient_data 正常退出； 动作提议前先保存本轮 interim/concluded 报告，动作提议后再保存 final 报告。 数据授权由系统配置，本场景不请求人工数据授权。