ADR 压缩与受控读取：完整实施计划

状态：批准的实现基线；交付覆盖和边界见验证报告。修订：第 3 版。日期：2026-09-19。

1. 最终决策与边界

保留完整决策历史，降低进入模型上下文的无关内容。五项能力分别负责：

能力	职责
context	当前任务需要读取哪些有界证据
summary	维护派生的当前决策阅读视图
consolidate	起草完整的替代 ADR，由人正式接受
archive	移动整份失效记录，不丢历史
read guard	约束支持入口的无范围读取，独立于压缩操作

默认 /adr compaction 分析全部未归档的原始 ADR，不调用模型、不重写文件、不接受决策、不移动历史。 显式选择模式才开始起草。全量检查不等于全量改写：N 份源记录可以产生 M 份新记录、若干原样保留记录和待解决项，不强迫无关决策合成一个巨型文件。

正式整合同时准备经过审阅的 CURRENT 候选稿和确定性的索引更新。所有决策变化都参与摘要失效检测，而不只是 compaction。归档独立恢复，不决定决策是否生效。运行 compaction 不改变读取门禁设置。

不做：删除历史、重编 ID、自动裁决冲突、原地改写已接受的决策实质、把 ADR 摘要当作代码符合性证明、常驻注入完整摘要、引入新模型服务或向量数据库、按年龄归档、承诺对任意 Shell/MCP/Git 通道实现隔离。

2. 已有基础与集成风险

• adr-views.ts 已限制部分关联条数和跳数，但直接匹配记录及完整响应没有统一硬预算；现有输出主要是标题、状态、路径和关系，而非决策实质。
• 迭代 context 走 adr-evolution.ts，ID/领域走另一条路径。共享证据与预算服务，同时保留迭代语义。
• adr-tool-guard.ts 是提交门禁，不是读取门禁；保持原有功能，独立实现读取策略。
• adr.ts 尚未注册 ADR 检索工具。使用平台原生工具接口，不假设 Agent 能调用用户 Slash 命令。
• 扁平与分层发现逻辑不同；两种布局都必须发现归档身份与关系，并排除生成物、临时稿和翻译镜像。
• OCP 子引用目前会回落到容器，子关系属于注释级证据。精确返回子正文不能静默把它升级成权威替代图。
• P0 必须验证真实工具参数、执行前取消、插件顺序、用户命令及原生提问回复来源、作用域与子 Agent 行为；在此之前不宣称授权或拦截已经可靠。

3. 存储、来源与发布物

docs/adr/
├── README.md
├── INDEX.md                      # 整个 ADL 的导航，包括归档入口
├── CURRENT.md                    # 当前决策的派生阅读视图
├── CURRENT.sources.json          # 来源、覆盖范围和有效性
├── <原始 ADR>.md
├── archive/                      # 可选，仅确认归档后创建
│   ├── INDEX.md
│   └── <原始 ADR>.md
└── zh/                           # 已有阅读镜像，不作为权威源记录

支持自定义根和模块根。项目根链接模块摘要，不重复复制所有模块内容；检索补充适用的系统级约束。第一版每个参与的根只使用一对 CURRENT 文件，不提前建设领域目录体系。用户已有同名文件时拒绝覆盖。

CURRENT 包含有效约束、必要理由与风险、单列的提案/冲突、覆盖范围、来源和派生视图声明。它不创设决策，也不证明实际代码状态。新替代 ADR 应能独立支持日常工作；过时实现细节和旧方案长篇比较留在历史，不全部复制到新记录。

来源清单记录：结构与生成协议版本、筛选规则、源 ID/路径/子定位/哈希、范围成员、逐项覆盖和摘要哈希。成员检测包含相关记录的新增与删除。INDEX 是确定性导航，CURRENT 是经过审阅的语义内容；生成文件不参与 ADR 编号，也不能仅因被生成就充当原始 ADR 满足治理要求。

正式 ADR、CURRENT、来源清单和索引纳入版本控制。候选稿、计划指纹、读取回执和恢复日志放在已忽略的 .ocp/。新记录身份在计划中明确并检查冲突；并发占用编号时使计划失效，不能偷偷更改已经审阅过的引用编号。

