jsharness 1.3.0 → 1.4.1

package/bin/jsharness.js

@@ -2,7 +2,7 @@
 
 /**
  * jsharness CLI
- * 
+ *
  * Usage:
  *   npx jsharness init                        # 交互式初始化（选择工具+技术栈）
  *   npx jsharness init --tool codebuddy       # 指定工具（跳过工具选择）
@@ -13,18 +13,34 @@
  *   npx jsharness openspec list               # 列出 OpenSpec 变更
  */
 
-import { createRequire } from 'module';
-import { program } from 'commander';
+import { fileURLToPath, pathToFileURL } from 'url';
+import path from 'path';
+
+// 关键：用相对路径引用主库，不用 import('jsharness') 包名
+// 这样在 npx 临时安装环境中也能可靠定位模块
+// Windows 上必须用 file:// URL 格式，不能用 C:\path 格式
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const libPath = path.join(__dirname, '..', 'lib', 'index.mjs');
+const libURL = pathToFileURL(libPath).href;
 
+const { runInit, listTools, showStatus, listOpenSpecChanges, archiveOpenSpecChange } = await import(libURL);
+
+// 读取版本号
+import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
+let version = '0.0.0';
+try {
+  const pkg = require(path.join(__dirname, '..', 'package.json'));
+  version = pkg.version;
+} catch { /* ignore */ }
 
-// 通过包名引用主库（npm 安装后兼容）
-const { runInit, listTools, showStatus, listOpenSpecChanges, archiveOpenSpecChange } = await import('jsharness');
+// commander 延迟导入，确保路径解析先完成
+const { program } = await import('commander');
 
 program
   .name('jsharness')
   .description('Harness Engineering - AI 编程行为工程化管控系统')
-  .version(require('jsharness/package.json').version);
+  .version(version);
 
 program
   .command('init')
@@ -47,7 +63,6 @@ program
   .description('查看当前项目 Harness 初始化状态')
   .action(() => showStatus(process.cwd()));
 
-// OpenSpec 子命令
 const openspecCmd = program
   .command('openspec')
   .description('OpenSpec 变更管理');

package/lib/index.mjs

@@ -1,7 +1,13 @@
 /**
  * Harness Engineering - Core Library
- * 
+ *
  * 多适配器架构：检测 AI 工具 → 转换规则格式 → 注入到对应位置
+ *
+ * v1.4.0: 多源获取策略，确保 npx jsharness init 在任何项目中 100% 可用
+ *   1. import.meta.url 定位本包 .harness/ （最快）
+ *   2. process.argv[1] 反推包根目录（npx 直接执行时）
+ *   3. npm 全局安装目录搜索
+ *   4. npm registry 远端下载 tgz 解压
  */
 
 import fs from 'fs';
@@ -9,18 +15,14 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import readline from 'readline';
 import https from 'https';
-import zlib from 'zlib';
 import { execSync } from 'child_process';
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
 // ============================================================
-// 远端源配置（GitHub 仓库 + npm registry）
+// 常量
 // ============================================================
 
-const HARNESS_GITHUB_REPO = 'jieaiag/harness-engineering'; // TODO: 替换为实际仓库
 const HARNESS_NPM_PACKAGE = 'jsharness';
-const HARNESS_BRANCH = 'main';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 // ============================================================
 // 支持的 AI 工具清单
