内容
# Takomo
[](https://github.com/ChristianKohlberg/Takomo/actions/workflows/ci.yml)
[](LICENSE)
**一个任务跟踪器，您可以自行托管，每个项目中的 AI 代理、编排器和人类都可以通过 HTTP 与其通信** — 实现统一的工作信息来源，而不是局限于单个代码仓库的待办事项列表。
Repo 内置的跟踪器可以在一个仓库中保留一个不错的记录，但跨多个编排器、机器和代码仓库的并行工作需要一个大家都可以访问的权威来源。Takomo 就是这样的权威来源：分层票据、真正的按项目划分的状态机、原子化认领/租约，确保只有一个工作者拥有票据，还有一个只追加的事件日志 — 错误写入日志以便后续的 LLM 参考。
> **没有公共的 Takomo 实例 — 您需要自行运行。** 它是一个独立的 Rust + SQLite 二进制文件；启动它只需点击或使用容器（如下所示）。一旦启动，Claude Code 插件和 `takomo` CLI 就会指向您的主机。
## 1. 托管它
Takomo 是一个您自行运行的服务器。请选择以下选项之一：
**选项 A — 一键部署到 Render：**
[](https://render.com/deploy?repo=https://github.com/ChristianKohlberg/Takomo)
[`render.yaml`](render.yaml) 蓝图规定了一个带有持久磁盘（SQLite 持久性）、TLS 和 `/healthz` 检查的 Web 服务，并为您提供一个 `https://<name>.onrender.com` 的 URL。
**选项 B — Docker（任何地方）：**
```sh
docker build -t takomo .
docker run -d -p 8080:8080 -v takomo-data:/var/data --name takomo takomo
```
在它前面添加 TLS — Takomo 终止纯 HTTP 并拒绝非环回绑定，除非设置了 `TAKOMO_ALLOW_PUBLIC_BIND=1`。
**然后使用 shell 访问服务器（信任根）创建第一个管理员令牌** — Render 上的 `render ssh`，本地的 `docker exec`：
```sh
takomo --db /var/data/takomo.db token create \
--actor human:me --scopes read,write,human,admin --projects '*'
```
它会一次性打印一个 `tk_...` 令牌。下面所有内容都指向 `https://<your-host>/v1` 并附有令牌。本地构建、TLS 和盒外备份：[docs/hosting.md](docs/hosting.md)。
## 2. 从 Claude Code 使用它 — 以及任何 MCP 客户端
Takomo 在二进制文件中托管了一个 **MCP 服务器（/mcp）**，因此任何支持 MCP 的客户端都可以直接连接 — 无需运行本地进程。
**Claude Code（两行）** — 该仓库同时作为插件市场：
/plugin marketplace add ChristianKohlberg/Takomo
/plugin install takomo
这会安装 `takomo` 技能（教导代理使用存储库作为其信息来源）以及远程 MCP 服务器。在启动 Claude Code 之前设置您的主机 + 令牌 — 插件中不包含任何内容：
```sh
export TAKOMO_MCP_URL="https://<your-host>/mcp" # MCP 端点 — 注意 /mcp，而不是 /v1
export TAKOMO_TOKEN="tk_<your read/write token>"
```
> **`/mcp`，不是 `/v1`。** MCP 服务器位于 `https://<your-host>/mcp`，而 CLI 的 `TAKOMO_URL` 指向 REST 基地址 `https://<your-host>/v1`。插件捆绑的 MCP 服务器读取 `${TAKOMO_MCP_URL}`，因此设置它（与 `TAKOMO_URL` 不同）— 否则服务器没有主机可达并且显示为 *failed to connect*。如果您还使用 CLI，请导出两者。
**任何其他 MCP 客户端（Codex、Cursor、…）** — 使用承载令牌将其指向端点，例如通过手动将其添加到 Claude Code：
```sh
claude mcp add --transport http \
--header "Authorization: Bearer tk_<token>" \
takomo https://<your-host>/mcp
```
然后，代理获得原生 `takomo_new / ready / next / start / done / comment / link / dep / roadmap / …` 工具。参见 [plugins/takomo/README.md](plugins/takomo/README.md) 和 [clients/mcp/README.md](clients/mcp/README.md)。
## 3. 从 CLI 使用它
`takomo` 是一个自包含的 `bash` + `curl` + `python3` 脚本 — 适用于人类和没有 MCP 的代理/环境。单行：
```sh
curl -fsSL https://raw.githubusercontent.com/ChristianKohlberg/Takomo/main/clients/cli/install.sh | sh
takomo help
```
安装程序检查 `curl`/`python3` 并将 `takomo`（和一个简短的 `tk` 别名）放在您的 `PATH` 上。参考：[clients/cli/README.md](clients/cli/README.md)。
## 4. 快速入门
**在一个仓库中启动 — 一条命令。** 从任何 git 仓库的根目录开始，使用管理员令牌：
```sh
export TAKOMO_URL="https://<your-host>/v1" # 注意 /v1
export TAKOMO_TOKEN="tk_<admin token>" # 仅用于预配
takomo init # 或：takomo init myproject --workflow simple
```
`takomo init` 创建项目（以仓库命名），应用 `simple` 工作流程，生成一个仅限该项目的 `read,write` 令牌，并写入 `.takomo/config`（`url` + `project`，可以安全提交）和 `.takomo/token`（模式 `600`，自动 gitignore）。之后，`takomo` 通过从当前工作目录向上遍历来自动加载 `.takomo/` — 仓库内不需要环境设置。
**处理队列：**
```sh
takomo whoami # 我是谁：演员、作用域、项目
takomo new "Wire up the frobnicator" # 创建票据（警告可能重复）
takomo ready # 当前可认领的票据
takomo roadmap # 每个 epic 的进度 + 没有 epic 的工作
ID=$(takomo next | awk '{print $2}') # 原子化认领下一个准备好的票据
takomo start "$ID" # -> in_progress（为你记住租赁围栏）
takomo comment "$ID" "opened PR, waiting on CI"
takomo link "$ID" --pr https://github.com/org/repo/pull/42
takomo done "$ID" # -> done（自动释放认领）
```
每次拒绝都会进行教学：非法操作会返回允许的转换和补救措施，并且 `takomo` 会打印它们。永远不要无变化地重试被拒绝的调用。
## 您获得的功能
- **强制状态机。** 每个项目的工作流程具有服务器强制转换；非法操作会返回教学 `409`（当前状态、允许的转换、补救措施）写入 LLM。
- **原子化认领/租赁。** 单调围栏令牌保证只有一个工作者拥有票据；过期租赁会自动将其返回到就绪队列。
- **层次结构 + 依赖关系。** `epic → task/bug/subtask` 树、`blocked_by` 边（反向 + 传递视图）、标签、路线图和自由格式的命名空间 JSON 元数据。
- **只追加事件日志。** 持久的 `?since=<seq>` 游标 + SSE 流 — 审计跟踪和唤醒馈送合一。
- **只读 Web 看板** 在 `/board`，具有作用域、过期的共享链接。可以缩小到一个 epic 或一个票据（包括子任务），并按 epic 分组卡片，因此大型项目仍然可读。
- **询问人类看板。** 当代理需要人类决策（确认、选择、澄清、批准）时，它会调用 `takomo ask` / `takomo_ask`：阻塞问题会停车票并释放租赁（当所有开放问题得到回答时，票据恢复），而咨询问题会记录路由决策而不会更改状态 — 用于 epic 级或战略调用。问题落在专用的电子邮件样式 **`/inbox`** （文件夹导轨、列表、阅读/答案窗格）由专业知识标签路由 — 或看板的快速 **Ask a human** 抽屉，或 API。对于没有 takomo 令牌的外部专家，生成一个 **每个问题的答案链接** — 一个有作用域、过期的、一次性使用的 URL，允许他们仅回答一个问题。人类也可以 **反弹问题以便进一步研究** 然后回答 — 一个清晰的后续线程与询问代理（`takomo_reply`），票据暂停直到他们最终回答。 可选的电子邮件/Slack 推送（除非配置）。参见 [docs/ask-a-human.md](docs/ask-a-human.md)。
- **每个项目的写作约定。** 项目可以携带原本位于客户端提示中的风格：**样式指南** 用于代理编写的文本（票据标题/正文、评论、问题）和 **人类面向语言** 问题属于 — `takomo project style <p> "Two sentences max…"` / `takomo project language <p> German`。两者都在代理写入之前传递给代理，在每个工作循环调用中（`style_hint` / `language_hint`），因此它们适用于每个客户端而不是一个代码仓库。建议性，但不强制执行。从 CLI 或仅限管理员的 `/board` 设置页面编辑。参见 [docs/ask-a-human.md](docs/ask-a-human.md#per-project-conventions-language-and-style)。
- **晋升。** 记录票据的工作已达到某个阶段 — `takomo promote TKM-1 production` / `takomo_promote`。自由格式 `target`（暂存、生产、发布、交付、…），因此它适用于任何工作流程，而不仅仅是软件；只追加历史记录，在看板上显示最新的徽章。参见 [docs/promotions.md](docs/promotions.md)。
- **存档 + 防锁定。** 存档终端票据以使其不可见；JSONL 导出/导入，具有幂等重导入，以及珠子和豆类的导入程序。
- **单个二进制文件。** Rust + SQLite（WAL）；一个进程，零个外部服务。
默认 **`simple`** 工作流程是 beads/beans 的直接替代品：`draft → todo → in_progress → done`，带有 `blocked`/`cancelled` 出口、`todo` 可认领，无需人类批准门槛 — 因此一个人或一队代理可以直接处理队列。更丰富的工作流程（批准门槛、自动登陆）是您上传的数据：[spec/workflow-format.md](spec/workflow-format.md)。
## 认证和安全
承载令牌（`tk_...`），有作用域（`read`/`write`/`human`/`autoland`/`admin`），存储时哈希，一次显示。每个演员一个令牌 — 永不共享。令牌是整个周界：保持它们远离 git（`takomo init` gitignore `.takomo/token`），通过撤销和重新生成来轮换，并狭隘地作用域，以便包含泄漏。共享链接是只读和过期的，但 **未经身份验证** — 将任何链接视为在其生命周期内公开。完整模型：[spec/auth.md](spec/auth.md)。
## 文档
- [docs/ask-a-human.md](docs/ask-a-human.md) — 询问人类看板：提出问题、后续线程、专业知识路由和电子邮件/Slack 通知。
- [docs/promotions.md](docs/promotions.md) — 记录票据的工作已达到某个阶段（暂存/生产/发布/...），与领域无关。
- [docs/hosting.md](docs/hosting.md) — 自主托管深度：本地构建、TLS 和盒外备份（Litestream）。
- [docs/development.md](docs/development.md) — 构建、测试、 linting 和 `backlot`/`handrail` 开发循环。
- [spec/openapi.yaml](spec/openapi.yaml) — 完整的 v1 HTTP API（票据、工作流程、认领/租赁、令牌、事件日志、`/mcp`）。
- [spec/workflow-format.md](spec/workflow-format.md) — 每个项目的状态机格式。
- [spec/auth.md](spec/auth.md) — 令牌、作用域和身份验证模型。
- [clients/cli/README.md](clients/cli/README.md) · [clients/mcp/README.md](clients/mcp/README.md) · [plugins/takomo/README.md](plugins/takomo/README.md) — 客户端界面。
- [docs/design/](docs/design/) — 采用 vs. 构建评估、架构和 DX-gap 注释。
## 许可证
Apache-2.0。参见 [LICENSE](LICENSE)；[NOTICE](NOTICE) 中的属性。
