create-railcode-agent

创建 Railcode Agent

先更新

在回答 Railcode Agent 或 CLI 问题，或运行 railcode 命令之前，请先更新已安装的 Railcode skills 和 CLI，然后确认 npm 上发布的版本：

npx skills add Railcode-HQ/railcode-skills
npm install -g railcode@latest
railcode --version
npm view railcode version

如果 skill 有变更，请从头重新阅读此文件。如果无法访问 npm，请说明无法验证最新版本，不要声称本指南是最新的。本版本已根据已发布的 Railcode CLI 0.1.28 核对。Agent 输入采用自由格式；其契约由 system 提示词定义。后端会验证清单中的工具和限制，因此保存时的验证结果优先于此快照。

自 0.1.28 起，CLI 会在其主版本内自动更新，但仅限交互式终端；Agent 驱动的会话是非交互式的，因此请继续显式运行上面的 npm install -g railcode@latest，不要想当然地认为自己使用的是最新版本。

提交 Railcode 反馈

完成有实质意义的 Railcode 工作后，如果有具体的产品反馈（例如 bug、使用阻碍、建议，或特别好用的地方），请使用隐藏的 railcode agent-feedback 命令。每个不同的问题提交一次。请描述任务、预期行为和实际行为，以及任何变通方法；报告应简洁，并省略凭据、客户隐私数据、源文件和对话记录。

railcode agent-feedback --message "Deploy failed with an unclear error; expected the missing field to be named." \
  --category friction --command "deploy" --context "Static app deploy; corrected the manifest to unblock."

对于已准备好的报告，请使用 --file <path>；也可以通过 stdin 输入文本，而不使用 --message。消息上限为 10,000 个字符；--context 为可选参数，上限为 5,000 个字符。类别包括：bug、friction、suggestion、praise、other（默认值）。如果知道，可以使用 --agent（例如 Codex 或 Claude Code）自行报告助手/工具名称，并使用 --model 报告所用模型。这些信息是你自行提供的，可能不准确；不知道时请省略，不要猜测。以上字段以及 --command 的长度均不得超过 200 个字符。

CLI 会附加其版本、操作系统平台、CPU 架构和 Node 版本。后端会在 PostHog 中将报告关联到已登录用户及其组织。必须已有登录状态；在应用目录之外也可以使用。Feedback accepted. 表示已尽力接受，并不代表已确认存储。如果报告失败，请继续原任务，不要反复重试，也不要仅为提交反馈而登录。

此命令不会显示在 CLI 帮助中，且要求使用 CLI 0.3.3 或更高版本。本反馈指南已根据 CLI 0.3.3 源码核实。较旧版本的 CLI 可能会返回 Unknown command；此时请视为该命令不可用。

将请求映射到 Railcode

在编写清单前，请先使用此表。如果请求提到了外部产品或数据源，在判断有哪些可用资源之前，务必检查数据连接/已保存查询以及连接器（共享的，或由某人关联并拥有的）；详细的发现命令见范围界定步骤。

硬性文件边界：只要 AI 需要读取、理解、提取、总结、转换或生成文件，就必须使用带有 tools.app_files 和沙箱的托管 Agent。配套应用可以上传、存储、列出、下载和显示文件，但绝不能让其页面内的 llm.generate() / llm.stream() 消费文件内容、文件 URL 或从文件派生的载荷，也不能用它生成文件制品作为替代方案。请通过 tools.app_data_write 发布持久化结果。

