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 许可证。