@sakanano-moe/agenthelm 6.5.3 → 6.6.0

package/runtime/plugins/opinion-manager/references/versioning.md

@@ -0,0 +1,263 @@
+# Opinion 变体、版本与个人 Profile
+
+## 身份与选择
+
+- 模板系列 `family` 标识用途，例如 `work-email`。
+- 模板变体 `variant` 标识同一用途下的平行偏好，例如 `formal-report`。各个变体维护独立版本。
+- 模板引用为 `family/variant@VERSION`，规则引用为 `ID@VERSION`。版本使用无前导零的 `major.minor.patch`。省略版本、使用 `latest` 和版本范围都会被拒绝。
+- 同一个系列在一份 Profile 中只能选择一个变体和版本。不同系列可以组合。
+- 原子规则包含 `id`、`version`、`slot`、`title`、`level`、`scopes`、`text`。`level` 为 `required` 或 `preferred`。
+- `slot` 表示一项行为选择。同一个有效 slot 出现两条规则会终止生成；相同规则和版本会去重，相同规则的不同版本会报告冲突。用于不同场景的独立选择应分配不同 slot。
+- 模板包含 `family`、`variant`、`version`、`name`、`description`、`scopes` 和精确规则引用数组 `rules`。模板名称与说明用于帮助用户选择。
+
+本文中的示例名称说明数据格式；实际可用规则、系列、变体与版本以 `catalog` 输出为准。随包候选目录说明见 `../catalog/README.md`，全部模板均为可选择的偏好。
+
+## 文件与版本
+
+每个规则和模板版本分别保存在规则目录：
+
+- `rules/ID/versions/VERSION.json`
+- `templates/FAMILY/VARIANT/versions/VERSION.json`
+
+每个项目的个人 Profile 保存在 `.opinion/profiles/ID/versions/VERSION.json`。Profile 包含精确模板引用、直接选择的规则、完整来源快照、个人 overrides、自定义正文及派生来源指纹。旧版本保留。项目根目录保存完整的 `OPINION.md` 和 `opinion.lock.json`。
+
+锁定文件包含完整 Profile 快照、Profile 指纹、正文指纹和渲染格式版本。运行 Agent 时读取完整正文；Profile 声明了分层加载时，可以按「分层加载」一节读取核心规则与规则束，两种方式得到的规则文字逐字一致。重建和核验不需要访问模板仓库或其他项目的本机路径。相同 Profile 在相同渲染格式下生成相同正文，正文没有变化的生成时间。
+
+指纹使用 SHA-256：JSON 使用 UTF-8、按字段名称排序、无额外空格的规范序列化；正文使用原始 UTF-8 内容。调整 JSON 排版不会改变内容指纹。
+
+`publish` 和 `profile` 只创建新版本，重复发布完全相同内容返回 `unchanged`；相同身份与版本的不同内容被拒绝。工具不会修改已发布文件。使用中发现已锁定来源被人工修改时，升级检查和修订都会终止。
+
+版本含义：
+
+- patch：拼写、名称或说明等不改变行为的修订。工具检查规则正文、等级、适用范围和 slot；模板检查有效规则与适用范围。
+- minor：符合既有目标的行为完善或新增规则；发布者必须审查兼容性，用户确认后才能采用。
+- major：改变既有目标、删除约束或引入不兼容行为；发布者必须说明适用条件并重新验证。
+
+任何版本更新都需要预览与确认。工具可以校验结构和依赖；行为兼容性需要内容审查。
+
+## 通用命令约定
+
+以下命令在完整分发仓库根目录执行，要求 Python 3.11 及以上。独立安装插件时，将示例中的 `plugins/opinion-manager/runtime/opinion_manager.py` 替换为该插件实际目录下的 `runtime/opinion_manager.py`，将 `plugins/opinion-manager/catalog` 替换为该插件的 `catalog` 目录。`/path/to/project` 必须已经存在。使用用户明确指定的私有目录保存个人内容，公开仓库中不得保存个人 Profile、来源文件或私有规则目录。
+
+所有写入默认预览。预览 JSON 包含 `confirmation_sha256`；向用户展示完整内容并取得确认后，在相同命令后追加 `--apply --confirm SHA256`。用户批准的是规则内容，Agent 负责传递指纹。任何相关内容在批准后改变，都必须重新预览。
+
+查看公开规则目录：
+
+```bash
+python3 plugins/opinion-manager/runtime/opinion_manager.py catalog \
+  --catalog plugins/opinion-manager/catalog --output json
+```
+
+目录为空时，使用自定义生成或跳过配置。
+
+## 自定义生成
+
+读取用户已有说明，整理后展示完整规则。用户确认后使用文件编辑工具保存到用户指定的私有文件。已有规则文件可以直接使用，无需重复复制。
+
+预览个人 Profile：
+
+```bash
+python3 plugins/opinion-manager/runtime/opinion_manager.py profile \
+  --project /path/to/project --id private.my-opinion --version 1.0.0 \
+  --custom-file /path/to/confirmed-rules.md
+```
+
+将 Profile 预览的 profile 对象保存为项目私有候选 JSON，正式 Profile 此时尚未保存。先以候选路径预览完整正文与锁，再集中确认内容：
+
+```bash
+python3 plugins/opinion-manager/runtime/opinion_manager.py compose \
+  --project /path/to/project \
+  --profile /path/to/private-preview/profile.json \
+  --output json
+```
+
+两份预览内容确认后，写入前重新核对两项指纹。先用 Profile 指纹保存正式 Profile，再把 compose 路径换成正式 Profile，用 compose 指纹保存正文与锁；完整步骤见 [首次使用说明](onboarding.md)。原有正文包含实际规则时，先读取并纳入 Profile，使用 `--replace` 重新预览。初始化器原样生成的空白占位内容可以直接替换。
+
+最后核验：
+
+```bash
+python3 plugins/opinion-manager/runtime/opinion_manager.py verify --project /path/to/project
+```
+
+后续自定义内容修订使用 `profile --from-profile <原文件> --id <相同编号> --version <新版本> --custom-file <完整的新自定义正文>`。`--custom-file` 替换自定义段落；新文件必须包含仍需保留的全部自定义要求。
+
+## 简单模式与复杂模式
+
+已有批准的版本化模板时，`profile` 使用 `--catalog <目录>`，并重复传入 `--template family/variant@VERSION`。预览每个系列的变体与说明，用户选择后展示最终合并内容。
+
+复杂模式可以重复传入 `--rule ID@VERSION` 逐条选择。也可以选择完整模板，然后使用 `--overrides-file <JSON文件>` 停用其中未确认的条目。问答由 Agent 交互完成，未确认的推荐不进入 Profile。
+
+overrides 是规则编号到内容的对象：值为 `null` 表示停用；值为对象时必须完整包含 `title`、`level`、`scopes`、`text`。只能修改当前来源中的规则，不能修改其编号和 slot。新增个人原子规则应在私有目录独立发布后通过 `--rule` 引入；个人自定义段落也可以表达新的要求。
+
+多个模板发布版本都保留时，`catalog` 展示全部版本和变体；工具不会替用户选择最新版本。
+
+## 首次配置的选择与确认
+
+首次只提供直接用模板、选择部分条目、从空白开始三个主入口，另可基于已授权记忆提出候选。使用 [首次使用说明](onboarding.md) 的流程，避免提前展开偏好问卷。
+
+Profile 和 compose 可在正式保存前各自预览。用户一次确认完整正文、来源、个人修改、差异与拟保存内容；Agent 分别使用两项实际返回指纹。写入前重新预览核对，内容变化重新审阅；未解决冲突和 blocked 状态不得写入。两次写入独立保护，不保证系统事务。
+
+默认模板只作为预览建议，确认前不生效。用户选择部分条目时保留精确模板引用并通过 overrides 停用；直接原子规则的 Profile 仅追踪原子规则更新。每个系列只选一个变体，slot 冲突须集中裁决。
+
+Agent 为适用范围与候选含义做判断；scopes 只提供元数据。工具不替 Agent 判断任务属于哪个场景，不检索记忆，也不在后台自动晋升；候选与使用次数可以用「候选、灰度与使用记录」一节的命令记账，裁决始终来自用户；Profile 声明分层加载后，工具只按用户确认的声明切分正文，并核对 Agent 声明的交付信号。新观察只有用户确认后才能形成新规则版本。用户从空白开始时不建立空版本，已有规则保持原样。
+
+## 分层加载
+
+规则较多时，可以在 Profile 中声明哪些模板系列始终读取、哪些在任务命中时再读取。声明是 Profile 的一部分，与规则一样经过完整预览、用户确认和指纹锁定；没有声明的 Profile 保持完整读取，行为与此前版本相同。
+
+声明文件是一个 JSON 对象，通过 `profile --loading-file <文件>` 整体写入：
+
+```json
+{
+  "core": ["baseline"],
+  "signals": {
+    "artifact": ["report", "email", "other"],
+    "activity": ["rule-maintenance", "none"]
+  },
+  "bundles": [
+    {
+      "family": "work-email",
+      "trigger": "撰写或审查对外邮件",
+      "exclude": "只是在回复中引用邮件内容",
+      "routes": [{"artifact": ["email"]}]
+    }
+  ]
+}
+```
+
+- `core` 列出始终读取的模板系列。直接选择的原子规则、用户自定义段，以及没有出现在声明中的模板系列，同样始终读取；新增模板不会因为漏登记而被跳过。
+- `bundles` 列出按需读取的模板系列。`trigger` 与 `exclude` 是给 Agent 的适用与不适用说明，会原样出现在索引中。
+- `signals` 是交付信号词表，`routes` 把信号映射到规则束：一条路由内的所有键都命中时该路由成立，任一路由成立即要求读取该规则束。
+- 一条规则同时属于常驻系列和按需系列时归入常驻。带声明的 Profile 使用 `schema_version` 2.1，旧版本工具会拒绝读取并给出明确错误；不带声明的 Profile 仍为 2.0，指纹不变。
+
+修订时未提供 `--loading-file` 则沿用原声明；`--remove-loading` 移除声明并恢复完整读取。移除了声明中引用的模板系列时，必须同时提供新的声明文件。
+
+读取与核对使用只读的 `context` 命令：
+
+```bash
+python3 plugins/opinion-manager/runtime/opinion_manager.py context core --project /path/to/project
+python3 plugins/opinion-manager/runtime/opinion_manager.py context bundle work-email --project /path/to/project
+python3 plugins/opinion-manager/runtime/opinion_manager.py context index --project /path/to/project
+python3 plugins/opinion-manager/runtime/opinion_manager.py context check --project /path/to/project \
+  --signal artifact=email --loaded work-email
+```
+
+- `core` 输出常驻规则、自定义段和规则束索引；`bundle` 输出指定规则束；`index` 以 JSON 给出各部分的规则数与字节数。
+- `check` 由 Agent 在交付前声明本次交付的信号和已读取的规则束，工具返回应读取与缺失的规则束。缺失时退出码为 1。信号必须取自词表。
+- 每次调用先核对锁与正文；核对失败、Profile 没有声明、或 Project Profile 的 `opinion.loading_mode` 设为 `full` 时，命令返回 `fallback`，调用方改为完整读取 `OPINION.md`。前者退出码为 2，后两者为 3。
+- 保存前可用 `context core --profile <候选 Profile>` 预览切分结果，此时不读取项目锁。
+
+判断任务属于哪个场景、声明哪些信号，始终由 Agent 负责；判断不清时一并读取。维护规则本身的任务读取完整正文。
+
+## 候选、灰度与使用记录
+
+`lifecycle` 命令在项目内的私有目录保存候选、证据快照、人工裁决和灰度使用记录。它只记账，不写 `OPINION.md`、规则目录或 Profile；每个项目各自维护状态，互不引用。
+
+```bash
+python3 plugins/opinion-manager/runtime/opinion_manager.py lifecycle queue --project /path/to/project --store .opinion/lifecycle
+python3 plugins/opinion-manager/runtime/opinion_manager.py lifecycle status --project /path/to/project --store .opinion/lifecycle
+python3 plugins/opinion-manager/runtime/opinion_manager.py lifecycle event --project /path/to/project --store .opinion/lifecycle --file 项目内事件.json
+```
+
+`event` 默认只预览，返回完整状态变化与 `confirmation_sha256`；追加 `--apply --confirm <指纹>` 才写入。指纹只核对操作完整性，`human_confirmed` 必须来自用户原话。事件与证据文件必须位于项目内，证据在写入时保留不可变副本；原文件之后可以继续增长，副本被改动则阻断后续操作。
+
+事件的 `kind` 与字段：
+
+1. `capture`：`id`、`content`（完整的 `title`、`text`、`scopes`）。同一编号的内容不可修改，修订使用新编号。
+2. `observe`：`id`、`occurrence`、`validation`（`pending`、`passed`、`failed`）、`fixture`。
+3. `presented`：`id`、`content_sha256`，证据须证明完整内容已展示给用户。
+4. `decision`：`id`、`decision`（`accepted`、`rejected`、`held`）、`human_confirmed: true`、`content_sha256`。`accepted` 只允许据此准备 Profile。
+5. `adopt`：`human_confirmed: true`、当前 `profile_sha256`。先通过 `verify`，随后该 Profile 版本记为灰度。
+6. `use`：`occurrence`、`rules`（当前 Profile 的精确规则引用）、`passed`、`user_changed`、`fixture`。可选字段：
+   - `results`：为每条规则给出 `passed`、`not-applicable` 或 `violated`；
+   - `loaded_bundles`：本次读取的按需规则束；
+   - `routing_miss`：本应读取却没有读取的规则束；
+   - `date`：`YYYY-MM-DD`，用于显示规则最近一次使用。
+7. `formalize`：`human_confirmed: true`、当前 `profile_sha256`。只改变上线标签，不改规则正文。
+
+计数规则：
+
+- `occurrence` 是项目内工作记录的相对路径，按前两级目录归为一个独立场景，同一任务的多个阶段只计一次。默认接受 `tasks`、`cases`、`reviews`、`projects`、`journal` 五个顶层目录，可用 `--occurrence-root` 改写。
+- `fixture: true` 的记录不计入任何成熟度。
+- 候选每新增一次独立真实发生次数 n，推荐信用增加 n/(n+1)，达到 1 时标记待推荐，展示后扣 1。出现 `failed` 的候选显示为待处理。这是默认参数，没有经过大量使用验证。
+- `use` 未通过、用户改动了结果、或存在 `routing_miss` 时记为阻断；有阻断的版本不能转正式，须在新版本中解决。
+- 至少两个独立的真实成功使用且无阻断时，`status` 标记 `ready_for_review`。它只表示可以提交复盘，不会自动转正式。
+
+`status` 在当前正文通过核验时附带覆盖视图：每条规则的独立成功使用次数、违反次数与最近使用日期，从未使用的规则；Profile 声明了分层加载时，还包括每个规则束被读取和实际用到的次数、漏读次数，以及从未用到的规则束。复盘时据此判断「正式」覆盖到了哪些规则。
+
+同一 Profile 编号发布新版本后，旧版本的使用记录在其全部规则指纹未变时沿用到新版本，并计入独立成功使用次数；规则被修改或个人修订后，相关记录不再沿用。沿用需要读取旧版本的 Profile 文件并核对指纹，默认位置为项目的 `.opinion/profiles`，可用 `--profiles-root` 指定；找不到或指纹不符时不沿用，并在 `not_carried` 中列出。旧版本的阻断不沿用，但违反记录仍可在覆盖视图中看到。
+
+`queue --titles` 只输出尚未裁决候选的标题与适用范围，便于在普通任务中留意是否出现了对应情形；候选全文、证据与次数只在维护规则时展开。
+
+## 私有发布与公开发布
+
+用户维护自己的版本化规则时，先创建私有规则目录，再使用文件编辑工具准备完整 JSON 文件，参考 [规则格式](rule.schema.json) 与 [版本化模板格式](versioned-template.schema.json)。禁止把个人内容写入本仓库。
+
+```bash
+python3 plugins/opinion-manager/runtime/opinion_manager.py publish \
+  --catalog /path/to/private-catalog --file /path/to/release.json
+```
+
+先发布模板依赖的精确规则版本，再发布模板。发布模板时检查所有依赖和内部 slot 冲突。
+
+公开目录发布还需要 `--public-approved`。使用此标志前必须执行 Skill 中的公开准入检查、展示待公开文件的全部内容并取得用户明确同意。标志本身不能代替用户的授权。公开目录只接收逐文件批准的规则、模板及说明；审批记录、私有来源映射、个人 Profile、锁和运行日志不能随目录复制到公开包。
+
+## 修订、派生与升级
+
+只读查看当前变体的可用新版本：
+
+```bash
+python3 plugins/opinion-manager/runtime/opinion_manager.py updates \
+  --catalog /path/to/catalog --profile /path/to/current-profile.json
+```
+
+模板内部规则由模板版本精确选择。模板依赖出现新的规则版本时，需要模板发布者发布新的模板版本；`updates` 显示当前模板和直接选择的规则的升级候选。
+
+预览升级：
+
+```bash
+python3 plugins/opinion-manager/runtime/opinion_manager.py profile \
+  --catalog /path/to/catalog --project /path/to/project \
+  --from-profile /path/to/current-profile.json \
+  --id private.my-opinion --version 1.1.0 \
+  --template FAMILY/VARIANT@VERSION
+```
+
+同系列的新选择替换原选择，其他系列、直接规则和自定义内容继续保留。不同变体之间也可以通过同一命令切换。移除整项选择使用 `--remove-template FAMILY` 或 `--remove-rule ID`；模板内部的单条规则通过 overrides 停用。
+
+私有派生使用独立 Profile 编号，传入 `--from-profile` 并指定新的 `--id` 与版本。派生记录保留原 Profile 编号、版本和指纹；个人 overrides 归属自己的 Profile，公开来源保持原样。
+
+升级对每条个人 overrides 比较三个状态：当前来源快照、个人有效内容、新来源内容。上游改变行为且个人内容存在不同选择时，预览包含完整 `base`、`local`、`upstream`；`unresolved` 非空时禁止保存。
+
+用户确认冲突处理后，通过 `--resolutions-file` 提供规则编号到 `keep-local` 或 `use-upstream` 的映射；或者通过 `--overrides-file` 明确指定完整的新个人内容。处理文件由文件编辑工具写入。上游删除规则时，明确保留的个人规则继续留在 Profile 内。
+
+查看两个已经保存的 Profile 差异：
+
+```bash
+python3 plugins/opinion-manager/runtime/opinion_manager.py compare \
+  --from-profile /path/to/old-profile.json --to-profile /path/to/new-profile.json
+```
+
+修订可先预览新 Profile 与 compose，再集中确认完整结果；两份工具指纹分别用于保存。升级检查、Profile 预览和 Profile 发布都不会直接改变 `OPINION.md`。
+
+## 人工编辑与写入中断
+
+人工编辑的正文继续作为环境的有效内容。`verify` 会报告正文与锁定文件的差异，`compose` 会保护当前文件。
+
+处理步骤：完整读取当前正文；整理用户保留的规则并纳入新 Profile；展示新正文与当前正文的差异；取得用户确认；使用 `--accept-current <当前正文SHA256>` 重新预览并确认写入。指纹可以用 `sha256sum /path/to/project/OPINION.md` 读取。错误指纹不会解除保护。
+
+正文和锁定文件分别使用同目录临时文件原子替换。操作系统中断可能造成两个文件不同步；工具不会声称这种状态已通过核验。读取当前两份文件并确认目标 Profile 后，采用相同的显式当前正文确认流程修复。工具不使用 Git 恢复项目文件。
+
+正文文件缺失且锁定文件完整时，可以用原锁定 Profile 预览并重建完全相同的正文。先恢复原版本的核验结果，再进行升级。
+
+## 验收与实际使用
+
+1. 运行本插件测试：`python3 -m unittest discover -s plugins/opinion-manager/tests -v`。测试在被 Git 和安装器忽略的 `__pycache__/opinion-test-work/` 中创建独立真实文件，使用无个人含义的测试标签。
+2. 在独立私有项目使用自定义 Profile，检查预览没有写入；确认后检查三种文件以及 `verify` 结果。
+3. 在独立私有规则目录检查同系列两个变体、同变体两个版本的展示与精确选择；检查不同系列的组合和 slot 冲突。
+4. 检查 `updates` 只报告候选，旧 Profile 继续生成相同正文；离开规则目录仍可使用 Profile 重建。
+5. 检查个人 overrides 与上游新版本产生三方冲突，未确认时保存被拒绝；确认保留个人内容或采用上游内容后核验通过。
+6. 人工修改正文，确认 `verify` 报告差异且 `compose` 保留原文件；按导入流程生成新版本后再次核验。
+7. 用户确认整个流程后，分别整理生活项目与工作项目的私有规则；每个项目保留一份包含全部适用要求的完整正文。公开模板须单独通过内容审批。
+
+本版本管理已经确认的规则。Agent 可根据已授权记录提出私有候选，用户确认后才发布新版本；候选次数、灰度使用与覆盖情况由 `lifecycle` 命令在项目私有目录记账，工具不会自动晋升候选或把灰度版本转为正式。

