内容
# 决策图
具备 `CLI + API + MCP` 的工程决策记忆系统，以及 [`docs`](./docs) 中的文档前端。
<p align="center">
<img src="./assets/decisiongraph-logo.svg" alt="DecisionGraph logo" width="460">
</p>
## 为什么选择决策图
软件团队通常记得**发生了什么**，但却忘记了**为什么要这样做**。决策图通过证据记录决策过程，使团队能够快速前进而不重复旧的错误。
- 保存具有支持证据的架构决策。
- 快速回答 `为什么 / 谁 / 何时 / 发生了什么变化` 等问题。
- 在进行高风险重构前添加预变更防护措施。
- 通过 CLI、HTTP API 和 MCP 工具公开相同的决策记忆。
## 视觉架构
## 核心能力
### 1) 数据摄入
- 本地文本/文件/目录。
- Git 提交历史记录。
- GitHub 拉取请求和问题。
- Slack 导出 JSON。
- Jira 导出 JSON。
- 通用 JSONL 事件流。
### 2) 决策智能
- 置信度 + 警告的决策查询。
- 带有过滤器的决策列表/搜索（`q`、`tag`、`component`、`owner`、`decision_type`）。
- 替换流程，链接新决策覆盖旧推理。
- 合并/去重流程，用于重叠决策。
- 按组件/标签/所有者/类型查看时间线。
- 证据质量评分，检测弱决策。
- 矛盾检测。
- 从实时指标检测过时假设。
- 假设观察器，带有 `warn/critical` 升级跟踪、审计日志和可选的连接器通知（`webhook|slack|discord|teams`）。
- 所需决策字段的治理策略模式（`off|warn|strict`）。
- 摘要报告和图形快照。
### 3) 运维 + 策略实用程序
- KPI 快照和场景检查。
- 针对 JSONL 基准数据集的评估。
- 安全审计、医生检查、发布检查。
- 用于 GTM 和产品框架的策略部分库/搜索。
## 快速入门（后端）
```bash
python -m pip install -e ".[dev]"
decisiongraph init --reset
decisiongraph seed-demo
decisiongraph serve --host 127.0.0.1 --port 8000 --seed-demo
```
快速入门演示：
健康检查：
```bash
curl http://127.0.0.1:8000/health
```
打开 API 文档：
- `http://127.0.0.1:8000/docs`
## 快速入门（Docker）
```bash
cp .env.example .env
docker compose up --build -d
```
检查健康状况：
```bash
curl http://127.0.0.1:8000/health
```
跟踪日志/停止：
```bash
docker compose logs -f decisiongraph
docker compose down
```
生产环境注意事项：
- 如果设置 `DECISIONGRAPH_ENV=production`，请在 `.env` 中设置 `DECISIONGRAPH_API_TOKEN`（或故意设置 `DECISIONGRAPH_REQUIRE_TOKEN_IN_PRODUCTION=false`）。
## 仅 CLI 模式（无 Web 服务器）
如果您只需要终端使用，请跳过 `decisiongraph serve`。
```bash
python -m pip install -e ".[dev]"
decisiongraph init --reset
decisiongraph seed-demo
decisiongraph chat
```
Windows 命令提示符（`cmd`）：
```cmd
py -m pip install -e ".[dev]"
decisiongraph init --reset
decisiongraph seed-demo
decisiongraph chat
```
在聊天中，直接提问或使用命令：
```text
/help
/list 20
/find <query>
/supersede <new_id> <old_id>
/merge <primary_id> <duplicate_id>
/timeline 20
/quality
/get <decision_id>
/guard <change request>
/contradictions
/stale
/watch
/audit 20
/metrics
/graph
/report json
/exit
```
非交互式 CLI 等价命令：
```bash
decisiongraph list
decisiongraph list --q "rabbitmq" --tag queues
decisiongraph find "rabbitmq" --tag queues
decisiongraph list --owner finance --decision-type risk-policy
decisiongraph query "Why did we cap payment retries at 2?"
decisiongraph supersede <new_decision_id> <old_decision_id>
decisiongraph merge <primary_decision_id> <duplicate_decision_id> --note "dedupe"
decisiongraph timeline --component payment-retry --exclude-superseded
decisiongraph evidence-quality --weak-threshold 0.5
decisiongraph quality --weak-threshold 0.5
decisiongraph watch-assumptions --notify --notify-target slack
decisiongraph watch
decisiongraph audit-log --limit 100 --event assumption.watch_run
decisiongraph audit --limit 100 --event assumption.watch_run
decisiongraph guardrail "Increase retry attempts in payment flow"
```
如果 `decisiongraph` 命令在 PATH 中不可用：
```bash
python -m decisiongraph list
python -m decisiongraph query "Why did we cap payment retries at 2?"
```
## 快速入门（文档前端）
```bash
cd docs
npm install
npm run dev
```
## MCP 服务器（stdio）
```bash
decisiongraph mcp
```
## 环境设置
创建环境文件：
```bash
cp .env.example .env
```
Windows PowerShell：
```powershell
Copy-Item .env.example .env
```
Windows 命令提示符（`cmd`）：
```cmd
copy .env.example .env
```
关键变量：
- `DECISIONGRAPH_ENV=development`
- `DECISIONGRAPH_DATA_PATH=data/decisiongraph.json`
- `DECISIONGRAPH_API_TOKEN` 可选 API 密钥（`x-api-key` 头部）
- `DECISIONGRAPH_REQUIRE_TOKEN_IN_PRODUCTION=true` 在生产环境中启动时阻止无令牌访问
- `DECISIONGRAPH_AUTO_SEED_DEMO=false` 在 `decisiongraph serve` 启动时自动播种演示数据
- `DECISIONGRAPH_GOVERNANCE_MODE=off` 治理策略模式（`off|warn|strict`）
- `DECISIONGRAPH_GOVERNANCE_REQUIRED_FIELDS=owners,assumptions,risks` 启用治理时所需字段
- `DECISIONGRAPH_RATE_LIMIT_PER_MINUTE=240` 每个客户端的速率限制（`0` 禁用）
- `DECISIONGRAPH_AUDIT_LOG_RETENTION=5000` 最多保留的审计事件
- `DECISIONGRAPH_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:5173`
- `DECISIONGRAPH_GITHUB_TOKEN` 用于 GitHub 数据摄入
- `DECISIONGRAPH_GITHUB_BASE_URL=https://api.github.com`
- `DECISIONGRAPH_ALERT_WEBHOOK_URL` 默认观察者 Webhook
- `DECISIONGRAPH_ALERT_SLACK_WEBHOOK`、`DECISIONGRAPH_ALERT_DISCORD_WEBHOOK`、`DECISIONGRAPH_ALERT_TEAMS_WEBHOOK` 连接器特定的观察者 Webhook
- `SE_URL` 旧版备用（优先使用 `DECISIONGRAPH_GITHUB_BASE_URL`）
- `GROQ_API_KEY`、`GROQ_MODELS` 可选模型集成
安全注意事项：
- 永远不要在 `.env` 中提交真实的密钥。
- 只需提交 `.env.example`。
## 端到端演示（2 分钟）
1. 播种数据并运行 API：
```bash
decisiongraph init --reset
decisiongraph seed-demo
decisiongraph serve --host 127.0.0.1 --port 8000
```
2. 提出一个为什么问题：
```bash
curl -X POST http://127.0.0.1:8000/api/query \
-H "content-type: application/json" \
-d '{"question":"Why did we cap payment retries at 2?"}'
```
3. 在更改前运行防护措施：
```bash
curl -X POST http://127.0.0.1:8000/api/guardrail \
-H "content-type: application/json" \
-d '{"change_request":"Increase retry attempts in payment flow"}'
```
4. 检查过时假设：
```bash
curl http://127.0.0.1:8000/api/assumptions/stale
```
5. 搜索决策并过滤：
```bash
curl "http://127.0.0.1:8000/api/decisions?limit=10&q=rabbitmq&tag=queues"
curl "http://127.0.0.1:8000/api/decisions?owner=finance&decision_type=risk-policy"
```
6. 使用替换流程链接替换决策：
```bash
curl -X POST http://127.0.0.1:8000/api/decisions/supersede \
-H "content-type: application/json" \
-d '{"decision_id":"<new_decision_id>","superseded_decision_id":"<old_decision_id>"}'
```
7. 合并重复的决策记录：
```bash
curl -X POST http://127.0.0.1:8000/api/decisions/merge \
-H "content-type: application/json" \
-d '{"primary_decision_id":"<primary_id>","duplicate_decision_id":"<duplicate_id>","note":"same rationale"}'
```
8. 运行假设观察器：
```bash
curl -X POST http://127.0.0.1:8000/api/assumptions/watch \
-H "content-type: application/json" \
-d '{"warn_severities":["medium","high"],"critical_severities":["high"],"notify":true,"notify_target":"slack"}'
```
## API 接口（主要端点）
### 系统
- `GET /`
- `GET /health`
- `GET /api/report/summary?format=json|markdown`
### 决策
- `GET /api/decisions`（支持 `limit`、`q`、`tag`、`component`、`owner`、`decision_type`）
- `GET /api/decisions/timeline`
- `GET /api/decisions/evidence-quality`
- `GET /api/decisions/{decision_id}`
- `POST /api/decisions/supersede`
- `POST /api/decisions/merge`
- `POST /api/query`
- `POST /api/guardrail`
- `GET /api/contradictions`
- `GET /api/assumptions/stale`
- `POST /api/assumptions/watch`
- `GET /api/audit/logs`
- `GET /api/metrics`
- `POST /api/metrics`
- `GET /api/graph`
### 数据摄入
- `POST /api/ingest`
- `POST /api/ingest/directory`
- `POST /api/ingest/git`
- `POST /api/ingest/jsonl`
- `POST /api/ingest/github`
- `POST /api/ingest/slack-export`
- `POST /api/ingest/jira-json`
### 智能 / 运维
- `GET /api/scenarios/run`
- `GET /api/kpi/snapshot`
- `POST /api/eval/dataset`
- `POST /api/eval/benchmark-check`
- `POST /api/research/scorecard`
- `GET /api/research/interview-script`
- `POST /api/research/design-partner-progress`
- `GET /api/strategy/sections`
- `GET /api/strategy/section/{section_id}`
- `GET /api/strategy/search?q=...`
- `GET /api/ops/doctor`
- `GET /api/ops/runbook`
- `GET /api/ops/release-check`
- `GET /api/ops/security-audit`
- `GET /api/schema/info`
## CLI 参考
### 核心
- `decisiongraph init [--reset]`
- `decisiongraph seed-demo`
- `decisiongraph chat [--list-limit 20] [--guardrail-limit 3]`
- `decisiongraph list --limit 20 [--q ...] [--tag ...] [--component ...] [--owner ...] [--decision-type ...]`
- `decisiongraph find <query> [--limit ...] [--tag ...] [--component ...] [--owner ...] [--decision-type ...]`（别名：search/list）
- `decisiongraph get <decision_id>`
- `decisiongraph supersede <decision_id> <superseded_decision_id>`
- `decisiongraph merge <primary_decision_id> <duplicate_decision_id> [--note ...]`
- `decisiongraph timeline [--limit 200] [--component ...] [--tag ...] [--owner ...] [--decision-type ...] [--exclude-superseded]`
- `decisiongraph evidence-quality [--limit 200] [--weak-threshold 0.45]`
- `decisiongraph quality [--limit 200] [--weak-threshold 0.45]`（别名）
- `decisiongraph query "..."`
- `decisiongraph guardrail "..."`
- `decisiongraph contradictions`
- `decisiongraph stale-assumptions`
- `decisiongraph watch-assumptions [--warn medium,high] [--critical high] [--notify --notify-target slack --webhook-url ...]`
- `decisiongraph watch [--warn medium,high] [--critical high] [--notify --notify-target ...]`（别名）
- `decisiongraph audit-log [--limit 100] [--event ...]`
- `decisiongraph audit [--limit 100] [--event ...]`（别名）
- `decisiongraph metric-set --key ... --value ... [--unit ...]`
- `decisiongraph metrics`
- `decisiongraph graph`
- `decisiongraph report --format markdown|json [--output ...]`
### 运行时
- `decisiongraph serve [--host 127.0.0.1] [--port 8000] [--seed-demo|--no-seed-demo]`
- `decisiongraph mcp`
### 数据摄入
- `decisiongraph ingest --source <file> --source-id <id> [--source-type note]`
- `decisiongraph ingest-text --source-id <id> --text "..." [--source-type note]`
- `decisiongraph ingest-dir --directory <dir> [--pattern "*.md"]`
- `decisiongraph ingest-git --repo <repo_path> [--max-commits 200] [--ref HEAD]`
- `decisiongraph ingest-jsonl --source <file.jsonl> [--source-type external]`
- `decisiongraph ingest-github --owner <org> --repo <name> [--state all]`
- `decisiongraph ingest-slack-export --export-dir <dir> [--max-messages 1000]`
- `decisiongraph ingest-jira-json --source <jira.json>`
### 洞察 + 运维
- `decisiongraph scenarios`
- `decisiongraph kpi`
- `decisiongraph eval-dataset --dataset <eval.jsonl>`
- `decisiongraph benchmark-check --dataset <eval.jsonl> [--min-top1 0.7] [--min-keyword-coverage 0.7]`
- `decisiongraph research-score --pain-frequency ... --impact ...`
- `decisiongraph research-script`
- `decisiongraph design-partner-progress`
- `decisiongraph strategy-list | strategy-show <section> | strategy-search "..."`
- `decisiongraph doctor | runbook | release-check | security-audit | schema-info`
## MCP 工具
运行 stdio 服务器：
```bash
decisiongraph mcp
```
工具组：
- 核心工具：query, list/filter, supersede, merge, timeline, evidence quality, guardrail, contradictions, stale assumptions, watch assumptions, audit logs, metrics, graph, report.
- 数据摄入工具：git/jsonl/github/slack/jira 连接器。
- 洞察工具：scenarios, KPI snapshot, dataset evaluation, benchmark gate, research scoring.
- 策略/运维工具：strategy sections, doctor, runbook, release check, security audit.
## 项目结构
```text
src/decisiongraph/
api.py FastAPI 应用组装
service.py 核心编排逻辑
store.py JSON 存储，带锁定和原子写入
integrations.py 连接器（git, GitHub, Slack, Jira, JSONL）
mcp_server.py MCP 服务器启动
cli.py Typer CLI 入口
api_routes/ API 路由
cli_commands/ CLI 命令组
mcp_toolsets/ MCP 工具组
tests/ 后端测试套件
tools/ CI 基准测试数据集和帮助工件
docs/ 前端文档应用（Vite + React）
assets/ README 视觉资产
```
## 质量和验证
本地质量命令：
```bash
python -m pytest -q
decisiongraph benchmark-check --dataset tools/ci_eval.jsonl --seed-demo --min-top1 0.65 --min-keyword-coverage 0.65
cd docs && npm run lint && npm run build
```
最新本地验证（2026-04-25）：
- 后端测试：通过（`59 passed`）
- 基准测试门控（`tools/ci_eval.jsonl`）：通过
- 前端 lint：通过
- 前端构建：通过
CI 流水线：
- [`.github/workflows/ci.yml`](./.github/workflows/ci.yml)
- 后端矩阵测试 + 基准测试门控 `tools/ci_eval.jsonl`
发布说明：
- [`CHANGELOG.md`](./CHANGELOG.md)
## 贡献者须知
- 为 API 和 CLI 合同保持向后兼容性。
- 为任何行为更改添加测试。
- 优先使用证据链接的决策条目，而不是自由格式笔记。
## 快速维语摘要
DecisionGraph 是用于快速回答“为什么代码是这样的”的工程决策记忆系统。
您可以从 Git/GitHub/Slack/Jira/JSONL 中摄入，查询语义，运行防护措施，然后通过 CLI + API + MCP 公开相同的逻辑。
连接信息
猜你喜欢
暂无推荐服务器