# 多意图多任务识别、持久计划与 HITL 统一确认方案

> 状态: **partially implemented**（U1–U8 代码与默认 `legacy` 已合入；U8 真实 PI generate 仍为证据缺口；U9–U12 deferred）
> 日期: 2026-09-15
> **SSOT 状态**：能力行见 [FEATURE-MATRIX](../status/FEATURE-MATRIX.md)（Wave 0 校准）；发布门禁见 [gap-matrix](../remediation/gap-matrix.md)。本文保留为设计权威，头部「planned/未实施」已过时。
> 作者: Cline（初稿）/ Codex（架构、安全与实施计划复核）
> 关联: [方案审计](../audit/2026-09-15-multi-intent-hitl-plan-review.md)；[意图识别深读](./intent-recognition/01-意图识别框架-设计-架构-实现-难点-解决方案-亮点与优势.md)；[模块化单体架构](./2026-09-14-module-decoupling-architecture.md)；[任务总览](../ops/short-term/2026-09-15-multi-intent-hitl.md)；[连续性计划](../remediation/2026-09-16-feature-matrix-production-readiness-plan.md)

---

## 一、结论与目标

方向可行，但原稿不能直接实施。需要先闭合计划生命周期、确认回路、授权、并发和模块归属。修订目标是：

1. 一次输入可安全识别 2–4 个候选子任务，并让用户核对系统理解；
2. 只有确定的低风险只读组合可自动执行；批量生成、写入、控制、缺槽、冲突或不确定组合必须进入服务端持久化 HITL；
3. 刷新、双标签页、服务/worker 重启和 SSE 晚到时，计划与卡片从 PostgreSQL 权威状态恢复；
4. 确认只表达用户意愿，不授予权限。每一步执行前按当前主体、成员关系、资源状态和版本重新授权；
5. 不回退已完成的解耦：`internal/intent` 保持纯规则领域模块；跨属主写入继续使用端口、单一写者、`app/uow` 和静态事件契约。

第一版按显式依赖顺序执行，每步独立提交，不承诺跨步骤原子回滚或并行 DAG 调度。

这项能力的直接价值不是替代逐条对话，而是消除当前“用户已经明确给出多个任务，系统却只执行 TopIntent 且不告知”的不可信行为，并让有依赖的“先查再生成”在一次可审计确认中完成。逐条提交仍是低复杂度场景的有效入口；如果 shadow 期显示多意图采用率低、确认放弃率高或用户普遍主动拆单，U7 之后的写动作扩面应停止，而不是为了完成路线图继续建设。

---

## 二、当前事实与缺口

| 能力 | 当前事实 | 证据 |
|------|----------|------|
| 单意图识别 | 18+ Intent、四级漏斗、三分支已实现；FEATURE-MATRIX L1 行 Wave 0 已收口为 `done`（U9–U12 拆出） | `internal/intent/recognizer.go`、`.doc/status/FEATURE-MATRIX.md` |
| V2 帧/动作表 | `IntentFrameV2`、ActionRegistry、风险、必填槽位、灰度开关已存在 | `internal/intent/types_v2.go`、`registry.go`、`flags.go` |
| 有限多意图 | 默认开启；只按首个连接词拆两段；写意图返回 `nil` | `internal/intent/plan_builder.go` |
| 有限执行 | 只读步骤顺序执行；需确认步骤只有文字提示 | `internal/coordinator/action_planner.go` |
| HITL 基础 | PendingExpectation、四类卡片和 ExpiresAt 已存在；前端仍有本地业务状态修改路径 | `internal/intent/types.go`、`web/src/App.tsx` |
| 可靠事件 | PG dispatcher、delivery、静态契约已 live；FAV 关闭 | `internal/events`、`.doc/ops/CURRENT.md` |
| 模块边界 | `intent` 只允许依赖 `maturity`；chatflow/stageflow/doccontent 等解耦已完成 | `.doc/system-design/module-boundaries.yaml` |

关键缺口：分段不确定时可能退回 TopIntent 并静默丢任务；计划没有 revision、决策凭据、执行账本或可恢复状态机；确认没有统一服务端命令；ActionRegistry 风险容易被误当授权；未处理重复提交、双标签决策、过期竞态和 worker 抢占；卡片/SSE 不是权威状态；原稿把 agent backend 引入 L1 会破坏 intent 边界；T1–T5 全用 `intent` mutex 与实际跨模块范围不符；自由文本结果传递存在提示注入和数据泄露风险；固定样例数不能代替质量门槛。

---

## 三、硬约束与非目标

### 3.1 不可回退的解耦约束