@@ -31,7 +33,6 @@ export const SUPPORTED_TOOLS = [
     id: 'codebuddy',
     name: 'CodeBuddy (腾讯云代码助手)',
     description: '.codebuddy/rules/ + .codebuddy/skills/',
-    detector: hasDir('.codebuddy') || hasFile('CODEBUDDY.md'),
     priority: 100,
     ruleFormat: 'markdown',
     skillFormat: 'markdown',
@@ -40,16 +41,14 @@ export const SUPPORTED_TOOLS = [
     id: 'cursor',
     name: 'Cursor',
     description: '.cursorrules 文件',
-    detector: hasFile('.cursorrules'),
     priority: 90,
     ruleFormat: 'cursor-md',
-    skillFormat: null, // Cursor 不支持独立 skills
+    skillFormat: null,
   },
   {
     id: 'copilot',
     name: 'GitHub Copilot',
     description: '.github/copilot-instructions.md',
-    detector: hasDir('.github'),
     priority: 80,
     ruleFormat: 'copilot-md',
     skillFormat: null,
@@ -58,7 +57,6 @@ export const SUPPORTED_TOOLS = [
     id: 'windsurf',
     name: 'Windsurf (Codeium)',
     description: '.windsurfrules 目录',
-    detector: hasFile('.windsurfrules') || hasDir('.windsurf'),
     priority: 70,
     ruleFormat: 'windsurf-md',
     skillFormat: null,
@@ -67,7 +65,6 @@ export const SUPPORTED_TOOLS = [
     id: 'continue',
     name: 'Continue (VS Code)',
     description: 'continue.config.json',
-    detector: hasFile('continue.config.json'),
     priority: 60,
     ruleFormat: 'continue-json',
     skillFormat: null,
@@ -76,7 +73,6 @@ export const SUPPORTED_TOOLS = [
     id: 'cline',
     name: 'Cline (VS Code)',
     description: '.clinerules 文件',
-    detector: hasFile('.clinerules'),
     priority: 50,
     ruleFormat: 'cline-md',
     skillFormat: null,
@@ -85,7 +81,6 @@ export const SUPPORTED_TOOLS = [
     id: 'qoder',
     name: 'Qoder (阿里云)',
     description: '.qoder/rules/ 目录',
-    detector: hasDir('.qoder'),
     priority: 95,
     ruleFormat: 'markdown',
     skillFormat: 'markdown',
@@ -94,7 +89,6 @@ export const SUPPORTED_TOOLS = [
     id: 'codex',
     name: 'Codex CLI (OpenAI)',
     description: 'AGENTS.md 文件（项目根目录）',
-    detector: hasFile('AGENTS.md') || hasDir('.codex'),
     priority: 85,
     ruleFormat: 'agents-md',
     skillFormat: null,
@@ -103,7 +97,6 @@ export const SUPPORTED_TOOLS = [
     id: 'claude-code',
     name: 'Claude Code (Anthropic)',
     description: '.claude/rules/ + CLAUDE.md',
-    detector: hasFile('CLAUDE.md') || hasDir('.claude'),
     priority: 93,
     ruleFormat: 'claude-rules-md',
     skillFormat: 'claude-skills-md',
@@ -112,7 +105,6 @@ export const SUPPORTED_TOOLS = [
     id: 'trae',
     name: 'Trae (字节跳动)',
     description: '.trae/rules/project_rules.md',
-    detector: hasDir('.trae') || hasFile('.trae/rules/project_rules.md'),
     priority: 75,
     ruleFormat: 'trae-rules-md',
     skillFormat: null,
@@ -123,36 +115,35 @@ export const SUPPORTED_TOOLS = [
 // 检测工具函数
 // ============================================================
 
-function hasDir(name) {
-  return () => fs.existsSync(name) && fs.lstatSync(name).isDirectory();
-}
-
-function hasFile(name) {
-  return () => fs.existsSync(name) && fs.lstatSync(name).isFile();
-}
-
 /**
  * 自动检测当前项目使用的 AI 工具
  */
 export function detectTool(projectDir) {
+  const detectors = {
+    codebuddy:   ['.codebuddy', 'CODEBUDDY.md'],
+    cursor:      ['.cursorrules'],
+    copilot:     ['.github'],
+    windsurf:    ['.windsurfrules', '.windsurf'],
+    continue:    ['continue.config.json'],
+    cline:       ['.clinerules'],
+    qoder:       ['.qoder'],
+    codex:       ['AGENTS.md', '.codex'],
+    'claude-code': ['CLAUDE.md', '.claude'],
+    trae:        ['.trae'],
+  };
+
   const results = [];
-  
   for (const tool of SUPPORTED_TOOLS) {
-    try {
-      const detectFn = tool.detector;
-      const isDetected = typeof detectFn === 'function' 
-        ? detectFn() 
-        : fs.existsSync(path.join(projectDir, typeof detectFn === 'string' ? detectFn : ''));
-      
-      if (isDetected) {
+    const markers = detectors[tool.id] || [];
+    for (const marker of markers) {
+      const fullPath = path.join(projectDir, marker);
+      if (fs.existsSync(fullPath)) {
         results.push({ ...tool, detected: true });
+        break;
       }
-    } catch {
-      // 检测失败，跳过
     }
   }
 
-  // 按优先级排序，返回最匹配的
   results.sort((a, b) => b.priority - a.priority);
   return results;
 }
@@ -161,17 +152,11 @@ export function detectTool(projectDir) {
 // 规则转换引擎
 // ============================================================
 
-/**
- * 将 .harness/rules/*.md 转换为目标工具的格式
- */
 export function transformRules(ruleFiles, targetToolId, options = {}) {
   const transformer = RULE_TRANSFORMERS[targetToolId] || RULE_TRANSFORMERS['generic'];
   return transformer(ruleFiles, options);
 }
 
-/**
- * 将 .harness/skills/*.md 转换为目标工具的格式
- */
 export function transformSkills(skillFiles, targetToolId, options = {}) {
   const transformer = SKILL_TRANSFORMERS[targetToolId] || SKILL_TRANSFORMERS['generic'];
   return transformer(skillFiles, options);
@@ -183,169 +168,90 @@ export function transformSkills(skillFiles, targetToolId, options = {}) {
 
 const RULE_TRANSFORMERS = {
 
-  /** CodeBuddy: 原样复制 .md 到 .codebuddy/rules/ */
   codebuddy(ruleFiles, opts) {
     const outputs = [];
     for (const file of ruleFiles) {
       const content = fs.readFileSync(file.path, 'utf-8');
-      outputs.push({
-        relativePath: `.codebuddy/rules/${file.name}`,
-        content,
-        source: file.path,
-      });
+      outputs.push({ relativePath: `.codebuddy/rules/${file.name}`, content, source: file.path });
     }
     return { format: 'directory', files: outputs };
   },
 
-  /** Cursor: 合并所有规则为 .cursorrules */
   cursor(ruleFiles, opts) {
-    let content = `# Harness Engineering Rules\n`;
-    content += `> Generated by hariness on ${new Date().toISOString().split('T')[0]}\n\n`;
-    
+    let content = `# Harness Engineering Rules\n> Generated by hariness on ${new Date().toISOString().split('T')[0]}\n\n`;
     for (const file of ruleFiles) {
-      const raw = fs.readFileSync(file.path, 'utf-8');
-      content += extractBody(raw);
+      content += extractBody(fs.readFileSync(file.path, 'utf-8'));
       content += '\n---\n\n';
     }
-    
     return { format: 'single-file', files: [{ relativePath: '.cursorrules', content }] };
   },
 
-  /** GitHub Copilot: 合并为 .github/copilot-instructions.md */
   copilot(ruleFiles, opts) {
-    let content = `# Project Rules & Guidelines\n\n`;
-    content += `## Harness Engineering System\n\n`;
-    
+    let content = `# Project Rules & Guidelines\n\n## Harness Engineering System\n\n`;
     for (const file of ruleFiles) {
       const raw = fs.readFileSync(file.path, 'utf-8');
-      content += `### ${extractTitle(raw)}\n\n`;
-      content += extractBody(raw);
-      content += '\n\n';
+      content += `### ${extractTitle(raw)}\n\n${extractBody(raw)}\n\n`;
     }
-    
     return { format: 'single-file', files: [{ relativePath: '.github/copilot-instructions.md', content }] };
   },
 
-  /** Windsurf: .windsurfrules 格式 */
   windsurf(ruleFiles, opts) {
     let content = '';
     for (const file of ruleFiles) {
       const raw = fs.readFileSync(file.path, 'utf-8');
-      content += `<rules>\n`;
-      content += `<rule name="${file.name.replace('.md', '')}">\n`;
-      content += extractBody(raw).trim();
-      content += `\n</rule>\n</rules>\n\n`;
+      content += `<rules>\n<rule name="${file.name.replace('.md', '')}">\n${extractBody(raw).trim()}\n</rule>\n</rules>\n\n`;
     }
     return { format: 'single-file', files: [{ relativePath: '.windsurfrules', content }] };
   },
 
-  /** Continue: continue.config.json 格式 */
   continue(ruleFiles, opts) {
-    const rules = [];
-    for (const file of ruleFiles) {
+    const rules = ruleFiles.map(file => {
       const raw = fs.readFileSync(file.path, 'utf-8');
-      rules.push({
-        name: file.name.replace('.md', ''),
-        type: 'rule',
-        description: extractDescription(raw),
-        content: extractBody(raw),
-      });
-    }
-    const config = { rules };
-    const content = JSON.stringify(config, null, 2);
-    return { format: 'json-config', files: [{ relativePath: 'continue.config.json', content }] };
+      return { name: file.name.replace('.md', ''), type: 'rule', description: extractDescription(raw), content: extractBody(raw) };
+    });
+    return { format: 'json-config', files: [{ relativePath: 'continue.config.json', content: JSON.stringify({ rules }, null, 2) }] };
   },
 
-  /** Cline: .clinerules 格式（类似 Cursor） */
   cline(ruleFiles, opts) {
     let content = `# Harness Engineering Rules for Cline\n\n`;
     for (const file of ruleFiles) {
       const raw = fs.readFileSync(file.path, 'utf-8');
-      content += `## ${extractTitle(raw)}\n\n`;
-      content += extractBody(raw);
-      content += '\n---\n\n';
+      content += `## ${extractTitle(raw)}\n\n${extractBody(raw)}\n---\n\n`;
     }
     return { format: 'single-file', files: [{ relativePath: '.clinerules', content }] };
   },
 
-  /**
-   * ================================================================
-   * 新增工具适配器 (v1.1+)
-   * ================================================================
-   */
-
-  /** Qoder: 原样复制 .md 到 .qoder/rules/ (与 CodeBuddy 相同模式) */
   qoder(ruleFiles, opts) {
     const outputs = [];
     for (const file of ruleFiles) {
       const content = fs.readFileSync(file.path, 'utf-8');
-      outputs.push({
-        relativePath: `.qoder/rules/${file.name}`,
-        content,
-        source: file.path,
-      });
+      outputs.push({ relativePath: `.qoder/rules/${file.name}`, content, source: file.path });
     }
     return { format: 'directory', files: outputs };
   },
 
-  /** Codex CLI: 合并所有规则为 AGENTS.md（项目根目录） */
   codex(ruleFiles, opts) {
-    let content = `# Harness Engineering - Project Instructions for Codex CLI\n`;
-    content += `> Generated by hariness on ${new Date().toISOString().split('T')[0]}\n`;
-    content += `> Source: .harness/ rules & skills system\n\n`;
-
-    // Codex AGENTS.md 推荐结构：Commands / Architecture / Conventions / Important
-    content += `## Overview\n\n`;
-    content += `This project uses **Harness Engineering** system with the following tech stack:\n\n`;
-    content += `- Frontend: Vue3 + Vite + TypeScript + Pinia + Element Plus\n`;
-    content += `- Backend: Spring Boot 3.2 + JDK21 + MyBatis-Plus + Nacos\n\n`;
-
-    content += `---\n\n## Conventions & Rules\n\n`;
-
+    let content = `# Harness Engineering - Project Instructions for Codex CLI\n> Generated by hariness on ${new Date().toISOString().split('T')[0]}\n> Source: .harness/ rules & skills system\n\n`;
+    content += `## Overview\n\nThis project uses **Harness Engineering** system with the following tech stack:\n\n- Frontend: Vue3 + Vite + TypeScript + Pinia + Element Plus\n- Backend: Spring Boot 3.2 + JDK21 + MyBatis-Plus + Nacos\n\n---\n\n## Conventions & Rules\n\n`;
     for (const file of ruleFiles) {
       const raw = fs.readFileSync(file.path, 'utf-8');
-      content += `### ${extractTitle(raw)}\n\n`;
-      content += extractBody(raw);
-      content += '\n\n';
+      content += `### ${extractTitle(raw)}\n\n${extractBody(raw)}\n\n`;
     }
-
-    // 追加 Skills 摘要
-    content += `---\n\n## Available Build/Test Skills\n\n`;
-    content += 'See .harness/skills/ directory for detailed build, lint, test, and review procedures.\n';
-    content += `- \`npm run build\` — Vue3 frontend production build\n`;
-    content += `- \`mvn compile test\` — Java backend build with tests\n`;
-    content += `- \`node .harness/gate/index.js\` — Run gate compliance checks\n\n`;
-
+    content += `---\n\n## Available Build/Test Skills\n\nSee .harness/skills/ directory for detailed build, lint, test, and review procedures.\n- \`npm run build\` — Vue3 frontend production build\n- \`mvn compile test\` — Java backend build with tests\n- \`node .harness/gate/index.js\` — Run gate compliance checks\n\n`;
     return { format: 'single-file', files: [{ relativePath: 'AGENTS.md', content }] };
   },
 
-  /** Claude Code: 输出为 .claude/rules/*.md（支持 paths: frontmatter 路径限定） */
   'claude-code'(ruleFiles, opts) {
     const outputs = [];
 
-    // 生成 CLAUDE.md 主文件（精简版，<200行）
-    let claudeMd = `# Harness Engineering System\n\n`;
-    claudeMd += `> Auto-generated by hariness. Full rules in \`.claude/rules/\`\n\n`;
-    claudeMd += `## Tech Stack\n`;
-    claudeMd += `- **Frontend**: Vue3 + Vite + TypeScript + Pinia + Element Plus\n`;
-    claudeMd += `- **Backend**: Spring Boot 3.2 (JDK21 Virtual Threads) + MyBatis-Plus\n\n`;
-    claudeMd += `## Commands\n`;
-    claudeMd += `\`\`\`bash\n`;
-    claudeMd += `npm run build          # Frontend build\n`;
-    claudeMd += `npm run lint           # ESLint check\n`;
-    claudeMd += `mvn compile test       # Backend build + test\n`;
-    claudeMd += `node .harness/gate/index.js   # Gate checks\n`;
-    claudeMd += `\`\`\`\n\n`;
-    claudeMd += `> Detailed rules are loaded from \`.claude/rules/\` files below.\n`;
-
+    let claudeMd = `# Harness Engineering System\n\n> Auto-generated by hariness. Full rules in \`.claude/rules/\`\n\n`;
+    claudeMd += `## Tech Stack\n- **Frontend**: Vue3 + Vite + TypeScript + Pinia + Element Plus\n- **Backend**: Spring Boot 3.2 (JDK21 Virtual Threads) + MyBatis-Plus\n\n`;
+    claudeMd += `## Commands\n\`\`\`bash\nnpm run build          # Frontend build\nnpm run lint           # ESLint check\nmvn compile test       # Backend build + test\nnode .harness/gate/index.js   # Gate checks\n\`\`\`\n\n> Detailed rules are loaded from \`.claude/rules/\` files below.\n`;
     outputs.push({ relativePath: 'CLAUDE.md', content: claudeMd });
 
-    // 为每个规则文件生成独立的 .claude/rules/*.md，带路径限定 frontmatter
     for (const file of ruleFiles) {
       const raw = fs.readFileSync(file.path, 'utf-8');
       const body = extractBody(raw);
-
-      // 根据规则类别决定 paths 范围
       let scopePaths = null;
       if (file.category === 'project') {
         if (file.relativePath.includes('vue3') || file.relativePath.includes('frontend') || file.relativePath.includes('web')) {
@@ -354,48 +260,28 @@ const RULE_TRANSFORMERS = {
           scopePaths = ['src/main/**/*.java', '**/*.java'];
         }
       }
-
       let content = '';
       if (scopePaths) {
         content += `---\npaths:\n`;
-        for (const p of scopePaths) {
-          content += `  - "${p}"\n`;
-        }
+        for (const p of scopePaths) content += `  - "${p}"\n`;
         content += `---\n\n`;
       }
-
       content += body;
-
-      outputs.push({
-        relativePath: `.claude/rules/${file.name}`,
-        content,
-        source: file.path,
-      });
+      outputs.push({ relativePath: `.claude/rules/${file.name}`, content, source: file.path });
     }
 
     return { format: 'multi-file', files: outputs };
   },
 
-  /** Trae: 合并为 .trae/rules/project_rules.md */
   trae(ruleFiles, opts) {
-    let content = `# Harness Engineering Rules for Trae\n\n`;
-    content += `> Generated by hariness on ${new Date().toISOString().split('T')[0]}\n\n`;
-    content += `## 技术栈\n\n`;
-    content += `- 前端: Vue3 + Vite + TypeScript + Pinia + Element Plus\n`;
-    content += `- 后端: Spring Boot 3.2 + JDK21 + MyBatis-Plus\n\n`;
-    content += `---\n\n`;
-
+    let content = `# Harness Engineering Rules for Trae\n\n> Generated by hariness on ${new Date().toISOString().split('T')[0]}\n\n## 技术栈\n\n- 前端: Vue3 + Vite + TypeScript + Pinia + Element Plus\n- 后端: Spring Boot 3.2 + JDK21 + MyBatis-Plus\n\n---\n\n`;
     for (const file of ruleFiles) {
       const raw = fs.readFileSync(file.path, 'utf-8');
-      content += `### ${extractTitle(raw)}\n\n`;
-      content += extractBody(raw);
-      content += '\n\n---\n\n';
+      content += `### ${extractTitle(raw)}\n\n${extractBody(raw)}\n\n---\n\n`;
     }
-
     return { format: 'single-file', files: [{ relativePath: '.trae/rules/project_rules.md', content }] };
   },
 
-  /** Generic fallback */
   generic(ruleFiles, opts) {
     return RULE_TRANSFORMERS.codebuddy(ruleFiles, opts);
   },
@@ -403,74 +289,43 @@ const RULE_TRANSFORMERS = {
 
 const SKILL_TRANSFORMERS = {
 
-  /** CodeBuddy: 复制到 .codebuddy/skills/ */
   codebuddy(skillFiles, opts) {
     const outputs = [];
     for (const file of skillFiles) {
-      const content = fs.readFileSync(file.path, 'utf-8');
-      outputs.push({
-        relativePath: `.codebuddy/skills/${file.name}`,
-        content,
-        source: file.path,
-      });
+      outputs.push({ relativePath: `.codebuddy/skills/${file.name}`, content: fs.readFileSync(file.path, 'utf-8'), source: file.path });
     }
     return { format: 'directory', files: outputs };
   },
 
-  /** 不支持 skills 的工具 → 合并到规则文件中 */
   generic(skillFiles, opts) {
     const outputs = [];
     for (const file of skillFiles) {
-      const content = fs.readFileSync(file.path, 'utf-8');
-      outputs.push({
-        relativePath: `.harness/skills/${file.name}`, // 保持原始位置作为参考
-        content,
-        source: file.path,
-      });
+      outputs.push({ relativePath: `.harness/skills/${file.name}`, content: fs.readFileSync(file.path, 'utf-8'), source: file.path });
     }
     return { format: 'reference', files: outputs };
   },
 
-  /** Qoder: 复制到 .qoder/skills/ */
   qoder(skillFiles, opts) {
     const outputs = [];
     for (const file of skillFiles) {
-      const content = fs.readFileSync(file.path, 'utf-8');
-      outputs.push({
-        relativePath: `.qoder/skills/${file.name}`,
-        content,
-        source: file.path,
-      });
+      outputs.push({ relativePath: `.qoder/skills/${file.name}`, content: fs.readFileSync(file.path, 'utf-8'), source: file.path });
     }
     return { format: 'directory', files: outputs };
   },
 
-  /** Claude Code: 复制到 .claude/skills/ (Claude 支持自动触发的 skills) */
   'claude-code'(skillFiles, opts) {
     const outputs = [];
     for (const file of skillFiles) {
       const raw = fs.readFileSync(file.path, 'utf-8');
       const body = extractBody(raw);
-
-      // Claude Code skills 格式：YAML frontmatter + Markdown body
-      let content = `---\n`;
-      content += `name: ${file.name.replace('.md', '')}\n`;
-      content += `description: Harness Engineering Skill - ${extractDescription(raw) || file.name}\n`;
-      // 自动触发条件
+      let content = `---\nname: ${file.name.replace('.md', '')}\ndescription: Harness Engineering Skill - ${extractDescription(raw) || file.name}\n`;
       const lowerName = file.name.toLowerCase();
       if (lowerName.includes('build')) content += `trigger_type: manual\n`;
       else if (lowerName.includes('test')) content += `trigger_type: on_save\n`;
       else if (lowerName.includes('lint') || lowerName.includes('review')) content += `trigger_type: on_pr\n`;
       else content += `trigger_type: manual\n`;
-      content += `---\n\n`;
-
-      content += body;
-
-      outputs.push({
-        relativePath: `.claude/skills/${file.name}`,
-        content,
-        source: file.path,
-      });
+      content += `---\n\n${body}`;
+      outputs.push({ relativePath: `.claude/skills/${file.name}`, content, source: file.path });
     }
     return { format: 'directory', files: outputs };
   },
@@ -486,129 +341,119 @@ function extractTitle(markdown) {
 }
 
 function extractDescription(markdown) {
-  // 尝试提取第一段描述性文字
   const body = markdown.replace(/^#.+/gm, '').trim();
   const firstPara = body.match(/^(.+)/m);
   return firstPara ? firstPara[1].slice(0, 120) : '';
 }
 
 function extractBody(markdown) {
-  // 移除 frontmatter (--- ... ---)
   let body = markdown;
   if (body.startsWith('---')) {
     const endIdx = body.indexOf('---', 3);
-    if (endIdx > 0) {
-      body = body.slice(endIdx + 3).trim();
-    }
+    if (endIdx > 0) body = body.slice(endIdx + 3).trim();
   }
   return body;
 }
 
 // ============================================================
-// 扫描 Harness 源文件
+// 多源获取 .harness/ 模板（核心：确保任何项目都能命中）
 // ============================================================
 
 /**
  * 获取 .harness/ 模板源目录
  *
- * 三级回退策略：
- *   1. 本包自带（import.meta.url 定位）— npx 缓存正常时最快
- *   2. npx 缓存解压目录 — 某些 npx 版本 .harness/ 未包含时
- *   3. 从 npm registry 下载 tgz 并解压到临时目录 — 纯净环境兜底
- *
- * 类似 OpenSpec/SpecKit 的初始化方式：不依赖项目本地 node_modules，
- * 而是从远端（npm registry）直接拉取模板文件写入目标项目。
- *
- * @param {object} [options]
- * @param {boolean} [options.verbose]
- * @returns {Promise<string|null>} .harness/ 目录的绝对路径，全部失败返回 null
+ * 四级回退策略，确保 npx jsharness init 在任何环境下 100% 可用：
+ *   1. import.meta.url 定位本包 .harness/ — npx 缓存正常时最快
+ *   2. process.argv[1] / npm 全局安装目录反推 — 全局安装时
+ *   3. require.resolve 模块解析 — npm install 后
+ *   4. npm registry 远端下载 tgz 解压 — 纯净环境兜底
  */
 async function getHarnessSourceDir(options = {}) {
   const { verbose = false } = options;
+  const tried = [];
 
-  // ── 策略 1: 本包自带 .harness/（基于 import.meta.url）──
-  const libDir = path.dirname(fileURLToPath(import.meta.url));
+  // ── 策略 1: import.meta.url 定位（npx 缓存中 lib/ 旁边就有 .harness/）──
+  const libDir = __dirname;
   const bundledDir = path.join(libDir, '..', '.harness');
+  tried.push(`import.meta.url → ${bundledDir}`);
   if (fs.existsSync(bundledDir) && fs.existsSync(path.join(bundledDir, 'rules'))) {
     if (verbose) console.log(`   📂 源=本包自带: ${bundledDir}`);
     return bundledDir;
   }
 
-  // ── 策略 2: npx 缓存中查找 jsharness 包 ──
+  // ── 策略 2: 从 CLI 入口文件反推包根目录 ──
+  // process.argv[1] = /path/to/npx-cache/.../node_modules/jsharness/bin/jsharness.js
+  // 包根 = bin/ 的上一级
   try {
-    const npxCacheDir = findNpxCacheDir();
-    if (npxCacheDir) {
-      if (verbose) console.log(`   📂 源=npx缓存: ${npxCacheDir}`);
-      return npxCacheDir;
+    const cliPath = process.argv[1];
+    if (cliPath) {
+      const cliDir = path.dirname(path.resolve(cliPath));
+      // 可能是 bin/ 目录 → 上级就是包根
+      const parentDir = path.dirname(cliDir);
+      const hDir = path.join(parentDir, '.harness');
+      tried.push(`argv[1] → ${hDir}`);
+      if (fs.existsSync(hDir) && fs.existsSync(path.join(hDir, 'rules'))) {
+        if (verbose) console.log(`   📂 源=CLI入口反推: ${hDir}`);
+        return hDir;
+      }
+      // npx 有时结构是 node_modules/jsharness/bin/ → 向上两级
+      if (path.basename(cliDir) === 'bin') {
+        const hDir2 = path.join(path.dirname(parentDir), '.harness');
+        tried.push(`argv[1]+1 → ${hDir2}`);
+        if (fs.existsSync(hDir2) && fs.existsSync(path.join(hDir2, 'rules'))) {
+          if (verbose) console.log(`   📂 源=CLI入口反推(深): ${hDir2}`);
+          return hDir2;
+        }
+      }
     }
   } catch { /* ignore */ }
 
-  // ── 策略 3: 从 npm registry 下载 jsharness tgz 并解压 ──
-  console.log('   ⬇️  本地未找到 .harness/ 模板，从 npm 远端拉取...');
-  const remoteDir = await downloadAndExtractFromNpm(options);
-  if (remoteDir) {
-    if (verbose) console.log(`   📂 源=npm远端: ${remoteDir}`);
-    return remoteDir;
-  }
-
-  return null;
-}
-
-/**
- * 在 npx 缓存目录中搜索包含 .harness/ 的 jsharness 包
- */
-function findNpxCacheDir() {
-  const candidates = [];
-
-  // npm 缓存根目录
+  // ── 策略 3: npm 全局安装路径搜索 ──
   try {
-    const npmCacheRoot = execSync('npm config get cache', { encoding: 'utf-8' }).trim();
-    candidates.push(path.join(npmCacheRoot, '_npx'));
+    const globalDir = getNpmGlobalDir();
+    if (globalDir) {
+      const hDir = path.join(globalDir, 'node_modules', HARNESS_NPM_PACKAGE, '.harness');
+      tried.push(`npm全局 → ${hDir}`);
+      if (fs.existsSync(hDir) && fs.existsSync(path.join(hDir, 'rules'))) {
+        if (verbose) console.log(`   📂 源=npm全局: ${hDir}`);
+        return hDir;
+      }
+    }
   } catch { /* ignore */ }
 
-  // 常见 npx 缓存路径
-  const homeDir = process.env.HOME || process.env.USERPROFILE || process.env.HOMEPATH || '';
-  if (homeDir) {
-    candidates.push(
-      path.join(homeDir, 'AppData', 'Local', 'npm-cache', '_npx'),  // Windows
-      path.join(homeDir, '.npm', '_npx'),                            // Linux/macOS
-    );
-  }
-
-  for (const cacheRoot of candidates) {
-    if (!fs.existsSync(cacheRoot)) continue;
-
-    // 递归搜索含 .harness/ 的 jsharness 包目录
-    const found = searchHarnessInDir(cacheRoot, 3);
-    if (found) return found;
+  // ── 策略 4: 从 npm registry 下载 tgz 并解压 ──
+  console.log('   ⬇️  本地未找到 .harness/ 模板，从 npm 远端拉取...');
+  try {
+    const remoteDir = await downloadAndExtractFromNpm(options);
+    if (remoteDir) {
+      if (verbose) console.log(`   📂 源=npm远端: ${remoteDir}`);
+      return remoteDir;
+    }
+    tried.push('npm远端下载 → 失败');
+  } catch (err) {
+    tried.push(`npm远端 → ${err.message}`);
   }
 
+  // ── 全部失败 ──
+  console.error('\n❌ 无法获取 .harness/ 模板。已尝试的路径：');
+  for (const t of tried) console.error(`   • ${t}`);
+  console.error('');
+  console.error('   请尝试：');
+  console.error('     npm install -g jsharness && jsharness init');
+  console.error('   或检查网络连接后重试：');
+  console.error('     npx jsharness@latest init');
   return null;
 }
 
 /**
- * 在指定目录下递归搜索包含 .harness/rules/ 的目录
+ * 获取 npm 全局安装根目录
  */
-function searchHarnessInDir(dir, maxDepth) {
-  if (maxDepth <= 0) return null;
+function getNpmGlobalDir() {
   try {
-    const entries = fs.readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const fullPath = path.join(dir, entry.name);
-
-      // 检查是否包含 .harness/rules/
-      const harnessDir = path.join(fullPath, '.harness');
-      if (fs.existsSync(path.join(harnessDir, 'rules'))) {
-        return harnessDir;
-      }
-
-      // 继续向下搜索
-      const found = searchHarnessInDir(fullPath, maxDepth - 1);
-      if (found) return found;
-    }
-  } catch { /* ignore permission errors */ }
-  return null;
+    return execSync('npm root -g', { encoding: 'utf-8' }).trim();
+  } catch {
+    return null;
+  }
 }
 
 /**
@@ -617,66 +462,80 @@ function searchHarnessInDir(dir, maxDepth) {
 async function downloadAndExtractFromNpm(options = {}) {
   const { verbose = false } = options;
 
-  try {
-    // 1. 获取包的 tgz URL
-    const packUrl = await getNpmPackageTarballUrl();
-    if (!packUrl) return null;
-
-    // 2. 下载 tgz 到临时目录
-    const tmpDir = path.join(process.env.TEMP || process.env.TMP || '/tmp', `jsharness-${Date.now()}`);
-    fs.mkdirSync(tmpDir, { recursive: true });
-    const tgzPath = path.join(tmpDir, 'jsharness.tgz');
+  // 1. 获取包的 tgz URL
+  const packUrl = await getNpmPackageTarballUrl();
+  if (!packUrl) return null;
 
-    if (verbose) console.log(`   📦 下载: ${packUrl}`);
-    await downloadFile(packUrl, tgzPath);
+  // 2. 下载 tgz 到临时目录
+  const tmpDir = path.join(
+    process.env.TEMP || process.env.TMP || process.env.TMPDIR || '/tmp',
+    `jsharness-${Date.now()}`
+  );
+  fs.mkdirSync(tmpDir, { recursive: true });
+  const tgzPath = path.join(tmpDir, 'jsharness.tgz');
 
-    // 3. 解压（优先 tar 命令，回退到 Node.js 流式解压）
-    const extractDir = path.join(tmpDir, 'extracted');
-    fs.mkdirSync(extractDir, { recursive: true });
+  if (verbose) console.log(`   📦 下载: ${packUrl}`);
+  await downloadFile(packUrl, tgzPath);
 
-    try {
-      execSync(`tar -xzf "${tgzPath}" -C "${extractDir}"`, { stdio: verbose ? 'inherit' : 'pipe' });
-    } catch {
-      // tar 命令失败（某些 Windows 环境），使用 Node.js 解压
-      if (verbose) console.log('   📦 tar 命令失败，使用 Node.js 解压...');
-      await extractTgzWithNode(tgzPath, extractDir);
-    }
+  // 3. 解压
+  const extractDir = path.join(tmpDir, 'extracted');
+  fs.mkdirSync(extractDir, { recursive: true });
 
-    // 解压后目录结构: package/.harness/ 或 .harness/
-    const harnessDir = path.join(extractDir, 'package', '.harness');
-    if (fs.existsSync(harnessDir)) return harnessDir;
+  extractTgz(tgzPath, extractDir, verbose);
 
-    const altDir = path.join(extractDir, '.harness');
-    if (fs.existsSync(altDir)) return altDir;
+  // 4. 查找 .harness/ 目录
+  const harnessDir = path.join(extractDir, 'package', '.harness');
+  if (fs.existsSync(harnessDir) && fs.existsSync(path.join(harnessDir, 'rules'))) {
+    return harnessDir;
+  }
 
-    // 深度搜索
-    return searchHarnessInDir(extractDir, 2);
-  } catch (err) {
-    if (verbose) console.log(`   ⚠️  npm 远端下载失败: ${err.message}`);
-    return null;
+  // 有些 tgz 没有 package/ 前缀
+  const altDir = path.join(extractDir, '.harness');
+  if (fs.existsSync(altDir) && fs.existsSync(path.join(altDir, 'rules'))) {
+    return altDir;
   }
+
+  // 深度搜索
+  return searchHarnessInDir(extractDir, 3);
 }
 
 /**
- * 使用 Node.js 内置模块解压 .tgz 文件
- * .tgz = gzip(tar)，使用 zlib + tar 命令组合
+ * 解压 tgz 文件（跨平台兼容）
  */
-async function extractTgzWithNode(tgzPath, destDir) {
-  // Windows 10+ 和 Linux/macOS 都自带 tar 命令
-  // 但 Windows 的 tar.exe 路径可能不同
-  const tarCommands = [
+function extractTgz(tgzPath, destDir, verbose) {
+  const commands = [
     `tar -xzf "${tgzPath}" -C "${destDir}"`,
-    `cmd /c "tar -xzf \\"${tgzPath}\\" -C \\"${destDir}\\""`,
   ];
+  // Windows 可能需要不同调用方式
+  if (process.platform === 'win32') {
+    commands.push(`cmd /c "tar -xzf \\"${tgzPath}\\" -C \\"${destDir}\\""`);
+  }
 
-  for (const cmd of tarCommands) {
+  for (const cmd of commands) {
     try {
-      execSync(cmd, { stdio: 'pipe' });
-      return; // 成功
-    } catch { /* 尝试下一种 */ }
+      execSync(cmd, { stdio: verbose ? 'inherit' : 'pipe' });
+      return;
+    } catch { /* try next */ }
   }
+  throw new Error('tar 解压失败，请确认系统安装了 tar 命令');
+}
 
-  throw new Error('所有 tar 命令均失败，请确认系统安装了 tar');
+/**
+ * 在指定目录下递归搜索包含 .harness/rules/ 的目录
+ */
+function searchHarnessInDir(dir, maxDepth) {
+  if (maxDepth <= 0) return null;
+  try {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const fullPath = path.join(dir, entry.name);
+      const rulesPath = path.join(fullPath, '.harness', 'rules');
+      if (fs.existsSync(rulesPath)) return path.join(fullPath, '.harness');
+      const found = searchHarnessInDir(fullPath, maxDepth - 1);
+      if (found) return found;
+    }
+  } catch { /* ignore */ }
+  return null;
 }
 
 /**
@@ -719,12 +578,16 @@ function downloadFile(url, destPath) {
       res.pipe(file);
       file.on('finish', () => { file.close(resolve); });
     }).on('error', (err) => {
-      fs.unlinkSync(destPath);
+      try { fs.unlinkSync(destPath); } catch { /* ignore */ }
       reject(err);
     });
   });
 }
 
+// ============================================================
+// 扫描 Harness 源文件
+// ============================================================
+
 export function scanHarnessRules(harnessDir, stackFilter) {
   const rulesDir = path.join(harnessDir, 'rules');
   const results = [];
@@ -739,24 +602,15 @@ export function scanHarnessRules(harnessDir, stackFilter) {
       // 技术栈过滤
       if (stackFilter && stackFilter !== 'all') {
         const lowerRel = relPath.toLowerCase();
-        if (stackFilter === 'vue3' && !lowerRel.includes('vue') && !lowerRel.includes('frontend') && !lowerRel.includes('global')) {
-          if (!lowerRel.includes('global') && !lowerRel.includes('frontend') && !lowerRel.includes('web')) {
-            continue;
-          }
+        if (stackFilter === 'vue3' && !lowerRel.includes('vue') && !lowerRel.includes('frontend') && !lowerRel.includes('global') && !lowerRel.includes('web')) {
+          continue;
         }
         if (stackFilter === 'java' && !lowerRel.includes('java') && !lowerRel.includes('backend') && !lowerRel.includes('global')) {
-          if (!lowerRel.includes('global') && !lowerRel.includes('backend')) {
-            continue;
-          }
+          continue;
         }
       }
 
-      results.push({
-        name: entry,
-        path: filePath,
-        category,
-        relativePath: relPath,
-      });
+      results.push({ name: entry, path: filePath, category, relativePath: relPath });
     }
   }
 
@@ -769,20 +623,12 @@ export function scanHarnessRules(harnessDir, stackFilter) {
 export function scanHarnessSkills(harnessDir, stackFilter) {
   const skillsDir = path.join(harnessDir, 'skills');
   const results = [];
-
   if (!fs.existsSync(skillsDir)) return results;
 
-  const entries = fs.readdirSync(skillsDir).filter(f => f.endsWith('.md'));
-  for (const entry of entries) {
+  for (const entry of fs.readdirSync(skillsDir).filter(f => f.endsWith('.md'))) {
     const filePath = path.join(skillsDir, entry);
-    results.push({
-      name: entry,
-      path: filePath,
-      category: 'skill',
-      relativePath: path.relative(harnessDir, filePath),
-    });
+    results.push({ name: entry, path: filePath, category: 'skill', relativePath: path.relative(harnessDir, filePath) });
   }
-
   return results;
 }
 
@@ -799,12 +645,10 @@ export function injectOutputs(projectDir, outputs, options = {}) {
     const targetPath = path.join(projectDir, output.relativePath);
     const targetDir = path.dirname(targetPath);
 
-    // 创建目录
     if (!fs.existsSync(targetDir)) {
       fs.mkdirSync(targetDir, { recursive: true });
     }
 
-    // 检查是否已存在
     if (fs.existsSync(targetPath) && !force) {
       skipped.push(output.relativePath);
       if (verbose) console.log(`  ⏭  跳过 (已存在): ${output.relativePath}`);
@@ -819,45 +663,22 @@ export function injectOutputs(projectDir, outputs, options = {}) {
   return { written, skipped };
 }
 
-// ============================================================
-// CLI 命令实现
-// ============================================================
-
 // ============================================================
 // 交互式问答辅助函数
 // ============================================================
 
-/**
- * 通用 readline 提问
- */
 function askQuestion(query) {
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => {
-    rl.question(query, (answer) => {
-      rl.close();
-      resolve(answer.trim());
-    });
+    rl.question(query, (answer) => { rl.close(); resolve(answer.trim()); });
   });
 }
 
-/**
- * 交互式选择 AI 编程工具
- *
- * 先自动检测，检测结果让用户确认或修改；
- * 检测不到则展示列表让用户选择（支持多选，逗号分隔）。
- *
- * @param {string} projectDir
- * @returns {Promise<string[]>} 选中的工具 ID 列表
- */
 async function promptSelectTools(projectDir) {
   const detected = detectTool(projectDir);
 
   console.log('━━━ 选择 AI 编程工具 ━━━\n');
 
-  // 展示所有支持的工具
   SUPPORTED_TOOLS.forEach((t, i) => {
     const isDetected = detected.some(d => d.id === t.id);
     console.log(`  ${String(i + 1).padStart(2)}. ${isDetected ? '✅' : '○ '} ${t.name}`);
@@ -873,18 +694,12 @@ async function promptSelectTools(projectDir) {
 
   const answer = await askQuestion('  请选择 (多选用逗号分隔，如 1,3): ');
 
-  // 回车 = 使用检测结果
-  if (!answer && detected.length > 0) {
-    return detected.map(t => t.id);
-  }
+  if (!answer && detected.length > 0) return detected.map(t => t.id);
 
-  // 解析用户输入的编号
   const indices = answer.split(/[,，\s]+/).map(s => parseInt(s, 10)).filter(n => !isNaN(n));
   const selected = [];
   for (const idx of indices) {
-    if (idx >= 1 && idx <= SUPPORTED_TOOLS.length) {
-      selected.push(SUPPORTED_TOOLS[idx - 1].id);
-    }
+    if (idx >= 1 && idx <= SUPPORTED_TOOLS.length) selected.push(SUPPORTED_TOOLS[idx - 1].id);
   }
 
   if (selected.length === 0) {
@@ -895,11 +710,6 @@ async function promptSelectTools(projectDir) {
   return selected;
 }
 
-/**
- * 交互式选择技术栈
- *
- * @returns {Promise<string>} 'vue3' | 'java' | 'all'
- */
 async function promptSelectStack() {
   console.log('━━━ 选择项目技术栈 ━━━\n');
   console.log('  1. 🖥️  前端 (Vue3 + TypeScript + Element Plus)');
@@ -907,7 +717,6 @@ async function promptSelectStack() {
   console.log('  3. 🔗 前后端一起\n');
 
   const answer = await askQuestion('  请选择 [1/2/3]: ');
-
   const map = { '1': 'vue3', '2': 'java', '3': 'all' };
   return map[answer] || 'all';
 }
@@ -921,7 +730,9 @@ function stackLabel(stack) {
   return labels[stack] || stack;
 }
 
-
+// ============================================================
+// CLI 命令实现
+// ============================================================
 
 export async function runInit(projectDir, options = {}) {
   const {
@@ -936,18 +747,9 @@ export async function runInit(projectDir, options = {}) {
   console.log('\n🔧 Harness Engineering 初始化');
   console.log(`   目标目录: ${projectDir}\n`);
 
-  // 1. 多源获取 .harness/ 模板（本包自带 → npx缓存 → npm远端）
+  // 1. 多源获取 .harness/ 模板
   const harnessDir = await getHarnessSourceDir({ verbose });
   if (!harnessDir) {
-    console.error('❌ 无法获取 .harness/ 模板。');
-    console.error('');
-    console.error('   已尝试：');
-    console.error('     1. 本包自带的 .harness/ 目录');
-    console.error('     2. npx 缓存目录');
-    console.error('     3. npm registry 远端下载');
-    console.error('');
-    console.error('   请检查网络连接，或手动安装后重试：');
-    console.error('     npm install -g jsharness && jsharness init');
     process.exit(1);
   }
   if (verbose) console.log(`   📂 Harness 源: ${harnessDir}`);
@@ -973,15 +775,11 @@ export async function runInit(projectDir, options = {}) {
   }
 
   console.log(`\n📋 选中的 AI 工具:`);
-  for (const t of targetTools) {
-    console.log(`   • ${t.name}`);
-  }
+  for (const t of targetTools) console.log(`   • ${t.name}`);
 
   // 3. 交互式选择技术栈
   let stack = requestedStack;
-  if (!stack) {
-    stack = await promptSelectStack();
-  }
+  if (!stack) stack = await promptSelectStack();
   console.log(`\n🏗️  技术栈: ${stackLabel(stack)}\n`);
 
   // 4. 扫描源文件
@@ -1000,27 +798,21 @@ export async function runInit(projectDir, options = {}) {
 
     const outputs = [];
 
-    // 注入 Rules
     if (!skillsOnly && allRuleFiles.length > 0) {
       console.log(`📜 注入规则 (${allRuleFiles.length} 个)...`);
-      const result = transformRules(allRuleFiles, tool.id, { stack });
-      outputs.push(...result.files);
+      outputs.push(...transformRules(allRuleFiles, tool.id, { stack }).files);
     }
 
-    // 注入 Skills
     if (!rulesOnly && allSkillFiles.length > 0) {
       console.log(`⚡ 注入技能 (${allSkillFiles.length} 个)...`);
-      const result = transformSkills(allSkillFiles, tool.id, { stack });
-      outputs.push(...result.files);
+      outputs.push(...transformSkills(allSkillFiles, tool.id, { stack }).files);
     }
 
-    // 写入文件
     const { written, skipped } = injectOutputs(projectDir, outputs, { force, verbose });
-
     summary.push({ tool: tool.name, written, skipped });
   }
 
-  // 6. 初始化 OpenSpec 变更管理目录（内聚在 jsharness 中，无需额外依赖）
+  // 6. 初始化 OpenSpec
   console.log('\n━━━ 初始化 OpenSpec ━━━');
   const openspecResult = initOpenSpec(projectDir, { force, verbose });
   if (openspecResult.created.length > 0) {
@@ -1034,7 +826,7 @@ export async function runInit(projectDir, options = {}) {
   // 7. 输出总结
   console.log('\n═════════════════════════════');
   console.log('✅ 初始化完成！');
-  
+
   for (const s of summary) {
     if (s.written.length > 0) {
       console.log(`\n  [${s.tool}]`);
@@ -1062,40 +854,30 @@ export async function runInit(projectDir, options = {}) {
 
 export function listTools() {
   console.log('\n支持的 AI 编程工具:\n');
-
   for (const tool of SUPPORTED_TOOLS) {
-    const status = tool.detector ? '✅' : '○ ';
-    console.log(`${status}  ${tool.id.padEnd(14)} ${tool.name}`);
+    console.log(`○   ${tool.id.padEnd(14)} ${tool.name}`);
     console.log(`   格式: ${tool.ruleFormat}${tool.skillFormat ? ' + ' + tool.skillFormat : ''}`);
-    console.log(`   说明: ${tool.description}`);
-    console.log('');
+    console.log(`   说明: ${tool.description}\n`);
   }
-
   console.log('使用方法:');
-  console.log('  npx hariness init --tool <id>');
-  console.log('');
+  console.log('  npx jsharness init --tool <id>\n');
 }
 
 export function showStatus(projectDir) {
   console.log('\n📊 Harness 项目状态\n');
 
-  // 检查 .harness 是否存在
   const harnessDir = path.join(projectDir, '.harness');
   const hasHarness = fs.existsSync(harnessDir);
   console.log(`  Harness 源: ${hasHarness ? '✅ 存在' : '❌ 缺失'} (.harness/)`);
 
   if (hasHarness) {
-    const rulesCount = scanHarnessRules(harnessDir, 'all').length;
-    const skillsCount = scanHarnessSkills(harnessDir, 'all').length;
-    console.log(`  规则数量:   ${rulesCount}`);
-    console.log(`  技能数量:   ${skillsCount}`);
+    console.log(`  规则数量:   ${scanHarnessRules(harnessDir, 'all').length}`);
+    console.log(`  技能数量:   ${scanHarnessSkills(harnessDir, 'all').length}`);
   }
 
-  // 检查各工具状态
   const detected = detectTool(projectDir);
   console.log(`  AI 工具:    ${detected.length > 0 ? detected.map(t => t.name).join(', ') : '(未检测到)'}`);
 
-  // 检查已注入的目标文件
   const targets = [
     { name: 'CodeBuddy', path: '.codebuddy/rules/' },
     { name: 'Qoder', path: '.qoder/rules/' },
@@ -1111,54 +893,36 @@ export function showStatus(projectDir) {
 
   console.log('\n  注入状态:');
   for (const t of targets) {
-    const fullPath = path.join(projectDir, t.path);
-    const exists = fs.existsSync(fullPath);
+    const exists = fs.existsSync(path.join(projectDir, t.path));
     console.log(`    ${exists ? '✅' : '○ '} ${t.name.padEnd(12)} ${t.path}`);
   }
 
-  // OpenSpec 状态
   const openspecDir = path.join(projectDir, 'openspec');
   const hasOpenSpec = fs.existsSync(openspecDir);
   console.log(`\n  OpenSpec:    ${hasOpenSpec ? '✅ 已初始化' : '○  未初始化'}`);
   if (hasOpenSpec) {
     const changesDir = path.join(openspecDir, 'changes');
     if (fs.existsSync(changesDir)) {
-      const active = fs.readdirSync(changesDir, { withFileTypes: true })
-        .filter(d => d.isDirectory() && d.name !== 'archive');
+      const active = fs.readdirSync(changesDir, { withFileTypes: true }).filter(d => d.isDirectory() && d.name !== 'archive');
       const archiveDir = path.join(changesDir, 'archive');
-      const archived = fs.existsSync(archiveDir)
-        ? fs.readdirSync(archiveDir, { withFileTypes: true }).filter(d => d.isDirectory()).length
-        : 0;
+      const archived = fs.existsSync(archiveDir) ? fs.readdirSync(archiveDir, { withFileTypes: true }).filter(d => d.isDirectory()).length : 0;
       console.log(`    活跃变更: ${active.length}  归档: ${archived}`);
     }
   }
-
   console.log('');
 }
 
 // ============================================================
-// OpenSpec 内聚初始化（无需额外 npm 依赖，直接创建目录结构）
+// OpenSpec 内聚初始化
 // ============================================================
 
-const OPENSPEC_DIRS = [
-  'openspec',
-  'openspec/changes',
-  'openspec/changes/archive',
-  'openspec/specs',
-];
+const OPENSPEC_DIRS = ['openspec', 'openspec/changes', 'openspec/changes/archive', 'openspec/specs'];
 
 const OPENSPEC_GITIGNORE = `# OpenSpec generated files
 changes/*/dist/
 *.log
 `;
 
-/**
- * 初始化 OpenSpec 目录结构到目标项目
- *
- * @param {string} projectDir - 目标项目根目录
- * @param {object} options - 选项 { force, verbose }
- * @returns {{ created: string[], skipped: string[] }}
- */
 export function initOpenSpec(projectDir, options = {}) {
   const { force = false, verbose = false } = options;
   const created = [];
@@ -1176,30 +940,23 @@ export function initOpenSpec(projectDir, options = {}) {
     if (verbose) console.log(`  ✅ 创建目录: ${dir}/`);
   }
 
-  // .gitkeep 确保空目录可被 git 追踪
   for (const dir of ['openspec/changes/archive', 'openspec/specs']) {
     const gitkeepPath = path.join(projectDir, dir, '.gitkeep');
-    if (!fs.existsSync(gitkeepPath)) {
-      fs.writeFileSync(gitkeepPath, '', 'utf-8');
-    }
+    if (!fs.existsSync(gitkeepPath)) fs.writeFileSync(gitkeepPath, '', 'utf-8');
   }
 
-  // openspec/.gitignore
   const gitignorePath = path.join(projectDir, 'openspec', '.gitignore');
   if (!fs.existsSync(gitignorePath) || force) {
     fs.writeFileSync(gitignorePath, OPENSPEC_GITIGNORE, 'utf-8');
     if (!created.includes('openspec')) created.push('openspec/.gitignore');
-    if (verbose) console.log(`  ✅ 创建文件: openspec/.gitignore`);
   } else {
     skipped.push('openspec/.gitignore');
   }
 
-  // openspec/README.md
   const readmePath = path.join(projectDir, 'openspec', 'README.md');
   if (!fs.existsSync(readmePath) || force) {
     fs.writeFileSync(readmePath, generateOpenSpecReadme(), 'utf-8');
     created.push('openspec/README.md');
-    if (verbose) console.log(`  ✅ 创建文件: openspec/README.md`);
   } else {
     skipped.push('openspec/README.md');
   }
@@ -1233,13 +990,8 @@ openspec/
 ## 命令行操作
 
 \`\`\`bash
-# 查看状态
 npx jsharness status
-
-# 列出活跃变更
 npx jsharness openspec list
-
-# 归档变更
 npx jsharness openspec archive --change "<name>"
 \`\`\`
 
@@ -1247,9 +999,6 @@ npx jsharness openspec archive --change "<name>"
 `;
 }
 
-/**
- * 列出当前项目的 OpenSpec changes
- */
 export function listOpenSpecChanges(projectDir) {
   const changesDir = path.join(projectDir, 'openspec', 'changes');
   if (!fs.existsSync(changesDir)) {
@@ -1257,8 +1006,7 @@ export function listOpenSpecChanges(projectDir) {
     return;
   }
 
-  const entries = fs.readdirSync(changesDir, { withFileTypes: true })
-    .filter(d => d.isDirectory() && d.name !== 'archive');
+  const entries = fs.readdirSync(changesDir, { withFileTypes: true }).filter(d => d.isDirectory() && d.name !== 'archive');
 
   if (entries.length === 0) {
     console.log('\n📋 没有活跃的 OpenSpec 变更\n');
@@ -1281,21 +1029,15 @@ export function listOpenSpecChanges(projectDir) {
 
   const archiveDir = path.join(changesDir, 'archive');
   if (fs.existsSync(archiveDir)) {
-    const archived = fs.readdirSync(archiveDir, { withFileTypes: true })
-      .filter(d => d.isDirectory());
+    const archived = fs.readdirSync(archiveDir, { withFileTypes: true }).filter(d => d.isDirectory());
     if (archived.length > 0) {
       console.log('\n📦 已归档:');
-      for (const entry of archived) {
-        console.log(`  • ${entry.name}`);
-      }
+      for (const entry of archived) console.log(`  • ${entry.name}`);
     }
   }
   console.log('');
 }
 
-/**
- * 归档一个 OpenSpec change
- */
 export function archiveOpenSpecChange(projectDir, changeName) {
   const changesDir = path.join(projectDir, 'openspec', 'changes');
   const sourceDir = path.join(changesDir, changeName);
@@ -1310,5 +1052,3 @@ export function archiveOpenSpecChange(projectDir, changeName) {
   fs.renameSync(sourceDir, archiveDir);
   console.log(`\n✅ 变更 "${changeName}" 已归档到 openspec/changes/archive/${path.basename(archiveDir)}/\n`);
 }
-
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsharness",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Harness Engineering - AI 编程行为工程化管控系统。将 rules/skills/gate/agents 一键注入到 CodeBuddy、Cursor、Copilot 等 AI 工具中。",
   "main": "lib/index.mjs",
   "bin": {