持續學習 v2.1 - 直覺式架構

持續學習 v2.1 - 直覺式架構 是做什麼的？

一個先進的學習系統，能將您的 Claude Code 工作階段轉化為可重複使用的知識，透過原子化的「直覺」——帶有信賴分數的小型學習行為——來實現。

v2.1 新增了專案範圍直覺——React 模式留在您的 React 專案中，Python 慣例留在您的 Python 專案中，而通用模式（例如「始終驗證輸入」）則會全域共享。

何時啟用

• 設定從 Claude Code 工作階段自動學習
• 透過鉤子配置基於直覺的行為提取
• 調整學習行為的信賴臨界值
• 檢閱、匯出或匯入直覺庫
• 將直覺演化為完整的技能、指令或代理
• 管理專案範圍與全域直覺
• 將直覺從專案範圍提升至全域範圍

v2.1 的新功能

功能	v2.0	v2.1
儲存	全域 (~/.claude/homunculus/)	專案範圍 (${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects/<hash>/)
範圍	所有直覺都應用於所有地方	專案範圍 + 全域
偵測	無	git 遠端 URL / 儲存庫路徑
提升	不適用	當在 2 個以上專案中出現時，從專案提升為全域
指令	4 個 (status/evolve/export/import)	6 個 (+promote/projects)
跨專案	有污染風險	預設隔離

v2（相較於 v1）的新功能

功能	v1	v2
觀察	停止鉤子（工作階段結束）	PreToolUse/PostToolUse（100% 可靠）
分析	主要上下文	背景代理 (Haiku)
粒度	完整技能	原子化「直覺」
信賴度	無	0.3-0.9 加權
演化	直接到技能	直覺 -> 叢集 -> 技能/指令/代理
分享	無	匯出/匯入直覺

直覺模型

一個直覺是一個小型學習行爲：

---
id: prefer-functional-style
trigger: "when writing new functions"
confidence: 0.7
domain: "code-style"
source: "session-observation"
scope: project
project_id: "a1b2c3d4e5f6"
project_name: "my-react-app"
---

# 偏好函數式風格

## 動作

在適當情況下使用函數式模式而非類別。

## 證據
- 觀察到 5 個偏好函數式模式的實例
- 使用者在 2025-01-15 將基於類別的方法更正為函數式

屬性：

• 原子化 -- 一個觸發條件，一個動作
• 信賴加權 -- 0.3 = 暫定，0.9 = 幾乎確定
• 領域標記 -- code-style, testing, git, debugging, workflow 等
• 證據支持 -- 記錄哪些觀察結果建立了它
• 範圍感知 -- project（預設）或 global

運作方式

工作階段活動（在 git 儲存庫中）
      |
      | 鉤子捕捉提示 + 工具使用（100% 可靠）
      | + 偵測專案上下文（git 遠端 / 儲存庫路徑）
      v
+---------------------------------------------+
|  projects/<project-hash>/observations.jsonl  |
|   （提示、工具呼叫、結果、專案）                      |
+---------------------------------------------+
      |
      | 觀察者代理讀取（背景，Haiku）
      v
+---------------------------------------------+
|          模式偵測                              |
|   * 使用者更正 -> 直覺                        |
|   * 錯誤解決方案 -> 直覺                      |
|   * 重複工作流程 -> 直覺                      |
|   * 範圍決定：專案或全域？                      |
+---------------------------------------------+
      |
      | 建立/更新
      v
+---------------------------------------------+
|  projects/<project-hash>/instincts/personal/ |
|   * prefer-functional.yaml (0.7) [project]   |
|   * use-react-hooks.yaml (0.9) [project]     |
+---------------------------------------------+
|  instincts/personal/  （全域）                  |
|   * always-validate-input.yaml (0.85) [global]|
|   * grep-before-edit.yaml (0.6) [global]     |
+---------------------------------------------+
      |
      | /evolve 叢集 + /promote
      v
+---------------------------------------------+
|  projects/<hash>/evolved/ （專案範圍）          |
|  evolved/ （全域）                              |
|   * commands/new-feature.md                  |
|   * skills/testing-workflow.md               |
|   * agents/refactor-specialist.md            |
+---------------------------------------------+

專案偵測

系統會自動偵測您目前的專案：

1. CLAUDE_PROJECT_DIR 環境變數（最高優先順序）-- 即使目錄不是 git 儲存庫，也會被視為明確覆寫（以其絕對路徑進行雜湊處理）
2. git remote get-url origin -- 進行雜湊處理以建立可攜帶的專案 ID（同一儲存庫在不同機器上會得到相同的 ID）
3. git rev-parse --show-toplevel -- 使用儲存庫路徑作為備用方案（特定於機器）
4. 全域備用方案 -- 如果未偵測到專案，直覺將歸入全域範圍

每個專案會獲得一個 12 個字元的雜湊 ID（例如 a1b2c3d4e5f6）。位於 ${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects.json 的註冊表檔案會將 ID 對應到人類可讀的名稱。

資料目錄

Continuous-learning-v2 將觀察者資料儲存在 ~/.claude 之外，這樣 Claude Code 的敏感路徑防護就不會阻止背景直覺寫入：

1. CLV2_HOMUNCULUS_DIR 當設定為絕對路徑時
2. $XDG_DATA_HOME/ecc-homunculus
3. $HOME/.local/share/ecc-homunculus

現有用戶可以一次性地將資料從 ~/.claude/homunculus 遷移：

bash skills/continuous-learning-v2/scripts/migrate-homunculus.sh

快速開始

1. 啟用觀察鉤子

如果以插件形式安裝（建議）：

無需在 settings.json 中新增額外的鉤子區塊。Claude Code v2.1+ 會自動載入插件 hooks/hooks.json，而 observe.sh 已經在其中註冊。

如果您之前已將 observe.sh 複製到 ~/.claude/settings.json，請移除重複的 PreToolUse / PostToolUse 區塊。重複插件鉤子會導致雙重執行和 ${CLAUDE_PLUGIN_ROOT} 解析錯誤，因為該變數僅在插件管理的 hooks/hooks.json 條目中可用。

如果手動安裝到 ~/.claude/skills，請將以下內容新增到您的 ~/.claude/settings.json：

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
      }]
    }]
  }
}

