内容
<img src="docs/assets/redraft-mark.svg" width="80" alt="redraft">
# redraft
AI 辅助项目开发与跟踪：一种用于工程项目的有类型、版本的设计记录，由您的代理驱动，基于 MCP。
<img src="assets/tables_page.png" alt="redraft 的决策表格：接受和拒绝的替代方案并排显示，分为解决问题的类别" width="100%">
* 决策记录，操作员 UI 渲染：每个决策按解决问题分类 - 接受和拒绝的替代方案并排显示，附有理由和权衡。未走的路仍然是记录的一部分。*
## 为什么
大多数项目文档都是以设计书籍的形式编写：线性叙述，一次草拟，很少阅读，在一个冲刺后过时。这不是工程项目实际产生知识的方式。决策、理由、需求和开放性问题作为稀疏的片段出现在项目的不同层次、不同时间，只有当它们与解决的问题、排除的方案和后续的决策联系起来时才变得有用。redraft 将其视为数据的真实形状，而不是抗拒它：有类型的节点和有类型的边，以纯 Markdown 存储，因此 git 成为事实的来源。MCP 服务器为您的代理提供工具，以便在项目演变过程中组织图形；报告按需压缩成审查级别的文件 - 包括未走的路。
## 快速入门
**1. 克隆并安装引擎。**
```bash
git clone https://github.com/KaelinGraf/redraft.git redraft
cd redraft
uv tool install --from . redraft
```
这会在您的 `PATH` 上添加一个命令 `redraft`（如果警告 bin 目录不存在，请运行 `uv tool update-shell`）。如果您正在开发引擎本身，而不是仅仅使用它，请跳过工具安装并运行 `uv sync` - `uv run redraft` 然后解析到您的本地 checkout。
**2. 创建图形。**
```bash
redraft init ~/my-project
```
写入 `graph/nodes/`（空）、`CLAUDE.md`（组织协议，原样）、`.mcp.json` 指向此图形（位置独立 - 它保持有效，即使图形仓库后来克隆到不同的路径或设备），以及默认情况下，其自己的独立 git 历史记录。
`redraft init --help` 列出每个选项（`--no-git`、`--project-name`）。已经有来自其他设备的图形仓库？一个普通的 `git clone` 就足够了 - 参见下面的“引擎和图形是单独的仓库”。
**3. 开始工作。**
```bash
cd ~/my-project
claude
```
`.mcp.json` 告诉 Claude Code 如何为此图形启动 `redraft serve` - 工具（`create_node`、`search_nodes`、`assemble_report` 等）在会话启动后自动出现。
`redraft serve` 需要 uv 管理的 Python 3.12（在 `.python-version` 中固定）：检索堆栈需要带有 FTS5 和扩展加载支持的 `sqlite3` 构建，许多系统/发行版 Python 不具备这些功能 - 如果您的 Python 缺少其中任何一个，它会快速失败并显示清晰的错误，而不是在后面的工具调用中出现令人困惑的错误。
## 在现有项目中注册 redraft
图形不必生活在代码项目中，大多数情况下也不应该如此 - 将其作为兄弟目录创建，然后在 Claude Code 的项目范围内注册，而不是手写 `.mcp.json`:
```bash
claude mcp add --scope project -e REDRAFT_DIR=<abs graph dir> -e PYTHONPATH= --transport stdio redraft -- redraft serve
```
`PYTHONPATH=` 在任何 shell 中都很有用，其中其他东西（ROS 工作区是一个常见的罪魁祸首）已经污染了它 - 继承的条目可能会遮蔽 redraft 的依赖项或自动加载不兼容的插件。
## 操作员 UI
`redraft ui` 在同一个图形上提供一个本地 Web 应用程序：一个大纲优先的三面板视图，用于阅读和完整创作（创建时带有实时重复检测提示、链接、批量链接、重新父节点、合并、上传、快照），以及实时文档渲染、决策表格、依赖感知里程碑时间线和力导向图。
| | |
|---|---|
| <img src="assets/outline_page.png" alt="大纲：脊柱树、节点详细信息和开放问题及未证明决策的注意力条"> *大纲 — 脊柱树、节点详细信息、注意力条* | <img src="assets/docs_page.png" alt="文档视图：图形渲染为设计文档，每个标题都有类型和状态"> *文档 — 图形渲染为设计文档* |
| <img src="assets/timeline.png" alt="时间线：具有依赖箭头的甘特样式里程碑和未调度的托盘"> *时间线 — 具有真实依赖关系的里程碑* | <img src="assets/map.png" alt="地图：整个项目的力导向视图"> *地图 — 整个项目，一个连接的图形* |
向您的助手请求技术报告，它会将图形渲染成审查级别的 LaTeX 文档 - 决策表格、开放性问题等 - 保存在 `reports/` 下，并在“报告”选项卡中显示排版：
<img src="assets/report.png" alt="从图形生成的 LaTeX 技术报告，在‘报告’选项卡中渲染" width="100%">
## 会话启动概述
每个图形 `redraft init` 都会附带一个 Claude Code `SessionStart` 钩子（`.claude/settings.json`）以及 `CLAUDE.md`/.mcp.json。它运行 `redraft overview` - 与 `overview` MCP 工具和 `graph://project/overview` 资源公开的嵌入式免费查询相同 - 并将生成的 Markdown 地图（脊柱根、它们的主要分支和每个分支的开放问题及未证明决策的统计数据）直接注入每个新会话的上下文中，以便第一个真正的调用是有针对性的，而不是盲目猜测。
默认情况下它是开启的，因为这是该功能的重点；要关闭它，请删除图形仓库中的 `.claude/settings.json`（或仅其中的一个 `SessionStart` 条目，如果您已经添加了其他钩子到该文件）。
## 引擎和图形是单独的仓库
此仓库（**引擎**）是 MCP 服务器、存储/索引代码和 CLI。它不包含任何项目数据。项目的 **图形** - 其节点文件、`CLAUDE.md`（组织协议，由 `redraft init` 原样写入）和 `.mcp.json` - 生活在它自己的仓库中，具有它自己的 git 历史记录和它自己的远程，完全独立于引擎版本。
为什么要分开它们：引擎是可替换的工具，可以升级、重新安装或分叉；图形是不可替代的设计记录。耦合它们的生命周期意味着每次引擎更改都可能影响数据，并且每个设备都需要完整的引擎源代码才能读取图形。
## 升级
重新安装较新的引擎不会接触到您已经拥有的图形 - 现有图形的 `CLAUDE.md`（组织协议）和 `.claude/settings.json`（会话启动钩子）曾经在您运行 `redraft init` 时写入，并且即使安装了提供这些文件的新版本的引擎后，它们仍然保持不变。在图形中运行 `redraft sync` 以更新它们：它刷新这两个文件（以及 `.gitignore` 所需的行）以匹配新安装的引擎所提供的版本，如果图形是 git 仓库，则提交刷新，但永远不会触及 `graph/nodes/`、`docs/` 或 `reports/` - 无论如何，您的项目数据都不会被触及。
```bash
uv tool install --reinstall --no-cache --from . redraft
cd ~/my-project
redraft sync
```
在重启 Claude Code 会话后，它会使用更新后的协议和钩子。
## 内容
- **节点类型**：`concept`、`decision`、`rationale`、`requirement`、`constraint`、`idea`、`question`、`artifact`、`observation`、`milestone` - 一个封闭集，每个都有自己的狭窄 `status` 生命周期，其中只有 `decision`、`question` 和 `milestone` 带有 `status`。
- **边语义**：`part_of` 是标量边 - 层次结构主干 - 加上八个类型化的列表边：`justifies`、`supersedes`、`addresses`、`depends_on`、`contradicts`、`references`、`derived_from`、`relates_to`。`docs/protocol/organizing-protocol.md` 是完整的词汇和规则，代理遵循这些规则以正确使用它。
- **混合检索**：FTS5 词汇搜索加上本地句子嵌入向量搜索（fastembed，无网络调用），通过互惠排名融合。
- **完整性检查**：悬空边、标题冲突、孤立节点、无记录理由的决策 - 与派生的 SQLite 索引进行检查，该索引完全可从文本文件中重建，并且永远不是第二个事实来源。
- **带有决策表格的报告**：`assemble_report` 遍历 `part_of` 子树，并将每个决策（任何状态）分组到它所解决的问题或需求下，并带有理由、权衡和超序列链 - 接受和拒绝的替代方案并排渲染，这样未走的路成为记录的一部分，而不是丢失。
- **版本控制是本地 git 提交**：每个图形写入批次都以快照结束 - 图形仓库自己的 git 历史记录中的路径范围提交。本地提交 *是* 版本历史记录（可区分、可恢复、按节点可归责）；添加远程并推送是可选的，完全由您决定。
- **内置报告生成**：每个图形都附带的组织协议教导驱动助手将图形压缩成技术写作 - `assemble_report` 用于完整的脊柱和决策表格，`briefing(query)` 用于主题上下文 - 保存为 LaTeX 并在 `reports/` 下渲染，在操作员 UI 中排版。`redraft-report` 技能将流程打包成一句话，即“生成技术报告”。
- **保存的参考资料**：`docs/` 是引用的研究的本地、gitignored 缓存 - 可从 `artifact` 节点的记录的 `source_url` 通过 `redraft-fetch-docs` 技能重新获取 - 不进行版本控制，因此它不会随图形一起旅行，并保持仓库精简。`graph/attachments/` 保留通过操作员 UI 上传到特定节点的 文件 - 是图形的提交选项。
## Obsidian 兼容性
图形是带有 YAML 前置元数据和 `[[wikilink]]` 样式边的纯 Markdown - 在 Obsidian 中直接打开图形仓库，它会原生渲染和导航。redraft 只需组织图形，而不读取它。
## Claude Code 技能
`skills/redraft-init/SKILL.md` 引导 Claude Code 创建项目的图形并注册它，因此您可以直接询问而不是手动遵循快速入门。将它链接或复制到 `~/.claude/skills/`：
```bash
ln -s "$(pwd)/skills/redraft-init" ~/.claude/skills/redraft-init
```
`skills/redraft-fetch-docs/SKILL.md` 从每个工件节点的记录的 `source_url` 重新获取图形的本地 `docs/` 缓存（参见上文）；以相同的方式链接它 (`ln -s "$(pwd)/skills/redraft-fetch-docs" ~/.claude/skills/redraft-fetch-docs`)。
`skills/redraft-report/SKILL.md` 打包报告流程：组装图形，在 `reports/` 中写入基于 LaTeX 的技术报告，快照它 - 因此在任何连接的 redraft 图形的会话中，“生成技术报告”是一句命令 (`ln -s "$(pwd)/skills/redraft-report" ~/.claude/skills/redraft-report`)。
## 运行测试
```bash
env -u PYTHONPATH uv run pytest -q
```
## 许可证
Apache-2.0。参见 `LICENSE`。