| 约束 | 强制规则 | 验证 |
|------|----------|------|
| L1 纯度 | `internal/intent` 只做确定性分段、识别、帧和计划提案；不得访问网络、PG、文件或 agent backend | arch-check 保持 `intent -> maturity` |
| 应用编排 | 新增 `internal/app/intentflow` 作为计划生命周期唯一编排入口 | chat/server 只依赖深接口，不获得 store/engine |
| 单一写者 | `intent_plans*` 仅由 intentflow repository owner 写；业务动作仍写自己的表 | table owner + SQL write archtest |
| 跨属主一致性 | 计划、决策、投影请求和 outbox 需要一致时使用不透明 `app/uow.TxScope` | 不暴露 pool/pgx.Tx |
| 事件契约 | 新事件先登记 YAML 与 `events.StaticContracts`，再接 dispatcher | registry parity + 未注册 fail closed |
| 授权归属 | intentflow 不复制 docgov/taskrun/workflow 权限，调用动作属主用例端口 | 每个 adapter 有即时授权负例 |
| 组合根 | store、adapter、clock、ID generator、event sink 仅在 `internal/app/app.go` 装配 | server 不重新接线 |

### 3.2 非目标

- 不拆微服务或新增 RPC；不支持 >4 步、并行 DAG、多个活动写计划自动合并；
- 不承诺跨步骤 ACID 或自动补偿；
- 当前作用域没有活动写/生成计划时，不改变单意图生成任务行为；已有活动计划时统一进入冲突/替换流程，禁止启动第二个写计划；
- 不让 LLM 决定风险、权限、槽位真值或执行顺序；
- 不启用 FAV，也不把中间结果归档到 FAV；
- 不借机全量重构 coordinator/chat action executor。

---

## 四、总体架构与权威性

```mermaid
flowchart LR
    UI[Web 计划卡] --> API[server HTTP/SSE]
    API --> FLOW[app/intentflow\n计划生命周期]
    CHAT[chat/chatflow] --> FLOW
    FLOW --> L1[intent\n纯规则提案]
    FLOW --> STORE[(plan owner store)]
    FLOW --> UOW[app/uow]
    FLOW --> PORTS[动作属主端口]
    FLOW --> EVENTS[events outbox]
    EVENTS --> PROJ[projection/notify]
    FLOW -.只建议分段.-> SEM[语义 adapter\nagent backend]
```

`app/intentflow` 对外只提供：处理一轮输入、提交计划决策、读取授权后的 PlanView、恢复/推进已有计划。不得向调用者暴露 PlanStore、事务、`docgov.Engine`、`taskrun.Manager` 或 pool。

权威性从高到低：当前认证主体与资源状态 → 动作属主的授权/业务不变量 → PG 计划/步骤/决策 → 消息卡片投影 → SSE/前端内存。下层不得覆盖上层。

### 4.1 端到端流

```mermaid
sequenceDiagram
    participant U as 用户
    participant W as Web/server
    participant F as app/intentflow
    participant I as intent
    participant D as PG plan store
    participant A as 动作属主
    U->>W: input + client_turn_id
    W->>F: HandleTurn(principal, context, input)
    F->>I: 安全扫描、分段、逐段识别
    I-->>F: PlanProposal + evidence + digest
    alt 独立低风险只读
        F->>A: 每步即时授权并执行
        F-->>W: 聚合结果
    else 需澄清/确认
        F->>D: 同事务写 plan/steps/outbox
        F-->>W: 权威卡片
        U->>W: decision + nonce + expected_revision
        W->>F: DecidePlan
        F->>D: CAS 状态
        F->>A: 每步重新授权、执行
        F->>D: CAS step + receipt/ref
        F-->>W: PlanView
    end
```

---

## 五、领域模型与状态机

- `intent.PlanProposal`：L1 值对象，含规范化分段、候选帧、证据、缺槽和依赖建议；不含授权结论或 DB 状态；
- `intentflow.Plan`：应用实体，含主体/会话/项目作用域、请求摘要、revision、过期、决策与执行账本；
- `PlanView`：脱敏 UI 投影，不回传内部 payload、权限快照或完整中间结果；
- UserProjectContext/消息只保留 `plan_id + revision` 引用，不持久化第二份 PendingPlan。

### 5.1 计划状态

```mermaid
stateDiagram-v2
    [*] --> proposed
    proposed --> awaiting_clarification
    proposed --> awaiting_confirmation
    proposed --> executing: 仅低风险只读
    awaiting_clarification --> awaiting_confirmation
    awaiting_clarification --> executing
    awaiting_clarification --> awaiting_clarification: 增量补槽形成新 revision
    awaiting_clarification --> superseded
    awaiting_confirmation --> executing
    awaiting_confirmation --> cancelled
    awaiting_confirmation --> expired
    awaiting_confirmation --> superseded
    executing --> partially_completed
    executing --> completed
    executing --> failed
    executing --> cancelled: 仅未开始步骤
    partially_completed --> completed
    partially_completed --> failed
    partially_completed --> executing: 用户选择重试/继续
    partially_completed --> cancelled: 取消全部未开始步骤
```