用户需求	使用此 Railcode 功能
“从我们的数据库分析公司指标／订单／客户”	tools.saved_queries（默认）；只有明确要求直接编写 SQL 时才使用 tools.adhoc_sql
“使用团队共享的 Stripe、CRM 或其他 SaaS 账户”	使用 tools.connectors 和 tools.docs；由组织管理的连接器持有凭据
“使用我个人连接的 Gmail、Slack 或其他账户”	使用同一个 tools.connectors，并指定由该人员关联且拥有的行（railcode connector link gmail → gmail-jp）。Agent 的创建者必须持有该连接器（作为所有者，或由他人共享给他们）；凭据属于该行，因此组织 Agent 和 cron 也能使用
“将我的账户连接到 Railcode 未捆绑的产品”	railcode connector add-mcp <name> <https-url> — 将远程 MCP 服务作为由该人员拥有的连接器，然后像其他行一样在 tools.connectors 下指定它
“每个人都应以自己的身份操作（查看自己的会议、收件箱）”	不要使用 Agent。 按用户配置的连接器使用调用者的账户运行，而 Agent 没有调用者：清单会被拒绝。请构建 Railcode 应用（$create-railcode-app）——或者指定由某个人拥有的连接器，并接受 Agent 会以该人员的身份操作
“读取人们在 Railcode 应用中管理的记录”	使用 tools.app_data，通常还需要配套应用
“用 AI 读取、提取、总结、转换或生成文件”	使用带有 tools.app_files 和沙箱的托管 Agent；切勿使用配套应用的 llm
“编辑此 Word 文档／DOCX，并将其保留为文件”	托管 Agent + 配套应用：应用存储和管理源文件及输出文件；声明 tools.app_files 以加载 DOCX，并声明 tools.app_data_write 以发布编辑后的文档
“创建或修改 PowerPoint／PPTX 演示文稿”	托管 Agent + 配套应用：应用管理模板、输入文件和生成的演示文稿；使用沙箱创建／编辑 PPTX，并使用 publish_artifact_to_app 返回该文件
“创建 PDF 报告、表单或文档”	托管 Agent + 配套应用：应用管理输入文件和可下载的输出文件；在沙箱中生成并验证 PDF，然后通过 tools.app_data_write 发布
“分析此 Excel／XLSX 工作簿”	托管 Agent + 配套应用：应用存储工作簿和结果；通过 tools.app_files 加载工作簿，在沙箱中解析／分析，并通过 tools.app_data_write 发布持久化结果
“将结果写入应用或向应用发布文件”	使用 tools.app_data_write（app_kv_*／publish_artifact_to_app）
“在多次运行之间记住状态”	使用 tools.agent_kv；当人们需要查看或编辑状态时，改用应用存储
“解析文件、生成文档或运行代码”	使用托管 Agent 沙箱和 tools.app_files；通过 tools.app_data_write 将持久化输出发布回应用
“通过系统发送报告邮件”	使用 tools.email；如果必须从所有者自己的邮箱发送，则在 tools.connectors 下指定由所有者关联的 Gmail 连接器
“每天早晨运行、从 Slack 运行或在浏览器关闭后运行”	使用托管 Agent，以及 cron 计划或内置的 Slack 调用路径
“提供 UI，让人们上传输入、触发运行或查看结果”	使用配套 Railcode 应用，由其 worker 调用 agents.start()（参见配套应用）
“调用任意网站／API”	先查找现有连接器（railcode connector list）；否则可选择添加连接器（connector catalog／link／add-mcp／管理员执行的 connector create），或提供导入路径——托管 Agent 无法抓取开放网络

沙盒功能

配置部署的沙盒功能后，受管理的 Agent 会在每次运行时使用独立的代码沙盒； 没有可用于请求启用沙盒的清单键或 Agent 级开关。沙盒提供 Shell 和文件工具， 使 Agent 能够编写并运行代码、检查和转换文件，并使用适当的库执行解析 Excel/CSV 数据、提取或组合 PDF、编辑文档、解压归档文件以及生成产物等任务。

沙盒是临时的，不包含凭据或持续有效的组织访问权限。使用 tools.app_files 引入租户文件， 仅通过明确声明的清单授权访问其他系统，并通过 tools.app_data_write 将持久文件或记录 写回。运行结束后，所有仅留在沙盒中的内容都会消失。

何时使用受管理的 Agent，何时使用页面内 LLM

受管理的 Agent（此技能）在服务端依照自身经批准的清单运行，配备代码沙盒， 并提供持久、可审计的运行记录。应用自身的 LLM（通过 $create-railcode-app 调用 llm.generate/llm.stream）在应用的工作线程中运行，受单次调用限制—— 它无法在请求结束后继续运行、执行代码或操作文件。请使用第一个符合条件的选项：

