Decision Os MCP

🚀 Decision OS MCP

Decision OS MCP 是 Decision OS 的 MCP 服務器，Decision OS 是一個原生大語言模型（LLM）的決策跟蹤與學習系統。它能有效捕捉工程工作中的意外時刻，構建獨特的學習循環，助力開發者更好地應對挑戰和積累經驗。

🚀 快速開始

1. 安裝 MCP 服務器

# 全局安裝
npm install -g decision-os-mcp

# 或者使用 npx（無需安裝）
npx decision-os-mcp

2. 添加到項目

將模板複製到你的項目中：

cp -r templates/.decision-os /path/to/your-project/

使用你的項目名稱編輯 config.yaml。

3. 配置你的代理

Cursor

添加到項目的 .cursor/mcp.json 文件中：

{
  "mcpServers": {
    "decision-os": {
      "command": "npx",
      "args": ["-y", "decision-os-mcp"],
      "env": {
        "DECISION_OS_PATH": "${workspaceFolder}/.decision-os"
      }
    }
  }
}

複製 Cursor 規則模板：

cp templates/.cursor/rules/decision-os.mdc /path/to/your-project/.cursor/rules/

Claude Code / Claude Desktop

添加到你的 Claude Desktop 配置文件（在 macOS 上為 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "decision-os": {
      "command": "npx",
      "args": ["-y", "decision-os-mcp"],
      "env": {
        "DECISION_OS_PATH": "/absolute/path/to/your-project/.decision-os"
      }
    }
  }
}

複製代理說明模板（包含一個指向 AGENTS.md 的 .claude/rules/ 符號鏈接）：

cp templates/AGENTS.md /path/to/your-project/
cp -R templates/.claude /path/to/your-project/

⚠️ 重要提示

Claude Desktop 在 DECISION_OS_PATH 中需要使用絕對路徑（不能使用 ${workspaceFolder}）。

AGENTS.md 是一個開放標準，支持 20 多種編碼代理，包括 OpenAI Codex、Google Jules、Claude Code、Cursor、Aider、Zed、Warp、VS Code 等。.claude/rules/ 符號鏈接也能讓 Claude Code 自動識別它 —— 一份文件，適用於所有代理。

✨ 主要特性

工具

📚 詳細文檔

核心概念

壓力事件

主要的學習成果，當意外情況發生時進行記錄：

expected: "Supabase insert would throw on null FK"
actual: "RLS silently blocked the write, no error"
adaptation: "Added explicit null-check before insert"
remember: "Supabase RLS fails silently on null FK values"

基礎信息

從重複的壓力事件中提煉出的壓縮學習成果：

id: F-0001
title: "Supabase RLS fails silently on null FK"
default_behavior: "Always validate FK values before insert when using RLS"
context_tags: [SUPABASE, RLS, DATA_MODEL]
confidence: 2  # Out of 3
scope: PROJECT  # or GLOBAL
origin_project: my-project
validated_in: [my-project, other-project]
exit_criteria: "Supabase adds explicit error for null FK violations"
source_pressures: [PE-0003, PE-0007]

分層基礎信息（全局 -> 項目）

Decision OS 支持類似於 Git 配置的級聯範圍模型：

~/.decision-os/                    # GLOBAL (用戶範圍，通用學習成果)
├── config.yaml
└── defaults/foundations.yaml      # GF 前綴的基礎信息

~/projects/my-app/.decision-os/    # PROJECT (特定於該代碼庫)
├── config.yaml
├── cases/
└── defaults/foundations.yaml      # F 前綴的項目學習成果

解析順序：在發生衝突時，項目範圍的基礎信息優先於全局範圍。

全局基礎信息是建議，而非規則。它們代表了超越特定技術棧的通用模式：

• 工具行為（例如，“MCP 描述符路徑可能過時”）
• 調試策略（例如，“在重構之前跟蹤調用點”）
• 元學習（例如，“在實現之前質疑需求”）

設置全局基礎信息：

# 創建全局 .decision-os
mkdir -p ~/.decision-os/defaults
cp templates/global-.decision-os/config.yaml ~/.decision-os/
cp templates/global-.decision-os/defaults/foundations.yaml ~/.decision-os/defaults/

衝突檢測：當調用 get_context 時，它會突出顯示項目和全局基礎信息重疊或相互矛盾的衝突情況。

案例

有邊界的工作單元（功能、錯誤修復、探索性工作），為壓力事件提供上下文：