编辑产生新 revision/digest，旧卡片 `outdated`；取消不能回滚已完成业务副作用；`skip` 只允许独立低风险只读步骤；依赖失败阻塞所有后代；`confirm_retry` 暂停计划并对指定失败步骤重新确认。

### 5.2 步骤、部分确认与幂等

步骤状态：`pending -> eligible -> running -> succeeded | failed | denied | conflicted | blocked_dependency | skipped | cancelled`。

- `eligible -> running` 用条件更新和 fencing token；
- 动作幂等键：`plan_id:plan_revision:step_id:action_digest`；同键同摘要返回既有 receipt，同键异摘要冲突；
- 动作属主端口必须接收 idempotency key、action digest、expected resource version 和 fencing token，并能按同一身份查询 receipt。只有属主事务能原子提交幂等占位与业务副作用，或已证明原生机制等价时，该 action 才能放量；旧 fence 必须被属主拒绝；
- 部分确认必须是依赖闭包；选中步骤进入 eligible，未选独立步骤继续等待确认。只有用户显式“排除未选项”才写 `cancelled_by_user`，其后代取消或阻塞；
- 高风险步骤逐项可见；确认父步骤不自动确认新出现的高风险后代；
- “确认第 1 项并修改第 2 项”拆成决策和新 revision，不混为一个转移。

---

## 六、分段、识别与组合策略

### 6.1 确定性分段

`internal/intent` 内扩展纯规则分段器，支持连接词、句号、分号、换行、序号和“先/再/最后”，上限 4 段。输出包含规范化文本、原文 span、连接证据、结构置信类别和未解析指代。

1. 整句先做 Stage 0 安全扫描；分段规范化、槽位补丁、LLM 建议后再次逐段扫描；原文命中优先，整体拒绝；
2. “查询并总结”“阅读后概括”等单动作内部链不拆；
3. 只有确定为完整单意图时才合并回单意图；低置信、指代补全失败或无法证明完整时进入澄清，禁止退回 TopIntent 执行；
4. 逐段识别后检查同资源冲突、重复动作和依赖；
5. 超过 4 段不创建残缺计划，明确要求分批。

### 6.2 可选语义分段

LLM adapter 位于 intentflow 外围，不放进 `internal/intent`。它只能提出 `text span + connector + reason`，不能输出权限、风险、ActionKey、执行顺序或权威槽位。

- 只发送当前文本和必要的脱敏实体标签；不发送 secrets、完整历史、文档正文或权限表；
- 严格版本化 schema；超时、格式错、span 重叠、越界或安全冲突均 fail closed；
- 每段重新进入确定性 recognizer、ActionRegistry 和安全扫描；护栏优先，无法裁定就澄清；
- 以 `request_digest + segmenter_version + model_contract_version` 固化已展示分段；重试不得因模型漂移改变计划；
- shadow 日志只保留 digest、类别、差异和计数。

### 6.3 组合风险矩阵

ActionRegistry 提供动作身份、目标类别和静态风险提示，但不是授权或批量编排 SSOT。`app/intentflow` 拥有版本化 `BatchActionPolicy`，只记录 action key 的批量确认要求、可开放 tier、adapter 能力和 execution mode，并在启动时校验 key 存在于 ActionRegistry。它不得复制 Risk、RequiredSlots、CapabilityKey 或 AllowedStates。`task.run`/`task.run.adhoc` 的批量策略要求确认，同时保持其单意图 `RequiresConfirm` 不变。

| 条件 | 模式 | 行为 |
|------|------|------|
| 全部独立 RiskLow 查询、槽位齐、无冲突 | `auto_read` | 即时授权后执行 |
| 任一批量生成、mutate/control、中高风险或 BatchActionPolicy 要求确认 | `awaiting_confirmation` | 先持久化并出卡，确认前零副作用 |
| 缺槽、指代/分段/依赖不明 | `awaiting_clarification` | 聚合澄清；有槽位依赖时分组问 |
| 原文或变换结果命中红线 | `rejected` | 整体拒绝，不执行其他段 |
| >4 段 | `rejected_batch_size` | 要求分批 |

V2 灰度不可绕过：只有 ActionRegistry 映射稳定、V2 shadow 达门槛且当前 multi-intent tier 允许的动作可进入 decision；其余走 legacy 或显式澄清。

