@xgent-ai/skills 0.7.4 → 0.7.6

package/bin/xgent-skills.js

@@ -8,17 +8,12 @@
 const { spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
+const os = require('node:os');
 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 以本包为准覆盖,其余已有配置保持不动。
@@ -31,12 +26,14 @@ const MANAGED_SETTINGS = {
 };
 
 // ─── Phoenix UI ─────────────────────────────────────────────────────────────
-// Phoenix 的 skill、hooks、旧 impeccable 迁移与回滚全部由 Rust 安装执行器事务化
-// 完成;这里只把包内 manifest 固定的 engine 校验进用户 cache,再以参数数组调用
-// 它,不在 JS 里再写一套配置合并。旧 vendor/impeccable 安装路径已移除。
+// Phoenix 的受管安装、hooks 与回执由 Rust 执行器事务化完成。
+// 旧工具是否删除由 npm 安装入口询问,工具清理不备份、不迁移旧数据。
 
 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 });
 }
@@ -69,6 +59,112 @@ function runPhoenix(binary, args) {
   }
 }
 
+// Tool directories are reinstallable. Shared settings retain unrelated entries.
+function preparePhoenixTools(project, providers) {
+  const refresh = [];
+  const legacy = new Set();
+  const configs = new Set();
+  const parents = new Map();
+  let managed = [];
+  try {
+    managed = readJson(path.join(project, '.phoenix-ui/install/active.json')).ownership
+      .filter(item => item.sha256).map(item => item.path);
+  } catch { /* The engine reports an absent or invalid receipt during preflight. */ }
+  const present = (file) => !!fs.lstatSync(file, { throwIfNoEntry: false });
+  const checked = (root, relative) => {
+    const file = path.join(root, relative);
+    parents.set(file, root);
+    return file;
+  };
+  const home = fs.realpathSync(os.homedir());
+  for (const provider of providers) {
+    const roots = provider === '.agents' || provider === '.codex'
+      ? ['.agents', '.codex'] : [provider];
+    for (const root of [project, home]) {
+      for (const dir of roots) {
+        for (const relative of [
+          `${dir}/skills/impeccable`, `${dir}/commands/impeccable.md`,
+          ...['asset-producer', 'documenter', 'finish-reviewer', 'manual-edit-applier']
+            .map(name => `${dir}/agents/impeccable-${name}.md`),
+        ]) {
+          // An earlier explicit migration may own a Phoenix compatibility entry.
+          if (root === project && managed.some(file => file === relative || file.startsWith(`${relative}/`))) continue;
+          const file = checked(root, relative);
+          if (present(file)) legacy.add(file);
+        }
+        const shared = dir === '.claude' ? ['settings.json', 'settings.local.json']
+          : dir === '.gemini' ? ['settings.json']
+            : ['.github', '.grok'].includes(dir) ? ['hooks/impeccable.json', 'hooks/phoenix-ui.json'] : ['hooks.json'];
+        for (const relative of shared) {
+          const file = checked(root, `${dir}/${relative}`);
+          if (present(file)) configs.add(file);
+        }
+      }
+    }
+    if (!fs.existsSync(path.join(project, '.phoenix-ui/install'))) {
+      const file = checked(project, `${provider}/skills/phoenix-ui`);
+      if (present(file)) 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);
+  const oldHandler = value => value?.type === 'command'
+    && [value.command, value.commandWindows].some(oldCommand);
+  const originals = [...configs].map(file => ({ file, before: fs.readFileSync(file) }));
+  const hasLegacy = legacy.size > 0 || originals.some(({ before }) =>
+    /impeccable/.test(before.toString()) && (oldCommand(before.toString().replaceAll('\\"', '"')) || /"impeccable[^"\n]*"\s*:\s*true/.test(before.toString())));
+  const covers = relative => refresh.some(file => {
+    const target = path.relative(project, file).split(path.sep).join('/');
+    return relative === target || relative.startsWith(`${target}/`);
+  });
+  return {
+    hasLegacy, covers,
+    apply(replace) {
+      const updates = [];
+      if (replace) {
+        const clean = value => {
+          if (Array.isArray(value)) return value.filter(item => !oldHandler(item))
+            .flatMap(item => {
+              const next = clean(item);
+              return item?.hooks?.length > 0 && Array.isArray(next.hooks) && next.hooks.length === 0 ? [] : [next];
+            });
+          if (!value || typeof value !== 'object') return value;
+          return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, clean(item)]));
+        };
+        for (const item of originals) {
+          let data;
+          try { data = JSON.parse(item.before.toString('utf8')); }
+          catch { throw phoenixFailure(1, `无法移除旧 hooks,配置不是合法 JSON: ${item.file}`); }
+          const next = { ...data };
+          if (data.hooks) next.hooks = clean(data.hooks);
+          if (data.enabledPlugins) next.enabledPlugins = Object.fromEntries(Object.entries(data.enabledPlugins)
+            .map(([key, value]) => [key, key.startsWith('impeccable') ? false : value]));
+          if (JSON.stringify(data) !== JSON.stringify(next)) updates.push({ ...item, after: JSON.stringify(next, null, 2) + '\n' });
+        }
+        for (const item of updates) {
+          if (!fs.readFileSync(item.file).equals(item.before)) throw phoenixFailure(3, `配置在预检后发生变化,请重跑: ${item.file}`);
+        }
+      }
+      const removals = [...refresh, ...(replace ? legacy : [])];
+      for (const file of [...removals, ...updates.map(item => item.file)]) {
+        for (let dir = path.dirname(file); dir !== parents.get(file); dir = path.dirname(dir)) {
+          if (fs.lstatSync(dir, { throwIfNoEntry: false })?.isSymbolicLink()) throw phoenixFailure(3, `工具目录的父路径是符号链接,未修改: ${dir}`);
+        }
+        if (updates.some(item => item.file === file) && fs.lstatSync(file).isSymbolicLink()) throw phoenixFailure(3, `共享配置是符号链接,未修改: ${file}`);
+      }
+      for (const file of removals) {
+        fs.rmSync(file, { recursive: true, force: true });
+        console.log(`  ${refresh.includes(file) ? '重新安装' : '删除'}  ${file}`);
+      }
+      for (const item of updates) {
+        fs.writeFileSync(item.file, item.after);
+        console.log(`  更新  ${item.file} (移除 impeccable hooks/插件启用项)`);
+      }
+      if (hasLegacy && !replace) console.log('  保留  impeccable,与 Phoenix UI 共存');
+    },
+  };
+}
+
 // 预检只写用户 cache 里的 engine;dry-run 不写项目。冲突时整个安装在写项目前停下。
 async function preparePhoenix(targetDir, options) {
   const manifest = bootstrap.manifestAt(path.join(PHOENIX_DIR, 'VERSION.json'));
@@ -81,14 +177,94 @@ 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'), '--json'];
+    '--keep-impeccable', '--json'];
   if (options.providers) args.push('--providers', options.providers);
   const plan = runPhoenix(binary, [...args, '--dry-run']).report;
