Agent-System/.doc/ops/research/2026-09-20-capability-enablement-impact-research.md

title, created, status, confidence

title	created	status	confidence
功能启用现状与项目文档修改影响分析调研	2026-09-20	done	high_for_source_and_runtime_configuration

功能启用现状与项目文档修改影响分析调研

1. 结论

用户观察基本成立，但“已实现未启用”包含三种不同情况：已有可运行能力被关闭、只有组件或测试链路而未接入生产入口、只有设置或适配器占位。不能统一通过打开开关解决。

建议先补真实执行链路、摘要持久化和工具权限约束，再分阶段启用。文档影响分析应建立项目级、版本化的需求与关联索引，工作流作为其中的归属和筛选维度。复用现有文档账本、变更报告和可靠事件，以增量抽取和关联查询代替每次全项目全文处理。

本轮交付调研与整改方案。未修改业务代码、未启用开关、未重启容器、未操作真实会话。下文的源码风险是静态发现，不冒充已复现的事故；历史测试不冒充本轮验收。

2. 调研范围与证据等级

• 基线：本地 dev@8fdcd98；开始时工作区干净，git pull --ff-only 返回 Already up to date。调研分支 feature/capability-enablement-impact-plan。
• 核查：internal/intent、internal/app/intentflow、chat、ctxmgr、docrevision、projectworkflow、projectcontext、sysadmin、PI Runner、相关前端、三环境 Compose、Goose 迁移。
• 实时只读证据：三环境 app 容器白名单环境变量、image ID、/health、/ready；各环境 PostgreSQL BEGIN READ ONLY 元数据和聚合计数。未输出密码、业务正文或用户数据。
• 历史证据：W2/W3/W4 测试报告、Wave5 封存决策、FEATURE-MATRIX。它们说明当时测了什么，不能证明当前聊天入口已打通。
• 外部研究：NASA 需求追踪方法、PostgreSQL 16 递归查询文档，仅用于设计依据，不代表本项目满足任何外部合规认证。
• 本轮没有运行 Go/前端测试或真实 PI/浏览器验收；没有证明运行镜像与源码逐字一致。运行开关是容器实际配置，接线结论基于当前检出源码。

3. 运行环境核查

2026-09-20 本轮读取结果：

项	dev	test	main
health / ready	ok / ok	ok / ok	ok / ok
schema	53	53	52
AGENT_BACKEND	pi-agent	pi-agent	pi-agent
MULTI_INTENT_ENABLED	true	true	true
MULTI_INTENT_PLAN_TIER	legacy	legacy	legacy
U9 / U10 / U11 / U12	全 false	全 false	全 false
INTENT_V2_SHADOW / DECISION / TIER	false / false / none	同左	同左
SEMANTIC_SUMMARY_SHADOW	false	false	false
SEMANTIC_SUMMARY_REPLACE	未注入；源码默认 false	同左	同左
PI_CHANGE_REPORT_NARRATIVE	false	false	false
FAV_PUBLISHER_ENABLED / DEGRADED_READ	false / false	false / false	false / false
document_lineage 行数	10	0	10
document_change_reports 行数	487	0	0
intent_plans 行数	2	0	0
public.chat_summaries	不存在	不存在	不存在
public.chat_daily_digests	存在	存在	存在

行数包含既有测试/种子可能性，不能据此推断活跃用户、覆盖率或业务采用率。

本轮 app image ID：dev sha256:de2c8802eb544cddef157d23d8731cd66b04b85bc6b120a070e08b9b234428df；test sha256:f7ad7d2427bbca4d0f6fb3bc9128aa86de546e7d7e3f4f7ebedbbe072776d66d；main sha256:0ffe0550461c2b75c783292994d75e71083f7c20c7e4a9a52ad9e5959580c2eb。这是本机镜像标识，不是远端 registry 发布凭据。

数据库核查先尝试 count(chat_summaries) 得到 relation does not exist；随后以 to_regclass('public.chat_summaries') 在三库重新确认。internal/bizdev/service.go:115 用业务 pool 构建 ContextManager；仓库 SQL 搜索也未找到该表的建表迁移。/ready 正常不能证明这项摘要持久化可用。

