specops 0.1.0

package/bin/install.js

@@ -0,0 +1,2089 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const crypto = require('crypto');
+
+// 颜色
+const cyan = '\x1b[36m';
+const green = '\x1b[32m';
+const yellow = '\x1b[33m';
+const dim = '\x1b[2m';
+const reset = '\x1b[0m';
+
+// 从 package.json 获取版本
+const pkg = require('../package.json');
+
+// 解析参数
+const args = process.argv.slice(2);
+const hasGlobal = args.includes('--global') || args.includes('-g');
+const hasLocal = args.includes('--local') || args.includes('-l');
+const hasOpencode = args.includes('--opencode');
+const hasClaude = args.includes('--claude');
+const hasGemini = args.includes('--gemini');
+const hasCodex = args.includes('--codex');
+const hasBoth = args.includes('--both'); // 旧版标志, 保持兼容
+const hasAll = args.includes('--all');
+const hasUninstall = args.includes('--uninstall') || args.includes('-u');
+
+// 运行时选择 - 可通过标志或交互提示设置
+let selectedRuntimes = [];
+if (hasAll) {
+  selectedRuntimes = ['claude', 'opencode', 'gemini', 'codex'];
+} else if (hasBoth) {
+  selectedRuntimes = ['claude', 'opencode'];
+} else {
+  if (hasOpencode) selectedRuntimes.push('opencode');
+  if (hasClaude) selectedRuntimes.push('claude');
+  if (hasGemini) selectedRuntimes.push('gemini');
+  if (hasCodex) selectedRuntimes.push('codex');
+}
+
+// 获取运行时的目录名辅助函数 (用于本地/项目安装)
+function getDirName(runtime) {
+  if (runtime === 'opencode') return '.opencode';
+  if (runtime === 'gemini') return '.gemini';
+  if (runtime === 'codex') return '.codex';
+  return '.claude';
+}
+
+/**
+ * 获取运行时相对于主目录的配置目录路径
+ * 用于模板化使用 path.join(homeDir, '<configDir>', ...) 的钩子
+ * @param {string} runtime - 'claude', 'opencode', 'gemini', 或 'codex'
+ * @param {boolean} isGlobal - 是否为全局安装
+ */
+function getConfigDirFromHome(runtime, isGlobal) {
+  if (!isGlobal) {
+    // 本地安装使用相同的目录名模式
+    return `'${getDirName(runtime)}'`;
+  }
+  // 全局安装 - OpenCode 使用 XDG 路径结构
+  if (runtime === 'opencode') {
+    // OpenCode: ~/.config/opencode -> '.config', 'opencode'
+    // 返回逗号分隔格式用于 path.join() 替换
+    return "'.config', 'opencode'";
+  }
+  if (runtime === 'gemini') return "'.gemini'";
+  if (runtime === 'codex') return "'.codex'";
+  return "'.claude'";
+}
+
+/**
+ * 获取 OpenCode 的全局配置目录
+ * OpenCode 遵循 XDG 基础目录规范, 使用 ~/.config/opencode/
+ * 优先级: OPENCODE_CONFIG_DIR > dirname(OPENCODE_CONFIG) > XDG_CONFIG_HOME/opencode > ~/.config/opencode
+ */
+function getOpencodeGlobalDir() {
+  // 1. 显式 OPENCODE_CONFIG_DIR 环境变量
+  if (process.env.OPENCODE_CONFIG_DIR) {
+    return expandTilde(process.env.OPENCODE_CONFIG_DIR);
+  }
+  
+  // 2. OPENCODE_CONFIG 环境变量 (使用其目录)
+  if (process.env.OPENCODE_CONFIG) {
+    return path.dirname(expandTilde(process.env.OPENCODE_CONFIG));
+  }
+  
+  // 3. XDG_CONFIG_HOME/opencode
+  if (process.env.XDG_CONFIG_HOME) {
+    return path.join(expandTilde(process.env.XDG_CONFIG_HOME), 'opencode');
+  }
+  
+  // 4. 默认: ~/.config/opencode (XDG 默认)
+  return path.join(os.homedir(), '.config', 'opencode');
+}
+
+/**
+ * 获取运行时的全局配置目录
+ * @param {string} runtime - 'claude', 'opencode', 'gemini', 或 'codex'
+ * @param {string|null} explicitDir - 来自 --config-dir 标志的显式目录
+ */
+function getGlobalDir(runtime, explicitDir = null) {
+  if (runtime === 'opencode') {
+    // 对于 OpenCode, --config-dir 覆盖环境变量
+    if (explicitDir) {
+      return expandTilde(explicitDir);
+    }
+    return getOpencodeGlobalDir();
+  }
+  
+  if (runtime === 'gemini') {
+    // Gemini: --config-dir > GEMINI_CONFIG_DIR > ~/.gemini
+    if (explicitDir) {
+      return expandTilde(explicitDir);
+    }
+    if (process.env.GEMINI_CONFIG_DIR) {
+      return expandTilde(process.env.GEMINI_CONFIG_DIR);
+    }
+    return path.join(os.homedir(), '.gemini');
+  }
+
+  if (runtime === 'codex') {
+    // Codex: --config-dir > CODEX_HOME > ~/.codex
+    if (explicitDir) {
+      return expandTilde(explicitDir);
+    }
+    if (process.env.CODEX_HOME) {
+      return expandTilde(process.env.CODEX_HOME);
+    }
+    return path.join(os.homedir(), '.codex');
+  }
+  
+  // Claude Code: --config-dir > CLAUDE_CONFIG_DIR > ~/.claude
+  if (explicitDir) {
+    return expandTilde(explicitDir);
+  }
+  if (process.env.CLAUDE_CONFIG_DIR) {
+    return expandTilde(process.env.CLAUDE_CONFIG_DIR);
+  }
+  return path.join(os.homedir(), '.claude');
+}
+
+const banner = '\n' +
+  cyan + '   ██████╗ ███████╗██████╗\n' +
+  '  ██╔════╝ ██╔════╝██╔══██╗\n' +
+  '  ██║  ███╗███████╗██║  ██║\n' +
+  '  ██║   ██║╚════██║██║  ██║\n' +
+  '  ╚██████╔╝███████║██████╔╝\n' +
+  '   ╚═════╝ ╚══════╝╚═════╝' + reset + '\n' +
+  '\n' +
+  '  Get Shit Done ' + dim + 'v' + pkg.version + reset + '\n' +
+  '  元提示、上下文工程和规格驱动开发系统\n' +
+  '  适用于 Claude Code、OpenCode、Gemini 和 Codex, 由 TÂCHES 开发。\n';
+
+// 解析 --config-dir 参数
+function parseConfigDirArg() {
+  const configDirIndex = args.findIndex(arg => arg === '--config-dir' || arg === '-c');
+  if (configDirIndex !== -1) {
+    const nextArg = args[configDirIndex + 1];
+    // 如果 --config-dir 没有值或下一个参数是另一个标志则报错
+    if (!nextArg || nextArg.startsWith('-')) {
+      console.error(`  ${yellow}--config-dir 需要一个路径参数${reset}`);
+      process.exit(1);
+    }
+    return nextArg;
+  }
+  // 同时处理 --config-dir=value 格式
+  const configDirArg = args.find(arg => arg.startsWith('--config-dir=') || arg.startsWith('-c='));
+  if (configDirArg) {
+    const value = configDirArg.split('=')[1];
+    if (!value) {
+      console.error(`  ${yellow}--config-dir 需要一个非空路径${reset}`);
+      process.exit(1);
+    }
+    return value;
+  }
+  return null;
+}
+const explicitConfigDir = parseConfigDirArg();
+const hasHelp = args.includes('--help') || args.includes('-h');
+const forceStatusline = args.includes('--force-statusline');
+
+console.log(banner);
+
+// 如果请求帮助则显示
+if (hasHelp) {
+  console.log(`  ${yellow}用法:${reset} npx get-shit-done-cc [选项]\n\n  ${yellow}选项:${reset}\n    ${cyan}-g, --global${reset}              全局安装 (到配置目录)\n    ${cyan}-l, --local${reset}               本地安装 (到当前目录)\n    ${cyan}--claude${reset}                  仅安装 Claude Code\n    ${cyan}--opencode${reset}                仅安装 OpenCode\n    ${cyan}--gemini${reset}                  仅安装 Gemini\n    ${cyan}--codex${reset}                   仅安装 Codex\n    ${cyan}--all${reset}                     安装所有运行时\n    ${cyan}-u, --uninstall${reset}           卸载 SpecOps (移除所有 SpecOps 文件)\n    ${cyan}-c, --config-dir <path>${reset}   指定自定义配置目录\n    ${cyan}-h, --help${reset}                显示此帮助信息\n    ${cyan}--force-statusline${reset}        替换现有状态栏配置\n\n  ${yellow}示例:${reset}\n    ${dim}# 交互式安装 (提示选择运行时和位置)${reset}\n    npx get-shit-done-cc\n\n    ${dim}# 全局安装 Claude Code${reset}\n    npx get-shit-done-cc --claude --global\n\n    ${dim}# 全局安装 Gemini${reset}\n    npx get-shit-done-cc --gemini --global\n\n    ${dim}# 全局安装 Codex${reset}\n    npx get-shit-done-cc --codex --global\n\n    ${dim}# 全局安装所有运行时${reset}\n    npx get-shit-done-cc --all --global\n\n    ${dim}# 安装到自定义配置目录${reset}\n    npx get-shit-done-cc --codex --global --config-dir ~/.codex-work\n\n    ${dim}# 仅安装到当前项目${reset}\n    npx get-shit-done-cc --claude --local\n\n    ${dim}# 全局卸载 Codex 的 SpecOps${reset}\n    npx get-shit-done-cc --codex --global --uninstall\n\n  ${yellow}说明:${reset}\n    --config-dir 选项在你有多个配置时很有用。\n    它优先于 CLAUDE_CONFIG_DIR / GEMINI_CONFIG_DIR / CODEX_HOME 环境变量。\n`);
+  process.exit(0);
+}
+
+/**
+ * 展开 ~ 到主目录 (shell 不会在传递给 node 的环境变量中展开)
+ */
+function expandTilde(filePath) {
+  if (filePath && filePath.startsWith('~/')) {
+    return path.join(os.homedir(), filePath.slice(2));
+  }
+  return filePath;
+}
+
+/**
+ * 使用正斜杠构建钩子命令路径, 实现跨平台兼容。
+ * 在 Windows 上, $HOME 不会被 cmd.exe/PowerShell 展开, 所以我们使用实际路径。
+ */
+function buildHookCommand(configDir, hookName) {
+  // 使用正斜杠确保所有平台上的 Node.js 兼容性
+  const hooksPath = configDir.replace(/\\/g, '/') + '/hooks/' + hookName;
+  return `node "${hooksPath}"`;
+}
+
+/**
+ * 读取并解析 settings.json, 如果不存在则返回空对象
+ */
+function readSettings(settingsPath) {
+  if (fs.existsSync(settingsPath)) {
+    try {
+      return JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch (e) {
+      return {};
+    }
+  }
+  return {};
+}
+
+/**
+ * 以正确格式写入 settings.json
+ */
+function writeSettings(settingsPath, settings) {
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+}
+
+// 归属设置缓存 (安装期间每个运行时填充一次)
+const attributionCache = new Map();
+
+/**
+ * 获取运行时的提交归属设置
+ * @param {string} runtime - 'claude', 'opencode', 'gemini', 或 'codex'
+ * @returns {null|undefined|string} null = 移除, undefined = 保持默认, string = 自定义
+ */
+function getCommitAttribution(runtime) {
+  // 如果有缓存值则返回
+  if (attributionCache.has(runtime)) {
+    return attributionCache.get(runtime);
+  }
+
+  let result;
+
+  if (runtime === 'opencode') {
+    const config = readSettings(path.join(getGlobalDir('opencode', null), 'opencode.json'));
+    result = config.disable_ai_attribution === true ? null : undefined;
+  } else if (runtime === 'gemini') {
+    // Gemini: 检查 gemini settings.json 的归属配置
+    const settings = readSettings(path.join(getGlobalDir('gemini', explicitConfigDir), 'settings.json'));
+    if (!settings.attribution || settings.attribution.commit === undefined) {
+      result = undefined;
+    } else if (settings.attribution.commit === '') {
+      result = null;
+    } else {
+      result = settings.attribution.commit;
+    }
+  } else if (runtime === 'claude') {
+    // Claude Code
+    const settings = readSettings(path.join(getGlobalDir('claude', explicitConfigDir), 'settings.json'));
+    if (!settings.attribution || settings.attribution.commit === undefined) {
+      result = undefined;
+    } else if (settings.attribution.commit === '') {
+      result = null;
+    } else {
+      result = settings.attribution.commit;
+    }
+  } else {
+    // Codex 目前没有等效的归属设置
+    result = undefined;
+  }
+
+  // 缓存并返回
+  attributionCache.set(runtime, result);
+  return result;
+}
+
+/**
+ * 根据归属设置处理 Co-Authored-By 行
+ * @param {string} content - 要处理的文件内容
+ * @param {null|undefined|string} attribution - null=移除, undefined=保持, string=替换
+ * @returns {string} 处理后的内容
+ */
+function processAttribution(content, attribution) {
+  if (attribution === null) {
+    // 移除 Co-Authored-By 行及其前面的空行
+    return content.replace(/(\r?\n){2}Co-Authored-By:.*$/gim, '');
+  }
+  if (attribution === undefined) {
+    return content;
+  }
+  // 替换为自定义归属 (转义 $ 防止反向引用注入)
+  const safeAttribution = attribution.replace(/\$/g, '$$$$');
+  return content.replace(/Co-Authored-By:.*$/gim, `Co-Authored-By: ${safeAttribution}`);
+}
+
+/**
+ * 将 Claude Code 前置元数据转换为 opencode 格式
+ * - 将 'allowed-tools:' 数组转换为 'permission:' 对象
+ * @param {string} content - 带 YAML 前置元数据的 Markdown 文件内容
+ * @returns {string} - 转换后前置元数据的内容
+ */
+// 颜色名到十六进制映射, 用于 opencode 兼容性
+const colorNameToHex = {
+  cyan: '#00FFFF',
+  red: '#FF0000',
+  green: '#00FF00',
+  blue: '#0000FF',
+  yellow: '#FFFF00',
+  magenta: '#FF00FF',
+  orange: '#FFA500',
+  purple: '#800080',
+  pink: '#FFC0CB',
+  white: '#FFFFFF',
+  black: '#000000',
+  gray: '#808080',
+  grey: '#808080',
+};
+
+// 工具名映射: Claude Code -> OpenCode
+// OpenCode 使用小写工具名; 重命名工具的特殊映射
+const claudeToOpencodeTools = {
+  AskUserQuestion: 'question',
+  SlashCommand: 'skill',
+  TodoWrite: 'todowrite',
+  WebFetch: 'webfetch',
+  WebSearch: 'websearch',  // 插件/MCP - 保留兼容性
+};
+
+// 工具名映射: Claude Code -> Gemini CLI
+// Gemini CLI 使用 snake_case 内置工具名
+const claudeToGeminiTools = {
+  Read: 'read_file',
+  Write: 'write_file',
+  Edit: 'replace',
+  Bash: 'run_shell_command',
+  Glob: 'glob',
+  Grep: 'search_file_content',
+  WebSearch: 'google_web_search',
+  WebFetch: 'web_fetch',
+  TodoWrite: 'write_todos',
+  AskUserQuestion: 'ask_user',
+};
+
+/**
+ * 将 Claude Code 工具名转换为 OpenCode 格式
+ * - 应用特殊映射 (AskUserQuestion -> question 等)
+ * - 转换为小写 (MCP 工具保持原格式除外)
+ */
+function convertToolName(claudeTool) {
+  // 先检查特殊映射
+  if (claudeToOpencodeTools[claudeTool]) {
+    return claudeToOpencodeTools[claudeTool];
+  }
+  // MCP 工具 (mcp__*) 保持原格式
+  if (claudeTool.startsWith('mcp__')) {
+    return claudeTool;
+  }
+  // 默认: 转换为小写
+  return claudeTool.toLowerCase();
+}
+
+/**
+ * 将 Claude Code 工具名转换为 Gemini CLI 格式
+ * - 应用 Claude→Gemini 映射 (Read→read_file, Bash→run_shell_command 等)
+ * - 过滤 MCP 工具 (mcp__*), 它们在 Gemini 中运行时自动发现
+ * - 过滤 Task, Agent 在 Gemini 中自动注册为工具
+ * @returns {string|null} Gemini 工具名, 如果工具应被排除则返回 null
+ */
+function convertGeminiToolName(claudeTool) {
+  // MCP 工具: 排除, 运行时从 mcpServers 配置自动发现
+  if (claudeTool.startsWith('mcp__')) {
+    return null;
+  }
+  // Task: 排除, Agent 自动注册为可调用工具
+  if (claudeTool === 'Task') {
+    return null;
+  }
+  // 检查显式映射
+  if (claudeToGeminiTools[claudeTool]) {
+    return claudeToGeminiTools[claudeTool];
+  }
+  // 默认: 小写
+  return claudeTool.toLowerCase();
+}
+
+function toSingleLine(value) {
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+function yamlQuote(value) {
+  return JSON.stringify(value);
+}
+
+function extractFrontmatterAndBody(content) {
+  if (!content.startsWith('---')) {
+    return { frontmatter: null, body: content };
+  }
+
+  const endIndex = content.indexOf('---', 3);
+  if (endIndex === -1) {
+    return { frontmatter: null, body: content };
+  }
+
+  return {
+    frontmatter: content.substring(3, endIndex).trim(),
+    body: content.substring(endIndex + 3),
+  };
+}
+
+function extractFrontmatterField(frontmatter, fieldName) {
+  const regex = new RegExp(`^${fieldName}:\\s*(.+)$`, 'm');
+  const match = frontmatter.match(regex);
+  if (!match) return null;
+  return match[1].trim().replace(/^['"]|['"]$/g, '');
+}
+
+function convertSlashCommandsToCodexSkillMentions(content) {
+  let converted = content.replace(/\/specops:([a-z0-9-]+)/gi, (_, commandName) => {
+    return `$specops-${String(commandName).toLowerCase()}`;
+  });
+  converted = converted.replace(/\/specops-help\b/g, '$specops-help');
+  return converted;
+}
+
+function convertClaudeToCodexMarkdown(content) {
+  let converted = convertSlashCommandsToCodexSkillMentions(content);
+  converted = converted.replace(/\$ARGUMENTS\b/g, '{{SpecOps_ARGS}}');
+  return converted;
+}
+
+function getCodexSkillAdapterHeader(skillName) {
+  const invocation = `$${skillName}`;
+  return `<codex_skill_adapter>
+Codex skills 优先模式:
+- 此 skill 通过提及 \`${invocation}\` 来调用。
+- 将 \`${invocation}\` 之后的所有用户文本视为 \`{{SpecOps_ARGS}}\`。
+- 如果没有参数, 将 \`{{SpecOps_ARGS}}\` 视为空。
+
+旧版编排兼容性:
+- 引用的工作流文档中的任何 \`Task(...)\` 模式都是旧版语法。
+- 用 Codex 协作工具实现等效行为: \`spawn_agent\`、\`wait\`、\`send_input\` 和 \`close_agent\`。
+- 将旧版 \`subagent_type\` 名称视为生成消息中的角色提示。
+</codex_skill_adapter>`;
+}
+
+function convertClaudeCommandToCodexSkill(content, skillName) {
+  const converted = convertClaudeToCodexMarkdown(content);
+  const { frontmatter, body } = extractFrontmatterAndBody(converted);
+  let description = `运行 SpecOps 工作流 ${skillName}。`;
+  if (frontmatter) {
+    const maybeDescription = extractFrontmatterField(frontmatter, 'description');
+    if (maybeDescription) {
+      description = maybeDescription;
+    }
+  }
+  description = toSingleLine(description);
+  const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
+  const adapter = getCodexSkillAdapterHeader(skillName);
+
+  return `---\nname: ${yamlQuote(skillName)}\ndescription: ${yamlQuote(description)}\nmetadata:\n  short-description: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
+}
+
+/**
+ * 为 Gemini CLI 输出去除 HTML <sub> 标签
+ * 终端不支持下标, Gemini 会将其渲染为原始 HTML。
+ * 将 <sub>text</sub> 转换为斜体 *(text)* 以获得可读的终端输出。
+ */
+function stripSubTags(content) {
+  return content.replace(/<sub>(.*?)<\/sub>/g, '*($1)*');
+}
+
+/**
+ * 将 Claude Code agent 前置元数据转换为 Gemini CLI 格式
+ * Gemini agent 使用带 YAML 前置元数据的 .md 文件, 与 Claude 相同,
+ * 但字段名和格式不同:
+ * - tools: 必须是 YAML 数组 (不是逗号分隔的字符串)
+ * - 工具名: 必须使用 Gemini 内置名称 (read_file, 不是 Read)
+ * - color: 必须移除 (会导致验证错误)
+ * - mcp__* 工具: 必须排除 (运行时自动发现)
+ */
+function convertClaudeToGeminiAgent(content) {
+  if (!content.startsWith('---')) return content;
+
+  const endIndex = content.indexOf('---', 3);
+  if (endIndex === -1) return content;
+
+  const frontmatter = content.substring(3, endIndex).trim();
+  const body = content.substring(endIndex + 3);
+
+  const lines = frontmatter.split('\n');
+  const newLines = [];
+  let inAllowedTools = false;
+  const tools = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // 将 allowed-tools YAML 数组转换为工具列表
+    if (trimmed.startsWith('allowed-tools:')) {
+      inAllowedTools = true;
+      continue;
+    }
+
+    // 处理内联 tools: 字段 (逗号分隔字符串)
+    if (trimmed.startsWith('tools:')) {
+      const toolsValue = trimmed.substring(6).trim();
+      if (toolsValue) {
+        const parsed = toolsValue.split(',').map(t => t.trim()).filter(t => t);
+        for (const t of parsed) {
+          const mapped = convertGeminiToolName(t);
+          if (mapped) tools.push(mapped);
+        }
+      } else {
+        // tools: 没有值意味着后面跟着 YAML 数组
+        inAllowedTools = true;
+      }
+      continue;
+    }
+
+    // 去除 color 字段 (Gemini CLI 不支持, 会导致验证错误)
+    if (trimmed.startsWith('color:')) continue;
+
+    // 收集 allowed-tools/tools 数组项
+    if (inAllowedTools) {
+      if (trimmed.startsWith('- ')) {
+        const mapped = convertGeminiToolName(trimmed.substring(2).trim());
+        if (mapped) tools.push(mapped);
+        continue;
+      } else if (trimmed && !trimmed.startsWith('-')) {
+        inAllowedTools = false;
+      }
+    }
+
+    if (!inAllowedTools) {
+      newLines.push(line);
+    }
+  }
+
+  // 将工具添加为 YAML 数组 (Gemini 要求数组格式)
+  if (tools.length > 0) {
+    newLines.push('tools:');
+    for (const tool of tools) {
+      newLines.push(`  - ${tool}`);
+    }
+  }
+
+  const newFrontmatter = newLines.join('\n').trim();
+
+  // 转义 agent body 中的 ${VAR} 模式以兼容 Gemini CLI。
+  // Gemini 的 templateString() 将所有 ${word} 模式视为模板变量,
+  // 无法解析时会抛出 "Template validation failed: Missing required input parameters"。
+  // SpecOps agent 在 bash 代码块中使用 ${PHASE}、${PLAN} 等作为 shell 变量,
+  // 转换为 $VAR (无花括号), 这在 bash 中等效且对 Gemini 的 /\$\{(\w+)\}/g 正则不可见。
+  const escapedBody = body.replace(/\$\{(\w+)\}/g, '$$$1');
+
+  return `---\n${newFrontmatter}\n---${stripSubTags(escapedBody)}`;
+}
+
+function convertClaudeToOpencodeFrontmatter(content) {
+  // 替换内容中的工具名引用 (适用于所有文件)
+  let convertedContent = content;
+  convertedContent = convertedContent.replace(/\bAskUserQuestion\b/g, 'question');
+  convertedContent = convertedContent.replace(/\bSlashCommand\b/g, 'skill');
+  convertedContent = convertedContent.replace(/\bTodoWrite\b/g, 'todowrite');
+  // 将 /specops:command 替换为 /specops-command 用于 opencode (扁平命令结构)
+  convertedContent = convertedContent.replace(/\/specops:/g, '/specops-');
+  // 将 ~/.claude 替换为 ~/.config/opencode (OpenCode 的正确配置位置)
+  convertedContent = convertedContent.replace(/~\/\.claude\b/g, '~/.config/opencode');
+  // 将通用子 Agent 类型替换为 OpenCode 的等效 "general"
+  convertedContent = convertedContent.replace(/subagent_type="general-purpose"/g, 'subagent_type="general"');
+
+  // 检查内容是否有前置元数据
+  if (!convertedContent.startsWith('---')) {
+    return convertedContent;
+  }
+
+  // 找到前置元数据的结尾
+  const endIndex = convertedContent.indexOf('---', 3);
+  if (endIndex === -1) {
+    return convertedContent;
+  }
+
+  const frontmatter = convertedContent.substring(3, endIndex).trim();
+  const body = convertedContent.substring(endIndex + 3);
+
+  // 逐行解析前置元数据 (简单 YAML 解析)
+  const lines = frontmatter.split('\n');
+  const newLines = [];
+  let inAllowedTools = false;
+  const allowedTools = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // 检测 allowed-tools 数组的开始
+    if (trimmed.startsWith('allowed-tools:')) {
+      inAllowedTools = true;
+      continue;
+    }
+
+    // 检测内联 tools: 字段 (逗号分隔字符串)
+    if (trimmed.startsWith('tools:')) {
+      const toolsValue = trimmed.substring(6).trim();
+      if (toolsValue) {
+        // 解析逗号分隔的工具
+        const tools = toolsValue.split(',').map(t => t.trim()).filter(t => t);
+        allowedTools.push(...tools);
+      }
+      continue;
+    }
+
+    // 移除 name: 字段 - opencode 使用文件名作为命令名
+    if (trimmed.startsWith('name:')) {
+      continue;
+    }
+
+    // 为 opencode 将颜色名转换为十六进制
+    if (trimmed.startsWith('color:')) {
+      const colorValue = trimmed.substring(6).trim().toLowerCase();
+      const hexColor = colorNameToHex[colorValue];
+      if (hexColor) {
+        newLines.push(`color: "${hexColor}"`);
+      } else if (colorValue.startsWith('#')) {
+        // 验证十六进制颜色格式 (#RGB 或 #RRGGBB)
+        if (/^#[0-9a-f]{3}$|^#[0-9a-f]{6}$/i.test(colorValue)) {
+          // 已经是有效的十六进制, 保持原样
+          newLines.push(line);
+        }
+        // 跳过无效的十六进制颜色
+      }
+      // 跳过未知的颜色名
+      continue;
+    }
+
+    // 收集 allowed-tools 项
+    if (inAllowedTools) {
+      if (trimmed.startsWith('- ')) {
+        allowedTools.push(trimmed.substring(2).trim());
+        continue;
+      } else if (trimmed && !trimmed.startsWith('-')) {
+        // 数组结束, 新字段开始
+        inAllowedTools = false;
+      }
+    }
+
+    // 保留其他字段 (包括 opencode 忽略的 name:)
+    if (!inAllowedTools) {
+      newLines.push(line);
+    }
+  }
+
+  // 如果有 allowed-tools 或 tools 则添加 tools 对象
+  if (allowedTools.length > 0) {
+    newLines.push('tools:');
+    for (const tool of allowedTools) {
+      newLines.push(`  ${convertToolName(tool)}: true`);
+    }
+  }
+
+  // 重建前置元数据 (body 中的工具名已转换)
+  const newFrontmatter = newLines.join('\n').trim();
+  return `---\n${newFrontmatter}\n---${body}`;
+}
+
+/**
+ * 将 Claude Code markdown 命令转换为 Gemini TOML 格式
+ * @param {string} content - 带 YAML 前置元数据的 Markdown 文件内容
+ * @returns {string} - TOML 内容
+ */
+function convertClaudeToGeminiToml(content) {
+  // 检查内容是否有前置元数据
+  if (!content.startsWith('---')) {
+    return `prompt = ${JSON.stringify(content)}\n`;
+  }
+
+  const endIndex = content.indexOf('---', 3);
+  if (endIndex === -1) {
+    return `prompt = ${JSON.stringify(content)}\n`;
+  }
+
+  const frontmatter = content.substring(3, endIndex).trim();
+  const body = content.substring(endIndex + 3).trim();
+  
+  // 从前置元数据提取描述
+  let description = '';
+  const lines = frontmatter.split('\n');
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('description:')) {
+      description = trimmed.substring(12).trim();
+      break;
+    }
+  }
+
+  // 构造 TOML
+  let toml = '';
+  if (description) {
+    toml += `description = ${JSON.stringify(description)}\n`;
+  }
+  
+  toml += `prompt = ${JSON.stringify(body)}\n`;
+  
+  return toml;
+}
+
+/**
+ * 将命令复制到 OpenCode 的扁平结构
+ * OpenCode 期望: command/specops-help.md (以 /specops-help 调用)
+ * 源结构: commands/specops/help.md
+ * 
+ * @param {string} srcDir - 源目录 (如 commands/specops/)
+ * @param {string} destDir - 目标目录 (如 command/)
+ * @param {string} prefix - 文件名前缀 (如 'specops')
+ * @param {string} pathPrefix - 文件引用的路径前缀
+ * @param {string} runtime - 目标运行时 ('claude' 或 'opencode')
+ */
+function copyFlattenedCommands(srcDir, destDir, prefix, pathPrefix, runtime) {
+  if (!fs.existsSync(srcDir)) {
+    return;
+  }
+  
+  // 复制新文件前移除旧的 specops-*.md 文件
+  if (fs.existsSync(destDir)) {
+    for (const file of fs.readdirSync(destDir)) {
+      if (file.startsWith(`${prefix}-`) && file.endsWith('.md')) {
+        fs.unlinkSync(path.join(destDir, file));
+      }
+    }
+  } else {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+  
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    
+    if (entry.isDirectory()) {
+      // 递归进入子目录, 添加到前缀
+      // 如 commands/specops/debug/start.md -> command/specops-debug-start.md
+      copyFlattenedCommands(srcPath, destDir, `${prefix}-${entry.name}`, pathPrefix, runtime);
+    } else if (entry.name.endsWith('.md')) {
+      // 扁平化: help.md -> specops-help.md
+      const baseName = entry.name.replace('.md', '');
+      const destName = `${prefix}-${baseName}.md`;
+      const destPath = path.join(destDir, destName);
+
+      let content = fs.readFileSync(srcPath, 'utf8');
+      const globalClaudeRegex = /~\/\.claude\//g;
+      const localClaudeRegex = /\.\/\.claude\//g;
+      const opencodeDirRegex = /~\/\.opencode\//g;
+      content = content.replace(globalClaudeRegex, pathPrefix);
+      content = content.replace(localClaudeRegex, `./${getDirName(runtime)}/`);
+      content = content.replace(opencodeDirRegex, pathPrefix);
+      content = processAttribution(content, getCommitAttribution(runtime));
+      content = convertClaudeToOpencodeFrontmatter(content);
+
+      fs.writeFileSync(destPath, content);
+    }
+  }
+}
+
+function listCodexSkillNames(skillsDir, prefix = 'specops-') {
+  if (!fs.existsSync(skillsDir)) return [];
+  const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+  return entries
+    .filter(entry => entry.isDirectory() && entry.name.startsWith(prefix))
+    .filter(entry => fs.existsSync(path.join(skillsDir, entry.name, 'SKILL.md')))
+    .map(entry => entry.name)
+    .sort();
+}
+
+function copyCommandsAsCodexSkills(srcDir, skillsDir, prefix, pathPrefix, runtime) {
+  if (!fs.existsSync(srcDir)) {
+    return;
+  }
+
+  fs.mkdirSync(skillsDir, { recursive: true });
+
+  // 移除之前的 SpecOps Codex skills 以避免旧版命令 skills 残留。
+  const existing = fs.readdirSync(skillsDir, { withFileTypes: true });
+  for (const entry of existing) {
+    if (entry.isDirectory() && entry.name.startsWith(`${prefix}-`)) {
+      fs.rmSync(path.join(skillsDir, entry.name), { recursive: true });
+    }
+  }
+
+  function recurse(currentSrcDir, currentPrefix) {
+    const entries = fs.readdirSync(currentSrcDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const srcPath = path.join(currentSrcDir, entry.name);
+      if (entry.isDirectory()) {
+        recurse(srcPath, `${currentPrefix}-${entry.name}`);
+        continue;
+      }
+
+      if (!entry.name.endsWith('.md')) {
+        continue;
+      }
+
+      const baseName = entry.name.replace('.md', '');
+      const skillName = `${currentPrefix}-${baseName}`;
+      const skillDir = path.join(skillsDir, skillName);
+      fs.mkdirSync(skillDir, { recursive: true });
+
+      let content = fs.readFileSync(srcPath, 'utf8');
+      const globalClaudeRegex = /~\/\.claude\//g;
+      const localClaudeRegex = /\.\/\.claude\//g;
+      const codexDirRegex = /~\/\.codex\//g;
+      content = content.replace(globalClaudeRegex, pathPrefix);
+      content = content.replace(localClaudeRegex, `./${getDirName(runtime)}/`);
+      content = content.replace(codexDirRegex, pathPrefix);
+      content = processAttribution(content, getCommitAttribution(runtime));
+      content = convertClaudeCommandToCodexSkill(content, skillName);
+
+      fs.writeFileSync(path.join(skillDir, 'SKILL.md'), content);
+    }
+  }
+
+  recurse(srcDir, prefix);
+}
+
+/**
+ * 递归复制目录, 替换 .md 文件中的路径
+ * 先删除现有 destDir 以移除旧版本的孤立文件
+ * @param {string} srcDir - 源目录
+ * @param {string} destDir - 目标目录
+ * @param {string} pathPrefix - 文件引用的路径前缀
+ * @param {string} runtime - 目标运行时 ('claude', 'opencode', 'gemini', 'codex')
+ */
+function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand = false) {
+  const isOpencode = runtime === 'opencode';
+  const isCodex = runtime === 'codex';
+  const dirName = getDirName(runtime);
+
+  // 干净安装: 移除现有目标以防止孤立文件
+  if (fs.existsSync(destDir)) {
+    fs.rmSync(destDir, { recursive: true });
+  }
+  fs.mkdirSync(destDir, { recursive: true });
+
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copyWithPathReplacement(srcPath, destPath, pathPrefix, runtime, isCommand);
+    } else if (entry.name.endsWith('.md')) {
+      // 将 ~/.claude/ 和 ./.claude/ 替换为运行时适当的路径
+      let content = fs.readFileSync(srcPath, 'utf8');
+      const globalClaudeRegex = /~\/\.claude\//g;
+      const localClaudeRegex = /\.\/\.claude\//g;
+      content = content.replace(globalClaudeRegex, pathPrefix);
+      content = content.replace(localClaudeRegex, `./${dirName}/`);
+      content = processAttribution(content, getCommitAttribution(runtime));
+
+      // 为 opencode 兼容性转换前置元数据
+      if (isOpencode) {
+        content = convertClaudeToOpencodeFrontmatter(content);
+        fs.writeFileSync(destPath, content);
+      } else if (runtime === 'gemini') {
+        if (isCommand) {
+          // 为 Gemini 转换为 TOML (去除 <sub> 标签, 终端无法渲染下标)
+          content = stripSubTags(content);
+          const tomlContent = convertClaudeToGeminiToml(content);
+          // 将扩展名替换为 .toml
+          const tomlPath = destPath.replace(/\.md$/, '.toml');
+          fs.writeFileSync(tomlPath, tomlContent);
+        } else {
+          fs.writeFileSync(destPath, content);
+        }
+      } else if (isCodex) {
+        content = convertClaudeToCodexMarkdown(content);
+        fs.writeFileSync(destPath, content);
+      } else {
+        fs.writeFileSync(destPath, content);
+      }
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * 清理旧版本的孤立文件
+ */
+function cleanupOrphanedFiles(configDir) {
+  const orphanedFiles = [
+    'hooks/specops-notify.sh',  // 在 v1.6.x 中移除
+    'hooks/statusline.js',  // 在 v1.9.0 中重命名为 specops-statusline.js
+  ];
+
+  for (const relPath of orphanedFiles) {
+    const fullPath = path.join(configDir, relPath);
+    if (fs.existsSync(fullPath)) {
+      fs.unlinkSync(fullPath);
+      console.log(`  ${green}✓${reset} 已移除孤立文件 ${relPath}`);
+    }
+  }
+}
+
+/**
+ * 清理 settings.json 中的孤立钩子注册
+ */
+function cleanupOrphanedHooks(settings) {
+  const orphanedHookPatterns = [
+    'specops-notify.sh',  // 在 v1.6.x 中移除
+    'hooks/statusline.js',  // 在 v1.9.0 中重命名为 specops-statusline.js
+    'specops-intel-index.js',  // 在 v1.9.2 中移除
+    'specops-intel-session.js',  // 在 v1.9.2 中移除
+    'specops-intel-prune.js',  // 在 v1.9.2 中移除
+  ];
+
+  let cleanedHooks = false;
+
+  // 检查所有钩子事件类型 (Stop, SessionStart 等)
+  if (settings.hooks) {
+    for (const eventType of Object.keys(settings.hooks)) {
+      const hookEntries = settings.hooks[eventType];
+      if (Array.isArray(hookEntries)) {
+        // 过滤掉包含孤立钩子的条目
+        const filtered = hookEntries.filter(entry => {
+          if (entry.hooks && Array.isArray(entry.hooks)) {
+            // 检查此条目中是否有钩子匹配孤立模式
+            const hasOrphaned = entry.hooks.some(h =>
+              h.command && orphanedHookPatterns.some(pattern => h.command.includes(pattern))
+            );
+            if (hasOrphaned) {
+              cleanedHooks = true;
+              return false;  // 移除此条目
+            }
+          }
+          return true;  // 保留此条目
+        });
+        settings.hooks[eventType] = filtered;
+      }
+    }
+  }
+
+  if (cleanedHooks) {
+    console.log(`  ${green}✓${reset} 已移除孤立钩子注册`);
+  }
+
+  // 修复 #330: 如果 statusLine 指向旧的 statusline.js 路径则更新
+  if (settings.statusLine && settings.statusLine.command &&
+      settings.statusLine.command.includes('statusline.js') &&
+      !settings.statusLine.command.includes('specops-statusline.js')) {
+    // 将旧路径替换为新路径
+    settings.statusLine.command = settings.statusLine.command.replace(
+      /statusline\.js/,
+      'specops-statusline.js'
+    );
+    console.log(`  ${green}✓${reset} 已更新状态栏路径 (statusline.js → specops-statusline.js)`);
+  }
+
+  return settings;
+}
+
+/**
+ * 从指定目录为特定运行时卸载 SpecOps
+ * 仅移除 SpecOps 特定的文件/目录, 保留用户内容
+ * @param {boolean} isGlobal - 是否从全局或本地卸载
+ * @param {string} runtime - 目标运行时 ('claude', 'opencode', 'gemini', 'codex')
+ */
+function uninstall(isGlobal, runtime = 'claude') {
+  const isOpencode = runtime === 'opencode';
+  const isCodex = runtime === 'codex';
+  const dirName = getDirName(runtime);
+
+  // 根据运行时和安装类型获取目标目录
+  const targetDir = isGlobal
+    ? getGlobalDir(runtime, explicitConfigDir)
+    : path.join(process.cwd(), dirName);
+
+  const locationLabel = isGlobal
+    ? targetDir.replace(os.homedir(), '~')
+    : targetDir.replace(process.cwd(), '.');
+
+  let runtimeLabel = 'Claude Code';
+  if (runtime === 'opencode') runtimeLabel = 'OpenCode';
+  if (runtime === 'gemini') runtimeLabel = 'Gemini';
+  if (runtime === 'codex') runtimeLabel = 'Codex';
+
+  console.log(`  正在从 ${cyan}${runtimeLabel}${reset} 卸载 SpecOps, 位置 ${cyan}${locationLabel}${reset}\n`);
+
+  // 检查目标目录是否存在
+  if (!fs.existsSync(targetDir)) {
+    console.log(`  ${yellow}⚠${reset} 目录不存在: ${locationLabel}`);
+    console.log(`  没有需要卸载的内容。\n`);
+    return;
+  }
+
+  let removedCount = 0;
+
+  // 1. 移除 SpecOps 命令/skills
+  if (isOpencode) {
+    // OpenCode: 移除 command/specops-*.md 文件
+    const commandDir = path.join(targetDir, 'command');
+    if (fs.existsSync(commandDir)) {
+      const files = fs.readdirSync(commandDir);
+      for (const file of files) {
+        if (file.startsWith('specops-') && file.endsWith('.md')) {
+          fs.unlinkSync(path.join(commandDir, file));
+          removedCount++;
+        }
+      }
+      console.log(`  ${green}✓${reset} 已从 command/ 移除 SpecOps 命令`);
+    }
+  } else if (isCodex) {
+    // Codex: 移除 skills/specops-*/SKILL.md skill 目录
+    const skillsDir = path.join(targetDir, 'skills');
+    if (fs.existsSync(skillsDir)) {
+      let skillCount = 0;
+      const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory() && entry.name.startsWith('specops-')) {
+          fs.rmSync(path.join(skillsDir, entry.name), { recursive: true });
+          skillCount++;
+        }
+      }
+      if (skillCount > 0) {
+        removedCount++;
+        console.log(`  ${green}✓${reset} 已移除 ${skillCount} 个 Codex skills`);
+      }
+    }
+  } else {
+    // Claude Code & Gemini: 移除 commands/specops/ 目录
+    const specopsCommandsDir = path.join(targetDir, 'commands', 'specops');
+    if (fs.existsSync(specopsCommandsDir)) {
+      fs.rmSync(specopsCommandsDir, { recursive: true });
+      removedCount++;
+      console.log(`  ${green}✓${reset} 已移除 commands/specops/`);
+    }
+  }
+
+  // 2. 移除 get-shit-done 目录
+  const gsdDir = path.join(targetDir, 'get-shit-done');
+  if (fs.existsSync(gsdDir)) {
+    fs.rmSync(gsdDir, { recursive: true });
+    removedCount++;
+    console.log(`  ${green}✓${reset} 已移除 get-shit-done/`);
+  }
+
+  // 3. 移除 SpecOps agents (仅 specops-*.md 文件)
+  const agentsDir = path.join(targetDir, 'agents');
+  if (fs.existsSync(agentsDir)) {
+    const files = fs.readdirSync(agentsDir);
+    let agentCount = 0;
+    for (const file of files) {
+      if (file.startsWith('specops-') && file.endsWith('.md')) {
+        fs.unlinkSync(path.join(agentsDir, file));
+        agentCount++;
+      }
+    }
+    if (agentCount > 0) {
+      removedCount++;
+      console.log(`  ${green}✓${reset} 已移除 ${agentCount} 个 SpecOps agents`);
+    }
+  }
+
+  // 4. 移除 SpecOps 钩子
+  const hooksDir = path.join(targetDir, 'hooks');
+  if (fs.existsSync(hooksDir)) {
+    const gsdHooks = ['specops-statusline.js', 'specops-check-update.js', 'specops-check-update.sh', 'specops-context-monitor.js'];
+    let hookCount = 0;
+    for (const hook of gsdHooks) {
+      const hookPath = path.join(hooksDir, hook);
+      if (fs.existsSync(hookPath)) {
+        fs.unlinkSync(hookPath);
+        hookCount++;
+      }
+    }
+    if (hookCount > 0) {
+      removedCount++;
+      console.log(`  ${green}✓${reset} 已移除 ${hookCount} 个 SpecOps 钩子`);
+    }
+  }
+
+  // 5. 移除 SpecOps package.json (CommonJS 模式标记)
+  const pkgJsonPath = path.join(targetDir, 'package.json');
+  if (fs.existsSync(pkgJsonPath)) {
+    try {
+      const content = fs.readFileSync(pkgJsonPath, 'utf8').trim();
+      // 仅在是我们的最小 CommonJS 标记时移除
+      if (content === '{"type":"commonjs"}') {
+        fs.unlinkSync(pkgJsonPath);
+        removedCount++;
+        console.log(`  ${green}✓${reset} 已移除 SpecOps package.json`);
+      }
+    } catch (e) {
+      // 忽略读取错误
+    }
+  }
+
+  // 6. 清理 settings.json (移除 SpecOps 钩子和状态栏)
+  const settingsPath = path.join(targetDir, 'settings.json');
+  if (fs.existsSync(settingsPath)) {
+    let settings = readSettings(settingsPath);
+    let settingsModified = false;
+
+    // 如果引用了我们的钩子则移除 SpecOps 状态栏
+    if (settings.statusLine && settings.statusLine.command &&
+        settings.statusLine.command.includes('specops-statusline')) {
+      delete settings.statusLine;
+      settingsModified = true;
+      console.log(`  ${green}✓${reset} 已从设置中移除 SpecOps 状态栏`);
+    }
+
+    // 从 SessionStart 移除 SpecOps 钩子
+    if (settings.hooks && settings.hooks.SessionStart) {
+      const before = settings.hooks.SessionStart.length;
+      settings.hooks.SessionStart = settings.hooks.SessionStart.filter(entry => {
+        if (entry.hooks && Array.isArray(entry.hooks)) {
+          // 过滤掉 SpecOps 钩子
+          const hasGsdHook = entry.hooks.some(h =>
+            h.command && (h.command.includes('specops-check-update') || h.command.includes('specops-statusline'))
+          );
+          return !hasGsdHook;
+        }
+        return true;
+      });
+      if (settings.hooks.SessionStart.length < before) {
+        settingsModified = true;
+        console.log(`  ${green}✓${reset} 已从设置中移除 SpecOps 钩子`);
+      }
+      // 清理空数组
+      if (settings.hooks.SessionStart.length === 0) {
+        delete settings.hooks.SessionStart;
+      }
+    }
+
+    // 从 PostToolUse 移除 SpecOps 钩子
+    if (settings.hooks && settings.hooks.PostToolUse) {
+      const before = settings.hooks.PostToolUse.length;
+      settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(entry => {
+        if (entry.hooks && Array.isArray(entry.hooks)) {
+          const hasGsdHook = entry.hooks.some(h =>
+            h.command && h.command.includes('specops-context-monitor')
+          );
+          return !hasGsdHook;
+        }
+        return true;
+      });
+      if (settings.hooks.PostToolUse.length < before) {
+        settingsModified = true;
+        console.log(`  ${green}✓${reset} 已从设置中移除上下文监控器钩子`);
+      }
+      if (settings.hooks.PostToolUse.length === 0) {
+        delete settings.hooks.PostToolUse;
+      }
+    }
+
+    // 清理空的 hooks 对象
+    if (settings.hooks && Object.keys(settings.hooks).length === 0) {
+      delete settings.hooks;
+    }
+
+    if (settingsModified) {
+      writeSettings(settingsPath, settings);
+      removedCount++;
+    }
+  }
+
+  // 6. 对于 OpenCode, 清理 opencode.json 中的权限
+  if (isOpencode) {
+    // 本地卸载清理 ./.opencode/opencode.json
+    // 全局卸载清理 ~/.config/opencode/opencode.json
+    const opencodeConfigDir = isGlobal
+      ? getOpencodeGlobalDir()
+      : path.join(process.cwd(), '.opencode');
+    const configPath = path.join(opencodeConfigDir, 'opencode.json');
+    if (fs.existsSync(configPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        let modified = false;
+
+        // 移除 SpecOps 权限条目
+        if (config.permission) {
+          for (const permType of ['read', 'external_directory']) {
+            if (config.permission[permType]) {
+              const keys = Object.keys(config.permission[permType]);
+              for (const key of keys) {
+                if (key.includes('get-shit-done')) {
+                  delete config.permission[permType][key];
+                  modified = true;
+                }
+              }
+              // 清理空对象
+              if (Object.keys(config.permission[permType]).length === 0) {
+                delete config.permission[permType];
+              }
+            }
+          }
+          if (Object.keys(config.permission).length === 0) {
+            delete config.permission;
+          }
+        }
+
+        if (modified) {
+          fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+          removedCount++;
+          console.log(`  ${green}✓${reset} 已从 opencode.json 移除 SpecOps 权限`);
+        }
+      } catch (e) {
+        // 忽略 JSON 解析错误
+      }
+    }
+  }
+
+  if (removedCount === 0) {
+    console.log(`  ${yellow}⚠${reset} 未找到需要移除的 SpecOps 文件。`);
+  }
+
+  console.log(`
+  ${green}完成!${reset} SpecOps 已从 ${runtimeLabel} 卸载。
+  你的其他文件和设置已保留。
+`);
+}
+
+/**
+ * 解析 JSONC (带注释的 JSON), 去除注释和尾随逗号。
+ * OpenCode 通过 jsonc-parser 支持 JSONC 格式, 所以用户可能有注释。
+ * 这是一个轻量级内联解析器, 避免添加依赖。
+ */
+function parseJsonc(content) {
+  // 如果存在则去除 BOM
+  if (content.charCodeAt(0) === 0xFEFF) {
+    content = content.slice(1);
+  }
+
+  // 移除单行和块注释, 同时保留字符串
+  let result = '';
+  let inString = false;
+  let i = 0;
+  while (i < content.length) {
+    const char = content[i];
+    const next = content[i + 1];
+
+    if (inString) {
+      result += char;
+      // 处理转义序列
+      if (char === '\\' && i + 1 < content.length) {
+        result += next;
+        i += 2;
+        continue;
+      }
+      if (char === '"') {
+        inString = false;
+      }
+      i++;
+    } else {
+      if (char === '"') {
+        inString = true;
+        result += char;
+        i++;
+      } else if (char === '/' && next === '/') {
+        // 跳过单行注释直到行尾
+        while (i < content.length && content[i] !== '\n') {
+          i++;
+        }
+      } else if (char === '/' && next === '*') {
+        // 跳过块注释
+        i += 2;
+        while (i < content.length - 1 && !(content[i] === '*' && content[i + 1] === '/')) {
+          i++;
+        }
+        i += 2; // 跳过结束的 */
+      } else {
+        result += char;
+        i++;
+      }
+    }
+  }
+
+  // 移除 } 或 ] 前的尾随逗号
+  result = result.replace(/,(\s*[}\]])/g, '$1');
+
+  return JSON.parse(result);
+}
+
+/**
+ * 配置 OpenCode 权限以允许读取 SpecOps 参考文档
+ * 这防止 SpecOps 访问 get-shit-done 目录时出现权限提示
+ * @param {boolean} isGlobal - 是否为全局或本地安装
+ */
+function configureOpencodePermissions(isGlobal = true) {
+  // 本地安装使用 ./.opencode/opencode.json
+  // 全局安装使用 ~/.config/opencode/opencode.json
+  const opencodeConfigDir = isGlobal
+    ? getOpencodeGlobalDir()
+    : path.join(process.cwd(), '.opencode');
+  const configPath = path.join(opencodeConfigDir, 'opencode.json');
+
+  // 确保配置目录存在
+  fs.mkdirSync(opencodeConfigDir, { recursive: true });
+
+  // 读取现有配置或创建空对象
+  let config = {};
+  if (fs.existsSync(configPath)) {
+    try {
+      const content = fs.readFileSync(configPath, 'utf8');
+      config = parseJsonc(content);
+    } catch (e) {
+      // 无法解析 - 不要覆盖用户的配置
+      console.log(`  ${yellow}⚠${reset} 无法解析 opencode.json - 跳过权限配置`);
+      console.log(`    ${dim}原因: ${e.message}${reset}`);
+      console.log(`    ${dim}你的配置未被修改。如需要请手动修复语法。${reset}`);
+      return;
+    }
+  }
+
+  // 确保权限结构存在
+  if (!config.permission) {
+    config.permission = {};
+  }
+
+  // 使用实际配置目录构建 SpecOps 路径
+  // 如果在默认位置则使用 ~ 简写, 否则使用完整路径
+  const defaultConfigDir = path.join(os.homedir(), '.config', 'opencode');
+  const gsdPath = opencodeConfigDir === defaultConfigDir
+    ? '~/.config/opencode/get-shit-done/*'
+    : `${opencodeConfigDir.replace(/\\/g, '/')}/get-shit-done/*`;
+  
+  let modified = false;
+
+  // 配置读取权限
+  if (!config.permission.read || typeof config.permission.read !== 'object') {
+    config.permission.read = {};
+  }
+  if (config.permission.read[gsdPath] !== 'allow') {
+    config.permission.read[gsdPath] = 'allow';
+    modified = true;
+  }
+
+  // 配置外部目录权限 (项目外路径的安全守卫)
+  if (!config.permission.external_directory || typeof config.permission.external_directory !== 'object') {
+    config.permission.external_directory = {};
+  }
+  if (config.permission.external_directory[gsdPath] !== 'allow') {
+    config.permission.external_directory[gsdPath] = 'allow';
+    modified = true;
+  }
+
+  if (!modified) {
+    return; // 已配置
+  }
+
+  // 写回配置
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  console.log(`  ${green}✓${reset} 已配置 SpecOps 文档的读取权限`);
+}
+
+/**
+ * 验证目录存在且包含文件
+ */
+function verifyInstalled(dirPath, description) {
+  if (!fs.existsSync(dirPath)) {
+    console.error(`  ${yellow}✗${reset} 安装 ${description} 失败: 目录未创建`);
+    return false;
+  }
+  try {
+    const entries = fs.readdirSync(dirPath);
+    if (entries.length === 0) {
+      console.error(`  ${yellow}✗${reset} 安装 ${description} 失败: 目录为空`);
+      return false;
+    }
+  } catch (e) {
+    console.error(`  ${yellow}✗${reset} 安装 ${description} 失败: ${e.message}`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * 验证文件存在
+ */
+function verifyFileInstalled(filePath, description) {
+  if (!fs.existsSync(filePath)) {
+    console.error(`  ${yellow}✗${reset} 安装 ${description} 失败: 文件未创建`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * 安装到指定目录的特定运行时
+ * @param {boolean} isGlobal - 是否全局安装或本地安装
+ * @param {string} runtime - 目标运行时 ('claude', 'opencode', 'gemini', 'codex')
+ */
+
+// ──────────────────────────────────────────────────────
+// 本地补丁持久化
+// ──────────────────────────────────────────────────────
+
+const PATCHES_DIR_NAME = 'specops-local-patches';
+const MANIFEST_NAME = 'specops-file-manifest.json';
+
+/**
+ * 计算文件内容的 SHA256 哈希
+ */
+function fileHash(filePath) {
+  const content = fs.readFileSync(filePath);
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * 递归收集目录中所有文件及其哈希
+ */
+function generateManifest(dir, baseDir) {
+  if (!baseDir) baseDir = dir;
+  const manifest = {};
+  if (!fs.existsSync(dir)) return manifest;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    const relPath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
+    if (entry.isDirectory()) {
+      Object.assign(manifest, generateManifest(fullPath, baseDir));
+    } else {
+      manifest[relPath] = fileHash(fullPath);
+    }
+  }
+  return manifest;
+}
+
+/**
+ * 安装后写入文件清单, 用于未来的修改检测
+ */
+function writeManifest(configDir, runtime = 'claude') {
+  const isOpencode = runtime === 'opencode';
+  const isCodex = runtime === 'codex';
+  const gsdDir = path.join(configDir, 'get-shit-done');
+  const commandsDir = path.join(configDir, 'commands', 'specops');
+  const opencodeCommandDir = path.join(configDir, 'command');
+  const codexSkillsDir = path.join(configDir, 'skills');
+  const agentsDir = path.join(configDir, 'agents');
+  const manifest = { version: pkg.version, timestamp: new Date().toISOString(), files: {} };
+
+  const gsdHashes = generateManifest(gsdDir);
+  for (const [rel, hash] of Object.entries(gsdHashes)) {
+    manifest.files['get-shit-done/' + rel] = hash;
+  }
+  if (!isOpencode && !isCodex && fs.existsSync(commandsDir)) {
+    const cmdHashes = generateManifest(commandsDir);
+    for (const [rel, hash] of Object.entries(cmdHashes)) {
+      manifest.files['commands/specops/' + rel] = hash;
+    }
+  }
+  if (isOpencode && fs.existsSync(opencodeCommandDir)) {
+    for (const file of fs.readdirSync(opencodeCommandDir)) {
+      if (file.startsWith('specops-') && file.endsWith('.md')) {
+        manifest.files['command/' + file] = fileHash(path.join(opencodeCommandDir, file));
+      }
+    }
+  }
+  if (isCodex && fs.existsSync(codexSkillsDir)) {
+    for (const skillName of listCodexSkillNames(codexSkillsDir)) {
+      const skillRoot = path.join(codexSkillsDir, skillName);
+      const skillHashes = generateManifest(skillRoot);
+      for (const [rel, hash] of Object.entries(skillHashes)) {
+        manifest.files[`skills/${skillName}/${rel}`] = hash;
+      }
+    }
+  }
+  if (fs.existsSync(agentsDir)) {
+    for (const file of fs.readdirSync(agentsDir)) {
+      if (file.startsWith('specops-') && file.endsWith('.md')) {
+        manifest.files['agents/' + file] = fileHash(path.join(agentsDir, file));
+      }
+    }
+  }
+
+  fs.writeFileSync(path.join(configDir, MANIFEST_NAME), JSON.stringify(manifest, null, 2));
+  return manifest;
+}
+
+/**
+ * 通过与安装清单比较来检测用户修改的 SpecOps 文件。
+ * 将修改的文件备份到 specops-local-patches/ 以便更新后重新应用。
+ */
+function saveLocalPatches(configDir) {
+  const manifestPath = path.join(configDir, MANIFEST_NAME);
+  if (!fs.existsSync(manifestPath)) return [];
+
+  let manifest;
+  try { manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); } catch { return []; }
+
+  const patchesDir = path.join(configDir, PATCHES_DIR_NAME);
+  const modified = [];
+
+  for (const [relPath, originalHash] of Object.entries(manifest.files || {})) {
+    const fullPath = path.join(configDir, relPath);
+    if (!fs.existsSync(fullPath)) continue;
+    const currentHash = fileHash(fullPath);
+    if (currentHash !== originalHash) {
+      const backupPath = path.join(patchesDir, relPath);
+      fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+      fs.copyFileSync(fullPath, backupPath);
+      modified.push(relPath);
+    }
+  }
+
+  if (modified.length > 0) {
+    const meta = {
+      backed_up_at: new Date().toISOString(),
+      from_version: manifest.version,
+      files: modified
+    };
+    fs.writeFileSync(path.join(patchesDir, 'backup-meta.json'), JSON.stringify(meta, null, 2));
+    console.log('  ' + yellow + 'i' + reset + '  发现 ' + modified.length + ' 个本地修改的 SpecOps 文件, 已备份到 ' + PATCHES_DIR_NAME + '/');
+    for (const f of modified) {
+      console.log('     ' + dim + f + reset);
+    }
+  }
+  return modified;
+}
+
+/**
+ * 安装后报告已备份的补丁, 供用户重新应用。
+ */
+function reportLocalPatches(configDir, runtime = 'claude') {
+  const patchesDir = path.join(configDir, PATCHES_DIR_NAME);
+  const metaPath = path.join(patchesDir, 'backup-meta.json');
+  if (!fs.existsSync(metaPath)) return [];
+
+  let meta;
+  try { meta = JSON.parse(fs.readFileSync(metaPath, 'utf8')); } catch { return []; }
+
+  if (meta.files && meta.files.length > 0) {
+    const reapplyCommand = runtime === 'opencode'
+      ? '/specops-reapply-patches'
+      : runtime === 'codex'
+        ? '$specops-reapply-patches'
+        : '/specops:reapply-patches';
+    console.log('');
+    console.log('  ' + yellow + '检测到本地补丁' + reset + ' (来自 v' + meta.from_version + '):');
+    for (const f of meta.files) {
+      console.log('     ' + cyan + f + reset);
+    }
+    console.log('');
+    console.log('  你的修改已保存在 ' + cyan + PATCHES_DIR_NAME + '/' + reset);
+    console.log('  运行 ' + cyan + reapplyCommand + reset + ' 将它们合并到新版本。');
+    console.log('  或手动比较并合并文件。');
+    console.log('');
+  }
+  return meta.files || [];
+}
+
+function install(isGlobal, runtime = 'claude') {
+  const isOpencode = runtime === 'opencode';
+  const isGemini = runtime === 'gemini';
+  const isCodex = runtime === 'codex';
+  const dirName = getDirName(runtime);
+  const src = path.join(__dirname, '..');
+
+  // 根据运行时和安装类型获取目标目录
+  const targetDir = isGlobal
+    ? getGlobalDir(runtime, explicitConfigDir)
+    : path.join(process.cwd(), dirName);
+
+  const locationLabel = isGlobal
+    ? targetDir.replace(os.homedir(), '~')
+    : targetDir.replace(process.cwd(), '.');
+
+  // markdown 内容中文件引用的路径前缀
+  // 全局安装: 使用完整路径
+  // 本地安装: 使用相对路径
+  const pathPrefix = isGlobal
+    ? `${targetDir.replace(/\\/g, '/')}/`
+    : `./${dirName}/`;
+
+  let runtimeLabel = 'Claude Code';
+  if (isOpencode) runtimeLabel = 'OpenCode';
+  if (isGemini) runtimeLabel = 'Gemini';
+  if (isCodex) runtimeLabel = 'Codex';
+
+  console.log(`  正在为 ${cyan}${runtimeLabel}${reset} 安装到 ${cyan}${locationLabel}${reset}\n`);
+
+  // 跟踪安装失败
+  const failures = [];
+
+  // 在被覆盖前保存任何本地修改的 SpecOps 文件
+  saveLocalPatches(targetDir);
+
+  // 清理旧版本的孤立文件
+  cleanupOrphanedFiles(targetDir);
+
+  // OpenCode 使用 command/ (扁平), Codex 使用 skills/, Claude/Gemini 使用 commands/specops/
+  if (isOpencode) {
+    // OpenCode: command/ 目录中的扁平结构
+    const commandDir = path.join(targetDir, 'command');
+    fs.mkdirSync(commandDir, { recursive: true });
+    
+    // 将 commands/specops/*.md 复制为 command/specops-*.md (扁平化结构)
+    const specopsSrc = path.join(src, 'commands', 'specops');
+    copyFlattenedCommands(specopsSrc, commandDir, 'specops', pathPrefix, runtime);
+    if (verifyInstalled(commandDir, 'command/specops-*')) {
+      const count = fs.readdirSync(commandDir).filter(f => f.startsWith('specops-')).length;
+      console.log(`  ${green}✓${reset} 已安装 ${count} 个命令到 command/`);
+    } else {
+      failures.push('command/specops-*');
+    }
+  } else if (isCodex) {
+    const skillsDir = path.join(targetDir, 'skills');
+    const specopsSrc = path.join(src, 'commands', 'specops');
+    copyCommandsAsCodexSkills(specopsSrc, skillsDir, 'specops', pathPrefix, runtime);
+    const installedSkillNames = listCodexSkillNames(skillsDir);
+    if (installedSkillNames.length > 0) {
+      console.log(`  ${green}✓${reset} 已安装 ${installedSkillNames.length} 个 skills 到 skills/`);
+    } else {
+      failures.push('skills/specops-*');
+    }
+  } else {
+    // Claude Code & Gemini: commands/ 目录中的嵌套结构
+    const commandsDir = path.join(targetDir, 'commands');
+    fs.mkdirSync(commandsDir, { recursive: true });
+    
+    const specopsSrc = path.join(src, 'commands', 'specops');
+    const specopsDest = path.join(commandsDir, 'specops');
+    copyWithPathReplacement(specopsSrc, specopsDest, pathPrefix, runtime, true);
+    if (verifyInstalled(specopsDest, 'commands/specops')) {
+      console.log(`  ${green}✓${reset} 已安装 commands/specops`);
+    } else {
+      failures.push('commands/specops');
+    }
+  }
+
+  // 复制 get-shit-done skill 并替换路径
+  const skillSrc = path.join(src, 'get-shit-done');
+  const skillDest = path.join(targetDir, 'get-shit-done');
+  copyWithPathReplacement(skillSrc, skillDest, pathPrefix, runtime);
+  if (verifyInstalled(skillDest, 'get-shit-done')) {
+    console.log(`  ${green}✓${reset} 已安装 get-shit-done`);
+  } else {
+    failures.push('get-shit-done');
+  }
+
+  // 复制 agents 到 agents 目录
+  const agentsSrc = path.join(src, 'agents');
+  if (fs.existsSync(agentsSrc)) {
+    const agentsDest = path.join(targetDir, 'agents');
+    fs.mkdirSync(agentsDest, { recursive: true });
+
+    // 复制新的之前移除旧的 SpecOps agents (specops-*.md)
+    if (fs.existsSync(agentsDest)) {
+      for (const file of fs.readdirSync(agentsDest)) {
+        if (file.startsWith('specops-') && file.endsWith('.md')) {
+          fs.unlinkSync(path.join(agentsDest, file));
+        }
+      }
+    }
+
+    // 复制新 agents
+    const agentEntries = fs.readdirSync(agentsSrc, { withFileTypes: true });
+    for (const entry of agentEntries) {
+      if (entry.isFile() && entry.name.endsWith('.md')) {
+        let content = fs.readFileSync(path.join(agentsSrc, entry.name), 'utf8');
+        // 始终替换 ~/.claude/ 因为它是仓库中的真实来源
+        const dirRegex = /~\/\.claude\//g;
+        content = content.replace(dirRegex, pathPrefix);
+        content = processAttribution(content, getCommitAttribution(runtime));
+        // 为运行时兼容性转换前置元数据
+        if (isOpencode) {
+          content = convertClaudeToOpencodeFrontmatter(content);
+        } else if (isGemini) {
+          content = convertClaudeToGeminiAgent(content);
+        } else if (isCodex) {
+          content = convertClaudeToCodexMarkdown(content);
+        }
+        fs.writeFileSync(path.join(agentsDest, entry.name), content);
+      }
+    }
+    if (verifyInstalled(agentsDest, 'agents')) {
+      console.log(`  ${green}✓${reset} 已安装 agents`);
+    } else {
+      failures.push('agents');
+    }
+  }
+
+  // 复制 CHANGELOG.md
+  const changelogSrc = path.join(src, 'CHANGELOG.md');
+  const changelogDest = path.join(targetDir, 'get-shit-done', 'CHANGELOG.md');
+  if (fs.existsSync(changelogSrc)) {
+    fs.copyFileSync(changelogSrc, changelogDest);
+    if (verifyFileInstalled(changelogDest, 'CHANGELOG.md')) {
+      console.log(`  ${green}✓${reset} 已安装 CHANGELOG.md`);
+    } else {
+      failures.push('CHANGELOG.md');
+    }
+  }
+
+  // 写入 VERSION 文件
+  const versionDest = path.join(targetDir, 'get-shit-done', 'VERSION');
+  fs.writeFileSync(versionDest, pkg.version);
+  if (verifyFileInstalled(versionDest, 'VERSION')) {
+    console.log(`  ${green}✓${reset} 已写入 VERSION (${pkg.version})`);
+  } else {
+    failures.push('VERSION');
+  }
+
+  if (!isCodex) {
+    // 写入 package.json 以强制 CommonJS 模式用于 SpecOps 脚本
+    // 防止项目有 "type": "module" 时出现 "require is not defined" 错误
+    // Node.js 向上查找 package.json, 这阻止了从项目继承
+    const pkgJsonDest = path.join(targetDir, 'package.json');
+    fs.writeFileSync(pkgJsonDest, '{"type":"commonjs"}\n');
+    console.log(`  ${green}✓${reset} 已写入 package.json (CommonJS 模式)`);
+
+    // 从 dist/ 复制钩子 (与依赖一起打包)
+    // 为目标运行时模板化路径 (将 '.claude' 替换为正确的配置目录)
+    const hooksSrc = path.join(src, 'hooks', 'dist');
+    if (fs.existsSync(hooksSrc)) {
+      const hooksDest = path.join(targetDir, 'hooks');
+      fs.mkdirSync(hooksDest, { recursive: true });
+      const hookEntries = fs.readdirSync(hooksSrc);
+      const configDirReplacement = getConfigDirFromHome(runtime, isGlobal);
+      for (const entry of hookEntries) {
+        const srcFile = path.join(hooksSrc, entry);
+        if (fs.statSync(srcFile).isFile()) {
+          const destFile = path.join(hooksDest, entry);
+          // 模板化 .js 文件, 将 '.claude' 替换为运行时特定的配置目录
+          if (entry.endsWith('.js')) {
+            let content = fs.readFileSync(srcFile, 'utf8');
+            content = content.replace(/'\.claude'/g, configDirReplacement);
+            fs.writeFileSync(destFile, content);
+          } else {
+            fs.copyFileSync(srcFile, destFile);
+          }
+        }
+      }
+      if (verifyInstalled(hooksDest, 'hooks')) {
+        console.log(`  ${green}✓${reset} 已安装钩子 (已打包)`);
+      } else {
+        failures.push('hooks');
+      }
+    }
+  }
+
+  if (failures.length > 0) {
+    console.error(`\n  ${yellow}安装不完整!${reset} 失败: ${failures.join(', ')}`);
+    process.exit(1);
+  }
+
+  // 写入文件清单用于未来的修改检测
+  writeManifest(targetDir, runtime);
+  console.log(`  ${green}✓${reset} 已写入文件清单 (${MANIFEST_NAME})`);
+
+  // 报告任何已备份的本地补丁
+  reportLocalPatches(targetDir, runtime);
+
+  if (isCodex) {
+    return { settingsPath: null, settings: null, statuslineCommand: null, runtime };
+  }
+
+  // 在 settings.json 中配置状态栏和钩子
+  // Gemini 目前与 Claude Code 共享相同的钩子系统
+  const settingsPath = path.join(targetDir, 'settings.json');
+  const settings = cleanupOrphanedHooks(readSettings(settingsPath));
+  const statuslineCommand = isGlobal
+    ? buildHookCommand(targetDir, 'specops-statusline.js')
+    : 'node ' + dirName + '/hooks/specops-statusline.js';
+  const updateCheckCommand = isGlobal
+    ? buildHookCommand(targetDir, 'specops-check-update.js')
+    : 'node ' + dirName + '/hooks/specops-check-update.js';
+  const contextMonitorCommand = isGlobal
+    ? buildHookCommand(targetDir, 'specops-context-monitor.js')
+    : 'node ' + dirName + '/hooks/specops-context-monitor.js';
+
+  // 为 Gemini CLI 启用实验性 agents (自定义子 Agent 所需)
+  if (isGemini) {
+    if (!settings.experimental) {
+      settings.experimental = {};
+    }
+    if (!settings.experimental.enableAgents) {
+      settings.experimental.enableAgents = true;
+      console.log(`  ${green}✓${reset} 已启用实验性 agents`);
+    }
+  }
+
+  // 配置 SessionStart 钩子用于更新检查 (opencode 跳过)
+  if (!isOpencode) {
+    if (!settings.hooks) {
+      settings.hooks = {};
+    }
+    if (!settings.hooks.SessionStart) {
+      settings.hooks.SessionStart = [];
+    }
+
+    const hasGsdUpdateHook = settings.hooks.SessionStart.some(entry =>
+      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('specops-check-update'))
+    );
+
+    if (!hasGsdUpdateHook) {
+      settings.hooks.SessionStart.push({
+        hooks: [
+          {
+            type: 'command',
+            command: updateCheckCommand
+          }
+        ]
+      });
+      console.log(`  ${green}✓${reset} 已配置更新检查钩子`);
+    }
+
+    // 配置 PostToolUse 钩子用于上下文窗口监控
+    if (!settings.hooks.PostToolUse) {
+      settings.hooks.PostToolUse = [];
+    }
+
+    const hasContextMonitorHook = settings.hooks.PostToolUse.some(entry =>
+      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('specops-context-monitor'))
+    );
+
+    if (!hasContextMonitorHook) {
+      settings.hooks.PostToolUse.push({
+        hooks: [
+          {
+            type: 'command',
+            command: contextMonitorCommand
+          }
+        ]
+      });
+      console.log(`  ${green}✓${reset} 已配置上下文窗口监控钩子`);
+    }
+  }
+
+  return { settingsPath, settings, statuslineCommand, runtime };
+}
+
+/**
+ * 应用状态栏配置, 然后打印完成消息
+ */
+function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallStatusline, runtime = 'claude', isGlobal = true) {
+  const isOpencode = runtime === 'opencode';
+  const isCodex = runtime === 'codex';
+
+  if (shouldInstallStatusline && !isOpencode && !isCodex) {
+    settings.statusLine = {
+      type: 'command',
+      command: statuslineCommand
+    };
+    console.log(`  ${green}✓${reset} 已配置状态栏`);
+  }
+
+  // 运行时支持 settings.json 时写入设置
+  if (!isCodex) {
+    writeSettings(settingsPath, settings);
+  }
+
+  // 配置 OpenCode 权限
+  if (isOpencode) {
+    configureOpencodePermissions(isGlobal);
+  }
+
+  let program = 'Claude Code';
+  if (runtime === 'opencode') program = 'OpenCode';
+  if (runtime === 'gemini') program = 'Gemini';
+  if (runtime === 'codex') program = 'Codex';
+
+  let command = '/specops:help';
+  if (runtime === 'opencode') command = '/specops-help';
+  if (runtime === 'codex') command = '$specops-help';
+  console.log(`
+  ${green}完成!${reset} 启动 ${program} 并运行 ${cyan}${command}${reset}。
+
+  ${cyan}加入社区:${reset} https://discord.gg/5JJgD5svVS
+`);
+}
+
+/**
+ * 处理状态栏配置, 可选提示
+ */
+function handleStatusline(settings, isInteractive, callback) {
+  const hasExisting = settings.statusLine != null;
+
+  if (!hasExisting) {
+    callback(true);
+    return;
+  }
+
+  if (forceStatusline) {
+    callback(true);
+    return;
+  }
+
+  if (!isInteractive) {
+    console.log(`  ${yellow}⚠${reset} 跳过状态栏 (已有配置)`);
+    console.log(`    使用 ${cyan}--force-statusline${reset} 来替换\n`);
+    callback(false);
+    return;
+  }
+
+  const existingCmd = settings.statusLine.command || settings.statusLine.url || '(自定义)';
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  console.log(`
+  ${yellow}⚠${reset} 检测到现有状态栏\n
+  你当前的状态栏:
+    ${dim}command: ${existingCmd}${reset}
+
+  SpecOps 包含一个状态栏, 显示:
+    • 模型名称
+    • 当前任务 (来自 todo 列表)
+    • 上下文窗口使用率 (颜色编码)
+
+  ${cyan}1${reset}) 保留现有
+  ${cyan}2${reset}) 替换为 SpecOps 状态栏
+`);
+
+  rl.question(`  选择 ${dim}[1]${reset}: `, (answer) => {
+    rl.close();
+    const choice = answer.trim() || '1';
+    callback(choice === '2');
+  });
+}
+
+/**
+ * 提示选择运行时
+ */
+function promptRuntime(callback) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  let answered = false;
+
+  rl.on('close', () => {
+    if (!answered) {
+      answered = true;
+      console.log(`\n  ${yellow}安装已取消${reset}\n`);
+      process.exit(0);
+    }
+  });
+
+  console.log(`  ${yellow}你想为哪个运行时安装?${reset}\n\n  ${cyan}1${reset}) Claude Code ${dim}(~/.claude)${reset}
+  ${cyan}2${reset}) OpenCode    ${dim}(~/.config/opencode)${reset} - 开源, 免费模型
+  ${cyan}3${reset}) Gemini      ${dim}(~/.gemini)${reset}
+  ${cyan}4${reset}) Codex       ${dim}(~/.codex)${reset}
+  ${cyan}5${reset}) 全部
+`);
+
+  rl.question(`  选择 ${dim}[1]${reset}: `, (answer) => {
+    answered = true;
+    rl.close();
+    const choice = answer.trim() || '1';
+    if (choice === '5') {
+      callback(['claude', 'opencode', 'gemini', 'codex']);
+    } else if (choice === '4') {
+      callback(['codex']);
+    } else if (choice === '3') {
+      callback(['gemini']);
+    } else if (choice === '2') {
+      callback(['opencode']);
+    } else {
+      callback(['claude']);
+    }
+  });
+}
+
+/**
+ * 提示选择安装位置
+ */
+function promptLocation(runtimes) {
+  if (!process.stdin.isTTY) {
+    console.log(`  ${yellow}检测到非交互式终端, 默认全局安装${reset}\n`);
+    installAllRuntimes(runtimes, true, false);
+    return;
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  let answered = false;
+
+  rl.on('close', () => {
+    if (!answered) {
+      answered = true;
+      console.log(`\n  ${yellow}安装已取消${reset}\n`);
+      process.exit(0);
+    }
+  });
+
+  const pathExamples = runtimes.map(r => {
+    const globalPath = getGlobalDir(r, explicitConfigDir);
+    return globalPath.replace(os.homedir(), '~');
+  }).join(', ');
+
+  const localExamples = runtimes.map(r => `./${getDirName(r)}`).join(', ');
+
+  console.log(`  ${yellow}你想安装到哪里?${reset}\n\n  ${cyan}1${reset}) 全局 ${dim}(${pathExamples})${reset} - 所有项目可用
+  ${cyan}2${reset}) 本地 ${dim}(${localExamples})${reset} - 仅当前项目
+`);
+
+  rl.question(`  选择 ${dim}[1]${reset}: `, (answer) => {
+    answered = true;
+    rl.close();
+    const choice = answer.trim() || '1';
+    const isGlobal = choice !== '2';
+    installAllRuntimes(runtimes, isGlobal, true);
+  });
+}
+
+/**
+ * 为所有选定的运行时安装 SpecOps
+ */
+function installAllRuntimes(runtimes, isGlobal, isInteractive) {
+  const results = [];
+
+  for (const runtime of runtimes) {
+    const result = install(isGlobal, runtime);
+    results.push(result);
+  }
+
+  const statuslineRuntimes = ['claude', 'gemini'];
+  const primaryStatuslineResult = results.find(r => statuslineRuntimes.includes(r.runtime));
+
+  const finalize = (shouldInstallStatusline) => {
+    for (const result of results) {
+      const useStatusline = statuslineRuntimes.includes(result.runtime) && shouldInstallStatusline;
+      finishInstall(
+        result.settingsPath,
+        result.settings,
+        result.statuslineCommand,
+        useStatusline,
+        result.runtime,
+        isGlobal
+      );
+    }
+  };
+
+  if (primaryStatuslineResult) {
+    handleStatusline(primaryStatuslineResult.settings, isInteractive, finalize);
+  } else {
+    finalize(false);
+  }
+}
+
+// 主逻辑
+if (hasGlobal && hasLocal) {
+  console.error(`  ${yellow}不能同时指定 --global 和 --local${reset}`);
+  process.exit(1);
+} else if (explicitConfigDir && hasLocal) {
+  console.error(`  ${yellow}不能将 --config-dir 与 --local 一起使用${reset}`);
+  process.exit(1);
+} else if (hasUninstall) {
+  if (!hasGlobal && !hasLocal) {
+    console.error(`  ${yellow}--uninstall 需要 --global 或 --local${reset}`);
+    process.exit(1);
+  }
+  const runtimes = selectedRuntimes.length > 0 ? selectedRuntimes : ['claude'];
+  for (const runtime of runtimes) {
+    uninstall(hasGlobal, runtime);
+  }
+} else if (selectedRuntimes.length > 0) {
+  if (!hasGlobal && !hasLocal) {
+    promptLocation(selectedRuntimes);
+  } else {
+    installAllRuntimes(selectedRuntimes, hasGlobal, false);
+  }
+} else if (hasGlobal || hasLocal) {
+  // 如果没有指定运行时但指定了位置, 默认 Claude
+  installAllRuntimes(['claude'], hasGlobal, false);
+} else {
+  // 交互式
+  if (!process.stdin.isTTY) {
+    console.log(`  ${yellow}检测到非交互式终端, 默认全局安装 Claude Code${reset}\n`);
+    installAllRuntimes(['claude'], true, false);
+  } else {
+    promptRuntime((runtimes) => {
+      promptLocation(runtimes);
+    });
+  }
+}