OpenHarness - 完整学习教程

教程级别： 从零到一 预计学习时间： 8-12 小时 前置知识： Python 基础、命令行操作、基本 Git 使用、LLM API 概念（Prompt/Completion） 基于版本： OpenHarness v0.1.0（2026-04-01 发布）

环境搭建指南

系统要求

• 操作系统： macOS、Linux 或 Windows（WSL 推荐）
• Python： 3.10 或更高版本
• 包管理器： uv（Python 高性能包管理器）
• Node.js： 18+（可选，仅用于 React 终端 UI）
• LLM API Key： 至少一个（Anthropic、DeepSeek、OpenAI 等）

安装步骤

# 第 1 步：安装 uv 包管理器（如果尚未安装）
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# 验证 uv 安装
uv --version

# 第 2 步：克隆 OpenHarness 仓库
git clone https://github.com/HKUDS/OpenHarness.git
cd OpenHarness

# 第 3 步：安装项目依赖（包含开发依赖）
uv sync --extra dev

# 第 4 步：配置 API Key（以下任选一种）

# 方式 A：使用 Anthropic Claude（默认）
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# 方式 B：使用 Moonshot/Kimi（Anthropic 兼容格式）
export ANTHROPIC_BASE_URL="https://api.moonshot.cn/anthropic"
export ANTHROPIC_API_KEY="your_kimi_api_key"
export ANTHROPIC_MODEL="kimi-k2.5"

# 方式 C：使用 DeepSeek（OpenAI 兼容格式）
export OPENHARNESS_API_FORMAT=openai
export OPENAI_API_KEY="your_deepseek_key"
export OPENHARNESS_BASE_URL="https://api.deepseek.com"
export OPENHARNESS_MODEL="deepseek-chat"

# 方式 D：使用本地 Ollama（完全离线）
# 先安装并启动 Ollama：https://ollama.com
ollama pull qwen3:8b
export OPENHARNESS_API_FORMAT=openai
export OPENAI_API_KEY="ollama"
export OPENHARNESS_BASE_URL="http://localhost:11434/v1"
export OPENHARNESS_MODEL="qwen3:8b"

验证安装

# 激活虚拟环境后启动 OpenHarness
source .venv/bin/activate
oh --help

预期输出：

Usage: oh [OPTIONS] COMMAND [ARGS]

OpenHarness - Open Agent Harness

Options:
  -p, --print         非交互模式，直接输出到 stdout
  -m, --model         指定模型名称
  --api-format        API 格式：anthropic（默认）或 openai
  --output-format     输出格式：text、json、stream-json
  --permission-mode   权限模式：default、auto、plan
  -d, --debug         启用调试模式
  ...

Commands:
  mcp      MCP 服务器管理
  plugin   插件管理
  auth     认证管理

# 快速验证：发送一条测试提示
oh -p "Say hello in 3 languages"

预期输出（因模型不同会有差异）：

Hello! / 你好！ / こんにちは！

第一部分：入门篇

1.1 理解 Agent Harness 的核心概念

概念讲解：

在传统的大语言模型（LLM）使用中，你输入一段文本，模型返回一段文本。模型只能"说话"，不能"做事"——它不能读写文件、不能执行命令、不能搜索网络。

Agent Harness（智能体驾驶系统） 的核心思想是：在模型外面包裹一层基础设施，为模型提供"手"（工具执行）、"眼"（上下文观察）、"记忆"（持久化存储）和"安全边界"（权限控制）。

用公式表达：

Harness = Tools（工具）+ Knowledge（知识）+ Observation（观察）+ Action（行动）+ Permissions（权限）

核心理念："The model is the agent. The code is the harness."（模型是 Agent，代码是 Harness）

模型决定 做什么（what），Harness 决定 怎么做（how）。

代码示例：

# 最简单的使用——一条命令让 Agent 分析当前目录
cd ~/my-project
oh -p "List all Python files in this directory and count total lines of code"

执行结果：

I found 12 Python files with a total of 3,456 lines of code:

1. main.py (234 lines)
2. utils.py (189 lines)
3. models/user.py (156 lines)
...

练习题： 1. 使用 oh -p 命令让 Agent 列出你当前目录下的所有文件，并按大小排序 2. 让 Agent 解释当前目录中某个 Python 文件的功能

1.2 交互式会话与基本命令

概念讲解：

