@dommaker/harness 0.13.0 → 0.13.2

package/src/tools/definitions/std/README.md

@@ -0,0 +1,350 @@
+# Skills - 能力单元层
+
+Skills 是工作流引擎的**能力单元层**，定义可复用的可调用能力（原名为 Steps，v0.8 重命名为 Skills）。
+
+---
+
+## 核心定义
+
+**Skill = 能力单元，可调用 Agent / Tools / 脚本，用户可直接触发**
+
+| 特征 | 说明 |
+|------|------|
+| 执行方式 | Agent / Tool / Script / Builtin |
+| Agent 调用 | ✅ 可选 |
+| 复用范围 | 跨项目复用 |
+| 用户可直接调用 | ✅ 支持（通过命令）|
+
+---
+
+## 命名说明
+
+- **v0.7 及之前**: 叫 `Step` - 执行单元
+- **v0.8 及之后**: 叫 `Skill` - 能力单元（用户可直接调用）
+- 工作流内部的执行步骤仍叫 `Step`，概念不变
+
+| 特征 | 说明 |
+|------|------|
+| 执行方式 | Agent / Tool / Script / Builtin |
+| Agent 调用 | ✅ 可选 |
+| 复用范围 | 项目内复用 |
+| 创建文件 | ✅ 可选（可内联定义） |
+
+---
+
+## Step 类型
+
+### 1. Agent Step（智能决策）
+
+调用 Agent 进行智能决策和代码生成。
+
+```yaml
+# steps/quality/run-tests.yml
+name: run-tests
+agent: codex              # 调用 Agent
+temperature: 0.2
+
+prompt: |
+  运行项目测试并报告结果...
+```
+
+**适用场景**：
+- 需要 AI 理解上下文
+- 需要智能决策
+- 代码生成/修改
+
+---
+
+### 2. Tool Step（复用能力）
+
+引用 Tools 层定义的能力。
+
+```yaml
+# Workflow 中引用
+steps:
+  - id: start-container
+    tool: docker/run      # 引用 tools/docker/run.yml
+    input:
+      image_name: "myapp"
+```
+
+**适用场景**：
+- 复用已定义的 Tool
+- 跨项目共享能力
+
+---
+
+### 3. Script Step（一次性脚本）
+
+在 Workflow 中内联脚本。
+
+```yaml
+steps:
+  - id: check-files
+    script: |
+      #!/bin/bash
+      ls -la
+      echo "Done"
+```
+
+**适用场景**：
+- 一次性脚本
+- 无需复用
+- 简单操作
+
+---
+
+### 4. Builtin Step（内置处理器）
+
+调用运行时内置处理器。
+
+```yaml
+steps:
+  - id: generate-report
+    step: evolution/report-gap    # 内置处理器
+    input:
+      execution_id: "xxx"
+```
+
+**适用场景**：
+- 高频调用
+- 需要高性能
+- 核心功能
+
+---
+
+## 目录结构
+
+```
+skills/
+├── quality/             # 质量相关
+│   ├── run-tests.yml    # 运行测试（agent）
+│   └── lint.yml         # 代码检查
+│
+├── evolution/           # 进化相关
+│   ├── report-gap.yml   # 生成 Gap Report（builtin）
+│   ├── prioritize.yml   # 优先级排序（builtin）
+│   └── implement.yml    # 实现建议（agent）
+│
+├── governance/          # 治理相关
+│   ├── multi-stance-review.yml
+│   └── audit.yml
+│
+├── analysis/            # 分析相关
+│   ├── detect-context.yml
+│   └── parse-code.yml
+│
+├── design/              # 设计相关
+│   ├── generate-spec.yml # 生成 Spec 约束文档
+│
+└── ...
+```
+
+---
+
+## Skill 文件格式
+
+```yaml
+# skills/<category>/<name>.yml
+id: unique-id           # 唯一标识 (可选，默认从路径生成)
+name: Skill 名称        # 人类可读名称
+description: 详细描述   # Skill 做什么
+category: category-name # 分类
+version: 1.0.0
+
+# 开放调用配置（用户可直接调用）
+openclaw:
+  userInvocable: true   # 是否允许用户直接调用
+  command: "!command"  # 触发命令
+  emoji: "🔍"           # 显示 emoji
+
+# 关键词（用于意图匹配）
+keywords: ["分析", "架构", "关键词"]
+
+# 默认工作流（用户调用时自动执行）
+defaultWorkflow: wf-analyze
+
+# Agent 配置（可选）
+agent: codex
+temperature: 0.3
+
+# 可用工具（agent 类型时）
+tools:
+  - file-read
+  - file-write
+  - bash
+
+# 输入定义
+inputs:
+  - name: param1
+    type: string
+    required: true
+    description: 参数说明
+
+# 输出定义
+outputs:
+  - name: result1
+    type: string
+    description: 输出说明
+
+# Prompt（agent 类型时）
+prompt: |
+  执行任务...
+  
+  ## 输入
+  {{param1}}
+
+# 或执行配置（builtin 类型时）
+execute:
+  type: builtin
+  handler: category/handler-name
+```
+
+---
+
+## 与 Tools 的边界
+
+### 判断标准
+
+```
+需要跨项目复用？
+    │
+    ├── 是 → 创建 Tool 文件（tools/xxx.yml）
+    │
+    └── 否 → 在 Workflow 中用 script step
+
+需要 Agent 智能决策？
+    │
+    ├── 是 → 创建 Step 文件（agent 类型）
+    │
+    └── 否 → 用 Tool 或 script step
+```
+
+### 示例对比
+
+| 场景 | 用 Tool | 用 Step |
+|------|:-------:|:-------:|
+| 运行 Docker 容器 | ✅ docker/run | - |
+| 浏览器操作 | ✅ browser/automate | - |
+| 运行测试（需 AI 判断） | - | ✅ quality/run-tests |
+| 分析代码（需 AI 理解） | - | ✅ analysis/parse-code |
+| 简单脚本（一次性） | - | script step |
+
+---
+
+## 在 Workflow 中使用
+
+### 引用 Step 文件
+
+```yaml
+# workflows/wf-evolution.yml
+steps:
+  - id: prioritize
+    step: evolution/prioritize    # 引用 steps/evolution/prioritize.yml
+    input:
+      project_path: "/path/to/project"
+```
+
+### 内联定义
+
+```yaml
+# workflows/xxx.yml
+steps:
+  # 引用 Tool
+  - id: start
+    tool: docker/run
+    input:
+      image_name: "myapp"
+  
+  # 内联脚本
+  - id: check
+    script: |
+      curl http://localhost:3000/health
+  
+  # 引用 Step 文件
+  - id: test
+    step: quality/run-tests
+    input:
+      project_path: "${inputs.project_path}"
+  
+  # 调用 Agent
+  - id: fix
+    agent: codex
+    prompt: |
+      修复发现的错误...
+```
+
+---
+
+## 设计原则
+
+### 1. 可复用性
+
+Step 文件应该是可复用的执行单元，不绑定特定项目。
+
+```yaml
+# ✅ 好的设计：参数化
+inputs:
+  - name: project_path
+    type: path
+    required: true
+
+# ❌ 坏的设计：硬编码
+script: |
+  cd /fixed/path/to/project
+```
+
+### 2. 单一职责
+
+每个 Step 文件只做一件事。
+
+### 3. 明确输入输出
+
+```yaml
+inputs:
+  - name: project_path
+    type: path
+    required: true
+
+outputs:
+  - name: test_results
+    type: object
+```
+
+---
+
+## Skill vs Tool vs Workflow vs Step
+
+| 概念 | 职责 | Agent | 用户可调用 | 文件 |
+|------|------|:-----:|:---------:|------|
+| **Tool** | 纯脚本能力 | ❌ | - | tools/xxx.yml |
+| **Skill** | 可调用能力单元 | ✅ 可选 | ✅ | skills/xxx.yml |
+| **Workflow** | 流程编排 | - | ✅ | workflows/xxx.yml |
+| **Step** | 工作流内部执行步骤 | - | - | 内联在 Workflow 中 |
+
+**层级关系：**
+
+```
+Skill（能力单元层）
+    │
+    ├── 可被用户直接调用
+    │   ↓
+    └── 触发 Workflow（编排层）
+        │
+        ├── Step 执行（执行单元）
+        │   ├── agent 类型 → 调用 Agent
+        │   ├── tool 引用 → 调用 Tool
+        │   └── builtin → 内置处理器
+        │
+        ├── Tool 引用（复用能力）
+        │
+        └── script step（一次性脚本）
+```
+
+---
+
+## 相关文档
+
+- [Tools 能力层](../tools/README.md)
+- [Workflow 编排](../workflows/README.md)
+- [Skill 开发指南](../docs/skill-development-guide.md)

