Subroutine — Agent 原生任务与决策追踪工具

技能简介

Subroutine 是一款专为人类与 AI 编程助手共同协作设计的自托管任务与决策追踪工具。它从底层架构开始就将 AI Agent 视为一等公民——每个 Agent 拥有独立账号，可自主领取工单、记录进展、提交决策。本次扫描到最新版本 0.8.29，支持 Python 3.11~3.14。

核心能力

1. Agent 账号体系：每个 AI Agent 拥有自己的账号，可以接收工单、认领任务、记录决策，而非仅作为人类的工具
2. MCP 服务端：内置 MCP 协议实现，Claude Code 等主流 Agent 可通过 MCP 协议直接操作 Subroutine
3. 自托管 Web UI：运行 subroutine serve 后，本地浏览器打开即可查看所有工单、任务和决策，支持实时刷新
4. 决策追踪与传递：每一个决策都附带产生背景和理由，后续 Agent 无需重复沟通即可获取完整上下文
5. 跨项目工作传递：一个项目中的工作可阻塞另一项目的工作，跨项目决策可绑定所有关联项目
6. 多 Agent 协作：一个 Agent 提交的工作可由另一个 Agent 接手，每条记录保留完整的执行者链条
7. 零学习成本交互：用户无需记忆任何命令，直接对 Agent 说「file that as a bug」即可创建工单
8. 即插即用的 Claude Code 插件：通过 claude plugin install 安装后，新 Claude Code 会话直接继承项目上下文

安装配置

环境要求：Python 3.11~3.14，Linux/macOS

第一步：安装 Subroutine

uv tool install subroutine

第二步：初始化实例

subroutine init

第三步：为 Claude Code 安装插件

claude plugin marketplace add simonholliday/subroutine
claude plugin install subroutine@subroutine

第四步：启动 Web UI（可选）

subroutine serve

使用步骤

第一步：告诉 Claude Code 使用 Subroutine 在新 Claude Code 会话中输入：

we use Subroutine now

第二步：让 Agent 创建任务 直接用自然语言：

file that as a bug

Agent 会自动查找已有项目，创建对应工单，而不是重复询问基本信息。

第三步：让 Agent 领取任务

what can I actually start?

Agent 会查看当前可启动的任务列表，认领后自动更新状态。

第四步：记录决策

what did we decide about retries?

Agent 会搜索历史决策记录并返回结果。

第五步：查看项目看板 打开浏览器访问 Subroutine 提供的本地 URL，实时观察任务流转。

适用场景

1. 多人协作 + Agent 协作的研发团队：人类开发者与多个 Agent 同时参与同一项目，任务状态统一追踪
2. 长周期研究项目：多轮对话中的决策记录永久保存，后续 Agent 可直接查阅，无需人类转述
3. 跨项目依赖管理：一个项目的里程碑决策影响多个子项目的执行方向
4. 需要 AI 自主推进的工作流：设置 /loop 指令让 Agent 定时检查 Subroutine 中的待办并自动推进
5. 团队知识沉淀：每次决策附带完整理由，新成员加入后可快速了解项目历史

适用人群

• AI 优先的研发团队：团队中有多名人类工程师和多个 AI Agent 同时工作，需要统一的任务视图
• 技术负责人：需要追踪多个 Agent 的工作进度，确保决策被正确执行
• 独立开发者：与 AI 协作开发复杂项目，需要让 AI 有记忆能力
• 多 Agent 系统架构师：设计多个 Agent 协作流程，需要每个 Agent 有独立身份和工单系统

工作原理

Subroutine 核心架构由四层组成：

• 数据层（SQLite）：所有工单、任务、决策存储在本地 SQLite 文件，可完全离线访问
• API 层（FastAPI）：提供 /v1/items、/v1/decisions、/v1/meta 等 REST 接口，Agent 通过 HTTP 调用
• MCP 层：作为 MCP 服务端，Claude Code 等 Agent 可通过 MCP 工具协议直接读写工单
• Skill 层：内置 Claude Code Skill，告诉 Agent 如何理解 Subroutine 的数据结构和使用规范

Agent 与 Subroutine 的交互原则是「拒绝即教导」——当 Agent 提交了错误格式的工单时，系统返回具体错误说明（字段名、错误原因、可接受的值），Agent 从错误中学习，无需人类干预。

官方链接

• PyPI 主页：https://pypi.org/project/subroutine/
• GitHub 仓库：https://github.com/simonholliday/subroutine