homunculus-code 0.1.0 → 0.3.0

package/examples/reference/evolved-skills/claude-code-reference/ch02-agents.md

@@ -0,0 +1,90 @@
+# ch02: Subagents + Agent Teams
+
+## 3. Subagents 系統
+
+```yaml
+# ~/.claude/agents/my-agent.md
+---
+name: my-agent
+description: Use proactively for X. Delegates Y tasks.
+tools: Read, Grep, Glob, Bash
+model: haiku          # sonnet | opus | haiku | inherit | 完整 model ID（如 claude-opus-4-6）（v2.1.74 修復：之前完整 ID 被靜默忽略）
+permissionMode: acceptEdits
+maxTurns: 20
+memory: user          # 持久記憶到 ~/.claude/agent-memory/<name>/
+background: false     # true = 永遠背景執行
+isolation: worktree   # git worktree 隔離
+skills:
+  - shell-automation-patterns  # 啟動時完全預載入 skill 內容（full preload）
+---
+You are a specialized agent...
+```
+
+> **Skills 預載入差異**：主 session 按需載入 skills（用戶 `/invoke` 或 Claude 判斷時才讀取內容）；
+> Subagent 的 `skills:` 欄位在**啟動時完全預載入**（full preload），直接進入隔離 context。
+> Subagent **不繼承**主 session 已載入的 skills，必須在 `skills:` 中明確列出。
+
+> **Subagent 繼承規則**：獨立 context 但**繼承 CLAUDE.md + git status**（從 parent）。
+> System prompt 與 parent **共享緩存**（節省 tokens）。對話歷史**不繼承**。
+
+**記憶 Scopes**：
+
+| Scope | 路徑 | 適用 |
+|-------|------|------|
+| `user` | `~/.claude/agent-memory/<name>/` | 跨所有專案（推薦預設）|
+| `project` | `.claude/agent-memory/<name>/` | 專案特定，可 commit 分享 |
+| `local` | `.claude/agent-memory-local/<name>/` | 專案特定，不 commit |
+
+→ 自動注入 `MEMORY.md` 前 200 行到 subagent context
+
+**Session-Scoped Agents（CLI flag）**：
+```bash
+claude --agents '{
+  "code-reviewer": {
+    "description": "Expert code reviewer. Use proactively after code changes.",
+    "prompt": "You are a senior code reviewer...",
+    "tools": ["Read", "Grep", "Glob", "Bash"],
+    "model": "sonnet"
+  }
+}'
+```
+
+**Resume Subagent**：Subagent 完成後可繼續（完整 context 保留）：
+```text
+Use the code-reviewer to review src/auth.ts
+[Agent 完成]
+Continue that code review and now check src/session.ts
+```
+Transcripts：`~/.claude/projects/{project}/{sessionId}/subagents/agent-{id}.jsonl`
+
+**Subagent-scoped hooks**：定義在 frontmatter 中，只在該 subagent 執行期間生效，結束後自動清理。
+
+**Agent 管理**：`/agents`（互動式）、`claude agents`（CLI 列出）
+
+---
+
+
+---
+
+## 11. Agent Teams（實驗性）
+
+```bash
+# 啟用
+# settings.json: { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
+
+# 建立 team（自然語言）
+"Create a team with 3 teammates: security reviewer, performance reviewer, test reviewer"
+
+# 控制
+# Shift+Down → 切換 teammate
+# Ctrl+T → 切換 task list
+```
+
+**Subagents vs Agent Teams**：
+- Subagents：回報給 main agent，適合快速獨立任務
+- Agent Teams：teammates 互相通訊，適合需要討論/辯論的複雜研究
+
+**最佳規模**：3-5 teammates，每人 5-6 tasks，各人負責不同檔案（避免衝突）
+
+---
+

package/examples/reference/evolved-skills/claude-code-reference/ch03-hooks.md

