<h1 align="center">Epic Harness</h1>

<blockquote><p align="center">一个自我进化的 AI 编程智能体框架 — 8 条命令、1 条自主流水线、自动触发技能，从你的失败中学习。</p></blockquote>

<p align="center"><b>更少的记忆负担。每次按键更多的智能。每次会话都在变得更聪明。</b></p>

<p align="center">
<a href="../../README.md">English</a> | <a href="../ja/README.md">日本語</a> | <a href="../ko/README.md">한국어</a> | <a href="../de/README.md">Deutsch</a> | <a href="../fr/README.md">Français</a> | 简体中文 | <a href="../zh-TW/README.md">繁體中文</a> | <a href="../pt-BR/README.md">Português</a> | <a href="../es/README.md">Español</a> | <a href="../hi/README.md">हिन्दी</a>
</p>

<p align="center">
  <a href="https://github.com/epicsagas/epic-harness/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/epicsagas/epic-harness?style=for-the-badge&labelColor=0d1117&color=ffd700&logo=github&logoColor=white" /></a>
  <a href="https://github.com/epicsagas/epic-harness/network/members"><img alt="Forks" src="https://img.shields.io/github/forks/epicsagas/epic-harness?style=for-the-badge&labelColor=0d1117&color=2ecc71&logo=github&logoColor=white" /></a>
  <a href="https://github.com/epicsagas/epic-harness/issues"><img alt="Issues" src="https://img.shields.io/github/issues/epicsagas/epic-harness?style=for-the-badge&labelColor=0d1117&color=ff6b6b&logo=github&logoColor=white" /></a>
  <a href="https://github.com/epicsagas/epic-harness/commits/main"><img alt="Last commit" src="https://img.shields.io/github/last-commit/epicsagas/epic-harness?style=for-the-badge&labelColor=0d1117&color=58a6ff&logo=git&logoColor=white" /></a>
</p>
<p align="center">
  <a href="../../LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-3fb950?style=for-the-badge&labelColor=0d1117" /></a>
  <img alt="Version" src="https://img.shields.io/badge/version-0.4.0-fc8d62?style=for-the-badge&labelColor=0d1117" />
  <img alt="Rust" src="https://img.shields.io/badge/rust-1.82+-d73a49?style=for-the-badge&labelColor=0d1117&logo=rust&logoColor=white" />
  <img alt="Claude Code" src="https://img.shields.io/badge/Claude_Code-plugin-bc8cff?style=for-the-badge&labelColor=0d1117" />
  <a href="https://buymeacoffee.com/epicsaga"><img alt="Buy Me a Coffee" src="https://img.shields.io/badge/buy_me_a_coffee-FFDD00?style=for-the-badge&labelColor=0d1117&logo=buymeacoffee&logoColor=black" /></a>
</p>

一个 Claude Code 插件，**将 30+ 条命令精简为 8 条**，根据你正在做的事情**自动触发技能**，并从你的失败模式中**进化出新的技能**。

<p align="center">
  <img src="./assets/features.png" alt="epic harness 功能特性" width="100%" />
</p>

---

![Demo](../../docs/demo/demo.gif)

### Web 控制面板 — 10 屏实时指标
<p align="center">
  <img src="../../assets/dashboard.png" alt="Dashboard" width="49%" />
  <img src="../../assets/dashboard-orbit.png" alt="Orbit Pipeline" width="49%" />
</p>

---

## 它做什么

一条命令即可端到端交付功能。技能无需你主动调用即可触发。智能体在每次会话后变得更聪明。

```bash
$ /orbit "为登录 API 添加 JWT 认证"
→ spec 已批准 → go（TDD 子智能体） → check（通过） → ship（PR + CI） → evolve
```

或者手动逐步执行：

```bash
/spec "为登录 API 添加 JWT 认证"   # 明确需求 → SPEC-*.md
/go                                  # 自动规划 → TDD 子智能体 → 4 分钟
/check                               # 并行审查 + 安全审计 + 测试 → 通过
/ship                                # 隔离测试 → PR → CI 通过
```

技能在后台自动触发 — 无需额外命令：

```
正在编写功能？    → tdd 触发（强制执行 Red→Green→Refactor）
测试失败？        → debug 触发（优先根因分析，不盲目修复）
涉及认证或数据库？  → secure 触发（OWASP 检查清单，不走捷径）
文件超过 200 行？  → simplify 触发（提取、重命名、精简）
```

