Agent-System/.doc/remediation/2026-09-20-capability-enablement-impact-plan.md

title, status, created, updated

title	status	created	updated
功能启用与项目文档修改影响分析整改方案	in_progress	2026-09-20	2026-09-20

功能启用与项目文档修改影响分析整改方案

1. 背景与目标

本方案依据源码与运行态调研。目标不是一次性打开全部 flag，而是使系统能够回答并证明四件事：功能是否真正接入生产入口、当前在哪个灰度阶段、失败时如何回退、用户如何看到可靠结果。

第二个目标是让助手在每次文档候选或提交后提供：本次修改内容、项目及相关文档影响、证据和不确定性、下一步建议。常规分析只读取变更片段和已登记关联；首次建索引、索引损坏或明确重建时才允许后台全量扫描。

本方案不直接授权启用 test/main 开关，也不授权 FAV、D7 删除策略、软件自举受控执行或全局编制人兼任。每个波次在 feature/fix 分支实施，合 dev 和共享容器验证继续占用 CURRENT 集成槽。

2. 总体判断

2.1 能力分组

组别	能力	当前动作
已在用	legacy 有限只读多意图、确定性摘要、确定性文档 diff/风险/report	保持运行，补观测，不改变默认行为
整改后可灰度	多意图 shadow/auto_read、语义摘要 shadow、PI change-report narrative	完成各自前置项后只在 dev 小范围开放
仍需实现	confirm 后可靠调度、U9 真实入口、U10–U12 live、语义摘要 replace、项目追踪索引	按波次开发和验收，不能用开关代替实现
继续关闭	full 一键放量、FAV live/degraded read、D7 物理删除、SWBOOT-10 stub 绕过	保持现状，另立授权与验收

2.2 核心架构

flowchart TB
  Candidate[文档候选] --> Preview[proposed 预估报告]
  Commit[正式提交] --> Ledger[文档快照和版本账本]
  Ledger --> Outbox[可靠事件]
  Outbox --> Indexer[增量追踪投影器]
  Indexer --> Items[项目追踪条目和修订]
  Indexer --> Edges[版本化关系]
  Items --> Analyzer[影响分析器]
  Edges --> Analyzer
  Ledger --> Analyzer
  Analyzer --> Report[持久变更报告]
  Preview --> Chat
  Report --> Chat[聊天影响卡]
  Report --> DocUI[文档版本面板]
  Report --> ProjectUI[项目追踪视图]
  Chat --> Suggested[用户选择建议动作]
  Suggested --> Auth[重新鉴权、租约、版本检查]
  Auth --> Workflow[目标文档工作流]

确定性事实始终由服务端账本、项目追踪关系和权限判定生成。PI 只生成解释、候选关系和建议，不能降低风险、扩大可见集或直接修改其他文档。

3. 功能就绪与灰度契约

管理台需要把一个“开关”拆成以下字段，避免 value=true 被误解成可用：

字段	含义
configured_value	配置声明值
effective_value	当前进程实际值
implementation_state	placeholder / dry_run / shadow / live
adapter_readiness	ready / unavailable / degraded，以及原因
rollout_scope	环境、项目、用户或百分比
requires_restart	是否需要重启
evidence	最近一次验收报告和镜像 digest
metrics	调用量、成功率、回退率、P95、最近错误

开关变更需写审计记录并支持按项目 allowlist。关闭时，已有计划和报告仍可读取；执行中的任务进入可解释终态，不能静默遗弃。

管理台采用“先读后改”的能力详情流。effective_value、成熟度、adapter readiness、证据和指标始终只读；管理员编辑 configured value 和允许的 rollout scope 时，页面即时展示未满足门禁和是否需要重启。提交前预览旧值、新值、作用范围和预期实际效果；提交后明确显示待重启、部分生效、成功或失败，并提供基于上一审计 revision 的回退动作。保存配置成功不等于能力已经生效。

3.1 多意图状态机

