@xgent-ai/skills 0.7.5 → 0.7.6

package/docs/phoenix-diagram.md

@@ -0,0 +1,173 @@
+# Phoenix Diagram 候选
+
+Phoenix Diagram 0.2.0 提供 architecture、workflow、sequence、dataflow、lifecycle、erd、class、tree、timeline、waterfall 十类的原生生成、独立 HTML 阅读与导出，可对固定提交核对仓库来源，阅读器界面支持 en、zh-CN、zh-TW、es、ko。新稿声明 `meta.input_contract: "phoenix-v1"`；原五类未标记的旧 JSON 按 `legacy-2.17` 解释，新五类只有 `phoenix-v1`，原 JSON/HTML 不被迁移。仓库以 phoenix-diagram 为唯一活跃图解入口；其他项目及个人旧安装须分别处理。数值图表、仪表盘及其他 infographic 不在范围内。
+
+目前实现与验收仍在进行，四平台、真实 provider 和最终包的完整交接尚未完成。candidate 的 loopback 下载地址仅用于隔离验收，不能直接作为公开 npm/R2 发行资源。
+
+## npm 发布安装
+
+npm 发布包与仓库的 `xgent-skills install` 默认同时安装 Phoenix UI 和 Phoenix Diagram，可用 `--no-phoenix-diagram` 单独跳过 Diagram。Diagram skill 随 npm 安装器与固定引擎一起安装、更新；`metadata.internal: true` 将它从 `npx skills add XGENT-ai/skills` 的默认列表排除，避免不同渠道覆盖配套版本。维护发布统一从 `main` 运行 `npm run release:phoenix`，不创建发布分支或使用 detached HEAD。该命令保留 Diagram 的 bin、skill、文档与发行资源，在上传 UI 前要求 Diagram 已具备匹配 npm 版本的四平台 release 清单、bundle、完整许可证和公共 HTTPS 地址；开发或候选清单不能代替。可用 `--diagram-release-dir DIR` 提供同版本的完整正式资源目录，在打包阶段注入。Diagram 引擎的构建和托管须先完成，本命令不会自动将 candidate 转为 release。最终 tarball 在 Node 18 与维护 Node 上验证联合安装、Diagram 入口和重复安装后才进入 npm 发布。
+
+## 候选安装
+
+消费需要 Node.js 18+，无需 Rust、Cargo 或源码。候选交付包含同一个 npm tgz 与匹配的完整 release-dir；不要混用版本或自行改 VERSION/ENGINE。以下 `PACKAGE_DIR` 是该 tgz 的解包目录，`PROJECT` 和 `RELEASE_DIR` 换成实际绝对路径：
+
+```sh
+node "$PACKAGE_DIR/bin/xgent-skills.js" install "$PROJECT" \
+  --no-phoenix-ui --no-xgent-init --providers=claude,codex \
+  --diagram-release-dir="$RELEASE_DIR"
+```
+
+这里跳过 UI 是候选消费范围：包内 UI 原资源保持原样，不能把它当作 diagram 四平台发行的证据。总安装器默认启用两个 Phoenix 工具；不支持 diagram 的平台默认跳过 diagram 并说明，显式指定 `--diagram-release-dir` 时仍在写项目前失败。`--release-dir` 只控制 UI，`--diagram-release-dir` 只控制 diagram，`--no-phoenix-diagram` 跳过且保留已有 diagram 安装。所有选项、XGENT、UI、diagram 预检均先于项目写入。执行顺序为 XGENT → UI → diagram；后段失败会报告前段已完成项，不回滚另一个工具。
+
+默认按项目已有 provider 目录选择，空项目用 `.claude`。`codex` 识别 `.agents` 或 `.codex`，diagram skill 仅进入 `$PROJECT/.agents/skills/phoenix-diagram`；本工具不新增 hooks、settings、AGENTS 或个人级 skill。新开 Claude Code/Codex 项目会话后核对实际加载的 skill 路径。安装状态位于 `$PROJECT/.phoenix-diagram/install/`，请按输出提示在本地忽略；不要删除整个目录作为恢复手段。
+
+引擎按 VERSION 的大小、SHA-256 与 probe 校验，缓存位于 `~/.phoenix-diagram/bin/<toolVersion>/<platform>/<engineSha256>/phoenix-diagram`；`PHOENIX_DIAGRAM_HOME` 可隔离缓存。普通命令不联网补装。缺引擎时只在用户明确请求安装后执行回执的 `setupCommand`（doctor 的 `recovery.engineInstall` 使用同一指引）。candidate/development 指向当前本地包或已安装 skill 的入口，不按同名版本去 registry 取另一个包；将命令中的 `MATCHING_RELEASE_DIR` 替换为该候选配套完整 release-dir 的实际绝对路径。用户或已提供材料尚未明确给出该路径时，先询问并停止安装，等待答复；安装授权不代替资源路径，不搜索项目外目录、猜路径、省略 `--release-dir` 试装或执行占位符。该目录按当前 VERSION/ENGINE 的原字节、引擎摘要和许可校验；遗失候选包或配套目录时须重新取得同一 tgz 和资源。只有 distribution=release 才输出 `npm exec --package=@xgent-ai/skills@<固定版本>`。candidate/release 离线目录必须含四平台；development 只校验清单声明的全部平台资源，单平台开发制品不计四平台验收。目录缺少声明的资源、清单或许可证时直接失败，不回退在线下载。
+
+## 旧入口迁移与安装恢复
+
+普通安装保留旧 Archify。只有明确请求迁移时，按[包内迁移合同](../skills/phoenix-diagram/references/migration.md)先 dry-run 查看精确项目/provider/来源及逐项路径，再以覆盖该范围的明确确认执行 `migrate --from-archify --confirm-remove-archify`。仅完整匹配固定来源的项目副本可移除；自定义、额外/缺失文件、链接、外部管理与个人安装保留。旧 skill 不备份，回滚不重建，恢复旧入口须按回执指引显式重装；原 JSON 和已有 HTML 保持。
+
+联合入口为 `node "$PACKAGE_DIR/bin/xgent-skills.js" install "$PROJECT" --migrate-archify --diagram-release-dir="$RELEASE_DIR"`，使用已存在的匹配引擎，先展示目标和后果。TTY 肯定答复后才移除；拒绝/EOF 不迁移。非交互须另加 `--confirm-remove-archify`；单独确认标志无效。此分支跳过 XGENT hooks/settings/AGENTS 和 UI，`--no-phoenix-diagram` 仍跳过并保留，普通联合安装继续原流程。
+
+中断后读取真实 `transactionId`、已删/剩余旧项与 `recoveryCommand`，只恢复指定事务。`rollbackCommand` 仅逆向恢复当前 committed 事务的 Diagram 受管写入，支持 v1/v2；预检发现后来修改先保持零变更，同一 ID 幂等，不跨过后来安装。恢复旧 Diagram active 时原生重新绑定实际文件身份，不手工复制回执。若部分回滚已恢复旧 launcher，优先原样执行回执给出的已验证新原生引擎命令，不从 PATH 选择旧引擎。普通命令仍核 active，恢复入口不要求损坏/pending active 先完整提交；不自动下载或重装。
+
+回执的 `legacyBackupPolicy: "none"`、`legacyRestoration: "not-supported"` 与 `reinstallInstructions` 必须交接；`backup` 只指 Diagram 受管文件。重开 provider 会话核实际加载的新 skill 路径，未处理的外部/个人入口不计全机唯一入口已生效。迁移成功也不代表图像已重新验收。
+
+## 从候选到 HTML
+
+以下在已安装项目根目录执行；只有 Claude provider 时把 `.agents` 换为 `.claude`：
+
+```sh
+PD="$PWD/.agents/skills/phoenix-diagram/scripts/phoenix-diagram"
+"$PD" --help
+"$PD" doctor --json
+"$PD" guide "审批工作流" --json
+cp .agents/skills/phoenix-diagram/examples/minimal.workflow.json candidate.json
+"$PD" finalize workflow candidate.json diagram.html --out-dir evidence-01 --json
+```
+
+示例只教结构，实际 candidate 应由授权事实写成，不能把示例当作用户的系统信息。所需日期、金额或业务条件缺失时，先询问，答复前不写 candidate 或生成图，也不附“草拟”“默认”“待确认”的猜测值；只有用户明确要求拟定这些值时才提供标为建议的方案。普通依据材料作图时，原材料已明确指出业务条件、日期或金额缺失，就直接走澄清分支；不能以主干仍可画或已有结果标签为由继续作图。其他必需事实未提供时，先提取阻止交付的缺口，改成开放式问题；不发散到材料未提及的可选分支、异常路径或设计选择。已给出的角色、关系和标签直接按原文使用，不以细化称谓、层级或内部细节为由追加问题。例如，“超预算还需批准”只说明追加条件；材料未要求具体执行先后时，不补造先后，也不为细化先后追加问题。发送前删去候选答案、假设例子、扩展问题、流程复述，以及列表前后汇报已核事实或解释为何要问的段落，只输出剩下的简短问题列表并结束，从第一条问题开始，列表前后不加介绍或解释；字段格式只给未赋值占位符，不追加创作步骤、草拟流程或具体值，也不用缺失规则卡片代替询问。事实齐备后读取匹配的 schema/common/example 与创作默认值；宿主读取返回被截断时，分段补齐必需内容后再写 candidate，不以子进程 stdout 完整代替宿主实际可见读取。新稿默认 showcase，先自动路线；Mermaid 的 flowchart/graph、sequenceDiagram、stateDiagram、erDiagram、classDiagram 由宿主保留语义后写 JSON，Rust CLI 不包含 Mermaid parser。十类之外的结构应明确提出，不靠删节点、删列、删成员、删关系、缩字或隐藏溢出来通过。
+
+ER 图创作前分别核对关系每端的最大基数、最小参与数与引用列可空性。外键只证明引用目标，不自动证明 `NOT NULL`；“可有多个”不单独证明最小数为零。`fromOptional`/`toOptional` 省略或写 `false` 仍表示最小值1，写 `true` 表示0；两种取值都要有材料依据，省略字段不能表示未知。以已给 SQL 约束、联合主键、显式文字或 Mermaid 端点为依据，材料已明确就直接使用，不重复询问或要求另选表现形式；需要表示的最小数或可空性缺少依据时，先按上述开放问题规则询问并停止，不生成 candidate 或先画 `0..N`/`1` 再标“待确认”，也不用卡片兜底。用户明确要求拟定规则时才提供建议。
+
+类图的关系种类与数量约束分别依据材料表达。成员可脱离整体存在，不等于整体可以没有成员；未给下界时保留“多个”等已有数量含义，不补 `0..*`、`1..*` 等数值标注，只省略无依据的可选数值。“一个/单个/多个”等已给数量须由关系标签或相应的单值/集合成员明确表达，不能只保留组合或创建销毁文字而漏掉数量。明确数值与 Mermaid 端点照用，不为可选标注追加问题。
+
+耗时瀑布分别核对跨度结束、trace 采集截止与显示窗口。请求或父跨度的 `end` 不自动给出 trace 的精确采集截止时刻；仅由自动扩展或人为固定得到的窗口边界不能作为观测事实。未给精确截止时，不在名称、`detail`、卡片、提示或最终答复中补精确截止时刻或截至该时的精确已观测时长。未结束的跨度保持 `incomplete`，有记录支持的区间可表达“至少/≥”时长下界：同一 trace 已记录的最晚时刻可给出采集截止下界，采集截止时仍开放的跨度可据其起点到该时刻的差给出时长下界，无须知道精确截止；不能由此补精确截止或最终耗时，缺少可省略的截止说明不追加问题。推导时长比较、极值或排序结论时，以材料已给事实、已知数值或上下界为依据，不能默认未结束跨度短于已完成跨度。材料直接给定的比较事实照用，不为证明它额外索要数值。上下界足以证明时，未知总时长也可参与比较；否则写清仅比较已知完成跨度或明确窗口内片段，不把该结论扩为全部跨度的最终耗时比较。判断无子跨度覆盖的区间时，核对相关未结束子跨度；缺少其结束依据就不作零覆盖断言。
+
+审批有多个继续分支时，逐条保留各分支所需的全部批准前提；某一分支写有批准，不代表其他仅按资格分流的分支也已获准。逐个从获准结果沿实际可达分支回溯，核对每条路径的条件是否足以推出该结果所需的全部批准；不能只因有拒绝出口，就把其余资格分流边视为已批准。源码或图中的等价条件表达同样有效，不要求固定批准词或独立批准节点、边。
+
+新稿或涉及语义的修复完成后，按原材料逐分支走读条件、动作、执行者与先后关系。进入处理步骤不等于已经通过或获准；资格条件与批准结果分别核对。原文要求某人批准后才能执行的动作，须由该执行者的批准节点或出边中的批准条件控制，不能仅以进入审批和满足资格条件代替。条件内的动作不能前移为其他分支的共同前置动作，也不能因合并节点或回路改变顺序。跨阶段适用的动作，先按原文枚举许可覆盖的全部非终态，再逐项核对主图路径；例如“任一下单前可撤回”也覆盖提交、补充材料等适用阶段。每个适用阶段都应能行使该许可并抵达相应结果，无需先满足额外条件或完成审批、提交、补交等其他业务动作。无条件且不执行业务动作的瞬时起始跳转可与后续阶段等价，显式覆盖全部适用阶段的结构也可等价表达，不要求逐节点各画一条直接边。有条件出口或执行检查的阶段不属于这种瞬时起始跳转。例如，材料给“合并前可撤回”时，图中单独表示的批准阶段或获批后尚未合并的阶段也要保留撤回路径，不能在审批通过时提前结束这项许可。卡片或“各阶段可……”文案不能代替主图中这项许可的完整范围。节点文字、`tag`/`sublabel`、卡片标题与条目、线型、颜色与图例都要对应原事实。未说明的同步/异步、批处理等执行方式，使用中性职责、动作与普通关系；不能仅凭 Queue、Worker 等名称推定节点任务的执行方式，也不为可省略的标注追加问题。组件的用途同样须有材料依据，不能按常见用法补充；例如，材料只给“读写 Redis”时，不标为“缓存”。节点和标签齐全、卡片复述正确，都不能代替主图路径与原事实一致；只据已给事实修正，必需事实缺失时仍先澄清。
+
+仓库图缩写文字、改写卡片或调整布局后，也要保留实际命令名、源码条件和替代路径，所用函数或校验名称仍与各入口、命令的条件对应；只在特定分支执行的校验，不能写成所有调用必经的前置条件或安全保证。合并不同入口、命令或条件分支时，共享前置只能放这些实际可走路径共同必经的动作；例如 A 入口执行 X、B 入口执行 Y，不能合并为两者都执行 X。分别沿源码核对有条件的校验、默认补足和失败返回，保留各自的条件与结果。沿调用链把实际传入的参数和禁用开关带入条件判断；可被入口参数跳过的校验，不能写成必经步骤或无条件保证。对短路、跳过、禁止或必经的断言，逐条核对实际分支的完整条件；源码存在一个提前返回分支，不代表相关入口或不同参数组合都走该分支。来源核验为 `verified` 也不能代替这项语义核对。
+
+Workflow 发生共用通道或箭头拥挤时，按实测节点与整组相关路线，先给共用起点或终点周围留出独立通道；必要时调整未固定节点的列、行或间距，包括回路起点、多入边的汇合与撤回目标。端点可在图的边缘或内部，以所有相关路线的实测结果为准，不由主路径顺序预定位置；不要为了保留拥挤布局而先叠加端口或通道 pin。自己添加的端口或路线约束冲突时，撤掉这些约束，让自动路线重新联排相关边；剩余实测问题再按诊断修复，保持原业务事实、质量和停滞停止规则。
+
+公开命令：
+
+用户或宿主对 CLI 执行器、命令形式或原始结果留存有明确约束时，所有 CLI 调用（含 `guide` 和帮助命令）都按这些约束执行。下方示例只说明参数，不能据此省略任务已明确要求的调用层或结果记录。命令形式已固定时，不自行添加环境变量赋值前缀或更换调用层。资料范围已限定时，搜索也须限于获准资料；不能用整个 skill 根的搜索读到已排除的实现，排障也不枚举授权外的个人缓存或应用目录。
+
+```text
+validate <type> <candidate.json> [--layout-json] [--quality standard|showcase] [--input-contract NAME] [--repo-root DIR] --json
+deliver <type> <candidate.json> <output.html> [compile options] [--repo-root DIR] --json
+check <output.html> [--strict-provenance] --json
+browser-check <output.html> [--out-dir DIR] --json
+visual-check <output.html> [--out-dir DIR] --json
+finalize <type> <candidate.json> <output.html> [compile options] [--repo-root DIR] [--out-dir DIR] --json
+review-record <output.html> --record <review.json> --json
+recover-output <private-recovery-directory> --json
+install --project DIR --bundle-root DIR [--providers claude,codex] [--dry-run] --json
+```
+
+显式 quality/input-contract 与 candidate 已声明值冲突会失败。保留旧合同默认值、固定节点、方向、标签与 route pins。品牌由固定目录或摘要固定的本地资源支持；旧 guided views 为 `unsupported-display`，旧播放偏好为 `ignored-display`，首次仍是 Still。这些终局处理列在 `compatibility.dispositions`，不再称为延期，核心兼容通过不能代替完整展示兼容。见[兼容约定](../skills/phoenix-diagram/references/compatibility.md)。普通 stdout 为一个 JSON，显式 preview 为 NDJSON 事件流；不要仅用退出码判断完整交付。
+
+主要元素带 `sources`、`meta.repository` 固定 40 位提交时，用 `--repo-root` 指向该仓库顶层目录。核对只读、不联网：origin 一致、提交存在、文件与行在该提交中存在，并逐段比较工作树文件（不跟随符号链接）。凭据 URL、路径逃逸、非法行区间、provider 与主机不符或网页链接用了不支持的主机会在输入阶段失败。其他不能核对的情形（缺 `--repo-root`、git 不可用或超时、缺提交或对象、文件缺失、行越界、工作树不同、旧版 git 遇部分克隆）只把对应来源记为待核实并附原因，HTML 照常生成；回执与 summary 的 `evidence.status` 为 `verified`、`partial`、`unverified` 或 `none`，与四门结论分开报告。时间线的日期型记录用 `precision: "day"`，没有记录的耗时瀑布用 `meta.evidence: "illustrative"`。
+
+每轮失败后，在可回读的进度或本次项目记录中写明实际失败门、诊断阶段、客观 error 数、历史最佳值和停滞计数；首次失败的停滞计数为0。同一门每次修复后，只有 error 低于该门历史最佳才更新最佳并清零，否则停滞计数加1。修改 candidate 或修复前先核对该门计数：达到2立即停止并列出未解决项；即使不再运行命令，也不能继续修改 candidate 或将它回退到历史较好版本。错误种类变化不能重置计数，也不允许再试一次。修复前实际读到失败 diagnostic 的 `subject`、`evidence`、`supportedFixes`；宿主返回截断或提取遗漏时先补齐，不能把原有实测或字符串修法筛掉、转成空对象后视为已读。只修相关邻域。重建 candidate 或交付、调整布局或卡片、返回已记录门时，沿用该门历史，不因新回执重新初始化；对最小示例的只读对照或验证不计修复，也不重置历史。环境失败也不允许无限重试。已通过前门而首次进入后门属于实际进展，按新门初始化记录；同一 validate 门内诊断 `stage` 首次由 `input` 变为 `layout` 也算进入后门。`supportedFixes` 写明经整图验证时，选定的一项修法所列全部路径是同一整组方案，须一次完整应用，不挑单个路径先试；保留每轮全部门的真实状态，不把不同门的顶层 error 数拼成同一停滞序列。
+
+## 看图后收口
+
+`finalize` 顺序执行 validate、deliver、严格 check、browser-check。首个失败后其余 `not-run`。浏览器默认隔离验收并采图，不打开用户当前浏览器；工具缺失、执行失败、自动通过与视觉待审分别报告。HTML 已提交后浏览器失败会保留新 HTML，不替换回旧文件。
+
+自动四门通过后仍为 `visualReview.status: required-pending`、`deliveryStatus: incomplete`。读取返回的 summary/browser receipt，实际查看 1440×900、2048×1320 的四张暗亮截图与必要长图，检查主图、全部标签/notes、卡片、关系遮挡、层级和控件。按包内 [交付合同的完整草稿命令](../skills/phoenix-diagram/references/delivery-contract.md) 从当前回执复制身份，逐张填写实际观察；未看图不得设置 passed。
+
+```sh
+"$PD" review-record diagram.html --record review-01.json --json
+```
+
+随后读取返回的 `evidence.summaryReceipt.path`。四门 pass、视觉 passed、`deliveryStatus: complete` 才是完整交付；原 `deliveryReceiptId`、`browserReceiptIdentity`、输入/HTML/config/engine/四图绑定必须保持。答复中的 HTML、candidate 和 summary 路径优先原样复制同一交付回执给出的真实值。若转为相对路径，先以宿主实际报告的本次工作目录逐条核对它们仍指向相同文件，再输出这些已核对的字符串；不能拿上级目录或消息中出现的其他目录作相对基准。简短回复也要保留定位所需的目录，不能用 `...` 代替路径或裁去前缀冒充绝对路径。只为登记审核不得再次 finalize。封存记录已成功但 summary 写失败时，以同一记录字节重试 review-record；修改 candidate 则生成新交付、新截图与新审核。不能拿旧图或旧回执补证。另读取同一 summary 中名为 `deliver` 的阶段回执 `receipt.compatibility.coreCompatibility` 与 `receipt.compatibility.dispositions`，逐项交接非 `supported` 字段及实际原因。`deliveryStatus: complete` 仅表示交付流程完成，不能代替这些兼容限制的交接。
+
+## 按请求启用的作者工具
+
+- [品牌资源](../skills/phoenix-diagram/references/brand-marks.md)：明确要求品牌标识时查询固定目录，只有明确采集请求才访问用户提供的公共 URL。普通编译只读本地固定资源，不因节点名称猜品牌或联网。
+- [本地预览](../skills/phoenix-diagram/references/preview.md)：明确请求才启动，`--open` 才打开系统浏览器；保留 last-good 并报告新尝试错误。服务停止和页面可用不等于正式交付通过。
+- [架构比较](../skills/phoenix-diagram/references/architecture-compare.md)：明确请求比较两份 architecture 时执行，提供 Before/Delta/After，走专用严格检查、12 张截图实际审核及两门 summary，不推断原因、风险或可合并性。
+
+普通作图继续使用单图 finalize 与四图审核，不自动附带上述操作。维护者增加类型时遵守[扩展约定](../skills/phoenix-diagram/references/extending-types.md)。
+
+## 中断后的文件恢复
+
+生成失败、竞争占位和提交后失败分别查看 diagnostics/commitState/publicState。若发布进程被 kill、终端输出丢失，先在**原输出父目录**只读定位持久记录：
+
+```sh
+ls -la "<原输出父目录>"
+```
+
+同一事务的记录按清理进度可能位于三处：
+
+1. `.phoenix-diagram-recovery-<id>/publication-recovery-v1.json`
+2. `.phoenix-diagram-recovery-<id>.cleanup.json`
+3. `.phoenix-diagram-output-cleanup/<id>.json`
+
+读取记录中的 target/requestedPath/commitPath，明确它绑定本次输出。固定 cleanup 目录还保留绑定的 `<原输出父目录>/.phoenix-diagram-output-cleanup/owner-v1.json`；空壳不是需要删除的垃圾。多个记录须明确选择，不能按时间自动挑选，不手改记录/备份/权限。
+
+**无论记录在哪一处，参数始终为原 `.phoenix-diagram-recovery-<id>` 目录，即便它已不存在：**
+
+```sh
+"$PD" recover-output "<原输出父目录>/.phoenix-diagram-recovery-<id>" --json
+```
+
+该入口只处理输出 publication，不接受项目 install journal。它核验原父目录、槽位、记录、备份及物理身份并取得同一 OS 锁；仅在缺失 public 时以 no-clobber link 恢复旧文件。后来的 claimant、改过的备份/记录、替换父目录、未知 owner/额外条目或多处记录歧义均保留并停止，不覆盖用户后来修改。恢复过程中再次被 kill，可重复显式恢复同一事务。
+
+| recoveryStatus | 含义 | 退出码 |
+| --- | --- | --- |
+| recovered | 原字节已恢复或核对一致，且本次清理完成 | 0 |
+| absent | 对应事务与残留不存在，无文件恢复 | 0 |
+| preserved | 新占位或已提交新图被保留，未恢复旧字节 | 3 |
+| recovery-required | 可信事务仍待恢复/清理 | 3 |
+| invalid | 参数或不支持的记录格式，读取 diagnostics | 2 |
+| failed | I/O 或运行失败，读取 diagnostics | 4 |
+
+返回的 `target` 只在可信记录核验后提供。文件恢复不生成 delivery/browser/visual 通过回执，后续交付仍需适用检查。项目安装中断则重跑原显式 install，让 Rust 在日志与 after 身份仍匹配时恢复；candidate/development 安装回执的 `recoveryCommand` 使用本次已验证的原生引擎与 bundle，不从 registry 另取同名包。引擎缓存也已遗失时先按上文恢复匹配引擎。用户后来修改不会被 before 备份盲覆盖。
+
+## 阅读与导出
+
+HTML 内置 Reader、字体与必要资源，可离线阅读。支持主题/风格、平移缩放、标签/id/来源路径搜索及详情；首次为 Still，用户选择 Live 后才保存偏好。十类都可做语义筛选、概览定位、展示模式和深链接；有已著关系的八类可找 Route 与上/下游 Reach，并导出标明范围、非 canonical 的范围卡片；树可折叠分支，导出与打印始终为完整树。详情按已核对、待核实（附原因）、未提供来源三态显示来源。界面语言按 `meta.locale` 选择五种之一，其他标签回退英文，finalize 回执的 `locale` 记录结果。缩减动画、页面隐藏、打印和导出临时暂停，静态图仍保留含义。页面可按声明的可读纵向画布滚动，不能用水平裁切或内部滚动掩盖内容。
+
+支持 PNG/JPEG/WebP、主题 SVG、WebM 和 PNG 复制。能力/权限拒绝、空 Blob、编码/录制失败都应返回明确失败与可用替代动作；格式实际可用性以当前浏览器结果为准。字体许可随独立 HTML/SVG 保留。源码与第三方许可位于独立发行目录 LICENSE、NOTICE、THIRD-PARTY.json/NOTICES/LICENSES；参考归属与 Phoenix 修改单列。
+
+维护验收的三变量 checkpoint 仅用于隔离临时项目的确定性 SIGKILL 场景，不是普通恢复步骤；默认不启用、不联网、不延迟消费命令。当前里程碑和实际验收记录见仓库开发计划，缺失的真实平台/provider/图像结果不计通过。
+
+## 验证结果与发行边界
+
+此前P2在本机 macOS arm64 开发引擎上，十类共15例（原五类的新/旧合同各一例、新五类各一例）通过四道自动门和确定性检查，实际查看60张暗亮截图后经原身份 `review-record` 达到完整交付。15例的Reader操作、20项导出、打印与剪贴板检查，离线生成/检查/阅读导出和8个公开中断恢复场景均已通过。十类探索（筛选、Route、Reach、树折叠、概览、展示、深链接、键盘与详情）通过，有已著关系的八类各导出一张Route与Reach范围卡片。冻结3.1.0参考包的25份JSON核心事实可被消费，原样交付均通过四道自动门并经实际看图，原JSON与15份参考HTML字节不变。本仓固定提交的来源核对覆盖已核对（含GitHub链接存在性）、工作树改动、仅本地和未提供来源四种显示，示意耗时与日精度时间线已核对。五种界面语言与fr英文回退均实际看图。这些历史开发结果不代替P3最终 npm tgz 的消费验收。
+
+P3最终候选须另附 `kind: phoenix-diagram-candidate-aggregate`、`profile: "p3"` 的聚合回执。先核对其中 `cohort.tgzSha256`、source身份、runId/runAttempt与收到的候选一致，再读取以下实际结果：
+
+- 四个平台与精确Node18.20.8对同一tgz的自动消费：15例四门全过，视觉保持待审。
+- 四个平台另核品牌/比较/显式预览、真实public npm进程与迁移故障；本机darwin-arm64对同一tgz完成15例及品牌/比较的实际看图、`review-record`、探索/范围卡片、来源、界面语言与文档最终页检查。
+- Claude Code、Codex各18个全新中性项目/原生会话：同一候选、冻结题面/材料、真实模型/端点类别、实际加载文件、命令原件和独立语义/图像观察。P3不沿用P2的抽样或旧development会话复用。
+- 完整品牌来源/全文、三份完整旧来源与五份legacy原例的同字节链；旧v1兼容另用明确、独立认证的历史候选作安装前置，不能充当第二个最终候选。
+
+完整Reader范围包含相机、空搜索、按标签和id搜索、无匹配反馈、详情、键盘与样式八项实际交互，双主题及Still/Live下缩减动画、页面隐藏的八项真实暂停/恢复样本，以及20项导出、剪贴板和打印暂停/恢复的证据；截图存在或单项pass不能替代这些范围。任何缺项、not-run、unavailable或身份不一致都保持incomplete；最终 `status: pass` 且 `handoff: passed` 才表示该候选的规定验收已齐备。
+
+本说明在最终封包前固定，封包后的验收结果保存在绑定原tgz摘要的独立聚合回执中。补写结果或修复包内文件会改变tgz身份，需要重新装配并取得适用的新证据。当前尚未取得最终同包四平台及真实provider的完整通过结果，也没有公开npm/R2发行；development清单和候选loopback地址不能用于宣称公开在线安装已可用。
+
+维护者从已认证、独立转移的harness目录执行最终检查，显式给出候选、历史v1前置和来源验收仓库：
+
+```sh
+node tools/phoenix-diagram/tests/p3-acceptance.mjs --stage all --candidate-dir "$CANDIDATE" --legacy-candidate-dir "$LEGACY_V1" --evidence-repo "$EVIDENCE_REPO" --output-dir "$NEW_RUN"
+node tools/phoenix-diagram/tests/p3-acceptance.mjs --stage providers --candidate-dir "$CANDIDATE" --provider-manifest "$PROVIDERS" --output-dir "$NEW_PROVIDER_RUN"
+```
+
+all默认只使用该harness中固定的官方测试资源描述符与惰性旧目标数据；后者从不执行，不进入产品。providers仅验证原始会话清单，不启动宿主或合成结果。all的consumer、author-tools、migration、providers各保存独立原件；缺图片审核、来源scope、旧v1前置或真实provider时保持incomplete。实际看图后用原all状态的`--resume`与同run的`--review-file`登记两个child审核映射，可同时给`--provider-manifest`；不重生成已审核图。已有迁移record保留并重核，不隐式重跑已通过case。CI的P3自动门可通过而CLI仍exit3，最终完成必须以本机完整审核及API认证的聚合结果为准。