上一节我们用了 -p 参数进行非交互式的单次对话。现在我们进入 交互式会话模式，这是 OpenHarness 的主要使用方式。

在交互模式下，你可以： - 输入自然语言提示与 Agent 对话 - 使用 / 开头的斜杠命令执行特定操作 - Agent 可以调用工具来读写文件、执行命令等 - 每次工具调用前都会请求你的权限确认（Default 模式下）

代码示例：

# 启动交互式会话
oh

# 进入后你会看到 OpenHarness 的欢迎界面
# 然后可以输入任何提示

常用斜杠命令一览：

# 在 OpenHarness 交互式会话中输入以下命令

/help                    # 查看所有可用命令
/permissions             # 切换权限模式（default/auto/plan）
/commit                  # 使用 commit skill 创建 Git 提交
/plan                    # 进入计划模式（禁止写入操作）
/resume                  # 恢复之前的会话
/clear                   # 清空当前对话上下文

执行结果（/help 命令）：

Available Commands:
  /help          Show this help message
  /commit        Create a git commit
  /permissions   Change permission mode
  /plan          Enter plan mode
  /resume        Resume a previous session
  /clear         Clear conversation context
  ...

练习题： 1. 启动 OpenHarness 交互式会话，使用 /help 查看所有命令 2. 输入一条提示让 Agent 在当前目录创建一个 hello.py 文件，观察权限确认对话框

1.3 Agent Loop（智能体循环）

概念讲解：

Agent Loop 是 OpenHarness 的核心引擎。它是一个无限循环的状态机，运作方式如下：

1. 接收提示：用户输入一条自然语言指令
2. 模型推理：将提示和可用工具列表发送给 LLM，获取流式响应
3. 判断行动：
4. 如果模型的 stop_reason 不是 tool_use，说明任务完成，返回结果
5. 如果模型返回了工具调用（tool_use），进入工具执行流程
6. 工具执行：经过权限检查 → Hook 前置 → 执行 → Hook 后置 → 获取结果
7. 结果回注：将工具执行结果追加到消息上下文中
8. 循环：回到第 2 步，模型看到工具结果后决定下一步行动

关键洞察： 模型自己决定需要调用哪些工具、以什么顺序调用。Harness 只是提供工具和安全边界。

代码示例：

# 观察 Agent Loop 的工作过程
# 使用 debug 模式可以看到每一步的详细信息
oh -d

# 然后输入提示：
# "读取 README.md 文件的第一行，然后创建一个 summary.txt 写入文件概要"

执行结果（简化版 debug 输出）：

[DEBUG] User prompt: 读取 README.md 文件的第一行...
[DEBUG] Sending to model with 43 tools available
[DEBUG] Model response: tool_use — Read(file_path="README.md", limit=1)
[DEBUG] Permission check: allowed
[DEBUG] Tool executed: Read → "# My Project\n"
[DEBUG] Appending tool result to context
[DEBUG] Model response: tool_use — Write(file_path="summary.txt", content="...")
[DEBUG] Permission check: asking user (Default mode)
> Allow Write to summary.txt? [y/n] y
[DEBUG] Tool executed: Write → success
[DEBUG] Model response: text — "我已经读取了 README.md..."

练习题： 1. 使用 debug 模式运行 OpenHarness，让 Agent 完成一个需要多步工具调用的任务（如"找到项目中的 TODO 注释并整理成列表"），观察 Agent Loop 的循环过程 2. 数一数你的任务中 Agent Loop 循环了多少次

1.4 工具系统基础

概念讲解：

工具（Tool）是 Agent 与外部世界交互的 唯一通道。OpenHarness 内置了 43 个工具，分为 9 大类：

每个工具都有四个核心特征： 1. Pydantic 输入验证 — 结构化、类型安全的参数定义 2. JSON Schema 自描述 — 模型自动理解工具的参数和用途 3. 权限集成 — 执行前进行权限检查 4. Hook 支持 — PreToolUse/PostToolUse 生命周期事件

代码示例：

# 在交互式会话中让 Agent 使用不同工具

# 文件 I/O 工具
# 提示："读取 config.json 并列出所有配置项"

# 搜索工具
# 提示："搜索 web 查找 Python 3.13 的新特性"

# Glob + Grep 工具组合
# 提示："找到项目中所有使用 asyncio 的 Python 文件"

执行结果（Glob + Grep 组合任务）：

Found 5 files using asyncio:

