@xgent-ai/skills 0.3.0 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@ XGENT 的 [Agent Skills](https://skills.sh) 集合,可安装到 Claude Code、Cu
 
 ## 安装
 
-安装全部 skills:
+列出并选择安装公开的 skills (`xgent-init` 是内部初始化 skill,不在默认列表中):
 
 ```bash
 npx skills add XGENT-ai/skills
@@ -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):
+本仓库同时以 [`@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>)
@@ -29,25 +29,55 @@ npx @xgent-ai/skills install
 
 | 选项 | 说明 |
 | --- | --- |
-| `--no-impeccable` | 只装 XGENT 的 hooks 与 settings,跳过 impeccable |
+| `--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`) |
+| `--force` | 强制重装,并允许覆盖非法 JSON 的 hook 配置(先存 `.bak`);不覆盖已有 `AGENTS.md` |
 
 安装是幂等的:hook 文件与 skill 目录按内容比对,只在有变化时覆盖;`settings.json` 按顶层 key 合并,impeccable 的 hook 按标记剔旧再合并,项目自己的 hook 与其他配置都保持不动。
 
-`install` 只装 hooks、settings 与 impeccable,不生成项目文档。出仓 App 仓库的 `CLAUDE.md` / `PRODUCT.md` / `DESIGN.md` 由 [xgent-init](skills/xgent-init/SKILL.md) skill 生成:`npx skills add XGENT-ai/skills --skill xgent-init`。
+`install` 会询问是否同时创建仓根 `AGENTS.md`,输入 `y` 或 `yes` 确认,回车默认跳过。确认后直接复制 [通用模板](skills/xgent-init/references/external-app-AGENTS.template.md),只创建 `AGENTS.md`,不安装 `xgent-init` skill,不生成 `CLAUDE.md` / `PRODUCT.md` / `DESIGN.md`。已有 `AGENTS.md` 时直接跳过并保留原文,包括使用 `--force` 时。
+
+非交互环境默认跳过,可用 `--xgent-init` 显式创建,或用 `--no-xgent-init` 跳过询问。文件位于仓根,不受 `--providers` 影响。模板没有待填占位,通用编码准则支持不同 coding agent;Portal App 的 onebox 联调与有前端改动时的真实浏览器验收分别按适用条件执行。
+
+`install` 还会询问是否安装 Codex goal 上下文收尾提醒,输入 `y` 或 `yes` 安装,回车和非交互环境默认跳过。此选项不受 `--providers` 或 `--no-impeccable` 影响。确认后先检查含 SQLite 标准库的 Python 3.9+,复制脚本到 `.codex/hooks/context-goal-guard.py`,合并 `.codex/hooks.json` 的同步 `PreToolUse` / `Stop` handler（3 秒超时）,保留其他 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 上下文收尾提醒,同样输入 `y` 或 `yes` 安装,回车和非交互环境默认跳过,不受 `--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
+npx skills add XGENT-ai/skills --skill xgent-init
+```
 
 ## vendor 的 impeccable
 
 [impeccable](https://github.com/pbakaus/impeccable)(Apache-2.0)整个 vendor 在 `vendor/impeccable/` 里:skill bundle 以去重形态随 npm 包发布,十几 MB 的 engine 二进制不进包、改放自家 R2,由 `install` 按 `VERSION.json` 里的地址与 sha256 取。官方的 `npx impeccable install` 要先从 GitHub 下 bundle、首次跑 hook 时再下 engine,墙内经常卡在 `Download failed`;这里 bundle 一步不联网,engine 只走一次 R2(装过一次就落在 `~/.impeccable/` 里,之后都不用了)。
 
-`vendor/impeccable/bundle/` 不是 `universal.zip` 解开的样子,而是它的去重形态:文件内容存在 `blobs/<sha256>`,`manifest.json` 里每个 harness 一张 `路径 → sha` 的清单。上游给 19 个 harness 目录各放了一整套 skill,其中 83% 的字节是同一批文件(光 `scripts/data/font-index.json` 就是 1.1 MB × 19 份、内容完全相同),各 harness 真正不同的只有 39 个路径 —— 有的差在路径 token(`.claude/skills/...` vs `.cursor/skills/...`),有的差在按 harness 改写过的措辞(有 `AskUserQuestion` 工具的 harness 写"调用该工具",没有的写"直接问用户")。`install` 按清单把文件写回去,装出来的结果与直接展开 zip 逐字节一致(上游 `impeccable doctor` 报 no drift)。展开后 38 MB → 6 MB,npm 包 13.5 MB → 3.1 MB。
+`vendor/impeccable/bundle/` 不是 `universal.zip` 解开的样子,而是它的去重形态:文件内容存在 `blobs/<sha256>`,`manifest.json` 里每个 harness 一张 `路径 → sha` 的清单。上游给 19 个 harness 目录各放了一整套 skill,其中 83% 的字节是同一批文件(光 `scripts/data/font-index.json` 就是 1.1 MB × 19 份、内容完全相同),各 harness 真正不同的只有 43 个路径 —— 有的差在路径 token(`.claude/skills/...` vs `.cursor/skills/...`),有的差在按 harness 改写过的措辞(有 `AskUserQuestion` 工具的 harness 写"调用该工具",没有的写"直接问用户")。`install` 按清单把文件写回去,装出来的结果与直接展开 zip 逐字节一致(上游 `impeccable doctor` 报 no drift)。当前 bundle 展开约 39.4 MiB,去重后约 6.7 MiB。
 
 装出来的东西和上游 `impeccable install` 的工程内安装一致(`impeccable doctor` 报 no drift):
 
 - `<harness>/skills/impeccable/`、`<harness>/agents/`、`<harness>/commands/`:按项目里已有的 harness 目录装,可用 `--providers` 指定;
 - hook manifest:Claude Code 写 `.claude/settings.local.json`(共享的 `settings.json` 里已有 impeccable hook 时以它为准),Cursor 写 `.cursor/hooks.json`,Codex 写 `.codex/hooks.json`,Copilot / Grok 写各自的 `hooks/impeccable.json`;
-- engine 二进制:只收 macOS(arm64 与 x64),按当前平台放进 `~/.impeccable/bin/<版本>/`,一台机器一份,所有项目和 `npx impeccable` 共用。缓存里已是对的那份就不再下;从本仓源码跑时直接用 `vendor/impeccable/engine/` 里的,不联网。非 mac 平台、以及 R2 拉不动时都只是跳过这一步,安装照常完成,由 launcher 首次运行时自己下载。
+- engine 二进制:只收 Apple Silicon macOS(darwin-arm64),放进 `~/.impeccable/bin/<版本>/`,一台机器一份,所有项目和 `npx impeccable` 共用。缓存里已是对的那份就不再下;从本仓源码跑时直接用 `vendor/impeccable/engine/` 里的,不联网。Intel Mac、其它平台以及 R2 拉不动时都只是跳过这一步,安装照常完成,由 launcher 首次运行时自己下载。
 
 升级 vendor 的版本(维护者执行,需要 curl、unzip 与 aws CLI):
 
@@ -60,14 +90,90 @@ node scripts/publish-vendor-r2.mjs    # engine 传 R2,下载地址回写 VERSION
 
 第二步把 engine 传到 R2 的 `vendor/impeccable/engine/v<版本>/<平台>/impeccable`,传完回读公共地址核一遍 sha256,再把 url 写进 `VERSION.json` 的 `engines`。凭据读仓库根的 `.env.cf`(`AGENT_RELEASE_R2_*`,已 gitignore,不在库里)。两步的顺序不能反 —— 第一步会重写 `VERSION.json`,先传就把 url 冲掉了;漏了第二步,发出去的包里 engine 没有下载地址,用户那边只会看到"跳过"。
 
-当前收录:skill 4.3.1 / engine 0.1.5(darwin-arm64、darwin-x64)。上游许可与三方声明见 `vendor/impeccable/LICENSE` 与 `vendor/impeccable/NOTICE.md`。
+当前收录:skill 4.5.0 / engine 0.1.11(darwin-arm64)。上游许可与三方声明见 `vendor/impeccable/LICENSE` 与 `vendor/impeccable/NOTICE.md`。
 
 ## Skills 列表
 
+以下按用途分组列出 `skills/` 中的 skill。点击名称查看使用条件与完整流程。
+
+### 需求、计划与评审
+
+| Skill | 说明 |
+| --- | --- |
+| [prd](skills/prd/SKILL.md) | 撰写或优化 PRD，明确产品目标、FR/NFR、UAT、分期与终验，可按授权录入 SPMS |
+| [dev-plan](skills/dev-plan/SKILL.md) | 基于需求、仓库规则与代码事实撰写或评审可执行、可跨对话续做的开发计划 |
+| [test-plan](skills/test-plan/SKILL.md) | 从需求与验收标准生成测试用例，覆盖正常、边界、权限和并发场景，可按授权写入 SPMS |
+| [story-points](skills/story-points/SKILL.md) | 按客观因子估算故事点，回写 SPMS 规划点数并复核 Sprint 容量 |
+| [review-prd](skills/review-prd/SKILL.md) | 核实代码现状，评审产品价值、体验、AI、SMAR、UAT 与分期终验，默认将完整报告落盘并回读核验 |
+| [review-dev-plan](skills/review-dev-plan/SKILL.md) | 评审开发计划的代码事实、技术方案、需求映射、依赖编排与交付可用性，输出评审报告 |
+| [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 或开发计划评审报告修订原文，复核关联内容并记录逐条处置结果 |
+
+把上述 skill 串成完整交付流水线（想法 → PRD → 分期 → 每期开发与并行测试 → 交付）的方法见 [AI Native SDLC](docs/ai-native-sdlc.md)，含各环节产物路径约定与测试线待补环节的现状核对。
+
+### 开发、调试与质量
+
+| Skill | 说明 |
+| --- | --- |
+| [architect](skills/architect/SKILL.md) | 实现前先设计类型、签名与模块结构，并在开发过程中持续校准 |
+| [debugging](skills/debugging/SKILL.md) | 按四阶段流程调查根因、定位问题并验证修复 |
+| [react](skills/react/SKILL.md) | 编写和评审 React 组件，处理 Hooks、Effects、渲染性能、数据请求与 React 19 迁移 |
+| [rust](skills/rust/SKILL.md) | 编写和评审 Rust 代码，处理所有权、错误、性能、测试及 Tokio 异步模式 |
+| [sql-optimization](skills/sql-optimization/SKILL.md) | 分析 SQL 执行计划，优化查询、索引、分页与批量操作 |
+| [security-audit](skills/security-audit/SKILL.md) | 沿数据流与组件交互审查注入、认证授权、密钥泄露、依赖及业务逻辑漏洞 |
+| [gdpr-compliant](skills/gdpr-compliant/SKILL.md) | 将 GDPR 隐私工程要求应用到个人数据处理、权限、日志、保留与删除流程 |
+| [working-with-mbx](skills/working-with-mbx/SKILL.md) | 安装和排查 Cargo 共享编译缓存 mbx，核对命中、绕过与磁盘使用情况 |
+| [working-with-mise](skills/working-with-mise/SKILL.md) | 配置和排查 mise 管理的工具、配置文件、PATH 与激活问题 |
+
+### Agent 协作与实验
+
+| Skill | 说明 |
+| --- | --- |
+| [agi-mode](skills/agi-mode/SKILL.md) | 以结果契约、主动实验、反证验证和可恢复执行，自主推进复杂任务到可验证交付 |
+| [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 兼容入口，从会话证据提炼并验证改进假设 |
+
+自进化流程集中在 `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`。它们不再独立维护执行规则。
+
+整体方法见 [agi-mode 自进化方法论](docs/agi-mode-evolution-methodology.md)，说明样本沉淀、重放、进化实践和能力评估，以及通用方法与业务实践案例的边界。
+
+### 文档、表达与图示
+
+| Skill | 说明 |
+| --- | --- |
+| [documentation-writer](skills/documentation-writer/SKILL.md) | 基于代码事实编写和更新 README、API、架构、代码库说明与用户手册 |
+| [archify](skills/archify/SKILL.md) | 将架构、流程、时序、数据流与状态关系制作成交互式 HTML 图，支持 Mermaid 输入和多格式导出 |
+| [elintp](skills/elintp/SKILL.md) | 将技术主题或文档改写成面向非研发读者、带图示的通俗 HTML 说明 |
+| [summarize](skills/summarize/SKILL.md) | 将需求、计划、Issue、文档或主题整理为 HTML 报告，并提交到指定 SPMS 项目的报告区 |
+| [humanize-writing](skills/humanize-writing/SKILL.md) | 改写机械、夸大或模板化的文字，使表达自然、直接 |
+| [meeting-minutes](skills/meeting-minutes/SKILL.md) | 整理会议议题、决定、负责人、截止日期与后续行动，生成会议纪要 |
+| [pardon](skills/pardon/SKILL.md) | 补充必要上下文，用当前会话语言把上一条回答重新讲清楚 |
+
+### 设计与转化
+
+| Skill | 说明 |
+| --- | --- |
+| [kpi-dashboard-design](skills/kpi-dashboard-design/SKILL.md) | 设计 KPI 仪表盘的指标选择、信息层级与数据可视化 |
+| [landing-page-conversion-audit](skills/landing-page-conversion-audit/SKILL.md) | 审查落地页、销售页或结账流程的转化障碍，按预期收入影响排序修复建议 |
+
+### XGENT Portal 接入与发布
+
 | Skill | 说明 |
 | --- | --- |
-| [dev-plan](skills/dev-plan/SKILL.md) | 以资深产品经理 + 资深架构师的双重视角,基于当前代码库的真实现状撰写高质量开发计划 |
-| [xgent-init](skills/xgent-init/SKILL.md) | 在出仓 App 自己的仓库里生成配套的 `CLAUDE.md` / `PRODUCT.md` / `DESIGN.md`,读清单与代码事实、一轮问清缺的,不留待填占位 |
+| [xgent-init](skills/xgent-init/SKILL.md) | 内部初始化 skill,补齐 `AGENTS.md` / `PRODUCT.md` / `DESIGN.md`,保留 Portal 产品边界与设计规范;`install` 仅直接创建 AGENTS.md |
+| [portal-dev-setup](skills/portal-dev-setup/SKILL.md) | 在 App 仓库中启动、体检和排查 Docker 一盒门户，完成本地联调 |
+| [portal-external-app](skills/portal-external-app/SKILL.md) | 接入以 Docker 镜像交付的外部服务，核对 manifest、注册、路由、权限与交付契约 |
+| [portal-micro-app](skills/portal-micro-app/SKILL.md) | 开发嵌入门户的微应用前端，处理 SDK 握手、导航、授权与 iframe 交互 |
+| [portal-app-exchange](skills/portal-app-exchange/SKILL.md) | 配置和排查跨应用 OAuth Token Exchange、交换白名单、授权与 scope |
+| [portal-logging](skills/portal-logging/SKILL.md) | 将应用日志与遥测接入门户，配置采集器、写入身份、日志流和字段口径 |
+| [xgent-image-push](skills/xgent-image-push/SKILL.md) | 构建并推送 App 镜像到私有 Harbor，预检链路、镜像架构、tag 与保留策略 |
+| [xgent-app-release](skills/xgent-app-release/SKILL.md) | 使用发布令牌提交前端产物、镜像和 manifest 变更，处理发布提案与发布故障 |
 
 ## 目录结构
 

package/bin/xgent-skills.js

@@ -10,6 +10,7 @@ const crypto = require('node:crypto');
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const readline = require('node:readline');
 
 const PKG_ROOT = path.join(__dirname, '..');
 const HOOKS_SRC_DIR = path.join(PKG_ROOT, '.claude', 'hooks');
@@ -17,6 +18,13 @@ const VENDOR_DIR = path.join(PKG_ROOT, 'vendor', 'impeccable');
 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 以本包为准覆盖,其余已有配置保持不动。
@@ -451,14 +459,14 @@ function readEngineBinary(meta, target, engine) {
 
 // engine 二进制放进 ~/.impeccable/bin/<版本>/:launcher 和 npx impeccable 都认
 // 这个版本化缓存,一台机器装一份,所有项目共用,之后运行也就不必联网了。
-// 只收了 macOS 的二进制,别的平台落到"跳过",由 launcher 首次运行时自己去
+// 只收了 Apple Silicon macOS 的二进制,别的平台落到"跳过",由 launcher 首次运行时自己去
 // GitHub 下载(上游原本的行为)。
 function installEngineBinary(meta, force) {
   const arch = { arm64: 'arm64', x64: 'x64' }[process.arch] || process.arch;
   const target = `${process.platform === 'darwin' ? 'darwin' : process.platform}-${arch}`;
   const engine = meta.engines && meta.engines[target];
   if (!engine) {
-    console.log(`  跳过  engine 二进制:只收了 macOS 的版本,${target} 会在首次运行时联网下载`);
+    console.log(`  跳过  engine 二进制:只收了 Apple Silicon macOS 的版本,${target} 会在首次运行时联网下载`);
     return;
   }
   const cacheRoot = process.env.IMPECCABLE_HOME || path.join(os.homedir(), '.impeccable');
@@ -501,6 +509,179 @@ function installImpeccable(targetDir, options) {
 
 // ─── install ────────────────────────────────────────────────────────────────
 
+async function confirm(question, skipMessage, answers) {
+  if (!process.stdin.isTTY) {
+    console.log(skipMessage);
+    return false;
+  }
+  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;
+  // POSIX 单引号同时保护空格、美元符号、反引号及项目路径中的单引号。
+  const command = `python3 '${scriptPath.replace(/'/g, "'\\''")}' --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。
+  提示: Python 3.9+ 必须在 Codex 运行环境可用;没有 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) {
+  const dest = path.join(targetDir, 'AGENTS.md');
+  try {
+    fs.copyFileSync(AGENTS_TEMPLATE, dest, fs.constants.COPYFILE_EXCL);
+    console.log('  创建  AGENTS.md');
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    console.log('  跳过  AGENTS.md (已存在,保留原文)');
+  }
+}
+
 function usage() {
   console.log(`用法: npx @xgent-ai/skills <command>
 
@@ -508,26 +689,69 @@ function usage() {
   install [dir]   为目标项目(默认当前目录)安装 .claude/hooks 下的全部
                   hook,在 .claude/settings.json 中启用对应配置,并装上
                   vendor 的 impeccable(skills + hooks,以及按需下载的
-                  engine 二进制)
+                  engine 二进制),并询问是否创建通用的 AGENTS.md
+                  与安装 Codex / Claude Code goal 上下文收尾提醒
   help            显示本帮助
 
 install 选项:
-  --no-impeccable       只装 XGENT 的 hooks 与 settings,跳过 impeccable
+  --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,不再询问
+  --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,不再询问
+  --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)
+  --force               强制重装,并允许覆盖非法 JSON 的 hook 配置(先存 .bak),
+                        不覆盖已有 AGENTS.md
 `);
 }
 
-function install(args) {
+async function install(args) {
   const flags = args.filter((a) => a.startsWith('--'));
   const dirArg = args.find((a) => !a.startsWith('--'));
-  const unknown = flags.filter((f) => f !== '--no-impeccable' && f !== '--force' && !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();
     process.exit(1);
   }
+  if (flags.includes('--xgent-init') && flags.includes('--no-xgent-init')) {
+    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'),
@@ -541,6 +765,36 @@ 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 askAgents = !flags.includes('--xgent-init') && !flags.includes('--no-xgent-init') && !agentsExists;
+  const askGuard = !flags.includes('--context-goal-guard') && !flags.includes('--no-context-goal-guard')
+    && codexThreshold === undefined;
+  const askClaudeGuard = !flags.includes('--claude-context-goal-guard') && !flags.includes('--no-claude-context-goal-guard')
+    && claudeThreshold === undefined;
+  // 各询问共享输入迭代器,避免前一问提前读掉后一问的回答。
+  const rl = process.stdin.isTTY && (askAgents || askGuard || askClaudeGuard)
+    ? readline.createInterface({ input: process.stdin, output: process.stdout }) : null;
+  const answers = rl?.[Symbol.asyncIterator]();
+  rl?.once('SIGINT', () => { rl.close(); process.exit(130); });
+  let agents;
+  let guard;
+  let claudeGuard;
+  try {
+    agents = flags.includes('--xgent-init') || (askAgents && await confirm(
+      '是否同时创建通用的 AGENTS.md (含 Portal 联调与前端验收约定)? [y/N] ',
+      '  跳过  AGENTS.md:非交互环境,可加 --xgent-init 创建', answers));
+    guard = flags.includes('--context-goal-guard') || codexThreshold !== undefined || (askGuard && await confirm(
+      `是否安装 Codex goal 上下文收尾提醒 (默认超过 ${CONTEXT_GOAL_GUARD_DEFAULT_THRESHOLD}% 时提醒收尾,需 Python 3.9+ 与 Codex 内手动信任)? [y/N] `,
+      '  跳过  Codex goal guard:非交互环境,可加 --context-goal-guard 安装', answers));
+    claudeGuard = flags.includes('--claude-context-goal-guard') || claudeThreshold !== undefined || (askClaudeGuard && await confirm(
+      `是否安装 Claude Code goal 上下文收尾提醒 (默认超过 ${CLAUDE_CONTEXT_GOAL_GUARD_DEFAULT_THRESHOLD}% 时提醒收尾并在回合结束时暂停 goal,需重启会话并信任工作区)? [y/N] `,
+      '  跳过  Claude Code goal guard:非交互环境,可加 --claude-context-goal-guard 安装', 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 });
@@ -581,14 +835,20 @@ function install(args) {
     console.log('  提示  在 agent 对话里(不是终端)输入 /impeccable init 完成 impeccable 的设计上下文');
   }
 
-  console.log('  提示  项目文档由 xgent-init skill 生成(npx skills add XGENT-ai/skills --skill xgent-init)');
+  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}`);
 }
 
 const [cmd, ...args] = process.argv.slice(2);
 switch (cmd) {
   case 'install':
-    install(args);
+    install(args).catch((error) => {
+      console.error(`错误: ${error.message}`);
+      process.exitCode = 1;
+    });
     break;
   case undefined:
   case 'help':