---

## 七、HITL、授权与并发协议

### 7.1 服务端权威卡片

`PLAN_CONFIRM` 折叠态也必须显示任务数、受影响目标、生成/写入/控制类型、最高风险、不可撤销副作用和“逐步提交、后续失败不回滚”提示；高风险步骤始终逐项可见。只有 action key、revision、digest 等技术元数据和低风险细节可折叠。支持全部确认、依赖闭包内部分确认、编辑、取消。

`CLARIFY_AGGREGATE` 展示逐步缺槽、约束、已知值和冲突。回复形成 slot patch 后必须重新识别、重新计算 digest、风险和授权预检。

用户只回答部分问题时保存可唯一映射的增量 patch，产生新 revision 并继续停留在 awaiting_clarification；新卡同时显示已解决值和剩余问题，旧卡 stale。不会要求重填已经验证的值，也不会在缺槽未闭合时提前执行。

澄清字段按步骤和依赖分组，标记“已验证/待填写/冲突/无效”，显示剩余数量；提交文案为“保存已填写并继续”，提交后保留合法值并聚焦首个未解决字段。

卡片 metadata 是 PG 状态投影。按钮和自然语言“确认/取消/只做第 1 项”统一进入服务端 `DecidePlan`；前端不得本地修改业务资源或先标成功。

部分确认 UI 使用依赖层级列表：选择子步骤时立即勾选并解释必需前置；存在已选后代时不能取消前置；提交按钮显示本次确认的步骤数和目标。未选项标为“继续等待”，显式排除是独立次级动作，并在提交前列出会被取消或阻塞的后代。

自然语言决策采用确定性语法优先：明确 plan/步骤编号或当前会话只有一个活动可见计划时才可绑定；“确认”在多个活动计划、步骤引用不合法或同时包含新任务时不执行，改为定向澄清。聚合槽位优先使用结构化卡片字段；自由文本只把可唯一映射的 `label:value`/已有 PatchSlots 结果写入 patch，冲突值、依赖值无效或多义值保持未解析并再次提问，绝不猜测。

### 7.2 确认不等于授权

执行每一步前，动作属主重新校验当前认证用户与 plan session/project/user、当前成员/duty/capability、资源归属/lifecycle/stage、expected version/ETag、动作允许状态。计划中的角色/权限快照只用于审计。失败进入 `denied/conflicted`，不得换系统身份代执行。

### 7.3 并发规则

- 创建：`(session_id, client_turn_id, request_digest)` 唯一；同 turn 异 digest 冲突；
- 决策：必须带 `expected_revision`、`decision_nonce`、`decision_digest`；同 nonce 同摘要返回 receipt，异摘要冲突；
- 标识：plan_id、step_id、decision_nonce 使用不可预测的随机标识；安全性不依赖其保密，所有访问仍做四元作用域授权；
- 状态：当前 revision 且未过期的等待态才能 CAS；陈旧卡片返回 409 和当前安全视图；
- 过期：服务端 `expires_at` 权威，TTLTurns 只显示；
- 执行：短 lease + owner + lease_until + 单调 fencing；续租失败不再领步骤；
- 竞态：确认/取消/过期、编辑/确认只允许一个 CAS 胜出；
- SSE：允许重复/乱序/丢失，前端按 revision/step version 去重，发现缺口 GET 对账。

同一 user/session/project 同时只允许一个活动写/生成计划。新的低风险查询可独立处理；新的写计划必须让用户完成、取消或显式替换旧计划，不自动合并。计划锁不替代业务资源自己的 lease/version lock。

因此“单意图生成保持现状”仅适用于没有活动写/生成计划的作用域。有活动计划时，无论新输入是单意图还是多意图，都返回同一服务端冲突视图，禁止创建第二个 task/run；真实页面验收分别覆盖无活动计划兼容和有活动计划冲突。

`partially_completed` 必须提供前向收口卡：重试指定失败步骤、继续仍 eligible 的独立步骤、取消所有未开始步骤并关闭计划。已成功 receipt 永不回滚；running 步骤先由 lease/fencing 收口，卡片列明已发生且不可撤销的副作用。

---

## 八、持久化、事务、事件与数据治理

### 8.1 表与所有权

`intent_plans`：plan_id、environment/project/session/user/client_turn、request_digest、segmenter/policy version、status、revision、expires_at、timestamps、last_fencing_token。原始输入沿用 chat message 保留；计划表保存引用、digest 和脱敏展示快照。

`intent_plan_steps`：plan/step、action_key、规范化 slots、依赖、status、expected_resource_version、action_digest、idempotency_key、attempt、result_ref/digest、safe_summary、timestamps、version。

