内容
# Flanner
[](https://pypi.org/project/flanner/)
[](https://pypi.org/project/flanner/)
[](https://github.com/jaysonmulwa/flanner/actions/workflows/ci.yml)
[](LICENSE)
<!-- mcp-name: io.github.jaysonmulwa/flanner -->
AI 编程代理的计划文件管理器，通过 MCP（模型上下文协议）与 Claude Code 和其他助手连接。
<div align="center">
<img src="docs/assets/demo.gif" alt="flanner: 版本化的计划文件链接到 Linear 问题，在 Web 控制台中" width="840">
</div>
## 为什么
AI 代理不断编写 Markdown 文件：设计文档、迁移计划、架构笔记。这些文件很快就会堆积，散落在您的仓库中，悄悄地过期，很容易被意外提交。Flanner 为这些文件提供了一个统一的存储位置，自动版本控制，并防止它们被提交到 Git 中，直到您决定这样做，提供可浏览的阅读视图和审计跟踪。
## 还不 convinced？为什么
这些计划文件在两个方向上堆积：散落在本地项目中，散落在项目管理工具的开放问题中。Flanner 是两者的汇集点，让您在磁盘上保持组织，并链接到每个计划所属的问题。
目前，Flanner 是本地优先的；目标是云托管计划：共享工作空间，以便于协作，提供实际上无限的存储和历史记录，以及与团队已经使用的工具（如产品跟踪器、聊天和 Notion 等第二大脑）的干净链接。
## 功能
- **MCP 集成**：向 Claude Code 和 Codex 公开计划文件工具。
- **自动头部和版本控制**：每个计划都有 YAML 前置信息，每个修订版都是一个新版本，拥有完整的历史记录。
- **Git 保护**：计划存放在 `.plans/` 中，自动保持在提交之外。
- **代理集成**：`flanner init` 配置 CLAUDE.md、AGENTS.md 和防护钩子，以便代理通过 Flanner 保存计划，而不是散布原始 Markdown 文件。
- **问题跟踪器链接**：将计划与 Linear（或 JIRA）问题绑定；使用 `LINEAR_API_KEY`，Flanner 验证问题并显示其实时状态，在 CLI 和控制台中。
- **阅读视图**：一个浏览器控制台，用于阅读、编辑和查看计划的历史记录（浅色和深色，完全离线）。
- **每个项目的配置**：按仓库自定义计划目录。
## 快速开始
```bash
pip install flanner
cd your-project # 一个 Git 仓库，计划文件应存放在这里
flanner init # 设置数据库、MCP 注册和项目
```
然后要求您的代理使用计划：
> “为 auth 服务创建架构计划”
>
> “显示架构计划的历史记录”
并打开控制台浏览器：
```bash
flanner web --open-browser # http://localhost:8080
```
`flanner init` 可以安全地重新运行。它检测您的 Git 根目录，创建 `.plans/`，更新 `.gitignore`，在 Claude Code 上注册 MCP 服务器，并安装代理集成。
## CLI 命令
```bash
flanner init [--project-root PATH] [--plan-dir DIR] # 设置项目
flanner status # 项目、计划文件、数据库路径
flanner list [--project NAME] [--output json] # 列出项目或项目的计划
flanner sync [--project NAME] [--dry-run] # 导入现有的 .plans/ 文件
flanner config NAME [--plan-dir DIR] [...] # 更改项目设置
flanner web [--port 8080] [--host 127.0.0.1] [--open-browser]
flanner register [--force] / flanner unregister # 与 Claude Code 的 MCP 注册
flanner claude-info # 集成状态
```
<details>
<summary><b>计划文件格式</b></summary>
每个受管理的计划都带有 YAML 前置信息，由工具生成，绝不手动编写：
```markdown
---
mcp_plan_file: true
project_id: 3d816ecd-489a-4fa0-abe2-15ec93f60d5a
plan_file_id: 59c34f9c-8471-47fc-97f2-8dcfefa15434
plan_name: architecture
version: 2
created_by: claude
---
# 架构计划
您的计划内容在这里...
```
</details>
<details>
<summary><b>Web 界面</b></summary>
服务器渲染的控制台，无需构建步骤，离线支持：
- 控制台（/`）：项目、统计数据和最近的活动
- 项目详情（`/projects/{id}`）：项目的计划，分页
- 计划查看器（`/plans/{id}`）：渲染的 Markdown，版本选择器，前置信息
- 编辑器（`/plans/{id}/edit`）和版本历史（`/plans/{id}/history`）
Web UI 绑定到 `127.0.0.1`，无身份验证。不要将其暴露到 localhost 以外。
</details>
<details>
<summary><b>数据存储位置</b></summary>
- 目录（SQLite）：`~/.flanner/data.db`，可通过 `FLANNER_HOME` 或 `FLANNER_DB_PATH` 覆盖
- 计划文件：`.plans/` 在您的仓库中，git-ignored，命名为 `name_v1.md`、`name_v2.md` 等
</details>
<details>
<summary><b>问题跟踪器链接（Linear，JIRA）</b></summary>
链接计划文件到问题，以便计划和票据一起跟踪。
```bash
flanner linear auth # 验证 LINEAR_API_KEY，打印 MCP 代码段
flanner linear config PROJECT --workspace acme # linear.app/acme
flanner linear link PLAN --issue ENG-123 [--notes ...] # 将计划链接到问题
flanner linear links [--project PROJECT] # 列出所有链接
flanner linear show PLAN [--project PROJECT] # 一个计划的链接
flanner linear unlink PLAN [--issue ENG-123 | --all]
flanner linear refresh PLAN # 重新拉取标题/状态（需要 API 密钥）
```
设置 `LINEAR_API_KEY` 后，`link` 验证问题存在并缓存其标题和状态，`--attach-url` 将 URL 附加到 Linear 问题，`refresh` 重新拉取实时状态。无密钥时，仅存储 ID，构建 URL。密钥仅从环境中读取，绝不存储在磁盘上。参见 [docs/LINEAR_INTEGRATION.md](docs/LINEAR_INTEGRATION.md)。一个平行的 `flanner jira` 组链接到 JIRA 问题密钥（仅链接）。
</details>
<details>
<summary><b>架构</b></summary>
通过 `tests/test_architecture.py` 强制分层：
- **基础** (`exceptions`、`utils`、`frontmatter`、`git_integration`、`jira_utils`、`linear_utils`) 不导入包中的其他模块；`linear_api` GraphQL 客户端仅添加 `exceptions`
- **数据** (`database`、`storage`) 仅位于基础之上
- **组合根** (`server` 用于 MCP、`web`、`cli`) 连接所有内容，不相互导入（`cli` 除外，它启动两者）
决策记录在 [docs/adr/](docs/adr/) 中，更多指南在 [docs/](docs/) 中。
</details>
## 工作原理
代理调用 `get_plan_config` 以了解计划的存储位置，然后调用 `create_plan_file_tool` 或 `update_plan_file_tool` 以编写计划。Flanner 将文件放在项目的计划目录中，添加头部，并更新版本。文件保留在 `.plans/`（git-ignored）中，因此它们不会意外地提交到 Git 中。
**让代理在轨道上运行。** MCP 工具是“如何”；`flanner init` 还安装了两个层，使代理实际上使用它们。它在 `CLAUDE.md` 和 `AGENTS.md`（Claude Code 和 Codex 每会话读取的指导）中编写了一个托管块，以及一个 `flanner-plan` 技能，以便代理知道通过 Flanner 路由计划文档。在此基础上，`guard-write` PreToolUse 钩子拒绝在计划目录中进行任何原始写入，并将代理指向 `create_plan_file_tool`，因此即使它忽略指导，计划也不能作为非托管 Markdown 落地。钩子失败打开，从不阻止其他地方的写入。
## 路线图
Flanner 今天是本地优先的。计划下一步：
- 云托管计划：PostgreSQL 目录和 S3 支持的存储，实现无限历史记录
- 共享工作空间，用于团队协作
- 计划之间的全文搜索
- 链接到产品跟踪器、聊天和 Notion 等第二大脑
- Web UI 中的实时更新
## 贡献
设置、CI 闸门、基准测试和发布过程在 [CONTRIBUTING.md](CONTRIBUTING.md) 中。
## 许可证
MIT
