@xgent-ai/skills 0.4.0 → 0.6.0

package/README.md

@@ -16,9 +16,9 @@ npx skills add XGENT-ai/skills
 npx skills add XGENT-ai/skills --skill dev-plan
 ```
 
-## Claude Code 辅助工具
+## 项目辅助工具（Claude Code / Codex）
 
-本仓库同时以 [`@xgent-ai/skills`](https://www.npmjs.com/package/@xgent-ai/skills) 发布到 npm,自带 `xgent-skills` 命令,可为任意项目安装 XGENT 的 Claude Code hooks(当前包含 statusline)、在项目 `.claude/settings.json` 中启用对应配置,装上随包 vendor 的 [impeccable](#vendor-的-impeccable),并可选创建通用的 `AGENTS.md`:
+本仓库同时以 [`@xgent-ai/skills`](https://www.npmjs.com/package/@xgent-ai/skills) 发布到 npm,自带 `xgent-skills` 命令,可为任意项目安装 XGENT 的 Claude Code hooks(当前包含 statusline)、在项目 `.claude/settings.json` 中启用对应配置,装上随包 vendor 的 [impeccable](#vendor-的-impeccable),并可选创建通用的 `AGENTS.md`、安装 Codex 或 Claude Code 的 goal 上下文收尾提醒:
 
 ```bash
 # 在目标项目根目录执行(也可显式传目录:npx @xgent-ai/skills install <dir>)
@@ -32,6 +32,12 @@ npx @xgent-ai/skills install
 | `--no-impeccable` | 跳过 impeccable,仍安装 XGENT 的 hooks 与 settings |
 | `--xgent-init` | 直接创建仓根 `AGENTS.md` (已有则跳过),不再询问 |
 | `--no-xgent-init` | 跳过创建 `AGENTS.md`,不再询问 |
+| `--context-goal-guard` | 显式安装 Codex goal 上下文收尾提醒(默认不安装);需要 Python 3.9+ |
+| `--no-context-goal-guard` | 跳过 Codex goal guard(默认行为);已有 guard 保留 |
+| `--context-goal-guard-threshold=N` | Codex guard 的触发阈值百分比(1–99 整数,默认 65),同时表示安装;重装不给则沿用已装的值 |
+| `--claude-context-goal-guard` | 显式安装 Claude Code goal 上下文收尾提醒(默认不安装) |
+| `--no-claude-context-goal-guard` | 跳过 Claude Code goal guard(默认行为);已有 guard 保留 |
+| `--claude-context-goal-guard-threshold=N` | Claude Code guard 的触发阈值百分比(1–99 整数,默认 70),同时表示安装;重装不给则沿用已装的值 |
 | `--providers=a,b` | 指定 impeccable 装进哪些 harness 目录(如 `--providers=.claude,.cursor`);默认按项目里已有的目录判断,一个都没有时只装 `.claude` |
 | `--force` | 强制重装,并允许覆盖非法 JSON 的 hook 配置(先存 `.bak`);不覆盖已有 `AGENTS.md` |
 
@@ -41,6 +47,20 @@ npx @xgent-ai/skills install
 
 非交互环境默认跳过,可用 `--xgent-init` 显式创建,或用 `--no-xgent-init` 跳过询问。文件位于仓根,不受 `--providers` 影响。模板没有待填占位,通用编码准则支持不同 coding agent;Portal App 的 onebox 联调与有前端改动时的真实浏览器验收分别按适用条件执行。
 
