jsharness 1.8.2 → 1.10.0

package/files/analyze-requirements.md

@@ -0,0 +1,197 @@
+# 需求分析师技能
+
+## 核心职责
+
+作为需求分析师，你的核心职责是：
+
+1. 理解并拆解客户需求
+2. 创建需求规格文档
+
+文档要求：
+
+1. 文档内容参照提供的模板
+
+## 文件管理
+
+### 目录结构
+
+```
+.cospec/{功能名}/
+└── requirements.md          # 需求文档
+```
+
+> **{功能名}目录请使用英文**
+
+### 阶段进度跟踪
+
+#### 进度跟踪
+
+- **任务开始时的第一步**: 使用todo_list工具列出任务清单，此操作必须在其它任何动作之前
+- 通过任务清单的勾选状态跟踪实现进度
+
+#### 任务清单内容
+
+todo_list中必须包含以下操作，**请勿遗漏任何一个步骤**:
+
+1. 创建需求文档
+2. **内容检查**：当需求文档生成后，请立即开始检查需求文档中的内容，明确是否存在【约束】栏目中不允许的内容，如果有请一定要删除，否则会带来重大灾难
+3. 确认结果：当文档生成后，必须使用 ask_followup_question 工具询问是否满足用户要求，并提示可补充信息或继续："示例提示：'当前已完成【需求明确】。如需修改可直接在对话框中输入修改要求，或直接在文档中修改。如已确认请点击：<suggest>继续</suggest>'"
+4. 总结任务：所有任务完成后，使用attempt_completion工具做简单总结
+
+## 工作流程约束
+
+### 1. 需求分析阶段
+
+**强制检查清单：**
+
+- [x] 判断`.cospec/{功能名}/`目录下，requirements.md文档是否存在，如果存在则读取，如果没有需要先创建
+
+**我的工作:**
+
+1. 创建 `.cospec/{功能名}/requirements.md` 文档
+2. 基于您的描述生成初始需求，**不会先问一系列连续问题**
+3. 与您反复讨论直到需求清晰
+
+**重要约束:**
+
+- 必须等待您的明确认可才能进入下一阶段
+- 如果您提供反馈，我必须修改并再次请求确认
+- 必须继续反馈-修订循环直到获得明确批准
+- 不会假设用户偏好或需求
+- 总是明确询问
+
+**完成标志:**
+
+- 您明确表示满意当前需求（如"是的"、"批准"、"看起来不错"等）
+
+**需求澄清规范：**
+
+- 必须识别所有不明确的需求点
+- 对每个需求提出至少3个澄清问题
+- 记录所有假设和约束条件
+- 提供替代解决方案建议
+
+**文档化要求：**
+
+- 创建`.cospec/{功能名}/requirements.md`包含：
+  - 功能需求清单（按优先级排序）
+  - 用户故事和用例
+- 更新`.cospec/{功能名}/requirements.md`
+- 编写需求前先判断需求的复杂程度，如果是简单需求，可以简化文档内容，不必严格按照模板规范，避免简单需求复杂化
+
+**需求文档中不包含：**
+
+- 非功能性需求
+- 测试需求
+- 部署需求
+
+## 输出规范
+
+### 文档标准
+
+#### 1. 需求规格文档
+
+- 使用标准模板
+- 包含版本控制信息
+- 每个需求有唯一标识符
+- 可追溯性矩阵
+
+## 交互约束
+
+### 与客户交互
+
+- 使用结构化提问获取需求
+- 提供可视化原型建议
+- 解释技术选择的权衡
+- 给出实施优先级建议
+
+### 与开发团队协作
+
+- 提供清晰的实施指南
+- 定义接口规范
+- 制定测试策略
+- 建立代码审查标准
+
+## 约束检查
+
+每次完成任务后，必须验证：
+
+1. 是否所有需求都被文档化？
+2. 技术方案是否经过充分论证？
+3. 架构设计是否考虑了扩展性？
+4. 文档是否易于理解和实施？
+5. 是否建立了有效的反馈机制？
+
+## 需求分析模板
+
+### 需求规格说明书模板
+
+```markdown
+# 需求规格说明书 - [项目名称]
+
+## 1. 项目概述
+
+### 1.1 背景
+
+[描述项目产生的背景和原因]
+
+### 1.2 目标
+
+[明确项目的业务目标和技术目标]
+
+### 1.3 范围
+
+[定义项目边界，包含和不包含的内容]
+
+## 2. 功能需求
+
+### 2.1 用户角色
+
+| 角色名称 | 描述 | 权限 |
+|----------|------|------|
+| [角色1]  | [描述] | [权限列表] |
+
+### 2.2 功能清单
+
+#### 2.2.1 [功能模块1]
+
+- **需求ID**: FR-001
+- **需求描述**: [详细描述]
+- **优先级**: [高/中/低]
+- **验收标准**: [可测量的标准]
+- **依赖关系**: [依赖的其他需求]
+
+## 3. 用户故事
+
+### 3.1 [用户故事标题]
+
+**作为** [用户角色]
+**我想要** [功能描述]
+**以便于** [业务价值]
+
+**验收条件**:
+
+- [条件1]
+- [条件2]
+
+## 4. 数据需求
+
+### 4.1 数据实体
+
+- [实体1]: [描述]
+- [实体2]: [描述]
+
+### 4.2 数据流
+
+[描述数据如何在系统中流动]
+
+## 5. 假设和依赖
+
+### 5.1 假设
+
+- [假设1]: [描述]
+
+### 5.2 依赖
+
+- [依赖1]: [描述]
+```