2. 初始化目錄結構

系統會在首次使用時自動建立目錄，但您也可以手動建立它們：

# 全域目錄
mkdir -p "${XDG_DATA_HOME:-$HOME/.local/share}/ecc-homunculus"/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects}

# 專案目錄會在鉤子首次於 git 儲存庫中運行時自動建立

3. 使用直覺指令

/instinct-status     # 顯示已學習的直覺（專案 + 全域）
/evolve              # 將相關直覺叢集化為技能/指令
/instinct-export     # 將直覺匯出到檔案
/instinct-import     # 從他人處匯入直覺
/promote             # 將專案直覺提升為全域範圍
/projects            # 列出所有已知專案及其直覺數量

指令

指令	描述
/instinct-status	顯示所有直覺（專案範圍 + 全域）及其信賴度
/evolve	將相關直覺叢集化為技能/指令，建議提升
/instinct-export	匯出直覺（可按範圍/領域篩選）
/instinct-import <file>	匯入直覺，具有範圍控制功能
/promote [id]	將專案直覺提升為全域範圍
/projects	列出所有已知專案及其直覺數量

配置

編輯 config.json 以控制背景觀察者：

{
  "version": "2.1",
  "observer": {
    "enabled": false,
    "run_interval_minutes": 5,
    "min_observations_to_analyze": 20
  }
}

鍵	預設值	描述
observer.enabled	false	啟用背景觀察者代理
observer.run_interval_minutes	5	觀察者分析觀察結果的頻率
observer.min_observations_to_analyze	20	執行分析前的最小觀察數

其他行為（觀察捕捉、直覺臨界值、專案範圍設定、提升條件）透過 instinct-cli.py 和 observe.sh 中的程式碼預設值進行配置。

觀察者平台支援

背景觀察者需要 WSL2、Linux 或 macOS。在原生 Windows（Git Bash / MSYS2）上，它會啟動並報告成功，但當生成鉤子退出且其作業物件關閉時，程序會被終止，因此不會執行任何分析——在該平台上設定 observer.enabled: true 實際上是一個空操作（請參閱問題 #2489）。

observe.sh 會在隨後的鉤子調用中偵測到此情況，並在觀察者連續多次未能存活後，將解釋性警告寫入 observer-start.log。