+`install` 默认不安装 Codex goal 上下文收尾提醒,也不询问;仅在显式传入 `--context-goal-guard` 或 `--context-goal-guard-threshold=N` 时安装。此选项不受 `--providers` 或 `--no-impeccable` 影响。请安装到 Git 仓库根目录;Codex 运行环境需要 git 和 Python 3.9+。显式安装时先检查含 SQLite 标准库的 Python 3.9+,复制脚本到 `.codex/hooks/context-goal-guard.py`,合并 `.codex/hooks.json` 的同步 `PreToolUse` / `Stop` handler（3 秒超时）,运行时从 Git 根目录定位脚本,配置不包含本机项目绝对路径,保留其他 hooks 与配置;重复安装只更新 guard,不重复添加。
+
+安装后会显示用户必须完成的步骤:从目标项目启动 Codex、信任项目 `.codex/` 层,在 `/hooks` 中审阅、信任并启用两个 handler,对**当前 goal** 明确超过阈值(默认 65%)时先保存进度和交接、再暂停的策略。安装输出提供可复制的指令;安装和信任本身不构成暂停授权。恢复 goal 或新开对话后需重新明确策略。当前仅验证 Codex 0.160.0、macOS arm64,完整限制与停用方法见 [启用说明](docs/codex-context-goal-guard.md)。
+
+Codex guard 已接入源码与 npm 打包清单,尚未发布到 npm;发布后可用 `npx @xgent-ai/skills install --context-goal-guard`。当前可从本仓库源码为目标项目安装:
+
+```bash
+node bin/xgent-skills.js install /absolute/path/to/project --context-goal-guard
+```
+
+`install` 默认不安装 Claude Code goal 上下文收尾提醒,也不询问;仅在显式传入 `--claude-context-goal-guard` 或 `--claude-context-goal-guard-threshold=N` 时安装,不受 `--providers` 或 `--no-impeccable` 影响。显式安装时复制脚本到 `.claude/hooks/context-goal-guard.js`,在个人的 `.claude/settings.local.json` 合并 `PostToolBatch` / `Stop` 两个 handler(5 秒超时),保留其他 hooks 与设置;重复安装只更新 guard。guard 只读当前会话记录:本会话 `/goal` 仍 active 且估算上下文严格超过阈值(默认 70%)时提醒 agent 按既有约定更新进度并交接,回合结束时由 Stop hook 结束回合,Claude Code 原生把 goal 置为 Goal paused,再由你在同一项目目录新开对话或 `/clear` 后重新设置 goal。hook 不写任何文件,也不清除或转移 goal。
+
+安装后需重启会话、信任工作区,并在 `/hooks` 中确认两个 handler 来源为 local settings。当前仅验证 Claude Code 2.1.288 交互式 CLI、macOS arm64 与 Opus 5.5 / Sonnet 5.5 / Haiku 4.5,完整限制、接续与停用方法见 [启用说明](docs/claude-context-goal-guard.md)。从源码安装:`node bin/xgent-skills.js install /absolute/path/to/project --claude-context-goal-guard`。
+
 Portal 的产品和设计规范仍保留在 [PRODUCT 模板](skills/xgent-init/references/external-app-PRODUCT.template.md) 与 [DESIGN 模板](skills/xgent-init/references/external-app-DESIGN.template.md) 中。需要生成项目上下文时,显式安装并在 Agent 对话中使用 [xgent-init](skills/xgent-init/SKILL.md),它读取清单与代码事实,补齐 PRODUCT.md / DESIGN.md (无前端的 service 型不新生成 DESIGN.md),已有文件保留:
 
 ```bash
@@ -81,6 +101,7 @@ node scripts/publish-vendor-r2.mjs    # engine 传 R2,下载地址回写 VERSION
 | Skill | 说明 |
 | --- | --- |
 | [prd](skills/prd/SKILL.md) | 撰写或优化 PRD，明确产品目标、FR/NFR、UAT、分期与终验，可按授权录入 SPMS |
+| [crd](skills/crd/SKILL.md) | 以整份 CRD 往返协作：起草需求、文末追加答复、整合对方返回版本并维护 Q&A |
 | [dev-plan](skills/dev-plan/SKILL.md) | 基于需求、仓库规则与代码事实撰写或评审可执行、可跨对话续做的开发计划 |
 | [test-plan](skills/test-plan/SKILL.md) | 从需求与验收标准生成测试用例，覆盖正常、边界、权限和并发场景，可按授权写入 SPMS |
 | [story-points](skills/story-points/SKILL.md) | 按客观因子估算故事点，回写 SPMS 规划点数并复核 Sprint 容量 |
@@ -89,7 +110,69 @@ node scripts/publish-vendor-r2.mjs    # engine 传 R2,下载地址回写 VERSION
 | [review-code](skills/review-code/SKILL.md) | 评审未提交变更、commit 或分支差异，可对照开发计划，输出有证据的代码评审报告 |
 | [review-prd-dev-gaps](skills/review-prd-dev-gaps/SKILL.md) | 核对 PRD 与开发交付，将遗漏、合理变更和待拍板差异分流，交互 Triage 后按需调用 dev-plan 生成 gaps plan |
 | [apply-code-review](skills/apply-code-review/SKILL.md) | 核实代码评审意见，实施合理修复、验证结果并回写实现记录与必要进度 |
-| [apply-doc-review](skills/apply-doc-review/SKILL.md) | 根据 PRD 或开发计划评审报告修订原文，复核关联内容并记录逐条处置结果 |
+| [apply-doc-review](skills/apply-doc-review/SKILL.md) | 可只传评审报告，沿报告的原文档引用定位并修订 PRD 或开发计划，复核并记录逐条处置结果 |
+
+把上述 skill 串成完整交付流水线（想法 → PRD → 分期 → 每期开发与并行测试 → 交付）的方法见 [AI Native SDLC](docs/ai-native-sdlc.md)，含各环节产物路径约定与测试线待补环节的现状核对。
+
+在任意阶段通过 `$agi-mode sdlc <问题>` 或自然语言获取 [SDLC 指引](skills/agi-mode/playbooks/sdlc.md)：解释 PRD、CRD、计划与测试的分工，判断交接条件，选择下一步。手册随 agi-mode 分发；咨询默认只读，涉及项目现状时复用 what-next 核对证据，实际能力以当前项目和已安装技能为准。
+
+这 10 个 SDLC skill 及 `agi-mode` 均在 `SKILL.md` 的 `argument-hint` 中提供参数提示。`<…>` 表示任务所需输入，可沿已有上下文或文档引用定位；`[…]` 是可选补充，`/` 分隔同一位置的备选，不是要求照抄的参数或新增命令解析器。例如：
+
+```text
+$review-prd <PRD路径/链接/内容> [上轮报告] [复审/完整评审] [问题ID/范围] [报告路径] [仅聊天]
+$review-code [未提交/commit/A..B/基准分支] [上轮报告] [复审/完整评审] [问题ID/文件范围] [开发计划] [报告路径] [仅聊天]
+$apply-doc-review <文档评审报告> [原文路径] [上轮报告/处置记录] [修复/仅复核] [问题ID/范围]
+$agi-mode <任务描述> 或 sdlc [流程/阶段/问题] 或 init-sdlc [PRD/计划/范围] 或 what-next [查询/更新] [PRD/计划/范围]
+```
+
+提示的展示取决于客户端：[Claude Code](https://code.claude.com/docs/en/skills#frontmatter-reference) 在 `/skill` 补全中支持 `argument-hint`；Codex 的 `$skill` 参数预览仍有[未关闭的功能请求](https://github.com/openai/codex/issues/31014)，不能仅凭新增字段保证弹出提示。未展示时可直接参考上述用法或各技能的 frontmatter。
+
+4 个 `review-*` 支持“对照上轮报告复审修复效果”：逐项保留来源 ID，区分已解决、仍存在、部分解决、回归、待核实、不再适用和本轮未复核；新增问题单列，默认另存报告。代码旧问题的复核不受本次修复 diff 限制。`review-prd-dev-gaps` 会先核对已有 gaps plan，支持“仅报告”，避免重复规划。
+
+2 个 `apply-*` 支持“继续修复”与“仅复核”：前者处理剩余问题，后者保留目标产物并保存必要处置记录；完全只读则仅聊天交付。重复执行先核对已有证据，无实质变化不改文件或时间；apply 的复核不自动成为新一轮独立 review。
+
+项目状态与下一步能力已合并到 `agi-mode` 的 [what-next 流程](skills/agi-mode/playbooks/what-next.md)，不再单独发布 `what-next` skill。查询默认只读；初始化/更新才保存，既有执行授权继续有效。
+
+```text
+使用 $agi-mode sdlc，解释从需求、CRD 往返到开发、验收和发布的交接。
+使用 $agi-mode init-sdlc 初始化项目状态跟进。
+使用 $agi-mode what-next 看当前项目状态和下一步。
+使用 $agi-mode what-next 更新状态，核对并行计划和最近几轮评审。
+```
+
+`init-sdlc` 按需创建状态目录和索引，核实并登记现有材料；可重复运行，沿用已有台账并补齐缺项，不重置历史。兼容原有 `what-next 初始化` 写法。其他 SDLC skill 在台账启用后维护相关状态，首次启用可直接运行上述初始化入口。
+
+[状态目录约定](skills/agi-mode/references/workspace-layout.md)使用仓根 `.xgent-ai/sdlc/` **只保存开发状态**。PRD、开发计划、评审报告、实施/验收记录和证据继续按用户习惯存放，台账通过链接引用，不改变其路径或复制正文。
+
+```text
+.xgent-ai/
+  index.md                          工作状态总入口
+  sdlc/
+    index.md                        本层导航与当前重点
+    protocol.md                     状态回写和索引维护协议
+    state-model.md                  固定状态、证据门槛和自愈规则
+    event-template.md               状态变化模板
+    status/
+      index.md                      类型入口
+      <prd|plan|review>/
+        index.md                    对象目录
+        <对象UUID>.md               各 PRD、计划、评审的状态
+    events/
+      index.md                      事件类型入口
+      <类型>/
+        index.md                    对象入口
+        <对象UUID>/
+          index.md                  事件清单
+          <事件UUID>.md             单次变化
+```
+
+每个实际创建的状态目录都有 `index.md`，非开发任务的 `tasks/` 及任务子目录也一样；不预建空目录。索引只列本层内容，数量增多后可按领域/年份分片。写入者按[索引维护规范](skills/agi-mode/assets/sdlc/protocol.md#目录索引维护)同步受影响入口，无变化不重写；多机合并保留双方条目并核对实际文件，查询只报告缺项。索引文件不算事件。
+
+状态按对象拆分、历史按需读取。PRD 与计划保持多对多关系，每轮评审有独立状态 ID，原报告文件名不必改变。UUID 事件保留并发记录，冲突待核对，不用机器时间覆盖。
+
+[固定状态模型](skills/agi-mode/assets/sdlc/state-model.md)将文档就绪、计划实施、每轮评审及处置分开：例如 `dev-plan-ready` 表示可开工，`dev-plan-completed` 表示实施范围和规定验证已完成。what-next 会从 `.review.md`、`.codereview.md`、`.code-review.md` 等候选补查漏记评审，并从报告处置节、`.applied.md` 或实施记录核实整改。原计划状态可能滞后，足够的实现/验证证据可纠正 SDLC 状态；原文自述、差异及证据质量仍保留。查询只读重算，更新才保存修复；证据不足用 `unknown`，独立验收线枚举暂为 TBD。
+
+相关撰写、评审、修复技能和计划实施模板仅增加状态回写规则，原产物落盘方式保持原有约定。已有台账可继续使用，不自动迁移或双写。状态协议随仓同步，另一台机器无需安装所有技能也能回写；状态已同步不代表原文和证据已同步。安装 `agi-mode`：`npx skills add XGENT-ai/skills --skill agi-mode`。
 
 ### 开发、调试与质量
 
@@ -109,16 +192,19 @@ node scripts/publish-vendor-r2.mjs    # engine 传 R2,下载地址回写 VERSION
 
 | Skill | 说明 |
 | --- | --- |
-| [agi-mode](skills/agi-mode/SKILL.md) | 以结果契约、主动实验、反证验证和可恢复执行，自主推进复杂任务到可验证交付 |
+| [agi-mode](skills/agi-mode/SKILL.md) | 自主推进复杂任务到可验证交付；含 SDLC 阶段指引、项目状态/what-next 与分类状态记录 |
 | [arena](skills/arena/SKILL.md) | agi-mode 的多候选比较兼容入口，选择基础版本并重新验证合成结果 |
 | [swarm](skills/swarm/SKILL.md) | 为任务选择多 agent 协作机制，设计角色、分工、执行与收尾流程 |
 | [autoresearch](skills/autoresearch/SKILL.md) | agi-mode 的 Hillclimb 兼容入口，在固定协议下搜索并确认改进 |
 | [reflect](skills/reflect/SKILL.md) | agi-mode 的 Reflection 兼容入口，从会话证据提炼并验证改进假设 |
+| [experience-capture](skills/experience-capture/SKILL.md) | 开发中轻量收集踩坑、纠正及自动化线索，供用户随后发起复盘 |
 
 自进化流程集中在 `agi-mode` 内：[Eval](skills/agi-mode/playbooks/eval.md) 建立可信判定，[Hillclimb](skills/agi-mode/playbooks/hillclimb.md) 管理搜索，[Arena](skills/agi-mode/playbooks/arena.md) 提供不同候选，[Reflection](skills/agi-mode/playbooks/reflection.md) 提炼教训。协作与记录约定见 [技能演化](skills/agi-mode/references/skill-evolution.md)。
 
 只需安装 `agi-mode` 即可使用上述流程；保留的 `autoresearch`、`arena`、`reflect` 名称是兼容入口，需要同时安装 `agi-mode`。它们不再独立维护执行规则。
 
+`experience-capture` 可独立安装，默认允许自动选择；本仓 `AGENTS.md` 也提供触发约定。它只在开发的自然间隙，把当前上下文已有的线索用 3–4 行保存到 `.xgent-ai/experience/`，不打断主任务，不额外检索取证或回读完整记录；没有合适间隙则跳过，纯咨询和只读任务不落盘。自动选择不等于可靠的后台事件监听；其他项目可在自己的 `AGENTS.md` 中约定出现这些信号时读取已安装的 skill。任务结束后用 `$agi-mode 复盘` 或 `$agi-mode reflect` 深入挖掘、查找和核对证据；默认给出建议，明确授权沉淀时落实到 know-how、playbook、principle 或自动化工具，并回写处置。
+
 整体方法见 [agi-mode 自进化方法论](docs/agi-mode-evolution-methodology.md)，说明样本沉淀、重放、进化实践和能力评估，以及通用方法与业务实践案例的边界。
 
 ### 文档、表达与图示
@@ -157,6 +243,10 @@ node scripts/publish-vendor-r2.mjs    # engine 传 R2,下载地址回写 VERSION
 
 每个 skill 位于 `skills/<name>/` 目录下,包含一个带 `name` 与 `description` frontmatter 的 `SKILL.md`:
 
+`description` 用于加载前的技能选择,按「触发条件与关键排除条件 → 核心产出」组织。整条建议不超过 200 字符,中文尽量在 100 字符左右;前 100 字符应能独立表达适用边界。这是本仓库的编辑目标,不是所有 coding agent 的统一截断上限。
+
+容易混淆的限制要紧跟触发条件,例如「仅写/评审计划,不用于按计划实施」,不能放在长段落末尾或只留在正文。操作步骤、完整错误码清单、工具细节和重复的双语说明放入正文或 references;精简后检查前缀是否仍表达原意,不要直接机械截字。
+
 ```
 skills/
 └── dev-plan/