4. 选取范围与决策规则

1. 默认源集合是项目所有参与根中的未归档权威 ADR，排除镜像、生成视图和临时稿；预览明确列出根与数量。
2. 显式起草时分批完整审阅选中源正文，逐单元记录覆盖；跨批次核对共享约束和冲突。只有证据不变且来源可验证时才复用已分析结果。
3. 每份源记录有处理结论：原样保留、摘要、整合、开放/未解决或归档候选。保留独立且已经清晰的记录；普通任务仍按需检索，不默认全量处理。
4. 不隐式读取归档正文，仅为具体依赖、理由缺口或冲突定向查证并记录。关联的系统约束只是参考证据，不自动成为被替代目标。
5. accepted 是有效约束候选；提案仍是提案；rejected/deprecated/superseded 是历史证据。未知状态、歧义 ID、环、断链和矛盾都明确报告。
6. 新提案不能让旧 accepted 提前失效。整份退出必须覆盖其所有决策单元；部分子决策仍有效的 OCP 容器不得整份归档，注释关系不足以授权退役。
7. 每个整合单元映射为：保留及新位置、改变及新理由、明确退出及原因、未解决。有链接不等于有语义覆盖；未解决项阻止整份退役。
8. 保留旧 ID、决策实质、更早历史及双向替代关系。移动导致的相对链接改写必须明确，不能假称所有字节不变。

5. 命令契约：拟实现接口

5.1 核心接口

/adr compaction
/adr compaction --dry-run
/adr compaction --mode summary [--domain <slug> | --sources <id1,id2,...>]
/adr compaction --mode consolidate [--domain <slug> | --sources <id1,id2,...>] [--archive]
/adr compaction --confirm <plan-id>
/adr compaction status [<plan-id>]
/adr compaction --help

Flag	含义
--mode summary|consolidate	显式请求 AI 起草；不指定 mode 就只读分析
--domain <slug>	限定领域；仍查证适用的系统约束
--sources <ids>	精确选择未归档原始记录；找不到、歧义或已归档则报错
--dry-run	按指定范围/模式分析，不调用模型、不写文件；未指定模式时默认如此
--archive	仅用于 consolidate，将接受后归档纳入独立待确认计划，不立即移动
--style ocp|madr|nygard	新 ADR 样式，仅用于 consolidate，默认项目配置
--baseline <version>	项目编号规则需要时指定新记录基线
--iteration <id>	指定新记录迭代，不是源记录过滤条件
--confirm <plan-id>	指定计划的备用/恢复入口；默认通过原生 Ask 确认
--help	查看帮助

组合规则：

• --domain 与 --sources 互斥。
• summary 拒绝 archive、样式和新记录编号参数。
• confirm 不允许同时改变范围、模式、编号、归档动作，也不与 dry-run 组合；修改内容就重新计划。
• P4 尚未交付时，归档参数明确报错，不能静默忽略。
• 拒绝未知参数；没有权威配置/交付计划时询问基线和迭代，不自行编造。
• OCP 迭代容器不能静默占用已有命名空间；在审阅前确定实际输出数量并解决编号分配。

显式起草先展示范围、读取规模与可获得的成本估算，确认维护任务范围/成本后再调用模型。起草只产生候选稿。dry-run 的机械分析不能承诺发现所有语义重复和冲突。

配套接口：

/adr context [<ADR-ID> | --domain <slug> | --iteration <id>] [--history]
/adr check --compaction
/adr config readGuard off|warn|guard
/adr compaction archive [--sources <ids>]                  # P4：独立移动预览
/adr compaction archive restore <completed-plan-id>       # P4：逆向恢复预览

独立归档/恢复计划也使用原生 Ask 和统一执行服务，--confirm <plan-id> 作为备用/恢复入口。第一版不提供 --all（默认已全量）、--force、--delete-history、--include-archived、--unlimited。

以上替换之前的 prepare/apply 子命令草案，不同时实现两套接口。

5.2 默认通过原生 Ask 审阅确认