4. 功能分类与启用判断

能力	当前实际完成边界	判断与建议
基础多意图识别	intent/flags.go:35 默认开；旧协调器执行有限只读组合	已启用，不应标为“全部关闭”
新多意图持久计划	表、策略、卡片、决定接口存在；生产查询 owner 是 Fake，确认后未发现 worker 调度	必须先整改，不能直接升 auto_read/confirm
U9 LLM 分段	PI proposer 组件已注入；生产未调用 ActiveSegmentProposer	需接真实聊天链路，不是单纯 flag 问题
U10 变更 / U11 治理 / U12 运行控制	flag 开后注册 DryRunAdapter	真实动作仍需实现；full 不是全功能开关
意图 V2 决策	有独立灰度 flags，运行环境均 off	与多意图计划分开验收，避免同时切两套路由无法归因
语义摘要 shadow	有 PI 实现，成功后仍服务确定性摘要	可作为第一阶段观测能力，但先补工具限制、持久化和异步隔离
语义摘要 REPLACE	明确封存未接线；true 也不替换	新实施项；需完整滚动、授权、质量、失效和回退设计
PI 变更报告叙事	有开关/Fetcher/摘要合并；输入仅统计数	接线存在但表达能力不足，先补具体差异与证据
文档修改影响	账本、报告、面板、lineage 已有	依赖覆盖窄；应扩展项目追踪索引
系统设置六项	可写白名单，但无业务消费方	管理台须显示“尚未生效”，逐项接线后开放
编制人兼任	有独立策略消费方	不随本次智能功能一并全局开启；保留项目逐文档配置和冻结职责
FAV	当前仅有限 shadow/骨架，生产消费者未放量	不纳入首批；维持独立观察窗和关闭降级读
软件项目自举受控执行	部分数据库表/allowlist/执行器仍 deferred	不因“已有表”认定可用，独立完善
D7 删除/留存治理	历史资料仍待合规决策	不与智能功能启用混合实施

4.1 多意图的具体缺口

1. internal/app/app.go:247-249 将 QueryGuard{Inner: NewFakeActionOwner()} 注入生产。intentflow/owner.go 的 Fake 返回 receipt，不查询真实业务。
2. internal/server/intent_plan_handlers.go:68-82 决定接口调用 DecidePlan 后返回。非测试 AdvanceEligible 调用只发现 intentflow/turn.go:98 自动只读路径；缺少确认后的可靠执行调度。
3. internal/chat/session.go:397-406 对新计划只清除旧 IntentPlan，忽略 planErr；后面仍走 Coordinator.Process。存在双路径处理及确认前副作用风险，须用真实聊天负例验证；本轮未制造真实副作用证明该风险。
4. internal/app/plan_owner.go:97-122 的 live starter 将 task.run 固定到 intake；turn.go:55-61 只持久化 key/digest/summary，没有完整类型化参数和目标版本，不能可靠表达“修改 A 后生成 B”。
5. U9 注入位在 app.go:141，生产 HandleTurn 仍直接使用规则 Recognize；ActiveSegmentProposer 调用只见测试。
6. intentflow/expansion.go:301-313 为 U10–U12 注册 dry-run；返回 dryrun:/validated_only:。新领域写不是“开后就可执行”。
7. 三个 Compose 已声明 PLAN_TIER。旧文档中“没有传进容器”的结论已过时，本轮不沿用。

4.2 语义摘要不仅缺一个开关