package/runtime/plugins/opinion-manager/runtime/constants.py

@@ -0,0 +1,7 @@
+KNOWN_PLACEHOLDERS = (
+    '# 项目 Opinion 覆盖层\n\n尚未配置 Opinion。\n\n使用 `opinion-manager` 选择直接用模板、选择部分条目或从空白开始；也可基于已授权记忆提出候选。完整预览经用户确认后生效，个人内容只写入当前项目。\n',
+    "# 项目 Opinion 覆盖层\n\n尚未配置 Opinion。\n\n"
+    "使用 `opinion-manager` 选择自定义生成、已批准模板组合、逐条引导或跳过。"
+    "公开模板目录可以为空；用户提供的内容只写入当前项目，禁止复制进公开模板。\n",
+    "# 项目 Opinion 覆盖层\n\n尚未配置 Opinion。\n",
+)

package/runtime/plugins/opinion-manager/runtime/context.py

@@ -0,0 +1,180 @@
+"""按 Profile 中用户确认的加载声明切分完整正文；只读，不写任何文件。"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+import versioned
+
+
+FALLBACK = "完整读取项目根目录 OPINION.md"
+PROJECT_PROFILE = Path(".agents") / "moe.sakanano.agent-pack" / "project.json"
+DIRECT = "(direct)"
+EXIT_OK, EXIT_MISSING, EXIT_ERROR, EXIT_FULL = 0, 1, 2, 3
+
+
+class FullReading(RuntimeError):
+    """当前契约本身要求完整读取，调用方按 fallback 执行即可。"""
+
+
+def project_mode(root: Path) -> str:
+    path = root / PROJECT_PROFILE
+    if not path.is_file():
+        return "tiered"
+    mode = versioned.read_object(path).get("opinion", {}).get("loading_mode", "tiered")
+    if mode not in ("tiered", "full"):
+        versioned.fail(f"Project Profile 的 opinion.loading_mode 必须为 tiered 或 full：{mode!r}")
+    return mode
+
+
+def load(args: argparse.Namespace) -> tuple[dict[str, Any], dict[str, Any] | None]:
+    """返回 Profile 与锁；使用候选 Profile 预览时锁为 None。"""
+    if args.profile is not None:
+        profile, lock = versioned.load_profile(args.profile), None
+    else:
+        if args.project is None:
+            versioned.fail("context 需要 --project 或 --profile")
+        root = versioned.safe_path(args.project)
+        versioned.verify_project(root)
+        lock = versioned.read_object(root / "opinion.lock.json")
+        profile = lock["profile"]
+        if project_mode(root) == "full":
+            raise FullReading("Project Profile 设为完整读取")
+    if "loading" not in profile:
+        raise FullReading("当前 Profile 未声明分层加载")
+    return profile, lock
+
+
+def partition(profile: dict[str, Any]) -> dict[str, Any]:
+    """把每条有效规则分到唯一的模板系列；常驻系列优先，未登记的系列按常驻处理。"""
+    loading = profile["loading"]
+    rules = versioned.effective_rules(profile)
+    routed = [bundle["family"] for bundle in loading["bundles"]]
+    templates = [(source["ref"], source["ref"].split("/")[0], source["value"]) for source in profile["sources"]["templates"]]
+    unlisted = [family for _, family, _ in templates if family not in loading["core"] and family not in routed]
+    always = set(loading["core"]) | set(unlisted)
+    assigned: dict[str, str] = {}
+    for wanted in (True, False):
+        for _, family, value in templates:
+            if (family in always) is not wanted:
+                continue
+            for ref in value["rules"]:
+                identity = versioned.parse_ref(ref, "rules")[0]
+                if identity in rules:
+                    assigned.setdefault(identity, family)
+    groups: dict[str, list[str]] = {}
+    for identity in rules:
+        groups.setdefault(assigned.get(identity, DIRECT), []).append(identity)
+    return {
+        "rules": rules, "groups": groups, "unlisted": unlisted,
+        "refs": {family: ref for ref, family, _ in templates},
+        "names": {family: value["name"] for _, family, value in templates},
+        "always": [family for family in (*loading["core"], *unlisted, DIRECT) if family in groups],
+        "bundles": [bundle for bundle in loading["bundles"] if bundle["family"] in groups],
+    }
+
+
+def group_text(profile: dict[str, Any], parts: dict[str, Any], family: str) -> str:
+    return "\n\n".join(versioned.render_rule(profile, parts["rules"][identity]) for identity in parts["groups"].get(family, []))
+
+
+def core_text(profile: dict[str, Any], lock: dict[str, Any] | None) -> str:
+    parts = partition(profile)
+    origin = f"正文指纹：`{lock['opinion_sha256']}`" if lock else "候选 Profile 预览，尚未生效"
+    lines = ["# Agent Opinion 核心规则", "", f"Profile：`{profile['id']}@{profile['version']}`；{origin}。",
+             "本输出是完整正文的只读切片，始终适用。场景规则束见文末索引，命中时再读取。"]
+    for family in parts["always"]:
+        lines.extend(("", group_text(profile, parts, family)))
+    if profile["custom"]:
+        lines.extend(("", "## 用户自定义规则", "", profile["custom"]))
+    lines.extend(("", "## 规则束索引", "", "任务命中触发条件时用 `context bundle <系列>` 读取对应规则束；判断不清时一并读取。"))
+    for bundle in parts["bundles"]:
+        family = bundle["family"]
+        lines.append(f"- `{family}`（{parts['names'][family]}，{len(parts['groups'][family])} 条）：{bundle['trigger']}。不适用：{bundle['exclude']}。")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def resolve_bundle(parts: dict[str, Any], name: str) -> str:
+    family = {ref: family for family, ref in parts["refs"].items()}.get(name, name)
+    if family not in {bundle["family"] for bundle in parts["bundles"]}:
+        versioned.fail(f"未知的按需规则束：{name}")
+    return family
+
+
+def bundle_text(profile: dict[str, Any], names: list[str]) -> str:
+    if not names:
+        versioned.fail("bundle 需要至少一个模板系列或精确模板引用")
+    parts = partition(profile)
+    lines: list[str] = []
+    for name in names:
+        family = resolve_bundle(parts, name)
+        lines.extend((f"# 规则束 `{parts['refs'][family]}`", "", group_text(profile, parts, family), ""))
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def index_view(profile: dict[str, Any], lock: dict[str, Any] | None) -> dict[str, Any]:
+    parts = partition(profile)
+
+    def entry(family: str) -> dict[str, Any]:
+        return {"family": family, "ref": parts["refs"].get(family), "name": parts["names"].get(family),
+                "rules": len(parts["groups"][family]), "bytes": len(group_text(profile, parts, family).encode("utf-8"))}
+
+    return {
+        "ok": True, "profile": f"{profile['id']}@{profile['version']}", "profile_sha256": versioned.digest(profile),
+        "opinion_sha256": lock["opinion_sha256"] if lock else None,
+        "core": [entry(family) for family in parts["always"]],
+        "custom_bytes": len((profile["custom"] or "").encode("utf-8")),
+        "bundles": [{**entry(bundle["family"]), "trigger": bundle["trigger"], "exclude": bundle["exclude"], "routes": bundle["routes"]} for bundle in parts["bundles"]],
+        "unlisted": parts["unlisted"], "signals": profile["loading"]["signals"],
+        "core_bytes": len(core_text(profile, lock).encode("utf-8")), "complete_bytes": len(versioned.render(profile).encode("utf-8")),
+    }
+
+
+def check(profile: dict[str, Any], signals: list[str], loaded: list[str]) -> dict[str, Any]:
+    parts = partition(profile)
+    vocabulary = profile["loading"]["signals"]
+    declared: dict[str, set[str]] = {}
+    for item in signals:
+        key, _, value = item.partition("=")
+        if key not in vocabulary or value not in vocabulary[key]:
+            versioned.fail(f"未声明的交付信号：{item}")
+        declared.setdefault(key, set()).add(value)
+    if not declared:
+        versioned.fail("check 至少需要一个 --signal")
+    have = {resolve_bundle(parts, name) for name in loaded}
+    required = [bundle["family"] for bundle in parts["bundles"]
+                if any(all(declared.get(key, set()) & set(values) for key, values in route.items()) for route in bundle["routes"])]
+    missing = [family for family in required if family not in have]
+    return {"ok": not missing, "signals": {key: sorted(values) for key, values in declared.items()},
+            "required": required, "loaded": sorted(have), "missing": missing}
+
+
+def add_command(subparsers: Any) -> None:
+    parser = subparsers.add_parser("context", help="按已确认的加载声明只读切分正文，并核对交付信号")
+    parser.add_argument("action", choices=("core", "bundle", "index", "check"))
+    parser.add_argument("names", nargs="*", help="bundle 的模板系列或精确模板引用")
+    parser.add_argument("--project", type=Path)
+    parser.add_argument("--profile", type=Path, help="用候选或已保存的 Profile 预览，不读取项目锁")
+    parser.add_argument("--signal", action="append", default=[], help="交付信号，格式为 键=值，可重复")
+    parser.add_argument("--loaded", action="append", default=[], help="本次已读取的规则束，可重复")
+    parser.add_argument("--output", choices=("json", "markdown"), default="markdown")
+
+
+def execute(args: argparse.Namespace) -> tuple[int, str]:
+    try:
+        profile, lock = load(args)
+        if args.action == "core":
+            return EXIT_OK, core_text(profile, lock)
+        if args.action == "bundle":
+            return EXIT_OK, bundle_text(profile, args.names)
+        if args.action == "index":
+            return EXIT_OK, versioned.pretty(index_view(profile, lock))
+        result = check(profile, args.signal, args.loaded)
+        return (EXIT_OK if result["ok"] else EXIT_MISSING), versioned.pretty(result)
+    except FullReading as exc:
+        return EXIT_FULL, versioned.pretty({"ok": False, "error": str(exc), "fallback": FALLBACK})
+    except (versioned.OpinionVersionError, OSError, UnicodeDecodeError, json.JSONDecodeError, KeyError, TypeError) as exc:
+        return EXIT_ERROR, versioned.pretty({"ok": False, "error": str(exc), "fallback": FALLBACK})