1. openharness/engine/query.py — 3 occurrences
2. openharness/tools/base.py — 1 occurrence
3. openharness/mcp/client.py — 7 occurrences
4. tests/test_engine.py — 12 occurrences
5. openharness/coordinator/swarm.py — 4 occurrences

练习题： 1. 让 Agent 使用 WebSearch 工具搜索一个技术问题并总结答案 2. 让 Agent 使用 Glob 工具找到项目中所有的 Markdown 文件

第二部分：进阶篇

2.1 多模型提供商切换

概念讲解：

OpenHarness 的一大亮点是同时支持 Anthropic 格式（默认）和 OpenAI 兼容格式。这意味着你可以自由切换后端模型，不受特定提供商锁定。

支持的提供商包括： - Anthropic 格式： Anthropic Claude、Moonshot/Kimi、Vertex、Bedrock - OpenAI 兼容格式： OpenAI、DeepSeek、DashScope（通义千问）、SiliconFlow、Groq、Ollama（本地）

代码示例：

# 示例 1：切换到 DeepSeek
uv run oh --api-format openai \
  --base-url "https://api.deepseek.com" \
  --api-key "sk-your-deepseek-key" \
  --model "deepseek-chat"

# 示例 2：切换到阿里云 DashScope（通义千问）
uv run oh --api-format openai \
  --base-url "https://dashscope.aliyuncs.com/compatible-mode/v1" \
  --api-key "sk-your-dashscope-key" \
  --model "qwen3.5-flash"

# 示例 3：使用本地 Ollama（完全离线，无 API 费用）
uv run oh --api-format openai \
  --base-url "http://localhost:11434/v1" \
  --api-key "ollama" \
  --model "qwen3:8b"

# 示例 4：通过环境变量持久配置（推荐写入 ~/.bashrc 或 ~/.zshrc）
export OPENHARNESS_API_FORMAT=openai
export OPENAI_API_KEY="sk-your-key"
export OPENHARNESS_BASE_URL="https://api.deepseek.com"
export OPENHARNESS_MODEL="deepseek-chat"

注意事项： - 不同模型的工具调用能力不同：Claude 和 DeepSeek 对工具调用的支持较好，小模型可能不稳定 - Ollama 本地模型需要足够的内存：8B 参数模型建议至少 8GB 内存 - API Key 不要提交到 Git：建议使用环境变量而非命令行参数传递密钥 - Base URL 必须包含协议前缀：https:// 或 http://

练习题： 1. 配置 OpenHarness 分别使用两种不同的模型提供商，发送相同的提示，对比响应质量 2. 尝试使用本地 Ollama 模型运行 OpenHarness，记录体验差异

2.2 Skills 技能系统

概念讲解：

Skills（技能）是 Markdown 格式的领域知识文件，在模型需要时 按需加载 到上下文中。技能不会一直占用上下文窗口，而是当用户的提示匹配到某个技能时才被注入。

OpenHarness 兼容 Claude Code 的 Skills 格式，这意味着你可以直接使用 anthropics/skills 仓库中的所有技能。

代码示例：

# 查看可用技能
# 在交互式会话中输入：
# /skills

创建自定义技能：

# 第 1 步：创建技能目录
mkdir -p ~/.openharness/skills

# 第 2 步：创建技能文件
cat > ~/.openharness/skills/code-review-zh.md << 'SKILL_EOF'
---
name: code-review-zh
description: 中文代码审查技能，专注于安全、性能和可维护性
---

# 中文代码审查技能

## 何时使用
当用户要求审查代码、检查 Bug、评估代码质量时使用此技能。

## 审查流程
1. **安全审查**：检查是否存在 SQL 注入、XSS、命令注入等安全漏洞
2. **性能审查**：检查是否存在 N+1 查询、不必要的循环、内存泄漏
3. **可维护性审查**：检查命名规范、代码复杂度、注释质量
4. **测试覆盖**：检查是否有对应的单元测试

## 输出格式
使用以下格式输出审查结果：

### 🔴 严重问题
- [文件:行号] 问题描述 → 建议修复方式

### 🟡 改进建议
- [文件:行号] 问题描述 → 建议改进方式

### 🟢 优秀实践
- 值得肯定的代码实践
SKILL_EOF

# 第 3 步：在会话中使用技能
oh
# 然后输入："审查 main.py 的代码质量"
# Agent 会自动加载 code-review-zh 技能

执行结果：

已加载技能：code-review-zh