package/src/tools/definitions/std/analysis/analyze-codebase.yml

@@ -0,0 +1,72 @@
+# analyze-codebase.yml
+name: analyze-codebase
+stage: plan
+description: 分析代码库，生成知识图谱
+agent: codex
+temperature: 0.3
+
+tools:
+  - file-read
+  - file-write
+
+prompt: |
+  你是代码分析专家。分析代码库并生成知识图谱。
+  
+  {{input}}
+  
+  ## 任务
+  
+  ### 1. 扫描代码文件
+  
+  ```bash
+  find . -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" | grep -v node_modules | grep -v dist | head -100
+  ```
+  
+  ### 2. 分析代码结构
+  
+  识别：
+  - 入口文件
+  - 核心模块
+  - 依赖关系
+  - 配置文件
+  
+  ### 3. 生成知识图谱
+  
+  创建 `knowledge-graph.json`：
+  ```json
+  {
+    "nodes": [
+      {"id": "src/index.ts", "type": "entry", "label": "主入口"},
+      {"id": "src/api", "type": "module", "label": "API 模块"}
+    ],
+    "edges": [
+      {"from": "src/index.ts", "to": "src/api", "type": "imports"}
+    ],
+    "summary": {
+      "language": "TypeScript",
+      "framework": "Express",
+      "totalFiles": 42,
+      "totalDeps": 15
+    }
+  }
+  ```
+  
+  ## 原则
+  
+  - 关注核心文件，忽略琐碎
+  - 识别关键依赖
+  - 总结项目架构
+
+inputs:
+  - name: scope
+    type: string
+    default: "."
+    description: 分析范围
+  
+  - name: exclude
+    type: array
+    default: ["node_modules", "dist", "coverage", ".git", "build"]
+    description: 排除目录
+
+outputs:
+  - knowledge-graph.json