@@ -0,0 +1,104 @@
+# ch03: Hooks 系統
+
+## 4. Hooks 系統
+
+```json
+// .claude/settings.json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{"type": "command", "command": "echo 'About to run bash'"}]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{"type": "command", "command": "npm run lint:fix"}]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [{"type": "command", "command": "./scripts/session-end.js"}]
+      }
+    ]
+  }
+}
+```
+
+**Hook 事件（完整，22 種）**：
+`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `Stop`, `StopFailure`（API 錯誤時，v2.1.78）, `TeammateIdle`（exit 2 = 繼續工作）, `TaskCompleted`（exit 2 = 阻止完成）, `InstructionsLoaded`, `ConfigChange`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`（v2.1.76）, `Elicitation`（exit 2 = deny MCP input）, `ElicitationResult`（exit 2 = block）, `SessionEnd`
+
+**四種 Hook 類型**：
+```json
+// 1. Shell command（最常用）
+{"type": "command", "command": "bash script.sh", "async": true}
+
+// 2. HTTP endpoint（POST JSON，非 2xx 不阻塞）
+{
+  "type": "http",
+  "url": "http://localhost:3000/hooks/pre-tool-use",
+  "headers": {"Authorization": "Bearer $MY_TOKEN"},
+  "allowedEnvVars": ["MY_TOKEN"]
+}
+
+// 3. Claude model 判斷
+{"type": "prompt", "prompt": "Should this tool be allowed? $ARGUMENTS"}
+
+// 4. Subagent 驗證（可用 Read/Grep/Glob）
+{"type": "agent", "prompt": "Validate: $ARGUMENTS"}
+```
+
+**控制 Claude 行為**（exit code）：
+- `exit 0` = 繼續
+- `exit 2` + `stdout` = 阻擋（輸出作為 Claude 的 feedback）
+
+**額外欄位**：`async: true`（背景）、`timeout`（秒）、`statusMessage`（spinner 文字）、`once: true`（只執行一次，Skills 專用）
+
+**進階 Hook 模式**：
+
+```bash
+# SessionStart compact matcher — compact 後重新注入 context（高價值！）
+# settings.json hooks.SessionStart[{matcher: "compact"}]
+
+# 結構化 JSON 輸出（比 exit code 更細緻）
+echo '{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Use rg instead of grep"}}'
+# permissionDecision: "allow" | "deny" | "ask"
+
+# Stop hook — 防無限迴圈
+if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then exit 0; fi
+echo '{"decision": "block", "reason": "Tests not passing yet"}'
+
+# Agent-based Stop hook — spawn subagent 驗證程式碼狀態
+# {"type": "agent", "prompt": "Verify all unit tests pass.", "timeout": 120}
+
+# MCP 工具 matcher
+# {"matcher": "mcp__github__.*"}  {"matcher": "mcp__playwright__.*"}
+
+# UserPromptSubmit 注入 context
+echo '{"additionalContext": "Current git branch: main, last deploy: 2h ago"}'
+```
+
+**進階 hookSpecificOutput 欄位**：
+```bash
+# 1. CLAUDE_ENV_FILE（SessionStart 專用）— 持久化 env vars 到所有 Bash 呼叫
+echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
+
+# 2. updatedInput（PreToolUse）— 執行前修改工具輸入
+echo '{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow", "updatedInput": {"command": "safe-cmd"}}}'
+
+# 3. updatedPermissions（PermissionRequest）— 自動批准不再提示
+echo '{"hookSpecificOutput": {"hookEventName": "PermissionRequest", "decision": {"behavior": "allow", "updatedPermissions": [{"type": "toolAlwaysAllow", "tool": "Bash"}]}}}'
+
+# 4. updatedMCPToolOutput（PostToolUse，MCP 工具專用）— 過濾 MCP 回應
+echo '{"hookSpecificOutput": {"hookEventName": "PostToolUse", "updatedMCPToolOutput": "sanitized output"}}'
+```
+
+**⚠️ Shell profile 陷阱**：hook 在非互動 shell 執行，`~/.zshrc` 中的 `echo` 會污染 JSON：
+```bash
+if [[ $- == *i* ]]; then echo "Shell ready"; fi  # 只在互動 shell echo
+```
+
+---
+

package/examples/reference/evolved-skills/claude-code-reference/ch04-mcp.md

