@xgent-ai/skills 0.7.5 → 0.7.6

package/bin/xgent-skills.js

@@ -14,12 +14,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');
-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 以本包为准覆盖,其余已有配置保持不动。
@@ -37,6 +31,9 @@ const MANAGED_SETTINGS = {
 
 const bootstrap = require('../skills/phoenix-ui/scripts/phoenix-bootstrap.cjs');
 const PHOENIX_DIR = path.join(PKG_ROOT, 'dist', 'phoenix-ui');
+const includesDiagram = Boolean(readJson(path.join(PKG_ROOT, 'package.json')).bin['phoenix-diagram']);
+const diagramBootstrap = includesDiagram ? require('../skills/phoenix-diagram/scripts/phoenix-bootstrap.cjs') : null;
+const DIAGRAM_DIR = path.join(PKG_ROOT, 'dist', 'phoenix-diagram');
 const PHOENIX_STATUS = {
   planned: '计划', installed: '已安装', unchanged: '未变', conflict: '冲突,未激活',
   'recovery-required': '待恢复', 'integration-pending': '已安装但融合未就绪',
@@ -46,13 +43,6 @@ function readJson(file) {
   return JSON.parse(fs.readFileSync(file, 'utf8'));
 }
 
-function writeFileIfChanged(dest, content) {
-  if (fs.existsSync(dest) && content.equals(fs.readFileSync(dest))) return false;
-  fs.mkdirSync(path.dirname(dest), { recursive: true });
-  fs.writeFileSync(dest, content, { mode: 0o644 });
-  return true;
-}
-
 function phoenixFailure(code, message) {
   return Object.assign(new Error(message), { code });
 }
@@ -187,7 +177,7 @@ async function preparePhoenix(targetDir, options) {
       + '  可用 --release-dir=DIR 指向已核验的离线 release 目录,或加 --no-phoenix-ui 先安装其余部分。');
   }
   const args = ['install', '--project', targetDir, '--bundle-root', path.join(PHOENIX_DIR, 'bundle'),
-    '--auxiliary-root', path.join(PKG_ROOT, 'skills'), '--keep-impeccable', '--json'];
+    '--keep-impeccable', '--json'];
   if (options.providers) args.push('--providers', options.providers);
   const plan = runPhoenix(binary, [...args, '--dry-run']).report;
   const tools = preparePhoenixTools(plan.project, plan.providers);
@@ -198,6 +188,85 @@ async function preparePhoenix(targetDir, options) {
   return { manifest, binary, args, tools };
 }
 
