jsharness 1.0.0

package/README.md

@@ -0,0 +1,237 @@
+# Harness Engineering
+
+> **AI 编程行为工程化管控系统** — 一条命令将规则和技能注入到你的 AI 工具中
+
+[![npm version](https://img.shields.io/npm/v/hariness.svg)](https://www.npmjs.com/package/hariness)
+![node](https://img.shields.io/node/%3E%3D18.svg)
+
+## 它是什么
+
+Harness Engineering 是一套**文件化的 AI 编码约束系统**，通过 **Rules（规则）+ Skills（技能）+ Gate（门禁）** 三层机制，确保 AI 在项目中持续产出符合规范的代码。
+
+**本 npm 包解决的核心问题：**
+
+> 当你使用 AI 编程助手（CodeBuddy / Cursor / Copilot / Windsurf 等）时，
+> 如何让 AI **自动遵守你们团队的编码规范、技术栈选择和安全红线？**
+
+## 快速开始
+
+### 30 秒初始化
+
+```bash
+# 在你的项目根目录执行
+npx hariness init
+```
+
+这条命令会：
+
+1. **自动检测** 你使用的 AI 编程工具
+2. **扫描** `.harness/` 下的所有规则和技能
+3. **转换格式** 并写入到对应工具的配置位置
+4. 让你在下一次 AI 对话中**立即生效**
+
+### 指定目标工具
+
+```bash
+# 指定 CodeBuddy
+npx hariness init --tool codebuddy
+
+# 指定 Cursor
+npx hariness init --tool cursor
+
+# 指定 GitHub Copilot  
+npx hariness init --tool copilot
+
+# 指定 Continue (VS Code)
+npx hariness init --tool continue
+
+# 指定 Cline (VS Code)
+npx hariness init --tool cline
+```
+
+### 只注入特定技术栈的规则
+
+```bash
+# 只要 Vue3 前端规则
+npx hariness init --stack vue3
+
+# 只要 Java 后端规则
+npx hariness init --stack java
+
+# 全部（默认）
+npx hariness init --stack all
+```
+
+## 支持的 AI 工具
+
+| 工具 | 注入位置 | 规则 | 技能 |
+|------|---------|------|------|
+| **CodeBuddy** | `.codebuddy/rules/` + `.codebuddy/skills/` | ✅ | ✅ |
+| **Cursor** | `.cursorrules` | ✅ 合并为单文件 | — |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | ✅ | — |
+| **Windsurf** | `.windsurfrules` | ✅ XML 格式 | — |
+| **Continue** | `continue.config.json` | ✅ JSON 格式 | — |
+| **Cline** | `.clinerules` | ✅ | — |
+
+查看完整列表：
+```bash
+npx hariness list-tools
+```
+
+## 工作原理
+
+```
+用户运行: npx hariness init
+           ↓
+    1️⃣ 扫描 .harness/rules/*.md 和 .harness/skills/*.md
+           ↓
+    2️⃣ 自动检测当前项目的 AI 工具
+           ↓
+    3️⃣ 将 Markdown 规则转换为目标工具的原生格式
+           ↓
+    4️⃣ 写入对应配置位置
+    
+    例: .harness/rules/global/coding-standard.md
+        ↓ 转换为 CodeBuddy 格式
+        → .codebuddy/rules/coding-standard.md
+        
+    例: .harness/rules/project/frontend-vue3.md  
+        ↓ 转换为 Cursor 格式
+        → 追加到 .cursorrules
+```
+
+## 系统架构
+
+Harness 包含以下层级，全部可通过本包一键注入：
+
+### 三层约束机制
+
+```
+┌─────────────────────────────────────────┐
+│  🔴 Rules (软约束)                      │  Markdown 声明式规范
+│  → "什么不能做"                          │  AI 自觉遵守
+├─────────────────────────────────────────┤
+│  🟡 Skills (半硬约束)                   │  步骤化操作手册
+│  → "具体怎么做"                          │  AI 按步骤执行
+├─────────────────────────────────────────┤
+│  🚧 Gate Scripts (硬约束)               │  可执行检查脚本
+│  → "不通过就拦截"                        │  PASS / FAIL
+└─────────────────────────────────────────┘
+```
+
+### 内置内容（默认包含）
+
+#### 规则层 (Rules)
+
+| 文件 | 说明 |
+|------|------|
+| `rules/global/coding-standard.md` | 通用编码规范（命名/导入/注释） |
+| `rules/global/commit-convention.md` | Commit 信息格式规范 |
+| `rules/global/security-baseline.md` | 安全红线（XSS/CSRF/注入） |
+| `rules/project/frontend-vue3.md` | Vue3 前端技术栈规则 |
+| `rules/project/java-backend.md` | Java Spring Boot 后端规则 |
+| `rules/project/web-specific.md` | Web 应用通用规则 |
+
+#### 技能层 (Skills)
+
+| 文件 | 说明 |
+|------|------|
+| `skills/vue-frontend-build.md` | Vue3 + Vite 构建全流程 |
+| `skills/java-build.md` | Maven + JUnit5 构建全流程 |
+| `skills/lint-check.md` | ESLint / Checkstyle 配置 |
+| `skills/code-review.md` | 代码审查清单（双技术栈） |
+| `skills/test-unit.md` | 单元测试（Vitest + JUnit5） |
+
+#### 门禁层 (Gate)
+
+| 文件 | 说明 |
+|------|------|
+| `gate/checks/build-gates.js` | 构建门禁路由器 |
+| `gate/checks/build-gates-frontend.js` | 前端门禁（npm/tsc/lint） |
+| `gate/checks/build-gates-java.js` | 后端门禁（mvn compile/test） |
+| `gate/checks/security-quality.js` | 安全质量检查 |
+
+#### 角色 (Agents) & 流程 (Workflow)
+
+7 个专业 Agent（PM/需求分析/方案设计/闸门/开发/CR/测试）+ 标准协作流程。
+
+## 高级用法
+
+```bash
+# 覆盖已有配置（谨慎使用）
+npx hariness init --force
+
+# 只注入规则，不注入技能
+npx hariness init --rules-only
+
+# 只注入技能，不注入规则
+npx hariness init --skills-only
+
+# 查看详细输出
+npx hariness init -v
+
+# 查看当前状态
+npx hariness status
+```
+
+## 作为 SDK 使用
+
+```javascript
+import { 
+  detectTool, 
+  scanHarnessRules, 
+  transformRules,
+  injectOutputs 
+} from 'hariness';
+
+// 检测 AI 工具
+const tools = detectTool('/path/to/project');
+
+// 获取规则文件
+const rules = scanHarnessRules('/path/to/.harness', 'vue3');
+
+// 转换为目标格式
+const outputs = transformRules(rules, 'codebuddy');
+
+// 写入项目
+injectOutputs('/path/to/project', outputs);
+```
+
+## 开发指南
+
+### 本地开发
+
+```bash
+git clone <repo>
+cd hariness
+npm install
+npm run init      # 初始化测试
+```
+
+### 自定义规则
+
+1. 在 `.harness/rules/` 下添加 `.md` 文件
+2. 运行 `npx hariness init --force` 更新注入
+3. 规则会自动被所有适配器支持
+
+### 添加新工具适配器
+
+在 `lib/index.mjs` 的 `RULE_TRANSFORMERS` 中新增一个 key 即可。每种工具只需实现一个函数，输入是规则文件列表，输出是 `{ format, files: [{ relativePath, content }] }`。
+
+## 技术栈说明
+
+本包内置的默认规则基于以下技术栈（可在初始化后自行修改）：
+
+- **前端**: Vue 3 + Vite + TypeScript + Pinia + Element Plus
+- **后端**: Spring Boot 3.2 + JDK21 + MyBatis-Plus + Nacos
+
+如需其他技术栈，修改 `.harness/` 下的对应文件即可。
+
+## License
+
+ISC
+
+## 相关链接
+
+- [操作手册](./Harness使用手册.md)
+- [OpenSpec 变更管理](./openspec/)

package/bin/jsharness.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+/**
+ * jsharness CLI
+ * 
+ * Usage:
+ *   npx jsharness init              # 初始化（自动检测 AI 工具）
+ *   npx jsharness init --tool codebuddy  # 指定工具
+ *   npx jsharness init --stack vue3      # 指定技术栈
+ *   npx jsharness list-tools        # 列出支持的工具
+ *   npx jsharness status            # 查看当前状态
+ */
+
+import { createRequire } from 'module';
+import { program } from 'commander';
+
+const require = createRequire(import.meta.url);
+
+// 通过包名引用主库（npm 安装后兼容）
+const { runInit, listTools, showStatus } = await import('jsharness');
+
+program
+  .name('jsharness')
+  .description('Harness Engineering - AI 编程行为工程化管控系统')
+  .version(require('jsharness/package.json').version);
+
+program
+  .command('init')
+  .description('初始化 Harness 到当前项目的 AI 工具中')
+  .option('-t, --tool <name>', '指定目标 AI 工具')
+  .option('-s, --stack <name>', '指定技术栈 (vue3/java/all)', 'all')
+  .option('--rules-only', '只注入规则，不注入技能')
+  .option('--skills-only', '只注入技能，不注入规则')
+  .option('--force', '覆盖已有配置')
+  .option('-v, --verbose', '显示详细输出')
+  .action((opts) => runInit(process.cwd(), opts));
+
+program
+  .command('list-tools')
+  .description('列出所有支持的 AI 工具及适配器状态')
+  .action(() => listTools());
+
+program
+  .command('status')
+  .description('查看当前项目 Harness 初始化状态')
+  .action(() => showStatus(process.cwd()));
+
+program.parse(process.argv);
+
+// 无参数时默认执行 init
+if (!process.argv.slice(2).length) {
+  await runInit(process.cwd(), {});
+}