From aa22eb2123bdc5e80917ca6fa1c5d67d7adeda35 Mon Sep 17 00:00:00 2001 From: hyhmrright Date: Mon, 1 Jun 2026 18:55:03 +0800 Subject: [PATCH] docs: add Chinese (Simplified) translation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add Chinese README and docs to match the existing KO/JA localization: - README_ZH.md — full translation of README.md (proper nouns kept in English) - docs/quickstart_ZH.md — translation of docs/quickstart.md - docs/experimental-dependency_ZH.md — translation of docs/experimental-dependency.md - Update EN/KO/JA README language switchers and the i18n badge to include 中文 (ZH) Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 4 +- README_JA.md | 4 +- README_KO.md | 4 +- README_ZH.md | 303 +++++++++++++++++++++++++++++ docs/experimental-dependency_ZH.md | 153 +++++++++++++++ docs/quickstart_ZH.md | 118 +++++++++++ 6 files changed, 580 insertions(+), 6 deletions(-) create mode 100644 README_ZH.md create mode 100644 docs/experimental-dependency_ZH.md create mode 100644 docs/quickstart_ZH.md diff --git a/README.md b/README.md index b64e786..a56e63c 100644 --- a/README.md +++ b/README.md @@ -14,12 +14,12 @@

Layer Sub-layer - i18n + i18n

# Harness — The Team-Architecture Factory for Claude Code -**English** | [한국어](README_KO.md) | [日本語](README_JA.md) +**English** | [한국어](README_KO.md) | [日本語](README_JA.md) | [中文](README_ZH.md) > **Harness is a team-architecture factory for Claude Code.** Say **"build a harness for this project"** (English) or **"하네스 구성해줘"** (한국어) or **"ハーネスを構成して"** (日本語), and the plugin turns your domain description into an agent team and the skills they use — picked from six pre-defined team-architecture patterns. diff --git a/README_JA.md b/README_JA.md index 542ce3e..befaeff 100644 --- a/README_JA.md +++ b/README_JA.md @@ -14,12 +14,12 @@

Layer Sub-layer - i18n + i18n

# Harness — Claude Code のためのチームアーキテクチャファクトリー -[English](README.md) | [한국어](README_KO.md) | **日本語** +[English](README.md) | [한국어](README_KO.md) | **日本語** | [中文](README_ZH.md) > **Harness は Claude Code 向けのチームアーキテクチャファクトリーです。** **「ハーネスを構成して」** (日本語) · **"build a harness for this project"** (English) · **"하네스 구성해줘"** (한국어) と伝えるだけで、プラグインがドメイン記述をエージェントチームとそのチームが使うスキルへと変換します — あらかじめ定義された 6 種類のチームアーキテクチャパターンから 1 つを選んで。 diff --git a/README_KO.md b/README_KO.md index 891994d..7295b8b 100644 --- a/README_KO.md +++ b/README_KO.md @@ -14,12 +14,12 @@

Layer Sub-layer - i18n + i18n

# Harness — Claude Code를 위한 팀 아키텍처 팩토리 -[English](README.md) | **한국어** | [日本語](README_JA.md) +[English](README.md) | **한국어** | [日本語](README_JA.md) | [中文](README_ZH.md) > **Harness는 Claude Code용 팀 아키텍처 팩토리입니다.** **"하네스 구성해줘"** (한국어) · **"build a harness for this project"** (English) · **"ハーネスを構成して"** (日本語) 한 문장으로, 플러그인이 도메인 설명을 에이전트 팀과 그들이 쓸 스킬로 변환합니다 — 사전 정의된 6가지 팀 아키텍처 패턴 중 하나를 골라서요. diff --git a/README_ZH.md b/README_ZH.md new file mode 100644 index 0000000..dccd5c5 --- /dev/null +++ b/README_ZH.md @@ -0,0 +1,303 @@ +

+ Harness Banner +

+ +

+ Version + License + Claude Code Plugin + 6 Architecture Patterns + Agent Teams + GitHub Stars +

+ +

+ Layer + Sub-layer + i18n +