`intent_plan_decisions`：append-only decision id/nonce、plan revision、actor、kind、step selection、patch/request digest、outcome、created_at。关键 CAS、审计和查询字段必须类型化；JSONB 只用于版本化 slots/display snapshot。三表 owner 登记为 `app/intentflow`，其他包只能走端口。

### 8.2 事务与恢复

- 创建：plan + steps + card projection request + outbox 同一 UoW；
- 决策：decision append + plan CAS + eligible steps 同一 UoW；
- 业务副作用由动作属主事务提交，再以 idempotent receipt 更新步骤，不制造跨模块长事务；
- 业务成功但 receipt 写回失败时，通过动作幂等键查既有结果并对账，不盲跑；
- 消息投影失败不回滚权威计划，dispatcher 重试，刷新 GET 修复。

### 8.3 事件与作用域

只发布事实，不发布执行命令。候选事件 `intent.plan.awaiting_input`、`intent.plan.step_changed`、`intent.plan.completed` 必须同时登记 YAML、StaticContracts、schema/golden 和 parity test。

payload 仅含 plan/revision/step/status、environment/project/user/session scope 和安全摘要引用；不含原 prompt、完整 slots、权限快照或完整结果。消费者和 SSE 投递前按当前主体重新读取授权后的 PlanView；同项目不同用户不能互见。

### 8.4 留存与结果传递

- plan/decision 随会话和项目数据政策清理，不早于关联 chat/taskrun 审计窗口；删除由 owner 执行；
- 中间结果仅保存 `ResultReference`：producer、result/artifact ID、digest、类型、敏感级别、允许用途和长度受限 safe summary；
- 不把前序自由文本直接拼入权威槽位或后续指令区。后续生成只能把带来源的数据放入隔离材料区，不能扩大 action/target/tool/capability；
- 若结果导致动作、目标或范围变化，产生新 revision 并重新确认；
- 最终生成物仍归 taskrun/受控文档/FAV（启用后），计划库不充当成果仓。

---

## 九、API、刷新与前端

资源接口必须包括 `GET /api/v1/intent-plans/active`（按当前 principal/environment/project/session/user 发现活动计划）、`GET /api/v1/intent-plans/{plan_id}` 与 `POST /api/v1/intent-plans/{plan_id}/decisions`。页面 bootstrap、刷新和 SSE 缺口恢复先查询 active，再拉 PlanView；消息投影失败时仍能找回计划。

decision API 继承当前服务端认证方式、Origin/CSRF 策略和统一限流；nonce/幂等键只防重放与并发，不替代 CSRF 或身份认证。若当前认证方式不具备适用的 CSRF 防护，U1 必须把它列为 U5 的前置 blocker，而不是在计划端点单独发明一套弱机制。

统一错误码至少包括：`PLAN_NOT_FOUND_OR_HIDDEN`、`PLAN_STALE_REVISION`、`PLAN_EXPIRED`、`PLAN_DECISION_CONFLICT`、`PLAN_DEPENDENCY_INVALID`、`PLAN_ACTION_FORBIDDEN`、`PLAN_ACTION_VERSION_CONFLICT`。无权主体沿用资源隐藏策略，避免枚举 plan_id。

刷新时由 plan 表生成卡片/进度，不从旧按钮或 SSE 推断。页面刷新、重开、SSE 重连均以 GET 覆盖本地缓存。卡片需支持键盘/读屏、依赖说明、错误焦点、过期/陈旧状态；按钮提交后可显示 submitting，但只有服务端 receipt 能变为 executing/resolved。完整结果从 owning API 读取，SSE 只携安全摘要和版本。

状态恢复矩阵：submitting 锁定重复提交并保留选择；outdated/conflict 自动读取最新 PlanView、聚焦状态通知并提供“查看最新版”；expired 禁用原决策，保留只读摘要并提供“按当前上下文重建计划”；服务端字段错误保留未提交输入并聚焦对应字段。会话顶部提供可关闭但可重新发现的活动计划入口，无活动计划返回明确空态。

可访问性契约：步骤用有序列表和带 legend 的选择组；折叠控件暴露 `aria-expanded/aria-controls`；进度用 polite live region，阻断错误用 alert 并聚焦；状态不只靠颜色；键盘顺序为摘要、步骤、主/次动作；窄屏单列、无横向滚动、触控目标至少 44px，并支持 reduced-motion。

---

## 十、灰度、指标与回滚

保留 `MULTI_INTENT_ENABLED` 作为 legacy 开关；在任何行为变更前新增 `MULTI_INTENT_PLAN_TIER=legacy|shadow|auto_read|confirm|full`，默认 `legacy`。