### 🔴 严重问题
- [main.py:45] SQL 查询使用字符串拼接 → 建议使用参数化查询

### 🟡 改进建议
- [main.py:23] 函数复杂度过高（圈复杂度 15）→ 建议拆分为多个小函数
- [main.py:67] 缺少错误处理 → 建议添加 try/except 块

### 🟢 优秀实践
- 类型注解使用规范
- 函数文档字符串完整

注意事项： - 技能文件的 frontmatter（--- 之间的 YAML）必须包含 name 和 description - 技能文件过大（超过 2000 token）会占用过多上下文窗口，影响模型表现 - 技能不是工具——它提供的是 知识指导，不是可执行代码 - anthropics/skills 仓库中的 .md 文件可以直接复制到 ~/.openharness/skills/ 使用

练习题： 1. 创建一个自定义技能，用于生成符合你团队规范的 Git commit message 2. 从 anthropics/skills 仓库下载一个技能文件并在 OpenHarness 中使用

2.3 权限治理与安全控制

概念讲解：

OpenHarness 提供三级权限模式，在 Agent 自主性和安全性之间取得平衡：

你还可以通过 settings.json 配置更细粒度的权限规则。

代码示例：

# 方式 1：通过命令行参数设置权限模式
oh --permission-mode auto          # 自动模式
oh --permission-mode plan          # 只读计划模式

# 方式 2：在交互式会话中切换
# 输入 /permissions 命令

# 方式 3：通过配置文件设置细粒度规则
mkdir -p .openharness
cat > .openharness/settings.json << 'SETTINGS_EOF'
{
  "permission": {
    "mode": "default",
    "path_rules": [
      {"pattern": "/etc/*", "allow": false},
      {"pattern": "/System/*", "allow": false},
      {"pattern": "*/.env", "allow": false},
      {"pattern": "*/credentials*", "allow": false}
    ],
    "denied_commands": [
      "rm -rf /",
      "rm -rf ~",
      "DROP TABLE *",
      "DELETE FROM *",
      "format c:",
      "mkfs"
    ]
  }
}
SETTINGS_EOF

注意事项： - 永远不要在生产环境使用 Auto 模式，除非在完全隔离的沙箱中 - Plan Mode 是只读的，Agent 只能分析和建议，不能修改任何文件 - 路径规则使用 glob 模式匹配，* 匹配任意字符，** 匹配多层目录 - denied_commands 是黑名单，任何包含这些字符串的 Shell 命令都会被拒绝 - 配置文件优先级：项目目录 .openharness/settings.json > 全局 ~/.openharness/settings.json

练习题： 1. 启动 OpenHarness 并切换到 Plan Mode，尝试让 Agent 修改文件，观察行为 2. 配置 settings.json 禁止 Agent 访问 /tmp 目录，然后测试规则是否生效

2.4 Plugins 插件系统

概念讲解：

插件（Plugins）是比技能更强大的扩展机制。一个插件可以包含： - 命令（Commands）：新的斜杠命令 - Hook：PreToolUse/PostToolUse 生命周期钩子 - Agent：专门的子 Agent 定义

OpenHarness 兼容 Claude Code 的插件格式，已验证 12 个官方插件。

代码示例：

# 管理插件
oh plugin list                      # 列出已安装的插件
oh plugin install <source-url>      # 安装插件
oh plugin enable <plugin-name>      # 启用插件
oh plugin disable <plugin-name>     # 禁用插件

创建自定义插件：

# 第 1 步：创建插件目录结构
mkdir -p .openharness/plugins/my-linter/.claude-plugin
mkdir -p .openharness/plugins/my-linter/commands
mkdir -p .openharness/plugins/my-linter/hooks

# 第 2 步：创建插件配置文件
cat > .openharness/plugins/my-linter/.claude-plugin/plugin.json << 'EOF'
{
  "name": "my-linter",
  "version": "1.0.0",
  "description": "自定义代码检查插件"
}
EOF

# 第 3 步：添加命令
cat > .openharness/plugins/my-linter/commands/lint.md << 'EOF'
---
name: lint
description: 运行代码检查并报告问题
---

# Lint 命令

## 执行流程
1. 使用 Bash 工具运行 `ruff check .` 或 `flake8 .`
2. 分析输出结果
3. 按严重程度分类报告问题
4. 对于可自动修复的问题，建议使用 `ruff check --fix`
EOF

