homunculus-code 0.1.0 → 0.2.0

package/examples/reference/evolved-skills/claude-code-reference/ch09-integrations.md

@@ -0,0 +1,502 @@
+# ch09: 外部整合（監控/Chrome/IDE/企業政策/GitLab/LLM Gateway/Plugin/Cloud/PR Review）
+
+## 21. 監控與 OTel
+
+```bash
+export CLAUDE_CODE_ENABLE_TELEMETRY=1
+export OTEL_METRICS_EXPORTER=console    # 本地 debug
+export OTEL_METRICS_EXPORTER=prometheus # Prometheus 整合
+export OTEL_METRICS_EXPORTER=otlp       # 完整 OTLP（Grafana/Datadog）
+```
+
+**8 個 Metrics**：session count、LOC（added/removed）、PR count、commit count、**cost（USD）**、**tokens**（input/output/cache）、code edit decisions、active time
+
+**5 個 Events**（OTel Logs）：user_prompt、api_request（含 cost_usd、speed）、api_error、tool_result（含 duration_ms、bash_command）、tool_decision
+
+**`prompt.id`**：UUID 追蹤單一 prompt 觸發的所有 API calls + tool results
+
+**Analytics Dashboard（Teams/Enterprise）**：https://claude.ai/analytics/claude-code
+
+### PR 歸因（Analytics）
+
+Merge 後自動標記 **`claude-code-assisted`** label（GitHub PR）：
+- 歸因窗口：merge 前 **21 天** + merge 後 **2 天**的 session activity
+- 自動過濾：lock files、build artifacts、minified（>1000 chars/line）
+- 保守估計：只計「高確信度」貢獻
+
+```bash
+# 程式化查詢
+gh pr list --label "claude-code-assisted" --state merged | wc -l
+```
+
+> ⚠️ 只支援 GitHub（不支援 GitLab）
+
+---
+
+## 22. Chrome 瀏覽器整合
+
+```bash
+claude --chrome      # 啟用（單次）
+/chrome              # session 中切換 / 查看狀態 / 重連
+```
+
+**前置條件**：
+- Chrome 或 Edge（非 Brave/Arc）+ [Claude in Chrome extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) >= v1.0.36
+- **必須直接 Anthropic 帳號**（❌ 不支援 Bedrock/Vertex/Foundry）
+
+**核心能力**：
+- Live debugging（讀 console errors + DOM，立即修代碼）
+- 共享 browser login state（可存取 Gmail/Notion/任何已登入網站）
+- GIF 錄製（`Record a GIF showing...`）
+- 資料抽取（網頁 → CSV/JSON）
+- 自動填表（從本地 CSV 讀取）
+
+```text
+# 典型用法
+> Open localhost:3000 and check the console for errors
+> Record a GIF showing the checkout flow
+> Fill the form with data from contacts.csv
+```
+
+**對比 Playwright MCP**：
+- `--chrome` = 簡單設定，共享登入，適合本地測試
+- Playwright MCP = 精確控制，適合 CI/CD、headless
+
+→ **quest-board 本地開發優先 `--chrome`，CI/CD 用 Playwright**
+
+⚠️ 預設啟用會增加 context（browser tools 常駐），按需使用
+
+---
+
+## 23. IDE 整合：VS Code 與 JetBrains
+
+### VS Code Extension 快捷鍵
+
+| 快捷鍵 | 功能 |
+|--------|------|
+| `Cmd+Esc` / `Ctrl+Esc` | Toggle focus：editor ↔ Claude |
+| `Option+K` / `Alt+K` | Insert @-mention with file path + line numbers |
+| `Cmd+Shift+Esc` | Open in new tab |
+
+**@-mentions**（VS Code 專有）：
+```text
+@app.ts#5-10        ← Option+K 自動插入（含行號）
+@terminal:name      ← 引用 terminal 輸出
+@browser            ← Chrome 整合
+```
+
+**Permission Modes**（設定 `claudeCode.initialPermissionMode`）：
+- `default`：每次詢問
+- `plan`：先出計劃 markdown，你 inline comment 後再執行
+- `acceptEdits`：自動接受修改
+- `bypassPermissions`：全自動（devcontainer 環境才推薦）
+
+**Remote Sessions**：Past Conversations → Remote tab → 繼續 claude.ai web session
+
+**URI Handler**（外部開啟 session）：
+```
+vscode://anthropic.claude-code/open?prompt=<encoded>&session=<id>
+```
+從其他 app（Slack bot / CLI / 網頁）直接在 VS Code 觸發 Claude Code。
+
+**Checkpoint（Rewind）**：hover 任何 message → rewind 按鈕 → Fork/Rewind code/Both
+
+### JetBrains Plugin（IntelliJ、PyCharm、WebStorm、GoLand 等）
+
+**安裝**：JetBrains Marketplace 搜尋 "Claude Code Beta"
+
+**快捷鍵**（JetBrains 特有）：
+
+| 快捷鍵 | 功能 |
+|--------|------|
+| `Cmd+Esc` / `Ctrl+Esc` | 開啟 Claude Code 面板 |
+| `Cmd+Option+K` / `Alt+Ctrl+K` | 插入 file reference（@File#L1-99）|
+
+**JetBrains 獨特功能**：
+- **Diagnostic sharing**：IDE 的 lint/syntax 錯誤自動傳給 Claude
+- **Selection context**：當前選取/tab 自動共享給 Claude
+- **Diff viewer**：程式碼變更在 IDE 的 diff viewer 顯示（非 terminal）
+
+**Remote Development 注意**：
+- 必須在遠端 host 安裝 plugin（Settings → Plugin (Host)）
+- 不是安裝在本機 client
+
+**ESC 鍵設定**（JetBrains terminal 問題）：
+```
+Settings → Tools → Terminal
+→ 取消勾選 "Move focus to the editor with Escape"
+（否則 ESC 被 IDE 攔截，無法中斷 Claude）
+```
+
+**安全注意**：auto-edit 模式可能修改 IDE config 檔案（自動執行風險）。
+
+### 共用（VS Code + JetBrains）
+
+```bash
+claude --resume   # IDE session 繼續到 CLI
+/ide              # Terminal Claude 連接到 IDE（啟用 diff viewer）
+```
+
+### Terminal 最佳化
+
+- **Shift+Enter**（換行）：iTerm2/WezTerm/Ghostty/Kitty 原生支援；其他用 `/terminal-setup`
+- **Vim 模式**：`/vim` 或 `/config` 啟用（支援 hjkl/w/e/b/dd/yy 等常用指令）
+- **通知**：完成後觸發 notification event（Kitty/Ghostty 原生；iTerm2 需設定）
+- VS Code terminal 對超長貼上有截斷問題 → 改用 file-based 工作流
+
+---
+
+## 24. 企業政策管理（Server-Managed Settings）
+
+**需求**：Teams/Enterprise 方案 + Claude Code >= 2.1.38
+
+### 兩種集中管理方式
+
+| 方式 | 最適合 | 強度 |
+|------|--------|------|
+| Server-managed | 無 MDM / 非管理裝置 | 中（client-side） |
+| Endpoint-managed | 有 MDM 的組織 | 高（OS 層級保護） |
+
+同時存在時：server-managed 優先；兩者都凌駕所有用戶設定和 CLI args。
+
+### 設定方式
+Claude.ai → Admin Settings → Claude Code → Managed settings → 填 JSON
+
+```json
+{
+  "permissions": {
+    "deny": ["Bash(curl *)", "Read(./.env)", "Read(./secrets/**)"]
+  },
+  "disableBypassPermissionsMode": "disable"
+}
+```
+
+### 快取與推送
+- 啟動時 + 每小時 polling 更新
+- 有快取：立即套用，背景刷新
+- 無快取（首次）：非同步拉取（有短暫空窗期）
+
+### 安全性對話框
+以下設定需用戶明確批准：
+- Shell command settings
+- 自訂環境變數（非 allowlist）
+- Hook 設定
+
+用戶拒絕 → Claude Code 退出；`-p` headless 跳過對話框。
+
+### 不支援 Server-Managed 的情況
+Bedrock / Vertex AI / Foundry / `ANTHROPIC_BASE_URL` / LLM Gateway 時繞過。
+
+### ConfigChange Hook
+```json
+"ConfigChange": [{ "type": "command", "command": "log_config_change.sh" }]
+```
+用於偵測/記錄設定被更改。
+
+### 資料保留政策
+
+| 用戶類型 | 保留期 |
+|---------|--------|
+| Consumer（允許訓練）| 5 年 |
+| Consumer（不允許）| 30 天 |
+| Commercial（Team/Enterprise/API）| 30 天 |
+| Enterprise + ZDR | 0 天 |
+
+**訓練政策**：Commercial 用戶預設不訓練；Bedrock/Vertex 不支援 Developer Partner Program。
+
+### 隱私 Env Vars
+
+```bash
+DISABLE_TELEMETRY=1                          # 停用 Statsig 指標
+DISABLE_ERROR_REPORTING=1                   # 停用 Sentry 錯誤
+DISABLE_BUG_COMMAND=1                       # 停用 /bug 指令（送完整 transcript）
+CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1       # 停用問卷（Bedrock/Vertex 預設 off）
+CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1  # 一次停用所有非必要流量 ⭐
+CLAUDE_CODE_DISABLE_CRON=1                  # 立即停用 session 內的 /loop 排程（v2.1.72）⭐
+CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1     # 從 system prompt 移除內建 git 工作流指令（v2.1.69）
+CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000  # SessionEnd hook 超時（預設 1500ms，常導致 session-end.js 被中止）（v2.1.74）
+```
+Bedrock/Vertex/Foundry：以上非必要流量**預設全部停用**。
+
+---
+
+## 25. GitLab CI/CD 整合（Beta）
+
+Beta 功能，由 GitLab 維護（非 Anthropic）。
+
+### 最小設定
+
+1. Settings → CI/CD → Variables → 加入 `ANTHROPIC_API_KEY`（masked）
+2. 在 `.gitlab-ci.yml` 加入 claude job：
+
+```yaml
+claude:
+  stage: ai
+  image: node:24-alpine3.21
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "web"'
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+  before_script:
+    - apk add --no-cache git curl bash
+    - curl -fsSL https://claude.ai/install.sh | bash
+  script:
+    - /bin/gitlab-mcp-server || true
+    - >
+      claude -p "${AI_FLOW_INPUT:-'Review and implement changes'}"
+      --permission-mode acceptEdits
+      --allowedTools "Bash Read Edit Write mcp__gitlab"
+```
+
+### AI_FLOW_* 變數（webhook 觸發時）
+- `AI_FLOW_INPUT` — 用戶留言（`@claude` 後的文字）
+- `AI_FLOW_CONTEXT` — issue/MR 上下文
+- `AI_FLOW_EVENT` — 事件類型
+
+### 與 GitHub Actions 差異
+| | GitHub Actions | GitLab CI/CD |
+|--|--|--|
+| 狀態 | GA | Beta |
+| 工具 | `mcp__github` | `mcp__gitlab` |
+| 安裝 | `/install-github-app` | 手動 YAML |
+| 觸發 | PR comment | issue/MR comment（需 webhook）|
+
+### 企業提供者 OIDC
+- **AWS Bedrock**：GitLab OIDC → `assume-role-with-web-identity`（無靜態 key）
+- **Vertex AI**：Workload Identity Federation（無下載 key）
+
+### 進階參數
+- `max_turns` — 限制回合數
+- `timeout_minutes` — 限制執行時間
+- `--debug` — 輸出詳細 log
+
+
+---
+
+## 26. LLM Gateway 整合（企業代理）
+
+LLM gateway（如 LiteLLM）提供集中認證、cost tracking、audit log、model routing。
+
+### 環境變數設定
+
+```bash
+# 統一端點（LiteLLM Anthropic 格式，推薦）
+export ANTHROPIC_BASE_URL=https://litellm-server:4000
+
+# 靜態 API key（作為 Authorization header）
+export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key
+
+# 動態 key helper（JWT 或 vault）
+# settings.json 中設定：
+# { "apiKeyHelper": "~/bin/get-litellm-key.sh" }
+
+# key 刷新間隔（毫秒）
+export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000
+
+# Bedrock through LiteLLM
+export ANTHROPIC_BEDROCK_BASE_URL=https://litellm-server:4000/bedrock
+export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
+export CLAUDE_CODE_USE_BEDROCK=1
+
+# Vertex through LiteLLM
+export ANTHROPIC_VERTEX_BASE_URL=https://litellm-server:4000/vertex_ai/v1
+export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
+export CLAUDE_CODE_USE_VERTEX=1
+
+# 當用 Anthropic Messages 格式連 Bedrock/Vertex 時
+export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
+```
+
+### Gateway 需求
+
+Gateway 必須支援以下 API 格式之一：
+- **Anthropic Messages**：`/v1/messages`（需轉發 `anthropic-beta`、`anthropic-version` headers）
+- **Bedrock InvokeModel**：`/invoke`（需保留 body 的 `anthropic_beta`、`anthropic_version`）
+- **Vertex rawPredict**：`:rawPredict`
+
+---
+
+## 27. Plugin Marketplace 管理
+
+### 企業管理員設定
+
+```json
+// .claude/settings.json — 推薦用戶安裝的 marketplace
+{
+  "extraKnownMarketplaces": {
+    "company-tools": {
+      "source": { "source": "github", "repo": "your-org/claude-plugins" }
+    }
+  },
+  "enabledPlugins": {
+    "code-formatter@company-tools": true
+  }
+}
+```
+
+```json
+// managed settings — 限制只允許特定 marketplace（企業管控）
+{
+  "strictKnownMarketplaces": [
+    { "source": "github", "repo": "acme-corp/approved-plugins" },
+    { "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
+  ]
+}
+```
+
+`[]` = 完全鎖定（禁止新增任何 marketplace）
+
+### Marketplace 建立
+
+```
+.claude-plugin/marketplace.json   ← 目錄結構
+```
+
+Plugin sources：`relative path`、`github`、`url`、`git-subdir`（sparse clone）、`npm`、`pip`
+
+```bash
+# 驗證 marketplace
+claude plugin validate .
+/plugin validate .
+
+# 增加 git timeout（慢速網路）
+export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000
+```
+
+`${CLAUDE_PLUGIN_ROOT}` — 在 hooks/MCP 設定中引用 plugin 內的檔案。
+
+### Release Channels
+- 建立兩個 marketplace 指向同一 repo 的不同 git ref（stable/latest）
+- 透過 managed settings 的 `extraKnownMarketplaces` 分配給不同用戶群
+
+
+---
+
+## 28. Cloud Provider 設定（Bedrock / Vertex AI）
+
+### Amazon Bedrock
+
+```bash
+export CLAUDE_CODE_USE_BEDROCK=1
+export AWS_REGION=us-east-1  # 必須！不讀 .aws config
+
+# 認證（選其一）
+aws configure                                    # CLI 設定
+export AWS_BEARER_TOKEN_BEDROCK=your-api-key    # 最簡單
+aws sso login --profile p && export AWS_PROFILE=p  # SSO
+
+# 自動 SSO 刷新（settings.json）
+# "awsAuthRefresh": "aws sso login --profile myprofile"
+```
+
+**Bedrock 特有功能**：
+```bash
+# 指定 Haiku 使用不同 region
+export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2
+
+# AWS Guardrails（settings.json）
+# "ANTHROPIC_CUSTOM_HEADERS": "X-Amzn-Bedrock-GuardrailIdentifier: id\nX-Amzn-Bedrock-GuardrailVersion: 1"
+```
+
+IAM 最小權限：`bedrock:InvokeModel` + `bedrock:InvokeModelWithResponseStream` + `bedrock:ListInferenceProfiles`
+
+### Google Vertex AI
+
+```bash
+export CLAUDE_CODE_USE_VERTEX=1
+export CLOUD_ML_REGION=global          # 推薦（可用性最佳）
+export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID
+
+# Haiku 不支援 global → 指定 region
+export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5
+export VERTEX_REGION_CLAUDE_4_0_OPUS=europe-west1  # Opus 用 EU
+```
+
+**1M Token Context Window**（Vertex beta）：需 header `context-1m-2025-08-07`
+
+IAM：`roles/aiplatform.user`（包含 `aiplatform.endpoints.predict`）
+
+### 共同重要設定
+
+```bash
+# ⚠️ 部署必做：固定模型版本（防止新版上線破壞帳號）
+# Bedrock
+ANTHROPIC_DEFAULT_SONNET_MODEL='us.anthropic.claude-sonnet-4-6'
+ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'
+# Vertex  
+ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
+ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'
+
+# 某些 region 不支援 prompt caching
+export DISABLE_PROMPT_CACHING=1
+```
+
+### Microsoft Foundry（Azure AI Foundry）
+
+```bash
+export CLAUDE_CODE_USE_FOUNDRY=1
+export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
+# 認證（API key 或 Entra ID 自動）
+export ANTHROPIC_FOUNDRY_API_KEY=your-key  # 或 az login
+```
+RBAC：`Azure AI User` 或 `Cognitive Services User`
+
+### 三者共同限制
+- `/login` `/logout` 停用
+- server-managed settings 繞過
+- 非必要遙測預設全部停用
+- ⚠️ **固定模型版本**（不固定 → 新版上線可能破壞帳號）
+- 建議建立**獨立帳號/專案**追蹤費用
+
+### LLM Gateway Skip-Auth（三者通用）
+```bash
+export ANTHROPIC_BEDROCK_BASE_URL='https://gateway.example.com/bedrock'
+export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1   # Gateway 處理 AWS auth
+
+export ANTHROPIC_VERTEX_BASE_URL='https://gateway.example.com/vertex'
+export CLAUDE_CODE_SKIP_VERTEX_AUTH=1   # Gateway 處理 GCP auth
+
+export ANTHROPIC_FOUNDRY_BASE_URL='https://gateway.example.com'
+export CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1  # Gateway 處理 Azure auth
+```
+用 `/status` 確認 gateway 設定。
+
+---
+
+
+---
+
+## 31. 自動 PR Code Review（Teams/Enterprise）
+
+Teams 和 Enterprise 功能。PR 開啟或 commit 更新時，自動觸發多 agent 並行分析。
+
+### 啟用步驟
+
+1. Admin 進入 `claude.ai/admin-settings/claude-code`
+2. 安裝 Claude GitHub App（需要 **Contents read + Pull requests write** 權限）
+3. 選擇要啟用的 repositories
+4. 設定觸發方式：
+   - **After PR creation**：每 PR 執行一次（較省費）
+   - **After every push**：每次 commit 都執行（較即時，費用較高）
+
+### 分析特點
+
+- **多 agent 並行分析**：邏輯錯誤、安全問題、regression
+- **Inline comments 嚴重度標籤**：
+  - 🔴 Normal — 需要修改
+  - 🟡 Nit — 建議改善（非必要）
+  - 🟣 Pre-existing — 既有問題，非此 PR 引入
+- 完成時間：約 20 分鐘
+- 費用：約 **$15–25 / review**（多 agent 並行）
+- **不阻塞 merge**：pure advisory
+
+### 自訂 Review 規則
+
+| 檔案 | 用途 |
+|------|------|
+| `CLAUDE.md` | 專案共用規則（違反 → nit 等級 finding） |
+| `REVIEW.md` | **review 專用**規則（風格指引、必查清單、跳過模式）|
+
+`REVIEW.md` 是獨立於 `CLAUDE.md` 的 review-only 規則檔。建議內容：
+```markdown
+# Review Rules
+