会话结束后，**evolve 循环**分析出错的原因，生成针对性技能，并在下次会话时加载。之前在 TypeScript 构建失败中挣扎的智能体，下次将拥有一个 `evo-ts-care` 技能。

---

## 安装

> **首次使用？** 阅读[快速入门指南（5 分钟）](../../docs/quickstart.md)。

### Claude Code（推荐）

```
/plugin marketplace add epicsagas/plugins
/plugin install epic@epicsagas
```

自动安装二进制文件并一步注册所有 hooks。

### macOS / Linux

```bash
brew install epicsagas/tap/epic-harness
```

没有 Homebrew？使用安装脚本：

```bash
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/epicsagas/epic-harness/releases/latest/download/epic-harness-installer.sh | sh
```

### Windows

```powershell
irm https://github.com/epicsagas/epic-harness/releases/latest/download/epic-harness-installer.ps1 | iex
```

### 通过 Rust 工具链

```bash
cargo binstall epic-harness   # 预编译二进制（快速）
cargo install epic-harness    # 从源码构建
```

然后运行安装向导：

```bash
epic install          # Claude Code（默认）
epic install codex    # Codex CLI
epic install gemini   # Gemini CLI
```

> 使用 `epic-harness --version` 验证。通过 `brew upgrade epic-harness` 或重新运行安装脚本来更新。

