adspecs 0.1.28 → 0.1.29

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "adspecs",
       "description": "AI Coding研发协同开发插件",
-      "version": "0.1.28",
+      "version": "0.1.29",
       "source": "./",
       "author": {
         "name": "Qingwen Chen",

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "adspecs",
   "displayName": "adspecs AI Plugin",
   "description": "AI first工程规范驱动开发插件",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "author": {
     "name": "Qingwen Chen",
     "email": "cqinwn@qq.com",

package/.qoder-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "adspecs",
   "displayName": "adspecs AI 工程规范驱动开发插件",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "description": "AI-first specification-driven development plugin for ECP platform full-lifecycle development",
   "descriptionZh": "AI优先的工程规范驱动开发插件，覆盖需求分析、PRD、系统设计、任务拆解、TDD、代码评审、Wiki同步全流程",
   "author": {

package/INSTALL.md

@@ -181,14 +181,41 @@ claude plugins update adspecs --scope project
 
 ---
 
-## 跨平台环境变量
+## 跨平台支持
 
-adspecs hooks 支持通过环境变量控制平台行为：
+### 平台自动检测
+
+adspecs 通过 `hooks/platform.js` 模块自动检测运行环境，无需手动配置：
+
+| 检测方式 | 说明 |
+|----------|------|
+| `ADSPECS_PLATFORM` 环境变量 | 显式指定平台（优先级最高） |
+| `CLAUDE_PLUGIN_ROOT` 环境变量 | Claude Code 自动注入 |
+| `QODER_PLUGIN_ROOT` 环境变量 | Qoder 自动注入 |
+
+### 环境变量
 
 | 环境变量 | 说明 | 可选值 |
 |----------|------|--------|
 | `ADSPECS_PLATFORM` | 显式指定运行平台 | `claude` / `qoder` |
 | `CLAUDE_PLUGIN_ROOT` | Claude Code 注入的插件根路径 | 自动 |
-| `QODER_PLUGIN_ROOT` | Qoder 注入的插件根路径（如适用） | 自动 |
+| `QODER_PLUGIN_ROOT` | Qoder 注入的插件根路径 | 自动 |
 
 通常无需手动设置，平台会自动注入。若 hooks 执行异常，可尝试设置 `ADSPECS_PLATFORM=qoder`。
+
+### Hooks 系统
+
+adspecs 的 hooks 脚本（`hooks/*.js`）已适配双平台，通过统一的 `platform.js` 模块获取：
+
+- 平台类型（`claude` / `qoder`）
+- 状态目录（`.claude/` / `.qoder/`）
+- 工具输出文件路径
+
+hooks 配置位于 `hooks/hooks.json`，支持以下事件：
+
+| 事件 | 说明 |
+|------|------|
+| `SessionStart` | 会话启动时注入上下文 |
+| `PreCompact` | 上下文压缩前保存提醒 |
+| `PostToolUse` | 文件变更后追踪队列 |
+| `Stop` | 会话结束时建议操作 |

package/README.md

@@ -2,20 +2,24 @@
 
 [![npm version](https://img.shields.io/npm/v/adspecs)](https://www.npmjs.com/package/adspecs)
 [![npm downloads](https://img.shields.io/npm/dt/adspecs)](https://www.npmjs.com/package/adspecs)
+[![Platform](https://img.shields.io/badge/platform-Claude%20Code%20%7C%20Qoder-blueviolet)](#安装)
 
 ---
 
 ## 简介
 
-AdSpecs 是一个基于 Claude Code 的 AI 工程研发协同插件，提供：
+AdSpecs 是一个支持 **Claude Code** 和 **Qoder** 双平台的 AI 工程研发协同插件，提供：
 
 - **21 个 Skill**（Slash 命令） — 覆盖需求分析、架构规划、系统设计、任务拆解、单元测试、代码审查、文档导出、Wiki 同步
 - **CLI 工具** — `adspecs init` 一键脚手架、`adspecs plugin install` 插件注册、`adspecs doctor` 环境检查
 - **21 个标准文档模板** — 需求 / 设计 / 任务 / 测试 / 评审 / 架构全覆盖
-- **多技术栈参考** — ECP Java 后端、Vue 3 前端、Ant Design React 前端、Python 后端等 11 套参考工程
+- **多技术栈参考** — Java 后端、Vue 3 前端、Ant Design React 前端、Python 后端等 11 套参考工程
+- **双平台支持** — 原生兼容 Claude Code 和 Qoder，自动检测运行环境
 - **npm 分发** — `npm install -g adspecs` 即装即用
 
-本插件需配合 [`superpowers`](https://github.com/anthropics/claude-plugins-official) 插件（提供 TDD、子代理驱动开发等通用 Skill）一起使用。
+> **平台依赖说明**：
+> - **Claude Code**：需配合 [`superpowers`](https://github.com/anthropics/claude-plugins-official) 插件（提供 TDD、子代理驱动开发等通用 Skill）一起使用
+> - **Qoder**：adspecs 的 Skills 可独立运行，无需额外依赖
 
 ---
 
@@ -344,12 +348,25 @@ Skill 支持通过 `.adspecs/paths.json` 自定义输出目录：
 
 详细安装说明见 [INSTALL.md](./INSTALL.md)。
 
+### Claude Code
+
+```bash
+npm install -g adspecs
+adspecs plugin install                    # 用户级（默认）
+adspecs plugin install --scope project    # 项目级
+```
+
+### Qoder
+
 ```bash
-# 安装
 npm install -g adspecs
-adspecs plugin install              # 用户级（默认）
-adspecs plugin install --scope project  # 项目级
+adspecs plugin install --platform qoder              # 用户级
+adspecs plugin install --platform qoder --scope project  # 项目级
+```
+
+### 通用命令
 
+```bash
 # 升级
 npm install -g adspecs@latest
 
@@ -363,15 +380,20 @@ adspecs plugin uninstall --scope project
 ## 常见问题
 
 **Q1：adspecs 与 superpowers 的关系？**
-adspecs 提供领域专属 Skill（需求、设计、模板、规范），superpowers 提供通用 AI 工程 Skill（TDD、子代理、调试）。两者分工协作，**编码阶段必须同时安装**。
+adspecs 提供领域专属 Skill（需求、设计、模板、规范），superpowers 提供通用 AI 工程 Skill（TDD、子代理、调试）。
+- **Claude Code**：两者分工协作，编码阶段必须同时安装
+- **Qoder**：adspecs 可独立运行，无需 superpowers
 
 **Q2：用户级和项目级安装可以共存吗？**
 可以，项目级优先于用户级（就近原则）。个人开发选用户级，团队协作选项目级。
 
-**Q3：安装后 Skill 未生效？**
+**Q3：Claude Code 和 Qoder 可以同时使用吗？**
+可以。adspecs 通过 `.claude-plugin/` 和 `.qoder-plugin/` 分别提供两个平台的插件配置，互不干扰。使用 `--platform` 参数指定目标平台即可。
+
+**Q4：安装后 Skill 未生效？**
 1. 执行 `/plugins` 查看 adspecs 是否在已加载列表
-2. 重启 Claude Code
-3. 检查安装 scope 对应的目录是否存在
+2. 重启 Claude Code 或 Qoder
+3. 检查安装 scope 对应的目录是否存在（`.claude-plugin/` 或 `.qoder-plugin/`）
 
 **Q4：如何升级？**
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adspecs",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "description": "AI first 工程规范驱动开发插件 — 支持 npm 安装和 CLI 初始化",
   "bin": {
     "adspecs": "bin/adspecs.js"

package/src/commands/plugin.js

@@ -3,6 +3,7 @@
 const { execSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
+const os = require('os');
 const chalk = require('chalk');
 
 /**
@@ -91,8 +92,9 @@ exports.install = async function install(options) {
 
 /**
  * Qoder 平台安装
- * Qoder 通过 .qoder-plugin/plugin.json 自动发现插件，
- * 安装即确保插件目录可被 Qoder 访问。
+ * 自动注册到 Qoder 插件系统：
+ * - 用户级：创建 junction 链接 + 写入注册表 + 启用插件
+ * - 项目级：在项目目录创建 .qoder-plugin 链接
  */
 async function installForQoder(pluginName, scope) {
   const qoderManifest = path.join(PLUGIN_DIR, '.qoder-plugin', 'plugin.json');
@@ -101,64 +103,238 @@ async function installForQoder(pluginName, scope) {
   }
 
   if (scope === 'project') {
-    // 项目级：在当前项目创建 .qoder-plugin 符号链接或复制
-    const targetDir = path.join(process.cwd(), '.qoder-plugin');
-    if (fs.existsSync(targetDir)) {
-      console.log(chalk.yellow('   ⏭ 当前项目已存在 .qoder-plugin/，跳过'));
-    } else {
-      try {
-        // 尝试创建符号链接（节省空间）
-        fs.symlinkSync(
-          path.join(PLUGIN_DIR, '.qoder-plugin'),
-          targetDir,
-          'junction' // Windows 使用 junction
-        );
-        console.log(chalk.green('   ✅ 已创建 .qoder-plugin 符号链接'));
-      } catch (_err) {
-        // 符号链接失败，复制清单文件
-        fs.mkdirSync(targetDir, { recursive: true });
-        fs.copyFileSync(qoderManifest, path.join(targetDir, 'plugin.json'));
-        console.log(chalk.green('   ✅ 已复制 .qoder-plugin/plugin.json 到项目'));
-      }
+    await installQoderProject(pluginName, qoderManifest);
+  } else {
+    await installQoderUser(pluginName, qoderManifest);
+  }
+
+  console.log('');
+  console.log(chalk.green.bold(`✅ adspecs 插件已配置到 Qoder (scope=${scope})`));
+  console.log('');
+  printSkillList();
+}
+
+/**
+ * Qoder 用户级安装 — 自动注册到 ~/.qoder/plugins/
+ */
+async function installQoderUser(pluginName, qoderManifest) {
+  const qoderHome = path.join(os.homedir(), '.qoder');
+  const pluginsDir = path.join(qoderHome, 'plugins');
+  const cacheDir = path.join(pluginsDir, 'cache', 'local');
+  const linkPath = path.join(cacheDir, pluginName);
+  const registryKey = `${pluginName}@local`;
+
+  console.log(chalk.gray('   → Qoder 用户级插件自动注册...'));
+  console.log('');
+
+  // 1. 确保目录结构存在
+  fs.mkdirSync(cacheDir, { recursive: true });
+
+  // 2. 创建 junction 链接（已存在则先移除重建，确保指向最新路径）
+  if (fs.existsSync(linkPath)) {
+    try {
+      fs.rmSync(linkPath, { recursive: true, force: true });
+    } catch (_err) {
+      // junction 可能无法用 rmSync 删除，尝试 unlink
+      try { fs.unlinkSync(linkPath); } catch (_e) { /* ignore */ }
     }
+  }
 
-    // 确保 skills 可被访问
-    const targetSkills = path.join(process.cwd(), 'skills');
-    if (!fs.existsSync(targetSkills)) {
-      try {
-        fs.symlinkSync(path.join(PLUGIN_DIR, 'skills'), targetSkills, 'junction');
-        console.log(chalk.green('   ✅ 已创建 skills/ 符号链接'));
-      } catch (_err) {
-        console.log(chalk.yellow('   ⚠ skills/ 链接创建失败，请手动确保 Qoder 可访问插件 skills 目录'));
-      }
+  try {
+    fs.symlinkSync(PLUGIN_DIR, linkPath, 'junction');
+    console.log(chalk.green(`   ✅ 已创建插件链接: ${linkPath}`));
+    console.log(chalk.gray(`      → ${PLUGIN_DIR}`));
+  } catch (err) {
+    // junction 创建失败（权限不足等），回退为复制关键文件
+    console.log(chalk.yellow(`   ⚠ 链接创建失败(${err.message})，回退为文件复制...`));
+    fs.mkdirSync(linkPath, { recursive: true });
+    copyDirRecursive(PLUGIN_DIR, linkPath, [
+      'node_modules', '.git', '.claude', 'assets'
+    ]);
+    console.log(chalk.green(`   ✅ 已复制插件文件到: ${linkPath}`));
+  }
+
+  // 3. 读取插件版本
+  const pluginJson = JSON.parse(fs.readFileSync(qoderManifest, 'utf8'));
+  const version = pluginJson.version || '0.0.0';
+  const now = new Date().toISOString();
+
+  // 4. 写入 installed_plugins_v2.json
+  const v2Path = path.join(pluginsDir, 'installed_plugins_v2.json');
+  let v2Data = { version: 2, plugins: {} };
+  if (fs.existsSync(v2Path)) {
+    try { v2Data = JSON.parse(fs.readFileSync(v2Path, 'utf8')); } catch (_e) { /* use default */ }
+  }
+  if (!v2Data.plugins) v2Data.plugins = {};
+
+  v2Data.plugins[registryKey] = [{
+    scope: 'user',
+    installPath: linkPath,
+    version: version,
+    source: 'local',
+    installedAt: (v2Data.plugins[registryKey] && v2Data.plugins[registryKey][0] && v2Data.plugins[registryKey][0].installedAt) || now,
+    lastUpdated: now,
+    enabled: true
+  }];
+
+  fs.writeFileSync(v2Path, JSON.stringify(v2Data, null, 2) + '\n', 'utf8');
+  console.log(chalk.green('   ✅ 已写入插件注册表 (installed_plugins_v2.json)'));
+
+  // 5. 写入 installed_plugins.json（v1 兼容）
+  const v1Path = path.join(pluginsDir, 'installed_plugins.json');
+  let v1Data = { plugins: {} };
+  if (fs.existsSync(v1Path)) {
+    try { v1Data = JSON.parse(fs.readFileSync(v1Path, 'utf8')); } catch (_e) { /* use default */ }
+  }
+  if (!v1Data.plugins) v1Data.plugins = {};
+
+  v1Data.plugins[registryKey] = { installPath: linkPath };
+
+  fs.writeFileSync(v1Path, JSON.stringify(v1Data, null, 2) + '\n', 'utf8');
+  console.log(chalk.green('   ✅ 已写入插件注册表 (installed_plugins.json)'));
+
+  // 6. 在 settings.json 中启用插件
+  const settingsPath = path.join(qoderHome, 'settings.json');
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch (_e) { /* use default */ }
+  }
+  if (!settings.enabledPlugins) settings.enabledPlugins = {};
+
+  settings.enabledPlugins[registryKey] = true;
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+  console.log(chalk.green('   ✅ 已在 settings.json 中启用插件'));
+
+  console.log('');
+  console.log(chalk.gray('   请重启 Qoder 使插件生效。'));
+}
+
+/**
+ * Qoder 项目级安装
+ */
+async function installQoderProject(pluginName, qoderManifest) {
+  // 项目级：在当前项目创建 .qoder-plugin 符号链接或复制
+  const targetDir = path.join(process.cwd(), '.qoder-plugin');
+  if (fs.existsSync(targetDir)) {
+    console.log(chalk.yellow('   ⏭ 当前项目已存在 .qoder-plugin/，跳过'));
+  } else {
+    try {
+      fs.symlinkSync(
+        path.join(PLUGIN_DIR, '.qoder-plugin'),
+        targetDir,
+        'junction'
+      );
+      console.log(chalk.green('   ✅ 已创建 .qoder-plugin 符号链接'));
+    } catch (_err) {
+      fs.mkdirSync(targetDir, { recursive: true });
+      fs.copyFileSync(qoderManifest, path.join(targetDir, 'plugin.json'));
+      console.log(chalk.green('   ✅ 已复制 .qoder-plugin/plugin.json 到项目'));
+    }
+  }
+
+  // 确保 skills 可被访问
+  const targetSkills = path.join(process.cwd(), 'skills');
+  if (!fs.existsSync(targetSkills)) {
+    try {
+      fs.symlinkSync(path.join(PLUGIN_DIR, 'skills'), targetSkills, 'junction');
+      console.log(chalk.green('   ✅ 已创建 skills/ 符号链接'));
+    } catch (_err) {
+      console.log(chalk.yellow('   ⚠ skills/ 链接创建失败，请手动确保 Qoder 可访问插件 skills 目录'));
     }
+  }
 
-    // 确保 hooks 可被访问
-    const targetHooks = path.join(process.cwd(), 'hooks');
-    if (!fs.existsSync(targetHooks)) {
-      try {
-        fs.symlinkSync(path.join(PLUGIN_DIR, 'hooks'), targetHooks, 'junction');
-        console.log(chalk.green('   ✅ 已创建 hooks/ 符号链接'));
-      } catch (_err) {
-        console.log(chalk.yellow('   ⚠ hooks/ 链接创建失败，请手动确保 Qoder 可访问插件 hooks 目录'));
-      }
+  // 确保 hooks 可被访问
+  const targetHooks = path.join(process.cwd(), 'hooks');
+  if (!fs.existsSync(targetHooks)) {
+    try {
+      fs.symlinkSync(path.join(PLUGIN_DIR, 'hooks'), targetHooks, 'junction');
+      console.log(chalk.green('   ✅ 已创建 hooks/ 符号链接'));
+    } catch (_err) {
+      console.log(chalk.yellow('   ⚠ hooks/ 链接创建失败，请手动确保 Qoder 可访问插件 hooks 目录'));
+    }
+  }
+}
+
+/**
+ * 递归复制目录（排除指定目录名）
+ */
+function copyDirRecursive(src, dest, excludeDirs) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    if (excludeDirs && excludeDirs.includes(entry.name)) continue;
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath, excludeDirs);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Qoder 用户级卸载 — 移除链接 + 注册表条目 + 启用配置
+ */
+function uninstallQoderUser(pluginName) {
+  const qoderHome = path.join(os.homedir(), '.qoder');
+  const pluginsDir = path.join(qoderHome, 'plugins');
+  const linkPath = path.join(pluginsDir, 'cache', 'local', pluginName);
+  const registryKey = `${pluginName}@local`;
+
+  // 1. 移除 junction 链接 / 复制的目录
+  if (fs.existsSync(linkPath)) {
+    try {
+      fs.rmSync(linkPath, { recursive: true, force: true });
+      console.log(chalk.green(`   ✅ 已移除插件目录: ${linkPath}`));
+    } catch (err) {
+      console.log(chalk.yellow(`   ⚠ 移除插件目录失败: ${err.message}`));
     }
   } else {
-    // 用户级：输出指引
-    console.log(chalk.gray('   → Qoder 用户级插件安装...'));
-    console.log('');
-    console.log(chalk.green('   ✅ Qoder 插件清单已就绪: ' + qoderManifest));
-    console.log('');
-    console.log('   Qoder 用户级安装方式：');
-    console.log('   1. 将本插件目录路径添加到 Qoder 插件搜索路径');
-    console.log('   2. 或在 Qoder 设置中配置插件目录指向: ' + PLUGIN_DIR);
-    console.log('   3. 重启 Qoder 使插件生效');
+    console.log(chalk.yellow('   ⏭ 插件目录不存在，跳过'));
   }
 
-  console.log('');
-  console.log(chalk.green.bold(`✅ adspecs 插件已配置到 Qoder (scope=${scope})`));
-  console.log('');
-  printSkillList();
+  // 2. 从 installed_plugins_v2.json 移除
+  const v2Path = path.join(pluginsDir, 'installed_plugins_v2.json');
+  if (fs.existsSync(v2Path)) {
+    try {
+      const v2Data = JSON.parse(fs.readFileSync(v2Path, 'utf8'));
+      if (v2Data.plugins && v2Data.plugins[registryKey]) {
+        delete v2Data.plugins[registryKey];
+        fs.writeFileSync(v2Path, JSON.stringify(v2Data, null, 2) + '\n', 'utf8');
+        console.log(chalk.green('   ✅ 已从注册表移除 (installed_plugins_v2.json)'));
+      }
+    } catch (_err) { /* ignore */ }
+  }
+
+  // 3. 从 installed_plugins.json 移除
+  const v1Path = path.join(pluginsDir, 'installed_plugins.json');
+  if (fs.existsSync(v1Path)) {
+    try {
+      const v1Data = JSON.parse(fs.readFileSync(v1Path, 'utf8'));
+      if (v1Data.plugins && v1Data.plugins[registryKey]) {
+        delete v1Data.plugins[registryKey];
+        fs.writeFileSync(v1Path, JSON.stringify(v1Data, null, 2) + '\n', 'utf8');
+        console.log(chalk.green('   ✅ 已从注册表移除 (installed_plugins.json)'));
+      }
+    } catch (_err) { /* ignore */ }
+  }
+
+  // 4. 从 settings.json 禁用
+  const settingsPath = path.join(qoderHome, 'settings.json');
+  if (fs.existsSync(settingsPath)) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      if (settings.enabledPlugins && settings.enabledPlugins[registryKey] !== undefined) {
+        delete settings.enabledPlugins[registryKey];
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+        console.log(chalk.green('   ✅ 已从 settings.json 移除启用配置'));
+      }
+    } catch (_err) { /* ignore */ }
+  }
+
+  console.log(chalk.gray('   请重启 Qoder 使变更生效。'));
 }
 
 /**
@@ -262,8 +438,8 @@ exports.uninstall = async function uninstall(options) {
   console.log('');
 
   if (platform === 'qoder') {
-    // Qoder 卸载：移除项目级链接
     if (scope === 'project') {
+      // Qoder 项目级卸载：移除项目链接
       const targetDir = path.join(process.cwd(), '.qoder-plugin');
       if (fs.existsSync(targetDir)) {
         try {
@@ -276,7 +452,8 @@ exports.uninstall = async function uninstall(options) {
         console.log(chalk.yellow('   ⏭ 项目未安装 .qoder-plugin/，无需卸载'));
       }
     } else {
-      console.log(chalk.yellow('   用户级卸载请从 Qoder 插件设置中移除本插件路径'));
+      // Qoder 用户级卸载：移除链接 + 注册表 + 启用配置
+      uninstallQoderUser(pluginName);
     }
     console.log('');
     console.log(chalk.green(`✅ ${pluginName} 已从 Qoder 卸载 (scope=${scope})`));