68 lines
5.4 KiB
Markdown
68 lines
5.4 KiB
Markdown
# 调查报告与可选流程说明
|
||
|
||
水质投诉事件以证据和调查报告为成果，使用 `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 调查报告契约](../../next-tjwater-server/docs/investigation-report-contract.md)。
|
||
数据缺失不再保持 waiting：关键缺口导致 final/insufficient_data 正常退出；
|
||
动作提议前先保存本轮 interim/concluded 报告，动作提议后再保存 final 报告。
|
||
数据授权由系统配置，本场景不请求人工数据授权。
|