package/src/tools/definitions/std/analysis/analyze-diff.yml

@@ -0,0 +1,182 @@
+name: analyze-diff
+stage: plan
+description: |
+  分析 Git diff 影响范围（智能版本）。
+  
+  通过 fingerprint 工具区分变更级别：
+  - STRUCTURAL: 结构性变更（函数签名、类结构、导入变化）
+  - COSMETIC: 表面变更（注释、格式化）
+  - NONE: 无变更
+  
+  核心功能：
+  - 智能跳过表面变更分析
+  - 变更的组件识别
+  - 受影响的下游组件
+  - 架构层级影响
+  - 风险评估
+  
+  用途：
+  - 代码审查前置分析（节省 30-50% 时间）
+  - 测试范围确定
+  - 发布影响评估
+
+agent: codex
+timeout: 300  # 5 分钟
+
+# 集成的工具
+tools:
+  - code/fingerprint
+
+inputs:
+  - name: project_path
+    type: string
+    required: true
+    description: 项目根路径
+    
+  - name: base_ref
+    type: string
+    required: false
+    default: "main"
+    description: 基准分支或 commit
+    
+  - name: head_ref
+    type: string
+    required: false
+    default: "HEAD"
+    description: 目标分支或 commit
+    
+  - name: knowledge_graph_path
+    type: string
+    required: false
+    description: 知识图谱文件路径（默认 .agent/knowledge-graph.json）
+
+outputs:
+  - name: changed_files
+    type: array
+    description: 变更文件列表
+    
+  - name: changed_nodes
+    type: array
+    description: 变更的知识图谱节点
+    
+  - name: affected_nodes
+    type: array
+    description: 受影响的下游节点
+    
+  - name: affected_layers
+    type: array
+    description: 涉及的架构层级
+    
+  - name: risk_assessment
+    type: object
+    description: 风险评估结果
+    
+  - name: report
+    type: string
+    description: Markdown 格式的分析报告
+
+prompt: |
+  分析项目 {{project_path}} 的 Git diff 影响范围。
+  
+  ## Step 0: 智能变更检测（fingerprint）
+  
+  对每个变更文件执行结构指纹分析：
+  ```bash
+  # 获取变更文件
+  CHANGED_FILES=$(git diff --name-only {{base_ref}}...{{head_ref}})
+  
+  # 对每个文件检测变更级别
+  for FILE in $CHANGED_FILES; do
+    fingerprint.sh "$FILE" "{{project_path}}" "{{base_ref}}"
+  done
+  ```
+  
+  根据变更级别决定分析策略：
+  - **STRUCTURAL**: 执行完整影响分析
+  - **COSMETIC**: 跳过深度分析，仅记录格式变更
+  - **NONE**: 跳过该文件
+  
+  ## Step 1: 获取变更文件列表
+  
+  ```bash
+  # 只分析 STRUCTURAL 变更
+  git diff --name-only {{base_ref}}...{{head_ref}}
+  ```
+  
+  ## Step 2: 加载知识图谱
+  
+  - 路径：{{knowledge_graph_path}} 或 .agent/knowledge-graph.json
+  - 如果不存在，需要先运行 wf-analyze 生成
+  
+  ## Step 3: 映射变更文件到知识图谱节点
+  
+  - 识别变更的组件（函数、类、模块）
+  - 追踪下游依赖关系
+  - 确定受影响范围
+  
+  ## Step 4: 架构层级分析
+  
+  - 识别涉及的层级（如：presentation、business、data）
+  - 判断是否跨层变更
+  
+  ## Step 5: 风险评估
+  
+  - 高复杂度组件变更
+  - 跨层级影响
+  - 大范围下游影响
+  - 新增/未映射文件
+  
+  ## 输出格式
+  
+  生成结构化的影响分析报告，包含：
+  - 变更级别统计（STRUCTURAL/COSMETIC/NONE）
+  - 变更组件清单
+  - 受影响组件清单
+  - 架构层级影响
+  - 风险等级和建议
+  
+  ## 示例输出
+  
+  ```markdown
+  # Diff Analysis: my-project
+  
+  ## Change Level Summary
+  
+  | Level | Count | Files |
+  |-------|-------|-------|
+  | STRUCTURAL | 3 | auth.ts, user.ts, api.ts |
+  | COSMETIC | 2 | utils.ts (格式), config.ts (注释) |
+  | NONE | 0 | - |
+  
+  ## Changed Components (STRUCTURAL only)
+  
+  - **UserService** (class) — 用户认证服务
+    - File: `src/services/auth.ts`
+    - Complexity: complex
+    - Change: 新增 logout 方法
+  
+  ## Affected Components
+  
+  这些组件连接到变更代码，可能需要注意：
+  
+  - **LoginComponent** (function) — 登录表单
+  - **AuthMiddleware** (function) — 认证中间件
+  
+  ## Affected Layers
+  
+  - **presentation**: 前端展示层
+  - **business**: 业务逻辑层
+  
+  ## Risk Assessment
+  
+  - **High complexity**: 1 个复杂组件变更: UserService
+  - **Cross-layer impact**: 变更跨越 2 个架构层级
+  - **Wide blast radius**: 5 个组件受下游影响
+  ```
+
+retry:
+  max_attempts: 2
+  backoff: exponential
+  initial_delay: 5000
+
+version: "1.0.0"