+ +# Harness — Claude Code 的团队架构工厂 + +[English](README.md) | [한국어](README_KO.md) | [日本語](README_JA.md) | **中文** + +> **Harness 是面向 Claude Code 的团队架构工厂。** 只需说一句 **"build a harness for this project"**（English）、**"하네스 구성해줘"**（한국어）、**"ハーネスを構成して"**（日本語）或 **"帮我配置 harness"**（中文），插件就会把你的领域描述转化为一支 agent team 以及它们所用的 skill —— 从六种预定义的团队架构模式中挑选其一。 + +## 概述 + +Harness 借助 Claude Code 的 agent team 系统，把复杂任务分解为协同工作的专家 agent 团队。说一句 "build a harness for this project"，它就会自动生成贴合你领域的 agent 定义（`.claude/agents/`）与 skill（`.claude/skills/`）。 + +## 类别 — Harness 所处的位置 + +Harness 位于 Claude Code 生态的 **L3 Meta-Factory** 层 —— 这一层生成其他 harness，而非自身作为一个 harness。在 L3 内部，我们选择了一个具体的子层：**Team-Architecture Factory**。 + +| 层级 | 它做什么 | 共存的邻居 | +|-------|--------------|---------------------------| +| **L3 — Meta-Factory / Team-Architecture Factory**（我们） | 一句领域描述 → agent team + skill，经由 6 种预定义团队模式 | — | +| L3 — Meta-Factory / Runtime-Configuration Factory | 确定性、可复现的运行时配置 | [coleam00/Archon](https://github.com/coleam00/Archon) | +| L3 — Meta-Factory / Codex Runtime Port | 相同理念，Codex 运行时 | [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) | +| L2 — Cross-Harness Workflow | 在多个 harness 之间统一 skill/规则/hook | [affaan-m/ECC](https://github.com/affaan-m/everything-claude-code) | + +> Archon 生成确定性的运行时配置。Harness 生成团队架构（pipeline、fan-out/fan-in、expert pool、producer-reviewer、supervisor、hierarchical delegation）以及 agent 所用的 skill。二者是同属 L3 的不同子层。需要运行时确定性就选 Archon，需要团队架构就选 Harness，也可以组合使用。 + +## Star History + + + + + + Star History Chart + + + + +## 核心特性 + +- **Agent Team 设计** —— 6 种架构模式：Pipeline、Fan-out/Fan-in、Expert Pool、Producer-Reviewer、Supervisor、Hierarchical Delegation +- **Skill 生成** —— 自动生成带 Progressive Disclosure 的 skill，实现高效的上下文管理 +- **编排（Orchestration）** —— agent 间数据传递、错误处理与团队协调协议 +- **校验（Validation）** —— 触发验证、dry-run 测试，以及「带 skill / 不带 skill」对比测试 + + +## 工作流 + +``` +Phase 1: 领域分析 + ↓ +Phase 2: 团队架构设计（Agent Team vs Subagent） + ↓ +Phase 3: 生成 Agent 定义（.claude/agents/） + ↓ +Phase 4: 生成 Skill（.claude/skills/） + ↓ +Phase 5: 集成与编排 + ↓ +Phase 6: 校验与测试 +``` + +## 安装 + +### 通过 Marketplace 安装 + +#### 添加 marketplace +```shell +/plugin marketplace add revfactory/harness +``` + +#### 安装插件 +```shell +/plugin install harness@harness-marketplace +``` + +### 作为全局 Skill 直接安装 + +```shell +# 将 skills 目录复制到 ~/.claude/skills/harness/ +cp -r skills/harness ~/.claude/skills/harness +``` + +## 插件结构 + +``` +harness/ +├── .claude-plugin/ +│ └── plugin.json # 插件清单 +├── skills/ +│ └── harness/ +│ ├── SKILL.md # 主 skill 定义（6-Phase 工作流） +│ └── references/ +│ ├── agent-design-patterns.md # 6 种架构模式 +│ ├── orchestrator-template.md # 团队/subagent 编排模板 +│ ├── team-examples.md # 5 个真实团队配置 +│ ├── skill-writing-guide.md # Skill 编写指南 +│ ├── skill-testing-guide.md # 测试与评估方法论 +│ └── qa-agent-guide.md # QA agent 集成指南 +└── README.md +``` + +## 用法 + +在 Claude Code 中用类似下面的提示触发： + +``` +Build a harness for this project +Design an agent team for this domain +Set up a harness +帮我配置 harness +``` + +### 执行模式 + +| 模式 | 说明 | 推荐场景 | +|------|-------------|-----------------| +| **Agent Team**（默认） | TeamCreate + SendMessage + TaskCreate | 需要 2 个以上 agent 协作 | +| **Subagent** | 直接调用 Agent 工具 | 一次性任务，无需 agent 间通信 | + +

+ Harness Agent Team +

