homunculus-code 0.1.0 → 0.2.0

package/examples/reference/evolved-skills/claude-code-reference/ch10-cli-sdk.md

@@ -0,0 +1,269 @@
+# ch10: CLI 進階 Flags + Agent SDK
+
+## 30. CLI 進階 Flags 與互動命令（cli-reference.md / interactive-mode.md）
+
+### Shell Script 中呼叫 Claude（Headless 模式）
+
+```bash
+# 必須先 unset，否則在 CC 環境內報錯
+unset CLAUDECODE
+
+# 基本 headless 呼叫（-p = --print = 無互動）
+claude -p "分析 $FILE" --model claude-sonnet-4-6
+
+# JSON 輸出，提取 result
+RESULT=$(claude -p "生成摘要" --output-format json | jq -r '.result')
+
+# 多步驟對話（保留 session context）
+SESSION=$(claude -p "Step 1：列出問題" --output-format json | jq -r '.session_id')
+claude -p "Step 2：修正問題" --resume "$SESSION" --output-format json | jq -r '.result'
+
+# 成本上限（CI 安全，超過就中止）
+claude -p "..." --max-budget-usd 2.00
+
+# 不儲存 session（CI/CD 避免殘留）
+claude -p "..." --no-session-persistence
+
+# 限制 agentic loop 回合數（未文件化但有效！）
+claude -p "..." --max-turns 1     # 只執行 1 輪不繼續 loop
+```
+
+### 未常見的 CLI Flags
+
+```bash
+# 工作目錄
+claude --add-dir /extra/path           # 增加額外目錄（不改 cwd）
+
+# Session 精確控制
+claude --fork-session                   # --resume 時建立新 session ID（保留 context）
+claude --session-id <uuid>             # 指定 session ID（而非隨機生成）
+# ⚠️ --continue / --fork-session：對話歷史保留，但 session-scoped permissions 完全遺失！
+# → 用戶之前核准的操作需要在新 session 重新核准（permissions 是 runtime 狀態）
+claude --include-partial-messages      # headless：包含 streaming 中間事件
+claude --input-format stream-json      # 指定輸入格式
+
+# 初始化與維護（CI/排程用）
+claude --init-only     # 執行 init hooks 後退出（環境驗證）
+claude --maintenance   # 執行 maintenance hooks 後退出（夜間維護）
+
+# MCP 精確控制
+claude --mcp-config ./mcp.json            # 從指定檔案載入 MCP
+claude --strict-mcp-config               # 只用 --mcp-config MCPs，忽略其他
+claude --permission-prompt-tool my_mcp   # headless：用 MCP tool 處理 permission
+
+# 設定層級
+claude --setting-sources user,project    # 指定載入哪些設定層
+claude --settings ./custom.json          # 額外設定（覆蓋/補充）
+
+# 其他
+claude --disable-slash-commands          # 停用所有 skills（CI 安全）
+claude --betas interleaved-thinking      # beta features（API key 限定）
+claude --teammate-mode auto|in-process|tmux  # Agent team 顯示模式
+claude --teleport                        # web session → 本機 terminal
+
+# 速度最佳化（v2.1.81 新增）
+# --bare：跳過所有初始化（hooks/LSP/plugins/skill scan/auto-memory），大幅加速 scripts
+# 限制：必須搭配 ANTHROPIC_API_KEY（不支援 OAuth/keychain），auto-memory 完全停用
+# 適用：heartbeat scripts 等不需要 hooks 的無狀態 headless 呼叫
+ANTHROPIC_API_KEY="..." claude -p "..." --bare   # 比標準 -p 更快
+
+# Debug 類別過濾
+claude --debug "api,mcp"                 # 只顯示指定類別
+claude --debug "!statsig,!file"          # negation 排除類別
+
+# Auth
+claude auth login --email user@a.com --sso  # SSO 登入
+claude auth status --text               # 純文字輸出
+claude agents                           # 列出所有 subagents
+```
+
+### 互動模式 Slash Commands（補充）
+
+```
+/copy               — 複製最後一則回覆（多個 code block 顯示 picker）
+/export [filename]  — 匯出對話為純文字
+/context            — 彩色格子視覺化 context 使用量
+/fork [name]        — 從當前點 fork 對話（類似 git branch）
+/stats              — 每日使用量、streak、模型偏好圖表
+/usage              — 方案上限 + rate limit 狀態
+/extra-usage        — 設定額外 rate limit
+/tasks              — 列出管理背景任務
+/insights           — CC session 使用模式分析報告
+/pr-comments [PR]   — 擷取 GitHub PR 評論進 context
+/review             — review PR 品質/安全
+/security-review    — 分析 pending changes 安全漏洞
+/privacy-settings   — 隱私設定（Pro/Max）
+/release-notes      — 完整 changelog
+/remote-env         — 設定預設遠端環境
+/mobile             — QR code 連接 mobile app
+/passes             — 分享免費週（Pro plan）
+/plan [description] — 進入 Plan Mode（v2.1.72：可直接帶描述，如 `/plan fix the auth bug`）
+```
+
+### 指令別名
+```
+/reset, /new        → /clear
+/config, /settings  → 設定（同一個）
+/desktop, /app      → Desktop connector
+/rewind, /checkpoint → rewind 功能
+```
+
+### 新環境變數
+```bash
+CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1      # 停用背景任務
+CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false  # 停用 prompt 建議
+CLAUDE_CODE_TASK_LIST_ID=my-project         # 跨 session 共享 task list
+```
+
+### PR 狀態欄
+Footer 彩色底線：🟢 passed / 🟡 pending / 🔴 failed / ⚪ draft / 🟣 merged，每 60 秒自動更新。
+
+### `--maintenance` Night Agent 用途
+```bash
+claude --maintenance   # 執行 PreMaintenance + PostMaintenance hooks 後退出
+# 適合 launchd plist: ExitProgramArgument = ["claude", "--maintenance"]
+```
+
+---
+
+
+---
+
+## Always Check
+- SQL injection / XSS in user input handling
+- Auth bypass conditions
+
+## Style
+- Follow existing naming conventions
+- No unused imports
+
+## Skip
+- Autogenerated files: dist/, generated/
+```
+
+### 監控使用量
+
+```
+claude.ai/analytics/code-review
+```
+- PR 審查數、weekly cost、feedback rate、per-repo 細分
+- 設月消費上限：`claude.ai/admin-settings/usage`
+
+### PR 規模與 Finding 統計
+
+- 大型 PR（>1000 行）：84% 有 findings，平均 7.5 issues
+- 小型 PR（<50 行）：31% 有 findings，平均 0.5 issues
+
+### 本機 Plugin（不需 Team/Enterprise）
+
+```bash
+/plugin install code-review@claude-code-plugins
+/code-review   # 推送前手動觸發
+```
+
+### 限制
+
+- 不支援 ZDR（Zero Data Retention）
+- 約 20 分鐘完成，不適合作為 merge gate
+
+### 與手動 @claude 觸發的差異
+
+| | 自動 PR Review | 手動 `@claude` |
+|--|--|--|
+| 觸發 | PR open/push | PR comment |
+| 費用 | $15-25/review | 依任務規模 |
+| 適合 | 所有 PR 一致性審查 | 特定問題追問 |
+| 設定 | Admin 啟用 | `/install-github-app` |
+
+---
+
+## 32. Claude Agent SDK（程式化 Agent）
+
+前身為 Claude Code SDK，讓 Claude 在程式中自主操作工具完成任務。
+
+### 安裝
+
+```bash
+pip install claude-agent-sdk           # Python
+npm install @anthropic-ai/claude-agent-sdk  # TypeScript
+```
+
+### vs Client SDK vs CLI
+
+| | Agent SDK | Client SDK | CLI (claude -p) |
+|--|--|--|--|
+| 工具迴圈 | 自動處理 | 手動 tool_call | 自動處理 |
+| 內建工具 | ✅ Read/Write/Bash 等 | ❌ | ✅ |
+| 適用 | CI/CD、Production | 簡單 API 呼叫 | 腳本、一次性 |
+
+### 認證注意
+
+```python
+agent = ClaudeAgent(api_key=os.environ["ANTHROPIC_API_KEY"])
+```
+
+**重要**：只能用 API key，**不支援** claude.ai OAuth 登入。
+Free/Pro/Max 帳號的 rate limit **不適用**於 Agent SDK。
+
+### 基本用法
+
+```python
+import asyncio
+from claude_agent_sdk import ClaudeAgent
+
+async def main():
+    agent = ClaudeAgent()
+    result = await agent.run("分析 src/ 並寫摘要")
+    print(result)
+
+asyncio.run(main())
+```
+
+### Sessions（對話續接）
+
+```python
+r1 = await agent.run("分析 auth.py")
+session_id = r1.session_id
+r2 = await agent.run("為上面的函式寫測試", session_id=session_id)
+```
+
+### Subagents（AgentDefinition）
+
+```python
+from claude_agent_sdk import AgentDefinition
+
+reviewer = AgentDefinition(
+    name="code-reviewer",
+    tools=["Read", "Glob", "Grep"],   # 限制工具
+    system_prompt="嚴格審查程式碼..."
+)
+result = await agent.run("審查變更", subagents=[reviewer])
+```
+
+### Hooks
+
+```python
+@agent.hook(HookType.PRE_TOOL_USE)
+async def before_tool(tool_name, tool_input):
+    # return {"action": "block"} 可阻止
+    pass
+
+@agent.hook(HookType.STOP)
+async def on_stop(result): pass
+```
+
+Hook 類型：PRE_TOOL_USE / POST_TOOL_USE / STOP / SESSION_START / SESSION_END
+
+### 常用選項
+
+```python
+agent = ClaudeAgent(
+    allowed_tools=["Read", "Glob"],   # 只允許讀取
+    disallowed_tools=["Bash"],
+    max_budget_usd=2.00,              # 成本上限
+    mcp_servers=[MCPServerConfig(...)]
+)
+```
+
+---
+

package/examples/reference/evolved-skills/claude-code-reference/ch11-output-versions.md

@@ -0,0 +1,172 @@
+# ch11: Output Styles + 版本更新（v2.1.72–80）+ CC Channels
+
+## 34. Output Styles（系統提示替換）
+
+Output Styles 直接**替換** Claude Code 的軟體工程 system prompt，用於非程式任務或整體風格改變（與 CLAUDE.md 附加不同）。
+
+```bash
+/config   # v2.1.73+ 在 /config 介面選擇（session 開始時固定，利於 prompt caching）
+```
+
+設定儲存於 `.claude/settings.local.json`。
+
+### 內建 Styles
+
+- `default` — 標準軟體工程模式
+- `explanatory` — 每個操作間加入教育性 Insights（學習 codebase 時有用）
+- `learning` — 協作學習模式：insights + 要求用戶完成部分代碼（加 `TODO(human)` 標記）
+
+### 自訂 Output Style
+
+```markdown
+<!-- ~/.claude/output-styles/my-style.md -->
+---
+name: 風格名稱
+description: 用途說明
+keep-coding-instructions: false   # false = 完全替換；true = 保留程式能力 + 自訂
+---
+[自訂 system prompt 內容...]
+```
+
+存放位置：
+- `~/.claude/output-styles/` — 個人（所有專案）
+- `.claude/output-styles/` — 專案級
+
+### 機制比較
+
+| 機制 | 作用點 | 適用場景 |
+|------|--------|---------|
+| Output Styles | 替換 system prompt（session 固定）| 非軟體任務、整體風格 |
+| CLAUDE.md | 附加到 user message（每次） | 持久規則、偏好 |
+| Skills | 任務觸發時載入 | 可重用工作流 |
+| `--append-system-prompt` | 附加到 system prompt | 單次 session 調整 |
+
+---
+
+## 35. v2.1.72–76 新功能速查
+
+> 詳細說明見 instinct `claude-code-v2174-features-2026.md`
+
+### v2.1.76（2026-03-14/15）
+
+- **MCP Elicitation**：MCP server 可在任務中途發出互動式 dialog 請求結構化輸入（`Elicitation` + `ElicitationResult` hooks 可攔截）
+- **`-n`/`--name` flag**：啟動時命名 session（`claude -n "my-task"`）
+- **`worktree.sparsePaths`**：大型 monorepo 用 git sparse-checkout 只 checkout 需要目錄
+- **`PostCompact` hook**：compaction 完成後觸發（可用於壓縮後清理或通知）
+- **`/effort` slash command**：在 session 中設定 effort level（原本需要 `--effort` CLI flag）
+- **Deferred tools schema 修復** ⭐：ToolSearch 載入的工具在 compaction 後不再遺失 input schema（修復 array/number 參數被拒絕）
+- **Background agent 改進**：kill 背景 agent 時保留其部分結果於 conversation context
+- **Stale worktree 清理**：平行跑 interrupted 後殘留的 worktree 自動清除
+- **Auto-compaction circuit breaker**：連續失敗 3 次停止自動重試（防無限迴圈）
+- **Remote Control 多項修復**：idle session 靜默死亡、rapid messages queuing、stale work items 等
+
+### v2.1.75（2026-03-14）
+
+- **Bash `!` mangling 修復**：jq `select(.x != .y)`、`history -c` 等含 `!` 語法現在正確執行
+- **Token 估算修復**：thinking + tool_use blocks 不再被過計，`/context` 百分比更可靠
+- **Memory files 最後修改時間**：Claude 可在 context 中看到記憶檔案的 timestamp，推理新鮮度
+- **1M context for Opus 4.6**：Max/Team/Enterprise plan 預設啟用，無額外計費
+- **Async hook 靜音**：`async: true` hooks 不再顯示 completion 訊息（`--verbose` 可見）
+- **`/color <hex>`**：為 session prompt bar 設顏色，方便識別多個 concurrent sessions
+- **`/rename <name>`**：session 名稱顯示於 prompt bar
+
+### v2.1.72–73
+
+- **Agent tool `model` 恢復**：per-invocation 模型覆寫（`"model": "haiku"` 在 Agent tool JSON）
+- **CLAUDE.md HTML 註解隱藏**：`<!-- 備注 -->` 自動注入時 Claude 看不到（Read tool 可見），可做私人備注
+- **`CLAUDE_CODE_DISABLE_CRON=1`**：立即停止所有 /loop 排程
+- **`ExitWorktree` tool**：離開 `EnterWorktree` session 的專用工具
+- **SDK `query()` cache 修復**：prompt cache 失效問題修復，input token 成本最高 -12x
+- **`modelOverrides` 設定**：將 model picker 選項映射到自訂 provider ID（Bedrock ARN 等）
+- **`lsof`、`pgrep`、`fd` 加入 bash auto-approve 清單**：減少常見唯讀命令的確認提示
+
+
+### v2.1.78（2026-03-19）
+
+- **`StopFailure` hook** ⭐：API 錯誤（rate limit、auth failure）結束 turn 時觸發，可捕捉靜默失敗
+- **`${CLAUDE_PLUGIN_DATA}`**：plugin 持久化狀態變數，升級後保留（搭配 `InstructionsLoaded` hook 讀取）
+- **Plugin agent frontmatter 新欄位**：`effort`、`maxTurns`、`disallowedTools`
+- **tmux 通知穿透**：`set -g allow-passthrough on` → 終端通知可穿透 tmux（支援 iTerm2/Kitty/Ghostty）
+- **回應逐行 streaming**：文字回應改為逐行輸出（非最後一次性）
+- **`ANTHROPIC_CUSTOM_MODEL_OPTION`**：在 `/model` picker 加入自訂 model entry
+- **安全修復** ⚠️（三項）：① `deny: ["mcp__servername"]` 未正確阻止 MCP tools → 已修復 ② sandbox 依賴缺失時靜默停用 → 改為警告 ③ `bypassPermissions` 可寫入 `.git`/`.claude` → 已修復
+- **Bug Fixes**：① `--resume` 大型 session（>5MB + subagent）歷史截斷 → 已修復 ② API 錯誤 → stop hook 無限迴圈 → 已修復 ③ `sandbox.filesystem.allowWrite` 不支援絕對路徑 → 已修復
+
+### v2.1.77（2026-03-18）
+
+- **Opus 4.6 output token 擴展** ⭐：預設 max output 4k → **64k**；上限 **128k**（對長程 coding/analysis 任務意義重大）
+- **安全修復** ⚠️：`PreToolUse` hook 回傳 `"allow"` 可繞過 `deny` 規則（含 enterprise managed settings）→ 已修復
+- **Agent tool API 重構**：`resume` 參數移除 → 改用 `SendMessage({to: agentId})` 繼續已停止的 agent；`SendMessage` 自動 resume stopped agent
+- **`/branch` 正式命名**：`/fork` 更名為 `/branch`（`/fork` 保留 alias，向後相容）
+- **`--resume` 競態修復**：memory-extraction write 與 transcript 競態導致歷史截斷 → 已修復
+- **`sandbox.filesystem.allowRead`**：在 `denyRead` 區域中例外放行特定路徑讀取（細粒度沙箱控制）
+- **`/copy N`**：複製第 N 條最近的 assistant 回應（N 預設 1 = 最新一條）
+
+### v2.1.79（2026-03-18）
+
+- **`SessionEnd` hooks 修復**：互動式 `/resume` 時不觸發 SessionEnd → 已修復
+- **`claude auth login --console`**：支援 Console 帳號認證（非 claude.ai 帳號）
+- **VSCode `/remote-control`**：橋接 claude.ai/code 的遠端控制
+- **Non-streaming fallback 2 分鐘 timeout**：API 不支援 streaming 時自動 fallback，每次嘗試 2 分鐘（解決長任務靜默超時問題）
+- **`CLAUDE_CODE_PLUGIN_SEED_DIR` 多目錄**：冒號（`:`）分隔多個 seed 目錄（Unix），方便共享 plugin 庫
+- **`/btw` 修復**：修復 `/btw` 回傳主 agent 輸出而非回答旁枝問題的 bug
+
+### v2.1.80（2026-03-19）⭐ 當前版本
+
+- **`effort` frontmatter for skills/commands** ⭐：在 `.md` skill/command YAML frontmatter 設定預設 effort：
+  ```yaml
+  ---
+  effort: low    # low | medium | high | max（max = Opus 4.6 only，最高品質）
+  ---
+  ```
+  夜間低風險任務可設 `low` 節省 token；high-stakes 任務設 `high` 提升品質。
+  也可在 shell 用 `CLAUDE_CODE_EFFORT_LEVEL=low claude -p "..."` 控制。
+- **`--channels` flag**：MCP server 可推送訊息到 session（research preview）— 詳見 Section 36
+- **statusline 新增 `rate_limits` 欄位**：可在 `~/.claude/statusline.sh` 加入 `rate_limits`，顯示 5h/7d 視窗的速率限制剩餘量
+- **修復 `--resume` 遺失平行 tool 結果**：多個 tool 並行呼叫在 resume 後不再遺失部分結果
+- **啟動記憶體減少 ~80MB**：大型 repo（250k+ 檔案）啟動時記憶體佔用大幅優化
+- **修復 managed settings 啟動未套用**：`remote-settings.json` 快取導致設定在啟動時未生效 → 已修復
+- **修復 `/remote-control` 出現在 gateway**：gateway 部署環境中不再顯示 `/remote-control`（不相容）
+
+## 36. CC Channels — Telegram/Discord 雙向橋接（v2.1.80+ research preview）
+
+允許 MCP server 推送事件到你的 CC session（CI 結果、Telegram 訊息、Discord DM），Claude 可反應並回覆。需 claude.ai 帳號（非 API key）。
+
+**快速設置（Telegram）：**
+```bash
+# 1. BotFather 建立 bot，取得 token
+# 2. 安裝插件（需 Bun）
+/plugin install telegram@claude-plugins-official
+# （找不到：先執行 /plugin marketplace add anthropics/claude-plugins-official）
+
+# 3. 設定 token
+/telegram:configure 123456789:AAHfiqks...
+
+# 4. 啟動並配對
+claude --channels plugin:telegram@claude-plugins-official
+# 在 Telegram 傳訊給 bot → 取得 pairing code
+/telegram:access pair <code>
+/telegram:access policy allowlist   # 只允許自己
+```
+
+**Discord 差異**：用 `/plugin install discord@claude-plugins-official`，Discord Developer Portal 建 bot，需啟用 Message Content Intent。
+
+**關鍵限制**：
+- 只在 session 開啟時有效；always-on 需 background process
+- `--channels` 明確指定才生效（.mcp.json 單獨不夠）
+- Team/Enterprise 預設停用，需 admin 在 managed settings 啟用
+
+**與 webhook 差異**：CC Channels = 雙向互動控制；webhook = 單向推送通知
+
+**Permission Relay（v2.1.81）**：channel servers 可將工具審核 prompt 轉發到手機。
+夜間 agent 遇到 sensitive 操作時，可透過 Telegram/Discord 通知用戶確認，而不是自動允許或拒絕。
+設定：在 `--channels` 啟動的 session 中，PermissionRequest 會同時推送到 channel。
+
+### v2.1.81（2026-03-22）
+
+- **`--bare` flag** ⭐：headless `-p` 呼叫跳過所有初始化（hooks/LSP/plugins/skill scan/auto-memory），大幅加速無狀態 script。限制：需 `ANTHROPIC_API_KEY`（不支援 OAuth/keychain）
+- **`--channels` permission relay**：PermissionRequest 轉發到手機 channel，夜間 agent 可請求人工審核高風險操作
+- **修復** background agent task 輸出卡住（polling interval 間完成的 race condition）
+- **修復** `--resume` worktree session 自動切換回 worktree 目錄
+- **修復** concurrent sessions OAuth token 刷新後需要重新認證（影響 heartbeat 多進程場景）
+- **MCP read/search** collapse 成單行顯示（大幅減少 UI 雜訊）

package/examples/reference/evolved-skills/claude-code-reference/index.md

@@ -0,0 +1,134 @@
+# Skill: Claude Code 功能參考手冊（Index）
+
+**Version:** 4.9
+**Icon:** eye
+**Abbr:** Reference
+**Use when:** 查閱 Claude Code 功能：hooks 設定、headless CLI flags、model 別名、permissions 規則、subagents、MCP、keybindings、版本更新要點
+
+---
+
+## 快速路由：讀哪個章節？
+
+| 你想做的事 | 章節文件 |
+|------------|---------|
+| 設計擴展架構（skill/hook/mcp 優先順序）| `ch01-extensions.md` |
+| 設定 Subagent / Agent Teams | `ch02-agents.md` |
+| 撰寫 Hooks（PreToolUse/PostSession 等）| `ch03-hooks.md` |
+| 設定 MCP 服務（基礎 + 進階）| `ch04-mcp.md` |
+| UI 功能（Checkpoint/排程/Remote/快捷鍵）| `ch05-ui.md` |
+| Rules / Plugins / 權限 / Sandboxing / 安全 | `ch06-rules-security.md` |
+| Model 設定 / opusplan / 記憶系統 / 成本 | `ch07-model-memory.md` |
+| 進階工作流 / Best Practices | `ch08-workflows.md` |
+| 外部整合（監控/Chrome/IDE/企業/Cloud）| `ch09-integrations.md` |
+| CLI flags / Agent SDK | `ch10-cli-sdk.md` |
+| Output Styles / 版本更新（v2.1.72–80）| `ch11-output-versions.md` |
+
+---
+
+## 決策樹：選什麼擴展方式？
+
+**我需要...**
+```
+永遠生效的規則 / 項目設定
+    → CLAUDE.md（< 200 行）or rules/（path-scoped）
+
+按需知識 / 可觸發工作流
+    → Skills（低 context，/name 觸發）
+
+隔離執行 / 並行任務 / 專用工作者
+    → Subagents（隔離 context）
+
+多 session 協同（需要互相通訊）
+    → Agent Teams（ch02-agents.md）
+
+連接外部服務（DB/Slack/browser）
+    → MCP（ch04-mcp.md）
+
+確定性腳本（lint/format/log）
+    → Hooks（零 context cost，ch03-hooks.md）
+
+跨專案打包分享
+    → Plugins（ch06-rules-security.md）
+```
+
+---
+
+## 決策樹：哪種 Model 設定？
+
+```
+需要深度推理 + 執行自動切 Sonnet
+    → opusplan 別名（ch07-model-memory.md）
+
+需要 1M context window
+    → sonnet[1m] 別名
+
+Opus 4.6 加速（速度 2.5x）
+    → /fast 或 Fast Mode（ch05-ui.md）
+
+設定 effort level
+    → CLAUDE_CODE_EFFORT_LEVEL=low|medium|high
+```
+
+---
+
+## 決策樹：Permissions / Security
+
+```
+查看/管理允許規則
+    → /permissions（ch06-rules-security.md）
+
+OS 層級隔離
+    → /sandbox（ch06-rules-security.md）
+
+Prompt injection 防護
+    → Sandboxing 安全優勢（ch06-rules-security.md）
+
+企業政策管理
+    → ch09-integrations.md
+```
+
+---
+
+## 擴展系統優先順序總覽
+
+| 功能 | Context 成本 | 適用情境 |
+|------|-------------|---------|
+| CLAUDE.md | 每次載入 | 永遠生效的規則 |
+| Skills | 低（按需）| 按需知識 / 工作流 |
+| Subagents | 與主 session 隔離 | 隔離執行 / 平行 |
+| Agent Teams | 高（獨立費用）| 多 session 協同 |
+| MCP | 每次（工具定義）| 外部服務 |
+| Hooks | **零** | 確定性腳本 |
+| Plugins | 同各組件 | 跨專案打包 |
+
+**CLAUDE.md 大小目標**：< 200 行（最多 ~500 行）。超過 → 移到 Skills（按需載入）
+
+---
+
+## Built-in Tools 速查
+
+| 類別 | 工具 |
+|------|------|
+| 檔案操作 | Read, Edit, Write |
+| 搜尋 | Glob（按名稱）、Grep（按內容）|
+| 執行 | Bash、Git |
+| Web | WebSearch、WebFetch |
+| 特殊 | Agent、TodoWrite、NotebookEdit |
+
+---
+
+## 最佳實踐摘要（Always Check）
+
+- `/permissions` — 確認目前允許規則
+- `git status` — 確認無未提交變更
+- 重大改動前 `git stash` — 保留快照
+- MCP 中途斷線 → `/mcp` 確認連線
+- subagent 不繼承主 session permissions
+
+**Style**：優先 CLI 工具（gh/gcloud）而非 MCP；subagent 用於隔離執行而非便利
+
+**Skip**：不要在 sandbox 模式下嘗試存取 Keychain
+
+---
+
+*詳細內容請讀對應章節文件（ch01–ch11）。章節文件含完整程式碼範例與邊界情境。*

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "homunculus-code",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A self-evolving AI assistant that grows smarter every night",
   "bin": {
-    "homunculus": "./bin/init.js"
+    "homunculus-code": "./bin/cli.js"
   },
   "keywords": [
     "ai",