- legacy：保持现有路径，但一旦可靠检测到未处理写/生成段，不得静默只执行 TopIntent，应澄清；
- shadow：只生成提案/指标，不建计划、不改路由；
- auto_read：先保持现状上限，仅开放 2 个低风险只读步骤；3–4 个只读步骤先进入确认/观察，达到单独门槛后再扩大；
- confirm：开放持久卡片；真实 adapter 未启用时只能产生 `validated_only` 预检。Plan、step、receipt 和 PlanView 显式携带 execution mode；`validated_only` 不能写 `succeeded/completed`，UI 必须显示“仅验证，未执行”；
- full：按 action key 逐项开放已验收 adapter。

LLM 分段独立开关且从 shadow 起步。关闭新计划创建后，已有计划仍能读取、取消和收口；不能回滚到无法处理已持久计划的版本。

| 指标 | 停走条件 |
|------|----------|
| 未确认/越权副作用 | 0 |
| 安全红线绕过 | 0 |
| hard-negative 反事实错误自动执行 | 0；shadow 必须计算“若处于 auto_read/confirm 会如何路由”，不能用实际未执行冒充零错误 |
| 重复确认导致重复动作 | 0 |
| refresh/restart 权威状态差异 | 0 |
| split precision/recall、澄清率、放弃率 | U2 先固定数据集与基线，再预注册阈值；未达不切档 |
| 用户采用与确认负担 | 记录多意图采用率、确认放弃率、拆单回退率；若价值不足，停止 U8/U9 而保留“识别后不静默丢弃”的安全改进 |
| projection backlog/dead letter | 不突破 Track E 既有预算 |

观察窗口由样本量和流量决定，不能用固定“一周”代替证据。

---

## 十一、实施计划（核心 U1–U8、按属主扩面 U10–U12、可选实验 U9）

### U1. 契约冻结与架构门禁

**目标：** 冻结 intentflow 边界、状态机、数据字典、错误码、事件和兼容策略。  
**依赖：** 无。  
**文件：** `.doc/system-design/module-boundaries.yaml`、`internal/events/registry.go`、API/schema 文档、arch/event tests。  
**做法：** 注册 app/intentflow allowlist 与 table owner；保持 intent->maturity；冻结 BatchActionPolicy，但不向 intent 回灌 HITL/tier/adapter 字段；先落默认 legacy tier；禁止 server/chat 直写计划表。  
**测试：** 新 import/SQL/event 违规 block；YAML/registry parity；未知 action/policy key fail closed；ActionRegistry 不出现批量执行策略；单意图生成策略不变。  
**停走门：** 架构测试全绿，授权/状态契约无待实现者猜测。  
**mutex：** 纯契约文档用 `architecture-docs`；事件注册变更串行占 `events`。U1 不修改 intent 业务类型，intent 代码变更从 U2 开始。

### U2. 确定性分段、PlanProposal 与 shadow 基线

**目标：** 不改变生产路由地生成 2–4 步提案和差异指标。  
**依赖：** U1。  
**文件：** `internal/intent/segmenter.go`、`plan_builder.go`、`types_v2.go`、`registry.go`、`internal/intent/testdata/*` 及 tests。  
**做法：** characterization-first；规则分段、span、指代/连动护栏、安全复扫、显式依赖、稳定 digest。  
**测试：** 连接词/句号/序号；查询并总结不拆；指代失败澄清；红线整体拒绝；5 段拒绝；同输入 digest 稳定；写段不静默丢弃。  
**停走门：** shadow 不改响应；对 golden、hard-negative 和真实抽样人工标签做 counterfactual evaluation，报告分母、误拆/漏段/错误自动执行率及置信区间；预注册阈值未达不得切档。  
**mutex：** `intent`。

### U3. intentflow、PG 状态机与 repository

**目标：** 建立持久计划/步骤/决策与并发协议，不接真实写动作。  
**依赖：** U1、U2。  
**文件：** `internal/app/intentflow/*`、`deploy/postgres/goose/*intent_plan*`、`internal/app/app.go`、PG tests。  
**做法：** owner repository、UoW、CAS revision、decision nonce、绝对过期、lease/fencing、创建幂等、retention、组合根装配。  
**测试：** 双创建；nonce 同/异 digest；确认/取消/过期竞态；两 worker 抢占；租约接管；旧 fencing token 在动作属主处被拒绝；重启恢复；业务成功但 receipt 写回失败；环境隔离。  
**停走门：** 无双 owner/双执行，arch-check 无新例外。  
**mutex：** 新增 `intent-plan`，迁移窗口协调 `db/app`。

### U4. 事件、卡片与步骤投影