stateDiagram-v2
  [*] --> Legacy
  Legacy --> Shadow: 只生成和对账计划
  Shadow --> AutoRead: 只读指标达标
  AutoRead --> Confirm: 生成动作验收通过
  Confirm --> DomainLive: 单一领域适配器验收
  DomainLive --> WiderRollout: 观察窗达标
  Shadow --> Legacy: 错误率或成本超阈值
  AutoRead --> Legacy: 权限、重复或恢复异常
  Confirm --> Legacy: 确认前副作用或调度异常

• shadow 必须从真实聊天入口生成持久但不可执行的计划，并与 legacy 结果对账；当前 legacy/no-op 语义不足以充当完整 shadow。
• auto_read 只允许真实查询 owner；receipt 必须包含查询类型、授权范围 digest、结果版本和恢复标识，禁止 Fake owner。
• confirm 在用户确认前零业务写。决定事务复用现有 intent_plan_steps、ClaimStep、ExecuteClaimed、RecoverReceipt 和 intent.plan 事件作为唯一执行事实源；新增生产 dispatcher 领取已有步骤，重新鉴权、检查 expected resource version，再调用幂等领域 owner。禁止另建第二套决定队列和步骤状态机。
• U9 仅在规则分段低置信时提出候选 span；所有候选仍进入相同策略、鉴权和确认链。
• U10、U11、U12 分别接真实领域端口和独立 allowlist；不使用 full 同时开放。

3.2 语义摘要状态机

stateDiagram-v2
  [*] --> Deterministic
  Deterministic --> Shadow: 后台生成语义候选
  Shadow --> ReplacePilot: 质量与数据安全门禁通过
  ReplacePilot --> ProjectRollout: 项目白名单观察窗通过
  ProjectRollout --> EnvironmentRollout: 环境级批准
  Shadow --> Deterministic: 超时、校验失败或撤权
  ReplacePilot --> Deterministic: 事实丢失或陈旧

语义叙事只替换 Narrative，Facts 和 OpenQuestions 由服务器合并保护。每份摘要绑定 session、授权可见集 digest、from/to message ID、上个摘要 revision、模型/协议版本和生成时间。授权变化或消息修订使其失效。

摘要生成放到可靠后台任务；用户请求先返回确定性摘要。PI 返回必须包含 input digest、覆盖水位和结构化字段，服务端严格校验。失败继续提供确定性结果并记录 fallback，不阻断聊天。

4. 项目追踪数据模型

4.1 设计原则

1. 项目级统一身份，工作流、文档和阶段作为归属，不为每个工作流复制需求。
2. 正文仍由 document snapshot/version 账本管理；追踪表只存结构化字段、定位和 hash。
3. 条目修订不可变，删除使用 tombstone；关系有生效和失效版本。
4. 确定关系、人工确认关系、规则抽取关系、模型候选关系分开存放。
5. 所有读取先经过项目与逐文档可见性过滤；不可通过标题、数量、错误或候选泄漏隐藏文档。

4.2 建议表

project_trace_items

稳定项目条目身份。

字段	说明
id / project_id	主键和项目边界
business_key	项目内稳定键，如 UR-001、REQ-017、TC-017
kind	requirement / risk / interface / test / decision / deliverable
lifecycle_state	draft / active / superseded / retired
current_revision_id	当前修订指针
created_at / created_by	审计字段

约束：unique(project_id, kind, business_key)；business_key 变更使用 alias 或 supersedes 边，不直接改写历史身份。

条目身份契约：合规且项目内唯一的显式业务键可直接绑定；无键条目分配不可变内部身份；重复键阻断投影并进入人工消歧；改名必须通过旧键映射和 expected revision 显式确认，未确认时按“删除候选 + 新增候选”处理。历史回填保留可审计映射，不能靠标题相似度静默合并身份。

project_trace_item_revisions

不可变条目版本。

