@xgent-ai/skills 0.7.7 → 0.7.9

package/README.md

@@ -2,6 +2,8 @@
 
 XGENT 的 [Agent Skills](https://skills.sh) 集合,可安装到 Claude Code、Cursor、Codex 等支持 skill 的 Agent 中。
 
+版本变更与历史记录见 [CHANGELOG.md](CHANGELOG.md)。
+
 ## 安装
 
 列出并选择安装公开的 skills (`xgent-init` 是内部初始化 skill,不在默认列表中):
@@ -20,25 +22,19 @@ npx skills add XGENT-ai/skills --skill dev-plan
 
 ## 项目辅助工具（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` 中启用对应配置,装上随包的 [Phoenix UI](#phoenix-ui) 设计工具,并可选创建通用的 `AGENTS.md`、安装 Codex 或 Claude Code 的 goal 上下文收尾提醒。npm 发布包与仓库的 `xgent-skills install` 统一默认安装 [Phoenix Diagram](docs/phoenix-diagram.md)。发布仅从 `main` 执行，不创建独立发布分支；Diagram 必须具备匹配版本的四平台 release 资源和公共下载地址，当前开发清单不能直接发布:
+本仓库同时以 [`@xgent-ai/skills`](https://www.npmjs.com/package/@xgent-ai/skills) 发布到 npm,自带 `xgent-skills` 命令,可为任意项目安装 XGENT 的 Claude Code hooks(当前包含 statusline)、在项目 `.claude/settings.json` 中启用对应配置,装上随包的 [Phoenix UI](#phoenix-ui) 设计工具,并可选安装 Codex 或 Claude Code 的 goal 上下文收尾提醒。npm 发布包与仓库的 `xgent-skills install` 统一默认安装 [Phoenix Diagram](docs/phoenix-diagram.md):
 
 ```bash
 # 在目标项目根目录执行(也可显式传目录:npx @xgent-ai/skills install <dir>)
 npx @xgent-ai/skills install
 ```
 
-0.7.3 补齐了 npx 默认入口。旧版 0.7.2 会报 `could not determine executable to run`,使用该版本时请显式指定安装器:
-
-```bash
-npx --package=@xgent-ai/skills@0.7.2 xgent-skills install
-```
-
 选项:
 
 | 选项 | 说明 |
 | --- | --- |
 | `--no-phoenix-ui` | 跳过 Phoenix UI,仍安装 XGENT 的 hooks 与 settings;不删除已装版本 |
-| `--no-impeccable` | 已弃用,等同 `--no-phoenix-ui`,保留一个迁移主版本 |
+| `--no-impeccable` | 已弃用,请改用 `--no-phoenix-ui` |
 | `--replace-impeccable` | 删除所选工具目录中的项目级及个人级 impeccable 入口和 hooks,不备份 |
 | `--keep-impeccable` | 保留 impeccable,与 Phoenix UI 共存;无交互环境默认采用 |
 | `--no-phoenix-diagram` | 跳过独立 Phoenix Diagram,不删除已装版本 |
@@ -46,8 +42,6 @@ npx --package=@xgent-ai/skills@0.7.2 xgent-skills install
 | `--confirm-remove-archify` | 与迁移配用的显式确认;旧 skill 不备份,回滚不重建,非交互迁移必须提供 |
 | `--release-dir=DIR` | 离线安装 Phoenix UI engine:使用已核验的 release 目录,不联网 |
 | `--diagram-release-dir=DIR` | 为 Phoenix Diagram 使用匹配的完整离线目录 |
-| `--xgent-init` | 直接创建仓根 `AGENTS.md` (已有则跳过),不再询问 |
-| `--no-xgent-init` | 跳过创建 `AGENTS.md`,不再询问 |
 | `--providers=a,b` | 指定 Phoenix 工具的 harness 目录(如 `--providers=.claude,.cursor`);`codex` 识别 `.agents/.codex`,Diagram skill 只写 `.agents`;默认按已有目录选择,空项目用 `.claude` |
 
 Phoenix UI 和 Phoenix Diagram skill 均由 npm 安装器随匹配引擎安装与更新，已通过 `metadata.internal: true` 从 `npx skills add XGENT-ai/skills` 的默认发现列表排除，避免独立更新 skill 后与引擎版本不一致。
@@ -56,29 +50,22 @@ Phoenix UI 和 Phoenix Diagram skill 均由 npm 安装器随匹配引擎安装
 
 普通安装不移除 Archify。`--migrate-archify` 使用独立的 Diagram 迁移分支,仅处理精确项目/provider 的完整已知来源;自定义、链接、外部管理与个人入口保留。TTY 拒绝或 EOF 不迁移;`--no-phoenix-diagram` 仍跳过并保留。旧入口移除后需要时按原来源重装,新 Diagram 入口的恢复/回滚见[迁移说明](docs/phoenix-diagram.md#旧入口迁移与安装恢复)。仓库只保留新活跃入口,不代表其他项目或个人旧安装已被处理。
 
-`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` 时直接跳过并保留原文。
-
-非交互环境默认跳过,可用 `--xgent-init` 显式创建,或用 `--no-xgent-init` 跳过询问。文件位于仓根,不受 `--providers` 影响。模板没有待填占位,通用编码准则支持不同 coding agent;Portal App 的 onebox 联调与有前端改动时的真实浏览器验收分别按适用条件执行。
-
-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
-```
+`install` 不创建或修改 `AGENTS.md`,也不询问是否安装模板。安装完成后会提示:可在 agent 对话中使用 [optimize-agents-md](skills/optimize-agents-md/SKILL.md),以 opinionated DSL(Odyssey/ODC)改良已有的 `AGENTS.md`;不喜欢这套风格可以忽略。Claude Code 用 `/optimize-agents-md`,Codex 用 `$optimize-agents-md`,由用户自行选择是否使用。
 
 ## Phoenix UI
 
+只有 `phoenix-ui` skill 随 Phoenix UI 工具附带，`phoenix-diagram` skill 随 Phoenix Diagram 工具附带；其余所有 skill 均独立于这两个工具。
+
 Phoenix UI 是 XGENT 自主维护的设计工具:从 [impeccable](https://github.com/pbakaus/impeccable) 4.5.0 / engine 0.1.11 的固定源码承接(Apache-2.0,来源与修改见 `dist/phoenix-ui/NOTICE.md`),版本、规则与发布由本仓控制,不再查询或下载上游 latest。它只随 npm 安装器分发:`install` 只装入 `phoenix-ui` skill、对应 hooks 与固定 engine。design-md、design-reference、ui-pattern-research、review-ui、apply-ui-review 由 `npx skills add XGENT-ai/skills` 独立安装和更新,Phoenix 不覆盖或比对它们的版本。对话里用 `/phoenix-ui`(Codex 用 `$phoenix-ui`);终端命令为 `npm exec --package=@xgent-ai/skills -- phoenix-ui --help`。
 
 Phoenix UI 适用于独立网站、应用和嵌入式界面等 UI 项目。`phoenix-ui init` 可独立完成产品上下文初始化,不依赖 `xgent-init`。subagent 与并行策略由 coding agent 自主安排,Phoenix 不额外要求询问或等待授权。
 
-- **engine**:按包内 `dist/phoenix-ui/VERSION.json` 的摘要校验后放进 `~/.phoenix-ui/bin/<版本>/<平台>/<engineSha256>/`(`PHOENIX_UI_HOME` 可改),新旧项目的引擎可共存,本期支持 darwin-arm64、darwin-x64、linux-x64、linux-arm64,Windows 延期。不可用时整个安装在写项目前停止,可改用 `--release-dir=DIR` 离线安装或 `--no-phoenix-ui`。hook 与 context 运行时不联网补下载。
-- **已有工具**:安装时发现 impeccable 会询问是否替换。选择替换则直接删除所选 provider 的项目级及个人级旧入口和旧 hooks,不备份、不留转跳入口;选择保留则共存,不阻止 Phoenix 安装,无交互环境默认保留。没有安装事务状态的 Phoenix 源码副本直接删除后重装。业务源码、旧工具的数据和文档不改动;共享配置中的其他 hooks 保留。
-- **回滚**:安装输出给出事务 ID、备份位置与完整命令,例如 `npm exec --package=@xgent-ai/skills@<版本> -- phoenix-ui migrate --rollback <事务ID> --project <项目>`;回滚只撤销本次安装的条目,后来新增的配置保留。
+- **engine**:按包内 `dist/phoenix-ui/VERSION.json` 的摘要校验后放进 `~/.phoenix-ui/bin/<版本>/<平台>/<engineSha256>/`(`PHOENIX_UI_HOME` 可改),新旧项目的引擎可共存,支持 darwin-arm64、darwin-x64、linux-x64、linux-arm64;不支持 Windows。不可用时整个安装在写项目前停止,可改用 `--release-dir=DIR` 离线安装或 `--no-phoenix-ui`。hook 与 context 运行时不联网补下载。
+- **已有工具**:Phoenix UI 和 Diagram 都是可重新安装的工具：安装直接覆盖工具文件，不备份旧版、不创建安装事务目录，不提供普通安装回滚。中断后重跑安装即可；成功安装会清理旧安装记录和备份。业务源码、工具生成的业务数据及其他 hooks 保留。发现 impeccable 时仍可选择替换或共存，无交互环境默认保留。
 
-安装、迁移、回滚、支持矩阵与渠道说明见 [docs/phoenix-ui.md](docs/phoenix-ui.md)。原 `vendor/impeccable/` 副本及其 vendor/R2 脚本已删除,需要时从 git 历史查看。
+安装、迁移、支持矩阵与渠道说明见 [docs/phoenix-ui.md](docs/phoenix-ui.md)。
 
-managed UI 循环先核对固定包 engine，再用 `phoenix-ui review --help` 和 `phoenix-ui review schema --json` 发现 verbs 与输入形状；后者是 typed examples，样例不是真实证据。具体调用与恢复边界见 [Phoenix 评审协议](skills/review-ui/references/phoenix-review.md)。
+选择 Phoenix CLI 管理评审记录时，用 `phoenix-ui review --help` 和 `phoenix-ui review schema --json` 发现 verbs 与输入形状；后者是 typed examples，样例不是真实证据。具体调用与恢复边界见 [Phoenix 评审协议](docs/phoenix-ui-review.md)。
 
 ## Skills 列表
 
@@ -91,8 +78,8 @@ managed UI 循环先核对固定包 engine，再用 `phoenix-ui review --help`
 | Skill | 说明 |
 | --- | --- |
 | [prd](skills/prd/SKILL.md) | 撰写或优化 PRD，明确产品目标、FR/NFR、UAT、分期与终验，可按授权录入 SPMS |
-| [crd](skills/crd/SKILL.md) | 固定由提出方使用：起草或修订需求、整合接收方回复、答复反问并维护需求与 Q&A 当前视图 |
-| [crd-respond](skills/crd-respond/SKILL.md) | 固定由接收方评估、答复 CRD 或回告实现结果；需改码时生成带来源 CR 与完成回写约定的计划，不实施。仅原样追加/收录不重评或生成计划 |
+| [crd](skills/crd/SKILL.md) | 固定由提出方使用：起草或修订需求、整合接收方回复；基于目标和长期成本明确本方立场，收敛契约及 Q&A，不将未发送等同草案 |
+| [crd-respond](skills/crd-respond/SKILL.md) | 固定由接收方独立评估长期方案、明确本方结论并收敛 CRD 答复，或回告实现结果；需改码时生成带来源 CR 与完成回写约定的计划，不实施。仅原样追加/收录不重评或生成计划 |
 | [dev-plan](skills/dev-plan/SKILL.md) | 基于需求、仓库规则与代码事实撰写或评审可执行计划，明确开发对象、排除与外部前置；CR 来源可追溯，对应请求完成后回写答复，支持跨对话续做 |
 | [spec-human-decision](skills/spec-human-decision/SKILL.md) | 逐项讲清 PRD 或开发计划的功能与价值，计划另述做法；交互选择确认、驳回、修改并打磨文档，修改须附说明 |
 | [test-plan](skills/test-plan/SKILL.md) | 从需求与验收标准生成测试用例，覆盖正常、边界、权限和并发场景，可按授权写入 SPMS |
@@ -102,10 +89,10 @@ managed UI 循环先核对固定包 engine，再用 `phoenix-ui review --help`
 | [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) | 核实代码评审意见，实施合理修复、验证结果并回写实现记录与必要进度 |
-| [review-ui](skills/review-ui/SKILL.md) | 代码评审后可选的 UI/UX 验收：只认运行中界面的实拍截图与实测，不凭代码推断效果；由全新上下文的独立评审按冻结的目标包打分并列出可执行差距，默认每个单元 ≥ 8/10 且没有未关闭的 P0/P1 才通过 |
-| [apply-ui-review](skills/apply-ui-review/SKILL.md) | 按 UI 验收报告对照截图与目标核实并修复界面差距、自检；停滞预警时重构思路，提交登记后交回复审 |
+| [review-ui](skills/review-ui/SKILL.md) | 代码评审后可选的 UI/UX 验收：真实界面增量取证，同状态多问题共用截图，复用有效历史与 apply 材料；默认一位独立评审检查变化和未关闭项，继承未受影响的已通过结论，默认每个单元 ≥ 8/10 且没有未关闭的 P0/P1 才通过；需补证时交 apply-ui-review 执行补证后独立复审 |
+| [apply-ui-review](skills/apply-ui-review/SKILL.md) | 按 UI 验收报告执行修复、补证与解阻，对照截图与目标核实并自检；停滞预警先诊断，有结构性根因才重构，提交登记后交回复审 |
 | [apply-doc-review](skills/apply-doc-review/SKILL.md) | 可只传评审报告，沿报告的原文档引用定位并修订 PRD 或开发计划，复核并记录逐条处置结果 |
-| [resolve-blocked](skills/resolve-blocked/SKILL.md) | 查证与交互推进计划解阻，外部依赖通过 CRD 交接，存 decisions 并回改计划；最终集中列全剩余阻塞、各方交付和用户具体动作 |
+| [resolve-blocked](skills/resolve-blocked/SKILL.md) | 查证解阻；需用户拍板、补证或协调外部依赖时用工具阻断式问答，外部请求用 CRD 交接，存 decisions 并回改计划，最终列全剩余阻塞和用户动作 |
 
 把上述 skill 串成完整交付流水线（想法 → PRD → 分期 → 每期开发与并行测试 → 交付）的方法见 [AI Native SDLC](docs/ai-native-sdlc.md)，含各环节产物路径约定与测试线待补环节的现状核对。
 
@@ -114,12 +101,12 @@ managed UI 循环先核对固定包 engine，再用 `phoenix-ui review --help`
 需要逐项确定功能取舍时，可在 PRD 或开发计划成稿后使用 `spec-human-decision <文档>`：每项简述功能与价值，开发计划另述做法；选择确认、驳回或附说明修改，修订版再确认，并同步文档与决定记录。这是可选的用户决策环节，技术评审与开工条件仍按下述回路核对。
 
 1. （可选）`prd` → `review-prd <PRD>`：需要修改时 `apply-doc-review <报告>`；可交接后 `dev-plan <PRD> P1`。临时或小任务可直接从 `dev-plan` 开始。
-2. `dev-plan` → `review-dev-plan <计划>`：需要修改时 `apply-doc-review <报告>`；之后 `Blocked` 用 `resolve-blocked <计划>`，自行查证、交互补齐前置，收到答复后继续处理，外部缺口实际用 `crd` 创建/续写本地请求，不自动发送；最终开头列全剩余阻塞、各方需提供什么、用户具体动作和解除条件，不只给重跑命令。先推进具体 CR 或本方验证，解除条件满足后再运行以重判就绪，`Ready` 用 `/goal 按 <计划> 开发`。从 PRD 派生的计划在顶部「需求来源」记录 PRD 与期次，开发范围区分本方改动与外部前置，不因端到端目标代建依赖系统。
+2. `dev-plan` → `review-dev-plan <计划>`：需要修改时 `apply-doc-review <报告>`；之后 `Blocked` 用 `resolve-blocked <计划>`，自行查证，需用户处理的决定、前置和跨项目协调必须用 Ask User 类工具提出并等待明确答复，不能仅输出聊天消息；收到答复后继续处理，外部缺口实际用 `crd` 创建/续写本地请求，不自动发送；最终开头列全剩余阻塞、各方需提供什么、用户具体动作和解除条件，不只给重跑命令。先推进具体 CR 或本方验证，解除条件满足后再运行以重判就绪，`Ready` 用 `/goal 按 <计划> 开发`。从 PRD 派生的计划在顶部「需求来源」记录 PRD 与期次，开发范围区分本方改动与外部前置，不因端到端目标代建依赖系统。
 3. `/goal` 开发：按计划的提交点分阶段提交，全部里程碑完成后最终提交，SHA 记入完成记录，结束时提示 `review-code <计划>`。来自 CR 的计划按顶部合同，在对应请求或明确子范围实现且约定检查通过后追加实现结果答复，保留历史、余项及回告链接；不等同发布或对方验收，未能回写时保留恢复动作。
 4. `review-code <计划>` 从完成记录登记的提交与未提交改动确定范围：需要修改时 `apply-code-review <报告>`（按计划约定提交修复并登记 SHA），再回到 `review-code <计划>` 复审，直到通过验收或你明确本期放过。
-5. （可选）计划涉及界面时，`review-ui <计划>` 做 UI/UX 验收：每轮按目标包截图，由全新上下文的独立评审打分。需要修改时 `apply-ui-review <报告>`（按计划约定提交并登记 `UI修复` SHA），再回到 `review-ui <计划>` 复审，直到通过（默认每个单元 ≥ 8/10 且没有未关闭的 P0/P1）、停滞后交你裁定，或你明确放过。UI 修复带来代码改动时，再用 `review-code <计划>` 复审这些改动。
+5. （可选）计划涉及界面时，`review-ui <计划>` 做 UI/UX 验收：按影响范围自动检查与采集代表帧，同页同状态共用截图；复用有效历史证据及已通过结论，默认一位全新上下文的独立评审，不按接近门槛自动增加评审。需要修改时 `apply-ui-review <报告>`（按计划约定提交并登记 `UI修复` SHA），再回到 `review-ui <计划>` 复审，直到通过（默认每个单元 ≥ 8/10 且没有未关闭的 P0/P1）、停滞后交你裁定，或你明确放过。UI 修复带来代码改动时，再用 `review-code <计划>` 复审这些改动。 需补证时同样交给 `apply-ui-review <报告>`，由执行 agent 补齐环境、数据与实测材料、处理差距后交回 `review-ui <计划或原范围>` 独立复审；只缺独立评审时续接 review-ui。仅无法自行取得的权限、资料或产品决定请求用户提供。没有代码、证据或阻塞条件变化时不新增轮次。
 
-   UI 循环可沿用人工 Markdown，或通过匹配的 Phoenix engine 管理证据与轮次。已有 managed 索引时从原轮与 revision 续接；engine 缺失、版本不匹配或状态损坏时保持只读，恢复固定版本后再继续。人工历史只经明确的 `review import` 接管，不能清零未知次数；CLI 操作成功不代表 UI 通过，真实取证和独立评审仍是判定依据。
+   UI 验收是独立的 agent 工作流，依据目标、真实证据和 Markdown 历史继续，不绑定工具、规则版本或文档指纹。可选用 Phoenix CLI 管理记录；不可用时保留其状态文件，继续记录评审与修复结果。CLI 操作成功不代表 UI 通过。
 6. 通过后，计划来自 PRD 时可选 `review-prd-dev-gaps <计划>`；生成 gaps plan 时从第 2 步的 `review-dev-plan <gaps 计划>` 继续。
 
 **跨项目入口按角色固定**：提出方始终用 `crd` 起草/修订需求、整合接收方返回稿、答复反问；接收方始终用 `crd-respond <CRD>` 评估/答复需求、续接提出方澄清或回告实现结果。双方收到文件或追加消息都不切换角色，归属不明先核实。接收方默认在原文末追加有证据的评估答复，需改本方代码时实际调用 `dev-plan`（未决契约按就绪门标 `Blocked`），计划记录来源 CR、承接请求/子范围、回写文件与顶部完成回写约定，生成计划从第 2 步继续；完成回告核对适用证据后追加 RESP，不重开规划或改写历史。仅原样追加/收录不重新评估或生成计划，仅评估不落盘，仅答复不生成计划，不自动发送或实施。
@@ -138,13 +125,13 @@ $review-ui [开发计划] [页面URL/路由] [设计稿/目标图] [上轮报告
 $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。
+参数提示的展示取决于客户端对 `argument-hint` 的支持。未展示时可直接参考上述用法或各技能的 frontmatter。
 
 5 个 `review-*` 支持“对照上轮报告复审修复效果”：逐项保留来源 ID，区分已解决、仍存在、部分解决、回归、待核实、不再适用和本轮未复核；新增问题单列，默认另存报告。代码旧问题的复核不受本次修复 diff 限制。`review-prd-dev-gaps` 会先核对已有 gaps plan，支持“仅报告”，避免重复规划。
 
 `apply-doc-review` 与 `apply-code-review` 支持“继续修复”与“仅复核”：前者处理剩余问题，后者保留目标产物并保存必要处置记录；完全只读则仅聊天交付。重复执行先核对已有证据，无实质变化不改文件或时间；apply 的复核不自动成为新一轮独立 review。
 
-项目状态与下一步能力已合并到 `agi-mode` 的 [what-next 流程](skills/agi-mode/playbooks/what-next.md)，不再单独发布 `what-next` skill。查询默认只读；初始化/更新才保存，既有执行授权继续有效。
+项目状态与下一步查询使用 `agi-mode` 的 [what-next 流程](skills/agi-mode/playbooks/what-next.md)。查询默认只读；初始化/更新才保存，既有执行授权继续有效。
 
 ```text
 使用 $agi-mode sdlc，解释从需求、CRD 往返到开发、验收和发布的交接。
@@ -220,15 +207,15 @@ $agi-mode <任务描述> 或 sdlc [流程/阶段/问题] 或 init-sdlc [PRD/计
 
 只需安装 `agi-mode` 即可使用上述流程；保留的 `autoresearch`、`arena`、`reflect` 名称是兼容入口，需要同时安装 `agi-mode`。它们不再独立维护执行规则。
 
-明确要求优化仓库指令时，可使用 `$optimize-agents-md [repo 路径] [文件范围] [仅诊断]`，默认处理当前代码仓库的根 AGENTS.md。它默认可发现，普通编码、初始化或全局规则修改不进入该流程；仅诊断保持只读。优化时使用已安装的 `use-prompt-dsl` 的 `compose`（默认操作）将原则压缩为 Odyssey RULE 片段（直接嵌入 AGENTS.md，无外层包装），按语义去重并补齐 Think Before Coding 与十二项 Coding Principles，保留项目事实、授权和作用域。缺少 DSL skill 时停止，建议完整安装本仓 skills；安装检查和优化流程只属于 skill，不写进目标 AGENTS.md。无需同仓评测任务或远端配置，文件精简不等于已证明行为质量提升。
+明确要求优化仓库指令时，可使用 `$optimize-agents-md [repo 路径] [文件范围] [仅诊断]`，默认处理当前代码仓库的根 AGENTS.md。它默认可发现，普通编码、初始化或全局规则修改不进入该流程；仅诊断保持只读。优化时使用已安装的 `use-prompt-dsl` 的 `compose`（默认操作）将原则压缩为 Odyssey RULE 片段（直接嵌入 AGENTS.md，无外层包装），按语义去重并补齐原则素材中缺失的编码准则，保留项目事实、授权和作用域。缺少 DSL skill 时停止，建议完整安装本仓 skills；安装检查和优化流程只属于 skill，不写进目标 AGENTS.md。无需同仓评测任务或远端配置，文件精简不等于已证明行为质量提升。
 
-独立的 agi-mode [远端执行工具](skills/agi-mode/references/remote-evolution.md) 提供 `validate / run / resume / apply`，优化器、被测 agent 与固定验收使用 SSH 主机上的独立环境。默认搜索 keep 只更新探索最佳，独立确认和原则核对通过后才在已有写回授权内按 CAS 采用；显式获准的 v2 `bounded_exploration_v1` 仅允许质量门通过、来源精度不足时探索一个候选，不晋级最佳、不确认/采用，整体 inconclusive。不自动提交、发布或安装全局配置。首期v1已在指定SSH/Docker组合完成真实隔离、任务对照/搜索、自然请求/CAS与故障恢复验收，但独立确认样本不足，未证明候选优于基线。v2现按已有结果阶段交付：工程和已测子范围可用，完整skill三条件及TypeSafe反馈进入真实optimizer尚未验收，没有已证实的指令收益；资源到位后再按3分目标续跑，详见[M4阶段记录](docs/plan/agent-instruction-evolution-v2.records/M4.md#2026-10-22-阶段交付)。
+独立的 agi-mode [远端执行工具](skills/agi-mode/references/remote-evolution.md) 提供 `validate / run / resume / apply`，优化器、被测 agent 与固定验收使用 SSH 主机上的独立环境。默认搜索 keep 只更新探索最佳，独立确认和原则核对通过后才在已有写回授权内按 CAS 采用；显式获准的 v2 `bounded_exploration_v1` 仅允许质量门通过、来源精度不足时探索一个候选，不晋级最佳、不确认/采用，整体 inconclusive。不自动提交、发布或安装全局配置。验收范围与运行结果见 [CHANGELOG.md](CHANGELOG.md) 及其引用的阶段记录。
 
 自然发现验收可用 `source.fixed_skill_roots` 显式提供完整固定背景目录，目标缺席/候选切换保持其他技能字节；实际目录、读取与任务行为分别记录，单独的目标技能执行不代表完整目录发现已通过。
 
 v2运行质量项可显式声明`verifier/`公开观测文件，按白名单接收固定grader的实际运行事实；验收分与运行证据分开，缺证据保持unknown，独立观测不替代新增回归测试。
-新百分表保留其他已知分项，不因单项unknown全表清空；已知硬失败控制可显式声明不可观察的非gate项并要求双评一致未知，成功控制、底线、排序及辅助资格保持严格。
-新百分rubric还可显式让程序从已校验逐项判断派生评审状态，避免把产物失败误作测量无效；旧协议默认保持，新格式需重新校准。
+百分制评分表保留其他已知分项，不因单项unknown全表清空；已知硬失败控制可显式声明不可观察的非gate项并要求双评一致未知，成功控制、底线、排序及辅助资格保持严格。
+百分制 rubric 可显式让程序从已校验逐项判断派生评审状态，避免把产物失败误作测量无效；旧协议默认保持，新格式需重新校准。
 固定预算项可显式要求双评数值及校准固定参考完全相同，分歧保持unknown及原分；缺省程度容差保持，同分仍须核对依据，详见远端手册。
 
 v2自有仓任务可显式使用`case.platform=linux/arm64`和匹配的固定镜像；默认及v1/Pro V2仍amd64。平台改变后重新校准，不能迁移旧分或资格；详见[远端手册](skills/agi-mode/references/remote-evolution.md)。
@@ -269,7 +256,7 @@ v2自有仓任务可显式使用`case.platform=linux/arm64`和匹配的固定镜
 
 | Skill | 说明 |
 | --- | --- |
-| [xgent-init](skills/xgent-init/SKILL.md) | 内部初始化 skill,补齐 `AGENTS.md` / `PRODUCT.md` / `DESIGN.md`,保留 Portal 产品边界与设计规范;`install` 仅直接创建 AGENTS.md |
+| [xgent-init](skills/xgent-init/SKILL.md) | 内部初始化 skill,补齐 `AGENTS.md` / `PRODUCT.md` / `DESIGN.md`,保留 Portal 产品边界与设计规范 |
 | [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 交互 |

package/bin/xgent-skills.js

@@ -13,7 +13,6 @@ const readline = require('node:readline');
 
 const PKG_ROOT = path.join(__dirname, '..');
 const HOOKS_SRC_DIR = path.join(PKG_ROOT, '.claude', 'hooks');
-const AGENTS_TEMPLATE = path.join(PKG_ROOT, 'skills', 'xgent-init', 'references', 'external-app-AGENTS.template.md');
 
 // 写入目标项目 .claude/settings.json 的配置,按顶层 key 合并:
 // 这里列出的 key 以本包为准覆盖,其余已有配置保持不动。
@@ -26,7 +25,7 @@ const MANAGED_SETTINGS = {
 };
 
 // ─── Phoenix UI ─────────────────────────────────────────────────────────────
-// Phoenix 的受管安装、hooks 与回执由 Rust 执行器事务化完成。
+// Phoenix 工具文件由 Rust 执行器直接覆盖,共享 hooks 只更新本工具条目。
 // 旧工具是否删除由 npm 安装入口询问,工具清理不备份、不迁移旧数据。
 
 const bootstrap = require('../skills/phoenix-ui/scripts/phoenix-bootstrap.cjs');
@@ -101,10 +100,8 @@ function preparePhoenixTools(project, providers) {
         }
       }
     }
-    if (!fs.existsSync(path.join(project, '.phoenix-ui/install'))) {
-      const file = checked(project, `${provider}/skills/phoenix-ui`);
-      if (present(file)) refresh.push(file);
-    }
+    const file = checked(project, `${provider}/skills/phoenix-ui`);
+    if (fs.lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink()) refresh.push(file);
   }
   const oldCommand = value => typeof value === 'string'
     && /(?:skills[\\/]impeccable[\\/]scripts[\\/](?:impeccable(?:\.cmd)?|hook(?:-(?:probe|before-edit|after-edit|stop))?\.mjs)|(?:^|[\s"'])impeccable\s+hook\b)/.test(value);
@@ -201,17 +198,15 @@ function runDiagram(binary, args) {
 
 function prepareDiagramTools(project, providers) {
   const refresh = [];
-  if (!fs.lstatSync(path.join(project, '.phoenix-diagram/install'), { throwIfNoEntry: false })) {
-    for (const provider of providers.filter(name => name !== '.codex')) {
-      const relative = `${provider}/skills/phoenix-diagram`;
-      const file = path.join(project, relative);
-      const stat = fs.lstatSync(file, { throwIfNoEntry: false });
-      if (!stat) continue;
-      for (let dir = path.dirname(file); dir !== project; dir = path.dirname(dir)) {
-        if (fs.lstatSync(dir).isSymbolicLink()) throw phoenixFailure(3, `工具目录的父路径是符号链接,未修改: ${dir}`);
-      }
-      refresh.push({ file, relative, linked: stat.isSymbolicLink() });
+  for (const provider of providers.filter(name => name !== '.codex')) {
+    const relative = `${provider}/skills/phoenix-diagram`;
+    const file = path.join(project, relative);
+    const stat = fs.lstatSync(file, { throwIfNoEntry: false });
+    if (!stat?.isSymbolicLink()) continue;
+    for (let dir = path.dirname(file); dir !== project; dir = path.dirname(dir)) {
+      if (fs.lstatSync(dir).isSymbolicLink()) throw phoenixFailure(3, `工具目录的父路径是符号链接,未修改: ${dir}`);
     }
+    refresh.push({ file, relative, linked: true });
   }
   return {
     covers(conflict) {
@@ -242,10 +237,7 @@ async function prepareDiagram(targetDir, options) {
     const tools = prepareDiagramTools(targetDir, planned.report.providers || []);
     const reinstallable = planned.code === 3 && planned.report.status === 'conflict'
       && planned.report.conflicts.length > 0 && planned.report.conflicts.every(conflict => tools.covers(conflict));
-    // A known pending transaction is recovered only by the later explicit apply.
-    const recoverable = planned.code === 3 && planned.report.status === 'recovery-required'
-      && planned.report.conflicts?.length === 0;
-    if (!reinstallable && ((planned.code !== 0 && !recoverable) || !['planned', 'unchanged', 'recovery-required'].includes(planned.report.status))) {
+    if (!reinstallable && (planned.code !== 0 || !['planned', 'unchanged'].includes(planned.report.status))) {
       printDiagram(planned.report, ready.manifest);
       throw phoenixFailure(planned.code || 3, 'Phoenix Diagram 预检失败');
     }
@@ -336,12 +328,17 @@ function printPhoenix(report, manifest) {
   }
   for (const entry of report.transitionEntries) console.log(`  提示  ${entry} 保留一个迁移主版本,只指向新命令`);
   for (const conflict of report.conflicts) console.log(`  冲突  ${conflict.path}: ${conflict.message}`);
-  for (const finding of report.findings) console.log(`  ${finding.blockingIntegration ? '待处理' : '说明'}  ${finding.path}: ${finding.message}`);
+  for (const finding of report.findings) {
+    if (!finding.blockingIntegration && ['document-old-entry', 'personal-old-command'].includes(finding.kind)) continue;
+    console.log(`  ${finding.blockingIntegration ? '待处理' : '说明'}  ${finding.path}: ${finding.message}`);
+  }
   for (const item of report.unconsumed) console.log(`  未迁移  ${item.path} ${item.field}: ${item.reason}`);
   if (report.transactionId && ['installed', 'integration-pending'].includes(report.status)) {
     console.log(`  事务  ${report.transactionId};备份 ${report.backups}`);
     const project = bootstrap.shellQuote(report.project);
     console.log(`  回滚  npm exec --package=@xgent-ai/skills@${npmPackageVersion} -- phoenix-ui migrate --rollback ${report.transactionId} --project ${project}`);
+  }
+  if (['installed', 'integration-pending'].includes(report.status)) {
     for (const provider of skillProviders) console.log(`  重载  ${reloadStep(provider)}`);
   }
 }
@@ -356,17 +353,6 @@ async function confirm(question, skipMessage, answers) {
   return /^(y|yes)$/i.test(value.trim());
 }
 
-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>
 
@@ -374,8 +360,7 @@ function usage() {
   install [dir]   为目标项目(默认当前目录)安装 .claude/hooks 下的全部
                   hook,在 .claude/settings.json 中启用对应配置,并安装
                   Phoenix UI(设计 skill 与 hooks;engine 校验后
-                  放入用户 cache;旧 impeccable 可选择替换或共存),
-${includesDiagram ? '                  以及 Phoenix Diagram(十类图解 skill 与独立原生 engine),\n' : ''}                  并询问是否创建通用的 AGENTS.md
+                  放入用户 cache;旧 impeccable 可选择替换或共存)${includesDiagram ? ',\n                  以及 Phoenix Diagram(十类图解 skill 与独立原生 engine)' : ''}
   help            显示本帮助
 
 install 选项:
@@ -384,14 +369,12 @@ install 选项:
   --replace-impeccable  删除项目及个人级旧 impeccable 工具和 hooks,不备份
   --keep-impeccable     保留 impeccable,与 Phoenix UI 共存(无交互时默认)
 ${includesDiagram ? `  --no-phoenix-diagram  跳过 Phoenix Diagram(不删除已装版本)
-  --migrate-archify     仅执行 Diagram 预检/确认/迁移,跳过 hooks/settings/AGENTS/UI;
+  --migrate-archify     仅执行 Diagram 预检/确认/迁移,跳过 hooks/settings/UI;
                         使用已存在且匹配包内固定版本的引擎,不自动获取
   --confirm-remove-archify  仅配 --migrate-archify,确认移除所选项目/provider 旧入口;
                         不备份 Archify,回滚不重建旧入口,需要时按原来源重装
 ` : ''}  --release-dir=DIR     离线安装 Phoenix UI engine:使用已核验的 release 目录,不联网
-${includesDiagram ? '  --diagram-release-dir=DIR 离线安装 Phoenix Diagram:使用匹配的完整目录,不联网\n' : ''}  --xgent-init          创建 AGENTS.md (已有则跳过),不再询问
-  --no-xgent-init       跳过 AGENTS.md,不再询问
-  --providers=a,b       指定 Phoenix 工具装进哪些 harness 目录(默认按项目里已有的
+${includesDiagram ? '  --diagram-release-dir=DIR 离线安装 Phoenix Diagram:使用匹配的完整目录,不联网\n' : ''}  --providers=a,b       指定 Phoenix 工具装进哪些 harness 目录(默认按项目里已有的
                         目录判断,都没有时装 .claude;codex 同时选 .agents 与 .codex)
 `);
 }
@@ -399,7 +382,7 @@ ${includesDiagram ? '  --diagram-release-dir=DIR 离线安装 Phoenix Diagram:
 async function install(args) {
   const flags = args.filter((a) => a.startsWith('--'));
   const dirArg = args.find((a) => !a.startsWith('--'));
-  const unknown = flags.filter((f) => !['--no-phoenix-ui', '--no-impeccable', '--replace-impeccable', '--keep-impeccable', '--xgent-init', '--no-xgent-init',
+  const unknown = flags.filter((f) => !['--no-phoenix-ui', '--no-impeccable', '--replace-impeccable', '--keep-impeccable',
     ...(includesDiagram ? ['--no-phoenix-diagram', '--migrate-archify', '--confirm-remove-archify'] : [])].includes(f)
     && !['--providers=', '--release-dir=', ...(includesDiagram ? ['--diagram-release-dir='] : [])].some((p) => f.startsWith(p)));
   if (unknown.length > 0) {
@@ -408,10 +391,6 @@ async function install(args) {
     process.exit(1);
   }
   if (flags.includes('--confirm-remove-archify') && !flags.includes('--migrate-archify')) throw phoenixFailure(2, '--confirm-remove-archify 需要 --migrate-archify');
-  if (flags.includes('--xgent-init') && flags.includes('--no-xgent-init')) {
-    console.error('错误: --xgent-init 与 --no-xgent-init 不能同时使用');
-    process.exit(1);
-  }
   if (flags.includes('--replace-impeccable') && flags.includes('--keep-impeccable')) {
     throw phoenixFailure(1, '--replace-impeccable 与 --keep-impeccable 不能同时使用');
   }
@@ -469,24 +448,18 @@ async function install(args) {
       process.exit(1);
     }
   }
-  const agentsExists = fs.existsSync(path.join(targetDir, 'AGENTS.md'));
-  const askAgents = !flags.includes('--xgent-init') && !flags.includes('--no-xgent-init') && !agentsExists;
   const phoenix = options.phoenix ? await preparePhoenix(targetDir, options) : null;
   const diagram = options.diagram ? await prepareDiagram(targetDir, options) : null;
   const askReplace = phoenix?.tools.hasLegacy && !flags.includes('--replace-impeccable') && !flags.includes('--keep-impeccable');
-  const rl = process.stdin.isTTY && (askAgents || askReplace)
+  const rl = process.stdin.isTTY && askReplace
     ? 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 replace = flags.includes('--replace-impeccable');
   try {
     if (askReplace) replace = await confirm(
       '发现旧 impeccable,是否删除并替换为 Phoenix UI(含个人级入口,不备份)? [y/N] ',
       '  保留  impeccable:无交互环境默认共存;可用 --replace-impeccable 替换', answers);
-    agents = flags.includes('--xgent-init') || (askAgents && await confirm(
-      '是否同时创建通用的 AGENTS.md (含 Portal 联调与前端验收约定)? [y/N] ',
-      '  跳过  AGENTS.md:非交互环境,可加 --xgent-init 创建', answers));
   } finally {
     rl?.close();
   }
@@ -521,16 +494,13 @@ async function install(args) {
     console.log('  写入  .claude/settings.json (statusLine)');
   }
 
-  if (agents) createAgents(targetDir);
-  else if (agentsExists && !flags.includes('--no-xgent-init')) console.log('  跳过  AGENTS.md (已存在,保留原文)');
-
-  // XGENT 部分已完成;Phoenix 在锁内重读这些文件后再应用,中断时可重试。
+  // XGENT 部分已完成;Phoenix 直接覆盖工具文件,中断后重跑。
   if (phoenix) {
     let applied;
     try {
       applied = runPhoenix(phoenix.binary, phoenix.args);
     } catch (error) {
-      console.log(`未完成: XGENT 部分已安装;Phoenix UI 待恢复(安装被中断,可能已部分写入),按下方错误处理后重跑本命令,会先按日志恢复(可重复执行)。${diagram ? 'Phoenix Diagram 未执行。' : ''}`);
+      console.log(`未完成: XGENT 部分已安装;Phoenix UI 安装未完成,处理下方错误后重跑本命令覆盖安装。${diagram ? 'Phoenix Diagram 未执行。' : ''}`);
       throw error;
     }
     printPhoenix(applied.report, phoenix.manifest);
@@ -548,7 +518,7 @@ async function install(args) {
     try {
       applied = runDiagram(diagram.binary, diagram.args);
     } catch (error) {
-      console.log(`未完成: ${completed};Phoenix Diagram 可能已部分写入,按错误和项目日志重跑恢复。`);
+      console.log(`未完成: ${completed};Phoenix Diagram 安装未完成,处理错误后重跑本命令覆盖安装。`);
       throw error;
     }
     printDiagram(applied.report, diagram.manifest);
@@ -559,6 +529,7 @@ async function install(args) {
     }
   }
   console.log(`完成: ${targetDir}`);
+  console.log('  可选  在 agent 对话中用 /optimize-agents-md(Codex 用 $optimize-agents-md)以 opinionated DSL 改良已有 AGENTS.md;不喜欢这套风格可忽略。');
 }
 
 const [cmd, ...args] = process.argv.slice(2);

package/dist/phoenix-diagram/VERSION.json

@@ -3,37 +3,37 @@
   "distribution": "release",
   "tool": "phoenix-diagram",
   "toolVersion": "0.2.0",
-  "npmPackageVersion": "0.7.7",
-  "sourceCommit": "f70b989d34ed067a556356501892e16229981faa",
-  "sourceInputSha256": "1e4a4c134dbae12345002c9c1025ed955b112afa375f2ba2c323315777876ec6",
+  "npmPackageVersion": "0.7.9",
+  "sourceCommit": "7229a8ba08f7d37bc37530e00e4d933903f1b5cf",
+  "sourceInputSha256": "910df91b4e857da6e30d8982aea308d2e1bf2d99c2d7644cb5455b37762740d9",
   "inputContractSchema": 1,
   "receiptSchema": 1,
   "viewerRevision": "phoenix-v2",
-  "bundleSha256": "58d1580a3a443f79a3aa41ee2c9000542de5a8d4b799377a4be673298ad8589e",
+  "bundleSha256": "e573234de7918dc87e1630c30a4ea1ba5862cc647dc0023a6d578ccb114e2ab6",
   "engines": {
     "darwin-arm64": {
       "asset": "phoenix-diagram-darwin-arm64",
-      "size": 17566448,
-      "sha256": "c6402d6ba1d3f2641dff8c8ed45dae0b46ce417f6a884f45fbb2e31d646f77b8",
-      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.7/darwin-arm64/phoenix-diagram-darwin-arm64"
+      "size": 17549968,
+      "sha256": "5f432a278a433bd456e8b65e0eb7a4128665f31d8c992609d6eb1cd9c48b7429",
+      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.9/ci-41410951647/darwin-arm64/phoenix-diagram-darwin-arm64"
     },
     "darwin-x64": {
       "asset": "phoenix-diagram-darwin-x64",
-      "size": 19576864,
-      "sha256": "adee5a88cf520b0cb549ea8327c3d9c50e046fadb8082f27c4360e574294a044",
-      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.7/darwin-x64/phoenix-diagram-darwin-x64"
-    },
-    "linux-x64": {
-      "asset": "phoenix-diagram-linux-x64",
-      "size": 21880592,
-      "sha256": "7d2d2e7092544d77b155c8f82a4ce64ec5ee4feec399093ff3fa38baefed9269",
-      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.7/linux-x64/phoenix-diagram-linux-x64"
+      "size": 19556424,
+      "sha256": "236384da35f4f65e892966b5912b1c1631fb4819194a7d51085076f2bc3b1a79",
+      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.9/ci-41410951647/darwin-x64/phoenix-diagram-darwin-x64"
     },
     "linux-arm64": {
       "asset": "phoenix-diagram-linux-arm64",
       "size": 19406792,
-      "sha256": "f1bebe41351ca0c384684aa585161653894cc4e06b45e0af19e566f561c42b0f",
-      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.7/linux-arm64/phoenix-diagram-linux-arm64"
+      "sha256": "0df998aed2c0d1968a94151e01e1be0ea73b62f279ff3f33fbaa2ec037e3c215",
+      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.9/ci-41410951647/linux-arm64/phoenix-diagram-linux-arm64"
+    },
+    "linux-x64": {
+      "asset": "phoenix-diagram-linux-x64",
+      "size": 21861536,
+      "sha256": "502c95c538ab6db7c4b3de80c65e7188a84a4326ba6a5a965a1c23e7b6033037",
+      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.9/ci-41410951647/linux-x64/phoenix-diagram-linux-x64"
     }
   }
 }

package/dist/phoenix-diagram/bundle/ENGINE.json

@@ -3,37 +3,37 @@
   "distribution": "release",
   "tool": "phoenix-diagram",
   "toolVersion": "0.2.0",
-  "npmPackageVersion": "0.7.7",
-  "sourceCommit": "f70b989d34ed067a556356501892e16229981faa",
-  "sourceInputSha256": "1e4a4c134dbae12345002c9c1025ed955b112afa375f2ba2c323315777876ec6",
+  "npmPackageVersion": "0.7.9",
+  "sourceCommit": "7229a8ba08f7d37bc37530e00e4d933903f1b5cf",
+  "sourceInputSha256": "910df91b4e857da6e30d8982aea308d2e1bf2d99c2d7644cb5455b37762740d9",
   "inputContractSchema": 1,
   "receiptSchema": 1,
   "viewerRevision": "phoenix-v2",
-  "bundleSha256": "58d1580a3a443f79a3aa41ee2c9000542de5a8d4b799377a4be673298ad8589e",
+  "bundleSha256": "e573234de7918dc87e1630c30a4ea1ba5862cc647dc0023a6d578ccb114e2ab6",
   "engines": {
     "darwin-arm64": {
       "asset": "phoenix-diagram-darwin-arm64",
-      "size": 17566448,
-      "sha256": "c6402d6ba1d3f2641dff8c8ed45dae0b46ce417f6a884f45fbb2e31d646f77b8",
-      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.7/darwin-arm64/phoenix-diagram-darwin-arm64"
+      "size": 17549968,
+      "sha256": "5f432a278a433bd456e8b65e0eb7a4128665f31d8c992609d6eb1cd9c48b7429",
+      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.9/ci-41410951647/darwin-arm64/phoenix-diagram-darwin-arm64"
     },
     "darwin-x64": {
       "asset": "phoenix-diagram-darwin-x64",
-      "size": 19576864,
-      "sha256": "adee5a88cf520b0cb549ea8327c3d9c50e046fadb8082f27c4360e574294a044",
-      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.7/darwin-x64/phoenix-diagram-darwin-x64"
-    },
-    "linux-x64": {
-      "asset": "phoenix-diagram-linux-x64",
-      "size": 21880592,
-      "sha256": "7d2d2e7092544d77b155c8f82a4ce64ec5ee4feec399093ff3fa38baefed9269",
-      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.7/linux-x64/phoenix-diagram-linux-x64"
+      "size": 19556424,
+      "sha256": "236384da35f4f65e892966b5912b1c1631fb4819194a7d51085076f2bc3b1a79",
+      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.9/ci-41410951647/darwin-x64/phoenix-diagram-darwin-x64"
     },
     "linux-arm64": {
       "asset": "phoenix-diagram-linux-arm64",
       "size": 19406792,
-      "sha256": "f1bebe41351ca0c384684aa585161653894cc4e06b45e0af19e566f561c42b0f",
-      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.7/linux-arm64/phoenix-diagram-linux-arm64"
+      "sha256": "0df998aed2c0d1968a94151e01e1be0ea73b62f279ff3f33fbaa2ec037e3c215",
+      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.9/ci-41410951647/linux-arm64/phoenix-diagram-linux-arm64"
+    },
+    "linux-x64": {
+      "asset": "phoenix-diagram-linux-x64",
+      "size": 21861536,
+      "sha256": "502c95c538ab6db7c4b3de80c65e7188a84a4326ba6a5a965a1c23e7b6033037",
+      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.9/ci-41410951647/linux-x64/phoenix-diagram-linux-x64"
     }
   }
 }

package/dist/phoenix-diagram/bundle/manifest.json

@@ -137,8 +137,8 @@
     },
     {
       "path": "references/migration.md",
-      "size": 6211,
-      "sha256": "9aad9f2d99eb2f2da9d2f2d656a7a7f01179862a815a6b07f3bf450fe565453a",
+      "size": 6209,
+      "sha256": "61f88625e1ffcb278db47ca1ddc7ba94ea9b1c459dfecd023125b05195c8a969",
       "mode": 420
     },
     {
@@ -233,8 +233,8 @@
     },
     {
       "path": "scripts/phoenix-bootstrap.cjs",
-      "size": 45211,
-      "sha256": "35fe87eb4e534470bc3bb2e6cc05e5483796694a8dd58f01c7702f3129132b71",
+      "size": 35018,
+      "sha256": "2b0e6f09be39d414d1d3928ed8ef8bd05f76504a03b039bca6200e5691ab0d31",
       "mode": 420
     },
     {

package/dist/phoenix-diagram/bundle/references/migration.md

@@ -36,7 +36,7 @@ dry-run只报告计划与冲突，零写入；遇pending只报告，不恢复。
 
 recover不接受dry-run；recover/rollback都不接受bundle-root、providers或confirm-remove-archify。它们核已存在的固定正确引擎与本地事务，不下载、不更新、不重装旧skill，不要求当前active安装已完整提交。
 
-普通 install 的 pending 恢复仍按其回执重跑原显式 install；`migrate --recover ID` 用于已确认的迁移或正在回滚的指定事务，不能代替普通安装恢复。优先执行对应回执的 `recoveryCommand`，不要只因有 journal ID 就改用迁移恢复命令。
+普通 install 直接覆盖工具文件，不建立事务；中断后重跑即可。成功安装会清理旧安装与迁移状态，不保留历史回滚入口。`migrate --recover ID` 仅用于仍存在的已确认迁移或回滚事务，优先执行该迁移回执的 `recoveryCommand`。
 
 - Recover继续指定已确认事务的安全剩余步骤；同一确认范围不重复索取确认。后来新增/改写、删除后重建或父目录身份变化保留并报告recovery-required；不凭stdout推断哪些文件已删。
 - Rollback仅回滚**当前committed事务**的新入口受管写入；包括仍为v1的当前事务经原生引擎验证并扩展后的回滚，不是跳过后来安装去回滚任意历史ID。后来修改在预检时冲突，先保持零变更；中途身份变化仍保留拒绝。成功rolled-back，同一ID可幂等重试。