内容
# OpenSddRag
**规范驱动开发（SDD）+ 框架** — 带有持久化语义记忆的MCP服务器和用于规范化软件开发的结构化工作流。
---
## 什么是 OpenSddRag
OpenSddRag 为 AI 代理（如 Claude Code）提供**持久记忆**和**规范驱动工作流**。与代理临时工作的方式不同，每次变更都经过定义明确的阶段：提出 → 规范 → 设计 → 任务 → 应用 → 验证 → 存档。
### 两个独立的软件包
| 软件包 | 技术 | 角色 |
|---|---|---|
| `mcp-server/` | Python + PostgreSQL/pgvector | 核心MCP服务器：存储制品、跟踪和会话上下文 |
| `client/` | Node.js | 连接任何项目到正在运行的MCP服务器的CLI |
### SDD 概念（规范驱动开发）
所有工作都遵循依赖顺序的制品生命周期：
```
提案 → 规范 → 设计 → 任务 → 应用 → 验证 → 同步增量 → 存档
```
每个制品都存储在数据库中，带有向量嵌入，从而实现对项目决策历史的语义搜索。
---
## 架构
### 三层记忆
| 表 | 类型 | 描述 |
|---|---|---|
| `artifacts` | 语义记忆 | 提案、规范、设计、任务 — 每个都有一个 `vector(384)` 嵌入 |
| `execution_traces` | 情景记忆 | 代理操作日志，带有用于回忆的嵌入 |
| `sessions` | 工作上下文 | 活动制品ID + 每个项目的自由格式JSON |
| `skills` | SDD模板 | 全局（`project_id IS NULL`）或项目范围 |
| `projects` | 多租户注册表 | 系统中注册的项目 |
| `artifact_relationships` | 依赖图 | 制品之间的链接（`depends_on`、`implements`、`relates_to`） |
| `project_rules` | 框架规则 | 在SDD阶段强制执行的、带有严重性和触发器的行为约束 |
所有向量都使用HNSW索引（`vector_cosine_ops`）。嵌入维度为384，通过`all-MiniLM-L6-v2`实现。
有关服务器端层模型（Clean Architecture），请参见 [mcp-server/docs/architecture/clean-architecture.md](mcp-server/docs/architecture/clean-architecture.md)。
---
## 先决条件
- **Docker** 和 **Docker Compose** （用于在容器中运行数据库和MCP服务器）
- **Python 3.11+** 和 **[uv](https://github.com/astral-sh/uv)** （用于本地运行 `mcp-server`）
- **Node.js 18+** 和 **npm** （用于 `client`）
---
## 快速入门
启动数据库和MCP服务器的最简单方法：
```bash
docker compose up -d
```
这将启动：
- **PostgreSQL/pgvector** 在端口 `54326` （从容器映射）
- **MCP服务器** （SSE模式）在端口 `8000`
验证它们是否正在运行（预计响应为 `401` — 默认启用身份验证）：
```bash
curl http://localhost:8000/health
```
然后创建API密钥并连接您的项目：
```bash
# 创建API密钥（需要Python虚拟环境）
cd mcp-server && source .venv/bin/activate
opensddrag-server key create --description "local dev"
# 连接项目（从目标项目根目录运行）
opensddrag init --api-key <key>
```
---
## 环境配置
在本地运行 `mcp-server` （在Docker外部）之前，请复制示例环境文件：
```bash
cp mcp-server/.env.example mcp-server/.env
```
`mcp-server/.env` 中的关键变量：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `DATABASE_URL` | `postgresql://opensddrag:opensddrag@localhost:54326/opensddrag` | 数据库连接字符串 |
| `EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | 嵌入模型（sentence-transformers） |
| `OPENSDDRAG_PROJECT` | `default` | 活动项目slug |
| `AUTH_ENABLED` | `true` | 在SSE模式下启用身份验证 |
---
## 身份验证
MCP服务器在 `AUTH_ENABLED=true` （默认值）时在SSE模式下需要API密钥。API密钥通过 `opensddrag-server` CLI进行管理，该CLI直接连接到数据库 — 不需要运行服务器。
首先激活Python虚拟环境：
```bash
cd mcp-server && source .venv/bin/activate
```
### 创建API密钥
```bash
# 全局密钥 — 适用于任何项目
opensddrag-server key create --description "local dev"
# 项目范围密钥 — 限制在特定项目内
opensddrag-server key create --project <slug> --description "prod key"
# 带有过期日期
opensddrag-server key create --description "ci key" --expires-at 2027-01-01
```
密钥的明文仅显示一次 — 立即保存。
### 使用密钥
将其传递给 `opensddrag init`：
```bash
opensddrag init --api-key <key>
```
### 管理密钥
```bash
opensddrag-server key list # 列出所有密钥及其状态
opensddrag-server key revoke <key-id> # 通过UUID吊销密钥
```
### 禁用身份验证（仅限本地开发）
在 `docker-compose.yml` 或 `mcp-server/.env` 中设置 `AUTH_ENABLED=false` 并重启：
```bash
docker compose up -d --force-recreate
```
---
## mcp-server (Python)
### 安装
```bash
cd mcp-server
# 安装软件包和依赖项
uv pip install -e .
# 运行迁移并播种全局SDD技能
opensddrag-server init
```
### 本地运行（stdio模式）
Claude Code可以直接将服务器作为子进程启动：
```bash
opensddrag-server server start
```
### 作为HTTP服务器运行（SSE模式）
用于远程使用或通过Docker：
```bash
opensddrag-server server start --transport sse --port 8000
```
SSE模式下的可用端点：
- `GET /health` — 健康检查
- `GET /sse` — MCP客户端的SSE流
- `POST /messages/` — MCP消息端点
- `GET /api/projects` — 项目列表（由Node.js客户端使用）
- `POST /api/projects` — 创建项目（由Node.js客户端使用）
### 测试
```bash
cd mcp-server
pytest # 所有测试
pytest tests/test_foo.py # 特定文件
pytest -k "test_name" # 按名称测试
```
---
## client (Node.js)
客户端通过安装Claude Code需要的文将任何软件项目连接到正在运行的MCP服务器。
### 安装
```bash
cd client
npm install
```
### 连接项目到MCP服务器
从**目标项目的根目录**运行（不是此存储库）：
```bash
# 当 `AUTH_ENABLED=true` （默认值）时，传递您的API密钥：
opensddrag init --api-key <key> [--server http://localhost:8000] [--project <slug>] [--yes]
```
选项：
- `--api-key` — API密钥（当 `AUTH_ENABLED=true` 时需要）
- `--server` — MCP服务器URL（默认值：`http://localhost:8000`）
- `--project` — 要注册的项目slug（默认值：目录名称）
- `--yes` — 自动接受所有提示
### `init` 在目标项目中安装的内容
| 文件/文件夹 | 描述 |
|---|---|
| `.mcp.json` | 配置Claude Code通过SSE连接到MCP服务器 |
| `.claude/commands/opsr/*.md` | `/opsr:*` 用于Claude Code的斜杠命令 |
| `.claude/skills/opensddrag-*/SKILL.md` | OpenSddRag技能，用于Claude Code |
| `.agents/skills/opensddrag-*/SKILL.md` | 其他兼容代理的技能 |
| `CLAUDE.md` （追加部分） | 指导Claude Code了解OpenSddRag项目 |
### 检查连接状态
```bash
node bin/opensddrag.js status
```
---
## MCP 传输
### stdio （本地使用）
Claude Code将 `opensddrag-server server start` 作为子进程启动。通信发生在标准输入/标准输出上。适用于Claude Code和服务器在同一台机器上运行的本地开发。
通过目标项目中的 `.mcp.json` 配置（由 `client init` 生成）：
```json
{
"mcpServers": {
"opensddrag": {
"type": "stdio",
"command": "opensddrag-server",
"args": ["server", "start"]
}
}
}
```
### SSE （远程或Docker）
服务器公开HTTP端点。适用于MCP服务器在Docker上运行、在另一台机器上运行或在多个开发人员之间共享。
通过 `.mcp.json` 配置为指向SSE端点：
```json
{
"mcpServers": {
"opensddrag": {
"type": "http",
"url": "http://localhost:8000/sse"
}
}
}
```
---
## SDD 工作流
完整的规范驱动开发工作流：
| 阶段 | 制品 | 描述 |
|---|---|---|
| **提出** | `proposal.md` | 定义内容和原因 — 问题、变更、受影响的能力 |
| **规范** | `specs/<cap>/spec.md` | 定义系统应执行的操作 — 可测试的需求与WHEN/THEN场景 |
| **设计** | `design.md` | 定义如何实现 — 技术决策、权衡、风险 |
| **任务** | `tasks.md` | 带复选框的可跟踪任务列表 |
| **应用** | （代码） | 实现任务，逐步标记 `[ ]` → `[x]` |
| **验证** | （测试） | 验证规范场景是否满足 |
| **同步增量** | （增量规范） | 将修改后的规范合并回基准 (`openspec/specs/`) |
| **存档** | （最终确定） | 关闭变更，记录在历史中 |
### 斜杠命令
由 `client init` 安装到 `.claude/commands/opsr/`：
| 命令 | 阶段 | 描述 |
|---|---|---|
| `/opsr:propose` | 提出 | 创建提案并指导变更定义 |
| `/opsr:spec` | 规范 | 根据提案生成能力规范 |
| `/opsr:design` | 设计 | 创建技术设计文档 |
| `/opsr:tasks` | 规划 | 将设计分解为可实现任务 |
| `/opsr:apply` | 实现 | 顺序实现任务，跟踪进度 |
| `/opsr:verify` | 验证 | 验证规范场景是否满足实现的代码 |
| `/opsr:sync` | 同步 | 将增量规范合并回基准规范 |
| `/opsr:archive` | 存档 | 最终确定并存档变更 |
| `/opsr:explore` | 探索 | 在提出变更前调查问题 |
| `/opsr:continue` | 继续 | 恢复正在进行中的变更 |
| `/opsr:status` | 状态 | 显示所有活动变更的当前状态 |
| `/opsr:flow` | 流 | 通过下一个SDD步骤的交互式指南 |
| `/opsr:search` | 搜索 | 对制品和轨迹进行语义搜索 |
---
## 框架
框架是一种规则引擎，强制执行SDD工作流阶段的项目级行为约束。规则在上下文重置后仍然存在 — 它们存储在数据库中，并自动注入到每个代理会话中。
### 工作原理
- 规则按项目存储，带有**触发器**、**类别**、**严重性**和纯英文**指令**
- 带有 `trigger="always"` 的规则自动注入到 `get_working_context` 的 `rules` 键中 — 每个代理会话开始时都加载它们，无需额外的工具调用
- 特定阶段的规则通过 `/opsr:apply`、`/opsr:verify`、`/opsr:spec` 和 `/opsr:archive` 内的 `get_harness_checklist` 以检查清单的形式显示
### 规则字段
| 字段 | 值 | 描述 |
|---|---|---|
| `trigger` | `always`、`on_apply`、`on_verify`、`on_archive`、`on_spec` | 规则何时触发 |
| `category` | `architecture`、`naming`、`forbidden`、`doc-sync`、`verification` | 规则族 |
| `severity` | `error`、`warning`、`info` | 代理应如何权衡违规行为 |
| `instruction` | （自由文本） | 代理必须遵循的人类可读指南 |
| `enabled` | `true` / `false` | `false` 软删除规则 |
### MCP 工具
| 工具 | 描述 |
|---|---|
| `add_rule` | 创建或更新规则（在 `(project_slug, name)` 上幂等） |
| `list_rules` | 列出活动规则；传递 `enabled_only=false` 以包含禁用规则 |
| `get_harness_checklist` | 返回具有阶段触发器的启用规则，按严重性然后名称排序 |
### `/opsr:harness` 命令
`opensddrag init` 安装了 `/opsr:harness` 斜杠命令和 `opensddrag-harness` 技能到连接的项目中。使用它直接从Claude Code管理规则：
```
/opsr:harness
```
该命令通过上述MCP工具指导代理添加、列出和禁用项目规则。
### 示例
**结构不变式（注入每个会话）：**
```
add_rule
name: "no-direct-db-in-controllers"
trigger: "always"
category: "architecture"
severity: "error"
instruction: "控制器永远不能直接导入数据库模块。所有数据库访问必须通过存储库或服务层。"
```
**阶段门控（在每次应用前检查）：**
```
add_rule
name: "migrations-separate-task"
trigger: "on_apply"
category: "architecture"
severity: "warning"
instruction: "数据库迁移必须在专用任务中实现，与应用程序代码更改分开。"
```
**禁用规则：**
```
add_rule
name: "migrations-separate-task"
enabled: false
```
---
## CLI 命令参考
所有命令都需要数据库可访问。
### 项目
```bash
opensddrag-server project list # 列出所有项目
opensddrag-server project create <slug> # 创建新项目
opensddrag-server project show <slug> # 显示项目详情
```
### 规范
```bash
opensddrag-server spec list # 列出活动项目的规范
opensddrag-server spec create <name> # 创建规范
opensddrag-server spec show <id> # 显示特定规范
```
### 任务
```bash
opensddrag-server task list # 列出活动项目的任务
opensddrag-server task create <description> # 创建任务
opensddrag-server task show <id> # 显示特定任务
```
### 技能
```bash
opensddrag-server skill list # 列出可用技能
opensddrag-server skill create <name> # 创建技能
opensddrag-server skill suggest <query> # 建议与查询相关的技能
```
### 语义搜索
```bash
opensddrag-server search semantic "<query>" # 按语义相似性搜索制品
```
### 会话和工作区
```bash
opensddrag-server session show # 显示活动项目的会话上下文
opensddrag-server workspace init # 初始化活动项目的工作区
```
### 导入 OpenSpec
将 OpenSpec 项目的规划制品导入 OpenSddRag：
```bash
opensddrag-server import openspec /path/to/project # 导入所有变更和全局规范
opensddrag-server import openspec /path/to/project --change add-auth # 仅导入单个变更
opensddrag-server import openspec /path/to/project --force # 重新导入和重新嵌入现有变更
opensddrag-server import openspec /path/to/project --project my-slug # 指定目标项目
```
### API 密钥
管理SSE模式身份验证的API密钥。需要激活Python虚拟环境（`cd mcp-server && source .venv/bin/activate`）。
```bash
opensddrag-server key create # 创建全局密钥
opensddrag-server key create --project <slug> # 项目范围密钥
opensddrag-server key create --description "label" # 带有描述
opensddrag-server key create --expires-at 2027-01-01 # 带有过期日期
opensddrag-server key list # 列出所有密钥及其状态
opensddrag-server key revoke <key-id> # 通过UUID吊销密钥
```
---
## 许可证
请参阅存储库根目录中的 `LICENSE` 文件。