package/docs/phoenix-ui.md

@@ -14,7 +14,7 @@ npx @xgent-ai/skills install
 一次安装分两段，先完成全部只读预检再写项目：
 
 1. **预检**：校验参数、`.claude/settings.json` 与 guard 配置；把包内 `dist/phoenix-ui/VERSION.json` 固定的 engine 下载或从 `--release-dir` 读取，按大小、SHA-256 和 `engine-probe` 身份核对后放进用户 cache；再以 dry-run 计算 Phoenix 的写入和合并。仅由待重装工具目录引起的冲突在清理后重新计算，其余预检失败不写项目。
-2. **写入**：按下节的选择删除待替换工具；再写 XGENT 部分（statusline hook、settings、可选 guard 与 AGENTS.md），最后由 Rust 安装执行器在项目锁内重读这些文件，事务化写入 Phoenix 的 skill、agents、hooks、五个辅助 skill 和安装回执 `.phoenix-ui/install/active.json`。清理的旧工具不备份、不参与回滚；清理后被打断时重跑安装。Phoenix 写入中途失败（如磁盘已满）时状态为「待恢复」，可能已部分写入；重跑同一命令会先按日志回滚或补完上次事务再安装。
+2. **写入**：按下节的选择删除待替换工具；再写 XGENT 部分（statusline hook、settings、可选 guard 与 AGENTS.md），最后由 Rust 安装执行器在项目锁内重读这些文件，事务化写入 Phoenix 的 skill、agents、hooks 和安装回执 `.phoenix-ui/install/active.json`。清理的旧工具不备份、不参与回滚；清理后被打断时重跑安装。Phoenix 写入中途失败（如磁盘已满）时状态为「待恢复」，可能已部分写入；重跑同一命令会先按日志回滚或补完上次事务再安装。
 
 安装输出逐项列出写入、合并与移除，状态为「已安装 / 未变 / 冲突,未激活 / 待恢复 / 已安装但融合未就绪」之一，并给出事务 ID、备份位置、完整回滚命令和各工具的重载步骤。只有状态为「已安装」或「未变」时才打印「完成」；冲突与融合未就绪以退出码 3 结束，engine 或文件环境失败以 4 结束，参数错误为 1（XGENT 部分）或 2（Phoenix 执行器）。
 