package/lib/index.mjs

@@ -3,6 +3,7 @@
  *
  * 多适配器架构：检测 AI 工具 → 转换规则格式 → 注入到对应位置
  *
+ * v1.10.0: 新增 5 个 OpenSpec Skills（openspec-explore/propose/apply/archive/skill-creator），Commands 精简为 Skill 委托模式
  * v1.8.0: 四桶分离架构（rules/skills/commands/agents），多源获取策略确保 100% 可用
  *   1. import.meta.url 定位本包 .harness/ （最快）
  *   2. process.argv[1] 反推包根目录（npx 直接执行时）
@@ -370,6 +371,7 @@ const SKILL_TRANSFORMERS = {
       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 if (lowerName.includes('openspec')) content += `trigger_type: manual\n`;
       else content += `trigger_type: manual\n`;
       content += `---\n\n${body}`;
       outputs.push({ relativePath: `.claude/skills/${skillName}/SKILL.md`, content, source: file.path });
@@ -1362,30 +1364,6 @@ export function scanHarnessSkills(harnessDir, stackFilter) {
   return results;
 }
 
-/**
- * 扫描项目根目录下的 files/ 目录
- * 这些是外部 SKILL 源文件（如 architecture-designer.md），
- * 需要被注入到目标 AI 工具对应的 skills 目录中
- */
-export function scanHarnessFiles(projectDir) {
-  const filesDir = path.join(projectDir, 'files');
-  const results = [];
-  if (!fs.existsSync(filesDir)) return results;
-
-  const entries = fs.readdirSync(filesDir).filter(f => f.endsWith('.md'));
-  for (const entry of entries) {
-    const filePath = path.join(filesDir, entry);
-    const skillName = entry.replace(/\.md$/, '').replace(/SKILL$/, '');
-    results.push({
-      name: skillName,
-      path: filePath,
-      category: 'file-skill',
-      relativePath: `files/${entry}`,
-    });
-  }
-  return results;
-}
-
 /**
  * 扫描 .harness/commands/ 目录下的命令定义
  * 支持两种结构:
@@ -1672,14 +1650,8 @@ export async function runInit(projectDir, options = {}) {
   const allCommandFiles = scanHarnessCommands(harnessDir, stack);
   const allSubagentFiles = scanHarnessSubagents(harnessDir);
 
-  // 5.5 扫描 files/ 目录（外部 SKILL 源文件）
-  const externalSkillFiles = scanHarnessFiles(projectDir);
-
   if (verbose) {
     console.log(`📋 扫描结果: ${allRuleFiles.length} 个规则, ${allSkillFiles.length} 个技能, ${allCommandFiles.length} 个命令, ${allSubagentFiles.length} 个角色\n`);
-    if (externalSkillFiles.length > 0) {
-      console.log(`📋 外部 SKILL 文件: ${externalSkillFiles.length} 个\n`);
-    }
   }
 
   // 判断是否有 *-only 过滤
@@ -1702,7 +1674,7 @@ export async function runInit(projectDir, options = {}) {
     }
 
     // Skills 桶
-    const allSkills = [...allSkillFiles, ...externalSkillFiles];
+    const allSkills = allSkillFiles;
     if ((!hasAnyOnly || skillsOnly) && allSkills.length > 0) {
       if (tool.skillFormat) {
         console.log(`⚡ 注入技能 (${allSkills.length} 个)...`);
@@ -1780,6 +1752,17 @@ export async function runInit(projectDir, options = {}) {
     console.log(`  ⏭  跳过 ${openspecResult.skipped.length} 项 (已存在)`);
   }
 
+  // 7.5 初始化 Harness doc 目录（originRequirements + ttspec）
+  console.log('\n━━━ 初始化 Harness 文档目录 ━━━');
+  const harnessDocResult = initHarnessDoc(projectDir, { force, verbose });
+  if (harnessDocResult.created.length > 0) {
+    console.log(`  ✅ 创建 ${harnessDocResult.created.length} 项:`);
+    harnessDocResult.created.forEach(f => console.log(`     - ${f}`));
+  }
+  if (harnessDocResult.skipped.length > 0) {
+    console.log(`  ⏭  跳过 ${harnessDocResult.skipped.length} 项 (已存在)`);
+  }
+
   // 8. 输出总结
   console.log('\n═════════════════════════════');
   console.log('✅ 初始化完成！');
@@ -1903,6 +1886,15 @@ export function showStatus(projectDir) {
 
 const OPENSPEC_DIRS = ['openspec', 'openspec/changes', 'openspec/changes/archive', 'openspec/specs'];
 
+// Harness doc 子目录（需求入口 + ttspec 变更管理）
+const HARNESS_DOC_DIRS = [
+  '.harness/doc/originRequirements',
+  '.harness/doc/ttspec',
+  '.harness/doc/ttspec/change',
+  '.harness/doc/ttspec/change/archive',
+  '.harness/doc/ttspec/specs',
+];
+
 const OPENSPEC_GITIGNORE = `# OpenSpec generated files
 changes/*/dist/
 *.log
@@ -1949,6 +1941,130 @@ export function initOpenSpec(projectDir, options = {}) {
   return { created, skipped };
 }
 
+/**
+ * 初始化 .harness/doc/ 子目录（originRequirements + ttspec）
+ */
+export function initHarnessDoc(projectDir, options = {}) {
+  const { force = false, verbose = false } = options;
+  const created = [];
+  const skipped = [];
+
+  for (const dir of HARNESS_DOC_DIRS) {
+    const fullPath = path.join(projectDir, dir);
+    if (fs.existsSync(fullPath)) {
+      if (verbose) console.log(`  ⏭  目录已存在: ${dir}/`);
+      skipped.push(dir);
+      continue;
+    }
+    fs.mkdirSync(fullPath, { recursive: true });
+    created.push(dir);
+    if (verbose) console.log(`  ✅ 创建目录: ${dir}/`);
+  }
+
+  // 在空目录中添加 .gitkeep
+  for (const dir of HARNESS_DOC_DIRS) {
+    const gitkeepPath = path.join(projectDir, dir, '.gitkeep');
+    if (!fs.existsSync(gitkeepPath)) fs.writeFileSync(gitkeepPath, '', 'utf-8');
+  }
+
+  // originRequirements README
+  const originReadmePath = path.join(projectDir, '.harness/doc/originRequirements', 'README.md');
+  if (!fs.existsSync(originReadmePath) || force) {
+    fs.writeFileSync(originReadmePath, generateOriginRequirementsReadme(), 'utf-8');
+    created.push('.harness/doc/originRequirements/README.md');
+  } else {
+    skipped.push('.harness/doc/originRequirements/README.md');
+  }
+
+  // ttspec README
+  const ttspecReadmePath = path.join(projectDir, '.harness/doc/ttspec', 'README.md');
+  if (!fs.existsSync(ttspecReadmePath) || force) {
+    fs.writeFileSync(ttspecReadmePath, generateTtspecReadme(), 'utf-8');
+    created.push('.harness/doc/ttspec/README.md');
+  } else {
+    skipped.push('.harness/doc/ttspec/README.md');
+  }
+
+  return { created, skipped };
+}
+
+function generateOriginRequirementsReadme() {
+  return `# 原始需求文件目录
+
+本目录用于存放所有原始需求文件，是 Harness 需求分析的统一入口。
+
+## 文件命名规则
+
+格式：\`{YYYY-MM-DD}-{kebab-case-title}.md\`
+
+示例：
+- \`2026-05-22-user-avatar-upload.md\`
+- \`2026-06-15-order-export-feature.md\`
+
+## 最小内容要求
+
+每个需求文件至少包含以下两个章节：
+
+\`\`\`markdown
+# 需求标题
+
+## 背景
+
+描述需求的业务背景、当前痛点和动机。
+
+## 期望
+
+描述期望达到的效果或目标。
+\`\`\`
+
+## 工作流
+
+1. 用户在此目录下创建需求文件
+2. PM Agent 扫描发现新文件
+3. PM 在 \`.harness/doc/ttspec/change/\` 下创建对应 change
+4. 需求分析师按 explore → propose → prd 三步执行分析
+
+> 本目录由 Harness Engineering 系统管理。
+`;
+}
+
+function generateTtspecReadme() {
+  return `# ttspec — 变更规格管理目录
+
+本目录用于存放 Harness 流程中 OpenSpec 的产出物，包括变更管理（change）和能力规格（specs）。
+
+## 目录结构
+
+\`\`\`
+.harness/doc/ttspec/
+├── change/                    # 变更目录（每个需求对应一个子目录）
+│   ├── archive/               # 已归档的变更
+│   └── {change-name}/         # 活跃变更
+│       ├── explore-notes.md   # explore 阶段产出
+│       ├── proposal.md        # propose 阶段产出
+│       ├── design.md          # 设计决策
+│       ├── specs/             # 能力规格
+│       └── tasks.md           # 实施任务列表
+└── specs/                     # 全局能力规格
+    └── {capability}/
+        └── spec.md
+\`\`\`
+
+## 变更命名规则
+
+change 名称从原始需求文件名派生：去除日期前缀，保留 kebab-case 标题。
+
+示例：需求文件 \`2026-05-22-user-avatar-upload.md\` → change 名 \`user-avatar-upload\`
+
+## 与 openspec/ 的关系
+
+- \`openspec/\` — OpenSpec CLI 原生操作目录（历史数据保持不动）
+- \`.harness/doc/ttspec/\` — Harness 流程中的变更管理产出目录
+
+> 本目录由 Harness Engineering 系统管理。
+`;
+}
+
 function generateOpenSpecReadme() {
   return `# OpenSpec 变更管理
 
@@ -1967,10 +2083,11 @@ openspec/
 
 在 AI 对话中使用 OpenSpec skills：
 
-- **openspec-propose** — 创建新变更提案
-- **openspec-explore** — 探索和澄清需求
-- **openspec-apply-change** — 实施变更任务
-- **openspec-archive-change** — 归档已完成变更
+- **openspec-explore** — 需求深度探索
+- **openspec-propose** — 创建结构化提案
+- **openspec-apply** — 实施变更任务
+- **openspec-archive** — 归档已完成变更
+- **openspec-skill-creator** — 创建新的 Harness Skill
 
 ## 命令行操作
 

package/package.json

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

package/.harness/skills/build/SKILL.md

@@ -1,199 +0,0 @@
----
-name: build
-description: 项目构建技能（已废弃，重定向至 vue-frontend-build 或 java-build）— 通用构建参考/历史存档
-alwaysApply: false
-enabled: true
----
-
-# 项目构建技能 (build)
-
-> ⚠️ **已废弃 (DEPRECATED)** — `harness-java-fullchain` change | 2026-05-21
-> 
-> 本文件已被技术栈专属构建技能替代。**请根据项目类型使用对应的 Skill：**
-> 
-> | 项目类型 | 推荐使用 Skill | 说明 |
-> |---------|---------------|------|
-> | **Vue3 + Vite 前端** | `skills/vue-frontend-build.md` | 完整的 Vite/TS/ESLint/Vitest/构建优化 |
-> | **Spring Boot (JDK21) 后端** | `skills/java-build.md` | 完整的 Maven/测试/JaCoCo/Docker/CI 流程 |
-> 
-> ---
-> 以下内容保留作为**通用参考/历史存档**，workflow 已切换为按技术栈条件引用上述专属 Skill。
-
----
-
-> **执行角色**: 开发实现 Agent / CI Pipeline
-> **触发时机**: 代码修改完成后、提交 PR 前、CI 构建时
-
----
-
-## 前端构建流程
-
-### Step 1: 依赖安装
-```bash
-# 使用 pnpm（推荐）或 npm
-pnpm install
-
-# 检查依赖安全
-npm audit --audit-level=moderate
-```
-
-**通过标准**: 安装无 error，无 HIGH/CRITICAL 安全漏洞
-
-### Step 2: 类型检查
-```bash
-# TypeScript 严格模式类型检查
-npx tsc --noEmit
-
-# 或使用项目配置的命令
-npm run type-check
-```
-
-**通过标准**: 零 type error
-
-### Step 3: 代码格式化检查
-```bash
-# ESLint 检查
-npx eslint . --ext .ts,.vue,.js --max-warnings 0
-
-# Prettier 格式化验证
-npx prettier --check "src/**/*.{ts,vue,js,css,md}"
-```
-
-**通过标准**: 零 warning（白名单规则除外）
-
-### Step 4: 生产构建
-```bash
-# Vue3 + Vite（推荐）
-npm run build
-
-# 或具体命令
-vite build         # Vite
-```
-
-### Step 5: 构建产物分析（可选但推荐）
-```bash
-# 分析打包体积
-npx @next/analyze   # Next.js
-npx rollup-plugin-visualizer  # Vite/Webpack
-
-# 通过标准：
-# - 首屏 JS ≤ 200KB (gzip)
-# - 单 chunk ≤ 100KB (gzip)
-```
-
-**通过标准**: 构建成功，退出码 0，产物体积在限制内
-
----
-
-## 后端编译流程
-
-### Step 1: 编译检查
-```bash
-# TypeScript 后端（如 NestJS）
-npx tsc --noEmit
-
-# Java (Maven)
-mvn compile
-
-# Go
-go build ./...
-```
-
-**通过标准**: 编译零错误
-
-### Step 2: Lint 检查
-```bash
-# NestJS / Node.js
-npx eslint . --ext .ts
-
-# Java
-mvn checkstyle:check
-
-# Go
-golangci-lint run ./...
-```
-
-**通过标准**: 零 warning（可配置的白名单）
-
----
-
-## TypeScript 类型检查专项
-
-### 配置要求
-
-```jsonc
-// tsconfig.json 必须启用
-{
-  "compilerOptions": {
-    "strict": true,
-    "noImplicitAny": true,
-    "strictNullChecks": true,
-    "strictFunctionTypes": true,
-    "noUncheckedIndexedAccess": true
-  }
-}
-```
-
-### any 类型使用规范
-
-| 场景 | 是否允许 | 要求 |
-|------|---------|------|
-| 新增代码 | 禁止 | 必须定义明确类型 |
-| 遗留系统重构 | 有条件允许 | 必须注释 `// TODO(#issue): replace with proper type` |
-| 第三方类型缺失 | 允许 | 封装一层并定义接口 |
-| JSON.parse 结果 | 禁止 | 使用泛型或 Zod 校验 |
-
----
-
-## 构建失败处理策略
-
-```
-构建失败
-  │
-  ├── 依赖安装失败 → 检查 lockfile 一致性 / 清缓存重试 / 检查网络
-  │
-  ├── 类型错误 → 定位错误位置 → 修复类型 → 重新运行
-  │               └── 如果是第三方库类型问题 → 添加 type declaration
-  │
-  ├── Lint 错误 → 运行 `--fix` 自动修复 → 手动修复剩余项
-  │
-  ├── 生产构建失败 → 检查 build log → 定位问题 → 修复
-  │                   └── 常见原因：动态 import 路径错误 / 环境变量缺失
-  │
-  └── 体积超限 → 分析 bundle → 排查大依赖 → 懒加载 / tree-shaking
-```
-
-## 构建结果输出模板
-
-```yaml
-build_result:
-  timestamp: "2026-05-20T22:00:00Z"
-  status: pass | fail
-  duration_seconds: 45
-  
-  frontend:
-    typecheck:
-      errors: 0
-      warnings: 0
-    lint:
-      errors: 0
-      warnings: 0
-    build:
-      success: true
-      output_size_kb:
-        total: 180
-        gzip: 62
-        
-  backend:
-    compile:
-      success: true
-    lint:
-      errors: 0
-      warnings: 2
-      
-  security_audit:
-    critical: 0
-    high: 0
-    moderate: 3
-    low: 5
-```