前置条件：**Git**。源码/二进制安装还需要 [Rust 工具链](https://rustup.rs)。

### `epic install` — 安装向导

安装二进制文件后，运行 `epic install`（或 `epic install claude`）来：

1. 创建 `~/.harness/` 目录结构
2. 同步命令、技能和智能体到工具的配置目录
3. 注册 MCP 服务器（harness-mem）用于 Claude Code
4. 如不存在则创建带默认值的 `~/.harness/config.toml`

在 Claude Code 中，`hooks/setup.sh` 在会话启动时自动运行，并在二进制文件缺失时安装。初始克隆后无需手动步骤。

### 其他工具

```bash
epic install codex        # Codex CLI   → ~/.codex/ + ~/.agents/skills/
epic install gemini       # Gemini CLI  → ~/.gemini/
epic install cursor       # Cursor      → ~/.cursor/（需要 Cursor 1.7+）
epic install opencode     # OpenCode    → ~/.config/opencode/
epic install cline        # Cline       → ~/Documents/Cline/Rules/
epic install aider        # Aider       → ~/.aider.conf.yml + ~/.aider/
epic install              # 交互式菜单
```

集成文件从二进制文件**同步**：缺失或过期的文件会被写入。`GEMINI.md` 和 `AGENTS.md` 仅在不存在时创建。

### 验证

```bash
epic --version              # 二进制已安装
ls ~/.harness/              # 数据目录存在
```

在 Claude Code 会话中：`/evolve status`

---

## 命令

| 命令 | 功能说明 |
|---------|-------------|
| `/orbit` | **完整自主流水线**：一次性完成 spec → go → check → ship → evolve |
| `/discover` | 先框定问题 — 5 Whys、JTBD、苏格拉底式提问（最多 3 轮） |
| `/spec` | 将需求转化为带编号的 R + AC 文档，保存为 `SPEC-{timestamp}.md` |
| `/go` | 自动规划 → TDD 子智能体 → 并行执行（worktree 隔离） → AC 验证 |
| `/check` | 并行审查 + 安全审计 + 测试，附带基于范围的额外检查（API 契约、无障碍、迁移安全） |
| `/ship` | 在干净 worktree 中隔离预检测试 → 带完整检查报告的 PR → CI 监控 + 自动修复 |
| `/team` | 浏览组织库、雇佣现有团队或设计新团队（3-6 个智能体，同步到 `.claude/agents/`） |
| `/evolve` | 手动进化触发 — 分析会话、查看仪表板、检查技能效果、回滚 |

---

## /orbit — 自主流水线

`/orbit` 将整个流水线封装为一次自主执行。选择一个模式 — 之后直到创建 PR 之前完全无需干预。

```mermaid
flowchart TD
    START(["/orbit"]) --> MODE{"requirement?"}:::human
    MODE -->|"unclear"| WAIT["Interactive\n/discover → /spec\nthen 'orbit go'"]:::human
    MODE -->|"clear + complex"| COUNCIL["Council\n4-voice auto-spec"]:::auto
    MODE -->|"clear + simple"| DIRECT["Direct\nauto-spec"]:::auto
    WAIT --> SPEC_LOAD["Load spec"]
    COUNCIL --> SPEC_LOAD
    DIRECT --> SPEC_LOAD
    SPEC_LOAD --> GO["Go\nplan → TDD → integrate"]:::auto
    GO --> CHECK["Check\nreview + audit + test"]:::auto
    CHECK -->|"PASS / WARN"| SHIP["Ship\nisolated test → PR → CI"]:::auto
    CHECK -->|FAIL| RETRY{"retry < 3?"}
    RETRY -->|yes| GO
    RETRY -->|no| PAUSE["Pause\nuser decides"]:::human
    PAUSE -->|continue| GO
    PAUSE -->|abort| ABORT(["Abort"])
    SHIP --> EVOLVE["Evolve\nauto-analyze session"]:::auto
    EVOLVE --> DONE(["Orbit Complete\nconsolidated report"]):::auto

    classDef human fill:#4a4a6a,stroke:#9b9bcc,color:#fff
    classDef auto  fill:#1a5c3a,stroke:#4caf7d,color:#fff
```

**紫色** — 人工步骤：模式选择（不明确 → 交互式）、3 次检查失败暂停。
**绿色** — 明确 + 复杂 → 委员会自动生成 spec；明确 + 简单 → 直接构建；两者完全自主。

状态持久化在 `$HARNESS_DIR/orbit/PIPELINE-{timestamp}.json` — 在上下文压缩后仍然保留。

> **注意事项**：当修改 orbit 本身或仅编辑文档时，智能体可能会绕过流水线。参见[已知问题（智能体判断）](#已知问题智能体判断)。

---

## 自动技能（Ring 2）

技能根据上下文自动触发。你不需要手动调用它们。

| 技能 | 触发时机 |
|-------|--------------|
| **tdd** | 新功能实现或 Bug 修复 |
| **debug** | 测试失败或运行时错误 |
| **discover** | 需求模糊、没有明确问题的解决方案、缺乏焦点的抱怨 |
| **secure** | 涉及认证 / 数据库 / API / 密钥代码 |
| **perf** | 循环、查询、渲染、批量操作 |
| **simplify** | 文件超过 200 行或圈复杂度过高 |
| **document** | 公共 API 新增或签名变更 |
| **verify** | 在完成 `/go` 或 `/ship` 之前 |
| **context** | 上下文窗口超过 70% |
| **council** | 存在歧义的架构或设计决策 |
| **agent-introspection** | 连续 3+ 次失败或循环重试模式 |
| **reflect** | 按需：你是否在将 AI 作为思维放大器？基于事实的冷静自我评估 |

---

## Evolve（Ring 3）

框架监控每一次工具调用，在 3 个维度上评分，检测失败模式，并生成针对性技能 — 在会话结束时自动完成。

### 评分

```
composite = 0.5 × tool_success + 0.3 × output_quality + 0.2 × execution_cost
```

失败分类（9 种类型）：`type_error` · `syntax_error` · `test_fail` · `lint_fail` · `build_fail` · `permission_denied` · `timeout` · `not_found` · `runtime_error`

### 模式检测

| 模式 | 检测内容 | 默认阈值 |
|---------|---------|-------------------|
| `repeated_same_error` | 相同错误出现 N+ 次 | 3 |
| `fix_then_break` | 编辑成功 → 构建/测试失败 | 3 次回溯，2 个周期 |
| `long_debug_loop` | 卡在同一个文件上 | 5 次操作 |
| `thrashing` | 编辑与错误交替出现 | 3 次编辑，3 次错误 |

### 进化流程

```
Observe（PostToolUse — 3 轴评分）
    ↓ obs/session_{id}.jsonl
Analyze（SessionEnd）
    ↓ 按工具、按扩展名的评分 + 模式
Propose（Solver — 按评分渐进：≥0.90 跳过，≥0.70 适度，<0.70 完整）
    ↓ SkillProposal[] 带置信度
Curate（Accept/Merge/Skip，反馈对 solver 不可见）
    ↓ evolved/{skill}/SKILL.md + meta.json
Gate（格式检查、去重、上限 10、≥ 3 次会话的门控提升）
    ↓ evolved_backup/（最佳检查点）
Instinct（高成功率模式 → 跨项目 memory.db 节点）
    ↓
Reload（下次会话 — resume 加载进化技能）
```

技能播种：弱工具（成功率 <60%，最少 5 次观测），弱文件类型（成功率 <50%，最少 3 次观测），高频错误（5+ 次出现）。

停滞：连续 3 次会话无 5% 提升 → 自动回滚到最佳检查点。

### 技能效果

每个进化技能都有 A/B 归因追踪：

```
/evolve history → 技能效果

| 技能               | 使用时 | 未使用时 | 差值 |
|--------------------|--------|----------|------|
| evo-ts-care        | 0.87   | 0.72     | +15% |
| evo-bash-discipline| 0.65   | 0.68     | -3%  |
```

正差值 = 有效。负差值 = 考虑通过 `/evolve rollback` 移除。

### 冷启动预设

首次会话时，根据技术栈自动应用预设技能：

| 技术栈 | 预设 |
|-------|---------|
| Node.js/TypeScript | `evo-ts-care`、`evo-fix-build-fail` |
| Go | `evo-go-care` |
| Python | `evo-py-care` |
| Rust | `evo-rs-care` |

### Instinct 学习

高成功率模式被提取并跨项目推广：

```
observe（100% 确认）→ extract_instincts() → instinct 节点（置信度 ≥ 0.8）
    → 在 ≥ 2 个项目中观察到时提升为全局
```

```bash
/evolve              # 立即运行
/evolve status       # 仪表板：评分、趋势、模式、技能
/evolve history      # 完整历史 + 技能效果
/evolve cross-project # 跨项目模式分析
/evolve rollback     # 恢复之前的最佳状态
/evolve reset        # 清除所有进化数据
```

---

## Hooks（Ring 0）

在每次会话中无形运行。单个 Rust 二进制文件（`epic-harness`）包含多个子命令。

| Hook | 触发时机 | 功能 |
|------|---------|------|
| **resume** | 会话启动 | 恢复上下文、加载记忆、检测技术栈 |
| **guard** | Bash 执行前 | 阻止强制推送到 main、`rm -rf /`、删除生产数据库 |
| **polish** | Edit 之后 | 自动格式化（Biome/Prettier/ruff/gofmt）+ 类型检查 |
| **observe** | 每次工具使用 | 记录到 `~/.harness/projects/{slug}/obs/` 用于进化 |
| **snapshot** | compact 之前 | 保存状态到 `~/.harness/projects/{slug}/sessions/` |
| **reflect** | 会话结束 | 分析失败、播种进化技能、门控、提取 instincts |

Polish 反馈到 observe：格式化失败 → `lint_fail`，TypeScript 错误 → `build_fail`。编辑→错误交替模式即使在错误来自 polish 时也能被检测到。

每次会话写入自己的 `session_{date}_{pid}_{random}.jsonl` — 多个并发会话不会互相破坏数据。

### Hook 配置方案

通过 `~/.harness/config.toml` 或 `EPIC_HOOK_PROFILE` 环境变量：

| 方案 | 活跃 hooks |
|---------|-------------|
| `minimal` | guard、observe、resume |
| `standard`（默认） | 以上 + polish、reflect、snapshot |
| `strict` | 所有 hooks + 未来的严格模式专用检查 |

### 自定义 Guard 规则

通过项目根目录的 `.harness/guard-rules.yaml` 添加项目特定规则：

```yaml
blocked:
  - pattern: kubectl\s+delete\s+namespace | msg: Namespace deletion blocked
warned:
  - pattern: docker\s+system\s+prune | msg: Docker prune — verify first
```

---

## Team（`epic team`）

团队是**组织级别**的，不绑定到项目。在任何项目中运行 `/team` 都会丰富共享的智能体定义池 — 永远不会静默覆盖。

```bash
epic team                              # 交互式：扫描 → 设计 → 写入 → 同步
epic team sync backend                 # 分发智能体 → .claude/agents/backend/
epic team link backend                 # 分发 + 在团队配置中注册项目
epic team list                         # 当前组织的所有团队
epic team list --org netflix           # 指定组织的团队
epic team show backend --playbook      # 配置 + 完整 playbook
epic team delete backend               # 仅从当前项目撤回
epic team delete backend --global      # 从组织存储中永久删除
```

同步后，智能体在下次会话中可用：`@domain-expert`、`@reviewer`、`@tester` 等。

| 类型 | 关键词 | 默认智能体 |
|------|---------|---------------|
| 流对齐（Stream-aligned） | `stream` | domain-expert、reviewer、tester |
| 平台（Platform） | `platform` | api-designer、infra-specialist、dx-agent |
| 赋能（Enabling） | `enabling` | specialist |
| 复杂子系统（Complicated Subsystem） | `subsystem` | domain-specialist、integration-tester |

多组织：`epic team --org netflix` — 每个组织独立的拓扑。

合并策略：变更的智能体会提示（默认：保留现有，备份到 `.history/`）。Playbook 始终追加。

---

## 多工具支持

所有工具共享相同的 `~/.harness/projects/{slug}/` 数据目录。

| 工具 | Ring 0 Hooks | 命令 | 技能 | 智能体 |
|------|-------------|----------|--------|--------|
| **Claude Code** | ✓ 完整 | ✓ 8 条命令（含 /orbit） | ✓ 11 个技能 | ✓ 4 |
| **Codex CLI** | ✓ 完整¹ | ✓ 8 个提示（含 /orbit） | ✓ 7 | ✓ 4 |
| **Gemini CLI** | ✓ 部分² | ✓ 8 条命令（含 /orbit） | ✓ 7 | ✓ 4 |
| **Cursor** | ✓ 完整³ | ✓ 8 条命令（含 /orbit） | ✓ 通过 rules | ✓ 4 |
| **OpenCode** | ✓ 部分⁴ | ✓ 8 条命令（含 /orbit） | — | ✓ 4 |
| **Cline** | ✓ 完整⁵ | — | — | — |
| **Aider** | —⁶ | — | — | — |

¹ `codex_hooks = true` 在 `~/.codex/config.toml` 中 · ² Guard 在 `BeforeModel` 级别 · ³ Cursor 1.7+ · ⁴ JS 插件 · ⁵ 5 个 hook 脚本 · ⁶ 仅 Conventions

---

## 架构：4-Ring 模型

```mermaid
flowchart TB
    subgraph R0["Ring 0 — Autopilot (hooks, invisible)"]
        direction LR
        h1(resume) --- h2(guard) --- h3(polish) --- h4(observe) --- h5(snapshot) --- h6(reflect)
    end

    subgraph R1["Ring 1 — Commands (you call these)"]
        direction TB
        subgraph orbit_wrap["  /orbit  "]
            direction LR
            c1("/discover") --> c2("/spec") --> c3("/go") --> c4("/check") --> c5("/ship") --> c6("/evolve")
        end
        c7("/team")
        c8("/evolve (manual)")
    end

    subgraph R2["Ring 2 — Auto Skills (context-triggered)"]
        direction LR
        s1(tdd) --- s2(debug) --- s3(secure) --- s4(perf) --- s5(simplify) --- s6(verify) --- s7(council)
    end

    subgraph R3["Ring 3 — Evolve (self-improving)"]
        direction LR
        e1(observe) --> e2(analyze) --> e3(seed) --> e4(gate) --> e5(reload)
    end

    R0 -->|"observe every tool call"| R3
    R3 -.->|"evolved skills"| R2
    R1 -->|"auto-trigger skills"| R2
    R0 -->|"resume: restore context"| R1
```

---

## 跨项目学习

选择性加入以跨项目共享失败模式：

```bash
touch ~/.harness/projects/{slug}/.cross-project-enabled
```

会话结束 → 导出匿名化模式到 `~/.harness/global_patterns.jsonl`。会话启动 → 显示来自其他项目薄弱环节的提示。

---

## 统一记忆

所有智能体共享 `~/.harness/memory.db`（SQLite 配合全文搜索）中的知识图谱。无需外部运行时。

```
score = recency(25%) + importance(35%) + access_frequency(15%) + FTS_match(25%)
```

### CLI

```bash
epic mem recall "auth refactor" --project my-project   # 智能召回
epic mem add --title "JWT rotation" --type decision    # 添加节点
epic mem search "JWT"                                  # FTS5 搜索
epic mem list --type decision --project my-project    # 过滤
epic mem context --project my-project                  # 项目上下文
epic mem serve                                         # Web UI → :7700 或使用 --port 8800 指定端口
epic mem mcp-install                                   # 注册 MCP 服务器
epic mem export --out ./docs/memory                    # 导出为 Markdown
```

### MCP 工具（6 个）

| 工具 | 用途 |
|------|---------|
| `mem_recall` | 带 hint + project + 图邻居的智能上下文召回 |
| `mem_add` | 按类型自动分配重要性添加节点（或显式指定 0.0–1.0） |
| `mem_search` | 关键词搜索（全文），按重要性排序 |
| `mem_query` | 按标签/类型/项目过滤 |
| `mem_context` | 项目范围的智能召回（无需 hint） |
| `mem_related` | 从节点 ID 进行图遍历（查找关联知识） |

### 节点类型

| 类型 | 创建方式 | 重要性 |
|------|-----------|------------|
| `decision` | 手动 / MCP | 0.9 |
| `resolution` | 手动 / MCP | 0.8 |
| `concept` | 手动 / MCP | 0.7 |
| `project` | 手动 / MCP | 0.7 |
| `instinct` | 自动（reflect） | 0.7 |
| `pattern` | 自动（reflect） | 0.5 |
| `error` | 自动（reflect） | 0.4 |
| `session` | 自动（reflect） | 0.2 |

生命周期：30+ 天未访问 → 10% 重要性衰减（下限 0.05）。180+ 天 → 标记为 `stale`，从召回中排除。`pinned` 标签防止衰减。

> **Web UI**：图可视化正在积极改进 — 聚类、邻居高亮和离线回退近期已上线。更多增强功能正在开发中。

---

<details>
<summary><strong>项目数据 — 目录布局</strong></summary>

## 项目数据

所有数据存储在 `~/.harness/`（主目录）中，不在你的项目根目录。不受项目删除影响，不会污染 git 历史。

```
~/.harness/
├── memory.db                  # SQLite 知识图谱（节点 + 边 + FTS5）
├── graph.json                 # 缓存图（用于 Web UI）
├── config.toml                # 用户配置
├── global_patterns.jsonl      # 跨项目模式（选择性加入）
├── orgs/                      # 团队全局存储
│   └── {org}/teams/{team}/
│       ├── config.json, mission.md, playbook.md, agents/, .history/
└── projects/{slug}/
    ├── memory/                # 项目模式和规则
    ├── sessions/              # 会话快照（用于 resume）
    ├── obs/                   # 工具使用观测日志（JSONL）
    ├── evolved/               # 自动进化技能
    │   ├── manifest.json
    │   └── {skill}/SKILL.md + meta.json
    ├── evolved_backup/        # 最佳检查点（用于回滚）
    ├── dispatch/              # 技能调度日志
    ├── evolution.jsonl        # 完整进化历史
    └── metrics.json           # 聚合统计 + 技能归因
```

与团队共享安全规则：在项目根目录放置 `.harness/guard-rules.yaml`（提交到 git）。

</details>

---

<details>
<summary><strong>配置 — config.toml 参考</strong></summary>

## 配置

`~/.harness/config.toml` 中的所有可调参数。未设置 = 硬编码默认值。

```toml
# 优先级：环境变量（EPIC_HOOK_PROFILE）> 此文件 > 默认值

[hook]
profile = "standard"         # "minimal" | "standard" | "strict"
gateguard_hints = true

[scoring]
weights = [0.5, 0.3, 0.2]   # [success, quality, cost]

[evolution]
max_skills = 10
stagnation_limit = 3
improvement_threshold = 0.05
gated_promotion_min = 3

[pattern]
# repeated_error_min = 3
# debug_loop_min = 5
# graduated_scope_skip = 0.90
# graduated_scope_moderate = 0.70

[instinct]
# confidence_threshold = 0.8
# promotion_min_projects = 2
# max_instincts = 20
# min_observations = 10
# min_avg_score = 0.5
```

</details>

---

## 已知问题（智能体判断）

这些问题源于智能体对上下文的解读，而非代码中的 Bug。列在此处以便用户知晓需要注意什么。

### 已发现问题

| 问题 | 触发时机 | 现象 | 解决方法 |
|-------|---------|-------------|------------|
| **Orbit 自修改绕过** | `/orbit` 被要求改进 orbit 本身时 | 智能体可能完全跳过 orbit 流水线，直接在 main 上临时编辑文件，导致更改未提交且没有 spec/PR/可追溯性 | orbit 完成后，检查 `git status`。如果更改在 main 上且没有流水线状态，手动提交或从单独的分支重新运行 `/orbit` |
| **仅文档任务跳过协议** | `/orbit` 收到仅 markdown 变更（无代码需测试）时 | 智能体可能判断 TDD/测试阶段无意义而跳过完整流水线 | 对纯文档变更可以接受。对于混合代码+文档的情况，确保智能体不跳过与代码相关的阶段 |
| **模式误判** | 需求处于 Direct 和 Council 的边界时 | 智能体可能选择 Direct 而 Council（4 声音）能捕获更多边界情况，或选择 Council 而 Direct 就够了 | 如果智能体选择的模式感觉不对，明确说"使用 Council 模式"或"使用 Direct 模式" |

### 有意的设计选择

这些曾被考虑增强但经过评估后保持原样：

| 选择 | 为何未增强 | 理由 |
|--------|-----------------|-----------|
| **Worktree 在 Go 阶段而非 orbit 启动时进入** | 可以更早隔离 | 预检/模式/spec 都是只读的。更早隔离增加复杂性但无收益 — 分支直到 Go 阶段才创建 |
| **Worktree 在 Ship 后保留** | 可以在 PR 合并后自动删除 | 该分支是 PR 的 HEAD。合并前删除会破坏 PR。清理留给用户在合并后处理 |
| **分支命名为 `orbit-{slug}` 而非 `feature/{slug}`** | 可以匹配常规分支命名 | `EnterWorktree` 不允许名称中包含 `/`。创建后重命名增加了一个步骤但仅有美观收益 |
| **文档变更无轻量流水线路径** | 可以检测仅文档并跳过 TDD/测试 | 检测脆弱（什么算"文档"？）。添加单独路径增加了协议复杂性但收益有限 |

---

## 故障排除

<details>
<summary>安装后提示 command not found: epic</summary>

将 Cargo bin 目录添加到你的 PATH：

```bash
export PATH="$HOME/.cargo/bin:$PATH"
```

将此行添加到你的 `~/.zshrc` 或 `~/.bashrc` 使其永久生效。
</details>

<details>
<summary>Hooks 在 Claude Code 中未触发</summary>

重新运行安装以将 hooks 同步到 Claude Code 设置：

```bash
epic install claude
```

然后重启 Claude Code。Hooks 写入到 `~/.claude/settings.json`。
</details>

<details>
<summary>macOS 上出现 Permission denied（Gatekeeper）</summary>

macOS 可能阻止从互联网下载的未签名二进制文件：

```bash
xattr -d com.apple.quarantine ~/.cargo/bin/epic-harness
xattr -d com.apple.quarantine ~/.cargo/bin/epic
```
</details>

<details>
<summary>epic：插件 hooks 中找不到二进制文件</summary>

插件首先在 `hooks/bin/epic-harness` 中查找二进制文件。通过 `cargo install` 更新后，请复制它：

```bash
cp ~/.cargo/bin/epic-harness hooks/bin/epic-harness
```
</details>

---

## 开发

```bash
cargo install --path .                                        # 构建 + 安装
cp ~/.cargo/bin/epic-harness hooks/bin/epic-harness           # 更新插件二进制
cargo test                                                    # 测试
```

Hooks 在两个位置查找二进制文件：`hooks/bin/epic-harness`（插件本地） → `~/.cargo/bin/epic-harness`（PATH）。

---

## 链接

- [更新日志](../../CHANGELOG.md) — 发布历史
- [贡献指南](../../CONTRIBUTING.md) — 如何贡献
- [安全政策](../../SECURITY.md) — 报告漏洞
- [问题追踪](https://github.com/epicsagas/epic-harness/issues) — Bug 报告和功能请求

## 致谢

- [a-evolve](https://github.com/A-EVO-Lab/a-evolve) — 自动进化和基准测试模式
- [agent-skills](https://github.com/addyosmani/agent-skills) — Claude Code 智能体技能系统
- [everything-claude-code](https://github.com/affaan-m/everything-claude-code) — 综合 Claude Code 模式
- [gstack](https://github.com/garrytan/gstack) — 插件架构参考
- [harness](https://github.com/revfactory/harness) — Hook 和框架基础设施模式
- [serena](https://github.com/oraios/serena) — 自主智能体设计
- [SuperClaude Framework](https://github.com/SuperClaude-Org/SuperClaude_Framework) — 多命令框架架构
- [superpowers](https://github.com/obra/superpowers) — Claude Code 扩展模式

## 许可证

[Apache 2.0](../../LICENSE)