@@ -26,7 +26,6 @@ npx @xgent-ai/skills install
 | `--keep-impeccable` | 保留 impeccable，与 Phoenix UI 共存，不再询问；无交互环境默认保留 |
 | `--release-dir=DIR` | 离线安装 engine：DIR 是发布者整理的完整 release 目录（`VERSION.json`、各平台 engine、许可与清单），必须与当前包的 manifest 完全一致，零网络 |
 | `--providers=a,b` | 指定安装目标目录；`codex` 同时选择 `.agents`（skills）与 `.codex`（hooks）。默认按项目里已有的目录判断，都没有时只装 `.claude` |
-| `--force` | 只影响 guard 的非法 JSON 备份覆盖；不放宽 Phoenix 的冲突保护 |
 
 **engine**：放在 `~/.phoenix-ui/bin/<版本>/<平台>/<engineSha256>/`（可用 `PHOENIX_UI_HOME` 改 engine cache 的根目录；提醒去重标记也在其中），按引擎摘要隔离，新旧项目固定的引擎可以共存，也不覆盖旧版缓存。hook、context 等普通运行不联网补下载：engine 缺失或版本不符时 hook 放行并每会话提醒一次补装命令，CLI 返回 4 并给出固定包版本的命令：
 
@@ -42,6 +41,8 @@ npm exec --package=@xgent-ai/skills@<包版本> -- phoenix-ui engine install --p
 
 无交互环境默认共存；自动化可用 `--replace-impeccable` 或 `--keep-impeccable` 明确选择。没有 `.phoenix-ui/install/` 事务状态的 Phoenix 副本属于待重装工具，直接删除对应 skill 目录后安装，不要求旧回执，也不备份。已有事务或受管安装仍按回执升级、恢复；早期显式迁移留下的 Phoenix 受管兼容入口也由回执维护，不当作旧工具删除。
 
