weichen/Agent-System
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(remediation): add partial/deferred completion plan (W1-W7) and short-term controller

Browse Source
This commit is contained in:
weichen
2026-09-16 16:03:50 +00:00
parent 83f9004f9e
commit bb8d921e7c
4 changed files with 240 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.doc/ops/CURRENT.md
+3 -2
View File
@@ -5,14 +5,15 @@
## 焦点
1. **全量 backlog 覆盖 no-go**：P0–P7 已合入 `dev`；Playwright 双标签真浏览器 PASS 已合入（[报告](../test-reports/2026-09-16-intent-plan-playwright-dual-tab-test-report.md)）
2. **运维**：nightly `DATA_DIR=dev` 已对齐；U8 PASS；FullNone product_fail 仍待收口
1. **partial/deferred 全量收口**：[收口计划](../remediation/2026-09-16-partial-deferred-completion-plan.md)（W1–W7；6 partial + 1 deferred → done；通信机制已确认为模块化单体端口+组合根+PG事件+HTTP 边界，不新增 RPC 层）；前序 P0–P7 与 Playwright 双标签 PASS 已合入
2. **运维**：nightly `DATA_DIR=dev` 已对齐；U8 PASS；FullNone product_fail 仍待收口（并入收口计划 W1）
3. **红线**：禁止整支 merge FAV；不默认升 `MULTI_INTENT_PLAN_TIER=full`；flag 默认 off；项目 143 只读
## 并行认领
| owner | task | branch | worktree | mutex | status |
|-------|------|--------|----------|-------|--------|
| Cline | 2026-09-16-partial-deferred-completion | docs/partial-deferred-completion-plan | - | architecture-docs | in_progress |
| Cursor | 2026-09-16-intent-plan-playwright-dual-tab | feature/intent-plan-cards-playwright | .worktrees/feature-intent-plan-cards-playwright | web | done |
| Cursor | 2026-09-16-full-backlog-override | docs/override-nogo-full-backlog | - | architecture-docs | done |
| Cursor | 2026-09-16-gitea-nightly-docker-datadir | fix/gitea-nightly-docker-datadir | - | ci | done |
.doc/ops/short-term/2026-09-16-partial-deferred-completion.md
+43
View File
@@ -0,0 +1,43 @@
---
title: "partial/deferred 全量收口总控"
status: in_progress
created: 2026-09-16
updated: 2026-09-16
owner: Cline
branch: docs/partial-deferred-completion-plan
worktree: "-"
mutex: architecture-docs
---
# partial/deferred 全量收口总控
## 目标
按 [收口计划](../../remediation/2026-09-16-partial-deferred-completion-plan.md) 把 FEATURE-MATRIX 6 行 `partial` + 1 行 `deferred` 推进到 `done`；全程保持模块独立解耦（端口 + 组合根 + PG 事件 + 契约门禁，不新增 RPC 层），变更影响面不跨模块扩散。
## 授权
用户 2026-09-16 要求已设计功能尽量推进 done，并确认通信机制与系统契约。
## 步骤
1. [ ] W1 CI/E2E 收口（mutex `ci`；secret/runner 配置 + FullNone product_fail + green nightly）
2. [ ] W2 PU6 语义摘要 D3（mutex `chat`；shadow + 真实 PI + R13 + 负例）
3. [ ] W3 PU7 PI change-report 叙事（mutex `docgov`；开 flag + 真实 PI + fallback 负例 + UI 区分）
4. [ ] W4 PU8 U9–U12（mutex `intent-plan`；逐 action 独立 flag，U9→U12 顺序）
5. [ ] W5 纯软件自举（mutex `workflow-design`；SWBOOT-10 非 stub + 真实 PI + UI 二次验收）
6. [ ] W6 FAV（mutex `events`；subscriber 审计 → shadow → live；禁止整支 merge）
7. [ ] W7 D7 数据治理（mutex `chat`，排在 W2 后；盘点 → 口径 → 整改；违规升 gap-matrix）
8. [ ] 逐行升 done（保留 lineage）+ CURRENT / 契约状态同步
## 验收标准
- [ ] 各波独立 short-term / feature 分支 / test-report / 回滚点（占用对应 mutex）
- [ ] 计划 DoD 全勾（见 remediation 计划 §8）
- [ ] `production_ready` 与 B1–B4 门禁零回归
## 相关链接
- Plan: [../../remediation/2026-09-16-partial-deferred-completion-plan.md](../../remediation/2026-09-16-partial-deferred-completion-plan.md)
- 矩阵: [../../status/FEATURE-MATRIX.md](../../status/FEATURE-MATRIX.md)
- 上位: [2026-09-16-full-backlog-override.md](./2026-09-16-full-backlog-override.md)（P0–P7 已完成，本总控承接其收口阶段）
.doc/remediation/2026-09-16-partial-deferred-completion-plan.md
+193
View File
@@ -0,0 +1,193 @@
---
title: "FEATURE-MATRIX partial/deferred 全量收口计划"
status: in_progress
created: 2026-09-16
updated: 2026-09-16
type: refactor
owner: Cline
branch: docs/partial-deferred-completion-plan
mutex: architecture-docs
---
# FEATURE-MATRIX partial/deferred 全量收口计划
## 1. 背景
- **用户授权（2026-09-16）**：已设计的功能与特性尽量推进到 `done`，不停留在 `partial`/`deferred`；保持功能、模块的独立与解耦；确认模块间通信机制；建立系统契约，保证新功能添加、已有功能修改的影响面收敛在所属模块，不扩散到其他模块。
- **收口对象**：[FEATURE-MATRIX](../status/FEATURE-MATRIX.md) 中 6 行 `partial` + 1 行 `deferred`（见 §3 总表）。
- **上位约束**：`production_ready=yes` 与发布门禁 B1–B4 已签。本计划是**能力成熟度收口**，与发布门禁正交；`production_ready` 只由 [gap-matrix](./gap-matrix.md) 决定，本计划不得反向触碰已签门禁。
- **通信机制结论先行**：本系统为模块化单体，模块间通信**不采用、也不应改成通用 IPC/RPC**；已确认的跨进程边界全部走 HTTP 与 PG 持久事件。详见 §2。
## 2. 通信与解耦机制确认（IPC/RPC 问题的回答）
**结论：系统是模块化单体（[ADR 2026-09-14-modular-monolith-decoupling](../adr/2026-09-14-modular-monolith-decoupling.md)），模块级隔离靠「消费者窄端口 + 组合根唯一装配 + 契约门禁」实现，而非 RPC 层。**已确认的通信边界共四类：
| 边界 | 机制 | 状态 |
|---|---|---|
| Web ↔ server | `/api/v1/*` HTTP + SSE（typed error envelope） | 已运行 |
| Go server ↔ PI Agent Runner | HTTP + Bearer（typed-result-v1） | 已运行 |
| 单体内模块 | 消费者窄端口 + `internal/app` 组合根唯一装配 | 已运行 |
| 跨进程领域事件 | PG outbox（envelope/delivery）+ `cmd/events` 独立 worker 原子 lease 消费 | 已运行（notify/advance/projection live） |
**为什么不把单体内端口改成 RPC**（依据 [IPC/RPC 现状评估](../ops/research/2026-09-15-module-decoupling-ipc-assessment.md)）：RPC 会增加序列化、延迟、部分失败与运维成本，却不消除 locator、授权、幂等和事件消费缺口；真正的进程级解耦已由 `cmd/events` worker（经 PG lease，而非服务间直连）与两条 HTTP 边界承担。用户要求的「通过 IPC/RPC 通信」在本系统的正确落法即：**跨进程一律走既有 HTTP / PG 事件边界；模块级独立解耦靠端口与契约门禁**。若未来确需新增跨进程边界，须先立 ADR，沿用「HTTP 或 PG 事件」两种既有模式。
### 2.1 系统契约体系（防扩散的既存机制，本计划全部沿用）
| 契约 | 载体 | 强制方式 |
|---|---|---|
| Import / SQL write / path / event 边界 | `.doc/system-design/module-boundaries.yaml` | `internal/archtest` + `./scripts/arch-check.sh --mode block`；import/event 违规零容忍（block_kinds） |
| 领域事件 schema 与生产者/消费者 | `events.Envelope` schema 1 + YAML allowlist ↔ `StaticContracts` parity | 构建期 parity 门禁；未登记事件不得投递 |
| 任务幂等与产物 | `taskrun.RunManifest` canonical JSON + SHA-256 + idempotency key | 服务端强制；异 digest 冲突 |
| HTTP 错误语义 | typed error envelope（details allowlist + 脱敏） | 已合入（H1–H3） |
| PI Runner 协议 | typed-result-v1 + handshake；typed 字段存在但无效 → fail closed | 已合入 |
| 能力灰度 | 每能力独立 flag，默认 off / legacy / shadow | 各契约预注册晋级阈值 |
| 并行认领互斥 | FEATURE-MATRIX `mutex` 列 → CURRENT 认领表 | 同一 mutex 同时仅一个 `in_progress` |
### 2.2 变更影响面收敛守则（每个波次必须遵守）
1. 新能力一律落在**深模块**（模式参考 `internal/app/intentflow`、`internal/doccontent`），禁止把实现聚集回 coordinator/bizdev。
2. 模块间只允许三种交互：消费者拥有的窄端口、组合根装配、领域事件；**禁止新增跨模块 import**（arch-check block 兜底）。
3. schema 变更只走 additive migration；旧版本兼容读取；每个放量有独立回滚点。
4. 每个能力一个独立 flag；默认 off；晋级按预注册阈值（shadow → confirm → live/replace），禁止共用开关批量上线。
5. 新增事件必须同时补 YAML allowlist 与 `StaticContracts` 并过 parity 门禁。
6. 修改声明范围须保留 before/after lineage 与义务迁移（矩阵更新规则 4）；禁止缩口径假完成。
## 3. 收口对象与关闭条件总表
| # | 行 | 当前 | 目标 done 的关闭条件（依据矩阵「剩余工作/关闭条件」列） | mutex |
|---|---|---|---|---|
| P1 | CI / E2E | partial | Actions secret/runner 环境配置完成 + FullNone product_fail 收口 + 一轮绿色 nightly receipt | `ci` |
| P2 | 语义摘要（D3） | partial | `SEMANTIC_SUMMARY_SHADOW` 开启并取得真实 PI + R13 + 负例证据；（可选）`SEMANTIC_SUMMARY_REPLACE` 灰度 | `chat` |
| P3 | PI change-report 叙事 | partial | `PI_CHANGE_REPORT_NARRATIVE` 开启 + 真实 PI 叙事 + fallback 全量负例 + UI narrative/事实字段区分 | `docgov` |
| P4 | 多意图扩面（U9–U12） | partial | U9→U12 逐 action 独立 flag 证据闭环（真实 PI + 浏览器 + 负例）；tier 升级评估 | `intent-plan` |
| P5 | 纯软件项目自举 | partial | SWBOOT-10 非 stub 实现 + 真实 PI 全链路 + UI 二次验收 | `workflow-design` |
| P6 | Final Artifact Vault（FAV） | partial | subscriber 独立审计 → shadow → live；崩溃/重启幂等；`FAV_DEGRADED_READ=false` 保持；**禁止整支 merge 保持** | `events` |
| P7 | 对话数据治理（D7） | deferred | 数据分类盘点 → 留存/删除口径 → 库/备份/日志控制 → 敏感字段加密边界；**发现违规 → 立即升 gap-matrix blocker** | `chat` |
**并行度**：P1 与其余全部可并行；P3/P4/P5/P6 各自 mutex 互不冲突可并行；**P2 与 P7 共用 `chat` mutex，须串行（先 P2 后 P7）**。Playwright 双标签升 `confirm/full` 属 `intent-plan` 辅助任务（见 [2026-09-16-intent-plan-playwright-dual-tab](../ops/long-term/2026-09-16-intent-plan-playwright-dual-tab.md)）。
## 4. 分波次计划
每波通用流程：从 `dev` 开独立分支（`feature/<slug>`）→ CURRENT 登记 → worktree 编码与单测 → 占集成槽合并 `dev` + 冒烟（`go vet` / `go test -short` / `env-service.sh dev rebuild` + `/health`）→ test-report 归档 → FEATURE-MATRIX 行升 `done`（保留 lineage）。
### W1（mutex `ci`）：CI / E2E → done
**现状**：nightly 入口 + 失败分类 + promotion-receipt 门禁已交付；TempDir race 已修；PR CI 不依赖外部模型。剩余：环境配置与 FullNone product_fail。
1. Actions secret 录入：`TEST_DATABASE_URL`、nightly 专用 `RUN_PI_E2E` / `RUNNER_AUTH_TOKEN`（隔离合成数据）；runner 注册与自检。
2. FullNone product_fail 收口：按 infra/product 分栏定位，修复产品失败或确认分类归属；nightly `DATA_DIR=dev` 保持对齐。
3. 跑一轮完整 nightly → green receipt 归档。
4. 矩阵行升 `done`（证据：[Wave2B](../test-reports/2026-09-16-wave2b-nightly-promotion-receipt-test-report.md)、[Wave2C](../test-reports/2026-09-16-wave2c-same-image-digest-test-report.md) + 新 green receipt）。
**回滚**：纯环境/CI 配置，不影响业务行为；secret 配置错误仅影响 nightly，不挡 PR CI。
### W2（mutex `chat`）：PU6 语义摘要 D3 → done
1. dev 环境 `SEMANTIC_SUMMARY_SHADOW=on`（test 环境随后），收集 shadow 对账：authorized view only、无工具权限摘要器、R13 出站门。
2. 真实 PI（MiniMax）摘要证据：freshness 标注、可解释 fallback。
3. 负例矩阵：撤权消息不入摘要；injection 不能改权限；失败保留旧摘要/deterministic。
4. 达预注册阈值后可选 `SEMANTIC_SUMMARY_REPLACE` 灰度（独立回滚：关 flag 回 deterministic）。
5. 矩阵行升 `done`；[契约](../ops/long-term/2026-09-16-pu6-semantic-summary-contract.md)状态更新。
**路径**：`internal/ctxmgr/summarizer.go`、`internal/app/chatflow/`、`internal/server/chat_digest_api.go`、web 摘要组件。
### W3（mutex `docgov`）：PU7 PI change-report 叙事 → done
1. dev `PI_CHANGE_REPORT_NARRATIVE=on`：真实 PI 只读消费 immutable diff+lineage+risk floor。
2. typed schema `change_report_narrative_v1` + input digest 绑定；任意 schema/超时/注入 → 全量 fallback（负例必测）。
3. UI 验收：narrative 与事实字段明确区分；禁止覆盖服务端风险/审批结论。
4. 矩阵行升 `done`（deterministic fallback 仍是本行显式声明行为）。
**回滚**：关 flag，仅 deterministic fallback，无第二份 candidate。契约：[pu7](../ops/long-term/2026-09-16-pu7-pi-narrative-contract.md)。
### W4（mutex `intent-plan`）：PU8 U9–U12 → done
**顺序 U9→U10→U11→U12，逐 action 独立 flag，禁止共用开关批量上线：**
1. U9 `MULTI_INTENT_U9_SEGMENT`：真实 LLM 分段 shadow→confirm；规则无法判断时才出 proposal；stub fail-closed 保持。
2. U10 `MULTI_INTENT_U10_MUTATE`：dry-run + expected revision 门禁；未确认/越权/stale revision/重复提交 → 零越界副作用。
3. U11（docgov）、U12（workflow/run-control）：按各自契约同模式推进。
4. 每个 action：真实 PI + Playwright 双标签 + 负例；独立报告与回滚点。
5. 全部闭环后：评估 `MULTI_INTENT_PLAN_TIER` legacy→confirm（**独立任务、独立授权**，默认不升 full；full 另拆行/backlog）。
6. 矩阵行升 `done`（声明范围 = 四个 action 的 flag 证据闭环；tier=full 不在本行关闭条件内）。
契约：[u9](../ops/long-term/2026-09-16-pu8-u9-segment-proposal-contract.md) / [u10](../ops/long-term/2026-09-16-pu8-u10-mutate-contract.md) / u11 / u12。
### W5（mutex `workflow-design`）：纯软件项目自举 → done
1. SWBOOT-10 从 stub 收口为真实现（按 [short-term](../ops/short-term/2026-09-16-software-project-bootstrap.md) 与 [ADR keys](../adr/2026-09-16-software-project-bootstrap-keys.md)）。
2. 真实 PI 全链路：`software_bootstrap` 工作流 创建→规划→交付（首期 docs_only / read_only_repo）。
3. Playwright UI 二次验收：服务端目录驱动的创建向导（停止前端固定克隆 7 份模板）、单人项目「无独立评审」显式标记。
4. 矩阵行升 `done`（范围沿用现状调研的复用/新增边界，不改医疗三工作流语义）。
### W6（mutex `events`）：FAV → done
1. subscriber 独立审计（沿用 U7 增量路径，**继续禁止整支 merge FAV 分支**）。
2. publisher/consumer flag **shadow**：只计算 intended outcome，不执行业务副作用。
3. shadow 阈值达标后逐 consumer **live**：staging/artifact/publication 幂等（唯一键/no-replace）；崩溃/重启重放无重复可见结果。
4. `FAV_DEGRADED_READ=false` 保持默认；degraded 读取仅在显式开启时可用并有告警。
5. 矩阵行升 `done`（声明范围：不可变终态制品库闭环）。
### W7（mutex `chat`，排在 W2 后）：D7 对话数据治理 → done
**前提**：需要用户/合规输入留存期限与删除口径（开放问题 §7）。
1. 数据分类盘点（产出 audit 文档）：chat_sessions/messages、KB、日志、备份、event 表中的敏感字段清单与流转路径。
2. 留存/删除口径落 ADR；库/备份/日志控制盘点。
3. 差距整改：日志/dead-letter/reconciliation 只存 ID、digest、typed error code 与 allowlist 摘要（Track E 红线沿用）。
4. 敏感字段加密边界决策与落地（如决定启用）。
5. **若盘点确认基线违规 → 立即写 gap-matrix blocker，本行 done 让位于整改**；无违规且口径落地 → 矩阵行升 `done`。
## 5. 测试方案（层级矩阵）
| 层级 | 适用波次 | 内容 | 通过标准 |
|---|---|---|---|
| Arch / contract | 全部 | `./scripts/arch-check.sh --mode block`；YAML ↔ `StaticContracts` parity | import/event 违规 = 0；无未登记事件 |
| 单测 | 全部 | `go vet ./...` + `go test -short ./...`；相关包 `-race` | 全绿；无 data race |
| PG 集成 | W2/W4/W5/W6/W7 | `TEST_DATABASE_URL` 下集成 + additive migration/回滚演练 | 持久化、恢复、旧版本兼容读取 |
| 真实 PI | W2/W3/W4/W5 | 真实 PI Agent Runner + MiniMax；记录 model/protocol/typed result；R13 数据安全门（最小出站、租户绑定、脱敏、凭证最小权限、泄漏负例） | 无 stub 冒充；无敏感出站 |
| 浏览器 | W2/W3/W4/W5 | Playwright：真实登录、双用户/职责负例、刷新/重登/重启 | 页面结果与 PG/账本一致 |
| 部署 | 全部运行时波次 | 占集成槽 rebuild、`/health`、promotion receipt（same digest 晋升） | 可追到同一 commit + digest |
| 回滚 | W2–W6 | disable/drain、旧版本兼容读取、无双 writer、孤儿状态检查 | 上一版本恢复且无孤儿状态 |
每波验收报告归档 `.doc/test-reports/`（遵循 test-reports-standard），回链本计划与对应契约；矩阵状态提升必须同时核对源码、迁移、artifact、API/runtime 与测试层级（上位计划 R5–R7）。
## 6. 风险与停走门
| 风险 | 停走门 |
|---|---|
| 授权旁路 / 跨用户泄漏 / 双 writer / main 或 prod fail-open | 任一波发现 → 停止全部扩面，写 gap-matrix |
| B1–B4 门禁回归 | 每波合 dev 冒烟全绿；回归即停 |
| stub / SKIP / deterministic fallback 冒充真实 PI | 验收报告必须记录真实 runner/model；SKIP 不得写成 PASS |
| flag 批量上线 / 共用开关 | 一个能力一个 flag；违规合并打回 |
| 缩小声明范围制造 done | 矩阵审查：before/after lineage 必须保留，义务迁移可追 |
| 三环境隔离破坏 | 每波验证不跨环境读写；schema 迁移三环境同步（当前 47） |
| FAV 整支 merge | 保持禁止；只走增量分支 + 独立审计 |
## 7. 需要用户决策的开放问题
1. **D7 留存期限与删除口径**（合规输入）——W7 前置，无法由工程侧单方面决定。
2. **`MULTI_INTENT_PLAN_TIER` 是否升 `confirm`**——W4 完成后独立授权（默认不升 `full`）。
3. **`SEMANTIC_SUMMARY_REPLACE` 是否启用**——W2 shadow 达阈值后的后置决策。
4. **FAV live 消费者上线顺序与观察窗口**——W6 shadow 后决策。
## 8. 验收标准（Definition of Done）
- [ ] W1–W6 各波 test-report 归档并回链；对应 FEATURE-MATRIX 行升 `done`（保留 lineage）。
- [ ] W7 数据分类盘点与口径文档落地；或违规升级 gap-matrix（该行转为整改跟踪）。
- [ ] 全程 `production_ready` 不翻转；gap-matrix 仅在真实 blocker 出现/关闭时变化。
- [ ] `arch-check --mode block` 全程通过；无新增跨模块 import、无未登记事件。
- [ ] 所有新 flag 保持独立且默认 off/legacy/shadow；每个放量有独立回滚点。
- [ ] B1–B4 门禁零回归（每波合 dev 冒烟全绿）。
- [ ] 开放问题 §7 的四项决策均已获用户确认或显式延期。
## 9. 相关链接
- 矩阵 SSOT: [../status/FEATURE-MATRIX.md](../status/FEATURE-MATRIX.md)
- 连续性审计: [../audit/2026-09-16-feature-matrix-production-readiness-audit.md](../audit/2026-09-16-feature-matrix-production-readiness-audit.md)
- 上位计划: [./2026-09-16-feature-matrix-production-readiness-plan.md](./2026-09-16-feature-matrix-production-readiness-plan.md)
- 发布门禁: [./gap-matrix.md](./gap-matrix.md)
- IPC/RPC 调研: [../ops/research/2026-09-15-module-decoupling-ipc-assessment.md](../ops/research/2026-09-15-module-decoupling-ipc-assessment.md)
- 模块解耦 Phase 2: [./2026-09-15-module-decoupling-ipc-phase2-remediation-plan.md](./2026-09-15-module-decoupling-ipc-phase2-remediation-plan.md)
- 契约: `../ops/long-term/2026-09-16-pu6-*` · `pu7-*` · `pu8-u9…u12`
- 总控 short-term: [../ops/short-term/2026-09-16-partial-deferred-completion.md](../ops/short-term/2026-09-16-partial-deferred-completion.md)
.doc/remediation/INDEX.md
+1
View File
@@ -3,6 +3,7 @@
| 文档 | 说明 |
|------|------|
| [gap-matrix.md](./gap-matrix.md) | 发布缺口 SSOT |
| [2026-09-16-partial-deferred-completion-plan.md](./2026-09-16-partial-deferred-completion-plan.md) | FEATURE-MATRIX 6 partial + 1 deferred 全量收口：通信机制确认（模块化单体，不新增 RPC 层）、7 项关闭条件、W1–W7 波次与测试层级矩阵 |
| [2026-09-16-feature-matrix-production-readiness-plan.md](./2026-09-16-feature-matrix-production-readiness-plan.md) | 能力状态与发布门禁解耦、证据校准、剩余 partial 收口和 production-ready 防回退计划（[审计](../audit/2026-09-16-feature-matrix-production-readiness-audit.md)） |
| [2026-09-14-module-decoupling-refactor-plan.md](./2026-09-14-module-decoupling-refactor-plan.md) | 纵向绞杀、UnitOfWork、高并发互斥、可靠事件、逐动作授权、FAV、迁移与恢复的详细重构计划 |
| [2026-09-15-module-decoupling-ipc-phase2-remediation-plan.md](./2026-09-15-module-decoupling-ipc-phase2-remediation-plan.md) | Phase 2 修订版：Track E 持久事件交付先行；Track S 结构解耦独立 go/no-go；HTTP 与 PI 协议另立 remediation（[审阅](../audit/2026-09-15-module-decoupling-phase2-plan-review.md)；[调研](../ops/research/2026-09-15-module-decoupling-ipc-assessment.md)） |