<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-CN/README.md">简体中文</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 外掛，**用 8 條命令取代 30+ 條命令**，**根據你正在做的事情自動觸發技能**，並**從你自己的失敗模式中進化出新技能**。

<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 approved → go (TDD subagents) → check (PASS) → ship (PR + CI) → evolve
```

也可以手動分步執行：

```bash
/spec "為登入 API 新增 JWT 驗證"   # 釐清需求 → SPEC-*.md
/go                                # 自動規劃 → TDD 子智能體 → 4 分鐘
/check                             # 平行審查 + 安全 + 測試 → PASS
/ship                              # 隔離測試 → PR → CI 綠燈
```

技能會在背景自動觸發 — 不需要額外命令：

```
正在開發新功能？         → 觸發 tdd（強制 Red→Green→Refactor）
測試失敗？               → 觸發 debug（先找根因，不做盲修）
修改了 auth 或 DB？      → 觸發 secure（OWASP 檢查清單，不走捷徑）
檔案超過 200 行？        → 觸發 simplify（抽取、重新命名、簡化）
```

會話結束後，**evolve 迴圈**會分析什麼壞了、生成針對性技能，並在下一次會話載入。今天卡在 TypeScript 建置失敗，下一次就有 `evo-ts-care` 技能幫你起跑。

---

## 安裝

> **第一次使用？** 請閱讀[快速入門指南（5 分鐘）](../../docs/quickstart.md)。

### Claude Code（推薦）

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

一步完成二進位安裝和所有掛鉤註冊。

### 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. 為 Claude Code 註冊 MCP 伺服器（harness-mem）
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` | 先定義問題 — 五問法、JTBD、蘇格拉底式提問（最多 3 輪） |
| `/spec` | 將需求轉換為帶編號的需求與驗收標準文件，儲存為 `SPEC-{timestamp}.md` |
| `/go` | 自動規劃 → TDD 子智能體 → 使用工作樹隔離的平行執行 → 驗收標準驗證 |
| `/check` | 平行程式碼審查 + 安全審計 + 測試，根據範圍附加額外檢查（API 合約、無障礙、遷移安全性） |
| `/ship` | 在乾淨工作樹中進行隔離預飛行測試 → 附帶完整檢查報告的 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 次檢查失敗暫停。
**綠色** — 明確 + 複雜 → 委員會自動生成規格；明確 + 簡單 → 直接建構；兩者皆完全自主。

狀態持久化於 `$HARNESS_DIR/orbit/PIPELINE-{timestamp}.json` — 在上下文壓縮後仍可恢復。