字段	说明
item_id / revision_no	条目和单调修订号
source_doc_id / source_snapshot_id	权威文档版本
block_id / heading_path / anchor	精确片段定位
content_hash	规范化片段 hash
title / statement	结构化标题和陈述
acceptance_criteria / verification_method	需求和验证字段
attributes	类型专属 JSONB；需 schema_version
evidence_kind	declared / extracted / imported
review_state	confirmed / candidate / rejected
extractor_version	重建和兼容依据
tombstone	在该快照已删除

唯一幂等键建议为 (source_snapshot_id, block_id, extractor_version, content_hash)。

project_trace_edges

版本化关系边。

字段	说明
project_id	事务与鉴权边界
from_item_id / to_item_id	有向关系两端
relation_type	refines / satisfies / verifies / mitigates / depends_on / conflicts_with / supersedes
from_revision_id / to_revision_id	关系成立时的证据版本
evidence_doc_id / snapshot_id / block_id	可点击证据
provenance	explicit_reference / workflow_consumption / rule / human / model_candidate
confidence	仅候选使用，不覆盖事实状态
review_state	confirmed / candidate / rejected；由决定账本投影
valid_from / valid_to	关系历史
created_by / reviewed_by	审计字段；reviewed_by 由决定账本投影

禁止用向量相似度直接生成 confirmed edge。模型候选不能触发自动写文档或把风险降级。

project_trace_edge_decisions

人工关系治理的不可变权威账本，避免重建投影时丢失已经确认、拒绝或撤销的决定。

字段	说明
id / project_id / edge_key	决定身份、项目和稳定关系键
candidate_revision_id	决定针对的候选版本
decision	confirm / reject / revoke
reason / evidence_refs	原因和当时可见证据引用
expected_revision	CAS 版本
decided_by / decided_at	操作者和时间

project_trace_edges 是文档事实、抽取结果与此决定账本的联合投影。重建必须重放决定账本；旧候选不得因 extractor 重跑而绕过既有拒绝，关系两端或证据实质变化时才产生新候选 revision。

project_trace_index_state

保存 project_id + doc_id + source_snapshot_id + extractor_version、status、indexed_at、覆盖条目数、失败原因、retry_count。只有状态为 complete 且 source snapshot 与当前基线一致，UI 才能显示“已分析且未发现影响”。

每次影响报告另记录项目覆盖 epoch、当前可见文档集合 digest，以及集合内各文档的 current snapshot 和 extractor version。只有集合全部 complete 且仍与当前基线一致，才可返回 no_known_dependencies；任一缺失、陈旧或失败分别返回 index_pending、partial 或 failed。

4.3 与现有 document_lineage 的关系

document_lineage 保留文档级的实际消费事实，但改用真实 snapshot/version，修复写死 version=1，并支持有效期。条目级 edge 解释被消费内容及其具体影响。静态工作流先后顺序不能自动当作真实依赖；没有实际引用时只可作为“建议检查”候选。

5. 增量索引与影响分析

5.1 提交链路

sequenceDiagram
  participant U as 用户/Agent
  participant D as 文档命令
  participant L as 版本账本
  participant O as Outbox
  participant I as 追踪投影器
  participant A as 影响分析器
  participant R as 报告/UI
  U->>D: 保存候选
  D->>D: 权限、租约、expected revision
  D->>A: 生成 proposed 预估报告
  A->>R: 保存 proposed report，不写 stale/通知
  R-->>U: 展示预估影响和下一步
  U->>D: 正式提交
  D->>L: 原子写 snapshot/version
  D->>O: 写 document.committed
  O-->>I: 至少一次投递
  I->>I: 按 snapshot+extractor 幂等增量抽取
  I->>A: trace.indexed 或 trace.failed
  A->>A: 授权过滤后有界反向遍历
  A->>R: 持久 report + coverage status
  R-->>U: 修改、影响、证据、建议