AI 功能……	使用
总结、分类或分析应用已读取的数据——用户正在查看，且几秒内即可完成	应用的工作线程 llm
读取、理解、提取、总结、转换或生成任何文件	受管理的 Agent（app_files + 沙盒）；切勿使用应用的 llm
编写并运行代码	受管理的 Agent（沙盒）
在应用之外触发（Slack、cron、API）	受管理的 Agent
必须在请求结束后继续运行、无人值守运行或需要重试	受管理的 Agent
产生的效果不能取决于当前查看者（共享写入、以系统身份发送）	受管理的 Agent
需要可供他人审计或调试的运行历史记录	受管理的 Agent

这些执行环境可以组合使用：应用在页面中保留聊天界面，并通过 LLM 工具的 run 调用 agents.start 来委派耗时步骤（应用清单声明 agents: [name]；此 Agent 声明 app_files: [app] 以访问上传的文件）。

从示例开始

Railcode 提供可部署的完整示例，地址为 https://github.com/Railcode-HQ/railcode-examples**。阅读示例，了解实现模式；如果某个示例涵盖了用户需求的大部分内容，就复制它。每个 agents/ 示例都由一个配套应用和其 Agent 清单**组成，这正是大多数 Agent 项目的形态。

示例	内容	展示的功能
agents/pitch-deck	一个用于上传公司资料的应用，配套 Agent 可根据这些资料生成精美的宣传演示文稿 PDF。	与应用配套的托管 Agent：app_data/app_files 访问权限、代码执行，以及从应用的 worker 调用 agents.start() 来启动运行，因为 worker 无法持有运行。
agents/proposals	一个按 cron 计划监控 Granola 会议并起草可编辑 .docx 提案的 Agent，配套应用可展示这些提案。	所有者关联并在 tools.connectors 下声明的连接器（Granola）、由 Agent 管理的 cron 计划，以及该计划为何不能放在应用上：cron 调用没有调用方，因此从 cron 调用 agents.start() 会返回 409。

Agent 无法直接拥有文件或存储，因此示例将应用与托管 Agent 配对——Agent 通过有权访问数据的应用来工作。两个配套应用都是 apps v2（由静态 frontend/ 和 server/index.ts worker 组成），因此 Agent 是从应用的 worker 启动的，而不是从页面启动。仓库的 apps/ 目录中有纯应用示例（kanban、data chat、CRM）；如需这些示例，请使用 $create-railcode-app。

先询问，不要假设。 如果用户的需求与某个示例大体相符，请在第 1 步的范围确认问题中提及该示例，并使用用户自己的说法：

"Railcode 提供了一个示例，可根据会议记录生成客户提案。您想以此为基础开始，还是从头构建？"

与其他范围确认问题一起问一次即可。切勿未经询问就复制示例；没有合适示例时，也不要提出这个问题。

复制示例

仅将这一个目录复制为普通文件 — 切勿在用户的项目中 git clone 该仓库、将其添加为子模块，或留下 .git：

mkdir -p my-proposals
curl -fsSL https://github.com/Railcode-HQ/railcode-examples/archive/refs/heads/main.tar.gz \
  | tar -xz --strip-components=3 -C my-proposals railcode-examples-main/agents/proposals

--strip-components=3 会移除 railcode-examples-main/agents/<example>/，因此示例文件会直接放入 my-proposals/。将末尾路径替换为上方其他行中的路径。若要查看某个清单而不复制任何内容，请从 https://raw.githubusercontent.com/Railcode-HQ/railcode-examples/main/agents/proposals/agents/proposal-writer/agent.yaml 获取原始文件。

Agent 清单位于 agents/<agent-name>/agent.yaml；其外围应用是一个普通的 Railcode 应用（railcode.json + manifest.yaml）。在编写行为之前，先让副本成为用户自己的：