package/src/tools/definitions/std/analysis/analyze-git-diff.yml

@@ -0,0 +1,70 @@
+# analyze-git-diff.yml
+name: analyze-git-diff
+stage: plan
+description: 分析 Git 变更
+agent: codex
+temperature: 0.2
+
+tools:
+  - file-read
+  - git-diff
+
+prompt: |
+  你是 Git 分析专家。分析代码变更内容。
+  
+  {{input}}
+  
+  ## 任务
+  
+  ### 1. 获取变更
+  
+  ```bash
+  git diff --name-only HEAD~1 2>/dev/null || echo "no git"
+  git diff HEAD~1 2>/dev/null | head -200
+  ```
+  
+  ### 2. 分析变更类型
+  
+  分类变更：
+  - **功能新增**：新文件、新函数
+  - **Bug 修复**：小范围修改
+  - **重构**：文件移动、重命名
+  - **文档**：*.md 文件
+  - **配置**：*.json, *.yml
+  
+  ### 3. 输出变更报告
+  
+  创建 `git-diff-report.json`：
+  ```json
+  {
+    "files": ["src/api.ts", "src/utils.ts"],
+    "changes": [
+      {"file": "src/api.ts", "type": "modified", "lines": 15}
+    ],
+    "summary": {
+      "added": 20,
+      "removed": 5,
+      "files": 2
+    }
+  }
+  ```
+  
+  ## 原则
+  
+  - 关注有意义的变化
+  - 识别潜在的破坏性变更
+  - 生成简洁摘要
+
+inputs:
+  - name: baseRef
+    type: string
+    default: "HEAD~1"
+    description: Git 基准引用
+  
+  - name: headRef
+    type: string
+    default: "HEAD"
+    description: Git 目标引用
+
+outputs:
+  - git-diff-report.json