# 第 4 步：添加 Hook（在文件编辑后自动检查）
cat > .openharness/plugins/my-linter/hooks/hooks.json << 'EOF'
{
  "hooks": [
    {
      "event": "PostToolUse",
      "tool": "Edit",
      "action": "Run `ruff check {{file_path}}` and report any issues found."
    },
    {
      "event": "PostToolUse",
      "tool": "Write",
      "action": "Run `ruff check {{file_path}}` and report any issues found."
    }
  ]
}
EOF

# 第 5 步：启用插件
oh plugin enable my-linter

注意事项： - 插件的 plugin.json 路径必须严格遵循 .claude-plugin/plugin.json 的格式 - Hook 的 event 只支持 PreToolUse 和 PostToolUse - 插件命令是 Markdown 文件，不是可执行脚本——它们提供的是 指导知识 - {{file_path}} 等 {{}} 占位符会在运行时被替换为实际值

练习题： 1. 创建一个自定义插件，在每次文件写入后自动运行 git diff 显示变更 2. 从 Claude Code 插件仓库安装一个官方插件并在 OpenHarness 中使用

第三部分：高级篇

3.1 多 Agent 协调（Swarm）

概念讲解：

OpenHarness 内置了多 Agent 协调能力，允许主 Agent 将复杂任务拆分为多个子任务，分配给专门的子 Agent 并行处理。这就是所谓的 Swarm（蜂群）模式。

相关工具： - Agent：生成子 Agent - SendMessage：向子 Agent 发送消息 - TeamCreate/Delete：创建/删除 Agent 团队 - TaskCreate/Get/List/Update/Stop/Output：后台任务生命周期管理

代码示例：

# 在交互式会话中使用多 Agent 协调
# 启动 OpenHarness
oh

# 然后输入提示：
# "同时审查 src/ 目录下的所有 Python 文件的代码质量，
#  为每个文件生成审查报告，保存到 review/ 目录"
#
# Agent 会自动：
# 1. 使用 Glob 找到所有 Python 文件
# 2. 使用 Agent 工具生成多个子 Agent
# 3. 每个子 Agent 负责审查一个文件
# 4. 使用 TaskCreate 创建后台任务
# 5. 汇总所有子 Agent 的结果

注意事项： - 每个子 Agent 都会消耗 API 调用次数和 Token，注意成本控制 - 子 Agent 之间的共享状态有限，不适合需要强一致性的任务 - 后台任务可以通过 TaskGet 和 TaskOutput 查询进度和结果 - 不要为每个小任务都创建子 Agent——只有当任务可以真正并行处理时才使用 Swarm 模式，否则串行处理更高效 - 子 Agent 的权限继承自主 Agent：如果主 Agent 是 Default 模式，子 Agent 也需要用户确认写操作，这可能导致阻塞

3.2 非交互模式与自动化集成

概念讲解：

OpenHarness 支持三种非交互式输出格式，使其可以嵌入到 CI/CD 流水线、Shell 脚本或其他自动化系统中：

代码示例：

# 示例 1：纯文本模式（默认）
oh -p "解释 main.py 的主要功能" --output-format text

# 示例 2：JSON 输出（用于脚本解析）
oh -p "列出所有 TODO 注释" --output-format json

# 示例 3：在 CI/CD 流水线中使用
oh -p "检查这个仓库的代码是否有明显的 Bug" \
  --output-format json \
  --permission-mode plan \
  | python -c "import sys, json; data=json.load(sys.stdin); sys.exit(1 if data.get('bugs_found') else 0)"

# 示例 4：在 Shell 脚本中使用
#!/bin/bash
# auto_review.sh - 自动代码审查脚本

REPO_PATH="$1"
cd "$REPO_PATH" || exit 1

# 运行 OpenHarness 进行代码审查
oh -p "审查最近一次 Git commit 的代码变更，检查安全问题和 Bug" \
  --output-format text \
  --permission-mode plan

echo "审查完成"

3.3 性能优化与最佳实践

优化策略 1：选择合适的模型

# 简单任务使用便宜快速的模型
oh --model "claude-haiku-4-5" -p "格式化这段 JSON"

# 复杂任务使用强大的模型
oh --model "claude-sonnet-4-6" -p "重构这个模块的架构"

# 日常开发使用性价比模型
oh --model "deepseek-chat" -p "修复这个 Bug"

优化策略 2：使用 Plan Mode 减少无效操作

