README.zh-TW.md

Trapic — AI 程式助手的長期記憶

English | 繁體中文 | 日本語

你的 AI 每次對話都從零開始。Trapic 解決這個問題。

決策、慣例、發現 — 自動捕捉、即時回憶、智慧衰減。

為什麼選 Trapic？

1. 自動回憶：每個 Session 都帶著記憶開始

AI 助手在 session 開始的瞬間載入專案知識 — 團隊決策、程式慣例、跨分支活動。不需要手動說明，不需要「讓我重新看一下 codebase」，直接擁有完整上下文。

2. 知識捕捉 + 衝突偵測

當你做出技術決策（「從 Redux 換成 Jotai」），Trapic 會靜默記錄。如果和之前的決策矛盾，舊的會自動被標記為取代 — 沒有過時知識，沒有矛盾。

3. 智慧衰減：知識會優雅地老化

不是所有知識的保鮮期都一樣。專案狀態（state）30 天衰減、架構決策（decision）90 天、命名慣例（convention）180 天。過期的 trace 會自動被標記、審查、清理。

---

安裝

方式 A：一鍵安裝腳本（推薦）

最穩定的安裝方式。在專案根目錄執行：

curl -fsSL https://raw.githubusercontent.com/trapicAi/trapic-plugin/main/scripts/install.sh | bash

一次搞定所有設定：

• MCP server 設定（.mcp.json）
• SessionStart hook 自動回憶
• CLAUDE.md 指示注入（即使 hook 沒觸發，AI 也會照做）
• Token 存入 ~/.claude/settings.json

方式 B：Plugin 安裝

/plugin marketplace add trapicAi/trapic-plugin
/plugin install trapic@trapicAi-trapic-plugin --scope user

關於 Claude Code 的 plugin 系統： Marketplace 還很年輕。Hook 有時不觸發、環境變數要手動設定、錯誤訊息讓人摸不著頭緒（「Duplicate hooks file detected」— 謝了 Anthropic）。Plugin 安裝是能用的，但如果遇到問題，方式 A 是久經考驗的選擇。我們已經回報了不少 feedback，希望會改善。

安裝後在 ~/.claude/settings.json 設定 token：

{
  "env": {
    "TRAPIC_TOKEN": "tr_your_token_here"
  }
}

到 trapic.ai 註冊取得 API token。設定後重啟 Claude Code。

方式 C：完全手動

1. 設定 token — 編輯 ~/.claude/settings.json：

{
  "env": {
    "TRAPIC_TOKEN": "tr_your_token_here"
  }
}

2. 加入 MCP server — 在專案根目錄建立 .mcp.json（${TRAPIC_TOKEN} 會自動從步驟 1 讀取）：

{
  "mcpServers": {
    "trapic": {
      "type": "http",
      "url": "https://mcp.trapic.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${TRAPIC_TOKEN}"
      }
    }
  }
}

3. 加入自動回憶 hook（選用） — 建立 .claude/hooks/trapic-recall.sh：

#!/bin/bash
PROJECT=$(git remote get-url origin 2>/dev/null | sed 's|.*/||;s|\.git$||')
BRANCH=$(git branch --show-current 2>/dev/null || echo "main")
[ -z "$PROJECT" ] && PROJECT=$(basename "$(pwd)")

cat <<EOF
Call trapic to load project knowledge before responding:
trapic({action: "recall", params: { context: "session start", scope: ["project:${PROJECT}", "branch:${BRANCH}"], project: "${PROJECT}" }})
EOF

然後在 .claude/settings.json 註冊 hook：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/trapic-recall.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

設定完成後重啟 Claude Code。

解除安裝

curl -fsSL https://raw.githubusercontent.com/trapicAi/trapic-plugin/main/scripts/uninstall.sh | bash

移除 MCP 設定、hook、CLAUDE.md 指示，token 可選擇是否移除。

你會得到什麼

1 個統一 MCP 工具

Trapic 使用單一統一工具以最小化上下文視窗開銷（~170 tokens vs 12 個獨立工具的 ~3,100 tokens）。

動作	功能
trapic({action: "recall"})	Session 開始時載入專案知識
trapic({action: "create"})	建立新的知識 trace
trapic({action: "search"})	用關鍵字、標籤、scope 搜尋
trapic({action: "update"})	更新 trace 狀態、內容、標籤
trapic({action: "health"})	專案知識健康度報告
trapic({action: "decay"})	掃描過期/衰減中的知識
trapic({action: "review-stale"})	確認或廢棄過期 trace

舊工具名稱（如 trapic-recall）仍然可以使用（向後相容）。

4 個 Skill（僅 plugin 安裝）

Skill	觸發方式	功能
trapic-knowledge	自動（寫程式時）	靜默捕捉決策、慣例、事實，含衝突偵測
trapic-search	/trapic-search 或「找 XX 的 trace」	語意推斷 topic tag 的智慧搜尋
trapic-review	/trapic-review	commit 前慣例檢查 + 過期知識清理
trapic-health	/trapic-health 或「知識庫狀態」	健康度、類型分佈、衰減指標

運作流程

1. Session 開始 — Hook + CLAUDE.md 觸發 trapic({action: "recall"})，載入完整專案上下文
2. 寫程式時 — 決策、慣例、事實被靜默捕捉，帶 topic tag
3. 每次決策前 — 衝突偵測搜尋相同 topic，自動取代過時 trace
4. 搜尋 — trapic({action: "search"}) 從模糊查詢推斷 topic tag，語意匹配
5. commit 前 — /trapic-review 檢查 staged diff 是否違反慣例
6. 維護 — /trapic-health 顯示健康度，衰減系統標記過期知識

需求

• Claude Code CLI（或任何支援 MCP 的 AI 工具）
• Trapic 帳號 + API token（trapic.ai）

連結

• 網站：trapic.ai
• 文件：trapic.ai/docs
• MCP Server：https://mcp.trapic.ai/mcp

授權

MIT