所有候选来源必须生成并持久化标识为 proposed 的预估报告：Agent 生成、人工块编辑、恢复历史版本、导入和修复迁移。候选报告不能写 stale、触发正式通知或发出 document.committed。正式提交后才写账本、发出 document.committed 并生成 authoritative report。

5.2 增量算法

1. 对比前后 block map 和 business key，识别新增、修改、删除、移动、改名。
2. 只重新抽取变化块及必要父标题；未变 block 沿用已确认条目修订。
3. 只有 schema 明确给出关系类型的结构化引用和已记录的实际工作流消费可自动写 confirmed 边。普通正文中的无类型 ID 提及只生成带上下文证据的 candidate；否决方案、历史引用和否定语境不得自动确认。模型只为未覆盖条目产生候选。
4. 后台以受审计的项目服务身份从变化条目反向遍历 confirmed 边；默认深度 3、节点数和时间有上限，并启用 cycle detection。规范结果只保存结构化条目、关系、文档标识和证据定位，不保存可直接向普通用户展示的隐藏正文。
5. 对命中的目标读取对应片段和邻接上下文，不读全部文档；首次索引或修复任务在后台全量读取，并显示状态。
6. 将 diff、条目变化、直接/间接影响、证据路径、索引覆盖和建议保存到规范 report revision。每次读取按当前主体重新执行逐文档策略，过滤 source、target 和 evidence 后重算数量、覆盖状态和展示文案。
7. 乱序事件不能将索引回退到旧 snapshot；重复事件返回同一投影结果。

5.3 影响状态与风险

必须区分：

状态	含义	UI 文案方向
confirmed_impact	确定关系和内容变化证明影响	需要复核/更新
possible_impact	候选关系或语义不确定	建议核实，不自动写
dependency_unchanged	存在关系，但相关片段未受影响	已检查，无需动作
no_known_dependencies	索引完整，未登记关系	未发现已知关联
index_pending	新版本尚未分析完	分析中，不能判断无影响
partial	达到查询上限或部分目标不可分析	结果不完整
failed	投影/查询失败	分析失败，保守处理

风险计算应按变更内容、关系类型、目标基线状态和证据确定性合成。纯格式变化不因存在 lineage 自动升 critical；删除已批准安全需求、关键数值变化、冲突关系或已批准下游失效继续保持 high/critical 下限。

6. 影响报告与用户交互契约

报告至少包含：

• report_id、project_id、source doc/snapshot、from/to SHA、状态和生成时间。
• 本次修改：业务键、位置、旧值→新值、变更类型；无业务变化时明确说明。
• 项目影响：工作流、阶段、风险、交付物和阻塞条件。
• 文档影响：可见文档名称、状态、直接/间接、确定/候选、证据路径。
• 覆盖说明：索引 snapshot、extractor/version、complete/partial/pending/failed。
• 建议动作：action key、原因、目标、前置条件、责任职责、是否需要确认。
• PI 说明 provenance：deterministic / pi_enriched / fallback，模型、协议、input digest。

同一 report_id 指向服务端规范事实，由聊天卡、文档版本面板和项目“需求与影响”页共同引用。每次规范结果更新生成单调 report_revision。面向用户的 ReportView 以 report_id + report_revision + authorization_visibility_digest + narrative_protocol_version 为键：先按当前主体过滤文档、条目、证据和数量，再生成确定性文案或 PI 叙事。trace.indexed、trace.failed、关系决定、规范报告更新和授权变化都失效旧视图；刷新、重登和重启后，同一主体看到一致结果，不同权限主体不会共享自由文本叙事。

proposed 报告具有 active、superseded、rejected、expired、committed 生命周期，绑定 candidate revision、base snapshot 和 expected head。候选被拒绝/取消、新候选替代、基线推进或版本冲突时，旧报告不可再创建建议动作；正式提交时写入 authoritative successor report_id。

助手应在候选生成后展示 proposed 预估影响，并在正式提交后展示 authoritative 结果。两种状态均主动说明：