> **注意**：智能體在修改 orbit 本身或僅編輯文件時可能繞過流水線。參見[已知問題（智能體判斷）](#已知問題智能體判斷)。

---

## 自動技能（Ring 2）

技能根據上下文自動觸發。你不需要手動呼叫它們。

| 技能 | 觸發時機 |
|-------|--------------|
| **tdd** | 新功能實作或錯誤修復 |
| **debug** | 測試失敗或執行時期錯誤 |
| **discover** | 模糊的請求、先給出解決方案而無問題描述、無焦點的抱怨 |
| **secure** | 涉及 Auth / DB / API / secrets 的程式碼 |
| **perf** | 迴圈、查詢、渲染、批次操作 |
| **simplify** | 檔案超過 200 行或圈複雜度過高 |
| **document** | 新增或修改了公開 API 簽名 |
| **verify** | 在完成 `/go` 或 `/ship` 之前 |
| **context** | 上下文視窗使用超過 70% |
| **council** | 模糊的架構或設計決策 |
| **agent-introspection** | 連續 3 次以上失敗或循環重試模式 |
| **reflect** | 按需觸發：你是否將 AI 作為思考放大器？基於冷证据的自我評估 |

---

## 進化（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` | Edit↔Error 交替出現 | 3 次編輯，3 次錯誤 |

### 進化流程

```
Observe (PostToolUse — 3-axis scoring)
    ↓ obs/session_{id}.jsonl
Analyze (SessionEnd)
    ↓ per-tool, per-ext scores + patterns
Propose (Solver — graduated by score: ≥0.90 skip, ≥0.70 moderate, <0.70 full)
    ↓ SkillProposal[] with confidence
Curate (Accept/Merge/Skip, feedback masked from solver)
    ↓ evolved/{skill}/SKILL.md + meta.json
Gate (format check, dedup, cap 10, gated promotion ≥ 3 sessions)
    ↓ evolved_backup/ (best checkpoint)
Instinct (high-success patterns → cross-project memory.db nodes)
    ↓
Reload (next session — resume loads evolved skills)
```

技能播種：弱工具（成功率 <60%，最少 5 次觀測）、弱檔案類型（成功率 <50%，最少 3 次觀測）、高頻錯誤（5+ 次出現）。

停滯處理：連續 3 個工作階段無 5% 改善 → 自動回滾到最佳檢查點。

### 技能有效性

每個進化技能都透過 A/B 歸因追蹤：

```
/evolve history → Skill Effectiveness

| Skill              | With | Without | Delta |
|--------------------|------|---------|-------|
| 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` |

### 直覺學習

高成功率模式被提取並在專案間推廣：

```
observe (100% confirmed) → extract_instincts() → instinct node (confidence ≥ 0.8)
    → promote to global when observed in ≥ 2 projects
```

```bash
/evolve              # 立即執行
/evolve status       # 儀表板：評分、趨勢、模式、技能
/evolve history      # 完整歷史 + 技能效果
/evolve cross-project # 跨專案模式分析
/evolve rollback     # 恢復上一個最佳版本
/evolve reset        # 清除所有進化資料
```

---

## 掛鉤（Ring 0）

在每個工作階段中無感執行。單一 Rust 二進位檔案（`epic-harness`），含多個子命令。

| 掛鉤 | 時機 | 功能 |
|------|------|------|
| **resume** | 工作階段啟動 | 恢復上下文、載入記憶、偵測技術堆疊 |
| **guard** | Bash 執行前 | 阻止強制推送到 main、`rm -rf /`、DROP 生產庫 |
| **polish** | Edit 執行後 | 自動格式化（Biome/Prettier/ruff/gofmt）+ 型別檢查 |
| **observe** | 每次工具呼叫 | 記錄到 `~/.harness/projects/{slug}/obs/`，用於進化 |
| **snapshot** | 壓縮前 | 將狀態儲存到 `~/.harness/projects/{slug}/sessions/` |
| **reflect** | 工作階段結束 | 分析失敗、播種進化技能、門控、提取直覺 |

Polish 回饋至 observe：格式化失敗 → `lint_fail`，TypeScript 錯誤 → `build_fail`。即使錯誤來自 polish，Edit→Error 抖振也會被偵測到。

每個工作階段寫入各自的 `session_{date}_{pid}_{random}.jsonl` — 多個並行工作階段不會互相損壞資料。

### 掛鉤設定檔

透過 `~/.harness/config.toml` 或 `EPIC_HOOK_PROFILE` 環境變數設定：

| 設定檔 | 啟用的掛鉤 |
|---------|-------------|
| `minimal` | guard、observe、resume |
| `standard`（預設） | 以上 + polish、reflect、snapshot |
| `strict` | 所有掛鉤 + 未來的 strict-only 檢查 |

### 自訂守衛規則

在專案根目錄的 `.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
```

---

## 團隊（`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 掛鉤 | 命令 | 技能 | 智能體 |
|------|-------------|----------|--------|--------|
| **Claude Code** | ✓ 完整 | ✓ 8 條命令（含 /orbit） | ✓ 11 個技能 | ✓ 4 |
| **Codex CLI** | ✓ 完整¹ | ✓ 8 條提示詞（含 /orbit） | ✓ 7 | ✓ 4 |
| **Gemini CLI** | ✓ 部分² | ✓ 8 條命令（含 /orbit） | ✓ 7 | ✓ 4 |
| **Cursor** | ✓ 完整³ | ✓ 8 條命令（含 /orbit） | ✓ 透過規則 | ✓ 4 |
| **OpenCode** | ✓ 部分⁴ | ✓ 8 條命令（含 /orbit） | — | ✓ 4 |
| **Cline** | ✓ 完整⁵ | — | — | — |
| **Aider** | —⁶ | — | — | — |

¹ `codex_hooks = true` 在 `~/.codex/config.toml` · ² 守衛在 `BeforeModel` 級別 · ³ Cursor 1.7+ · ⁴ JS 外掛 · ⁵ 5 個掛鉤腳本 · ⁶ 僅約定

---

## 架構：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` | 基於提示 + 專案 + 圖鄰居的智慧上下文檢索 |
| `mem_add` | 按類型自動設定重要性新增節點（或顯式 0.0–1.0） |
| `mem_search` | 關鍵字搜尋（全文），按重要性排序 |
| `mem_query` | 按標籤/類型/專案過濾 |
| `mem_context` | 專案範圍的智慧檢索（無提示） |
| `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/              # 工作階段快照（用於恢復）
    ├── 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>

---

## 已知問題（智能體判斷）

這些問題源於智能體對上下文的解釋，而非程式碼缺陷。列出這些是讓使用者知道需要注意什麼。

### 已發現問題

| 問題 | 觸發條件 | 現象 | 解決方法 |
|------|---------|------|---------|
| **Orbit 自我修改繞過** | 請求 `/orbit` 改進 orbit 自身 | 智能體可能跳過整個 orbit 流水線，直接在 main 分支上臨時編輯檔案，沒有 spec/PR/可追溯性，變更處於未提交狀態 | orbit 完成後檢查 `git status`。如果 main 上有變更但沒有流水線狀態，手動提交或從單獨的分支重新執行 `/orbit` |
| **純文件任務跳過協議** | 向 `/orbit` 提供僅 Markdown 的變更（無測試程式碼） | 智能體可能判斷 TDD/測試階段無意義而跳過整個流水線 | 純文件變更可接受。混合程式碼 + 文件時，確保程式碼相關階段未被跳過 |
| **模式誤判** | 請求處於 Direct 和 Council 的邊界 | 智能體可能選擇 Direct 而 Council（4 方審查）會發現更多邊界情況，或反之 | 如果智能體的模式選擇看起來不合適，明確指定「使用 Council 模式」或「使用 Direct 模式」 |

### 刻意保留的設計選擇

以下選擇曾考慮增強，但經評估後維持現狀：

| 選擇 | 未增強的原因 | 依據 |
|------|------------|------|
| **僅在 Go 階段進入工作樹** | 可以從 preflight 開始隔離 | Preflight/mode/spec 是唯讀的。更早隔離增加複雜度但無收益 — 分支本身在 Go 階段才建立 |
| **Ship 後保留工作樹** | 可以在 PR 合併後自動刪除 | 分支是 PR 的 head 引用。合併前刪除會損壞 PR。清理留給使用者在合併後處理 |
| **分支名使用 `orbit-{slug}` 而非 `feature/{slug}`** | 可以匹配常規分支命名 | `EnterWorktree` 不允許名稱中包含 `/`。建立後重新命名僅增加步驟，只有外觀上的收益 |
| **純文件變更無輕量流程路徑** | 可以偵測 doc-only 並跳過 TDD/測試 | 偵測不可靠（什麼算「文件」？）。協議複雜度增加的代價大於邊際收益 |

---

## 疑難排解

<details>
<summary>安裝後出現 command not found: epic</summary>

將 Cargo bin 目錄加入你的 PATH：

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

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

<details>
<summary>掛鉤在 Claude Code 中未觸發</summary>

重新執行安裝以同步掛鉤到 Claude Code 設定：

```bash
epic install claude
```

然後重新啟動 Claude Code。掛鉤會寫入 `~/.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：外掛掛鉤內找不到二進位</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/bin/epic-harness`（外掛本地）→ `~/.cargo/bin/epic-harness`（PATH）。

---

## 連結

- [更新日誌](../../CHANGELOG.md) — 發佈歷史
- [貢獻指南](../../CONTRIBUTING.md) — 如何貢獻
- [安全政策](../../SECURITY.md) — 回報漏洞
- [Issues](https://github.com/epicsagas/epic-harness/issues) — 錯誤回報和功能請求

## 致謝

- [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) — 掛鉤與框架基礎設施模式
- [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)
