@pzy560117/codex-harness 0.1.4 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/setup-pm.md

@@ -0,0 +1,83 @@
+---
+description: 配置您首选的包管理器（npm/pnpm/yarn/bun）
+disable-model-invocation: true
+---
+
+# 包管理器设置
+
+配置您为此项目或全局偏好的包管理器。
+
+## 使用方式
+
+```bash
+# Detect current package manager
+node scripts/setup-package-manager.js --detect
+
+# Set global preference
+node scripts/setup-package-manager.js --global pnpm
+
+# Set project preference
+node scripts/setup-package-manager.js --project bun
+
+# List available package managers
+node scripts/setup-package-manager.js --list
+```
+
+## 检测优先级
+
+在确定使用哪个包管理器时，会按以下顺序检查：
+
+1. **环境变量**：`CLAUDE_PACKAGE_MANAGER`
+2. **项目配置**：`.claude/package-manager.json`
+3. **package.json**：`packageManager` 字段
+4. **锁文件**：package-lock.json、yarn.lock、pnpm-lock.yaml 或 bun.lockb 的存在
+5. **全局配置**：`~/.claude/package-manager.json`
+6. **回退方案**：第一个可用的包管理器 (pnpm > bun > yarn > npm)
+
+## 配置文件
+
+### 全局配置
+
+```json
+// ~/.claude/package-manager.json
+{
+  "packageManager": "pnpm"
+}
+```
+
+### 项目配置
+
+```json
+// .claude/package-manager.json
+{
+  "packageManager": "bun"
+}
+```
+
+### package.json
+
+```json
+{
+  "packageManager": "pnpm@8.6.0"
+}
+```
+
+## 环境变量
+
+设置 `CLAUDE_PACKAGE_MANAGER` 以覆盖所有其他检测方法：
+
+```bash
+# Windows (PowerShell)
+$env:CLAUDE_PACKAGE_MANAGER = "pnpm"
+
+# macOS/Linux
+export CLAUDE_PACKAGE_MANAGER=pnpm
+```
+
+## 运行检测
+
+要查看当前包管理器检测结果，请运行：
+
+```bash
+node scripts/setup-package-manager.js --detect
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/skill-create.md

@@ -0,0 +1,176 @@
+---
+name: skill-create
+description: 分析本地Git历史以提取编码模式并生成SKILL.md文件。Skill Creator GitHub应用的本地版本。
+allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"]
+---
+
+# /skill-create - 本地技能生成
+
+分析你的仓库的 git 历史，以提取编码模式并生成 SKILL.md 文件，用于向 Claude 传授你团队的实践方法。
+
+## 使用方法
+
+```bash
+/skill-create                    # Analyze current repo
+/skill-create --commits 100      # Analyze last 100 commits
+/skill-create --output ./skills  # Custom output directory
+/skill-create --instincts        # Also generate instincts for continuous-learning-v2
+```
+
+## 功能说明
+
+1. **解析 Git 历史** - 分析提交记录、文件更改和模式
+2. **检测模式** - 识别重复出现的工作流程和约定
+3. **生成 SKILL.md** - 创建有效的 Claude Code 技能文件
+4. **可选创建 Instincts** - 用于 continuous-learning-v2 系统
+
+## 分析步骤
+
+### 步骤 1：收集 Git 数据
+
+```bash
+# Get recent commits with file changes
+git log --oneline -n ${COMMITS:-200} --name-only --pretty=format:"%H|%s|%ad" --date=short
+
+# Get commit frequency by file
+git log --oneline -n 200 --name-only | grep -v "^$" | grep -v "^[a-f0-9]" | sort | uniq -c | sort -rn | head -20
+
+# Get commit message patterns
+git log --oneline -n 200 | cut -d' ' -f2- | head -50
+```
+
+### 步骤 2：检测模式
+
+寻找以下模式类型：
+
+| 模式 | 检测方法 |
+|---------|-----------------|
+| **提交约定** | 对提交消息进行正则匹配 (feat:, fix:, chore:) |
+| **文件协同更改** | 总是同时更改的文件 |
+| **工作流序列** | 重复的文件更改模式 |
+| **架构** | 文件夹结构和命名约定 |
+| **测试模式** | 测试文件位置、命名、覆盖率 |
+
+### 步骤 3：生成 SKILL.md
+
+输出格式：
+
+```markdown
+---
+name: {repo-name}-patterns
+description: 从 {repo-name} 提取的编码模式
+version: 1.0.0
+source: local-git-analysis
+analyzed_commits: {count}
+---
+
+# {Repo Name} 模式
+
+## 提交规范
+{detected commit message patterns}
+
+## 代码架构
+{detected folder structure and organization}
+
+## 工作流
+{detected repeating file change patterns}
+
+## 测试模式
+{detected test conventions}
+
+```
+
+### 步骤 4：生成 Instincts（如果使用 --instincts）
+
+用于 continuous-learning-v2 集成：
+
+```yaml
+---
+id: {repo}-commit-convention
+trigger: "when writing a commit message"
+confidence: 0.8
+domain: git
+source: local-repo-analysis
+---
+
+# Use Conventional Commits
+
+## Action
+Prefix commits with: feat:, fix:, chore:, docs:, test:, refactor:
+
+## Evidence
+- Analyzed {n} commits
+- {percentage}% follow conventional commit format
+```
+
+## 示例输出
+
+在 TypeScript 项目上运行 `/skill-create` 可能会产生：
+
+```markdown
+---
+name: my-app-patterns
+description: Coding patterns from my-app repository
+version: 1.0.0
+source: local-git-analysis
+analyzed_commits: 150
+---
+
+# My App 模式
+
+## 提交约定
+
+该项目使用 **约定式提交**：
+- `feat:` - 新功能
+- `fix:` - 错误修复
+- `chore:` - 维护任务
+- `docs:` - 文档更新
+
+## 代码架构
+
+```
+
+src/
+├── components/     # React 组件 (PascalCase.tsx)
+├── hooks/          # 自定义钩子 (use\*.ts)
+├── utils/          # 工具函数
+├── types/          # TypeScript 类型定义
+└── services/       # API 和外部服务
+
+```
+## 工作流
+
+### 添加新组件
+1. 创建 `src/components/ComponentName.tsx`
+2. 在 `src/components/__tests__/ComponentName.test.tsx` 中添加测试
+3. 从 `src/components/index.ts` 导出
+
+### 数据库迁移
+1. 修改 `src/db/schema.ts`
+2. 运行 `pnpm db:generate`
+3. 运行 `pnpm db:migrate`
+
+## 测试模式
+
+- 测试文件：`__tests__/` 目录或 `.test.ts` 后缀
+- 覆盖率目标：80%+
+- 框架：Vitest
+```
+
+## GitHub 应用集成
+
+对于高级功能（10k+ 提交、团队共享、自动 PR），请使用 [Skill Creator GitHub 应用](https://github.com/apps/skill-creator)：
+
+* 安装: [github.com/apps/skill-creator](https://github.com/apps/skill-creator)
+* 在任何议题上评论 `/skill-creator analyze`
+* 接收包含生成技能的 PR
+
+## 相关命令
+
+* `/instinct-import` - 导入生成的 instincts
+* `/instinct-status` - 查看已学习的 instincts
+* `/evolve` - 将 instincts 聚类为技能/代理
+
+***
+
+*属于 [Everything Claude Code](https://github.com/affaan-m/everything-claude-code)*

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/skill-health.md

@@ -0,0 +1,54 @@
+---
+name: skill-health
+description: 显示技能组合健康仪表板，包含图表和分析
+command: true
+---
+
+# 技能健康仪表盘
+
+展示投资组合中所有技能的综合健康仪表盘，包含成功率走势图、故障模式聚类、待处理修订和版本历史。
+
+## 实现
+
+在仪表盘模式下运行技能健康 CLI：
+
+```bash
+ECC_ROOT="${CLAUDE_PLUGIN_ROOT:-$(node -e "var p=require('path'),f=require('fs'),h=require('os').homedir(),d=p.join(h,'.claude'),q=p.join('scripts','lib','utils.js');if(!f.existsSync(p.join(d,q))){try{var b=p.join(d,'plugins','cache','everything-claude-code');for(var o of f.readdirSync(b))for(var v of f.readdirSync(p.join(b,o))){var c=p.join(b,o,v);if(f.existsSync(p.join(c,q))){d=c;break}}}catch(x){}}console.log(d)")}"
+node "$ECC_ROOT/scripts/skills-health.js" --dashboard
+```
+
+仅针对特定面板：
+
+```bash
+ECC_ROOT="${CLAUDE_PLUGIN_ROOT:-$(node -e "var p=require('path'),f=require('fs'),h=require('os').homedir(),d=p.join(h,'.claude'),q=p.join('scripts','lib','utils.js');if(!f.existsSync(p.join(d,q))){try{var b=p.join(d,'plugins','cache','everything-claude-code');for(var o of f.readdirSync(b))for(var v of f.readdirSync(p.join(b,o))){var c=p.join(b,o,v);if(f.existsSync(p.join(c,q))){d=c;break}}}catch(x){}}console.log(d)")}"
+node "$ECC_ROOT/scripts/skills-health.js" --dashboard --panel failures
+```
+
+获取机器可读输出：
+
+```bash
+ECC_ROOT="${CLAUDE_PLUGIN_ROOT:-$(node -e "var p=require('path'),f=require('fs'),h=require('os').homedir(),d=p.join(h,'.claude'),q=p.join('scripts','lib','utils.js');if(!f.existsSync(p.join(d,q))){try{var b=p.join(d,'plugins','cache','everything-claude-code');for(var o of f.readdirSync(b))for(var v of f.readdirSync(p.join(b,o))){var c=p.join(b,o,v);if(f.existsSync(p.join(c,q))){d=c;break}}}catch(x){}}console.log(d)")}"
+node "$ECC_ROOT/scripts/skills-health.js" --dashboard --json
+```
+
+## 使用方法
+
+```
+/skill-health                    # 完整仪表盘视图
+/skill-health --panel failures   # 仅故障聚类面板
+/skill-health --json             # 机器可读的 JSON 输出
+```
+
+## 操作步骤
+
+1. 使用 --dashboard 标志运行 skills-health.js 脚本
+2. 向用户显示输出
+3. 如果有任何技能出现衰退，高亮显示并建议运行 /evolve
+4. 如果有待处理修订，建议进行审查
+
+## 面板
+
+* **成功率 (30天)** — 显示每个技能每日成功率的走势图
+* **故障模式** — 聚类故障原因并显示水平条形图
+* **待处理修订** — 等待审查的修订提案
+* **版本历史** — 每个技能的版本快照时间线

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/tdd.md

@@ -0,0 +1,330 @@
+---
+description: 强制执行测试驱动开发工作流。首先搭建接口，生成测试，然后实现最小化代码以通过测试。确保 80%+ 覆盖率。
+---
+
+# TDD 命令
+
+此命令调用 **tdd-guide** 代理来强制执行测试驱动开发方法。
+
+## 此命令的作用
+
+1. **搭建接口** - 首先定义类型/接口
+2. **首先生成测试** - 编写失败的测试（红）
+3. **实现最小化代码** - 编写刚好足够的代码以通过测试（绿）
+4. **重构** - 改进代码，同时保持测试通过（重构）
+5. **验证覆盖率** - 确保 80%+ 的测试覆盖率
+
+## 何时使用
+
+在以下情况下使用 `/tdd`：
+
+* 实现新功能时
+* 添加新函数/组件时
+* 修复错误时（首先编写重现错误的测试）
+* 重构现有代码时
+* 构建关键业务逻辑时
+
+## 工作原理
+
+tdd-guide 代理将：
+
+1. 为输入/输出**定义接口**
+2. **编写将会失败的测试**（因为代码尚不存在）
+3. **运行测试**并验证它们因正确的原因而失败
+4. **编写最小化实现**以使测试通过
+5. **运行测试**并验证它们通过
+6. **重构**代码，同时保持测试通过
+7. **检查覆盖率**，如果低于 80% 则添加更多测试
+
+## TDD 循环
+
+```
+RED → GREEN → REFACTOR → REPEAT
+
+RED:      编写一个失败测试
+GREEN:    编写通过测试的最简代码
+REFACTOR: 改进代码，保持测试通过
+REPEAT:   开始下一个功能/场景
+```
+
+## 使用示例
+
+````
+User: /tdd I need a function to calculate market liquidity score
+
+Agent (tdd-guide):
+# TDD Session: Market Liquidity Score Calculator
+
+## Step 1: Define Interface (SCAFFOLD)
+
+```typescript
+// lib/liquidity.ts
+export interface MarketData {
+  totalVolume: number
+  bidAskSpread: number
+  activeTraders: number
+  lastTradeTime: Date
+}
+
+export function calculateLiquidityScore(market: MarketData): number {
+  // TODO: Implementation
+  throw new Error('Not implemented')
+}
+````
+
+## 步骤 2：编写失败的测试（红）
+
+```typescript
+// lib/liquidity.test.ts
+import { calculateLiquidityScore } from './liquidity'
+
+describe('calculateLiquidityScore', () => {
+  it('should return high score for liquid market', () => {
+    const market = {
+      totalVolume: 100000,
+      bidAskSpread: 0.01,
+      activeTraders: 500,
+      lastTradeTime: new Date()
+    }
+
+    const score = calculateLiquidityScore(market)
+
+    expect(score).toBeGreaterThan(80)
+    expect(score).toBeLessThanOrEqual(100)
+  })
+
+  it('should return low score for illiquid market', () => {
+    const market = {
+      totalVolume: 100,
+      bidAskSpread: 0.5,
+      activeTraders: 2,
+      lastTradeTime: new Date(Date.now() - 86400000) // 1 day ago
+    }
+
+    const score = calculateLiquidityScore(market)
+
+    expect(score).toBeLessThan(30)
+    expect(score).toBeGreaterThanOrEqual(0)
+  })
+
+  it('should handle edge case: zero volume', () => {
+    const market = {
+      totalVolume: 0,
+      bidAskSpread: 0,
+      activeTraders: 0,
+      lastTradeTime: new Date()
+    }
+
+    const score = calculateLiquidityScore(market)
+
+    expect(score).toBe(0)
+  })
+})
+```
+
+## 步骤 3：运行测试 - 验证失败
+
+```bash
+npm test lib/liquidity.test.ts
+
+FAIL lib/liquidity.test.ts
+  ✕ should return high score for liquid market (2 ms)
+    Error: Not implemented
+
+1 test failed, 0 passed
+```
+
+PASS: 测试按预期失败。准备实施。
+
+## 步骤 4：实现最小化代码（绿）
+
+```typescript
+// lib/liquidity.ts
+export function calculateLiquidityScore(market: MarketData): number {
+  // Handle zero volume edge case
+  if (market.totalVolume === 0) {
+    return 0
+  }
+
+  // Calculate component scores (0-100 scale)
+  const volumeScore = Math.min(market.totalVolume / 1000, 100)
+  const spreadScore = Math.max(100 - (market.bidAskSpread * 1000), 0)
+  const traderScore = Math.min(market.activeTraders / 10, 100)
+
+  // Recent activity bonus
+  const hoursSinceLastTrade = (Date.now() - market.lastTradeTime.getTime()) / (1000 * 60 * 60)
+  const recencyScore = Math.max(100 - (hoursSinceLastTrade * 10), 0)
+
+  // Weighted average
+  const score = (
+    volumeScore * 0.4 +
+    spreadScore * 0.3 +
+    traderScore * 0.2 +
+    recencyScore * 0.1
+  )
+
+  return Math.min(Math.max(score, 0), 100) // Clamp to 0-100
+}
+```
+
+## 步骤 5：运行测试 - 验证通过
+
+```bash
+npm test lib/liquidity.test.ts
+
+PASS lib/liquidity.test.ts
+  ✓ should return high score for liquid market (3 ms)
+  ✓ should return low score for illiquid market (2 ms)
+  ✓ should handle edge case: zero volume (1 ms)
+
+3 tests passed
+```
+
+PASS: 所有测试通过！
+
+## 步骤 6：重构（改进）
+
+```typescript
+// lib/liquidity.ts - Refactored with constants and better readability
+const WEIGHTS = {
+  VOLUME: 0.4,
+  SPREAD: 0.3,
+  TRADERS: 0.2,
+  RECENCY: 0.1,
+} as const
+
+const SCALE_FACTORS = {
+  VOLUME: 1000,
+  SPREAD: 1000,
+  TRADERS: 10,
+  RECENCY_PENALTY: 10,
+} as const
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max)
+}
+
+export function calculateLiquidityScore(market: MarketData): number {
+  if (market.totalVolume === 0) return 0
+
+  const volumeScore = Math.min(market.totalVolume / SCALE_FACTORS.VOLUME, 100)
+  const spreadScore = clamp(100 - (market.bidAskSpread * SCALE_FACTORS.SPREAD), 0, 100)
+  const traderScore = Math.min(market.activeTraders / SCALE_FACTORS.TRADERS, 100)
+
+  const hoursSinceLastTrade = (Date.now() - market.lastTradeTime.getTime()) / (1000 * 60 * 60)
+  const recencyScore = clamp(100 - (hoursSinceLastTrade * SCALE_FACTORS.RECENCY_PENALTY), 0, 100)
+
+  const weightedScore =
+    volumeScore * WEIGHTS.VOLUME +
+    spreadScore * WEIGHTS.SPREAD +
+    traderScore * WEIGHTS.TRADERS +
+    recencyScore * WEIGHTS.RECENCY
+
+  return clamp(weightedScore, 0, 100)
+}
+```
+
+## 步骤 7：验证测试仍然通过
+
+```bash
+npm test lib/liquidity.test.ts
+
+PASS lib/liquidity.test.ts
+  ✓ should return high score for liquid market (3 ms)
+  ✓ should return low score for illiquid market (2 ms)
+  ✓ should handle edge case: zero volume (1 ms)
+
+3 tests passed
+```
+
+PASS: 重构完成，测试仍然通过！
+
+## 步骤 8：检查覆盖率
+
+```bash
+npm test -- --coverage lib/liquidity.test.ts
+
+File           | % Stmts | % Branch | % Funcs | % Lines
+---------------|---------|----------|---------|--------
+liquidity.ts   |   100   |   100    |   100   |   100
+
+Coverage: 100% PASS: (Target: 80%)
+```
+
+PASS: TDD 会话完成！
+
+```
+## TDD 最佳实践
+
+**应做：**
+- PASS: 先写测试，再写实现
+- PASS: 运行测试并确认失败，再实现功能
+- PASS: 编写最少代码使测试通过
+- PASS: 仅在测试通过后进行重构
+- PASS: 添加边界情况和错误场景
+- PASS: 目标覆盖率 80% 以上（关键代码 100%）
+
+**不应做：**
+- FAIL: 先写实现再写测试
+- FAIL: 每次更改后跳过运行测试
+- FAIL: 一次性编写过多代码
+- FAIL: 忽略失败的测试
+- FAIL: 测试实现细节（应测试行为）
+- FAIL: 过度模拟（优先使用集成测试）
+
+## 应包含的测试类型
+
+**单元测试**（函数级别）：
+- 正常路径场景
+- 边界情况（空值、null、最大值）
+- 错误条件
+- 边界值
+
+**集成测试**（组件级别）：
+- API 端点
+- 数据库操作
+- 外部服务调用
+- 包含钩子的 React 组件
+
+**端到端测试**（使用 `/e2e` 命令）：
+- 关键用户流程
+- 多步骤流程
+- 全栈集成
+
+## 覆盖率要求
+
+- 所有代码**最低 80%**
+- **必须达到 100%** 的代码：
+  - 财务计算
+  - 认证逻辑
+  - 安全关键代码
+  - 核心业务逻辑
+
+## 重要说明
+
+**强制要求**：测试必须在实现之前编写。TDD 循环是：
+
+1. **红** - 编写失败的测试
+2. **绿** - 实现功能使测试通过
+3. **重构** - 改进代码
+
+切勿跳过红阶段。切勿在测试之前编写代码。
+
+## 与其他命令的集成
+
+- 首先使用 `/plan` 来了解要构建什么
+- 使用 `/tdd` 进行带测试的实现
+- 如果出现构建错误，请使用 `/build-fix`
+- 使用 `/code-review` 审查实现
+- 使用 `/test-coverage` 验证覆盖率
+
+## 相关代理
+
+此命令调用由 ECC 提供的 `tdd-guide` 代理。
+
+相关的 `tdd-workflow` 技能也随 ECC 捆绑提供。
+
+对于手动安装，源文件位于：
+- `agents/tdd-guide.md`
+- `skills/tdd-workflow/SKILL.md`
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/test-coverage.md

@@ -0,0 +1,69 @@
+# 测试覆盖率
+
+分析测试覆盖率，识别缺口，并生成缺失的测试以达到 80%+ 的覆盖率。
+
+## 步骤 1：检测测试框架
+
+| 指标 | 覆盖率命令 |
+|-----------|-----------------|
+| `jest.config.*` 或 `package.json` jest | `npx jest --coverage --coverageReporters=json-summary` |
+| `vitest.config.*` | `npx vitest run --coverage` |
+| `pytest.ini` / `pyproject.toml` pytest | `pytest --cov=src --cov-report=json` |
+| `Cargo.toml` | `cargo llvm-cov --json` |
+| `pom.xml` 与 JaCoCo | `mvn test jacoco:report` |
+| `go.mod` | `go test -coverprofile=coverage.out ./...` |
+
+## 步骤 2：分析覆盖率报告
+
+1. 运行覆盖率命令
+2. 解析输出（JSON 摘要或终端输出）
+3. 列出**覆盖率低于 80%** 的文件，按最差情况排序
+4. 对于每个覆盖率不足的文件，识别：
+   * 未测试的函数或方法
+   * 缺失的分支覆盖率（if/else、switch、错误路径）
+   * 增加分母的死代码
+
+## 步骤 3：生成缺失的测试
+
+对于每个覆盖率不足的文件，按以下优先级生成测试：
+
+1. **快乐路径** — 使用有效输入的核心功能
+2. **错误处理** — 无效输入、缺失数据、网络故障
+3. **边界情况** — 空数组、null/undefined、边界值（0、-1、MAX\_INT）
+4. **分支覆盖率** — 每个 if/else、switch case、三元运算符
+
+### 测试生成规则
+
+* 将测试放在源代码旁边：`foo.ts` → `foo.test.ts`（或遵循项目惯例）
+* 使用项目中现有的测试模式（导入风格、断言库、模拟方法）
+* 模拟外部依赖项（数据库、API、文件系统）
+* 每个测试都应该是独立的 — 测试之间没有共享的可变状态
+* 描述性地命名测试：`test_create_user_with_duplicate_email_returns_409`
+
+## 步骤 4：验证
+
+1. 运行完整的测试套件 — 所有测试必须通过
+2. 重新运行覆盖率 — 验证改进
+3. 如果仍然低于 80%，针对剩余的缺口重复步骤 3
+
+## 步骤 5：报告
+
+显示前后对比：
+
+```
+覆盖率报告
+──────────────────────────────
+文件                   变更前  变更后
+src/services/auth.ts   45%     88%
+src/utils/validation.ts 32%    82%
+──────────────────────────────
+总计：               67%     84%  PASS:
+```
+
+## 重点关注领域
+
+* 具有复杂分支的函数（高圈复杂度）
+* 错误处理程序和 catch 块
+* 整个代码库中使用的工具函数
+* API 端点处理程序（请求 → 响应流程）
+* 边界情况：null、undefined、空字符串、空数组、零、负数