@@ -0,0 +1,78 @@
+# ch04: MCP 設定 + MCP 進階設定
+
+## 5. MCP 設定
+
+```json
+// .claude/settings.json （project scope，推薦）
+{
+  "mcpServers": {
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@anthropic/mcp-playwright"]
+    },
+    "filesystem": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/jinx"]
+    },
+    "my-local-tool": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/Users/jinx/tools/my-mcp.js"]
+    }
+  }
+}
+```
+
+**Scope 層級**：
+- **User（全域）**：`~/.claude/settings.json` → 所有專案可用
+- **Project（專案）**：`.claude/settings.json` → 只此專案有效（推薦隔離）
+- **CLI 覆蓋**：`claude --mcp-config ./custom.json`；`--strict-mcp-config` 只用指定設定
+
+**MCP Tool Search**：預設啟用，最多載入 **10% context** 的 MCP tools，其餘延遲載入直到需要。
+
+**MCP 精選原則**：只啟用當前任務需要的，不要全開（省 context）
+
+---
+
+
+---
+
+## 20. MCP 進階設定（2026）
+
+```bash
+# Scope（注意：名稱已更改）
+claude mcp add --scope user playwright -- npx @playwright/mcp@latest     # 跨專案
+claude mcp add --scope project --transport http github https://...       # 共享
+
+# Claude Code 作為 MCP server（供 Claude Desktop 連接）
+claude mcp serve
+
+# 從 Claude Desktop 匯入
+claude mcp add-from-claude-desktop
+```
+
+**.mcp.json 環境變數展開**：
+```json
+{
+  "mcpServers": {
+    "api": {
+      "type": "http",
+      "url": "${API_BASE:-https://api.example.com}/mcp",
+      "headers": {"Authorization": "Bearer ${API_KEY}"}
+    }
+  }
+}
+```
+
+| 環境變數 | 用途 |
+|---------|------|
+| `MCP_TIMEOUT` | server 啟動 timeout（ms）|
+| `MAX_MCP_OUTPUT_TOKENS` | 輸出上限（預設 25000）|
+| `ENABLE_CLAUDEAI_MCP_SERVERS=false` | 不自動載入 claude.ai servers |
+
+⚠️ SSE transport 已棄用，改用 HTTP
+
+---
+

package/examples/reference/evolved-skills/claude-code-reference/ch05-ui.md

