# 架构与设计理念

本文档说明 Harness-ZH 的设计目标、抽象层级与扩展点。面向希望**二次开发、深度定制或贡献代码**的读者。

## 设计目标

1. **分离"谁"与"怎么做"**
   - Agent（`.claude/agents/*.md`）只描述**角色、原则、I/O 协议**，不含实现细节。
   - Skill（`.claude/skills/*/SKILL.md`）只描述**能力、触发机制、执行步骤**，不绑定具体 agent。
   - 同一个 skill 可被多个 agent 复用；同一个 agent 可调用多个 skill。

2. **团队优先（Agent Teams First）**
   - 2+ agent 协作场景一律默认用 `TeamCreate + SendMessage + TaskCreate`。
   - 仅在通信确实无必要时降级为独立 subagent。

3. **进化性（Evolving Harness）**
   - 每次执行完向反馈收敛：更新 agent 定义、调整 skill description、在 `CLAUDE.md` 追加变更历史。
   - Phase 0 审计是运维的常态化入口。

4. **渐进披露（Progressive Disclosure）**
   - SKILL.md 是骨架 + 指针，保持精简。
   - 细节放在 `references/` 的专题文档里，Claude 按需加载，降低每次对话的上下文成本。

## 抽象层级

```
┌───────────────────────────────────────────────────────┐
│  Phase 0–7 工作流                                      │ ← SKILL.md（主入口）
├───────────────────────────────────────────────────────┤
│  3 种执行模式                                          │
│    Agent Teams / Subagents / Hybrid                   │ ← references/orchestrator-template.md
├───────────────────────────────────────────────────────┤
│  6 种架构模式                                          │
│    Pipeline / Fan-out·Fan-in / Expert Pool /          │ ← references/agent-design-patterns.md
│    Producer-Reviewer / Supervisor / Hierarchical      │
├───────────────────────────────────────────────────────┤
│  Agent 定义模板 + Skill 写作指南                       │ ← references/skill-writing-guide.md
│                                                        │   references/team-examples.md
├───────────────────────────────────────────────────────┤
│  QA + 测试（5 维 QA / A/B + 对抗性变体）               │ ← references/qa-agent-guide.md
│                                                        │   references/skill-testing-guide.md
└───────────────────────────────────────────────────────┘
```

## 触发流

```
用户自然语言提示
        │
        ▼
Claude Code 匹配 SKILL.md 的 description
        │
        ▼
加载 SKILL.md 主骨架
        │
        ▼
Phase 0 审计（读 .claude/{agents,skills}，读 CLAUDE.md）
        │
        ├─ 新建 ──────────▶ Phase 1–6 全流程
        ├─ 扩展 ──────────▶ Phase 选择矩阵 → 仅跑必要的 Phase
        └─ 运维/维护 ─────▶ Phase 7-5 运维子流程
                │
                ▼
        按需加载 references/*.md（Progressive Disclosure）
                │
                ▼
        生成 .claude/agents/*.md 与 .claude/skills/*/
                │
                ▼
        更新 CLAUDE.md trigger 指针 + 变更历史
                │
                ▼
        Phase 6 验证（trigger / dry-run / A/B / 对抗性）
```

## 关键决策点

### 为什么强制 Agent 定义落盘
即便使用内置 agent 类型（`general-purpose`、`Explore`、`Plan`），也必须生成 `.claude/agents/{name}.md`。原因：
- 下次会话才能复用。
- 团队通信协议必须显式写明，否则协作质量不稳定。
- Harness 的价值来自"角色-能力分离"，角色丢了就退化成一次性 subagent 调用。

### 为什么分级模型（v2.0.0 松动点）
- 上游强制全 opus 保证质量，但代价是高 token 成本。
- v2 基于"任务复杂度"二元评估：
  - **复杂推理 / 创造 / 架构决策** → opus
  - **结构化转换 / 规则匹配 / 格式化输出** → sonnet 即可
- 实证观察：在"数据管道 schema 生成"等结构化任务上，sonnet 质量与 opus 差异 <5%，但成本下降 5x。

### 为什么时序一致性独立成维
结构一致性 bug（字段名对不上）**启动即崩**——容易发现。时序一致性 bug（并发重复写入、回调乱序）**偶发、在生产才暴露**——危害更大但更隐蔽。主动校验比被动等故障更划算。

### 为什么对抗性测试只对"用户自由文本输入"类 skill
- 若 skill 输入由上游 agent 按契约格式投喂，对抗性变体等于在测上游契约，不经济。
- 若 skill 直接受理人类消息（如文案生成、问答、分析），必须对抗性测试以暴露 silent failure。

## 扩展点

| 想扩展什么 | 改动位置 | 备注 |
|---|---|---|
| 新架构模式 | `references/agent-design-patterns.md` | 同时在 SKILL.md Phase 2-2 列表中引用 |
| 新 QA 维度 | `references/qa-agent-guide.md` | 在最终检查清单与优先级表同步 |
| 新测试方法 | `references/skill-testing-guide.md` | 声明适用边界，避免过度工程化 |
| 新领域示例 | `references/qa-agent-guide.md` §6/§7 后续 | 保持"通用方法论 + 独立领域节" 格式 |
| 新触发短语 | SKILL.md frontmatter `description` | 注意命中面扩大带来的误触风险 |

## 质量门禁

贡献合并前 CI 会强制：
- Markdown lint
- 韩文字符扫描（本 fork 已全部中文化，任何韩文都视为泄漏）
- 结构完整性（plugin.json、6 份 references、必要 meta 文件存在）
- JSON 语法合法

运行本地等效检查：

```shell
grep -Pr '[\x{AC00}-\x{D7A3}]' skills/ docs/ --include='*.md'  # 应无输出
python3 -c "import json; json.load(open('.claude-plugin/plugin.json'))"
```