• 重命名每个 agents/<name>/ 目录及清单中的 name，避免副本与组织中已有的 Agent 冲突。
• 将 tools.app_data / app_files / app_data_write 指向重命名后的配套应用 slug，并使用 railcode connector list 重新核对 tools.connectors 下的每个名称 — 示例中的条目（granola-…）属于其他人的组织。
• 删除新 Agent 不需要的所有工具 — 复制的清单带有示例的权限，而非完成这项工作所需的最小权限集 — 并根据新的工作负载重新设置 limits。
• 根据新的约定重写 system 提示词和 input_schema；示例的提示词包含其自身的逐步流程和输入格式。
• 在应用中：设置 railcode.json 中的 app，重命名 package.json 中的 name，运行 npm install，更新 manifest.yaml 中的 agents: 列表和每个 agents.start / agents.get 调用，并替换示例自带的 README.md（如果有）。

然后按照下方的构建工作流，在创建任何内容之前测试草稿（railcode agent test --file …）。如果下载失败，请如实说明并从头构建 — 不要凭记忆重建示例。

构建工作流

1. 确定 Agent 的范围

首先一次性提出所有范围界定问题 — 用户此刻还在；在构建过程中陆续提问，可能等用户离开后才收到答复。问题要面向不了解 Railcode 内部机制的非技术用户：询问他们的意图，并根据答案选择相应的基础组件，不要直接提及组件名称。“应该让整个团队都能运行它，还是只有你能运行？” — 不要问“要组织级还是个人级可见性？”。“它也应该每天早上自动运行吗？” — 不要问“你想要 cron 计划吗？”。下面的项目是你需要从回答中了解的信息，而不是提问时要用的措辞。

如果请求需要 Agent 无法完成的功能（抓取开放网络、响应数据变化、持续运行 — 参见 硬性限制），请一开始就说明，并提出最接近的受支持方案。只澄清会实质性改变定义的选择：

必须发现外部数据源。 每当用户要求 Agent 读取、写入、同步、搜索或操作来自某个具名产品或系统（“X”）的数据时，不要直接跳到清单，也不要断定 X 不受支持。在选择工具之前，检查已登录用户可用的每个 Railcode 集成平面：

railcode db list                       # database/data-source connections
railcode query list                    # admin-published saved queries over those sources
railcode connector list                # connectors you can reach: org-managed, yours, shared with you
railcode connector catalog             # providers that could be linked, if no row exists yet

编写之前，检查任何可能匹配的集成（对于 http 条目，使用 railcode connector docs <name>；对于 mcp 条目和已关联的账户，使用 railcode connector tools <name>），并准确复制连接器名称、端点、工具 slug 和架构，不要猜测。优先使用已保存的查询，而非 adhoc_sql。请阅读 mode 列：Agent 完全不能使用 per-user 条目（保存会被拒绝 — 该条目在调用者的账户上运行，而 Agent 没有账户）；只有当 Agent 的创建者持有某个带有所有者的 shared 条目时，才能指定该条目（创建者拥有该条目，或该条目已与创建者或组织共享）。如果无法进行身份验证或访问实例，请询问用户配置了哪些内容，并提供这些发现命令；不要把检查失败当作不存在集成的证据。 如果没有合适的数据源，请说明缺口并提供具体方案：让管理员连接数据库并发布已保存的查询；让管理员为共享凭据/API 创建由组织管理的连接器；让用户关联自己的账户（railcode connector link <provider>），或通过 URL 添加 X 的远程 MCP 服务（railcode connector add-mcp <name> <url>）——二者都会成为 Agent 在 tools.connectors 下列出的条目；或者将所需数据导入已连接的数据库/应用商店，供 Agent 读取。如果 X 没有提供这些接入方式，请说明 Railcode 无法直接连接 X，并询问用户想改用哪个替代数据源。