1. 本次实际改了什么。
2. 对当前项目或工作流的影响。
3. 还可能涉及哪些文档及证据。
4. 哪些关系尚不确定或索引尚未完成。
5. 建议的有序下一步。

用户点击“按建议修改”只创建明确的动作草案；随后重新检查权限、职责、租约、expected revision 和审批规则。总结、查询、分析类意图保持只读，不自动启动修改。

每个建议动作使用统一可见状态：available、checking、draft_created、confirmation_required、executing、completed、forbidden、stale_or_conflict、failed、cancelled。三个入口共用状态和按钮语义；目标文档显示草案入口，冲突要求刷新后重新预览，失败可重试，取消和完成都回写原 report_id 时间线。

异步分析状态也必须给出恢复路径：index_pending 自动刷新并显示最近更新时间；partial 展示已覆盖和未覆盖范围；failed 仅展示安全的失败分类、重试状态和管理员联系/重建入口。恢复后在原 report_id 上更新状态并通知，不覆盖历史时间线。

项目“需求与影响”页的信息架构固定为：首屏先显示索引覆盖健康和待处理影响；随后是按 requirement、risk、interface、test、decision、deliverable 分类并可搜索筛选的条目清单。条目详情集中展示当前修订、上下游关系、证据片段、历史版本和关联报告；聊天卡与文档影响项直接深链到该详情。

跨界面验收包含可访问性和窄屏行为：报告和管理动作可全键盘完成；弹层聚焦标题并在关闭时归还焦点；pending/failed/completed 使用 aria-live；关系图提供等价的可筛选关系列表和证据链接；窄屏使用全宽抽屉和分组列表，主要动作满足触控操作要求。

7. API 与授权边界

建议增加或扩展以下资源，命名可在实施时按现有路由规范调整：

资源	用途	关键约束
项目追踪条目列表/详情	需求、风险、接口、测试清单	项目成员 + 文档可见性；分页、过滤
条目关系图	直接和有界多跳关系	服务端过滤后计算数量，防侧信道
文档影响报告	获取 report 和进度	source/target 均按可见性裁剪
关系候选确认/拒绝	人工治理模型候选	默认关闭；治理政策批准后才开放；CAS、决定账本、审计
索引状态/重建	管理索引健康	普通用户只读状态；重建为管理员操作
建议动作创建	从 report 生成动作草案	再鉴权、幂等、明确目标版本

现有 lineage API 先修复：doc_id 必须属于 URL project，且每个返回端点都通过逐文档策略；错误不得把不可见对象存在性泄漏给调用方。影响总数只能按调用者可见集统计。

关系候选的治理政策已由 阶段回溯设计 §8 取代下文推荐：不新增 trace_reviewer。model_candidate 由下游文档编制人确认或否决；该文档没有编制人时由项目创建者裁决。决议写入 project_trace_edge_decisions。未决候选只产生 possible_impact。全局管理员不因管理员身份获得确认权。确认事务仍须证明项目、条目和文档属于同一项目。

以下为 2026-09-20 方案原文，保留作对照，实施时以上一段为准：

关系候选治理的推荐政策是新增项目本地 trace_reviewer 动作能力，并把它嵌入现有文档职责：项目创建者只能在两端文档已有编制人或审核人中显式指派；全局系统管理员不会自动获得该项目、文档或候选的查看和确认权限。确认或拒绝时，同一 CAS 事务必须验证 route project、candidate、两个 item 和两个 source document 都属于同一项目，操作者当前可见两端文档且持有该能力。跨文档候选需要源端和目标端各一名符合条件者确认；同一人同时承担两端职责时可合并一次决定。每次变更限制候选数量并生成待办；未处理候选只产生 possible_impact，积压超过 Foundation 0 冻结门槛时停止扩大模型候选范围。此政策需用户审核通过后实施；未批准前端点保持关闭。

7.1 PI 输入安全门