id: 0001-add-tile-caching
title: "Add tile caching"
goal: "Reduce API latency for repeated tile requests"
status: ACTIVE
signals:
  context:
    risk_level: MEDIUM
    affected_surface: [PERFORMANCE_CRITICAL, INTEGRATION]
decisions:
  approach: BUILD
  posture: BALANCED
  validation_level: STANDARD

目錄結構

# 全局（用戶範圍）
~/.decision-os/
├── config.yaml               # 範圍: GLOBAL
└── defaults/
    └── foundations.yaml      # GF 前綴的通用學習成果

# 項目（每個代碼庫）
your-project/
├── .decision-os/
│   ├── config.yaml           # 範圍: PROJECT
│   ├── cases/
│   │   ├── 0001-bootstrap/
│   │   │   ├── case.yaml     # 案例元數據
│   │   │   └── pressures.yaml # 壓力事件
│   │   └── 0002-add-auth/
│   │       └── ...
│   └── defaults/
│       └── foundations.yaml  # F 前綴的項目學習成果
├── .cursor/                  # Cursor 設置
│   ├── mcp.json              # MCP 服務器配置
│   └── rules/
│       └── decision-os.mdc   # LLM 說明（Cursor 格式）
├── .claude/                  # Claude Code 設置
│   └── rules/
│       └── decision-os.md    # -> 符號鏈接到 ../../AGENTS.md
├── AGENTS.md                 # 代理說明（Claude Code、Codex、Jules 等）
└── src/

LLM 工作流程

1. 任務開始時：調用 get_context() 加載活動案例和基礎信息（按相關性排序）
2. 遇到意外時：調用 quick_pressure() 進行快速捕獲，或調用 log_pressure() 進行詳細記錄
3. 做出構建決策之前：調用 check_policy() 查看要求
4. 任務結束時：調用 close_case() 並提供遺憾分數
5. 定期：調用 suggest_review() 查找未提取的學習內容和遺忘機會

遺忘機制

系統設計為自動遺忘。案例是臨時容器，知識存在於基礎信息中。

當使用 遺憾分數為 0 調用 close_case() 且 沒有未提升的壓力事件 時，案例將被自動刪除，而不是存檔。

這使得 .decision-os/cases/ 目錄保持簡潔：只有仍有未壓縮學習內容（未提升的壓力事件或遺憾分數大於 0）的案例才會保留。

生命週期如下：

1. 案例誕生：工作開始時
2. 壓力事件捕獲：發生意外時
3. 壓力事件提升：出現模式時將壓力事件提升為基礎信息
4. 案例遺忘：案例沒有可學習內容時
5. 基礎信息留存：作為唯一持久的知識

使用 suggest_review() 查找阻礙遺忘的案例（遺憾分數為 0 但仍有未提升的壓力事件），並決定是否提升或丟棄它們。

活動案例持久化

活動案例會持久保存到 .decision-os/.active-case，即使 MCP 服務器重啟也不會丟失。這樣，當 Cursor 重啟時，你不會丟失活動案例。

信號詞彙表

上下文信號（執行前）

• risk_level：低 / 中 / 高
• reversibility：容易 / 中等 / 困難
• change_frequency：罕見 / 偶爾 / 頻繁
• affected_surface：核心領域 / 集成 / 數據模型 / 基礎設施部署 / 安全邊界 / 用戶界面和用戶體驗 / 性能關鍵
• novelty：低 / 中 / 高

決策

• approach：複用 / 重構 / 構建 / 混合
• posture：最小化 / 平衡 / 健壯
• validation_level：基本 / 標準 / 嚴格

結果信號

• regret：0 - 3（0 = 會做出相同選擇，3 = 強烈遺憾）
• regressions：無 / 輕微 / 嚴重

🔧 技術細節

開發

# 安裝依賴
npm install

# 構建
npm run build

# 本地運行
DECISION_OS_PATH=/path/to/.decision-os npm start

設計理念

• 僅記錄新穎的壓力：不記錄大語言模型可以推導出來的內容
• 系統應具備遺忘能力：成功的案例會被刪除，知識存在於基礎信息中，而不是案例中
• 基於假設，而非公理：基礎信息有置信度，可以進行修訂
• 簡化流程：使用少量詞彙，結構清晰但不繁瑣
• 先捕獲，後過濾：不確定時先記錄，捕獲過多比錯過意外情況要好
• 原生支持大語言模型：專為人工智能輔助的工程工作流程設計

📄 許可證

本項目採用 MIT 許可證。