• 它负责的任务及预期输出；
• 它接受的输入——自由格式的 JSON 或文本；system 提示词就是输入约定；
• 它需要的模型和工具；
• 它是按需运行、从应用运行、按计划运行，还是通过 Slack 提及触发；
• 它是否需要配套应用（参见配套应用）；
• 是否要从示例开始——当从示例开始中的某个示例已涵盖大部分需求时，询问：“Railcode 提供了一个示例，可根据会议记录生成客户提案。要以此为起点，还是从头构建？”；
• 测试可能触及哪些真实系统、数据、支出或副作用；
• 其可见性——org（默认值：共享；任何拥有调用授权的人都可以调用；由创建者或任何管理员管理），或 personal（仅由创建者拥有并调用，包括管理员在内的其他人也不例外——任何授权都无法使其成为共享项，且之后不能改为 org）。当 Agent 应仅供一个人使用时，选择 personal——通常是因为它通过只有创建者持有的连接器（如其自己的 Gmail、Slack、Granola）执行操作，且不应让其他人触发它。

使用最精简且实用的工具集，并提供明确指令——但 limits 应设置得相对宽裕：根据任务匹配 Token 预算，并留出余量。文档编辑和文件分析运行消耗的 Token 远多于默认值；达到上限的运行会以 limit_exceeded 结束，而未用到的额度不会产生任何成本（参见 manifest 工具参考中的“设置 limits 大小”）。 不要臆造工具标识符、 提供商名称或 manifest 字段；由服务端定义托管 Agent 的 manifest 字段（使用 JSON 或 YAML 编写文件——参见步骤 2）。有关当前 tools.* 词汇和 limits 的信息，请参见 manifest 工具参考——它是服务端架构的快照，并非约定；保存时的报错始终优先于此文件。

2. 身份验证与检查

如果 CLI 没有可用的已保存令牌，请运行 railcode login。Agent 命令使用所选的 组织上下文，可在任何目录中运行；Agent 可以设为 org 或 personal 可见性，且不使用 railcode.json。

清单文件格式。 --file（用于 create/update/test）会以 JSON 或 YAML 格式读取清单；CLI 根据扩展名选择解析器（.yaml/.yml → YAML，其他扩展名 → JSON），两种格式都会解析为 API 存储的同一对象。没有本地清单架构验证器——应以服务器验证和批准警告为准。

对于现有 Agent，请先拉取其准确的已存储清单，再进行编辑：

railcode agent show <agent>
railcode agent pull <agent> --output agent.json

pull 和 show --manifest 只会输出 JSON——没有 YAML 输出选项。如果用户 要求以 YAML 查看或存储 Agent 定义，请自行将拉取的 JSON 转换为 YAML 并写入 agent.yaml；通过 --file 提交后可原样往返转换。

对于新 Agent，请按当前服务器支持的格式编写清单；或者，如果用户在第 1 步中选择了示例，请复制该示例的 agent.yaml 并进行调整（参见 从示例开始）。按照编写系统提示词中的说明编写 system 提示词。询问用户 是否要将定义保存在当前工作目录中。 如果要，请以 YAML 格式（agent.yaml）写入该目录，并将文件提供给 test/create；如果不要，请将其保存在项目之外的临时位置。

3. 测试草稿

在创建或替换 Agent 之前，先测试尚未保存的清单：

railcode agent test --file agent.json --input '{"key":"value"}' --trace

对于较大或敏感的测试负载，请使用 --input-file。测试会调用实际配置的 模型和工具，因此可能产生费用、读取真实数据或导致工具产生副作用。运行会产生副作用的测试前，请先获得所需授权。

通过 app_data/app_files 读取配套应用的 Agent，在空应用上无法证明任何能力。请先使用 railcode app kv set <collection> <key> '<json>' 和 railcode app files upload <path>（CLI 0.1.28+，应用所有者或组织管理员）按应用自身写入的数据结构填充数据，然后清理所有临时数据。

不要只依赖进程退出代码：请求到达运行时后，即使运行打印的状态为失败，也可能以 0 退出。请检查 Status: 或查看 --json。

草稿测试不会持久化写入。app_data_write 工具会对每次运行的内存覆盖层进行操作，而由于尚无已保存的 Agent，agent_kv 工具会被省略。运行 test 后存储未发生变化是预期行为；请使用 create + run 验证持久化。参见 清单工具参考。

4. 发布或更新