Foundation 1 建立所有 PI 消费者共用的 R13 输入信封。服务端绑定 tenant/project、主体授权可见集 digest 和输入 digest；每个消费者只接收字段白名单和必要片段，执行敏感字段脱敏，并限制 runner 凭证、workspace 和日志留存。门禁不可用时 adapter_readiness=unavailable，立即走确定性回退。

语义摘要、变更叙事、U9 分段和关系候选都必须经过同一门禁；不得把“完整 diff/impact”解释为无裁剪全文。Track I、S、T 各阶段的进入条件均包含跨项目、撤权、提示注入、敏感字段泄漏和日志留存负例。

8. 分轨实施计划

先完成共享基座，再让三条能力轨道独立晋级、验收和回退，避免语义摘要被多意图或追踪索引阻塞，也避免用户最关心的影响定位排在多意图之后。

8.1 共享基座

波次	内容	主要产物	关闭条件
Foundation 0：状态校准	校准 FEATURE-MATRIX 和管理台成熟度；新增运行时 readiness/metrics；开关审计、项目 allowlist、放量阈值登记	准确能力目录和管理流程	配置值不再冒充可用性；阈值预先冻结
Foundation 1：安全与持久化	lineage API 鉴权；chat_summaries 迁移和严格错误；授权水位；纯推理 Runner profile；共用 R13 PI 输入信封	通用安全和恢复基础	PG、权限/泄漏负例、重启恢复、工具隔离通过

8.2 Track I：多意图

阶段	内容	进入下一阶段条件
I1 生产接线	真实 query owner；单轮接管；typed payload/version；复用现有步骤领取、receipt 恢复和 intent.plan 事件；新增生产 dispatcher	确认前零写、确认后一次执行、崩溃与刷新恢复通过
I2 shadow / auto_read / confirm	按状态机逐级开放项目 allowlist	精度、安全、P95、采用率和放弃率达到冻结阈值
I3 逐域扩面	U9、U10、U11、U12 分别接真实 adapter	每域真实 UI+PG+PI 长链单独通过；禁止 full 一次放量

8.3 Track S：语义摘要

阶段	内容	进入下一阶段条件
S1 shadow 生产化	后台任务、旧摘要融合、input/watermark 校验、持久 provenance、确定性即时回退	事实保持、撤权、陈旧、性能、重启和 R13 门通过
S2 replace 项目试点	只替换 Narrative；Facts/OpenQuestions 由服务端保护；项目 allowlist	shadow 标注数据达到冻结质量阈值，回退演练通过
S3 环境扩面	test/main 分别授权	各环境观察窗和真实页面验收通过

8.4 Track T：文档影响与追踪

阶段再打开、待复核和对话提案桥见 阶段回溯与影响闭环设计。下表仍是索引与报告轨道；B1–B3 是该设计拆出的回溯切片，不替代 T1–T3。

阶段	内容	进入下一阶段条件
T1 基础影响闭环	修 lineage 版本；统一提交事件；proposed/authoritative 报告；聊天卡；PI narrative 接最小化 diff/impact。人工修订、导入、聊天正式提交的报告补齐见 T1 任务	人改/Agent/恢复/导入一致；未知不伪装无影响
T2 项目追踪索引	五表迁移；结构化需求/用例投影；UR/RS/REQ/TC 键；决定账本；项目页面。留存类别已定为 record，见回溯设计 §9	双向追踪、授权、决定重放、增量幂等通过。不再等待整份 D7 对话 ADR；仍禁止物理删除
T3 多跳与候选	有界递归、循环检测、语义候选、下游编制人确认、片段装配	准确率、候选积压和成本门槛达标；候选不污染事实
B1–B3 回溯	L2 再打开、待复核软标记、对话修订提案	见各 short-term；未复核不拦截推进

推荐先并行启动 Foundation 0、lineage API 鉴权和 T1 的非 PI 部分。Foundation 1 完成后，I、S、T 各自推进；任何轨道都不能以另一轨道“尚未完成”为由跳过自身门禁。