+ +### 架构模式 + +| 模式 | 说明 | +|---------|-------------| +| Pipeline | 顺序、相互依赖的任务 | +| Fan-out/Fan-in | 并行、相互独立的任务 | +| Expert Pool | 依上下文选择性调用 | +| Producer-Reviewer | 先生成，再做质量评审 | +| Supervisor | 中心 agent 动态分配任务 | +| Hierarchical Delegation | 自顶向下递归委派 | + +## 产出 + +Harness 生成的文件： + +``` +your-project/ +├── .claude/ +│ ├── agents/ # Agent 定义文件 +│ │ ├── analyst.md +│ │ ├── builder.md +│ │ └── qa.md +│ └── skills/ # Skill 文件 +│ ├── analyze/ +│ │ └── SKILL.md +│ └── build/ +│ ├── SKILL.md +│ └── references/ +``` + +## 应用场景 —— 试试这些提示 + +安装 Harness 后，把下面任意提示复制到 Claude Code 中： + +**深度调研（Deep Research）** +``` +Build a harness for deep research. I need an agent team that can investigate +any topic from multiple angles — web search, academic sources, community +sentiment — then cross-validate findings and produce a comprehensive report. +``` + +**网站开发** +``` +Build a harness for full-stack website development. The team should handle +design, frontend (React/Next.js), backend (API), and QA testing in a +coordinated pipeline from wireframe to deployment. +``` + +**Webtoon / 漫画制作** +``` +Build a harness for webtoon episode production. I need agents for story +writing, character design prompts, panel layout planning, and dialogue +editing. They should review each other's work for style consistency. +``` + +**YouTube 内容策划** +``` +Build a harness for YouTube content creation. The team should research +trending topics, write scripts, optimize titles/tags for SEO, and plan +thumbnail concepts — all coordinated by a supervisor agent. +``` + +**代码评审与重构** +``` +Build a harness for comprehensive code review. I want parallel agents +checking architecture, security vulnerabilities, performance bottlenecks, +and code style — then merging all findings into a single report. +``` + +**技术文档** +``` +Build a harness that generates API documentation from this codebase. +Agents should analyze endpoints, write descriptions, generate usage +examples, and review for completeness. +``` + +**数据管线设计** +``` +Build a harness for designing data pipelines. I need agents for schema +design, ETL logic, data validation rules, and monitoring setup that +delegate sub-tasks hierarchically. +``` + +**营销活动** +``` +Build a harness for marketing campaign creation. The team should research +the target market, write ad copy, design visual concepts, and set up +A/B test plans with iterative quality review. +``` + +## 共存 —— Harness 与它的邻居 + +在 Claude Code / agent 框架生态里，Harness 并不孤单。以下仓库分布在相邻层级；每一项都以并列的「X 是……，Harness 是……」形式描述，方便你挑选合适的一个，或组合多个使用。 + +| 仓库 | 它的定位 | 与 Harness 的关系 | +|------|----------------|-------------------------| +| [coleam00/Archon](https://github.com/coleam00/Archon) | "harness builder" —— 确定性、可复现的运行时配置 | **同属 L3，邻接子层。** Archon 是 Runtime-Configuration Factory，Harness 是 Team-Architecture Factory。需要运行时确定性选 Archon，需要团队架构选 Harness，或组合使用。 | +| [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) | 相同理念的 Codex 移植版 | **同属 L3，不同运行时。** 在 Claude Code 上用 Harness，在 Codex 上用 meta-harness。 | +| [affaan-m/ECC](https://github.com/affaan-m/everything-claude-code) | "Agent harness 性能与工作流层"（位于现有 harness 之上） | **不同层级。** ECC 是跨 harness 的标准化层；Harness 是生成 harness 的工厂。可串联组合。 | +| [wshobson/agents](https://github.com/wshobson/agents) | Subagent / skill 目录（182 个 agent，149 个 skill） | **工厂 ↔ 零件供应。** wshobson 是可选购的目录；Harness 设计团队。把 wshobson 的条目作为零件吸收进 Harness 生成的团队中。 | +| [LangGraph](https://langchain-ai.github.io/langgraph/) | 状态图编排，与 LLM 无关 | **不同赛道。** LangGraph 面向长时运行、状态可恢复的编排；Harness 面向快速、Claude-Code 原生的团队设计。 | + +## 用 Harness 构建的成果 + +### Harness 100 + +**[revfactory/harness-100](https://github.com/revfactory/harness-100)** —— 覆盖 10 个领域的 100 个生产级 agent team harness，提供英文与韩文两版（共 200 个包）。每个 harness 配有 4-5 个专家 agent、一个 orchestrator skill 以及领域专属 skill —— 全部由本插件生成。1808 个 markdown 文件，涵盖内容创作、软件开发、数据/AI、商业战略、教育、法律、健康等领域。 + +### 研究：Harness 有效性的 A/B 测试 + +**[revfactory/claude-code-harness](https://github.com/revfactory/claude-code-harness)** —— 一项覆盖 15 个软件工程任务的对照实验，衡量结构化预配置对 LLM 代码 agent 产出质量的影响。 + +| 指标 | 不用 Harness | 用 Harness | 提升 | +|--------|:-:|:-:|:-:| +| 平均质量分 | 49.5 | 79.3 | **+60%** | +| 胜率 | — | — | **100%**（15/15） | +| 产出方差 | — | — | **-32%** | + +关键发现：有效性随任务复杂度递增 —— 任务越难，提升越大（Basic +23.8，Advanced +29.6，Expert +36.2）。 + +**各处统一使用的表述：** +60% 平均质量（49.5 → 79.3）、15/15 胜率、−32% 方差（n=15，作者自测 A/B，第三方复现待补）。 + +> 完整论文：*Hwang, M. (2026). Harness: Structured Pre-Configuration for Enhancing LLM Code Agent Output Quality.* + +## 依赖要求 + +- [启用 Agent Teams](https://code.claude.com/docs/en/agent-teams)：`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` + +## 常见问题（FAQ） + +
+Q1. "+60%" 是不是夸大了？ + +**答：** +60% 这个数字来自**作者自测的 A/B（n=15，15 个任务，在姊妹仓库 `claude-code-harness` 上测量）**。本仓库中每一处引用都在同一句里附上披露说明「n=15，作者自测，第三方复现待补」。对于采纳决策，我们建议先做 2-4 周的内部试点，测量你自己的数据。 + +**证据：** +- 作者 A/B：[revfactory/claude-code-harness](https://github.com/revfactory/claude-code-harness) +- 论文：*Hwang, M. (2026). Harness: Structured Pre-Configuration for Enhancing LLM Code Agent Output Quality* +
+ +
+Q2. 为什么是 "harness factory" 而不是 "harness builder"？这不是在和 Archon 竞争吗？ + +**答：** Archon 生成确定性的运行时配置 —— 它是 **Runtime-Configuration Factory**。Harness 生成 agent team 架构（团队结构、消息协议、评审关卡）—— 它是 **Team-Architecture Factory**。二者是**同属一个 L3 Meta-Factory 的邻接子层**，服务于不同需求。需要运行时确定性选 Archon，需要团队架构模式选 Harness，或组合使用（用 Harness 设计架构 → 用 Archon 部署运行时）。 + +**证据：** +- Archon 的自我定义：[clawfit docs/reference-levels.md](https://github.com/hongsw/clawfit/blob/main/docs/reference-levels.md) +- 子层声明：见上文 **类别 — Harness 所处的位置** 一节 +- Archon 仓库：[github.com/coleam00/Archon](https://github.com/coleam00/Archon) +
+ +
+Q3. "仅支持 Claude Code" 是不是太窄了？Gemini/Codex 怎么办？ + +**答：** 目前官方运行时仅支持 Claude Code。相同理念的 Codex 移植版 —— [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) —— 已经公开，Codex 团队可以从那里开始。Harness 选择了「Claude-Code 原生、深入」而非「多运行时、浅尝」；与姊妹仓库（meta-harness、harness-init、OpenRig）的跨运行时协作已列入路线图。 + +**证据：** +- Codex 移植版：[github.com/SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) +- 跨运行时脚手架：[github.com/Gizele1/harness-init](https://github.com/Gizele1/harness-init) +
+ +## 许可证 + +Apache 2.0 diff --git a/docs/experimental-dependency_ZH.md b/docs/experimental-dependency_ZH.md new file mode 100644 index 0000000..653de61 --- /dev/null +++ b/docs/experimental-dependency_ZH.md @@ -0,0 +1,153 @@ +# 实验性开关依赖 + +> **状态：** Active · **负责人：** revfactory · **最后更新：** 2026-04-18 · **SLA：** 见 [监控承诺](#监控承诺) + +本文档解释 `harness` 为何需要 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`、该开关三种可能的未来，以及本仓库在每种情况下会做什么 —— 并给出限时承诺，便于企业采纳者据此规划。 + +--- + +## 当前状态 + +### 为何需要这个开关 + +`harness` 是一个构建于 Claude Code **Agent Teams API** 之上的元 skill 工厂。每当用户运行 `claude "build a harness for "` 时，内部会调用三个 Claude Code 原语： + +| 原语 | 用途 | 是否受开关限制 | +|-----------|---------|-------------| +| `TeamCreate` | 实例化一支共享上下文的多 agent 团队 | **是** | +| `SendMessage` | 在团队成员间路由消息（supervisor ↔ worker） | **是** | +| `TaskCreate` | 在团队内派生长时运行的子任务 | **是** | +| `Agent` 工具（invoke） | 单 agent 派发 | 否（GA） | + +这三个受开关限制的原语都要求： + +```bash +export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 +``` + +如果启动 `claude` 的 shell 中未设置该变量，harness 生成的团队会回退为单 agent 执行，从而悄然破坏 Pipeline / Fan-out-in / Supervisor / Hierarchical Delegation 模式。 + +### Anthropic 参考资料（提交 issue 前必读） + +该开关的设计理由与路线图见三篇 Anthropic Engineering 博文。评估 harness 的采纳者至少应阅读第一篇： + +1. [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) —— 定义了 Anthropic 认可的 "harness" 类别与长时运行 agent 契约。 +2. [Harness design for long-running apps](https://www.anthropic.com/engineering/harness-design-long-running-apps) —— `harness` 所固化的模式（Pipeline、Producer-Reviewer、Supervisor 等）。 +3. [Scaling Managed Agents](https://www.anthropic.com/engineering/managed-agents) —— 可能取代实验性开关的前进路径（见场景 B）。 + +--- + +## 依赖图 + +``` +harness (v1.2.0) + └── Agent Teams API (Claude Code) + ├── TeamCreate ← EXPERIMENTAL_AGENT_TEAMS=1 + ├── SendMessage ← EXPERIMENTAL_AGENT_TEAMS=1 + ├── TaskCreate ← EXPERIMENTAL_AGENT_TEAMS=1 + └── Agent (invoke) ← GA (与开关无关) + └── Anthropic Roadmap + ├── Scenario A: Flag removed (GA promotion) + ├── Scenario B: Managed Agents GA (parallel path) + └── Scenario C: Breaking signature change +``` + +**自顶向下阅读此图：** harness 依赖 Agent Teams API，后者依赖单个实验性开关，而该开关又依赖 Anthropic 自己的路线图。任一上游节点变化时，本仓库都有义务在下文 SLA 内适配。 + +--- + +## 3 种场景 + +每种场景都列出**检测触发条件**（我们如何得知它发生）、本仓库承诺的 **T+24h / T+48h / T+72h 行动**，以及每个检查点的**用户可见产物**。 + +### 场景 A —— 开关移除（Agent Teams 晋升 GA） + +**触发检测：** Anthropic Claude Code Changelog 发布 "Agent Teams is now GA"，**或** `claude-code` 二进制不再需要 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`（由 [P-13](#) 的 nightly CI 检测）。 + +**概率（主观）：** 高 —— 这是上述三篇博文所预示的路径。 + +| 检查点 | 行动 | 产物 | +|------------|--------|----------| +| **T+24h** | 开 `feat/drop-experimental-flag` 分支。从每个 README / docs / Quickstart 移除 `export` 行。在 `plugin.json` 中加入 `claude-code >= X.Y.Z` 下界。 | 分支 + PR（草稿） | +| **T+48h** | 发布 `docs/migrating-from-experimental.md`。把 `docs/experimental-dependency.md`（本文件）标题更新为 "no flag required as of vX.Y"。置顶 GitHub issue："Action required: drop the export line"。 | 迁移指南 + 置顶 issue | +| **T+72h** | 发布 **v1.3.0**，包含：(a) CHANGELOG 条目，(b) 带迁移说明的 `gh release create`，(c) HN 跟进帖："We dropped the experimental flag"。 | `v1.3.0` git tag + GH Release | + +**采纳者影响：** 正面。企业审批阻力下降 —— "无实验性开关" 这一勾选项变得可满足。对 harness 用户代码无破坏性变更。 + +--- + +### 场景 B —— Managed Agents 进入 GA（并行路径） + +**触发检测：** Anthropic 发布 "[Managed Agents](https://www.anthropic.com/engineering/managed-agents) is generally available"，并提供稳定的 `claude-agents` CLI 或 SDK 接口。 + +**概率（主观）：** 90 天内中-高。Managed Agents 是服务端执行模型；harness 的客户端团队编排**不会**自动迁移过去。 + +| 检查点 | 行动 | 产物 | +|------------|--------|----------| +| **T+24h** | 开 `feat/managed-agents-compat` PR。加入 `adapters/managed-agents/` 脚手架，把 harness 的 6 种团队模式映射到 Managed Agents 调用。识别不兼容的模式（很可能是 Hierarchical Delegation）。 | 兼容 PR（草稿） | +| **T+48h** | 发布博文：**"Harness + Managed Agents: one layer up, not replaced"**，发于 Dev.to 与本仓库。把 harness 重新定位为输出 Managed Agents 配置的**设计期**层，而非运行时竞品。 | 共存定位博文 | +| **T+72h** | 发布 `docs/managed-agents-migration.md`，附逐模式矩阵（6 种模式中哪些 1:1 映射、哪些需重写）。更新 README 姊妹仓库一节。 | 迁移指南 | + +**战略说明：** harness 重新定位为 Managed Agents **之上的层** —— "Managed Agents 运行团队，harness 设计团队"。这是 GTM 计划 §4.2 中的共存框架。 + +**采纳者影响：** 中性偏正面。现有 harness 用户继续在实验性开关路径上工作；新用户可选择 Managed Agents 输出。 + +--- + +### 场景 C —— 破坏性变更（API 签名突变） + +**触发检测：** Nightly CI（`.github/workflows/nightly-compat.yml`，路线图编号 P-13）对 Claude Code 最新 nightly 构建运行失败，**或** Changelog 宣布重命名的环境变量 / 变更的 `TeamCreate` 签名。 + +**概率（主观）：** 中。实验性 API 可能在无弃用窗口的情况下被重命名。 + +| 检查点 | 行动 | 产物 | +|------------|--------|----------| +| **T+0 至 T+24h** | Nightly CI 在 Slack/Discord 告警。作者开 `hotfix/compat-` 分支，修补受影响的调用点。在新旧签名上单测通过（尽力而为）。 | Hotfix 分支 | +| **T+24h** | 合并 hotfix。推 `v1.2.x` 补丁 tag。更新 `docs/compatibility-matrix.md` 中受影响 Claude Code 版本的行。 | `v1.2.x` 补丁发布 | +| **T+72h** | 若变更非平凡（影响 harness 的公共契约），在仓库 Discussions 标签页 + X 发布简短通告。否则一条 CHANGELOG 条目即可。 | Discussions 帖（视情况） | + +**采纳者影响：** 固定在旧版 Claude Code 的现有用户不受影响。使用最新版的用户会在同一周内获得补丁。 + +--- + +## 监控承诺 + +我们承诺以下**可观测 SLA**。未达成即构成提交带 `sla-breach` 标签 issue 的理由。 + +| 事件 | SLA | 度量方式 | +|-------|-----|-------------| +| Anthropic 在官方 Changelog 发布 Agent Teams / Managed Agents 变更 | 本文档在 **72 小时**内更新 | 对比 Changelog 帖时间戳与本文件 `最后更新` 行 | +| Nightly CI 检测到兼容性破坏 | **24 小时**内开 hotfix 分支 | GitHub Actions 运行时间戳 vs. 分支创建时间戳 | +| 新的 Claude Code 稳定版（minor 或 major） | **7 天**内为 `docs/compatibility-matrix.md` 添加对应行 | 兼容性矩阵 diff | + +**我们主动监控的来源：** + +- Claude Code 发布说明 —— 通过 [Anthropic Engineering 博客](https://www.anthropic.com/engineering) RSS 关注 +- `anthropics/claude-code` GitHub Releases（nightly tag） +- Anthropic Discord `#claude-code` 频道（社区信号） + +--- + +## 企业采纳者 FAQ + +### Q1. 我们处于受监管行业（金融、医疗、公共部门），无法在生产中启用 `EXPERIMENTAL` 开关。如何采纳 harness？ + +**原因：** 许多合规框架（SOC 2 Type II、ISO 27001、K-ISMS）禁止在生产中使用不稳定 / 预览特性。 +**行动：** **仅在设计期**使用 harness：在沙箱工作站上运行它来生成 `.claude/agents/` 与 `.claude/skills/` 文件，然后把生成的产物提交进你的生产仓库。生产环境的 Claude Code 永远不需要这个开关 —— 只有受开关限制的 `TeamCreate` 运行时才需要。生成的单 agent skill 与 GA 路径兼容。 + +### Q2. 如果 Agent Teams 进入 GA（场景 A），我现有的 harness 生成代码会坏吗？ + +**原因：** 在 Anthropic 的 Claude Code 中，GA 晋升对生成产物历来是非破坏性的；只是该开关不再被要求而已。 +**行动：** 终端用户无需任何操作。你的 `.claude/agents/*.md` 与 `.claude/skills/*` 文件是纯 Markdown，仍然有效。GA 当天你即可 `unset CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`。我们会在 48 小时内发布迁移说明（见场景 A）。 + +### Q3. 你们有书面 SLA 保证吗？如果没达成会怎样？ + +**原因：** 企业在审批前需要一份合同级、或至少可观测的承诺。 +**行动：** 上方 SLA 表即为**公开承诺**，由以下机制保障：(a) 一个 GitHub Action，在检测到 Changelog 事件 72 小时后若本文件 `最后更新` 行仍未更新则在本文件下评论，(b) 采纳者可施加的 `sla-breach` issue 标签，(c) `CONTRIBUTING.md` 中对任何违约的事后复盘义务。这不是付费 SLA —— 而是社区承诺。如需付费 SLA，请联系维护者（见仓库 README）。 + +--- + +**相关文档：** +- [`docs/quickstart.md`](./quickstart.md) —— 5 分钟安装演练 +- [`docs/show-hn-launch-kit.md`](./show-hn-launch-kit.md) —— 公开发布套件 +- `docs/compatibility-matrix.md` *（待补，P-13）* —— Claude Code × harness 版本对照表 diff --git a/docs/quickstart_ZH.md b/docs/quickstart_ZH.md new file mode 100644 index 0000000..b091044 --- /dev/null +++ b/docs/quickstart_ZH.md @@ -0,0 +1,118 @@ +# 快速上手 —— 5 分钟构建你的第一个 Harness + +> **时间预算：5 分钟（严格）。** 如果 5 分钟内你还没走到 Step 5，请停下并提交 issue —— 那是本文档的 bug，不是你的问题。 + + + +**结束时你将拥有：** 一个可用的 `.claude/agents/` 目录，里面有 3-5 个领域专精的 agent —— 由一句话提示生成，可直接在示例任务上运行。 + +**前置条件（开始前请确认）：** +- Claude Code **v2.x 或更高版本**（`claude --version` 应返回 `2.x` 或更高） +- 一个能跨命令保留 `export` 的 shell（bash、zsh 或 fish） +- 可访问 `github.com` 与 `api.anthropic.com` 的网络 + +--- + +## Step 1 —— 添加 marketplace（60 秒） + +```bash +claude plugin marketplace add revfactory/harness +``` + +**作用：** 注册 `harness` marketplace，使 Claude Code 能发现 `revfactory` 发布的插件。 + +**预期输出：** `Added marketplace: revfactory/harness` + +--- + +## Step 2 —— 安装插件并启用实验性开关（40 秒） + +```bash +claude plugin install harness@harness +export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 +``` + +*（要让该开关在多个 shell 会话间持久生效，把 `export` 这一行追加到 `~/.zshrc` 或 `~/.bashrc`。）* + +**作用：** 从 `harness` marketplace 安装 `harness` 插件，然后启用 Agent Teams —— harness 用来编排多 agent 工作流的 Claude Code API。开关为何必需，见 [`docs/experimental-dependency.md`](./experimental-dependency.md)。 + +**失败 FAQ #1 —— `AGENT_TEAMS not found` / team 无法实例化** +**原因：** Claude Code 版本低于 v2.x（Agent Teams 在 v2.0 引入）。 +**修复：** 运行 `claude --version`。若低于 2.0，通过 `npm i -g @anthropic-ai/claude-code`（或你所用发行版的安装器）升级，然后重复 Step 2。 + +--- + +## Step 3 —— 用一句话生成一个 harness（2 分钟） + +```bash +claude "build a harness for a fintech risk-assessment team" +``` + +**作用：** 调用 `/harness:harness` 元 skill，它会分析你的领域描述，并把一支专精 agent 团队 + 它们的 skill 脚手架写入当前目录的 `.claude/agents/` 与 `.claude/skills/`。 + +**试试这些替代提示** —— 任意一条都有效： +- `claude "帮我配置 harness —— 金融科技风险评估团队"`（中文同样有效） +- `claude "하네스 구성해줘 — 핀테크 리스크 평가 팀"`（韩文同样有效） +- `claude "build a harness for an e-commerce fraud-detection workflow"` +- `claude "design an agent team for technical due diligence on open-source repos"` + +**预期输出：** 一段流式计划，随后确认已写出 3-5 个 agent `.md` 文件及其 skill。 + +**失败 FAQ #2 —— 中文/韩文提示无响应，而英文提示成功** +**原因：** 区域设置或分词器误路由；harness 的 orchestrator 基于触发词匹配（如韩文「하네스 구성」），这些触发词内建于 skill 定义中。 +**修复：** 若非英文提示失败，用上面的英文提示重试 —— 底层 skill 完全相同。若都失败，跳到失败 FAQ #3。 + +--- + +## Step 4 —— 校验生成的文件（30 秒） + +```bash +ls -la .claude/agents/ +ls -la .claude/skills/ +``` + +**作用：** 确认元 skill 已把文件写入预期位置。 + +**预期输出：** 每个目录 3-5 个文件，文件名反映你的领域（如金融科技示例中的 `risk-analyst.md`、`compliance-reviewer.md`、`portfolio-monitor.md`）。 + +**失败 FAQ #3 —— "什么都没生成" / 目录为空** +**原因：** 插件实际未安装，或在当前项目中未激活。 +**修复：** 运行 `claude plugin list`。若没有 `harness@harness`，重复 Step 2。若存在但未激活，运行 `claude plugin enable harness@harness`，然后重复 Step 3。 + +--- + +## Step 5 —— 让新团队跑一个示例任务（90 秒） + +复制一条贴近真实的 Jira-工单式提示，交给你刚生成的团队： + +```bash +claude "Ticket FIN-427: A new corporate customer (mid-cap manufacturer, \$80M revenue, South Korea) has applied for a \$5M working-capital line. Produce a risk assessment covering (1) credit-history red flags, (2) sector concentration vs. our existing book, (3) regulatory exposure (KFTC, FSC). Output: a 1-page memo with a go/no-go recommendation." +``` + +**作用：** Claude Code 检测到 `.claude/agents/` 中的新 agent，按 harness 生成的团队模式（风险类工作通常是 Producer-Reviewer 或 Expert-Pool）路由任务，并返回一份结构化备忘录。 + +**失败 FAQ #4 —— "团队不执行 / 只有一个 agent 响应"** +**原因：** `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 在运行 Step 3 的 shell 中设置了，但运行 Step 5 的 shell 中没有（新开终端时常见）。 +**修复：** 在当前 shell 重新 export：`export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`，然后重跑 Step 5。要永久生效，把该行加入你的 shell rc 文件。 + +**失败 FAQ #5 —— "API 调用太多 / 成本焦虑"** +**原因：** 多 agent 团队每个任务可能扇出 5 个以上并行 Claude 调用。单个复杂工单可消耗 50K-200K token。 +**修复：** 每次运行限制为单个任务（不要用 `&&` 串联多次 harness 调用），若你的 Claude Code 版本支持，使用 `--max-turns` 标志。生产环境中，把 harness 调用置于成本感知的包装层之后 —— 见 `docs/cost-controls.md` *（待补）*。 + +--- + +## 完成 + +到这一步，你应该已经拥有： + +- [x] 一个含领域专精 agent 的 `.claude/agents/` 目录 +- [x] 一个含其支撑 skill 的 `.claude/skills/` 目录 +- [x] 一次成功的示例任务执行 +- [x] 一个可用的 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 环境 + +**下一步阅读：** +- [`docs/experimental-dependency.md`](./experimental-dependency.md) —— 为何需要这个开关，以及它变化时我们会怎么做 +- [`revfactory/harness-100`](https://github.com/revfactory/harness-100) —— 100+ 预构建领域 harness 的目录，若你更想克隆而非生成 +- [`revfactory/claude-code-harness`](https://github.com/revfactory/claude-code-harness) —— 我们用来在 15 个任务上测得 +60% 质量的 A/B 测试 harness + +**如果你遇到本指南未覆盖的问题：** 提交一个带 `quickstart-gap` 标签的 issue，并附上：(a) 哪一步失败，(b) `claude --version`，(c) 准确的错误信息。quickstart-gap issue 的首次响应 SLA 为 **48 小时**（见 `CONTRIBUTING.md`）。