jiang
b853b61a0b
Accumulate investigation paths and preserve failed attempts across rounds. Keep graph annotations separate from execution state, synchronize the API contract, and consolidate documentation.
56 lines
5.6 KiB
Markdown
56 lines
5.6 KiB
Markdown
# 旧动态调查计划兼容契约
|
||
|
||
> 历史兼容文档：字段和示例用于读取已有 `execution-plan@1/@2` 快照，不要求当前调查生成或执行这些计划。当前进展与累计图见 [调查进展](investigation-progress-and-presentation.md)，Agent 生命周期见 [任务执行](../../next-tjwater-agent/docs/execution-plan.md)。
|
||
|
||
早期设计由 Agent 生成 `execution-plan@2` 并按证据追加修订；数据库保存不可变计划快照的 JSONB 文档，不保存固定流程模板。任务、Run、证据、访问申请、审核动作和报告各有独立生命周期。计划中的 `gate_ref` 只引用已经持久化的访问申请或动作，不能把审批结果写成模型自行判断的文本。
|
||
|
||
## `execution-plan@2`
|
||
|
||
| 字段 | 含义 |
|
||
| --- | --- |
|
||
| `schema` | 固定为 `execution-plan@2`；旧快照继续按 `execution-plan@1` 读取 |
|
||
| `title`、`reason` | 本次计划名称和制定或修订原因 |
|
||
| `nodes[]` | 具有稳定 `id`、`title`、`owner`、`status`、`detail`、`kind`、`evidence_refs[]`、`action_refs[]` 的步骤 |
|
||
| `nodes[].kind` | `activity` 单项执行；`decision` 条件判断；`parallel_split` 并行分叉；`parallel_join` 并行汇合；`gate` 人工审核或授权等待点 |
|
||
| `nodes[].selected_edge_id` | 仅判断节点使用。判断完成时指向实际选择的出边；未选择时为 `null` |
|
||
| `nodes[].gate_ref` | 仅审核节点使用。UUID 指向任务内已有的访问申请或待确认动作 |
|
||
| `nodes[].revisits_node_id` | 再次核验时，新节点引用先前节点 ID；不创建回环连线 |
|
||
| `edges[]` | 每条有稳定 `id`、`from`、`to` 和可空 `condition`；判断路线必须有条件文字 |
|
||
|
||
图必须无环且只有一个起点。只有 `decision` 和 `parallel_split` 可以有多条出边；`parallel_join` 至少有两条入边。选中路线的直接目标不能标为跳过；未选路线的直接目标不能标为执行中、待人工或已完成。执行中和已完成的步骤，前置步骤必须完成或跳过。已完成的业务判断与活动必须引用真实证据或动作；纯分叉、汇合和审核节点不要求伪造证据。服务端在发布时再次核验引用、当前 Run 和会话租约。
|
||
|
||
下面是最小示例；`gate_ref` 所指申请先通过独立接口创建，再发布包含审核节点的计划。审批后，Agent 从当前任务上下文读取结果并发布下一版计划。
|
||
|
||
```json
|
||
{
|
||
"schema": "execution-plan@2",
|
||
"title": "水质投诉调查",
|
||
"reason": "核对工单位置和当前风险",
|
||
"nodes": [
|
||
{"id": "risk", "title": "判断紧急风险", "owner": "agent", "status": "completed", "detail": "根据投诉记录判断", "kind": "decision", "selected_edge_id": "urgent", "evidence_refs": ["complaint-1"], "action_refs": []},
|
||
{"id": "field", "title": "安排现场采样", "owner": "human", "status": "pending", "detail": "待安排现场人员", "kind": "activity", "evidence_refs": [], "action_refs": []},
|
||
{"id": "routine", "title": "常规核查", "owner": "human", "status": "skipped", "detail": "本次选择紧急路线", "kind": "activity", "evidence_refs": [], "action_refs": []},
|
||
{"id": "split", "title": "并行核对", "owner": "agent", "status": "pending", "detail": "授权后同时核对现场和数据", "kind": "parallel_split", "evidence_refs": [], "action_refs": []},
|
||
{"id": "upstream", "title": "上游监测", "owner": "agent", "status": "pending", "detail": "待批准读取", "kind": "activity", "evidence_refs": [], "action_refs": []},
|
||
{"id": "network", "title": "管网运行", "owner": "agent", "status": "pending", "detail": "待核对运行事件", "kind": "activity", "evidence_refs": [], "action_refs": []},
|
||
{"id": "join", "title": "汇总调查证据", "owner": "agent", "status": "waiting", "detail": "等待现场与数据结果", "kind": "parallel_join", "evidence_refs": [], "action_refs": []},
|
||
{"id": "access", "title": "审核数据范围", "owner": "human", "status": "waiting", "detail": "等待项目成员审核", "kind": "gate", "gate_ref": "84000000-0000-4000-8000-000000000001", "evidence_refs": [], "action_refs": []}
|
||
],
|
||
"edges": [
|
||
{"id": "urgent", "from": "risk", "to": "access", "condition": "有紧急风险"},
|
||
{"id": "normal", "from": "risk", "to": "routine", "condition": "无紧急风险"},
|
||
{"id": "access-split", "from": "access", "to": "split", "condition": null},
|
||
{"id": "field-route", "from": "split", "to": "field", "condition": "现场"},
|
||
{"id": "upstream-route", "from": "split", "to": "upstream", "condition": "上游"},
|
||
{"id": "network-route", "from": "split", "to": "network", "condition": "管网"},
|
||
{"id": "field-join", "from": "field", "to": "join", "condition": null},
|
||
{"id": "upstream-join", "from": "upstream", "to": "join", "condition": null},
|
||
{"id": "network-join", "from": "network", "to": "join", "condition": null}
|
||
]
|
||
}
|
||
```
|
||
|
||
实际调查可以把现场路径与 Agent 路径放在同一个并行分叉下，并在下一次修订中补充更多判断或并行组。已发布计划保留原样；拒绝授权、人工补充、复测或回访触发新 Run 时，Agent 读取当前任务事实后继续规划。旧 `execution-plan@1` 只有依赖关系，前端按原始前置条件展示，不推断它代表条件选择还是并行执行。
|
||
|
||
访问申请独立存于 `workbench.operational_task_access_requests`，包括请求范围、理由、申请节点、审核人、批准范围和版本；工单草稿及其审批、回执仍存于动作表。前端默认呈现选中路线，并在明确的分叉与汇合处组成并行组；未选路线折叠保留供核对。
|