9. 验收方案

9.1 静态与单元门

• 迁移从空库、与当前 main 一致的 schema 52 夹具、schema 53 三种基线升级均成功；main 晋升前保存升级与回退演练证据，down migration 按项目规范评估。
• config 测试保证默认值和 Compose 声明一致；未知 tier fail closed。
• 每个状态转换、CAS、幂等键、乱序事件、循环关系和查询上限有测试。
• rg 证明生产组合根无 Fake owner，live adapter 无 dry-run receipt。
• PI 纯推理 profile 的实际 argv 不包含 read/write/edit/search 或扩展，不能仅断言 prompt 文案。
• 所有 PI 消费者的 R13 输入信封校验 tenant/project、授权可见集 digest、字段白名单、脱敏和日志留存；门禁失败时能力 unavailable。

9.2 PostgreSQL 与授权门

• 两项目、两用户、项目管理员、普通成员、非成员和文档级不可见对象。
• 任意 project_id + 他项目 doc_id 不能读取 lineage、条目、边、report 或总数。
• 索引事务中断、重复和乱序事件，最终只指向最新快照。
• 删除、改名、supersede、循环、多跳、旧版本边、候选拒绝均保留历史。
• 摘要和影响报告重启后恢复；数据库写失败不得伪装持久化成功。
• 高权限提交者与低权限查看者共用 report_id 时，ReportView、PI 叙事、数量和覆盖状态按各自 visibility digest 隔离；撤权后旧视图失效。

9.3 真实聊天与浏览器门

• 用户从真实页面发起“两项查询”“查询+指定文档生成”“两项生成”“先查询再总结”“模糊指代”。
• 确认前数据库零业务写；确认后只执行所选步骤一次。覆盖双标签、重复点击、取消、超时、撤权和版本冲突。
• 在 dispatcher 领取后、领域写后/receipt 前杀进程并重启，卡片恢复且无重复副作用。
• 人工修改一条数值需求后，页面显示 old→new、相关设计/用例、证据和建议；纯格式修改不滥升 critical。
• 索引 pending/partial/failed 时禁止展示“无影响”。隐藏文档不泄漏标题、ID、摘要或数量。
• 聊天、文档版本面板和项目追踪页共用 report_id，刷新/重登/重启一致。

9.4 真实 PI 门

• 固定提交和镜像 digest，记录实际 feature state、模型、input digest、工具 profile 和耗时。
• semantic shadow、change narrative、U9 各有正常、timeout、畸形、注入和撤权用例。
• PI 不能降低服务端风险、添加 confirmed impact、扩大可见集或绕过确认。
• 不以 stub、直接 adapter 单测或 API 直调替代最终真实页面验收。

9.5 度量与放量门槛

首次 shadow 观察期至少采集：

• 多意图：segment precision/recall、写意图漏判、错误动作率、fallback、P95、计划采用率、确认放弃率、主动拆单回退率。
• 摘要：事实保持率、旧事实召回、幻觉/矛盾率、撤权失效率、fallback、P95、token/成本。
• 影响：confirmed 关系 precision/recall、候选接受率、漏报、误报、平均读取文档数/块数/字节、索引滞后、P95。
• 运行：任务重复副作用为 0，未授权读取/写入为 0，pending/failed 误报 no-impact 为 0。

具体阈值由 Foundation 0 用标注数据集登记后冻结，禁止事后按结果降低。没有代表性样本时，只能保持 shadow。多意图采用率、确认放弃率或主动拆单回退率未达阈值时，停止 confirm 后写动作和 U9–U12 扩面，只保留明确告知与已验证的只读路径。

10. 回退与数据兼容