起草完成后展示完整审阅产物，并提供有界确认卡片：计划 ID/版本、源与新记录身份及数量、覆盖关系、实质约束变化、未解决阻断项、CURRENT/索引更新、具体可选归档移动及链接风险。卡片不能代替可查看的完整候选正文。使用经过验证的 OpenCode 原生提问机制，不另造确认通道，也不接受模型口头声称“用户同意”。

选项	行为
接受并执行	明确接受列出的新决策，并授权展示的视图、关系和归档动作
仅保存草稿	落地 proposed 新记录；不替代、不归档旧记录，也不发布接受后才有效的 CURRENT
需要修改	收集意见，修改候选稿，生成新的审阅/确认版本
取消	不应用计划；明确说明是否保留本地候选文件

summary 模式提供“发布摘要 / 需要修改 / 取消”，不暗示接受任何 ADR。有阻断问题时禁用执行选项，但仍允许查看或保存草稿。无回复、关闭或超时都不视为同意。

将可信回复绑定到项目/会话、计划版本、候选稿/来源/成员指纹、列出的决策变化和具体授权动作；写入锁内再验证。计划变化重新 Ask，重复回复不能重复应用。保存最小审计回执与恢复进度，不保存可任意重放的无限授权令牌。

正常路径是“命令 → 起草审阅 → Ask → 验证接受并自动执行”，不要求复制计划 ID、逐条运行 /adr decide 或再次执行应用命令。起草前对维护范围/费用的确认，不等于接受起草后的新决策。--confirm <plan-id> 仅用于无可用交互界面或恢复，复用相同范围与治理检查，必须明示接受效果，不能伪装成只保存草稿。

如果 P0 无法可靠确认原生提问或用户命令来源，暂停接受并提示可用的现有人工作业路径；不能用 Agent 自填 confirmed: true 或仅由模型解释的口头同意代替。

5.3 Agent 原生工具

注册 adr_context，与用户命令共享服务。输入是概览/ID/领域/迭代选择器、当前/理由/历史意图、可选子定位和续页游标；输出是证据、来源、新鲜度、覆盖/问题、可计算的未返回数量和续页入口。门禁限制到的 Agent 必须能够使用此工具。

初始可调预算：每次最多 8 个决策单元，序列化响应总计 12,000 个 Unicode 码点，包含来源、标题、警告和导航。一般关系最多 3 跳；归档正文每次最多展开 1 跳。程序可以通过元数据寻找当前后继，不必将沿途祖先正文交给模型；后继有歧义时报告而不猜测。

超长单元分成可定位片段，不静默截掉后半部分。所有选择器均受预算约束，游标绑定语料指纹。字节统计与模型相关 token 估算分开报告，字符数不是通用 token 数。系统约束和明确依赖优先于附带的同迭代关系；必要约束尚未取完时必须声明覆盖未完成。

6. 起草、接受与恢复

6.1 统一计划和审阅

确定性计划包含：选中源指纹、范围成员、候选输出、覆盖、问题、预期状态变更、新身份和可选移动计划。AI 起草本身不保证确定性；专门的按需技能分批消费证据，不全量注入系统提示，也不授予全局读取豁免。

summary 只起草 CURRENT 及来源。consolidate 起草完整 proposed 新 ADR，同时起草生效后的 CURRENT 候选稿并预览索引变化，一起审阅，不需要用户再跑一次 summary。

局部整合必须保留未参与整合的有效约束，可复用仍经验证的新鲜部分。未触及部分本身已过期时，应经批准补充证据，或明确保持整个视图过期，不能伪装成覆盖完整的全局摘要。

整合默认保留决策含义：去重和重组不得静默削弱约束。审阅报告分开列出纯整理、待解决歧义和实质变更建议。改变或退出约束必须突出展示并明确接受，不能仅以“压缩”为依据。

程序检查身份、引用、指纹、覆盖、命名空间和输出所有权；人审阅含义、充分性、改变与退出理由。新 ADR 按所选样式保留必要背景、决策、理由、后果和被拒绝方案，不需要复制完整历史。

6.2 接受不能绕过治理

