ClawPal Harness Engineering 标准

# ClawPal Harness Engineering 标准

## 1. 目标

为 ClawPal（基于 Tauri 的 OpenClaw 桌面伴侣应用）建立一套 agent-first 的 Harness Engineering 标准，使工程师和 coding agent 能在清晰边界内稳定完成开发、验证和发布工作。

本标准综合以下三份基线文档，并结合 ClawPal 项目当前实际状态制定：

- [Harness Engineering 可执行落地文档](https://github.com/Keith-CY/harness-framework/blob/investigation/docs/harness-engineering-executable-playbook.md)
- [Tauri Harness System 设计](https://github.com/Keith-CY/harness-framework/blob/investigation/docs/tauri-harness-system-design.md)
- [ClawPal 落地路径对比分析](https://github.com/Keith-CY/harness-framework/blob/investigation/docs/clawpal-tauri-harness-adoption-comparison.md)

---

## 2. 适用范围

本标准适用于 `lay2dev/clawpal` 仓库的所有代码变更、文档维护和自动化流程，覆盖前端（React/TypeScript）、Rust 后端（Tauri commands / clawpal-core / clawpal-cli）和 CI/CD 流水线。

---

## 3. 核心原则

| # | 原则 | ClawPal 落地要求 |
|---|------|-----------------|
| P1 | **先让系统可见，再让 agent 自主** | 所有架构边界、运行命令、约束条件必须写入固定位置的文档 |
| P2 | **文档是工作入口，不是事后补充** | `AGENTS.md` 为 agent 唯一入口；`docs/` 为结构化知识库 |
| P3 | **把标准写进机制** | 能自动检查的规则不依赖 reviewer 记忆，用 lint/CI gate 实施 |
| P4 | **小步快跑，证据交付** | 单 PR ≤ 500 行为宜；每个 PR 必须附验证证据 |
| P5 | **持续清理熵** | 每周至少一次熵治理动作（删无用代码、归档过期文档、修正漂移） |
| P6 | **跨端调用视为正式接口** | Tauri `invoke` 是进程边界，所有 command 必须有稳定命名、明确 I/O、统一错误模型 |
| P7 | **默认隔离副作用** | 文件系统/shell/通知/剪贴板/updater 等原生能力收敛到 adapter 层 |

---

## 4. 仓库结构标准

### 4.1 必须存在的顶层文件

| 文件 | 用途 |
|------|------|
| `AGENTS.md` | Agent 工作入口（启动命令、目录说明、边界规则、验收要求） |
| `README.md` | 项目概述、快速开始 |
| `justfile` 或 `cargo xtask` | 统一命令入口 |

> **Action Required**: 当前 `agents.md`（小写）需重命名为 `AGENTS.md`。

### 4.2 文档目录结构

```
docs/
  architecture/       # 模块边界、分层原则、核心数据流
  decisions/          # ADR（Architecture Decision Records）
  plans/              # 任务计划（已有，保留）
  runbooks/           # 启动、调试、发布、回滚、故障处理
  testing/            # 测试矩阵、验证策略（已有，保留）
```

> **Action Required**: 将现有 `design.md`、`cc.md`、`cc-architecture-refactor-v1.md`、`cc-ssh-refactor-v1.md` 重新分类归档到 `docs/architecture/` 和 `docs/decisions/`。

### 4.3 Harness 专用目录

```
harness/
  fixtures/           # 最小稳定测试数据
  artifacts/          # 日志、截图、trace、失败产物收集
```

### 4.4 代码分层标准

ClawPal 采用四层架构，每层职责和约束如下：

#### UI 层 (`src/`)

- 职责：页面、组件、状态管理、用户交互
- **禁止**：直接在组件中散落 `invoke("xxx")`、直接访问原生能力、拼接 command 名称
- 所有 Tauri command 调用通过 `src/lib/api/` 统一封装

#### Command 层 (`src-tauri/src/commands/`)

- 职责：Tauri command 定义、参数校验、权限检查、错误映射、事件分发
- **禁止**：堆积业务编排逻辑、直接写文件系统/数据库
- 保持薄层，每个 command 文件 ≤ 300 行

> **Action Required**: `src-tauri/src/commands/mod.rs`（约 10,546 行）必须按领域拆分为独立模块。

#### Domain 层 (`src-tauri/src/domain/` 或 `clawpal-core`)

- 职责：核心业务规则、用例编排
- **禁止**：依赖 `tauri::*`，I/O 保持普通 Rust 类型
- 业务逻辑优先在此层做单元测试

#### Adapter 层 (`src-tauri/src/adapters/`)

- 职责：文件系统、shell、通知、剪贴板、数据库、updater、外部 API
- 所有原生副作用从此层进入
- 必须提供 mock/fake/test double
- 记录平台差异和失败模式

---

## 5. AGENTS.md 标准内容

`AGENTS.md` 必须包含以下章节：

```markdown
# AGENTS.md

## 项目概述
（一句话描述 + 技术栈）

## 目录说明
（关键目录及其职责）

## 启动命令
just dev          # 本地开发
just test-unit    # 单元测试
just test-contracts  # Contract 测试
just smoke        # 冒烟测试

## 代码修改约束
- UI 层不直接调用 invoke
- Command 层保持薄层
- 新增原生能力必须走 adapter 层
- 修改权限配置必须附验证证据

## 提交与验证要求
- PR ≤ 500 行
- 必须通过所有 CI gate
- 必须附验证证据（测试输出/截图/日志）

## 新增 Command 检查清单
- [ ] Command 定义在 commands/ 对应模块
- [ ] 参数校验和错误映射完整
- [ ] Contract test 已添加
- [ ] 前端 API 封装已更新
- [ ] AGENTS.md command 列表已更新

## 常见排查路径
（打包问题、平台差异、command 调用失败等）
```

---

## 6. 统一命令入口

必须通过 `justfile`（推荐）或 `cargo xtask` 提供以下命令：

| 命令 | 用途 |
|------|------|
| `just doctor` | 检查 Rust、Node、平台依赖、WebView、签名配置 |
| `just dev` | 启动前端 + Tauri dev |
| `just test-unit` | 前端单测 + Rust 单测 + domain 测试 |
| `just test-contracts` | Command 输入/输出/错误/权限契约验证 |
| `just test-integration` | Adapter 层集成测试 |
| `just smoke` | 桌面应用关键路径冒烟 |
| `just package-check` | 打包后 packaged app 冒烟验证 |
| `just artifacts` | 汇总日志、截图、trace |
| `just fmt` | 统一格式化（前端 + Rust） |
| `just lint` | 统一 lint（前端 + clippy） |

> **Action Required**: 统一包管理器为 Bun（README 已以 Bun 为主，但 PR build 仍用 `npm ci` + `package-lock.json`，需归一）。

---

## 7. 验证链路标准

### 7.1 静态检查（CI Gate，每次 PR 必须通过）

- 前端类型检查 (`tsc --noEmit`)
- 前端 lint
- `cargo fmt --check`
- `cargo clippy`

### 7.2 单元测试

覆盖重点：
- Domain 层业务规则
- 错误映射逻辑
- 前端状态更新
- 数据转换逻辑

### 7.3 Command Contract 测试

每个 Tauri command 必须有契约测试，验证：
- 输入 schema 符合预期
- 输出类型稳定
- 业务错误映射为统一错误结构
- 权限不足返回可识别错误
- 不泄露内部错误细节

### 7.4 集成测试

针对 adapter 层：文件读写、本地数据库、外部 API、平台能力调用。
必须配最小 fixture，禁止依赖本机随机状态。

### 7.5 Packaged App 冒烟测试

至少验证：
- 应用正常启动
- 首页渲染成功
- 一条核心 command 闭环执行
- 日志路径和资源路径正确
- 关键权限在打包后有效

### 7.6 覆盖率

维持现有 coverage CI gate，domain 层目标 ≥ 80%。

---

## 8. PR 标准

### 8.1 规模

- 单 PR 变更 ≤ 500 行（不含自动生成文件）
- 超过 500 行需拆分或附书面说明

### 8.2 必须附带的验证证据

- 测试通过截图或日志
- 涉及 UI 的改动附截图
- 涉及权限/安全的改动附 capability 变更说明
- 涉及打包的改动附 packaged app 验证结果

### 8.3 PR 模板

```markdown
## 目标

## 影响范围

## 验证方式

## 验证证据

## 风险与回滚
```

### 8.4 Review 重点

Reviewer 聚焦：
- 方向是否正确
- 边界是否被破坏
- 复杂度是否合理
- 文档是否同步更新
- 是否引入隐性耦合

自动化能处理的问题（格式、lint、类型）不应占用 review 时间。

---

## 9. 任务流程标准

### Step 1: 定义任务

在 `docs/plans/` 创建任务文档：

```markdown
# 任务名称

## 目标
## 非目标
## 背景
## 影响范围
## 约束条件
## 执行步骤
## 验收标准
## 风险与回滚
```

### Step 2: 提供上下文

只提供与任务直接相关的文档、目录、运行方式。不堆无关上下文。

### Step 3: 小范围交付

单次只做一个清晰子任务（新增接口、重构模块、修复问题、补测试）。

### Step 4: 自动验证

提交前必须运行 `just lint`、`just test-unit`、`just test-contracts` 并附结果。

### Step 5: Review + 合并

通过则尽快合并；不通过指出最小修正集，禁止长期悬空大 PR。

### Step 6: 归档回写

完成后更新相关文档、归档计划、记录异常、踩坑写入 runbook。

---

## 10. 日志与调试标准

- 前端日志、Rust 日志、command 调用日志进入统一目录
- 每次 command 调用携带 `request_id`
- 失败时自动输出 command 名称、参数摘要、错误码、耗时
- Smoke test 失败时自动保存截图和日志包
- **禁止** 在正式代码中使用 `eprintln!`，统一走 `tracing` 结构化日志

### Runbook 标准

`docs/runbooks/` 中至少包含：
- 本地开发启动
- 前端日志查看
- Rust 日志查看
- Command 调用失败排查
- Packaged app 与 dev 模式差异定位
- SSH 远程连接故障排查
- Doctor 诊断流程
- 版本回滚流程

Runbook 模板：

```markdown
# 场景名称

## 触发条件
## 排查步骤
## 常见原因
## 修复动作
## 验证方法
```

---

## 11. 安全与权限标准

- Command 白名单和职责说明写入 `AGENTS.md`
- Capability/permission 配置变更必须经 review
- 高风险 adapter（shell、文件系统、updater）必须有测试覆盖
- 默认最小权限原则
- 新增原生能力必须同时补文档和验证
- Agent 可提高速度，但**不得绕过桌面应用权限边界**

---

## 12. 代码可读性标准（Agent Legibility）

- 单文件 ≤ 500 行（超过需拆分或附理由）
- 关键模块配 architecture note（`docs/architecture/<module>.md`）
- 高变更频率模块配 change guide
- 为高风险模块标注 CODEOWNERS

> **Action Required**:
> - `src/App.tsx`（约 1,787 行）需按路由/功能拆分
> - `src-tauri/src/commands/mod.rs`（约 10,546 行）需按领域拆分

---

## 13. 熵治理标准

每周执行一次熵治理，内容包括：
- 删除无用代码和死分支
- 合并重复实现
- 归档过期 `docs/plans/` 文档
- 修正文档与代码的漂移
- 记录 agent 失败案例并归纳为规则
- 复盘"哪些失败是 harness 问题，哪些是模型问题"

---

## 14. 效果度量指标

| 指标 | 目标方向 |
|------|----------|
| PR 中位生命周期 | ↓ 缩短 |
| 单 PR 平均变更行数 | ↓ 趋近 200-500 行 |
| Agent 独立完成任务占比 | ↑ 提升 |
| 回退/返工率 | ↓ 降低 |
| 文档更新滞后率 | ↓ 降低 |
| CI 失败中环境问题占比 | ↓ 降低 |
| 同类问题重复出现次数 | ↓ 降低 |
| Command 漂移（前后端不一致）次数 | ↓ 降低 |
| Packaged app 问题暴露阶段 | ↑ 更早 |

---

## 15. 角色分工

| 角色 | 职责 |
|------|------|
| Harness Owner | Agent 入口维护、验证链路、文档结构、治理节奏 |
| Domain Owner | 业务域架构边界和质量标准 |
| Reviewer | 方向、风险、复杂度审查（不补上下文） |
| Agent Operator | 任务分解、上下文提供、结果验收 |

小团队可兼任，但职责须明确。

---

## 16. 落地路线图

基于路径对比分析结论，采用**原仓库改造**路径。

### Phase 1: 仓库入口归一（2-4 天）

- [ ] `agents.md` → `AGENTS.md`，按第 5 节标准补全内容
- [ ] 建立 `docs/architecture/`、`docs/decisions/`、`docs/runbooks/`
- [ ] 将 `design.md`、`cc*.md` 重新分类归档
- [ ] 建立 `harness/fixtures/`、`harness/artifacts/`

### Phase 2: 验证与流程归一（3-5 天）

- [ ] 落地 `justfile`，按第 6 节标准实现所有命令
- [ ] 统一 Bun/npm 策略（选定 Bun，移除 `package-lock.json`）
- [ ] 增加 PR 模板和任务模板
- [ ] 将 `business-flow-test-matrix.md` 升级为标准 gate 文档
- [ ] 补 packaged app smoke test 入口
- [ ] 补 artifacts 汇总入口

### Phase 3: 代码可读性改造（1.5-3 周）

- [ ] 拆分 `src/App.tsx`
- [ ] 拆分 `src-tauri/src/commands/mod.rs`
- [ ] 收口 GUI / core / remote helper 边界
- [ ] 为高风险模块补 architecture note 和 change guide
- [ ] 补 command contract tests

### Phase 4: 机制固化（4-7 天）

- [ ] PR 必须附验证证据（CI gate 强制）
- [ ] 关键目录加 CODEOWNERS
- [ ] 高风险调用链加约束测试
- [ ] Runbook 增加失败诊断和回滚路径
- [ ] 建立每周熵治理 checklist

---

## 17. 参考文档

- [Harness Engineering 可执行落地文档](https://github.com/Keith-CY/harness-framework/blob/investigation/docs/harness-engineering-executable-playbook.md)
- [Tauri Harness System 设计](https://github.com/Keith-CY/harness-framework/blob/investigation/docs/tauri-harness-system-design.md)
- [ClawPal 落地路径对比分析](https://github.com/Keith-CY/harness-framework/blob/investigation/docs/clawpal-tauri-harness-adoption-comparison.md)
- OpenAI [Harness Engineering](https://openai.com/index/harness-engineering/) (2026-02-11)


#	原则	ClawPal 落地要求
P1	先让系统可见，再让 agent 自主	所有架构边界、运行命令、约束条件必须写入固定位置的文档
P2	文档是工作入口，不是事后补充	`AGENTS.md` 为 agent 唯一入口；`docs/` 为结构化知识库
P3	把标准写进机制	能自动检查的规则不依赖 reviewer 记忆，用 lint/CI gate 实施
P4	小步快跑，证据交付	单 PR ≤ 500 行为宜；每个 PR 必须附验证证据
P5	持续清理熵	每周至少一次熵治理动作（删无用代码、归档过期文档、修正漂移）
P6	跨端调用视为正式接口	Tauri `invoke` 是进程边界，所有 command 必须有稳定命名、明确 I/O、统一错误模型
P7	默认隔离副作用	文件系统/shell/通知/剪贴板/updater 等原生能力收敛到 adapter 层

文件	用途
`AGENTS.md`	Agent 工作入口（启动命令、目录说明、边界规则、验收要求）
`README.md`	项目概述、快速开始
`justfile` 或 `cargo xtask`	统一命令入口

命令	用途
`just doctor`	检查 Rust、Node、平台依赖、WebView、签名配置
`just dev`	启动前端 + Tauri dev
`just test-unit`	前端单测 + Rust 单测 + domain 测试
`just test-contracts`	Command 输入/输出/错误/权限契约验证
`just test-integration`	Adapter 层集成测试
`just smoke`	桌面应用关键路径冒烟
`just package-check`	打包后 packaged app 冒烟验证
`just artifacts`	汇总日志、截图、trace
`just fmt`	统一格式化（前端 + Rust）
`just lint`	统一 lint（前端 + clippy）

指标	目标方向
PR 中位生命周期	↓ 缩短
单 PR 平均变更行数	↓ 趋近 200-500 行
Agent 独立完成任务占比	↑ 提升
回退/返工率	↓ 降低
文档更新滞后率	↓ 降低
CI 失败中环境问题占比	↓ 降低
同类问题重复出现次数	↓ 降低
Command 漂移（前后端不一致）次数	↓ 降低
Packaged app 问题暴露阶段	↑ 更早

角色	职责
Harness Owner	Agent 入口维护、验证链路、文档结构、治理节奏
Domain Owner	业务域架构边界和质量标准
Reviewer	方向、风险、复杂度审查（不补上下文）
Agent Operator	任务分解、上下文提供、结果验收

ClawPal Harness Engineering 标准 #123

Description

ClawPal Harness Engineering 标准

1. 目标

2. 适用范围

3. 核心原则

4. 仓库结构标准

4.1 必须存在的顶层文件

4.2 文档目录结构

4.3 Harness 专用目录

4.4 代码分层标准

UI 层 (src/)

Command 层 (src-tauri/src/commands/)

Domain 层 (src-tauri/src/domain/ 或 clawpal-core)

Adapter 层 (src-tauri/src/adapters/)

5. AGENTS.md 标准内容

6. 统一命令入口

7. 验证链路标准

7.1 静态检查（CI Gate，每次 PR 必须通过）

7.2 单元测试

7.3 Command Contract 测试

7.4 集成测试

7.5 Packaged App 冒烟测试

7.6 覆盖率

8. PR 标准

8.1 规模

8.2 必须附带的验证证据

8.3 PR 模板

8.4 Review 重点

9. 任务流程标准

Step 1: 定义任务

Step 2: 提供上下文

Step 3: 小范围交付

Step 4: 自动验证

Step 5: Review + 合并

Step 6: 归档回写

10. 日志与调试标准

Runbook 标准

11. 安全与权限标准

12. 代码可读性标准（Agent Legibility）

13. 熵治理标准

14. 效果度量指标

15. 角色分工

16. 落地路线图

Phase 1: 仓库入口归一（2-4 天）

Phase 2: 验证与流程归一（3-5 天）

Phase 3: 代码可读性改造（1.5-3 周）

Phase 4: 机制固化（4-7 天）

17. 参考文档

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

UI 层 (`src/`)

Command 层 (`src-tauri/src/commands/`)

Domain 层 (`src-tauri/src/domain/` 或 `clawpal-core`)

Adapter 层 (`src-tauri/src/adapters/`)