**目标：** 权威计划可靠投影；消息/SSE 丢失不影响恢复。  
**依赖：** U3。  
**文件：** 新增 intent-plan event registry/schema、intentflow projection subscriber、ctxmgr owner port、对应 parity/dispatcher integration tests。  
**做法：** 同 UoW outbox、事实事件、消费者幂等与最小 payload；复用 Track E 已有重试/dead letter/replay。禁止修改通用 claim、lease、delivery、retry 或 replay 语义；若确需修改，另立缺陷任务。  
**测试：** 重复/乱序；projection 暂停 replay；消息失败后 GET 修复；worker restart；伪造 producer/字段拒绝；同项目跨用户不可见。  
**停走门：** shadow projection 与 DB diff=0，delivery 可查。  
**mutex：** `events`；ctxmgr 写入只走 owner 端口。

### U5. 决策 API 与即时授权端口

**目标：** 按钮/自然语言走同一服务端命令，执行前重新授权。  
**依赖：** U3。  
**文件：** `internal/server/*intent_plan*`、`internal/app/intentflow/*`、授权端口契约、fake/dry-run adapter、auth integration tests。  
**做法：** active discovery/GET/decision、错误信封、四元作用域、expected revision、依赖闭包、资源版本；不在本单元接真实业务属主 adapter。  
**测试：** 投影缺失仍能发现活动计划；非成员/跨项目/跨 session；角色撤销；资源变更；stale revision；重复点击；非法部分确认；edit 使旧卡失效；按钮/自然语言同 receipt。  
**停走门：** 权限负例全绿；确认前零副作用；无系统身份绕过。  
**mutex：** `intent-plan` + `server/authz`；动作接入另占 owner mutex。

### U6. Web 卡片、刷新与可访问性

**目标：** UI 只呈现 PlanView，刷新和多标签一致。  
**依赖：** U4、U5。  
**文件：** `web/src/types/workbench.ts`、`web/src/components/chat/InteractiveCard.tsx`、API client、`web/src/App.tsx`、web/browser tests。  
**做法：** 两卡、步骤进度、依赖选择、submitting/outdated/expired/conflict、GET reconcile；计划动作不进入本地 AST/资源修改路径。  
**测试：** reload/reopen 与无投影 active discovery；双标签确认/取消；409 查看最新版；过期重建；字段输入保留；键盘/读屏/live-region；窄屏 44px/reduced-motion；SSE 重复乱序；慢请求；validated_only 明示未执行。  
**停走门：** 真实浏览器双标签/reload 无本地假成功。  
**mutex：** `web`。

### U7. 低风险只读执行与聚合

**目标：** 独立低风险查询从 proposal 安全推进到完成。  
**依赖：** U4、U5；可与 U6 并行，开放 auto_read tier 前两者都必须通过。  
**文件：** `internal/app/intentflow/*`、query adapters、coordinator/chatflow 兼容入口、integration tests。  
**做法：** 每步即时授权、显式依赖、ResultReference、失败/阻塞汇报；旧 executeIntentPlan 仅兼容，不扩成跨模块 switch。  
**测试：** 2–4 查询；独立失败继续；依赖失败阻塞；敏感字段脱敏；同 turn 重放；重启续跑。  
**停走门：** legacy 单意图无回归，重复执行为 0。  
**mutex：** `intent-plan`；触及入口时协调 `chat`。

### U8. 生成任务 adapter

**目标：** 经确认后只开放 `task.run` 与 `task.run.adhoc`，形成第一版生成闭环。  
**依赖：** U7。  
**文件：** intentflow taskrun adapter、taskrun owner port/tests、real PI/browser tests。  
**做法：** shadow/dry-run 后开启；传稳定幂等键，保存 result reference/receipt；不改变无活动计划时的单意图行为。  
**测试：** 多意图生成需确认；活动计划冲突；权限撤销；重放；部分完成；receipt 丢失恢复；真实 PI 结果引用。  
**停走门：** taskrun owner/PG/auth/browser/real PI 分层证据全绿。  
**mutex：** `taskrun` + `intent-plan`。

### U9. LLM 分段 adapter 与全面灰度

**目标：** 仅为规则无法可靠判断的输入提供受控建议。  
**依赖：** U2、U7。  
**文件：** intentflow segment proposal port/adapter、版本化 schema、eval/real PI tests。  
**做法：** 最小输入、严格 schema、固定版本/digest、护栏优先、shadow、超时 fail closed。  
**测试：** malformed/timeout；重试稳定；模型改风险/权限无效；红线拆分逃逸失败；敏感内容不出站；冲突澄清。  
**停走门：** real PI eval 达预注册阈值且安全错误为 0。  
**mutex：** `intent-plan` + `pi-agent`，不得改变 intent imports。