原生 Ask 的“接受并执行”明确表示人工接受列出的新决策，不只是同意起草。将现有用户 /adr decide 入口与经过验证的 Ask 执行器重构为共享同一接受服务。strict 模式必须先为每份被接受的新记录写入所需决策日志，再让旧记录退役；Ask 是新增的受审计入口，不是绕过。按需落地 proposed 新记录，再应用已经授权的状态变化。驱动服务的是可信平台回复，不是模型自己填写的布尔值，起草 Agent 不能自行接受。

手动 --confirm 备用入口使用相同的明确接受契约与检查。无法验证用户来源、缺少必要审批或治理条件不满足时，报告“等待接受”与下一步，不能免除条件。新记录仍 proposed 时旧约束继续有效；“仅保存草稿”不授权以后自动接受。有效 Ask 已覆盖完整计划后，不再强制逐条接受或重复确认才能启动已授权动作。

接受与旧记录退役是一个带恢复日志的逻辑状态变更，不冒充单次文件系统原子写入。旧记录必须等覆盖它的所有新记录被接受后才能退役。需要显式扩展/组合现有单记录处理器，不能假设已有 N 对 1 批量接受能力。

读取端应识别中间不一致并报告待恢复。计划中预期且经过授权的治理状态变化可以凭回执推进；非预期正文/范围变化使计划失效。不能因为正常接受操作改变了状态，就让所有待应用计划必然失效。

6.3 状态变更后的独立发布

新 ADR 已审阅接受 + 替代关系已应用
    ├── 发布已审阅的 CURRENT 和来源，按实际状态重建 INDEX
    └── 检查并执行单独预授权的归档移动

归档成功不是当前决策发布的前提。 接受成功但未移动的旧记录在原路径仍是 superseded。如果后续移动改变路径/链接，经验证后机械更新来源和导航；若语义改变则失效并重新审阅，不能为纯路径变化暗中重新调用模型。

在项目锁内验证前置条件、暂存写入、记录恢复步骤。拒绝 CURRENT 与清单不匹配的组合。失败回执分别报告决策状态、CURRENT 发布、索引和归档状态，不能部分失败却宣称全部成功。索引反映实际文件位置，不反映尚未执行的计划位置。

已完成步骤重复执行无副作用；仍满足条件的未完成步骤可以恢复，但不得接受已变化的输入。保留用户无关修改。新决策被接受后，语义撤销必须走正常治理，不能在文件回滚时直接删除新 ADR。

7. 全局失效检测，而非仅 compaction 检测

任何相关源变化都使依赖视图失效，包括：new、接受/拒绝/废弃、supersede、子决策追加及状态/正文修改、迁移、归档/恢复、手改、新增/删除/改名、领域/范围变更、关联模块或系统约束变更。摘要展示开放提案时，提案变化也可能使它失效。

钩子提供及时反馈；读取时的成员/内容哈希检查发现钩子之外的修改。发布正确性不能只依赖修改时间。

• INDEX 是确定性视图，应适时自动重建。
• CURRENT 的新语义内容不能自动花钱起草并直接发布。
• consolidate 发布事先一起审阅过的候选稿。
• 其他变更提示 stale，允许显式刷新或定向读取原始证据。
• 清单缺失、损坏、不兼容或不匹配时，回退为当前范围的有界检索，不静默采用旧结论，也不转储全库。

如果归档失败且实际路径未变，已针对这些路径验证的 CURRENT 不必仅因失败而失效。成功移动后，需要更新来源/引用再判为新鲜。

8. 独立读取门禁与历史展开

off 保持旧访问；warn 去重提示；guard 拦截支持入口的归档正文直读和明确的无范围 ADR 正文读取/搜索。现有项目默认 off，不因 compaction 自动开启；与提交治理独立。

允许文件名发现、导航和定向活跃原文读取。全仓正文搜索包含受控文件时应缩小范围或走检索；排除这些路径的正常代码搜索仍允许。规范化根、相对路径、分隔符、符号链接与作用域，不能见到名为 archive 的目录就一律禁止。