環境變數	預設值	描述
ECC_OBSERVER_NOSURVIVE_WARN_AFTER	3	記錄警告前的連續未存活次數

檔案結構

${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/
+-- identity.json           # 您的個人檔案、技術等級
+-- projects.json           # 註冊表：專案雜湊 -> 名稱/路徑/遠端
+-- observations.jsonl      # 全域觀察結果（備用方案）
+-- instincts/
|   +-- personal/           # 全域自動學習的直覺
|   +-- inherited/          # 全域匯入的直覺
+-- evolved/
|   +-- agents/             # 全域生成的代理
|   +-- skills/             # 全域生成的技能
|   +-- commands/           # 全域生成的指令
+-- projects/
    +-- a1b2c3d4e5f6/       # 專案雜湊（來自 git 遠端 URL）
    |   +-- project.json    # 每個專案的元資料鏡像（id/name/root/remote）
    |   +-- observations.jsonl
    |   +-- observations.archive/
    |   +-- instincts/
    |   |   +-- personal/   # 專案特定的自動學習
    |   |   +-- inherited/  # 專案特定的匯入
    |   +-- evolved/
    |       +-- skills/
    |       +-- commands/
    |       +-- agents/
    +-- f6e5d4c3b2a1/       # 另一個專案
        +-- ...

範圍決定指南

模式類型	範圍	範例
語言/框架慣例	project	"使用 React hooks"、"遵循 Django REST 模式"
檔案結構偏好	project	"測試放在 __tests__/"、"元件放在 src/components/"
程式碼風格	project	"使用函數式風格"、"偏好 dataclasses"
錯誤處理策略	project	"對錯誤使用 Result 類型"
安全實務	global	"驗證使用者輸入"、"清理 SQL"
通用最佳實踐	global	"先寫測試"、"始終處理錯誤"
工具工作流程偏好	global	"在編輯前先 grep"、"在寫入前先讀取"
Git 實務	global	"慣例式提交"、"小而專注的提交"

直覺提升（專案 -> 全域）

當同一個直覺在具有高信賴度的多個專案中出現時，它就是提升為全域範圍的候選對象。

自動提升條件：

• 在 2 個以上專案中出現相同直覺 ID
• 平均信賴度 >= 0.8

如何提升：

# 提升特定直覺
python3 instinct-cli.py promote prefer-explicit-errors

# 自動提升所有符合條件的直覺
python3 instinct-cli.py promote

# 預覽而不進行變更
python3 instinct-cli.py promote --dry-run

/evolve 指令也會建議提升候選對象。

信賴度評分

信賴度會隨著時間演進：

分數	含義	行爲
0.3	暫定	建議但不強制執行
0.5	中等	相關時應用
0.7	強烈	自動批准應用
0.9	幾乎確定	核心行爲

信賴度增加當：

• 模式被重複觀察到
• 使用者沒有更正建議的行爲
• 來自其他來源的類似直覺一致

信賴度減少當：

• 使用者明確更正行爲
• 模式長時間未被觀察到
• 出現矛盾的證據

為什麼觀察使用鉤子而非技能？

「v1 依賴技能來觀察。技能是機率性的——它們大約在 50-80% 的時間內會根據 Claude 的判斷觸發。」

鉤子100% 確定性地觸發。這意味著：

• 每個工具呼叫都會被觀察到
• 沒有模式被遺漏
• 學習是全面的

向後相容性

v2.1 完全相容於 v2.0 和 v1：

• 現有的全域直覺可以透過 scripts/migrate-homunculus.sh 從 ~/.claude/homunculus/instincts/ 遷移
• v1 中現有的 ~/.claude/skills/learned/ 技能仍然可以運作
• 停止鉤子仍然會執行（但現在也會饋入 v2）
• 逐步遷移：兩者並行執行

隱私

• 觀察結果保留在您機器的本地端
• 專案範圍的直覺與每個專案隔離
• 只有直覺（模式）可以匯出——而非原始觀察結果
• 不會分享任何實際的程式碼或對話內容
• 您控制匯出和提升的內容

相關資源

• ECC-Tools GitHub App - 從儲存庫歷史生成直覺
• Homunculus - 社群專案，啟發了 v2 直覺式架構（原子觀察、信賴度評分、直覺演化管線）
• 長篇指南 - 持續學習章節

---

直覺式學習：教導 Claude 您的模式，一次一個專案。