• 每个能力可按项目降级到上一层；停止创建新任务，不删除已有计划、report、条目或审计。
• 多意图关闭后，执行中的步骤完成到安全终态或明确 cancelled；禁止回落到 legacy 后重复执行同一句写操作。
• 摘要 replace 关闭后立即使用最后一次确定性摘要；语义候选保留用于审计，不注入 prompt。
• 索引器关闭后文档提交继续成功；报告影响状态显示 index_pending，索引器的 adapter_readiness 显示 degraded；恢复后从 outbox/checkpoint 重放。
• 条目、修订、关系和索引状态的留存类别已定为合规业务记录（record），见 阶段回溯设计 §9。允许审计过的修复重放，禁止当可丢缓存删后重建。人工关系决定仍由 project_trace_edge_decisions 权威账本保存，重建不能丢失确认、拒绝或撤销。
• 下文若仍写「可重建投影、可丢弃」，以本节和回溯设计 §9 为准。
• test/main 放量需独立变更记录、环境级验收和回退演练，不因 dev 通过自动继承。

11. 任务拆分建议

实施时为每项建立独立 short-term 与 mutex：

1. fix/feature-readiness-and-lineage-authz：Foundation 0 + lineage 鉴权。
2. fix/semantic-summary-persistence：chat_summaries、watermark、授权 digest、失败语义。
3. feature/pi-reasoning-profile：Runner 纯推理协议和三个消费者迁移。
4. fix/intent-plan-production-wiring：真实 query owner、单轮接管、现有步骤内核的生产 dispatcher 和恢复。
5. feature/document-impact-report：统一提交事件、文档级影响与聊天卡。
6. feature/project-traceability-index：表、投影、项目需求/验证视图。
7. feature/trace-impact-candidates：有界多跳、候选治理和片段装配。
8. feature/semantic-summary-replace-pilot：独立授权后的替换试点。
9. U9/U10/U11/U12 各自独立任务，禁止合成一个 full 放量任务。

12. 完成定义

• 管理台准确区分配置、实际值、实现成熟度、adapter 状态和 rollout。
• 多意图不存在生产 Fake receipt；confirm 后由复用现有步骤内核的可恢复 dispatcher 执行，确认前零写。
• 摘要 PostgreSQL 持久化、授权可见集、水位、provenance、重启恢复和确定性回退闭环。
• PI 的 no-tool 由 Runner 能力强制，而非只靠 Instructions。
• 所有文档提交来源生成持久影响报告；未知、失败和无影响语义分开。
• 项目需求/风险/接口/测试清单来自统一版本化索引，可双向追踪到文档快照与块。
• 无类型正文 ID 仅形成候选；条目无键、重复键和改名均按身份契约处理，历史映射可审计。
• 助手在修改后主动展示本次修改、项目影响、相关文档、证据、不确定性和下一步建议。
• 每个候选都有持久 proposed 报告，正式提交才产生 authoritative report、stale 和通知；两条路径不混用事件。
• proposed 报告在取消、替代、冲突和基线推进后不可执行，正式提交回链 successor report。
• T2 开始前完成派生条目、候选和关系决定的留存分类：2026-09-20 定为 record（回溯设计 §9）。源文档依法清除时 tombstone 条目、保留边和决议。整份 D7 对话 ADR 仍未签，不执行物理删除。
• 常规分析有证据证明只读取命中片段；全量重建是可见、可审计的后台状态。
• 真实浏览器 + PostgreSQL + 产品 PI 长链通过，报告归档并回链 FEATURE-MATRIX。
• dev→test→main 分别批准和验收；任一失败可回退且不丢历史或重复副作用。

13. 相关链接

• Research: 2026-09-20-capability-enablement-impact-research.md
• 阶段回溯（取代候选边职责与可丢弃投影表述）: 2026-09-20-stage-backtrack-and-impact-loop-design.md
• Archived task: 2026-09-20-capability-enablement-impact-plan.md
• Feature matrix: FEATURE-MATRIX.md
• Gap matrix：本轮未新增发布 blocker；实现阶段若发现当前默认路径存在真实安全/数据破坏问题，再按证据更新。