• ctxmgr/summary_flags.go:10-20、semantic_summary.go 明确 REPLACE 未接线；现有测试故意令 Replace=true 并验证叙事不变。
• ctxmgr/summarizer.go:64-115 读写 chat_summaries；数据库缺表时写错误被忽略、返回成功并存内存。因此重启持久化是前置整改，不能用内存测试当通过。
• Source、Shadow、FreshnessNote 不在现有保存 SQL 中，即使补表也需设计完整 provenance 持久化。
• MinimizeAuthorizedMessages 仅取最后 40 条、每条约 240 字符；shadow 输入没有旧摘要。直接把它赋给 Narrative 会丢更早的上下文；不能宣称覆盖全部 CoveredCount。
• chat/session.go:177-212 同步计算滚动摘要，并将当前 early 全量与旧摘要再合并；缺稳定消息水位去重契约，有覆盖计数/重复压缩风险。
• app/chatflow/chatlog.go:324 存在授权包装，但 Session 直接调用 ContextManager。旧摘要复用仅按 session_id；撤权、阶段可见范围变化后是否仍安全，必须补真实链路复核与可见集绑定。
• shadow 与服务请求同步执行，PI 默认 timeout 3 分钟（app/semantic_summarizer.go:18），Session 外层约 30 秒。开启可能增加等待；应移至可观察的后台任务并立即提供确定性结果。
• PiSemanticSummarizer 只检查输出非空，未验证返回 digest、证据引用和长度等完整质量契约。

4.3 “no-tool”目前不是运行时强约束

app/semantic_summarizer.go:64-69 与 app/pi_narrative.go:60-67 通过 Instructions 声明 zero tool，但 deploy/pi-agent/runner.mjs:151-154 固定使用 read,write,edit,tavily_search,web_search 和 approve。本轮没有验证攻击利用；源码足以证明提示词声明不等价于禁用工具。

建议增加专用纯推理请求 profile：材料直接作为输入，结构化结果通过协议返回，由服务端保存；Runner 不加载搜索扩展、不提供文件/网络工具。若底层 CLI 不支持该 profile，能力应显示 unavailable 并回退，而不是继续标记 no-tool。摘要、叙事和 U9 一并覆盖。

4.4 管理台的显示不能当作功能已生效

internal/sysadmin/features.go 返回 value/source/requiresRestart，没有 adapter readiness 或 rollout 覆盖信息。settings.go:68-87 明示六项无消费方：维护公告、只读模式、默认会话职责、任务默认自动修复、KB 默认返回数、阶段推进提醒。

因此需要拆分“配置值”“实际生效值”“实现成熟度”“失败/阻断原因”。尤其只读模式必须服务端阻断写操作，不能只让前端按钮变灰；默认会话职责不能升级授权。维护公告等低风险项可单独接线，不能把六项保存成功当作六项功能完成。

5. 修改影响分析已有什么、缺什么

现有资产	证据	复用方式与限制
快照、版本、块映射、事件、报告	docrevision/types.go:96-168；迁移 00028	唯一文档事实来源；索引不另存可独立修改的正文
变更报告面板	web/src/components/doc/ChangeReportPanel.tsx:94-165	已有摘要/影响/推荐动作；增加覆盖状态、文档名、证据定位、聊天卡复用
下游 lineage	bizdev/service.go:1169-1193	主要为 test_manager 引用 system_reqs；下游 version 写死 1，不能扩面沿用
ImpactResolver	bizdev/service.go:132-156	一跳查下游；查询错误和无关联都返回 nil，必须区分未知与无影响
风险规则	docrevision/impact.go:18、risk.go:49-54	任意 lineage 均变 stale_candidate 并升 critical；扩大关系前先分清存在依赖和实际受影响
可靠事件	app/docflow/commands.go:285-312	复用提交后事件、投影和重放；不新增第二套消息基础设施
需求/用例 JSON	squad/quality_gate_v2.go:34-101	已校验 requirements.json/test_cases.json；是工作区产物，不是需求实体数据库
上下文快照	projectcontext/service.go:167-184,216-242	来源用 DocKey、版本用 Stage，且 approved 文档全选；需改为真实快照/版本/片段
材料装配	projectcontext/service.go:126-145	截到 12 项、正文约 4000 字节；减少输入但不能证明召回完整
块业务键	docrevision/blockmap.go:13	仅覆盖 REQ-*；需要兼容 UR/RS 等并维护稳定身份

另发现 lineage GET 的权限缺口：server/project_handlers.go:280-322 只校验 URL 项目，然后接受任意 query doc_id 查询；应核验文档属于项目、逐文档可见性、关联端点可见性。当前为静态确定的缺少检查，未对真实项目做越权请求。