+旧回执曾管理的五个辅助 skill 在本次升级时释放归属，现有文件原样保留；后续由 skills.sh 更新，不再阻止 Phoenix 安装。
+
 这些操作不改业务代码、文档和 `.impeccable/` 数据。个人级旧入口只在选择替换时删除。清理后若安装中断，直接重跑；需要旧工具时从 Git 或其安装渠道恢复。
 
 ## 显式迁移旧数据
@@ -58,14 +59,13 @@ npm exec --package=@xgent-ai/skills@<包版本> -- phoenix-ui engine install --p
 - `AGENTS.md`、`CLAUDE.md`、`DESIGN.md`、`PRODUCT.md` 中的旧入口只报告行号与替换建议，不自动改写。
 - 个人级目录里早期上游版本的分命令 skill（如 skills.sh 装到 `~/.agents/skills` 的 `polish`、`teach-impeccable`）没有 hook 或 engine，只报告位置与移除、重载步骤，不阻止激活。
 
-显式迁移时，以下情况会阻止激活（退出码 3，项目不被修改），按输出逐项处理后重跑。普通安装仍保留外部辅助 skill 的融合检查：
+显式迁移时，以下情况会阻止激活（退出码 3，项目不被修改），按输出逐项处理后重跑。辅助 skill 独立管理，不参与 Phoenix 安装检查：
 
 | 情况 | 处理 |
 | --- | --- |
 | 旧 skill 或旧 hook 被用户改过、被 shell 包装，或结构无法唯一确定 | 输出列出文件与条目；先备份/还原或移出活跃目录，再重跑 |
 | 固定旧状态路径或注入日志中记录的 live、注入或变体残留；显式迁移还检查源码中的孤立标记 | 用旧项目的 launcher 正常停止、`live-inject --remove`、接受或丢弃变体；不要按 PID 杀进程 |
 | 个人级（如 `~/.claude/skills/impeccable`）旧入口、旧 hook 或插件 | 安装器只读发现、不改个人配置；按输出在对应工具中禁用或移除后重载并重跑 |