package/bin/xgent-skills.js

@@ -19,6 +19,12 @@ const BUNDLE_DIR = path.join(VENDOR_DIR, 'bundle');
 const BLOBS_DIR = path.join(BUNDLE_DIR, 'blobs');
 const MANIFEST_FILE = path.join(BUNDLE_DIR, 'manifest.json');
 const AGENTS_TEMPLATE = path.join(PKG_ROOT, 'skills', 'xgent-init', 'references', 'external-app-AGENTS.template.md');
+const CONTEXT_GOAL_GUARD_SRC = path.join(PKG_ROOT, 'hooks', 'codex', 'context-goal-guard.py');
+// 不放进 .claude/hooks:那里的文件会被无条件复制到目标项目,绕过用户选择。
+const CLAUDE_CONTEXT_GOAL_GUARD_SRC = path.join(PKG_ROOT, 'hooks', 'claude', 'context-goal-guard.js');
+// 与两份脚本内置的默认阈值一致;安装器总是把阈值写进 handler 命令,在 /hooks 里可见。
+const CONTEXT_GOAL_GUARD_DEFAULT_THRESHOLD = 65;
+const CLAUDE_CONTEXT_GOAL_GUARD_DEFAULT_THRESHOLD = 70;
 
 // 写入目标项目 .claude/settings.json 的配置,按顶层 key 合并:
 // 这里列出的 key 以本包为准覆盖,其余已有配置保持不动。