railcode agent create --file agent.yaml            # or agent.json — format is picked by extension
railcode agent create --file agent.yaml --visibility personal
railcode agent update <agent> --file agent.yaml

update 会替换已存储的清单。请从 railcode agent pull 开始，有意保留所需字段，并在确认更改完成前阅读所有批准警告。 查看拉取的清单时，请检查 system 提示词中是否残留早期测试轮次留下的内容——参见编写系统提示词。

create/update/test 中的 --visibility <org|personal> 用于设置或更改 Agent 的 归属。create/test 中省略该选项时，默认值为 org；update 中省略该选项可保留 现有可见性（切勿仅为明确设置而传入该选项——在服务器端，省略该选项与显式指定 org 是不同的请求）。创建 personal Agent 或切换为 personal 需要 agent:create 权限；org 需要 agent:create_org——持有其中一种权限并不意味着持有另一种。personal -> org 会被直接拒绝；允许 org -> personal，但不会追溯更改过去的共享运行或写入。

5. 验证已保存的 Agent

railcode agent run <agent> --input '{"key":"value"}' --trace
railcode agent show <agent> --manifest

确认已保存的清单、运行状态、输出以及相关的跟踪步骤。如需查看组织可观测性日志，请使用 $manage-railcode-org；其 railcode logs agent ... 工作流属于管理员功能，不属于 Agent 编写流程。

当 Agent 通过 tools.app_data_write 回写数据时，运行状态正常并不能证明数据已成功写入。请直接检查配套应用的数据存储（CLI 0.1.28+，应用所有者或组织管理员）：

railcode app kv collections --app <app>              # collections + record counts
railcode app kv list <collection> --app <app>        # what app_kv_set actually wrote
railcode app files list --app <app>                  # what publish_artifact_to_app produced
railcode app files download <name> --app <app>       # open the generated .docx/.pdf yourself

添加 --scope user --user <member-uuid> 或 --scope role --role <role-uuid>，以检查非共享命名空间；--scope all 会列出所有范围中的记录，并注明所有者。这也是最快发现以下问题的方法：团队原本期望写入共享记录，但个人 Agent 却将数据写入所有者的私有范围。

6. 仅在收到请求时安排计划

每个受管理的 Agent 目前最多只能有一个 cron 计划。请先检查现有计划，然后使用 schedule set 创建或更新计划；如果需要严格区分创建和更新，则使用相应的别名。

railcode agent schedule show <agent>
railcode agent schedule set <agent> --cron "0 9 * * *" --timezone UTC

使用 IANA 时区和五字段 cron 表达式。每次修改后都要验证已保存的计划。run-now 会针对真实服务同步执行。

计划运行时会传入 null 输入——每个计划没有单独的负载。编写 system 提示词时，应确保 Agent 知道在没有输入的情况下该做什么。请参见示例 Agent（daily-metrics-report）。

编写 System 提示词

system 提示词是 Agent 的完整约定：它负责什么工作、如何读取输入，以及应该返回什么。养成两个习惯，有助于提示词随着 Agent 的演进持续发挥作用。

优先使用正向指示。 说明 Agent 应该做什么，而不是不应该做什么。“仅引用上传材料中的数字，缺失时请用方括号占位” 为模型提供了明确目标；“不要编造数字” 只是禁止了一种做法，把其他部分留给模型猜测。这是一个建议，并非规则——明确的边界（“绝不向参会名单以外的任何人发送邮件”）值得直截了当地写出，硬性限制也应继续保持严格。但如果“不要”其实是在代替“应该”，就改写成“应该”。

每次更新时都要审查整份提示词。 每次运行都会从头读取提示词。Agent 不会记得之前的版本、先前的运行，或上周正在排查的 bug——因此，提示词中会逐渐堆积一些对我们来说读起来没问题、却会误导 Agent 的内容：