-| 外部管理的辅助 skill 副本与本包不同（含 skills.sh 副本、符号链接） | Phoenix 仍激活，状态为「已安装但融合未就绪」；按输出用 `npx skills add XGENT-ai/skills --skill <名称>` 更新，或备份后移出活跃目录再重跑 |
 
 ## 回滚与恢复
 
@@ -103,18 +103,46 @@ npm exec --package=@xgent-ai/skills@<包版本> -- phoenix-ui migrate --rollback
 | `.gemini` | Gemini CLI | skills、`.gemini/settings.json` hooks | 重新打开会话 |
 | `.agent`、`.dsh`、`.hermes`、`.kiro`、`.opencode`、`.pi`、`.qoder`、`.rovodev`、`.trae`、`.trae-cn`、`.veto`、`.vibe` | 对应工具 | skills（无 hooks） | 重新打开会话 |
 
-Phoenix 的 hook 按完整分组写入；同一事件里已有其他工具或 goal guard 的分组（包括都没有 matcher 的分组）互不影响，重复安装不产生重复 handler。安装器测试覆盖各目录的文件与 hook 合并；工具真实加载以各自会话为准，同名 skill 的优先级按工具规则（Claude Code 个人级优先于项目级），安装器无法确定时会提示待人工核对。
+Phoenix 的 hook 按完整分组写入；同一事件里已有其他工具（含旧版 goal guard）的分组（包括都没有 matcher 的分组）互不影响，重复安装不产生重复 handler。安装器测试覆盖各目录的文件与 hook 合并；工具真实加载以各自会话为准，同名 skill 的优先级按工具规则（Claude Code 个人级优先于项目级），安装器无法确定时会提示待人工核对。
 
 ## 渠道
 
 - npm：`@xgent-ai/skills` 包含 Phoenix 运行资源（skill bundle、`VERSION.json`、许可），engine 二进制按 manifest 从固定地址获取或离线目录提供，不进 npm 包。
-- skills.sh：五个辅助 skill（design-md、design-reference、ui-pattern-research、review-ui、apply-ui-review）继续公开，可单独安装；`phoenix-ui` skill 标为 internal，只通过 npm 安装器分发。没有 Phoenix CLI 时，辅助 skill 按各自的人工流程工作。
+- skills.sh：五个辅助 skill（design-md、design-reference、ui-pattern-research、review-ui、apply-ui-review）仅由 `npx skills add XGENT-ai/skills` 独立安装和更新，npm 安装器不写入、不认领、不比对它们的版本；`phoenix-ui` skill 用 `metadata.internal: true` 排除在默认发现列表之外，只通过 npm 安装器分发。已由 npm 安装的 Phoenix 主技能应通过 npm 更新，不再用 skills.sh 覆盖，否则文件会与安装回执不匹配。没有 Phoenix CLI 时，辅助 skill 按各自的人工流程工作。
 - 原 `vendor/impeccable/` 副本及其 vendor/R2 脚本已删除，需要时从 git 历史查看；旧安装的迁移依据是 `tools/phoenix-ui/migration-sources/` 中按 npm 包核对过的固定记录。
 
