内容
代理看板
[](README.md)
[](README.ru.md)
> **英文** · [俄语](README.ru.md)
[](LICENSE)
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
一个基于人工智能的看板，代理（如 Codex、Hermes 等）通过模型上下文协议拉取任务。看板是被动的 — 它不会启动或控制代理。你通过 MCP 配置将代理指向看板，它们通过 `get_next_task` / `claim_task` 自助拉取任务。
## 为什么？
大多数代理编排器 **推送** 工作：调度器决定谁做什么是并发送它。代理看板则相反 — 看板是一个被动的 **MCP 服务器**。代理发现并认领工作时准备好了，就像开发人员从真正的看板中挑选任务一样。这将“需要做的事情”（看板）与“谁做以及何时做”（代理）解耦，并且适用于任何支持 MCP 的代理 — 无需为每个代理编写适配代码。
## 功能
- **基于拉取的 MCP** — 看板通过流式 HTTP 传输暴露 11 种工具（`get_next_task`、`claim_task`、`post_progress`、`request_review` 等）
- **硬分配** — 为特定代理预留任务；其他代理看不到它
- **实时进度订阅** — 代理流式传输差异、文本、工件、错误；您可以评论，代理在下一次读取您的反馈
- **双语界面** — 中文 / 英文，单击切换语言
- **审查差异** — 看板收集 diff base...branch` 并request_review` 时内（Shiki 语法）
- **设计系统** — 暗色优先，单琥珀色强调的 UI，基于令牌构建
- **自托管** — FastAPI + PostgreSQL + React；作为 Docker 镜像提供
## 截图
<table>
<tr>
<td width="50%" align="center"><b>看板（暗色）</b></td>
<td width="50%" align="center"><b>卡片详情</b></td>
</tr>
<tr>
<td><img src="docs/screenshots/board.png" alt="看板视图"></td>
<td><img src="docs/screenshots/card-detail.png" alt="卡片详情"></td>
</tr>
<tr>
<td align="center" colspan="2"><b>首次运行设置</b></td>
</tr>
<tr>
<td align="center" colspan="2"><img src="docs/screenshots/login.png" alt="登录 / 设置屏幕" width="50%"></td>
</tr>
</table>
## 架构
详见 `docs/superpowers/specs/2026-07-05-agent-kanban-design.md`。第一阶段 MVP 范围已在 `docs/superpowers/plans/2026-07-06-agent-kanban-phase1-mvp.md` 中记录。
## 快速入门（本地开发）
### 前置条件
- Python 3.11+
- `uv`（安装：`curl -LsSf https://astral.sh/uv/install.sh | sh`）
- Node.js 20+ 和 `pnpm`
- PostgreSQL 16+ 在本地运行
### 1. 数据库
```bash
createdb kanban # 或使用 docker：参见 docker-compose.yml
cp .env.example .env # DATABASE_URL 默认端口 5436（与 docker-compose ak-pg 匹配）
uv run kanban migrate
```
### 2. 后端
```bash
uv sync --extra dev
uv run kanban serve
```
### 3. 前端（独立终端）
```bash
cd web
pnpm install
pnpm dev # http://localhost:5173，代理到 :7331
```
### 4. 将代理指向看板
在代理的 MCP 配置中添加：
**Codex** (`~/.codex/config.toml`)：
```toml
[mcp_servers.kanban]
url = "http://localhost:7331/mcp"
```
**Hermes** (`~/.hermes/config.yaml`)：
mcp_servers:
ban:
url:localhost:7331/mcp
```
然后指示代理：“通过 `get_next_task` 检查看板任务。”
## 代理工作流
1. 在界面中创建任务。它以 `todo` 状态开始。
2. 将其拖到 `READY` 列。现在它对代理通过 `get_next_task` 可见。
3. 指示代理（例如 Codex、Hermes）检查看板：
- 调用 `get_next_task` 以发现工作。
- 调用 `claim_task` 以认领任务。
- 调用 `post_progress` 以报告正在执行的操作。
- 调用 `request_review` 以请求审查，或 `complete_task` 以完成任务。
4. 在卡片详情视图中实时观察进度事件流入。
5. 添加评论以给出后续指示；代理通过 `get_comments` 读取它们。
代理必须将它们的标识符作为 `agent` 参数传递异工具（`claim_task`、`post_progress`、`complete_task`、`request_review`_comment`、`post_artifact`、`set_task_branch`、`set_task_pr`）。看板通过检查 `claimed_by == agent` 来授权变异。
## 编码任务（git / PR）
对于涉及 git 仓库的任务，在创建任务时设置 `repo_path` 和 `base_branch`。看板 **不** 创建分支或 PR — 您的代理使用其自己的 git 工具执行此操作。看板记录代理报告的内容并渲染审查差异。
代理编码任务的工作流：
1. `claim_task` — 接收 `repo_path` 和（如果设置）`base_branch`。
2. 在 `repo_path` 中使用代理的 git 工具创建分支。
3. `set_task_branch(task_id, agent, branch)` — 记录它，以便界面显示它并且可以收集差异。
4. 在该分支上提交工作。
5. `(task_id, agent, summary)` — 看板运行 `git -C <repo_path> diff <base>...<branch>` 一次并将结果存储为可在卡片进度订阅中查看的差异事件。
6. 使用代理的 GitHub 工具打开 PR，然后 `set_task_pr(task_id, agent, pr_url, "open")`。
7. 当合并时，`set_task_pr(task_id, agent, pr_url, "merged")` 然后 `complete_task如果 `repo_path`、`base_branch`（或项目的 `default_branch`）或 `branch` 丢失，则静默跳过差异收集。如果 `git diff` 失败，则记录错误事件，但审查请求本身仍成功。
## 身份验证
看板需要身份验证。两种主体：
- **用户**（人类）：通过网络界面使用用户名 + 密码登录。会话是签名 cookie。
- **令牌**（代理）：不透明的 bearer 令管理面板中管理。每个令牌都绑定到一个 `agent_name`。
### 首次运行
在数据库为空时首次启动，看板会显示设置屏幕：选择管理员用户名 + 密码（8+ 字符）并提交。或者，设置 `AGENT_KANBAN_BOOTSTRAP_ADMIN_PASSWORD` 以无界面方式创建管理员（用于自动化）。设置完成后，登录并进入管理 → 令代理铸造令牌。
### 将代理指向看板
bearer 令牌进行身份验证。在代理的 MCP 配置中：
**Codex** (`~/.codex/config.toml`)：
```toml
[mcp_servers.kanban]
url = "http://your-host:7331/mcp"
# Codex 在较新版本中从配置中读取标头；否则通过 env 设置身份验证。
headers = { Authorization = "Bearer <your-token>" }
```
**Hermes** (`~/.hermes/config.yaml`)：
```yaml
mcp_servers:
kanban:
url: http://your-host:7331/mcp
headers:
Authorization: Bearer <your-token>
```
的 `agent_name必须与传递给工具的 `agent`。使用 `agent_name=codex` 铸造的令牌可以调用 `claim_task(agent="codex")不能调用 `claim_taskhermes")`。
### 生产环境变量
- `SESSION_SECRET` — 会 的签名密钥。中必填；设置一个长随机字符串。
- `PUBLIC_URL` — 公共基准 URL（例如 `https://kanban.example.com`）。控制 cookie 的 `Secure` 标志。
- `AGENT_KANBAN_BOOTSTRAP_ADMIN_PASSWORD` — 首次运行管理员密码（可选；如果未设置，界面设置屏幕会创建第一个管理员）。
## Docker
```bash
docker compose up -d
```
在内部容器中运行应用程序（不暴露给主机）。应用程序通过 compose 网络连接到它作为 `postgres:5432`。有关针对主机可见的 Postgres 进行本地开发，请参见上面的“数据库”中的独立容器说明（端口 5436）。
## 贡献
欢迎贡献。设计规范和分阶段实施计划位于 `docs/superpowers/` 下 — 它们是架构和意图的良好映射。
```bash
# 克隆后：
uv sync --extra dev # 后端依赖 + 测试工具
cd web && pnpm install # 前端依赖
uv run pytest -q # 112+ 测试
cd web && pnpm build # 类型检查 + 打包
```
请为非琐碎的更改首先打开一个问题，以便我们统一范围。
## 鸣谢
界面建立在受 [Sergey Dmitriev 的品牌手册](https://brandbook.graywrk.ru) 启发的设计系统上 — 琥珀色作为唯一的 UI 强调