+function runDiagram(binary, args) {
+  const result = spawnSync(binary, args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, windowsHide: true });
+  if (result.error) throw phoenixFailure(4, `无法运行 Phoenix Diagram engine: ${result.error.message}`);
+  try {
+    return { code: result.status, report: JSON.parse(result.stdout) };
+  } catch {
+    throw phoenixFailure([2, 3].includes(result.status) ? result.status : 4,
+      `Phoenix Diagram 安装执行器失败(exit ${result.status}): ${(result.stderr || '').trim()}`);
+  }
+}
+
+async function prepareDiagram(targetDir, options) {
+  try {
+    const ready = await diagramBootstrap.preflight({
+      project: targetDir, manifestPath: path.join(DIAGRAM_DIR, 'VERSION.json'),
+      bundleRoot: path.join(DIAGRAM_DIR, 'bundle'), packageJsonPath: path.join(PKG_ROOT, 'package.json'),
+      releaseDir: options.diagramReleaseDir, env: process.env, allowInstall: true, checkReceipt: false,
+    });
+    const args = ['install', '--project', targetDir, '--bundle-root', ready.bundleRoot, '--json'];
+    if (options.providers) args.push('--providers', options.providers);
+    const planned = runDiagram(ready.enginePath, [...args, '--dry-run']);
+    // 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 ((planned.code !== 0 && !recoverable) || !['planned', 'unchanged', 'recovery-required'].includes(planned.report.status)) {
+      printDiagram(planned.report, ready.manifest);
+      throw phoenixFailure(planned.code || 3, 'Phoenix Diagram 预检失败');
+    }
+    return { manifest: ready.manifest, binary: ready.enginePath, args };
+  } catch (error) {
+    throw phoenixFailure(Number.isInteger(error.code) ? error.code : 4, `Phoenix Diagram 未就绪,未修改项目: ${error.message}\n`
+      + '  可用 --diagram-release-dir=DIR 指向匹配的完整离线目录,或加 --no-phoenix-diagram 跳过本工具。');
+  }
+}
+
+async function migrateDiagram(project, options, confirmed) {
+  const ready = await diagramBootstrap.preflight({
+    project, exactProject: true, manifestPath: path.join(DIAGRAM_DIR, 'VERSION.json'),
+    bundleRoot: path.join(DIAGRAM_DIR, 'bundle'), packageJsonPath: path.join(PKG_ROOT, 'package.json'),
+    releaseDir: options.diagramReleaseDir, env: process.env, allowInstall: false, checkReceipt: false,
+  });
+  const args = ['migrate', '--from-archify', '--project', ready.project, '--bundle-root', ready.bundleRoot, '--json'];
+  if (options.providers) args.push('--providers', options.providers);
+  const planned = runDiagram(ready.enginePath, [...args, '--dry-run']);
+  printDiagram(planned.report, ready.manifest);
+  if (planned.code !== 0) { process.exitCode = planned.code || 3; return; }
+  console.log('  Archify 仅移除上述所选项目/provider 的完整已知来源;不备份,回滚不重建旧入口,需要时按原来源重装。');
+  let answer = confirmed;
+  if (!answer && !process.stdin.isTTY) throw phoenixFailure(3, '非交互迁移需要显式 --confirm-remove-archify;未开始删除或新入口写入。');
+  if (!answer) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try { answer = await confirm('确认直接移除上述 Archify 并安装 Phoenix Diagram? [y/N] ', '', rl[Symbol.asyncIterator]()); }
+    finally { rl.close(); }
+  }
+  if (!answer) { console.log('  取消迁移;未开始删除或新入口写入。'); return; }
+  const applied = runDiagram(ready.enginePath, [...args, '--confirm-remove-archify']);
+  printDiagram(applied.report, ready.manifest);
+  process.exitCode = applied.code || 0;
+}
+
+function printDiagram(report, manifest) {
+  const { toolVersion, npmPackageVersion } = manifest.data;
+  console.log(`Phoenix Diagram ${toolVersion} (@xgent-ai/skills@${npmPackageVersion}): ${PHOENIX_STATUS[report.status] || report.status}`);
+  for (const item of report.removals || []) console.log(`  ${item.status}  ${item.path} (${item.source})`);
+  for (const item of report.preserved || []) console.log(`  保留  ${item}`);
+  if (report.rollbackCommand) console.log(`  新入口回滚  ${report.rollbackCommand}`);
+  for (const item of report.reinstallInstructions || []) console.log(`  旧入口  ${item}`);
+  for (const item of report.writes || []) console.log(`  写入  ${item.path}`);
+  for (const item of report.conflicts || []) console.log(`  冲突  ${item.path}: ${item.message}`);
+  for (const item of report.diagnostics || []) console.log(`  诊断  ${item.code}: ${item.message}`);
+  if (report.recovered?.length) console.log(`  恢复  ${report.recovered.join(', ')}`);
+  if (report.transactionId) console.log(`  事务  ${report.transactionId};日志 ${report.journal};备份 ${report.backup}`);
+  if (report.status === 'installed') {
+    for (const provider of (report.providers || []).filter(p => p !== '.codex')) console.log(`  重载  ${provider}: 新开项目会话加载 ${provider === '.agents' ? '$' : '/'}phoenix-diagram`);
+  }
+  if (report.recoveryCommand && report.status === 'recovery-required') console.log(`  恢复命令  ${report.recoveryCommand}`);
+  for (const item of report.localIgnore || []) console.log(`  本地说明  ${item}`);
+}
+
 function groupedPaths(paths) {
   const groups = new Map();
   for (const file of paths) {
@@ -254,175 +323,6 @@ async function confirm(question, skipMessage, answers) {
   return /^(y|yes)$/i.test(value.trim());
 }
 
-// 重装没给阈值 flag 时沿用旧 handler 里的值。
-function guardThreshold(command) {
-  return Number(/ --threshold ([1-9][0-9]?)$/.exec(command)?.[1]) || undefined;
-}
-
-// 先校验并算出内容,返回写入动作;任何项目写入都在全部预检之后。
-function prepareContextGoalGuard(targetDir, force, threshold) {
-  const python = spawnSync('python3', ['-c', 'import sys, sqlite3; sys.exit(0 if sys.version_info >= (3, 9) else 1)'],
-    { encoding: 'utf8', timeout: 5000 });
-  if (python.status !== 0) {
-    throw new Error('Codex goal guard 需要含 sqlite3 的 Python 3.9 或更高版本。请先安装并用 python3 --version 核对,确保 Codex 运行环境也能找到 python3,再重试;或加 --no-context-goal-guard 跳过。');
-  }
-  const manifestPath = path.join(targetDir, '.codex', 'hooks.json');
-  let existing = {};
-  let backup = false;
-  if (fs.existsSync(manifestPath)) {
-    try {
-      existing = readJson(manifestPath);
-    } catch (error) {
-      if (!(error instanceof SyntaxError)) throw error;
-      if (!force) throw new Error(`${manifestPath} 不是合法 JSON,未修改;请先手动修复,或加 --force 备份为 .bak 后覆盖。`);
-      backup = true;
-    }
-  }
-  // 合法 JSON 的未知结构不能当成空配置,否则会丢失用户的 hooks。
-  if (!existing || typeof existing !== 'object' || Array.isArray(existing)
-      || (existing.hooks !== undefined && (!existing.hooks || typeof existing.hooks !== 'object' || Array.isArray(existing.hooks)))
-      || Object.values(existing.hooks || {}).some((entries) => !Array.isArray(entries))) {
-    throw new Error(`${manifestPath} 的 hooks 结构不受支持,未修改;请先手动修复为事件数组。`);
-  }
-  const scriptPath = path.join(fs.realpathSync(targetDir), '.codex', 'hooks', 'context-goal-guard.py');
-  let previous;
-  const hooks = { ...existing.hooks };
-  for (const event of ['PreToolUse', 'Stop']) {
-    const kept = [];
-    for (const entry of hooks[event] || []) {
-      if (!Array.isArray(entry?.hooks)) {
-        kept.push(entry);
-        continue;
-      }
-      const handlers = entry.hooks.filter((handler) => {
-        const guard = handler?.type === 'command' && typeof handler.command === 'string'
-          && /\.codex\/hooks\/context-goal-guard\.py(?:['"\s]|$)/.test(handler.command);
-        if (guard) previous ??= guardThreshold(handler.command);
-        return !guard;
-      });
-      if (handlers.length === entry.hooks.length) kept.push(entry);
-      else if (handlers.length > 0) kept.push({ ...entry, hooks: handlers });
-    }
-    hooks[event] = kept;
-  }
-  const limit = threshold ?? previous ?? CONTEXT_GOAL_GUARD_DEFAULT_THRESHOLD;
-  // 运行时从 Git 根目录定位,避免配置绑定安装机器或会话子目录。
-  const command = `python3 "$(git rev-parse --show-toplevel)/.codex/hooks/context-goal-guard.py" --threshold ${limit}`;
-  const handler = { type: 'command', command, timeout: 3 };
-  // 已有且仅有同一 handler 时保留原字节和位置:Phoenix 安装器随后会在同一文件追加自己的分组。
-  const installed = !backup && ['PreToolUse', 'Stop'].every((event) => {
-    const guards = (existing.hooks?.[event] || []).flatMap((entry) => (Array.isArray(entry?.hooks) ? entry.hooks : []))
-      .filter((item) => /\.codex\/hooks\/context-goal-guard\.py(?:['"\s]|$)/.test(item?.command ?? ''));
-    return guards.length === 1 && JSON.stringify(guards[0]) === JSON.stringify(handler);
-  });
-  for (const event of ['PreToolUse', 'Stop']) hooks[event].push({ hooks: [handler] });
-  const script = fs.readFileSync(CONTEXT_GOAL_GUARD_SRC);
-  const manifest = installed ? fs.readFileSync(manifestPath) : Buffer.from(JSON.stringify({ ...existing, hooks }, null, 2) + '\n');
-  return {
-    limit,
-    write() {
-      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)`);
-    },
-  };
-}
-
-function printContextGoalGuardSteps(threshold) {
-  console.log(`
-Codex goal guard 已部署,请完成以下操作后使用:
-  1. 在目标项目运行 codex --version;目前仅验证 Codex 0.160.0、macOS arm64。
-     其他版本的会话格式不自动兼容;请先在隔离项目验证。
-  2. 从目标项目启动 Codex,审阅并信任项目 .codex/ 层。
-     在 Codex 对话中输入 /hooks,找到本项目 .codex/hooks.json 的
-     PreToolUse 和 Stop 两个 context-goal-guard.py handler,分别审阅、信任并启用。
-     核对两者来源和状态,确认其他 hooks 仍保留;配置或脚本更新后重新审阅信任。
-  3. 安装与信任不构成暂停授权。请在当前 goal 的用户指令中明确(可复制):
-     对当前 goal,如果本地估算上下文使用率严格超过 ${threshold}%,请先安全收尾,
-     按已有任务约定保存进度和交接说明,再使用原生 goal 工具将其设为 paused
-     并核对,无需二次确认。未完成工作不要标为 complete。请提醒我自己新开对话继续。
-  4. 先用测试 goal 验证提醒与真实 paused 状态。/goal resume 撤销先前暂停请求,
-     需重新明确策略;新开对话也需手动设置新 goal 并重新明确策略。
-     暂停失败时在原对话输入 /goal pause;临时停用可在 /hooks 中禁用这两个 handler。
-  提示: 请安装到 Git 仓库根目录;Codex 运行环境必须能找到 git 和 Python 3.9+。
-        hook 运行时从 Git 根目录定位脚本;没有 active goal 时不会触发。
-`);
-}
-
-// 与 prepareContextGoalGuard 形状相似,但文件、事件和匹配式都不同,暂不抽公共函数。
-function prepareClaudeContextGoalGuard(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');
-  return {
-    limit,
-    write() {
-      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)`);
-    },
-  };
-}
-
-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 {
@@ -440,10 +340,9 @@ function usage() {
 命令:
   install [dir]   为目标项目(默认当前目录)安装 .claude/hooks 下的全部
                   hook,在 .claude/settings.json 中启用对应配置,并安装
-                  Phoenix UI(设计 skill、hooks 与五个辅助 skill;engine 校验后
+                  Phoenix UI(设计 skill 与 hooks;engine 校验后
                   放入用户 cache;旧 impeccable 可选择替换或共存),
-                  并询问是否创建通用的 AGENTS.md;
-                  Codex / Claude Code goal 上下文收尾提醒默认不安装
+${includesDiagram ? '                  以及 Phoenix Diagram(十类图解 skill 与独立原生 engine),\n' : ''}                  并询问是否创建通用的 AGENTS.md
   help            显示本帮助
 
 install 选项:
@@ -451,34 +350,31 @@ install 选项:
   --no-impeccable       已弃用,等同 --no-phoenix-ui
   --replace-impeccable  删除项目及个人级旧 impeccable 工具和 hooks,不备份
   --keep-impeccable     保留 impeccable,与 Phoenix UI 共存(无交互时默认)
-  --release-dir=DIR     离线安装 Phoenix UI engine:使用已核验的 release 目录,不联网
-  --xgent-init          创建 AGENTS.md (已有则跳过),不再询问
+${includesDiagram ? `  --no-phoenix-diagram  跳过 Phoenix Diagram(不删除已装版本)
+  --migrate-archify     仅执行 Diagram 预检/确认/迁移,跳过 hooks/settings/AGENTS/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,不再询问
-  --context-goal-guard  显式安装 Codex goal guard(默认不安装,需要 Python 3.9+)
-  --no-context-goal-guard 跳过 Codex goal guard(默认行为,保留已有 guard)
-  --context-goal-guard-threshold=N  Codex guard 的阈值百分比(1–99 整数,默认 ${CONTEXT_GOAL_GUARD_DEFAULT_THRESHOLD};
-                        重装时不给则沿用已装的值),同时表示安装
-  --claude-context-goal-guard 显式安装 Claude Code goal guard(默认不安装)
-  --no-claude-context-goal-guard 跳过 Claude Code goal guard(默认行为,保留已有 guard)
-  --claude-context-goal-guard-threshold=N  Claude Code guard 的阈值百分比(1–99 整数,
-                        默认 ${CLAUDE_CONTEXT_GOAL_GUARD_DEFAULT_THRESHOLD};重装时不给则沿用已装的值),同时表示安装
-  --providers=a,b       指定 Phoenix UI 装进哪些 harness 目录(默认按项目里已有的
+  --providers=a,b       指定 Phoenix 工具装进哪些 harness 目录(默认按项目里已有的
                         目录判断,都没有时装 .claude;codex 同时选 .agents 与 .codex)
-  --force               允许覆盖非法 JSON 的 guard 配置(先存 .bak),不覆盖已有 AGENTS.md;
-                        不绕过 Phoenix 受管安装及共享配置的冲突保护
 `);
 }
 
 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', '--context-goal-guard', '--no-context-goal-guard', '--claude-context-goal-guard', '--no-claude-context-goal-guard', '--force'].includes(f)
-    && !['--providers=', '--release-dir=', '--context-goal-guard-threshold=', '--claude-context-goal-guard-threshold='].some((p) => f.startsWith(p)));
+  const unknown = flags.filter((f) => !['--no-phoenix-ui', '--no-impeccable', '--replace-impeccable', '--keep-impeccable', '--xgent-init', '--no-xgent-init',
+    ...(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) {
     console.error(`错误: 未知选项: ${unknown.join(', ')}\n`);
     usage();
     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);
@@ -486,39 +382,27 @@ async function install(args) {
   if (flags.includes('--replace-impeccable') && flags.includes('--keep-impeccable')) {
     throw phoenixFailure(1, '--replace-impeccable 与 --keep-impeccable 不能同时使用');
   }
-  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 releaseDir = flags.find((f) => f.startsWith('--release-dir='))?.slice('--release-dir='.length);
+  const diagramReleaseDir = flags.find((f) => f.startsWith('--diagram-release-dir='))?.slice('--diagram-release-dir='.length);
   const options = {
     phoenix: !flags.includes('--no-phoenix-ui') && !flags.includes('--no-impeccable'),
-    force: flags.includes('--force'),
+    diagram: includesDiagram && !flags.includes('--no-phoenix-diagram'),
     providers: flags.find((f) => f.startsWith('--providers='))?.slice('--providers='.length),
     releaseDir: releaseDir ? path.resolve(releaseDir) : undefined,
+    diagramReleaseDir: diagramReleaseDir ? path.resolve(diagramReleaseDir) : undefined,
   };
+  if (options.diagram && !diagramBootstrap.TARGETS.includes(`${process.platform}-${process.arch}`)) {
+    if (diagramReleaseDir !== undefined) diagramBootstrap.platformTarget();
+    options.diagram = false;
+    console.log(`  跳过 Phoenix Diagram: ${process.platform}/${process.arch} 不在支持的四个 macOS/Linux 平台内。`);
+  }
+
+  if (flags.includes('--migrate-archify')) {
+    const target = path.resolve(dirArg || process.cwd());
+    if (!options.diagram) { console.log('  跳过 Phoenix Diagram 迁移;保留 Archify。'); return; }
+    await migrateDiagram(target, options, flags.includes('--confirm-remove-archify'));
+    return;
+  }
 
   // 跳过 Phoenix 时仍按包内 bundle 校验 --providers,保持旧参数语义;启用时由执行器校验。
   if (!options.phoenix && options.providers) {
@@ -554,11 +438,8 @@ async function install(args) {
   }
   const agentsExists = fs.existsSync(path.join(targetDir, 'AGENTS.md'));
   const askAgents = !flags.includes('--xgent-init') && !flags.includes('--no-xgent-init') && !agentsExists;
-  const guard = flags.includes('--context-goal-guard') || codexThreshold !== undefined;
-  const claudeGuard = flags.includes('--claude-context-goal-guard') || claudeThreshold !== undefined;
-  let codexGuardPlan = guard ? prepareContextGoalGuard(targetDir, options.force, codexThreshold) : null;
-  let claudeGuardPlan = claudeGuard ? prepareClaudeContextGoalGuard(targetDir, options.force, claudeThreshold) : null;
   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)
     ? readline.createInterface({ input: process.stdin, output: process.stdout }) : null;
@@ -578,13 +459,9 @@ async function install(args) {
   }
   if (phoenix) {
     phoenix.tools.apply(replace);
-    // Cleanup may change shared settings that the optional guards also merge.
+    // Cleanup may change shared settings.
     if (fs.existsSync(settingsPath)) settings = readJson(settingsPath);
-    codexGuardPlan = guard ? prepareContextGoalGuard(targetDir, options.force, codexThreshold) : null;
-    claudeGuardPlan = claudeGuard ? prepareClaudeContextGoalGuard(targetDir, options.force, claudeThreshold) : null;
   }
-  codexGuardPlan?.write();
-  claudeGuardPlan?.write();
 
   const hooksDestDir = path.join(targetDir, '.claude', 'hooks');
   fs.mkdirSync(hooksDestDir, { recursive: true });
@@ -612,8 +489,6 @@ async function install(args) {
 
   if (agents) createAgents(targetDir);
   else if (agentsExists && !flags.includes('--no-xgent-init')) console.log('  跳过  AGENTS.md (已存在,保留原文)');
-  if (codexGuardPlan) printContextGoalGuardSteps(codexGuardPlan.limit);
-  if (claudeGuardPlan) printClaudeContextGoalGuardSteps(claudeGuardPlan.limit);
 
   // XGENT 部分已完成;Phoenix 在锁内重读这些文件后再应用,中断时可重试。
   if (phoenix) {
@@ -621,17 +496,34 @@ async function install(args) {
     try {
       applied = runPhoenix(phoenix.binary, phoenix.args);
     } catch (error) {
-      console.log('未完成: XGENT 部分已安装;Phoenix UI 待恢复(安装被中断,可能已部分写入),按下方错误处理后重跑本命令,会先按日志恢复(可重复执行)。');
+      console.log(`未完成: XGENT 部分已安装;Phoenix UI 待恢复(安装被中断,可能已部分写入),按下方错误处理后重跑本命令,会先按日志恢复(可重复执行)。${diagram ? 'Phoenix Diagram 未执行。' : ''}`);
       throw error;
     }
     printPhoenix(applied.report, phoenix.manifest);
     if (applied.code !== 0) {
       process.exitCode = applied.code;
       console.log(`未完成: XGENT 部分已安装;Phoenix UI ${PHOENIX_STATUS[applied.report.status] || applied.report.status},按上方提示处理后重跑。`);
+      if (diagram) console.log('  待执行  Phoenix Diagram');
       return;
     }
     console.log('  提示  在 agent 对话里(不是终端)输入 /phoenix-ui init 完成设计上下文;Codex 用 $phoenix-ui');
   }
+  if (diagram) {
+    const completed = `XGENT 已安装${phoenix ? ',Phoenix UI 已完成' : ''}`;
+    let applied;
+    try {
+      applied = runDiagram(diagram.binary, diagram.args);
+    } catch (error) {
+      console.log(`未完成: ${completed};Phoenix Diagram 可能已部分写入,按错误和项目日志重跑恢复。`);
+      throw error;
+    }
+    printDiagram(applied.report, diagram.manifest);
+    if (applied.code !== 0) {
+      process.exitCode = applied.code;
+      console.log(`未完成: ${completed};Phoenix Diagram ${applied.report.status},保留前段结果,按上述提示重跑。`);
+      return;
+    }
+  }
   console.log(`完成: ${targetDir}`);
 }
 

package/dist/phoenix-diagram/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 XGENT.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/phoenix-diagram/NOTICE.md

@@ -0,0 +1,34 @@
+# Phoenix Diagram notices
+
+Phoenix Diagram 的 Archify 参考代码、schema、JSON 语料和阅读器来源保存在 [upstream/SOURCE.json](upstream/SOURCE.json)。3.1.0 来源是用户提供的本地快照，未核对上游提交；legacy 来源固定在 XGENT-ai/skills 提交 `4a65a1525f9ed03c775a0e18935901e1edbb773f`。
+
+Archify 源码采用 MIT License，保留以下署名：
+
+```text
+Copyright (c) 2026 tt-a1i (Archify)
+Copyright (c) 2025 Cocoon AI
+```
+
+MIT 全文保存在 [upstream/LICENSE-archify-MIT.txt](upstream/LICENSE-archify-MIT.txt)，也保留在完整归档及 legacy 子集中。
+
+Archify 阅读器模板嵌入的 JetBrains Mono 字体采用 SIL Open Font License 1.1。全文保存在 [upstream/JetBrainsMono-OFL.txt](upstream/JetBrainsMono-OFL.txt)，归档和 legacy 子集内也保留原许可。
+
+原生文本分段模块将 [ICU 77.1 官方 release-77-1 来源](https://github.com/unicode-org/icu/tree/release-77-1/icu4c/source)中的词边界规则、字典分派、CJK 成本分段和东南亚三词前瞻算法适配为 Rust，并使用 ICU4X 2.0 代际的 Unicode 16.0 compiled dictionaries 与规范化数据。修改包括 Rust 存储、UTF-8 字节偏移和原生词典调用；原始来源文件保持未修改。12 个原始文件的官方取回 URL、逐文件 SHA-256 和修改声明见 [文本来源清单](tests/fixtures/text-segmentation/sources.json)，清单本身及许可副本的冻结身份登记在 [upstream/SOURCE.json](upstream/SOURCE.json) 的 `nativeText` 条目，其中路径以 `tools/phoenix-diagram/` 为基准。
+
+原生 SystemV 时间模块将该 ICU 77.1 来源的 [zoneinfo64.txt](https://github.com/unicode-org/icu/blob/release-77-1/icu4c/source/data/misc/zoneinfo64.txt) 中六个夏令时区适配为 Rust：`SystemV/AST4ADT`、`SystemV/CST6CDT`、`SystemV/EST5EDT`、`SystemV/MST7MDT`、`SystemV/PST8PDT` 和 `SystemV/YST9YDT`。修改包括归一化的 150 项历史转换表和 1977 年起的最终年度规则；原始文件保持未修改，其头部 tz 版本为 2025a。官方取回 URL、原始字节大小与 SHA-256、六区选择及规则见 [时间来源清单](tests/fixtures/format/system-v-sources.json)，独立冻结身份登记在 `upstream/SOURCE.json` 的 `nativeTime` 条目；只采用这六区的数据，不替换既有 IANA 时区库。
+
+ICU 适配及数据的 Unicode-3.0 许可和完整第三方 notices 保存在 [assets/icu77-LICENSE.txt](assets/icu77-LICENSE.txt)，该文件是官方 ICU 77.1 许可的原字节副本。开发期来源校验离线检查清单、每个原始文件及许可副本，来源缺失或字节变化时直接失败，不下载、恢复或刷新基线。这些原始开发 fixtures 不进入消费端 npm 包。
+
+六个锁定 Rust 依赖缺少独立许可文件的情形，由 [assets/license-sources.json](assets/license-sources.json) 和 [assets/licenses/](assets/licenses/) 中四份未修改的全文补齐。清单固定 crate 版本、Cargo.lock 归档 SHA-256、repository、`.cargo_vcs_info.json` 的 commit/path、原 Cargo/README 适用性证据，以及全文的原始 URL、大小和 SHA-256；其冻结身份与全文来源登记在 `upstream/SOURCE.json` 的 `rustLicenses` 条目。它们是发行构建的固定输入，普通来源检查、prepare 前置检查和 build 都不隐式下载、修补或更新这些许可。
+
+`jsonschema-regex` / `jsonschema-value` 0.58.6 共用同一仓库提交 `55ac1664384793c5d3b20745d3f9c169dfe2c06f` 的完整 MIT 许可，保留 Dmitry Dygalo 的该提交署名。`uuid-simd` / `vsimd` 0.8.0 共用提交 `d74c030d9dc4f3cae02146d1f497ff62726ef09a` 的完整 MIT 许可，保留 Nugine 署名。`r-efi` 5.3.0 选择其 `MIT OR Apache-2.0 OR LGPL-2.1-or-later` 中的 MIT 分支，原样保留提交 `97b55bed1c2c91dcbf787674849f05337ff80b33` 的整份 `AUTHORS`，其中包含完整 MIT 许可及该版本版权；其中 Apache/LGPL 的摘要声明不计为这两个分支的完整许可。
+
+`selectors` 0.38.0 的适用性来自 Stylo 提交 `572ecba2d1600e7c3d490586692a209faf703baa` 的 Cargo 声明及 `selectors/lib.rs` 原始 MPL-2.0 文件头；该提交未携带 MPL 全文。清单分别保留该源码文件和文件头的 SHA-256，并从其明确指向的 Mozilla 官方 MPL 2.0 取得全文：字节来自 [Mozilla Bedrock 固定提交中的版本 2.0 文本](https://github.com/mozilla/bedrock/blob/a15178c3c7c976c67b3641af77cae0b66093a175/media/MPL/2.0/index.txt)。这份通用许可正文独立于 Stylo 源码提交，不借用其他项目的 MIT/Apache 版权或宣称 Stylo 仓库自带该全文。
+
+完整快照和 legacy oracle 的导入闭包包含历史第三方品牌数据及对应原始 notices，供开发期参考。冻结源码独立于消费者运行资源，来源归档不进入 npm 包。历史 P1 的运行资源不携带 Simple Icons 或官方品牌数据。
+
+P3 的原生固定品牌目录原字节派生自该 3.1.0 快照的 `generated-brand-marks.mjs`，保留 107 项的图形和原始 provenance。Simple Icons 16.28.0 集合的 CC0 许可不替代各品牌记录的单独条款、商标或其他权利。目录及完整许可来源清单见 [assets/brand-license-sources.json](assets/brand-license-sources.json)，其固定身份登记在 `upstream/SOURCE.json` 的 `nativeBrands` 条目。八份全文保留集合 CC0、JavaScript MIT 及原目录已记载的 CC0、CC-BY-4.0、CC-BY-SA-3.0、CC-BY-SA-4.0、CC-BY-NC-SA-4.0 和 Apache-2.0；原始 Archify notices 与 Simple Icons DISCLAIMER 同时保留。未记录单独许可的品牌不据此推定为 CC0，也不宣称已获特定使用授权。
+
+构建与 P3 候选逐项核品牌目录、许可清单、全文和 notices 的来源元组及摘要。发行法律资源离线保存原目录 provenance、原始清单、全部全文与 notices；普通作图不联网补材料。完整迁移来源仍只用于开发期识别及测试，既不是用户目标备份，也不进入 npm 包。
+
+时间线 IANA 命名时区由 `chrono-tz` 0.10.4 编译期内置的 tzdata 2025b 计算，上述六个 ICU 专属 SystemV 时区使用独立原生规则；`chrono` 0.4.45 负责日期与固定偏移。两者的 MIT/Apache-2.0 全文随 Cargo.lock 从各自 crate 收集。tz 代码与数据按其 `tz/LICENSE` 属于公有领域，`chrono-tz` 的 LICENSE 同样声明其许可不适用于 tzdb 文件。