只为验证过的工具参数实现适配器。Shell 仅识别有限的直接读、搜索和明显循环；任意脚本、Git 历史、MCP 和未接入通道是明确的局限，不将正则识别宣传为安全隔离。

阻断发生在支持工具输出正文之前，回执提供可调用的检索参数；日志或安全包装异常不能吞掉阻断。配置或工具作用域出错时报告实际降级，不编造 deny-all 策略，也不假称防护完整。

历史链接不是递归读取指令。当前查询旧 ID 时优先明确的已接受后继；理由/历史查询需要具体目标和证据缺口，进一步深入通过有界续页。证据足够就停止，不用满额度。缺失/过期证据和冲突允许定向调查，完整审计是明确范围的分批任务。

模型填写的理由不能证明“必要”，更不是用户授权。维护回执限定任务/会话并到期，不赋予无限读取。不能可靠识别用户授权时不实现自动豁免。工具统计累计证据、去重并对重复读取告警，但不承诺跨任意工具的会话总 token 硬上限。

9. 可选归档与逆向恢复

计划列出源/目标路径、入站/出站相对链接、翻译来源、索引变化、冲突、外部链接风险和逆向操作。整份退役、子状态一致、必要后继可解析、没有影响移动的未解决问题才可归档；时间久远不是依据。

只执行用户确认的具体计划，并重新检查所需接受状态与路径/内容。源变化、目标冲突、必需链接无法修复或外部风险未确认时停止。外部链接不保证全部修复。移动有日志，验证身份、决策实质、状态和引用，失败恢复不重置整个工作区。

归档记录在扁平、分层布局下都参与全局编号、完整性、图、history、引用及支持的迁移。不兼容归档的迁移必须显式拒绝。新建记录仍进活跃根。归档与经过测试的逆向恢复一起交付；恢复位置不恢复旧决策效力。

10. 代码职责

位置	责任
adr-engine.ts、类型及适配器	源分类、归档身份、精确证据单元，保持样式语法
新 adr-context.ts	筛选、预算、游标、新鲜度和证据输出
adr-views.ts、adr-evolution.ts	保留视图语义，复用有界输出
新 adr-compaction.ts	分析、起草契约、审阅发布、整合状态与恢复
新 adr-read-guard.ts	读取策略，独立于提交门禁
后续 adr-archive.ts	移动/恢复计划及执行
adr.ts、命令/配置/界面	原生工具、钩子组合、参数验证、帮助
按需 context/compaction 技能	工作流，常驻只保留短入口
国际化、双语文档和测试	公共行为与实际注册路径覆盖

沿用作用域、导出和项目配置契约，不为本功能额外建设通用工作流框架。

11. 分阶段交付

阶段	交付	出口门槛
P0	运行时矩阵、状态/存储契约、proposed 架构 ADR	验证真实取消、用户/Ask 回复来源、作用域、样式往返和编号
P1	共享有界检索工具/命令	全选择器受限，系统约束和缺失/过期视图可处理
P2	摘要计划、审阅发布、全局失效	覆盖普通变更路径，并发与中断恢复通过
P2b	正式整合及 CURRENT/INDEX 更新	N 对 M 覆盖及 Ask 审计接受成立，无归档或归档失败不阻断正确现状
P3	独立的三档读取门禁	支持入口输出前拦截，回查可达，提交门禁不回归
P4	可选预授权归档及恢复	两种布局身份/链接/迁移正确，中断可恢复
P5	双语文档、基准与发布检查	自动化和真实会话测试通过，成本与局限公开

P1/P2/P2b/P3 是第一批功能范围，P4 独立交付，不阻塞 token 优化。实施前记录 proposed 架构 ADR，基线/迭代取自批准的交付计划，不自行接受。P0 未验证前，授权和门禁细节是待验证风险，不是已经完成的保证。

12. 测试、测量与验收

12.1 自动化用例