+## XGENT 自有检测规则
+
+Phoenix UI 在承接上游的 61 条内置规则之外，另带一组 XGENT 自有规则（ID 以 `xgent/` 开头）。它们默认启用、与内置规则分开定义，可以按规则单独关闭。规则包只装进原生 `phoenix-ui` 二进制：`detect`（源码文件与 URL 目标）和设计 hook 会运行它；live 叠层与浏览器扩展在页面内使用 WASM 检测、不加载这个规则包，所以同一页面在叠层或扩展里看不到下面这些发现，结果可能与 `detect <url>` 不同；需要这部分发现时以 `detect` 的结果为准。
+
+| 规则 ID | 检测方式 | 级别 | 关闭方式 |
+| --- | --- | --- | --- |
+| `xgent/transition-all` | 源码文件（文本扫描） | advisory | `detector.ignoreRules`、`hooks ignore-rule`、inline 豁免、`--no-advisory` |
+| `xgent/focus-outline-removed` | 源码文件（文本扫描） | warning | `detector.ignoreRules`、`hooks ignore-rule`、inline 豁免 |
+| `xgent/wrapped-control-label` | 页面（`detect <url>`，浏览器渲染） | warning | `detector.ignoreRules`、`hooks ignore-rule` |
+| `xgent/control-height-mismatch` | 页面（`detect <url>`，浏览器渲染） | advisory | `detector.ignoreRules`、`hooks ignore-rule`、`--no-advisory` |
+| `xgent/unlabeled-inline-svg` | 页面（`detect <url>`，浏览器渲染） | warning | `detector.ignoreRules`、`hooks ignore-rule` |
+| `xgent/redrawn-window-chrome` | 页面（`detect <url>`，浏览器渲染） | advisory | `detector.ignoreRules`、`hooks ignore-rule`、`--no-advisory` |
+| `xgent/emoji-icon` | 页面（`detect <url>`，浏览器渲染） | advisory | `detector.ignoreRules`、`hooks ignore-rule`、`--no-advisory` |
+| `xgent/font-family-count` | 页面（`detect <url>`，浏览器渲染） | advisory | `detector.ignoreRules`、`hooks ignore-rule`、`--no-advisory` |
+
+「源码文件」指文本扫描，覆盖 CSS、HTML、Vue、JSX、TSX 等前端源文件；「页面」指把 http(s):// 或 file:// URL 交给 `detect`，由真实浏览器渲染后检查，可用 `--viewport <W>x<H>` 指定视口（默认 1280x800）。warning 级发现计入失败数，可能让退出码为 2；advisory 单独列出、不改变退出码，`--no-advisory` 只能隐藏 advisory 级发现。两条文本规则也随设计 hook 在编辑后运行：`xgent/focus-outline-removed` 会在 Stop 深检提醒中给出，并在 Cursor before-edit 中拒绝写入；`xgent/transition-all` 是 advisory，hook 默认不输出 advisory 发现。页面规则依赖浏览器渲染，hook 不会产生它们，需要时单独运行 `detect <url>`。
+
+关闭方式（按影响范围选择）：
+
+- `detector.ignoreRules`：项目级关闭，手动 `detect` 与 hook 共用这份过滤；配置在 `.phoenix-ui/config.json`，本地覆盖在 `.phoenix-ui/config.local.json`。不要手改这两个文件，走下面的 hooks 命令。
+- `hooks ignore-rule <id>`：把规则 ID 追加到 `detector.ignoreRules` 的受支持写法，影响整个项目；范围较大，先征得用户同意。只关一个文件中的一条时用 `phoenix-ui hooks ignore-value <id> "*" --file <path>`，窄例外默认写入项目共享 config。
+- inline 豁免：`impeccable-disable*`（引擎原有）与 `phoenix-ui-disable*`（skill 文案）两种前缀都生效；词形为 `disable`（整个文件）、`disable-line`、`disable-next-line`（单行），后接一个或多个规则 ID（逗号分隔）或 `*`，可带 `: 理由` 或 `-- 理由`。内联标记按源文件内容生效；URL 扫描读取渲染后的页面，页面规则的例外用项目级忽略。`--no-inline-ignores`（或 `--no-config`）可绕过内联豁免。
+- `detect --no-advisory`：只在单次扫描中隐藏 advisory 级发现，warning 级发现与退出码不受影响。
+
+在 Cursor 上启用新版本后，本来含无替代 `focus:outline-none` 的文件会对任何编辑触发 before-edit 拒绝：该检查扫描整份投影后的文件，不扣除编辑前已经存在的发现，所以与该焦点样式无关的编辑也会被拒。处理方式是先修掉该文件的焦点样式；确需临时放行时用 `phoenix-ui hooks ignore-value xgent/focus-outline-removed "*" --file <path>` 只关这个文件中的这一条。不要为绕过拒绝改用 inline 豁免。例外默认通过 `ignore-value` 写入项目 config；`ignore-file`、`ignore-rule` 影响面更大，应先征得用户同意。
+
 ## 融合用法与 UI 验收
 
 本节适用于支持结构化 context 与 managed 评审协议的匹配版本；CLI 操作成功不代表 UI 通过，候选验收与公开发布见后面的维护流程。下列 `<包版本>` 从实际回执/候选包读取；未发布候选先用维护者提供的 tarball 与匹配离线资源，不把 latest 当作该候选。
 
+Phoenix UI 适用于独立网站、应用和嵌入式界面等 UI 项目。`phoenix-ui init` 直接依据目标项目的事实和已确认信息生成或补齐 PRODUCT.md，不依赖 `xgent-init`；产品边界、平台和设计约束均来自项目本身，不预设宿主平台或接入方式。subagent 与并行方式由 coding agent 结合自身能力、策略和用户约束选择，Phoenix 不另设授权询问或等待步骤；critique 的单上下文执行仍须先完成 A 再运行 B，并披露降级原因。
+
 视觉参考用 `design-reference`，交互选型用 `ui-pattern-research`，维护项目规范用 `design-md`，已选方向的实现继续用 `phoenix-ui`。先读取明确目标的上下文：
 
 ```bash
@@ -166,23 +194,23 @@ prepare 显式联网准备锁定依赖、工具、浏览器、迁移包和公告
 
 [CI workflow](../.github/workflows/phoenix-ui.yml) 在 macOS/Linux 四个平台同架构冷构建/运行，不恢复编译缓存，另有 Node18 consumer。固定成功 run 的四份 native、四份 phase evidence、一份 Node18 evidence 必须保留原始 ZIP/digest、HEAD/tree、工具链、输入/制品摘要、许可及全部真实 step/phase 结果。CI 不持 R2/npm 凭据；缺平台、失败 phase 或摘要不符不能交接。
 
-发布只用一条命令，在**干净、已推送且 Phoenix CI 成功**的 HEAD 上执行。版本号先在 `package.json` 改好，并用上面的开发构建同步 `VERSION.json`/`ENGINE.json`/`GENERATED.json`：
+发布只用一条命令，在 **main 分支上干净、已推送且 Phoenix CI 成功**的 HEAD 上执行，不创建独立发布分支，也不从 detached HEAD 发布。版本号先在 `package.json` 改好，并用上面的开发构建同步 `VERSION.json`/`ENGINE.json`/`GENERATED.json`：
 
 ```bash
 mise exec --no-deps -- npm run release:phoenix                      # 上传 R2 与 npm 发布前各确认一次，npm 会要 OTP