• 以历史背景表述的修正——“我们不再做 X，改做 Y。” 这个 Agent 从未做过 X；这句话引入了 X，还要求它同时兼顾两者。只写 Y。
• 调试遗留内容——临时指示，例如 “目前只处理前三行”，或针对已修复 bug 的变通方法。
• 失效步骤——指示中提到的工具、应用、连接器或字段，清单中已不再声明。
• 用不同措辞重复三次的同一条规则，每次都是在不同测试轮次中添加的。重复表述会互相冲突；保留最清晰的一条。

因此，在运行 railcode agent update 前，请通过 railcode agent pull 从头到尾阅读已保存的 system 提示词——不要依靠对上次编写内容的记忆——然后将它改写成一套初次接触该提示词的人也能遵循的流程。System 提示词应当像一份规范，而不是变更日志。

Slack（默认开启）

组织管理员连接组织的 Slack 工作区后，每个活跃 Agent 都可从 Slack 访问，无需为每个 Agent 单独设置。成员只需在已邀请机器人加入的频道中提及机器人，即可运行 Agent：

@Railcode $<agent-name> summarize this thread

Agent 名称前须加 $，且必须是提及机器人后的第一个词元（如果只输入名称，系统会显示使用提示，而不会悄悄运行某个 Agent）。这对 Agent 设计意味着：

• 权限不变。 系统会通过已验证的电子邮件将 Slack 调用者匹配到组织中的有效成员，且该成员必须拥有常规调用授权——没有匹配项就不会运行。因此，personal Agent 只有其所有者能从 Slack 访问。
• 输入以 { text: <message> } 的形式传入。 Agent 输入是自由格式，因此可以提及任何 Agent；其 system 提示词必须说明如何解读该输入。
• 平台会将最终回复发布到提及机器人的线程中，无论成功还是失败。Agent 返回的内容就是 Slack 回复（由 Slack 触发的运行会在其 system 提示词中获知这一点，并被要求使用 Slack mrkdwn 编写）；它无需使用 slack 连接器来回复——获准使用该连接器时，它仅用于发布中间进度更新。

因此，团队打算以对话方式使用的任何 Agent，都应能处理自由文本输入，并生成适合作为 Slack 消息的最终回复。

配套应用

Agent 通常需要一个配套应用——一个部署在 Agent 旁边的小型应用（$create-railcode-app）。如今构建的每个应用都是 apps v2：由静态前端和后端 worker 组成，因此配套应用通过 @railcode/sdk 在 worker 中调用 Agent，而不是从页面调用。只要 Agent 依赖需要有人管理的文件或记录，或需要一个供人们触发 Agent 并查看其输出的界面，就可以采用这种模式：

• Agent 所依赖的存储——应用是上传和管理 Agent 要读取的文件与记录的界面：在应用中使用 files.upload()/db；在 Agent 的清单中使用 app_files: [<app-slug>] / app_data: [<app-slug>]。
• 展示结果的界面——Agent 通过 app_data_write (app_kv_set, publish_artifact_to_app) 写回结果，应用负责呈现运行输出。
• 轻松测试和触发——通过 agents.start(name, input) 接入的 worker 路由 （应用清单：agents: [<agent-name>]）可端到端测试 Agent，速度远快于手动编写 CLI 运行命令，也可作为生产环境中的交互式触发方式。

通过 v2 配套应用驱动 Agent，需要了解以下四点：

• agents.start() 会立即返回一个已排队的运行任务。将 request_id 传给前端，然后让前端轮询调用 agents.get() 的路由。worker 端没有等待运行完成的调用，而且循环调用 get() 也无法替代这一做法：每次轮询都会消耗一个子请求，并且令牌会在长时间运行结束前过期。
• 应用必须声明 Agent（agents: [<name>]）。缺少声明时会拒绝请求（403），而不是放行——即使调用方可以从控制面板调用该 Agent 也一样。
• 运行任务归 (app, caller) 所有。 应用只能读取由自己启动、且启动者为当前调用方的运行任务；它看不到从控制面板启动的运行任务。
• 应用的 cron 无法启动运行任务（409——没有调用方就没有运行任务的所有者）。要执行定时任务，请为 Agent 设置自己的计划任务。