@@ -0,0 +1,161 @@
+# ch05: UI 功能（Checkpointing / 排程 / Remote Control / Fast Mode / Keybindings）
+
+## 6. Checkpointing / Rewind
+
+每個 user prompt 自動建立 checkpoint（追蹤檔案編輯前狀態），跨 session 保存，30 天後清除。
+
+```
+Esc + Esc  或  /rewind  ← 開啟 rewind 選單
+```
+
+| 選項 | 行為 |
+|------|------|
+| Restore code and conversation | 完整回退（回到該點的程式碼 + 對話）|
+| Restore code only | 只回退檔案，保留對話 |
+| **Summarize from here** | **壓縮該點後的對話（最常用，不改檔案）** |
+
+回退後，被選中的 prompt 會放回 input field，可直接重發或修改。
+
+### Summarize from here（關鍵技巧）
+
+比 `/compact` 更精準的 context 管理：
+- 保留選中點之前的完整對話，只壓縮之後的部分
+- **不修改磁碟檔案**，原始訊息仍在 transcript
+- 最佳時機：debug 密集段結束後、切換任務前
+- 效果：把佔空間的 debug session 壓縮，為新任務騰出 context
+
+### Checkpoint vs /fork
+
+| | Checkpoint / Rewind | Fork |
+|--|---------------------|------|
+| 動作 | 回退到過去狀態（undo）| 從當前狀態分支（branch）|
+| 用途 | 回到某點重試不同方案 | 平行探索不同方向，保留原 session |
+| 命令 | `Esc+Esc` / `/rewind` | `claude --continue --fork-session` |
+
+### 限制
+
+- Bash 指令造成的改動**不追蹤**（rm、mv、cp 等）
+- 不追蹤 Claude Code 外部的手動修改
+- 不是 git 替代品（checkpoint = local undo，git = permanent history）
+
+### 應用場景
+
+- **Debug 死胡同** → Restore code and conversation → 重新開始
+- **長 session 中段清理** → Summarize from here → 釋放 context
+- **比較實作方案** → checkpoint → 嘗試 A → 不滿意 → rewind → 嘗試 B
+
+---
+
+## 7. 排程任務（Session-Scoped）
+
+```text
+/loop 5m check if deployment finished
+/loop 30m /review-pr 1234
+remind me at 3pm to push release branch
+```
+
+底層工具：`CronCreate`, `CronList`, `CronDelete`
+
+**限制**：session-scoped，關閉 terminal 後消失。持久排程要用 launchd 或 GitHub Actions。
+
+---
+
+## 8. Remote Control
+
+```bash
+claude remote-control "My Project"  # 新 session（自訂名稱）
+/remote-control                      # 現有 session 中啟動
+/rc                                  # 縮寫
+/rc My Project                       # 加自訂名稱
+```
+
+連接方式：terminal 按空白鍵顯示 QR code；或直接用 URL；或到 `claude.ai/code` session 列表。
+
+| | Remote Control | Claude Code on the web |
+|--|----------------|------------------------|
+| 執行位置 | **本機** | Anthropic 雲端 |
+| 本地 MCP/工具 | ✅ 可用 | ❌ 不可用 |
+| 本地檔案系統 | ✅ 完整存取 | ❌ 不可用 |
+| 適用場景 | 從桌機開始，手機繼續 | 不需要本地環境的任務 |
+
+**技術細節**：outbound HTTPS only（不開 inbound ports）、多個短期憑證分開 scope、網路中斷後自動重連、每 session 只能一個遠端連線。
+
+**限制**：關閉 terminal = session 結束（不繼續跑）；網路中斷超過 ~10 分鐘 = timeout。
+
+**啟用對所有 session**：`/config → Enable Remote Control for all sessions → true`
+
+```bash
+/mobile    # 顯示 Claude app 下載 QR code
+/desktop   # 將 session 傳送到 Desktop app
+```
+
+---
+
+
+---
+
+## 12. Fast Mode（Opus 4.6 加速）
+
+```
+/fast    # 切換 on/off，Opus 4.6 速度 2.5x，費用更高
+```
+
+- `↯` 圖示出現 = fast mode 啟用
+- 建議 session **開始**就決定，中途切換會多付整個 context 的費用
+- 不適合：背景任務、CI/CD、重成本環境
+
+---
+
+
+---
+
+## 19. 自訂快捷鍵（Keybindings）
+
+```bash
+/keybindings    # 建立或開啟 ~/.claude/keybindings.json（儲存後即時套用）
+```
+
+```json
+{
+  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
+  "bindings": [
+    {
+      "context": "Chat",
+      "bindings": {
+        "ctrl+s": "chat:stash",
+        "ctrl+e": "chat:externalEditor",
+        "ctrl+u": null
+      }
+    },
+    {
+      "context": "Global",
+      "bindings": {
+        "ctrl+k ctrl+t": "app:toggleTodos"
+      }
+    }
+  ]
+}
+```
+
+**常用 Actions**：
+
+| Context | Action | 預設 | 說明 |
+|---------|--------|------|------|
+| Chat | `chat:stash` | Ctrl+S | 暫存 prompt，問其他問題後取回 |
+| Chat | `chat:externalEditor` | Ctrl+G | 在文字編輯器編輯 prompt |
+| Chat | `chat:cycleMode` | Shift+Tab | 切換 permission modes |
+| Chat | `chat:submit` | Enter | 送出訊息 |
+| Global | `app:toggleTodos` | Ctrl+T | 切換 task list |
+| Global | `app:toggleTranscript` | Ctrl+O | 切換 verbose transcript |
+
+**Voice Mode**（語音輸入，push-to-talk）：
+```json
+{ "voice:pushToTalk": "meta+k" }   // 自訂 keybinding
+```
+預設：Space bar 按住說話；支援 20 種語言（中/英/日/韓/俄/波/土 等）
+
+**和絃語法**：`ctrl+k ctrl+s`（依序按兩個組合鍵）
+**注意**：`Ctrl+C`/`Ctrl+D` 不可重綁；`Ctrl+B` 與 tmux 衝突（tmux 用戶按兩次）
+
+---
+