# 先用 Plan Mode 分析，确认方案后再执行
oh --permission-mode plan -p "分析这个项目并提出重构建议"
# 确认方案后切换到 Default 模式执行

最佳实践：

1. 使用 CLAUDE.md 提供项目上下文：在项目根目录创建 CLAUDE.md 文件，写入项目规范、架构说明、编码风格等。OpenHarness 会自动发现并注入到上下文中。

# 创建项目级 CLAUDE.md
cat > CLAUDE.md << 'EOF'
# 项目规范

## 技术栈
- Python 3.12+
- FastAPI + SQLAlchemy
- pytest 测试

## 编码规范
- 使用 type hints
- 函数最大长度 50 行
- 必须有 docstring

## 测试要求
- 所有新功能必须有测试
- 测试覆盖率 > 80%
EOF

1. 使用 Auto-Compact 控制上下文窗口：长时间会话中，OpenHarness 会自动压缩历史消息以节省 Token。

2. 使用 Memory 持久化关键信息：通过 MEMORY.md 文件保存跨会话的知识。

第四部分：实战项目

项目需求

构建一个 自动化代码审查机器人，能够： 1. 分析 Git 仓库中最近的代码变更 2. 对变更进行安全审查、性能审查和代码质量审查 3. 生成结构化的审查报告 4. 支持多种输出格式（终端、JSON）

项目设计

auto-review/
├── review.sh              # 主入口脚本
├── .openharness/
│   ├── settings.json      # 权限配置
│   ├── skills/
│   │   └── review.md      # 自定义审查技能
│   └── plugins/
│       └── auto-review/
│           └── .claude-plugin/
│               └── plugin.json
└── README.md

完整实现代码

#!/bin/bash
# review.sh - 自动化代码审查机器人
# 使用方法：./review.sh [仓库路径] [输出格式]

# 第 1 步：解析参数
REPO_PATH="${1:-.}"
OUTPUT_FORMAT="${2:-text}"

# 第 2 步：切换到目标仓库
cd "$REPO_PATH" || { echo "错误：无法进入目录 $REPO_PATH"; exit 1; }

# 第 3 步：检查是否是 Git 仓库
if [ ! -d ".git" ]; then
    echo "错误：$REPO_PATH 不是 Git 仓库"
    exit 1
fi

# 第 4 步：获取最近的变更摘要
COMMIT_COUNT=$(git log --oneline -5 | wc -l)
echo "=== 将审查最近 $COMMIT_COUNT 个提交的变更 ==="

# 第 5 步：构建审查提示
REVIEW_PROMPT="你是一位资深代码审查专家。请审查这个 Git 仓库中最近 5 个提交的代码变更。

审查维度：
1. 安全性：是否存在 SQL 注入、XSS、命令注入等安全漏洞
2. 性能：是否存在 N+1 查询、内存泄漏、不必要的循环
3. 代码质量：命名规范、复杂度、重复代码
4. 测试覆盖：新增代码是否有对应的测试

输出格式：
- 按严重程度分类（严重/警告/建议）
- 每个问题包含：文件路径、行号范围、问题描述、建议修复方式
- 最后给出整体评分（1-10）和改进建议"

# 第 6 步：运行 OpenHarness（Plan Mode 确保只读）
oh -p "$REVIEW_PROMPT" \
   --output-format "$OUTPUT_FORMAT" \
   --permission-mode plan

echo ""
echo "=== 审查完成 ==="

# 创建自定义审查技能
mkdir -p .openharness/skills
cat > .openharness/skills/security-review.md << 'SKILL_EOF'
---
name: security-review
description: 专注于安全漏洞的代码审查技能
---

# 安全审查技能

## 检查清单

### OWASP Top 10 检查
1. **注入攻击**：检查所有 SQL 查询是否使用参数化
2. **XSS**：检查所有用户输入是否经过转义
3. **敏感数据泄露**：检查是否有硬编码的密钥或密码
4. **访问控制**：检查 API 端点是否有权限验证
5. **安全配置**：检查 CORS、CSRF 等配置

### 输出格式
对于每个发现的安全问题：
- 严重程度：🔴 高危 / 🟡 中危 / 🟢 低危
- CWE 编号（如适用）
- 受影响的代码位置
- 修复建议（包含代码示例）
SKILL_EOF

