用 Arketum 给 Agent 的每一步装上人类闸门：单工具 MCP、PRD 审批与带版本需求的收口实操

安装只要求 Node.js 20 及以上。最完整的是 Claude Code 插件路线：它一次性带来服务本体、会话启动时的本地面板、一个技能与三条命令。想给任意 MCP 客户端装，可以用一行命令，加上 -g 让它在每个项目里都可用。愿意手工配的，本质就是在客户端里注册一条 stdio 命令。

Claude Code 插件（带服务、本地面板、技能与三条命令）
/plugin marketplace add rlabs-cl/claude-plugins
/plugin install arketum@rlabs

任意 MCP 客户端，一行装（-g 表示每个项目都可用）
npx add-mcp @rlabs-cl/arketum -g

手工注册为 stdio MCP 服务
claude mcp add --scope user arketum -- npx -y @rlabs-cl/arketum

等价的通用配置
{ "mcpServers": { "arketum": { "command": "npx", "args": ["-y", "@rlabs-cl/arketum"] } } }

它也挂在官方 MCP 注册表上，名字是 cl.rlabs/arketum。全局安装之后，arketum 这个可执行文件就是同一个服务；另外两个入口后面会用到：arketum ci 在 CI 里重跑各单元记录下来的证据，arketum panel 启动本地状态面板，每台机器一个，监听 127.0.0.1。如果你的客户端无法向人展示表单（也就是不支持诱导式提问），设 ARKETUM_GATES=chat，Agent 就会改为在对话里逐条问你闸门决策。

它不挑起点：可以在空目录里从零开始，也可以接进一个已经有代码的项目，还可以从一个只有文档的目录起步。开局的调用不会要求你先写一堆配置，而是直接返回两样东西——一份最小的 .arketum/project.yaml，以及当前应该打开的那个工作单元。这个设计的好处是：你不需要先理解全部概念才能开始，Agent 会在每一步告诉你下一步。

项目里它记住的一切
位置：项目根目录下的 .arketum 目录，纯文本

开局的调用返回：
1) 最小的 .arketum/project.yaml
2) 当前应当打开的工作单元

格式变更在 CHANGELOG.md；旧格式的存储仍可读取
迁移动作：action: update_store

语言这件事要在项目启动时就定下来：Arketum 说西班牙语或英语，每个项目在开始时选定一种，之后这个项目里 Agent 和人看到的一切——指引、闸门、表单、批处理文件与面板——都用那一种语言。动作名是英文，西班牙语名作为别名同样被接受；安装过程本身始终是英文。团队选哪种，取决于你们希望评审材料落在哪种语言上。

工作单元是它的基本单位，开单元时要先选一条通道：新项目、新特性、小修、纠错、部署等等。通道决定了这一趟要走的步骤序列。选完之后，步骤清单会交给人确认——这一步很关键，它把「Agent 打算怎么干」在动手之前就摆到了人面前。

开单元的两件事

1) 选通道（lane）
   新项目 / 新特性 / 小修 / 纠错 / 部署 等
2) 定目标（goal）

通道确定后，人确认这条通道及其步骤
该由人决定的事会问人；流程性步骤可以委派

这里有一条很重要的分工原则值得抄进团队规范：该由人决定的事，它会来问人；而流程性的步骤可以委派给 Agent。也就是说，它不是把每一步都变成一次打断，而是把决策点挑出来。如果你的 Agent 表现出「跳过闸门直接写代码」，那通常意味着它没有被要求在每个步骤调用 build——这条约束要写进你的 Agent 指令里。

需求阶段分成两个角色在跑：一个分析师负责和人对话，把要什么问清楚；一个架构师负责推导技术侧，把该怎么做补齐。两者合起来产出 PRD。然后是关键的一道闸门——人批准「将要被建出来的东西」之后，才进入实施。这就是它和「让 Agent 直接写代码」最不一样的地方：在被建出来之前，你会先看到一份要建什么的说明，而且你有批准与否的权力。

需求阶段的两个角色

analyst    与人对话，把需求问清楚
architect  推导技术侧，把实现路径补齐

产出：PRD
闸门：人批准「将要被建出来的东西」之后才进入实施

客户端不支持表单时：设 ARKETUM_GATES=chat
Agent 会在对话里逐条询问闸门决策

它承诺的四件事在这一阶段就开始生效：建出来的东西回应的是被问出来的需求；人在它被建出之前就确认了将要做什么；每个工件都从一般到具体逐层下沉，每一层都检查覆盖度、理由、粒度与是否贴合它的原型，并且忠实于文件树；项目里的每个文件要么被某个原型认领，要么被显式声明为脚手架，任何改动都不逃出所在单元声明的范围。需求带版本与状态，每个改动都挂在某一条需求上。

进入实施之后，每一个被改动的工件都要沿着它的阶梯一级一级往下沉，而不是一次性写到底。执行过程中产生的证据会链回它所满足的需求。于是到了收尾的时候，你能回答两个问题：这个文件为什么长这样，以及它对应哪条需求的哪个版本。

实施阶段的三条约束

1) 每个被碰到的工件沿阶梯逐层下沉
2) 执行证据链回它满足的需求
3) 改动不逃出所在单元声明的范围

需求带版本与状态，每个改动挂在其中一条上
项目里每个文件要么被原型认领，要么被声明为脚手架

这套约束在实践中最大的价值是让「跑偏」变可见：Agent 想改一个没有被任何原型认领的文件时，它会被要求说明这个文件是什么；改动越出单元声明的范围时，同样会被挡住。代价是节奏变慢，所以通道的选择很重要——小修与纠错这类通道的步骤序列明显比新项目短，别把所有工作都开成新项目。

收口阶段它会把每一次下沉对照当前的原型与文件树重新检查一遍，并核对收尾条件。这之后还有两个工程化入口：全局安装后的 arketum ci 会在 CI 里重跑各单元记录下来的证据，让流程约束不只是本地约定；arketum panel 启动每机一个的本地状态面板，监听 127.0.0.1，用来看当前有哪些待决事项。

收口与工程化入口

arketum ci ...     在 CI 里重跑各单元记录下来的证据
arketum panel ...  启动本地状态面板（每机一个，127.0.0.1）
action: update_store   迁移旧格式的存储

遥测（仅在被接受时才发生）
arketum telemetry          打印将要发送的内容
arketum telemetry --accept / --no
arketum telemetry --test   发一条测试事件并告知是否到达
ARKETUM_TELEMETRIA=0       本机强制关闭

遥测这一段值得单独看一眼，因为它默认是「先问你」的：初次使用时会用一个是否表单征求同意，或者由 Agent 在对话里问；在答复之前，这个问题会一直挂在你的待决事项里（批处理、面板与状态中都能看到），不答复或答复否，就不会统计也不会发送。答复之后不再重复询问。发送的内容是匿名汇总，最多每天一次，包含版本、安装方式、操作系统家族、客户端声明的名字、使用天数与项目数，以及每个项目（只用不可逆哈希标识）的通道分布、闸门等待时长与开放关闭的主题数；不含任何文本、路径、名称或代码。此外它每天会用一次普通的 GET 去 npm 查新版本，只告诉 Agent 有没有新版与怎么升级，从不自动安装，同样可以用那个环境变量关掉。