• 语义：三样式、OCP 混合子状态、提案、未知/矛盾状态、环/断链、歧义 ID、已接受与待决后继、完整与部分替代。
• 范围：全部未归档根、领域/精确筛选、参考不升级为目标、镜像/生成物排除、未知领域、原样保留、N 对 M 分组、跨批次约束核对。
• 命令：默认/dry-run 零模型调用且零写入；显式模式只起草；组合与未知参数；编号冲突；confirm 不扩大授权范围；未交付功能报错。
• Ask：整合四选项、summary 专用文案、完整候选可访问、阻断时不可执行、取消/超时、伪造确认、回复过期/重放/跨会话、strict 日志与 /adr decide 一致、无强制二次确认、部分失败恢复不扩大授权。
• 检索：大量匹配、长正文/标题、中英文、完整响应预算、归档 1 跳与一般 3 跳区分、过期游标、精确子定位、当前后继优先、覆盖不足可见。
• 新鲜度：全部普通变更和手改/新增/删除/迁移；局部保留未触及有效约束；无未授权收费刷新；不一致清单安全降级。
• 整合：草稿/拒绝不影响旧效力；改变/退出需审阅；预期治理变更与外部改动区分；部分新记录接受；状态中断；编号被占用。
• 发布：新 ADR 与 CURRENT 一起审阅；索引反映实际状态；校验哈希/所有权；归档失败不阻塞独立视图发布；成功移动只改路径时不重跑模型；待办可幂等恢复。
• 门禁：真实工具参数、文件名/正文搜索区分、已知 Shell 情况及绕过、日志异常、作用域/子 Agent、模式切换、无关文件不受影响、工具不可用降级和重复读取告警。
• 归档：自定义/模块根、两种布局、翻译与双向链接、冲突、符号链接/根外路径、外链警告、中断/恢复、迁移兼容、归档 ID 不重用。

通过现有入口运行全部 tests/test-adr-*.ts 和新增检索/压缩/门禁/归档测试、类型检查及结构检查。真实 OpenCode 会话验证工具注册、取消、命令/提问回复来源、全部 Ask 选项、技能加载、无全库注入、接受与恢复；不能只靠单元测试。

12.2 成本与质量测量

临时生成 10 / 100 / 1,000 份记录，包含长记录，不提交大数据。分别测首次起草成本、后续任务证据字节/字符、可用时的模型相关 token 估算、相关约束召回、未覆盖读取通道及误拦截。

同任务对比现有“context 加定向原文”流程，而非只和刻意全读比较。首次压缩费用单列，不预先承诺任意节省比例。

最终验收：历史身份保留、约束不静默遗漏、输出有界、过期可识别、支持入口拦截且回查可用、索引确定性正确、语义产物经过审阅、发布/移动可恢复、旧默认和提交治理不回归。

13. 回滚与审批

读取策略独立关闭。停用只属于本功能的派生物后继续有界原文检索。删除归档发现能力前先恢复文件位置，不能丢失历史可发现性。已接受新决策的语义回滚是新的治理动作，不是文件回滚。

审批点：修订计划；P0 结论和 proposed ADR；代表性摘要/整合质量；实际门禁覆盖；独立物理移动计划。本文本身不修改运行时行为。

14. 设计评分

这是对第 3 版方案的自评，不是实现测试成绩，也不是独立审计结论。

维度	满分	得分	剩余不确定性
正确性与可追溯性	30	27	语义忠实度、多记录状态恢复仍需样例和运行时验证
上下文效率	20	17	首次起草成本、重复读取和分批质量尚未测量
可维护性与范围控制	20	17	恢复、多样式整合仍有不可忽略的复杂度
可验证性	20	18	验收明确，但真实运行覆盖尚未验证
易用性	10	8	编号、等待接受和部分失败交互仍需验证
总分	100	87	可以进入 P0，不代表可以直接发布

第 3 版补齐默认原生 Ask 审阅接受、备用命令与恢复、保留语义的审阅要求；没有新增实测证据，评分不变。统一后的计划清理了命令变体冲突，默认改为只读分析，将 CURRENT/INDEX 纳入整合发布，失效检测覆盖普通决策修改，归档与读取门禁解耦。后续加分必须来自证据：真实钩子/接受链路、中断恢复、内容覆盖质量、误拦截率和端到端 token 成本，而不是继续增加设计条目。