# 创建权限配置
cat > .openharness/settings.json << 'SETTINGS_EOF'
{
  "permission": {
    "mode": "plan",
    "path_rules": [
      {"pattern": "/etc/*", "allow": false},
      {"pattern": "*/.env", "allow": false},
      {"pattern": "*/credentials*", "allow": false},
      {"pattern": "*/id_rsa*", "allow": false}
    ],
    "denied_commands": [
      "rm -rf",
      "curl.*|.*sh",
      "wget.*|.*sh",
      "DROP TABLE",
      "DELETE FROM"
    ]
  }
}
SETTINGS_EOF

使用方式：

# 赋予执行权限
chmod +x review.sh

# 审查当前仓库（终端输出）
./review.sh .

# 审查指定仓库（JSON 输出，适合集成到 CI）
./review.sh /path/to/repo json

# 集成到 GitHub Actions
# .github/workflows/review.yml 中使用：
# - name: Auto Review
#   run: ./review.sh . json > review-report.json

代码解析

本实战项目综合运用了以下知识点：

1. 非交互模式（-p 参数 + --output-format） — 通过 -p 传递审查提示，配合 json 输出格式，使脚本可以集成到 CI/CD 流水线中。参考入门篇 1.1 和高级篇 3.2。

2. 权限治理（--permission-mode plan） — 审查机器人使用 Plan Mode，确保 Agent 只读取代码、生成报告，不会修改任何文件。参考进阶篇 2.3。

3. 自定义技能（Skills） — security-review.md 技能为 Agent 提供安全审查的专业知识，使其审查更有针对性。参考进阶篇 2.2。

4. 配置文件（settings.json） — 通过路径规则和命令黑名单，防止 Agent 访问敏感文件或执行危险命令。参考进阶篇 2.3。

扩展挑战

1. 添加 Slack/飞书通知：在审查完成后，通过 Webhook 将审查结果发送到 Slack 或飞书群组
2. 增量审查：只审查 Git diff 中的变更部分，而非整个仓库，提高效率
3. 多模型对比审查：使用不同模型对同一份代码进行审查，对比审查质量

第五部分：常见问题与排查指南

常见错误及解决方案

调试技巧

1. 使用 debug 模式：启动时加 -d 或 --debug 参数，可以看到每一步的工具调用、权限检查和模型响应细节，是排查问题的第一选择。

oh -d -p "你的提示"

1. 检查配置文件优先级：当配置不生效时，检查是否存在多个配置文件冲突。优先级从高到低：命令行参数 > 项目 .openharness/settings.json > 全局 ~/.openharness/settings.json。

2. 逐步简化提示：当 Agent 行为异常时，将复杂提示拆分为多个简单步骤，逐步排查是哪一步出了问题。

第六部分：学习路线推荐

官方文档推荐阅读顺序

1. GitHub README — 快速入门、安装指南、基本使用。重点：Quick Start 和 Provider Compatibility 章节
2. docs/SHOWCASE.md — 实际使用场景和示例。重点：理解不同使用模式（交互/非交互/自动化）
3. CONTRIBUTING.md — 贡献指南和开发环境配置。重点：开发流程、测试运行方式
4. 源码 openharness/engine/ — Agent Loop 核心实现。重点：理解循环机制和工具调度
5. 源码 openharness/tools/ — 工具实现参考。重点：BaseTool 抽象和工具注册机制

推荐进阶资源

• anthropics/skills 仓库 — Claude Code 官方技能库，所有 .md 文件可直接在 OpenHarness 中使用
• claude-code/plugins 仓库 — Claude Code 官方插件库，了解插件开发最佳实践
• Model Context Protocol (MCP) 文档 — MCP 协议官方文档，理解 OpenHarness 的 MCP 集成机制
• Pydantic V2 文档 — 工具输入验证框架，开发自定义工具的必备知识
• OpenClaw 项目 — 同属 HKUDS 生态的 AI 网关项目，理解更广泛的 Agent 生态

学习里程碑检查清单

• [ ] 成功安装并运行 OpenHarness
• [ ] 理解 Agent Loop 的工作原理（提示→推理→工具→循环）
• [ ] 能使用交互式和非交互式两种模式
• [ ] 能切换不同的 LLM 模型提供商
• [ ] 能创建自定义技能（.md 文件）
• [ ] 能配置权限规则（settings.json）
• [ ] 能创建自定义插件（commands + hooks）
• [ ] 能将 OpenHarness 集成到 Shell 脚本中
• [ ] 理解多 Agent 协调的基本概念
• [ ] 能阅读源码理解核心模块的实现

附录：术语对照表