@@ -503,23 +509,167 @@ function installImpeccable(targetDir, options) {
 
 // ─── install ────────────────────────────────────────────────────────────────
 
-async function confirmAgents() {
+async function confirm(question, skipMessage, answers) {
   if (!process.stdin.isTTY) {
-    console.log('  跳过  AGENTS.md:非交互环境,可加 --xgent-init 创建');
+    console.log(skipMessage);
     return false;
   }
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
-    rl.once('close', () => resolve(false));
-    rl.once('SIGINT', () => {
-      rl.close();
-      process.exit(130);
-    });
-    rl.question('是否同时创建通用的 AGENTS.md (含 Portal 联调与前端验收约定)? [y/N] ', (answer) => {
-      resolve(/^(y|yes)$/i.test(answer.trim()));
-      rl.close();
-    });
-  });
+  process.stdout.write(question);
+  const { value = '' } = await answers.next();
+  return /^(y|yes)$/i.test(value.trim());
+}
+
+// 重装没给阈值 flag 时沿用旧 handler 里的值。
+function guardThreshold(command) {
+  return Number(/ --threshold ([1-9][0-9]?)$/.exec(command)?.[1]) || undefined;
+}
+
+function installContextGoalGuard(targetDir, force, threshold) {
+  const python = spawnSync('python3', ['-c', 'import sys, sqlite3; sys.exit(0 if sys.version_info >= (3, 9) else 1)'],
+    { encoding: 'utf8', timeout: 5000 });
+  if (python.status !== 0) {
+    throw new Error('Codex goal guard 需要含 sqlite3 的 Python 3.9 或更高版本。请先安装并用 python3 --version 核对,确保 Codex 运行环境也能找到 python3,再重试;或加 --no-context-goal-guard 跳过。');
+  }
+  const manifestPath = path.join(targetDir, '.codex', 'hooks.json');
+  let existing = {};
+  let backup = false;
+  if (fs.existsSync(manifestPath)) {
+    try {
+      existing = readJson(manifestPath);
+    } catch (error) {
+      if (!(error instanceof SyntaxError)) throw error;
+      if (!force) throw new Error(`${manifestPath} 不是合法 JSON,未修改;请先手动修复,或加 --force 备份为 .bak 后覆盖。`);
+      backup = true;
+    }
+  }
+  // 合法 JSON 的未知结构不能当成空配置,否则会丢失用户的 hooks。
+  if (!existing || typeof existing !== 'object' || Array.isArray(existing)
+      || (existing.hooks !== undefined && (!existing.hooks || typeof existing.hooks !== 'object' || Array.isArray(existing.hooks)))
+      || Object.values(existing.hooks || {}).some((entries) => !Array.isArray(entries))) {
+    throw new Error(`${manifestPath} 的 hooks 结构不受支持,未修改;请先手动修复为事件数组。`);
+  }
+  const scriptPath = path.join(fs.realpathSync(targetDir), '.codex', 'hooks', 'context-goal-guard.py');
+  let previous;
+  const hooks = { ...existing.hooks };
+  for (const event of ['PreToolUse', 'Stop']) {
+    const kept = [];
+    for (const entry of hooks[event] || []) {
+      if (!Array.isArray(entry?.hooks)) {
+        kept.push(entry);
+        continue;
+      }
+      const handlers = entry.hooks.filter((handler) => {
+        const guard = handler?.type === 'command' && typeof handler.command === 'string'
+          && /\.codex\/hooks\/context-goal-guard\.py(?:['"\s]|$)/.test(handler.command);
+        if (guard) previous ??= guardThreshold(handler.command);
+        return !guard;
+      });
+      if (handlers.length === entry.hooks.length) kept.push(entry);
+      else if (handlers.length > 0) kept.push({ ...entry, hooks: handlers });
+    }
+    hooks[event] = kept;
+  }
+  const limit = threshold ?? previous ?? CONTEXT_GOAL_GUARD_DEFAULT_THRESHOLD;
+  // 运行时从 Git 根目录定位,避免配置绑定安装机器或会话子目录。
+  const command = `python3 "$(git rev-parse --show-toplevel)/.codex/hooks/context-goal-guard.py" --threshold ${limit}`;
+  for (const event of ['PreToolUse', 'Stop']) hooks[event].push({ hooks: [{ type: 'command', command, timeout: 3 }] });
+  const script = fs.readFileSync(CONTEXT_GOAL_GUARD_SRC);
+  const manifest = Buffer.from(JSON.stringify({ ...existing, hooks }, null, 2) + '\n');
+  if (backup) fs.copyFileSync(manifestPath, `${manifestPath}.bak`);
+  console.log(`  ${writeFileIfChanged(scriptPath, script) ? '写入' : '未变'}  .codex/hooks/context-goal-guard.py`);
+  console.log(`  ${writeFileIfChanged(manifestPath, manifest) ? '写入' : '未变'}  .codex/hooks.json (context goal guard)`);
+  return limit;
+}
+
+function printContextGoalGuardSteps(threshold) {
+  console.log(`
+Codex goal guard 已部署,请完成以下操作后使用:
+  1. 在目标项目运行 codex --version;目前仅验证 Codex 0.160.0、macOS arm64。
+     其他版本的会话格式不自动兼容;请先在隔离项目验证。
+  2. 从目标项目启动 Codex,审阅并信任项目 .codex/ 层。
+     在 Codex 对话中输入 /hooks,找到本项目 .codex/hooks.json 的
+     PreToolUse 和 Stop 两个 context-goal-guard.py handler,分别审阅、信任并启用。
+     核对两者来源和状态,确认其他 hooks 仍保留;配置或脚本更新后重新审阅信任。
+  3. 安装与信任不构成暂停授权。请在当前 goal 的用户指令中明确(可复制):
+     对当前 goal,如果本地估算上下文使用率严格超过 ${threshold}%,请先安全收尾,
+     按已有任务约定保存进度和交接说明,再使用原生 goal 工具将其设为 paused
+     并核对,无需二次确认。未完成工作不要标为 complete。请提醒我自己新开对话继续。
+  4. 先用测试 goal 验证提醒与真实 paused 状态。/goal resume 撤销先前暂停请求,
+     需重新明确策略;新开对话也需手动设置新 goal 并重新明确策略。
+     暂停失败时在原对话输入 /goal pause;临时停用可在 /hooks 中禁用这两个 handler。
+  提示: 请安装到 Git 仓库根目录;Codex 运行环境必须能找到 git 和 Python 3.9+。
+        hook 运行时从 Git 根目录定位脚本;没有 active goal 时不会触发。
+`);
+}
+
+// 与 installContextGoalGuard 形状相似,但文件、事件和匹配式都不同,暂不抽公共函数。
+function installClaudeContextGoalGuard(targetDir, force, threshold) {
+  const settingsPath = path.join(targetDir, '.claude', 'settings.local.json');
+  let existing = {};
+  let backup = false;
+  if (fs.existsSync(settingsPath)) {
+    try {
+      existing = readJson(settingsPath);
+    } catch (error) {
+      if (!(error instanceof SyntaxError)) throw error;
+      if (!force) throw new Error(`${settingsPath} 不是合法 JSON,未修改;请先手动修复,或加 --force 备份为 .bak 后覆盖。`);
+      backup = true;
+    }
+  }
+  // 合法 JSON 的未知结构不能当成空配置,否则会丢失用户的设置。
+  if (!existing || typeof existing !== 'object' || Array.isArray(existing)
+      || (existing.hooks !== undefined && (!existing.hooks || typeof existing.hooks !== 'object' || Array.isArray(existing.hooks)))
+      || Object.values(existing.hooks || {}).some((entries) => !Array.isArray(entries))) {
+    throw new Error(`${settingsPath} 的 hooks 结构不受支持,未修改;请先手动修复为事件数组。`);
+  }
+  let previous;
+  const hooks = { ...existing.hooks };
+  for (const event of ['PostToolBatch', 'Stop']) {
+    const kept = [];
+    for (const entry of hooks[event] || []) {
+      if (!Array.isArray(entry?.hooks)) {
+        kept.push(entry);
+        continue;
+      }
+      const handlers = entry.hooks.filter((handler) => {
+        const guard = handler?.type === 'command' && typeof handler.command === 'string'
+          && /\.claude\/hooks\/context-goal-guard\.js(?:['"\s]|$)/.test(handler.command);
+        if (guard) previous ??= guardThreshold(handler.command);
+        return !guard;
+      });
+      if (handlers.length === entry.hooks.length) kept.push(entry);
+      else if (handlers.length > 0) kept.push({ ...entry, hooks: handlers });
+    }
+    hooks[event] = kept;
+  }
+  const limit = threshold ?? previous ?? CLAUDE_CONTEXT_GOAL_GUARD_DEFAULT_THRESHOLD;
+  const command = `node "$CLAUDE_PROJECT_DIR/.claude/hooks/context-goal-guard.js" --threshold ${limit}`;
+  for (const event of ['PostToolBatch', 'Stop']) hooks[event].push({ hooks: [{ type: 'command', command, timeout: 5 }] });
+  const script = fs.readFileSync(CLAUDE_CONTEXT_GOAL_GUARD_SRC);
+  const settings = Buffer.from(JSON.stringify({ ...existing, hooks }, null, 2) + '\n');
+  if (backup) fs.copyFileSync(settingsPath, `${settingsPath}.bak`);
+  console.log(`  ${writeFileIfChanged(path.join(targetDir, '.claude', 'hooks', 'context-goal-guard.js'), script) ? '写入' : '未变'}  .claude/hooks/context-goal-guard.js`);
+  console.log(`  ${writeFileIfChanged(settingsPath, settings) ? '写入' : '未变'}  .claude/settings.local.json (context goal guard)`);
+  return limit;
+}
+
+function printClaudeContextGoalGuardSteps(threshold) {
+  console.log(`
+Claude Code goal guard 已部署,请完成以下操作后使用:
+  1. 运行 claude --version;目前仅验证 Claude Code 2.1.288 交互式 CLI、macOS arm64,
+     以及 claude-opus-5-5、claude-sonnet-5-5(1M)与 claude-haiku-4-5-20251001(200k)。
+     可在 statusLine 输入的 context_window.context_window_size 核对窗口,不一致时不要启用。
+  2. 重启 Claude Code 会话并信任本工作区;输入 /hooks,确认 PostToolBatch 与 Stop
+     各有一个 context-goal-guard.js handler,来源为 .claude/settings.local.json,其他 hooks 仍在。
+  3. 先用测试 goal 验证:估算上下文严格超过 ${threshold}% 时 agent 收到收尾提醒;回合结束时
+     界面可能先出现「Stop hook error: …」(收尾请求,属正常),随后出现 Goal paused。
+  4. 接续:在同一项目目录新开对话或 /clear,提供计划路径或交接摘要,并重新设置 /goal;
+     新对话不继承 goal。原会话发消息或 --resume 会恢复 goal 并再次触发暂停,
+     不再需要时在原会话 /goal clear。
+  5. 停用:从 .claude/settings.local.json 删除这两个 handler 并重启会话;
+     不要用 disableAllHooks,它会连 /goal 一起禁用。
+  说明见 @xgent-ai/skills 包内 docs/claude-context-goal-guard.md;没有 active goal 时不会触发。
+`);
 }
 
 function createAgents(targetDir) {
@@ -540,13 +690,22 @@ function usage() {
   install [dir]   为目标项目(默认当前目录)安装 .claude/hooks 下的全部
                   hook,在 .claude/settings.json 中启用对应配置,并装上
                   vendor 的 impeccable(skills + hooks,以及按需下载的
-                  engine 二进制),并询问是否创建通用的 AGENTS.md
+                  engine 二进制),并询问是否创建通用的 AGENTS.md;
+                  Codex / Claude Code goal 上下文收尾提醒默认不安装
   help            显示本帮助
 
 install 选项:
   --no-impeccable       跳过 impeccable,仍安装 XGENT 的 hooks 与 settings
   --xgent-init          创建 AGENTS.md (已有则跳过),不再询问
   --no-xgent-init       跳过 AGENTS.md,不再询问
+  --context-goal-guard  显式安装 Codex goal guard(默认不安装,需要 Python 3.9+)
+  --no-context-goal-guard 跳过 Codex goal guard(默认行为,保留已有 guard)
+  --context-goal-guard-threshold=N  Codex guard 的阈值百分比(1–99 整数,默认 ${CONTEXT_GOAL_GUARD_DEFAULT_THRESHOLD};
+                        重装时不给则沿用已装的值),同时表示安装
+  --claude-context-goal-guard 显式安装 Claude Code goal guard(默认不安装)
+  --no-claude-context-goal-guard 跳过 Claude Code goal guard(默认行为,保留已有 guard)
+  --claude-context-goal-guard-threshold=N  Claude Code guard 的阈值百分比(1–99 整数,
+                        默认 ${CLAUDE_CONTEXT_GOAL_GUARD_DEFAULT_THRESHOLD};重装时不给则沿用已装的值),同时表示安装
   --providers=a,b       指定 impeccable 装进哪些 harness 目录(默认按项目里
                         已有的目录判断,都没有时装 ${DEFAULT_TARGETS.join(' 和 ')})
   --force               强制重装,并允许覆盖非法 JSON 的 hook 配置(先存 .bak),
@@ -557,7 +716,8 @@ install 选项:
 async function install(args) {
   const flags = args.filter((a) => a.startsWith('--'));
   const dirArg = args.find((a) => !a.startsWith('--'));
-  const unknown = flags.filter((f) => !['--no-impeccable', '--xgent-init', '--no-xgent-init', '--force'].includes(f) && !f.startsWith('--providers='));
+  const unknown = flags.filter((f) => !['--no-impeccable', '--xgent-init', '--no-xgent-init', '--context-goal-guard', '--no-context-goal-guard', '--claude-context-goal-guard', '--no-claude-context-goal-guard', '--force'].includes(f)
+    && !['--providers=', '--context-goal-guard-threshold=', '--claude-context-goal-guard-threshold='].some((p) => f.startsWith(p)));
   if (unknown.length > 0) {
     console.error(`错误: 未知选项: ${unknown.join(', ')}\n`);
     usage();
@@ -567,6 +727,32 @@ async function install(args) {
     console.error('错误: --xgent-init 与 --no-xgent-init 不能同时使用');
     process.exit(1);
   }
+  if (flags.includes('--context-goal-guard') && flags.includes('--no-context-goal-guard')) {
+    console.error('错误: --context-goal-guard 与 --no-context-goal-guard 不能同时使用');
+    process.exit(1);
+  }
+  if (flags.includes('--claude-context-goal-guard') && flags.includes('--no-claude-context-goal-guard')) {
+    console.error('错误: --claude-context-goal-guard 与 --no-claude-context-goal-guard 不能同时使用');
+    process.exit(1);
+  }
+  const thresholds = {};
+  for (const [name, skip] of [['--context-goal-guard-threshold', '--no-context-goal-guard'],
+    ['--claude-context-goal-guard-threshold', '--no-claude-context-goal-guard']]) {
+    const flag = flags.find((f) => f.startsWith(`${name}=`));
+    if (flag === undefined) continue;
+    const value = flag.slice(name.length + 1);
+    if (!/^[1-9][0-9]?$/.test(value)) {
+      console.error(`错误: ${name} 需要 1–99 的整数百分比,收到 "${value}"`);
+      process.exit(1);
+    }
+    if (flags.includes(skip)) {
+      console.error(`错误: ${name} 与 ${skip} 不能同时使用`);
+      process.exit(1);
+    }
+    thresholds[name] = Number(value);
+  }
+  const codexThreshold = thresholds['--context-goal-guard-threshold'];
+  const claudeThreshold = thresholds['--claude-context-goal-guard-threshold'];
   const options = {
     impeccable: !flags.includes('--no-impeccable'),
     force: flags.includes('--force'),
@@ -582,7 +768,23 @@ async function install(args) {
   options.detected = detectProviders(targetDir);
   if (options.providers) resolveProviders(options.detected, options.providers);
   const agentsExists = fs.existsSync(path.join(targetDir, 'AGENTS.md'));
-  const agents = flags.includes('--xgent-init') || (!flags.includes('--no-xgent-init') && !agentsExists && await confirmAgents());
+  const askAgents = !flags.includes('--xgent-init') && !flags.includes('--no-xgent-init') && !agentsExists;
+  const guard = flags.includes('--context-goal-guard') || codexThreshold !== undefined;
+  const claudeGuard = flags.includes('--claude-context-goal-guard') || claudeThreshold !== undefined;
+  const rl = process.stdin.isTTY && askAgents
+    ? readline.createInterface({ input: process.stdin, output: process.stdout }) : null;
+  const answers = rl?.[Symbol.asyncIterator]();
+  rl?.once('SIGINT', () => { rl.close(); process.exit(130); });
+  let agents;
+  try {
+    agents = flags.includes('--xgent-init') || (askAgents && await confirm(
+      '是否同时创建通用的 AGENTS.md (含 Portal 联调与前端验收约定)? [y/N] ',
+      '  跳过  AGENTS.md:非交互环境,可加 --xgent-init 创建', answers));
+  } finally {
+    rl?.close();
+  }
+  const codexLimit = guard && installContextGoalGuard(targetDir, options.force, codexThreshold);
+  const claudeLimit = claudeGuard && installClaudeContextGoalGuard(targetDir, options.force, claudeThreshold);
 
   const hooksDestDir = path.join(targetDir, '.claude', 'hooks');
   fs.mkdirSync(hooksDestDir, { recursive: true });
@@ -625,6 +827,8 @@ async function install(args) {
 
   if (agents) createAgents(targetDir);
   else if (agentsExists && !flags.includes('--no-xgent-init')) console.log('  跳过  AGENTS.md (已存在,保留原文)');
+  if (codexLimit) printContextGoalGuardSteps(codexLimit);
+  if (claudeLimit) printClaudeContextGoalGuardSteps(claudeLimit);
   console.log(`完成: ${targetDir}`);
 }
 

package/docs/claude-context-goal-guard.md

@@ -0,0 +1,124 @@
+# Claude Code goal 上下文收尾提醒
+
+当前会话的 `/goal` 仍 active，且本地估算上下文使用率**严格超过阈值**（默认 70%，可配置）时，本 hook 提醒 agent 收尾：停止开始新的实质任务，按任务已有约定更新进度并交接。回合结束时由 Stop hook 结束回合，Claude Code 原生把 goal 置为「Goal paused」，再由你自己新开对话（或 `/clear`）接续。恰好等于阈值不触发。hook 只读当前会话记录，不写任何文件，也不清除、转移或恢复 goal。
+
+## 兼容范围与限制
+
+- 已验证：Claude Code **2.1.288** 交互式 CLI、macOS arm64、Node v25.2.1（安装器要求 Node ≥ 18）。完整验收见 [M1 记录](plan/claude-context-goal-guard.records/M1.md)、[M2 记录](plan/claude-context-goal-guard.records/M2.md)、[M3 记录](plan/claude-context-goal-guard.records/M3.md)、[M4 记录](plan/claude-context-goal-guard.records/M4.md)。新版本不自动视为兼容。
+- 未验证：`claude -p` 非交互模式、桌面应用、Remote Control、云端会话。
+- 只保护主会话；子 agent 内的事件直接跳过。
+- 上下文窗口：hook 输入和会话记录都不含窗口大小，脚本只认下表中验证过的模型。其他模型，或设置了 `CLAUDE_CODE_DISABLE_1M_CONTEXT`、`DISABLE_COMPACT`、`CLAUDE_CODE_MAX_CONTEXT_TOKENS` 任一变量时，报告「检测不可用」，不触发。
+
+| 模型 id（会话记录中的 `message.model`） | 窗口 |
+| --- | --- |
+| `claude-opus-5-5` | 1,000,000（是否选 `[1m]` 相同） |
+| `claude-sonnet-5-5` | 1,000,000（是否选 `[1m]` 相同） |
+| `claude-haiku-4-5-20251001` | 200,000 |
+
+窗口还会因账号与服务端能力而不同，上表只在验证时用的 Claude Max 账号上核对过。启用前用 statusLine 自查：statusLine 命令的 stdin JSON 里 `model.id` 和 `context_window.context_window_size` 应与上表一致，不一致时不要启用。
+
+### 用量口径
+
+```text
+used    = input_tokens + cache_creation_input_tokens + cache_read_input_tokens   # 取最新主链 assistant 记录；有 iterations 时取最后一项
+trigger = used * 100 > window * threshold     # threshold 默认 70，见「阈值配置」
+```
+
+与 statusLine 的 `used_percentage` 同口径，不计 output。会话记录异步写入，可能落后一条消息。自动压缩后，出现新统计前不判定。
+
+Claude Code 界面右下角的「NN% context used」按扣除输出预留后的有效窗口计算，读数比本 guard 高。例如 Haiku 4.5 实测 155,100 token 时，界面显示 86%（≈ 155,100 / 180,000），guard 计为 78%。
+
+## 安装
+
+### 使用 install
+
+```sh
+# 默认不安装 guard；从本仓库源码显式安装
+# 发布到 npm 后可用 npx @xgent-ai/skills install --claude-context-goal-guard
+node bin/xgent-skills.js install /absolute/path/to/project --claude-context-goal-guard
+```
+
+交互和非交互安装均默认跳过 guard，不再询问。仅在显式传入 `--claude-context-goal-guard` 或 `--claude-context-goal-guard-threshold=N` 时安装；`--no-claude-context-goal-guard` 显式跳过并保留已有 guard，不能与安装参数同时使用。这个选项与 `--providers`、`--no-impeccable`、`--xgent-init` 及 Codex guard 的选项互不影响。
+
+安装器会：
+
+1. 复制脚本到目标项目 `.claude/hooks/context-goal-guard.js`；
+2. 把 `PostToolBatch` 与 `Stop` 两个 handler 合并进个人的 `.claude/settings.local.json`（不进共享的 `settings.json`），command 为 `node "$CLAUDE_PROJECT_DIR/.claude/hooks/context-goal-guard.js"`，超时 5 秒；
+3. 保留其他事件、handler、matcher 和顶层字段，重复安装只更新 guard。非法 JSON 默认报错，`--force` 先备份为 `.bak` 再覆盖；合法 JSON 但结构不认识时报错，需要手动修复。
+
+### 阈值配置
+
+阈值写在 handler 命令末尾：`--threshold N`，N 为 1–99 的整数百分比；不带参数时为 70。与 Codex 版（默认 65）各自独立。
+
+```sh
+# 安装时指定（同时表示安装，不再询问）
+node bin/xgent-skills.js install /absolute/path/to/project --claude-context-goal-guard-threshold=75
+```
+
+安装器总是把阈值明确写进两个 handler 的 command，在 `/hooks` 里看得到。之后重装时不给这个 flag，就沿用已装的值。也可以直接改 `.claude/settings.local.json` 里两条 command 末尾的数字，两条要一致。参数无效时（如 `0`、`100`、`6.5`）guard 不猜测数值，按「检测不可用」处理。
+
+阈值不宜太高：收尾本身还要消耗上下文，而 Claude Code 在接近有效窗口上限时会自动压缩（见上面的界面读数说明）。建议不超过 75%。
+
+### 手动部署
+
+```sh
+mkdir -p "/absolute/path/to/project/.claude/hooks"
+cp hooks/claude/context-goal-guard.js "/absolute/path/to/project/.claude/hooks/context-goal-guard.js"
+```
+
+把 [设置示例](../hooks/claude/settings.example.json) 里的两组 handler（默认 `--threshold 70`，按需修改）**追加**到目标项目 `.claude/settings.local.json` 已有的 `PostToolBatch`、`Stop` 数组，不要用示例覆盖整个文件。Claude Code 的 hook 运行环境里必须能找到 `node`。
+
+## 信任与生效确认
+
+1. 运行 `claude --version`，确认是上面验证过的版本。
+2. 从目标项目启动 Claude Code，信任该工作区。工作区未被信任时，设置里的 hook 和 `/goal` 都不可用。
+3. 输入 `/hooks`，确认 `PostToolBatch` 和 `Stop` 下各有一条 `[Local] node "$CLAUDE_PROJECT_DIR/.claude/hooks/context-g…`，其他 hooks 仍在。
+4. 先用测试 goal 走一遍：越过阈值后应看到提醒，回合结束后出现「Goal paused · a hook ended the turn」。
+
+## goal 条件怎么写
+
+guard 不管进度写到哪里，提醒只要求 agent 按任务**已有约定**更新进度。最好让 goal 条件指向一份带进度区的计划，例如：
+
+```text
+/goal 按 docs/plan/xxx.md 开发：全部里程碑完成并回写进度
+```
+
+没有计划文件时，agent 会在最终回复里给出交接摘要，不会新建文件。
+
+## 触发后会看到什么
+
+1. 越线后的每个工具批次，agent 都会收到同一条收尾提醒：停止新工作，把手上的工作处理到可交接，更新进度，停止后台任务，写明「因上下文收尾而暂停，工作未完成」。
+2. agent 第一次结束回合时，guard 可能先请求补做收尾。界面上显示为「Stop hook error: 上下文估算使用率 NN% …」，这是正常的继续请求，不是故障。
+3. 下一次结束回合时，guard 结束回合，界面显示 guard 的说明和「Goal paused · a hook ended the turn · send a message to continue」。goal 评估器会照常判定「未达成」，但不会再自动续跑。
+
+提醒没有强制力。在 goal 的自动续轮里越线时，agent 可能只收到一次提醒、甚至一次都没收到就被暂停。交接不完整时，在原会话发一句「按上下文收尾提醒补交接」，回合结束后会再次暂停。
+
+## 接续
+
+在同一项目目录新开对话，或在原会话输入 `/clear`。告诉 agent 计划路径（或粘贴交接摘要），再重新设置 `/goal`。新对话和 `/clear` 后都**不继承** goal：不重新设置，guard 就不会触发。
+
+原会话的 goal 只是暂停：在原会话里发任何消息都会恢复 goal，guard 随即再次收口；`claude --resume` 也会恢复 goal（不会自动运行）。不再需要时，在原会话 `/goal clear`。
+
+### 后台任务
+
+暂停时如果还有后台命令或子 agent 在跑，它们完成时的通知（以及 goal 的 idle check-in）会唤醒会话。guard 会先请求一次收尾，在请求里列出仍在运行的任务，再结束回合；进度不会前进，但每次唤醒多花两次简短的模型调用。这种被唤醒后再结束的回合，界面可能显示「Goal not yet met… continuing」，状态栏仍是「/goal active」，没有「Goal paused」提示；实测此后约 7 分钟内没有自动回合。
+
+## 停用
+
+从 `.claude/settings.local.json` 删除 command 含 `context-goal-guard.js` 的两个 handler，保留其他 hooks，再删除 `.claude/hooks/context-goal-guard.js`。实测会话运行中修改后，`/hooks` 数秒内就不再列出它们；保险起见仍建议重启会话。已暂停的 goal 不受影响。
+
+不要用 `disableAllHooks`：它会连 `/goal` 一起禁用。
+
+## 排查
+
+guard 只在 **Stop** 时显示告警，不会在每个工具批次刷屏。告警格式为「context goal guard 检测不可用：<原因>」：
+
+| 原因 | 处理 |
+| --- | --- |
+| 模型 `X` 的上下文窗口未经验证 | 换用上表中的模型，或停用 guard；补表需要先在同环境核对 statusLine 的窗口 |
+| 设置了改变上下文窗口的环境变量 `X` | 取消该变量，或停用 guard |
+| 无法读取会话记录 / hook 输入缺少会话记录路径 | 核对 Claude Code 版本；持续出现时停用 guard |
+| 用量统计格式未知 | Claude Code 的会话记录格式变了，停用 guard 并等待重新验证 |
+| 阈值参数无效 | 把两条 command 末尾改为 `--threshold` 加 1–99 的整数，或重新运行安装器 |
+
+检测不可用时，guard 不提醒、不结束回合，也不显示 0%。