其他语言: English, Español, Português, 日本語, Deutsch, Français, 한국어, Italiano, हिन्दी · 全部中文指南
声明:Carbon Forge 由我们 100monkeys.ai 开发,因此请把这篇指南当作开发方的说明来读。它由我们的一个 AI 智能体根据公开文档(英文)起草,主要是 MCP token scopes (R#62460)、MCP tokens (R#61824) 和 Tokens catalog page (R#62188),并经公司审阅;这个简体中文版是英文原版指南的译文。预设名称、参数和引文都是文档自己的,引文保留英文原文,译文附在旁边;文档没有给出完整的生成调用示例,所以这里展示参数列表而不是示例。文档没有回答的问题,最后一节会说明。
每个 token 上的两道限制
token 带有一个角色上限(viewer、editor 或 admin)和一个工具范围,即 "the explicit set of MCP tools the bearer is allowed to call."(持有者被允许调用的 MCP 工具的明确集合。)角色上限是权限的上界;范围在此基础上再收窄。文档的例子:admin token 上的 SCM reader 范围,与 viewer token 上的同一范围,返回相同的工具目录。
确定智能体必须做什么
打开表单之前,先用一行写下智能体的工作:检索和推理、记笔记、读代码、在 lane 上构建,或者发布。每一种都对应下面的一个预设。文档的规则:"Default to the narrowest preset that still covers what the client needs."(默认选择仍能覆盖客户端需要的最窄预设。)
设置角色上限
打开设置,选择 API tokens,然后选择工作区和角色上限。SCM 预设写明了与之搭配的角色:SCM reader 配 viewer,SCM agent 和 SCM release 配 editor。
选择最窄的预设
各预设及文档给出的工具数量(每个都包含 cortex.ground):
- Read-only memory(
read_only_memory,14):读取页面和 atom、搜索、跟随交叉链接;不能写入。 - Basic LLM memory(
basic_memory,30):读写页面、atom 和标签,以及搜索。 - Knowledge-graph reader(
knowledge_graph_reader,31):所有内容面和图谱,不能写入。 - SCM reader(
scm_reader,58):代码树、lane、changeset、cut 和文件树,加上页面和搜索;不能写入。 - SCM agent(
scm_agent,104):SCM 读取,加上写页面、atom、lane 和树,落地 lane,切出 cut 和渲染。 - SCM release(
scm_release,67):SCM 读取,加上落地和批准 lane、切出 cut、推送归档和发布站点。 - Full access(
full,177):所有工具,在角色上限之内。
在 lane 上构建的编码智能体用 SCM agent;负责批准的审阅者用 SCM release;研究型智能体用一个 reader。文档把 Full access 留给 "trusted with anything the role can do"(在该角色能做的任何事上都被信任)的客户端。
用 Custom 多加一个工具
当某个预设差一个工具时,选择 Custom,在分组的选择器中挑选工具。文档的例子是一个 "that should be able to create comments but not pages"(应能创建评论但不能创建页面)的发布智能体。范围在工具列表、/api/mcp/manifest 上的清单以及每次调用上强制执行。范围之外的工具回答 Unknown tool: <name>,"exactly as a tool that does not exist"(和不存在的工具完全一样),所以客户端无法得知它的 token 缺少什么。
生成 token 并保存密钥
用持有它的智能体或环境给 token 命名,然后复制密钥:"it is shown once, then only the prefix."(它只显示一次,之后只显示前缀。)每个 token 保留自己的当前工作区,所以两个智能体用两个 token 时不会移动彼此的指针。
只为编排器允许执行 token
执行 token 是 "a short-lived child of one of your tokens, minted for a single AEGIS run"(你的某个 token 的短期子 token,为一次 AEGIS 运行而生成),这里的 AEGIS by 100monkeys.ai, in beta,是运行智能体的编排器。只有当 token 的所有者在 token 表单中勾选 May mint execution tokens(可生成执行 token)时,它才能生成子 token。默认关闭,没有任何预设会打开它,文档说 "leave it off unless an orchestrator holds the token."(除非 token 由编排器持有,否则保持关闭。)生成工具只在 full 预设中。
为一次运行生成子 token
父 token 用这些参数调用 tokens.mint_execution:
execution_id, instance_id, workspace_id, tree_path, lane_label, tools, role_cap, lifetime_seconds, workflow一个实例、一个工作区、一个树路径、一个 lane 标签、父 token 持有的 1 到 166 个工具、等于父 token 或 viewer 的角色上限,以及最多 86,400 秒且永不超过父 token 到期时间的有效期。workflow 可选:运行所执行的落地规则关卡的名称。回答:
{ token_id, parent_token_id, execution_id, instance_id, workspace_id, tree_path, lane_label, workflow, role_cap, tools, expires_at, secret }任何扩大权限的请求都会用一句话拒绝,并且什么都不生成。子 token 的每次写入都必须写明它的 lane 并留在它的路径之下;文档针对 lane forge/run-1 和路径 apps/web 的拒绝信息:
This execution token writes only to lane "forge/run-1", not to the trunk.
This execution token writes only under "apps/web", not to "apps/api/x.ts".子 token 从来不是第二个身份:它做的每个改动都把你记录为执行者,并记录它为之生成的那次运行。
撤销,并查看审计日志
子 token 自己撤销,或由父 token 用 tokens.revoke_execution 撤销;它在执行撤销的服务器上立即停止认证,30 秒内在所有地方停止。撤销父 token 或改变其范围,会撤销所有子 token。每次工具调用都以 token 身份记入审计日志,每次生成和撤销都会写一行审计记录,写明父 token、子 token 和运行。
要让一次运行的批准在受保护的主干上生效,请读我们的指南落地规则:把代码所有者规则保存在记录里,并用 AEGIS 工作流作为门控。
文档没有回答的问题
- 完整示例。目录列出了生成的参数和回答,但没有示例调用。
- 工具上限。子 token 可取 1 到 166 个工具,而
full预设有 177 个;哪些工具不能传给子 token 没有列出。 - 编排器如何拿到父 token。文档说只在编排器持有 token 时才允许生成,但没有说如何把这个 token 交给 AEGIS。
- 预设列表在哪里。给出了数量;每个预设的工具名只在表单的选择器里。