PI 叙事并不能补这些关系：app/pi_narrative.go:40-48 只传 SHA、风险与 hunk/impact 数量，没有具体 Hunks/Impacts。已有 BuildNarrativePromptInput 可以提供差异，但未发现生产调用。仅开启 flag 更可能得到“修改了若干处、存在若干影响”这种泛化说明。

还需统一报告可信边界：新 narrative 路径以服务端 impacts 为准；旧 ValidateChangeReportJSON 仍通过 mergeImpacts 合并模型提供的关联。新增设计应将模型推测单独列为候选，经文档定位、权限与证据校验后才进入确定关联。

6. 是否建立需求清单等表

需要建立；建议项目级统一条目索引，而不是每个工作流各建一套孤立需求表。 同一需求可以贯穿需求、设计、风险、验证多个工作流；逐工作流复制会产生重复编号、版本不一致和跨工作流断链。

建议首期三类核心表：稳定条目身份、不可变条目修订、版本化关系；再保存索引构建状态。需求清单、风险清单、接口清单、测试覆盖表是同一索引的不同视图。已有 document_lineage 保留“实际消费了哪个文档版本”的事实，条目关系解释“为什么影响哪一处”。

路线	优点	局限	建议
每次全文处理	无建模启动成本	输入随项目增长、重复成本高、结果不稳定	仅初始化/明确修复，不作常规路径
仅摘要/向量检索	查找相似内容方便	相似不等于依赖，不能可靠证明未受影响	用于补充候选
仅文档级 lineage	可快速覆盖实际引用	无条目粒度，易误报全篇影响	第一阶段复用并修版本
PostgreSQL 条目+关系+片段	版本、事务、双向查询与审计可落在现有栈	需持续维护抽取/关系质量	推荐主路线
独立图数据库/完整 GraphRAG	可支持更复杂关系探索	新基础设施、一致性/授权/运维成本	当前无规模证据，不先引入

NASA 需求管理资料强调双向追踪及需求变更影响管理，可作为需求—设计—验证关联建模的参考。NASA Requirements Management

PostgreSQL 16 支持递归 CTE 和循环检测，现有数据库可承担首期受限关系遍历。这支持“先用现有 PG”的设计选择，但不能替代本项目性能基准。PostgreSQL 16 WITH Queries

7. 预期用户体验

示例仅说明设计，不是本轮真实项目结果：用户把某需求的响应时间从 2 秒改为 1 秒，提交成功后，助手返回：

已修改《系统需求》REQ-017 的响应时间：2 秒 → 1 秒。直接相关的《性能设计》§3.2 和测试用例 TC-017 需要复核；《验收方案》通过测试追踪关系可能受影响。建议先确认实现预算，再更新测试阈值，最后复核验收标准。当前索引覆盖已提交版本，另有一个关联尚待核实。

每条结论可点开证据、旧/新版本和相关片段。明确区分“确定影响”“可能影响”“尚未覆盖”。不因一句影响说明自动修改其他文档；用户选择建议后，仍走目标文档权限、租约、版本校验和审批。

消息、文档面板和项目清单共用一个 report_id。刷新、重开、重启后仍可查阅，并显示后续处理进度。候选尚未提交时只能说“拟修改的预估影响”，不能说已经修改完成。

8. 推荐推进顺序与研究局限

1. 修复阻断：真实多意图 owner/确认调度/路由隔离、摘要表和持久化、纯推理工具隔离、lineage 权限和错误状态。
2. 快速形成用户价值：所有提交路径都产生基础影响报告，聊天主动展示；补完整差异输入后灰度启用 PI 叙事。
3. 项目需求索引：先覆盖结构化需求和用例，再扩展文档章节、风险和接口；精确关系先行，模型候选后置。
4. 多意图按 shadow → auto_read → confirm 扩面；U9/领域动作逐个接线、验收。
5. 语义摘要按 shadow → 质量评估 → 项目级替换推进，保留硬事实和确定性回退。

尚未实测：运行镜像内上述源码接线、真实浏览器旗标开启后的端到端行为、PI工具调用实际执行情况、索引规模/性能、需求关系准确率。报告中的源码缺口已足以阻止盲目放量；验收方案负责关闭这些未验证项。详见实施方案。