-mise exec --no-deps -- npm run release:phoenix -- --prepare-only     # 只做到安装检查；再跑一次不带参数即发布
+mise exec --no-deps -- npm run release:phoenix -- --prepare-only     # 只做到安装检查；再次运行时仅去掉 --prepare-only，保留资源目录等参数
 ```
 
 [release-phoenix-ui.mjs](../scripts/release-phoenix-ui.mjs) 依次执行，任一步失败即停：
 
-1. 核对工作树干净、npm 上还没有这个版本，找到该提交成功的 Phoenix CI run（也可用 `--run-id` 指定）。
+1. 核对当前分支为 `main`、工作树干净、Diagram 的四平台 release 清单、bundle、完整许可证与公共 HTTPS 下载地址齐备，npm 上还没有这个版本，找到该提交成功的 Phoenix CI run（也可用 `--run-id` 指定）。
 2. 下载 CI 的九个原始 ZIP，逐个核对 GitHub digest。
 3. 用 [publish-phoenix-ui-r2.mjs](../scripts/publish-phoenix-ui-r2.mjs) 条件上传四个 engine（已存在即拒绝覆盖），公共 URL 回读通过后冻结 release manifest。凭据取已导出的 `AGENT_RELEASE_R2_*`，没有时读仓根 `.env.cf` 里的同名行。
-4. 用 [pack-phoenix-ui-release.mjs](../scripts/pack-phoenix-ui-release.mjs) 只打一次 tarball。
-5. 用 [check-phoenix-ui-release.mjs](../scripts/check-phoenix-ui-release.mjs) 在 Node 18 和维护 Node 上新装（engine 从公共 URL 下载），检查 0.3.0/0.6.0 工具保留共存、直接删除替换、无回执 Phoenix 副本重装与受管安装回滚。删除的旧工具不会回滚恢复。
+4. 用 [pack-phoenix-ui-release.mjs](../scripts/pack-phoenix-ui-release.mjs) 只打一次联合 tarball：保留 `package.json` 声明的 UI 和 Diagram bin、skill、文档及发行资源，最终包再次通过发布校验。`xgent-skills install` 默认安装两者。Diagram 默认使用仓库中已准备好的 release 资源，也可用 `--diagram-release-dir DIR` 指定同版本的完整正式资源目录，在打包阶段注入；本脚本不构建或上传 Diagram 引擎，缺少资源时在上传 UI 前停止。
+5. 用 [check-phoenix-ui-release.mjs](../scripts/check-phoenix-ui-release.mjs) 在 Node 18 和维护 Node 上联合新装（两个 engine 从公共 URL 下载），核对 Diagram 引擎摘要、可运行入口及重复安装；另检查 0.3.0/0.6.0 工具保留共存、直接删除替换、无回执 Phoenix 副本重装与受管安装回滚。删除的旧工具不会回滚恢复。
 6. `npm publish` 这个 tarball，再从 registry 下载回来核对 shasum、integrity 和 SHA-256。
 
-每步产物保存在 `local/phoenix-ui/releases/v<版本>-<短SHA>/`，中断后重跑会复核已有产物再续接。预发布版本必须加 `--tag`。CI 测过的提交之后 main 又有新提交时，用 `git worktree add <目录> <该SHA>` 在该提交上执行，产物留在那个 worktree 的 `local/` 下。
+每步产物保存在 `local/phoenix-ui/releases/v<版本>-<短SHA>/`，中断后重跑会复核已有产物再续接。预发布版本必须加 `--tag`。CI 测过的提交之后 main 又有新提交时，等待 main 当前 HEAD 的 CI 成功后再发布；不另建发布分支或检出旧提交发布。
 
 在仓库根目录直接 `npm publish` 会被 `prepublishOnly` 拒绝：检出里的 `dist/phoenix-ui/VERSION.json` 是开发清单，没有 engine 下载地址。发布过的 R2 对象和 npm 版本都不能覆盖，出错只能发新版本。
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xgent-ai/skills",
-  "version": "0.7.5",
-  "description": "XGENT skills 与 Claude Code 辅助工具:通过 npx 为项目安装 hooks、启用 settings,并安装 Phoenix UI 设计工具与 UI 验收 skills",
+  "version": "0.7.6",
+  "description": "XGENT skills 与项目辅助工具:安装 hooks、settings、Phoenix UI 与独立 Phoenix Diagram 图解候选",
   "keywords": [
     "claude-code",
     "skills",
@@ -15,24 +15,21 @@
   "bin": {
     "skills": "bin/xgent-skills.js",
     "xgent-skills": "bin/xgent-skills.js",
-    "phoenix-ui": "bin/phoenix-ui.js"
+    "phoenix-ui": "bin/phoenix-ui.js",
+    "phoenix-diagram": "bin/phoenix-diagram.js"
   },
   "scripts": {
     "test": "node scripts/run-tests.mjs",
     "test:phoenix": "node scripts/test-phoenix-ui.mjs",
+    "test:diagram": "node scripts/test-phoenix-diagram-native.mjs",
     "release:phoenix": "node scripts/release-phoenix-ui.mjs",
     "prepublishOnly": "node scripts/require-release-package.mjs"
   },
   "files": [
     "bin",
     ".claude/hooks",
-    "hooks/codex/context-goal-guard.py",
-    "hooks/codex/hooks.example.json",
-    "docs/codex-context-goal-guard.md",
-    "hooks/claude/context-goal-guard.js",
-    "hooks/claude/settings.example.json",
-    "docs/claude-context-goal-guard.md",
     "docs/phoenix-ui.md",
+    "docs/phoenix-diagram.md",
     "skills",
     "dist/phoenix-ui/bundle",
     "dist/phoenix-ui/VERSION.json",
@@ -40,7 +37,14 @@
     "dist/phoenix-ui/NOTICE.md",
     "dist/phoenix-ui/THIRD-PARTY.json",
     "dist/phoenix-ui/THIRD-PARTY-NOTICES.md",
-    "dist/phoenix-ui/THIRD-PARTY-LICENSES"
+    "dist/phoenix-ui/THIRD-PARTY-LICENSES",
+    "dist/phoenix-diagram/bundle",
+    "dist/phoenix-diagram/VERSION.json",
+    "dist/phoenix-diagram/LICENSE",
+    "dist/phoenix-diagram/NOTICE.md",
+    "dist/phoenix-diagram/THIRD-PARTY.json",
+    "dist/phoenix-diagram/THIRD-PARTY-NOTICES.md",
+    "dist/phoenix-diagram/THIRD-PARTY-LICENSES"
   ],
   "engines": {
     "node": ">=18"

package/skills/agi-mode/SKILL.md

@@ -22,11 +22,13 @@ disable-model-invocation: true
 
 每环只加载当前需要的流程，共用判定协议和搜索状态；协作与沉淀读 [技能演化](references/skill-evolution.md)。这些流程内置于本 skill，外部 `autoresearch`、`arena`、`reflect` 是兼容入口，单独安装 agi-mode 即可运行。
 
+真实可重放的代码或文档任务，可按当前阶段读取 [远端执行工具](references/remote-evolution.md)，提供匹配的任务契约与量表。它是可选执行能力，沿用 Eval/Hillclimb 的协议、判定词和授权；v2 先校准任务适配的多维质量与分辨力，再诊断基线余量/噪声/预算。默认严格；显式获准的一次探索只放行来源精度不足，不晋级/确认/采用，整体 inconclusive。TypeSafe 可在独立校准后辅助 search 反馈，不持有主分或采用权。缺配置时保留未执行状态。仓库 AGENTS 瘦身可路由至已安装的 `optimize-agents-md`：通过 `use-prompt-dsl` 的 Odyssey RULE 精炼原则、去重补缺，保留项目事实与作用域；仅诊断只读，缺 DSL skill 时停止并建议完整安装，优化流程不写入目标文件，也不依赖远端评测。
+
 先固定目标、质量底线、可改范围和基线，再改候选。判定器有缺陷时升协议版本并重测，不把换尺当进步。用于选方案的反馈属于开发证据；泛化结论需要未参与选择的任务，重复同题只证明稳定性。没有行为对照时，规则修订仍是改进假设。
 
 普通任务先完成当前目标；已授权持续改进时才运行完整搜索。持久修改 skill、全局指令、工具或偏好须在授权范围内，不从一次纠正推导永久规则。保留机制、证据、适用边界、反例与回退点；能力评估读 [进化证据](references/evolution-evidence.md)。
 
-`$agi-mode 复盘` 与 `$agi-mode reflect` 等价，默认回顾当前会话及已授权经验记录，给出沉淀建议；已有修改授权直接落实。可补充材料、范围或沉淀目标。
+`$agi-mode 复盘` 与 `$agi-mode reflect` 等价，默认回顾当前会话及已授权经验记录，给出沉淀建议并回写已审条目的处置；已有修改授权直接落实。可补充材料、范围或沉淀目标。
 
 ## 解决问题的闭环
 

package/skills/agi-mode/assets/sdlc/event.md

@@ -25,9 +25,8 @@ relations: []
 
 # <本次事实摘要>
 
-- 事实与证据：<本次读到/验证了什么；评审写种类、所审对象版本和范围，区别于观察 checkout>
-- 校准依据：<规范状态与来源自述的差异、证据覆盖与原文滞后；一致时简述依据>
-- 未完项与限制：<缺证、未同步、待决；没有则写无，不填猜测>
-- 下一步及解除条件：<动作 + 可观察完成判据；无后续则说明>
+- 独立留存理由：<不可变审计要求的出处；或原记录、可取回版本及当前页均不足以保留的具体并发/纠错事实；不能仅写里程碑完成、提交或状态更新>
+- 必须保留的事实或差异：<仅写独立留存所需内容；已有实施、验收、评审及处置事实直接链接原记录章节和版本，不再概述一遍>
+- 直接影响与未解项：<本事实改变的状态/范围、缺证或解除条件；原记录已有的只引用，无新增则省略>
 
-<!-- 仅在仓内协议要求独立留存时创建，正文说明为何原产物与当前页不足以保留该事实；普通进度直接更新对象状态页。创建时替换占位并移除此注释。source_state 有原文状态则保留，否则 null；candidate_state 仅在 state 为 unknown 时使用对应枚举。kind=review 时补 review_type: prd / dev-plan / code / other。sources.path、artifact 按仓根解析，正文链接按本文件目录解析。relations 如 {type: covers, target: 对象UUID, scope: FR-1}；评审用 reviews，复审用 rechecks。 -->
+<!-- 创建前先核对原记录；仅在仓内协议要求独立留存时使用，无法说明留存理由则不创建。普通进度和最终完成直接更新对象状态页，审计另有必填内容时从其要求。创建时替换占位并移除此注释。source_state 有原文状态则保留，否则 null；candidate_state 仅在 state 为 unknown 时使用对应枚举。kind=review 时补 review_type: prd / dev-plan / code / other。sources.path、artifact 按仓根解析，正文链接按本文件目录解析。relations 如 {type: covers, target: 对象UUID, scope: FR-1}；评审用 reviews，复审用 rechecks。 -->

package/skills/agi-mode/assets/sdlc/object-status.md

@@ -9,7 +9,7 @@
 
 - 状态：<固定状态码>；来源自述：<原文状态>；证据质量：<evidence_status>。
 - 核查：<带时区时间>；基线与适用范围：<分支/HEAD/dirty、所核实范围及同步限制>。
-- 依据：<原产物的路径、版本/hash、必要章节；有相关事件才链接>。
+- 依据：<直接链接原产物的路径、版本/hash、必要章节；计划进度链接恢复快照/完成记录，实现与验收链接已有里程碑记录，评审/处置链接原报告对应章节；不先建 event 代替这些来源，相关补充事件按需另链>。
 - 差异、缺证或阻塞：<实际限制；没有则省略>。
 - 下一步及完成判据：<具体动作与条件；归档对象不推荐动作>。
 

package/skills/agi-mode/assets/sdlc/protocol.md

@@ -16,6 +16,8 @@
 
 新来源或版本仍需在对应分段准确登记，但不单独构成创建事件的理由。同一进度、状态或下一步只在所属分段展开，不在索引、页头或其他维度再写摘要；事件总数、历史覆盖条数等可枚举信息不手工维护，计划的里程碑完成数只在 implementation 分段按原计划保留。覆盖当前页前确认被替换的有效事实已有可取回来源；唯一的待决、授权依据或未解冲突不得直接丢弃，先保留在当前页，确需独立留存时才建事件。hash 只能检测变化，不能代替可取回内容。用户要求只读/仅聊天/不保存时不登记。
 
+**开发过程直接复用原记录**：计划就绪依据链接原计划与决策/评审章节；实施进度链接原计划的恢复快照/完成记录；实现、验收、偏差、阻塞及解除条件链接已有里程碑记录的对应章节；评审与整改链接原报告及处置记录。来源带必要版本与定位，台账只留当前判断和影响下一步的差异，不复述过程。里程碑推进、验证结果更新、最终提交、整份计划完成以及台账与原文的状态校准，都不单独构成新建事件的理由；不先生成 event，再用 event 替代原记录作为依据。
+
 ## 分类与读取
 
 - 本目录只保存状态及其索引、协议和必要的补充事件。PRD、开发计划、评审报告、实施/验收记录、测试计划、原始日志/截图等继续按用户习惯与项目约定保存；不规定它们的目录或文件名，不搬迁、复制或创建在本目录。用 `artifact`、`sources` 及来源链接引用实际位置。
@@ -58,7 +60,7 @@
 
 ## 补充事件（按需）
 
-仅符合“保存取舍”中的独立留存条件时，新建 `events/<kind>/<object_id>/<event_id>.md`，并注明为何原产物与当前页不足以保留该事实。首次需要时再复制事件模板为 `event-template.md`；已有模板沿用。记录为 YAML frontmatter 加简短 Markdown 证据正文，去掉不适用的可选字段。一旦交付保存不覆盖；需要纠正该事件时新建接续事件。写前重读相关记录，文件名已存在则核对，禁止覆盖不同内容。字段兼容 v3 历史事件：
+新建前先读取相关原记录及其可取回版本，核对拟留存内容是否已可恢复。仅符合“保存取舍”中的独立留存条件时，新建 `events/<kind>/<object_id>/<event_id>.md`；必须写明不可变审计要求的出处，或指出原记录及当前页均不足以保留的具体并发/纠错事实。只有来源复述、状态变化或新观察时间时不创建。首次需要时再复制事件模板为 `event-template.md`；已有模板沿用。记录为 YAML frontmatter 加简短 Markdown 证据正文，去掉不适用的可选字段。一旦交付保存不覆盖；需要纠正该事件时新建接续事件。写前重读相关记录，文件名已存在则核对，禁止覆盖不同内容。字段兼容 v3 历史事件：
 
 | 字段 | 约定 |
 | --- | --- |
@@ -78,7 +80,7 @@
 | `sources` | 路径 + 版本/hash + 稳定章节/问题定位；至少一个事实来源，未知版本明确写 unknown |
 | `relations`（可选） | `type`、`target` 对象 ID、`scope`；如 `covers`（承接需求）、`reviews`、`rechecks`、`depends-on`、`derived-from`、`same-as`；关系在后续事件中可显式撤销并给依据，不默默遗失 |
 
-正文记录事实摘要、证据、未完项/解除条件及建议动作。测试与报告的长内容留在来源文件，只链到必要段落。关系、状态变更及作废均须有依据。角色/责任人、实际活动日期、分期等按需补充，未知不填成默认事实。
+正文只写独立留存理由、必须保留的事实或差异及其直接影响，已有实施过程、验证结果、评审结论和解除条件只链到原记录的必要段落，不复制一套摘要；审计另有必填内容时从其要求。关系、状态变更及作废均须有依据。角色/责任人、实际活动日期、分期等按需补充，未知不填成默认事实。
 
 维度与固定枚举分开保存；具体状态集合及证据门槛见 state-model.md。项目扩展先登记定义，不要求全部维度存在：