对于 v2 配套应用，优先使用 ORG Agent。 ORG Agent 的 app_data_write 会写入应用的共享作用域，也就是 v2 应用的扁平 db 存储——因此，结果会显示在 worker 已读取的集合中，无需桥接。个人 Agent 会将数据写入所有者的用户作用域；迁移后的应用中，worker 对该作用域的访问已冻结且为只读。

应用名称应与 Agent 相关（例如，Agent report-extractor，应用 report-extractor-console），两端都声明范围最窄的 slug，并使用 $create-railcode-app 构建应用。Start From An Example 中的 agents/ 条目，都是完全采用这种配对方式的可运行 apps-v2 版本，涵盖 Agent 清单和 worker——如果其中某个示例符合用户的需求，就复制使用。

严格限制

无论清单如何配置，托管式 Agent 都不能执行以下操作（完整的平台级列表见 $create-railcode-app →“限制”）：

• 访问开放网络。 沙箱出站流量采用允许列表（PyPI、npm、带有 app_files 的预签名 下载主机）；connector 工具只能访问已批准的端点。 不能抓取数据，也不能调用任意 API。
• 长时间或持续运行。 运行受限——最多 300 步 / 1200 秒 / limits 中的 token 上限。不能运行守护进程或监控程序；周期性工作需使用 cron 计划。
• 响应事件。 仅支持应用/API 调用、cron 和 Slack 提及作为触发器——不支持数据变更或 入站 Webhook 触发器。
• 调用其他 Agent。 没有 Agent→Agent 工具；请改为通过应用 或外部调用方来组合流水线。
• 使用按用户配置的连接器。 按用户配置的连接器（名称相同，但每位成员使用自己的账户） 会使用调用方的账户运行，而 Agent 没有调用方：保存时会拒绝指定此类连接器的清单，运行时运行器也会拒绝它。请改为指定创建者拥有的连接器 （或组织管理的连接器）；按 URL 添加的 MCP 条目（railcode connector add-mcp）可以使用。
• 保留沙箱状态。 沙箱文件系统按运行隔离；需要保留的内容必须在运行结束前发布 （publish_artifact_to_app）或写入 KV。

权限与边界

• list、show 和 pull 只会返回组织 Agent 以及调用方自己的 个人 Agent——看不到其他人的个人 Agent（返回 404，而非 403，以免确认其存在），包括管理员在内。
• 对于组织 Agent：run 需要该 Agent 的调用授权；update/delete/test/ 计划变更仅允许该 Agent 的创建者本人或任何组织所有者/管理员执行——并非 每位成员都可以。创建组织 Agent（或将现有 Agent 转为组织 Agent）还需要 agent:create_org 权限。
• 对于个人 Agent：调用和管理都仅限所有者，管理员无权越权——没有紧急访问机制， 因此即使组织所有者/管理员也无法访问他人的个人 Agent。创建个人 Agent 需要可广泛授予的 agent:create 权限，而非所有者/管理员身份。
• delete 会归档 Agent，同时保留运行历史；在非 TTY 环境中需要指定 --yes。
• 构建应用时，如果应用要从其 worker 通过 agents.start(name, input) 启动 Agent， 请使用 $create-railcode-app。具有特权的应用清单需声明 agents: [name]。
• 应用也可以通过 llm.generate({ tools }) / llm.stream({ tools }) 在页面内运行自己的 Agent 循环，无需托管式 Agent。有关两者的区别，请参阅本技能顶部的 何时使用托管式 Agent，何时使用页面内 LLM。
• 成员、角色/授权、应用/访问权限、连接、服务连接器、分析和组织日志，请使用 $manage-railcode-org。

参考

阅读CLI 参考，了解准确的 Agent 命令、别名、 计划行为、输入、输出和失败语义。阅读 清单工具参考，了解 tools.* 术语、 每项工具授予的权限、权限门槛以及 limits。阅读 示例 Agent，查看可运行的完整清单示例，涵盖最简 Agent 和定时查询转邮件工作流。有关完整的 Agent 加配套应用项目 （演示文稿、客户提案），请阅读或复制 railcode-examples 中的项目——参见 从示例开始。