U9 是核心首版之外的独立实验，不参与 U1–U8 的完成判定。未实施或未达阈值时，规则无法裁定的输入继续进入澄清。

### U10. 低风险 mutate adapters

**目标：** 只接入经专项批准的 medium/low mutate action。  
**依赖：** U8。  
**文件：** 每个动作的 intentflow adapter 与 owner tests。  
**做法：** 每个 action 独立 short-term、flag、dry-run、权限负例和回滚；不打包发布。  
**停走门：** 单 action 证据齐全后才加入 full tier。  
**mutex：** 对应动作 owner + `intent-plan`。

### U11. 文档治理 adapters

**目标：** 按 claim/submit/review/final 等 action 分项接入 docgov，不复制其 duty/lifecycle 规则。  
**依赖：** U8。  
**文件：** intentflow docgov adapters、docgov owner ports/tests、browser auth negatives。  
**做法：** 高风险动作逐个任务、逐个 go/no-go；必须带 expected document version。  
**停走门：** 各 action 的跨角色、生命周期和并发负例独立签署。  
**mutex：** `docgov` + `intent-plan`。

### U12. Workflow 与 run-control adapters

**目标：** 分别接入 workflow switch/run 与 task run resume/restart/cancel。  
**依赖：** U8。  
**文件：** intentflow workflow/run adapters、owner ports/tests。  
**做法：** workflow 与 run-control 必须拆成独立 short-term，不共用发布开关或回滚点。  
**停走门：** 当前 stage/state、权限、幂等和冲突负例分别通过。  
**mutex：** `workflow` 或 `taskrun` + `intent-plan`。

---

## 十二、验收矩阵与 DoD

必须覆盖：两个只读查询；查询+生成确认前零副作用；部分确认后未选项仍可稍后确认、显式排除才取消；增量补槽保留已验证值；部分完成可重试/继续/关闭；确认后权限撤销；双标签确认/取消只一方成功；确认/过期竞态；服务/worker 重启不重跑成功步骤；投影停机而 GET 正确；“查法规并总结”不误拆；红线混入整体拒绝；前序结果含提示注入仍只作材料；无活动计划时单意图生成不变、有活动计划时不创建第二任务、批量生成需确认；跨用户/项目/会话隐藏；同 turn/nonce 异摘要冲突；编辑后旧卡 stale。

Definition of Done：

- [ ] 核心首版 U1–U8 按各自停走门独立验收；U9、U10–U12 未实施不阻塞首版，但任何已启用 adapter 必须满足自己的停走门；
- [ ] `intent -> maturity` 保持，intentflow 无 service locator、pool 或跨 owner SQL；
- [ ] 所有写/生成/控制在未确认和越权时副作用为 0；
- [ ] 双标签、刷新、服务/worker 重启、重复/乱序事件下无双执行且可恢复；
- [ ] 按钮与自然语言走同一命令，每步即时授权并校验资源版本；
- [ ] 中间结果不进 FAV，事件不携带敏感正文；
- [ ] arch-check、Go short、PG、web build/test、真实 browser 和适用 real PI 分别有报告；
- [ ] FEATURE-MATRIX、CURRENT、任务与必要时 gap-matrix 一致；
- [ ] 清除废弃实验、旧本地成功路径和临时开关；回滚版本仍能读取/取消已有计划。

---

## 十三、关键决策

1. 采用 `app/intentflow` 深模块，不继续膨胀 coordinator；
2. 单意图生成行为保持；多意图策略由 intentflow 的 BatchActionPolicy 管理并引用 ActionRegistry action key，不把应用编排政策回灌 L1；
3. 同步权威状态 + outbox 投影，不用纯事件驱动 plan state；
4. 服务端绝对过期，不用 TTLTurns 作权威；
5. 逐步骤事务，不制造跨 owner 长事务；
6. LLM 只建议分段且最后实施；
7. 新行为默认 legacy/shadow，现有 `MULTI_INTENT_ENABLED=true` 不是自动放量许可。

不采用：把完整 PendingPlan 塞进 UserProjectContext、扩展前端本地 cardActionEngine 执行业务、用 coordinator switch 持有所有具体 engine、LLM 直接生成可执行计划、跨模块大事务。它们会造成双真相、越权/假成功、service locator 回潮、不可信执行或解耦倒退。

长期维护归属按模块分开：intent owner 维护规则与评测；intentflow owner 维护状态机、schema 和 rollout；web owner 维护卡片交互；events owner 维护投影契约；各 action owner 维护自己的授权 adapter。上线后每次新增 ActionSpec 必须同时给出批量策略、计划适配能力和负例，不能让矩阵靠人工记忆同步。