-  if (plan.status === 'conflict') {
+  const tools = preparePhoenixTools(plan.project, plan.providers);
+  if (plan.status === 'conflict' && plan.conflicts.some(conflict => !tools.covers(conflict.path))) {
     printPhoenix(plan, manifest);
     throw phoenixFailure(3, 'Phoenix UI 预检发现冲突,未修改项目。解决上列冲突后重跑;或加 --no-phoenix-ui 先安装其余部分。');
   }
-  return { manifest, binary, args };
+  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) {
@@ -147,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 {
@@ -333,80 +340,69 @@ function usage() {
 命令:
   install [dir]   为目标项目(默认当前目录)安装 .claude/hooks 下的全部
                   hook,在 .claude/settings.json 中启用对应配置,并安装
-                  Phoenix UI(设计 skill、hooks 与五个辅助 skill;engine 校验后
-                  放入用户 cache;旧 impeccable 项目事务化迁移、可回滚),
-                  并询问是否创建通用的 AGENTS.md;
-                  Codex / Claude Code goal 上下文收尾提醒默认不安装
+                  Phoenix UI(设计 skill 与 hooks;engine 校验后
+                  放入用户 cache;旧 impeccable 可选择替换或共存),
+${includesDiagram ? '                  以及 Phoenix Diagram(十类图解 skill 与独立原生 engine),\n' : ''}                  并询问是否创建通用的 AGENTS.md
   help            显示本帮助
 
 install 选项:
   --no-phoenix-ui       跳过 Phoenix UI,仍安装 XGENT 的 hooks 与 settings(不删除已装版本)
   --no-impeccable       已弃用,等同 --no-phoenix-ui
-  --release-dir=DIR     离线安装 Phoenix UI engine:使用已核验的 release 目录,不联网
-  --xgent-init          创建 AGENTS.md (已有则跳过),不再询问
+  --replace-impeccable  删除项目及个人级旧 impeccable 工具和 hooks,不备份
+  --keep-impeccable     保留 impeccable,与 Phoenix UI 共存(无交互时默认)
+${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 UI:用户改动与冲突始终保留,按提示解决后重跑
 `);
 }
 
 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', '--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);
   }
-  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('--replace-impeccable') && flags.includes('--keep-impeccable')) {
+    throw phoenixFailure(1, '--replace-impeccable 与 --keep-impeccable 不能同时使用');
   }
-  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) {
@@ -442,25 +438,30 @@ 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;
-  const codexGuardPlan = guard ? prepareContextGoalGuard(targetDir, options.force, codexThreshold) : null;
-  const claudeGuardPlan = claudeGuard ? prepareClaudeContextGoalGuard(targetDir, options.force, claudeThreshold) : null;
   const phoenix = options.phoenix ? await preparePhoenix(targetDir, options) : null;
-  const rl = process.stdin.isTTY && askAgents
+  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;
   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();
   }
-  codexGuardPlan?.write();
-  claudeGuardPlan?.write();
+  if (phoenix) {
+    phoenix.tools.apply(replace);
+    // Cleanup may change shared settings.
+    if (fs.existsSync(settingsPath)) settings = readJson(settingsPath);
+  }
 
   const hooksDestDir = path.join(targetDir, '.claude', 'hooks');
   fs.mkdirSync(hooksDestDir, { recursive: true });
@@ -488,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) {
@@ -497,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.