migrate-to-railcode
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMigrate to Railcode
迁移到 Railcode
A migration is a port, not a rewrite: the project already works somewhere, and the job is to
keep what it does for its users while replacing what the old host provided (auth, a database,
env vars, cron, file storage) with what Railcode provides.
Most internal tools fit. Usually one or two pieces have no direct equivalent, and almost all
of those can be rebuilt a different way that the user will not notice — see
Find another way. A short list of things cannot be hosted at all today —
see What Railcode cannot host today. Know both lists
before you promise anything.
Guides by source project:
| Source project | Guide | Status |
|---|---|---|
| Next.js (App Router) | references/nextjs.md | Supported as |
A container: a | references/containers.md | Method and mappings built from the platform's documented behaviour; not yet backed by a recorded migration |
For any other source, follow the method below and build the app with .
create-railcode-appRailcode's own is meant for fast, simple use. It has limits for a lot of data or complex
queries (no joins, aggregates or transactions; paged reads), so a project that needs those
keeps its database. references/databases.md covers those limits,
connecting a database as a data source, using it directly with a secret, databases Railcode
has no connector for, where schema migrations run, and how to register interest in a managed
Postgres through .
dbrailcode agent-feedback迁移是一次移植,而不是重写:项目已经在某个环境中正常运行,任务是在保留其对用户提供的功能的同时,用 Railcode 提供的能力替换旧托管环境提供的组件(auth、数据库、环境变量、cron、文件存储)。
大多数内部工具都适合迁移。通常只有一两个部分没有直接对应物,而几乎所有这些部分都能通过用户不会察觉的不同方式重建——参见寻找替代方式。目前还有一小部分功能完全无法承载——参见Railcode 目前无法承载的功能。在做出承诺前,先了解这两份清单。
按来源项目划分的指南:
| 来源项目 | 指南 | 状态 |
|---|---|---|
| Next.js(App Router) | references/nextjs.md | 支持 |
容器:包含运行任意语言服务器的 | references/containers.md | 方法和映射依据平台的文档行为制定;尚无已记录的迁移案例佐证 |
对于其他来源项目,请按照下方方法执行,并使用 构建应用。
create-railcode-appRailcode 自带的 适合快速、简单的使用。对于海量数据或复杂查询,它存在限制(不支持 join、aggregate 或 transaction;采用分页读取),因此需要这些能力的项目应保留自己的数据库。references/databases.md 介绍了这些限制、如何将数据库作为 data source 连接、如何直接配合 secret 使用数据库、Railcode 没有 connector 的数据库、schema migration 在哪里运行,以及如何通过 登记使用托管 Postgres 的意向。
dbrailcode agent-feedbackUpdate First
先更新
Before running a command, update the skills and the CLI and confirm what is
published:
railcodebash
npx skills add Railcode-HQ/railcode-skills
npm install -g railcode@latest
railcode --version
npm view railcode versionIf npm is unreachable, say so and do not claim this guidance is current. This version was
written against CLI 0.3.8, 0.4.0 and 0.1.0.
@railcode/sdk@railcode/nextThis skill does not restate the SDK, the manifest or the deploy flow. Those live in
(, ,
, ); read them when a step below names
an SDK surface.
create-railcode-appreferences/worker-sdk.mdreferences/cli-workflow.mdreferences/deployment.mdreferences/app-patterns.md运行任何 命令之前,更新 skills 和 CLI,并确认已发布的版本:
railcodebash
npx skills add Railcode-HQ/railcode-skills
npm install -g railcode@latest
railcode --version
npm view railcode version如果 npm 无法访问,应如实说明,不要声称本指南为最新版本。本指南基于 CLI 0.3.8、 0.4.0 和 0.1.0 编写。
@railcode/sdk@railcode/next本 skill 不会重复说明 SDK、manifest 或部署流程。这些内容位于 (、、、);当下文提到某个 SDK surface 时,请阅读相应内容。
create-railcode-appreferences/worker-sdk.mdreferences/cli-workflow.mdreferences/deployment.mdreferences/app-patterns.mdWhat Railcode is, for someone arriving from another host
从其他托管环境迁移时,Railcode 是什么
Four facts shape every migration. Check the project against them first.
- Every viewer is a signed-in member of the organization. There are no anonymous visitors and no self-signup. Railcode hosts internal tools.
- The backend is one worker module on a Workers runtime (), not a Node server and not a container. It runs once per request and keeps nothing in memory between requests. No filesystem, no child processes, no native addons, no raw TCP.
nodejs_compat - The worker runs only when a signed-in member's browser calls it, or on the app's own cron. Nothing on the public internet can call it.
- Authentication is ambient. The platform signs the user in before any app code runs and
hands the worker a verified . The project's own login goes away, and that is usually the largest deletion in the migration.
ctx.user
In exchange the app gets, with no setup: sign-in, a store (), file storage (), an
LLM gateway (), email sending, per-app secrets, cron, connectors to the org's databases
and SaaS accounts, managed agents, deploy history and logs.
dbfilesllm以下四项事实决定了所有迁移方式。首先用它们检查项目。
- 每个访问者都是组织中已登录的成员。 不存在匿名访问者,也不支持自行注册。Railcode 用于托管内部工具。
- 后端是 Workers 运行时()上的一个 worker module,而不是 Node 服务器或容器。它每次请求运行一次,请求之间不会在内存中保留任何内容。不支持文件系统、子进程、native addon 或 raw TCP。
nodejs_compat - 只有已登录成员的浏览器调用 worker,或应用自身的 cron 调用 worker 时,它才会运行。 公共互联网无法调用它。
- 身份验证是环境内置的(ambient)。 平台会在任何应用代码运行前为用户登录,并将经过验证的 交给 worker。项目自身的登录机制会被移除,这通常是迁移中删除量最大的部分。
ctx.user
作为交换,应用无需额外配置即可获得:登录、 存储、 文件存储、 gateway、邮件发送、per-app secrets、cron、组织数据库和 SaaS 账号的 connectors、managed agents、部署历史与日志。
dbfilesllmMethod
方法
Work in this order. Do the inventory before touching code: most failed migrations port the UI
first and discover on day two that the data layer has no equivalent.
请按以下顺序执行。必须在修改代码之前完成盘点:大多数失败的迁移会先移植 UI,到了第二天才发现 data layer 没有对应物。
1. Inventory
1. 盘点
Read the project and write down, with file paths:
| What | Where to look |
|---|---|
| Auth | NextAuth/Auth.js, Clerk, Supabase auth, Passport, a session cookie, a |
| Data | An ORM (Prisma, Drizzle, SQLAlchemy, ActiveRecord), a database URL, a hosted KV or blob store |
| Secrets and config | |
| Scheduled and background work | |
| Outbound calls | Every host the server code fetches |
| Inbound calls | Webhooks, public API routes, OAuth callbacks, anything not called by the app's own frontend |
| Files | Uploads, generated documents, an S3 client, a mounted volume |
| Processes and binaries | Every service in docker-compose, every |
| Host-specific packages | |
阅读项目,并连同文件路径记录以下内容:
| 内容 | 查看位置 |
|---|---|
| Auth | NextAuth/Auth.js、Clerk、Supabase auth、Passport、session cookie、 |
| 数据 | ORM(Prisma、Drizzle、SQLAlchemy、ActiveRecord)、database URL、托管的 KV 或 blob store |
| Secrets 和配置 | |
| 定时和后台工作 | |
| 出站调用 | 服务端代码会请求的每一个 host |
| 入站调用 | Webhooks、公共 API routes、OAuth callbacks,以及任何并非由应用自身前端调用的内容 |
| 文件 | 上传内容、生成的文档、S3 client、挂载的 volume |
| 进程和二进制文件 | docker-compose 中的每个服务、每次 |
| 特定于托管平台的包 | |
2. Map each item
2. 映射每一项
| The project has | On Railcode |
|---|---|
| Its own login and sessions | Delete the authentication machinery. Read |
| A user table | Keep what is application data (profiles, preferences, app-level roles): move it to |
| Per-user rows in its own database | |
| A database it reads (Postgres, BigQuery, Turso) | Connect it as a data source: a data connector an org admin sets up. Read-only. Prefer saved queries ( |
| A database it reads and writes | Keep it and use it directly: the connection credential in |
| A database Railcode has no connector for (MySQL, MongoDB, DynamoDB, Redis and so on) | The same: set its credentials as secrets, allow its host, and use it as before over its HTTPS API |
| Schema migrations (Prisma, Drizzle, Alembic, Rails) | Run them in the build or deploy script, on the machine that runs it, never in the worker. See references/databases.md |
| |
| Cron jobs | |
| Outbound fetches | List each host under |
| File uploads, a mounted volume | |
| An LLM provider key and client | |
| Transactional email | |
| A SaaS API it calls with its own OAuth flow or API key | A connector an admin or the user links, called with |
| A queue, websockets, a webhook receiver, a native binary, a search index | No direct equivalent. Go to Find another way |
For every item with no direct equivalent, tell the user before porting: what the project
does today, how you propose to rebuild it, and what changes for them (for example "new
payments show up within a minute instead of instantly"). Get a yes on each one. A different
implementation the user agreed to is a good migration; an approximation they discover later
is a bug.
| 项目包含 | 在 Railcode 中 |
|---|---|
| 自身的登录和 sessions | 删除身份验证机制。读取 |
| 用户表 | 保留属于应用数据的部分(profiles、preferences、应用级角色)并迁移到 |
| 自有数据库中的 per-user 行 | |
| 仅读取的数据库(Postgres、BigQuery、Turso) | 将其连接为 data source:由组织管理员设置 data connector。只读。 优先使用 saved queries( |
| 同时读取和写入的数据库 | 保留并直接使用:在 |
| Railcode 没有 connector 的数据库(MySQL、MongoDB、DynamoDB、Redis 等) | 同样处理:将 credentials 设为 secrets,允许其 host,然后像以前一样通过其 HTTPS API 使用 |
| Schema migrations(Prisma、Drizzle、Alembic、Rails) | 在构建或部署脚本运行的机器上执行,绝不能在 worker 中执行。参见 references/databases.md |
| |
| Cron jobs | 在 |
| 出站 fetch | 在 |
| 文件上传、挂载的 volume | |
| LLM provider key 和 client | |
| Transactional email | |
| 使用自有 OAuth flow 或 API key 调用的 SaaS API | 由管理员或用户关联 connector,并通过 |
| Queue、websockets、webhook receiver、native binary、search index | 没有直接对应物。请参阅寻找替代方式 |
对于每个没有直接对应物的部分,必须在移植之前告知用户:项目目前具备什么功能、建议如何重建,以及用户会看到哪些变化(例如,“新支付会在一分钟内出现,而不是立即出现”)。每一项都需要获得用户确认。用户认可的不同实现是成功的迁移;用户事后才发现的近似替代则属于缺陷。
3. Port
3. 移植
- Add the Railcode files (,
railcode.json) and get an unchanged page rendering undermanifest.yaml.railcode dev - Replace auth.
- Replace the data layer, one entity at a time.
- Move secrets, crons and egress into the manifest and .
railcode secrets - Rebuild the pieces from Find another way.
- Remove the old host's packages and config.
Keep each step runnable. A migration that only works when all six are done is one you cannot
debug.
railcode devdbfilesllm- 添加 Railcode 文件(、
railcode.json),并让未经修改的页面能够在manifest.yaml下正常呈现。railcode dev - 替换 auth。
- 逐个 entity 替换 data layer。
- 将 secrets、crons 和 egress 迁移到 manifest 与 。
railcode secrets - 重建寻找替代方式中列出的部分。
- 移除旧托管平台的包和配置。
每一步都应保持可运行。只有六步全部完成后才能运行的迁移无法调试。
railcode devdbfilesllm4. Deploy beside the original
4. 与原应用并行部署
Deploy to a new app slug and leave the original running. Nothing about a first deploy is
destructive, and the user can compare the two. Only move data and switch people over once the
new app has been checked.
Existing data does not move by itself. If it matters, write a one-off import (a script that
reads the old store and writes through a temporary admin-only route, or
from the CLI), run it once, and delete it.
railcode app kvRecords owned by a user need their owner translated. The old app's user ids mean nothing on
Railcode, so importing rows under their old ids leaves them unreachable. Build the mapping
first — old id → email → the Railcode member with that email () — show the user who
did not match, and only then import, writing each record under the Railcode id.
appUsers使用新的 app slug 部署,同时保持原应用运行。第一次部署不会造成破坏,用户可以比较两个版本。只有检查完新应用后,才能迁移数据并切换用户。
现有数据不会自动迁移。如果数据很重要,请编写一次性导入程序(读取旧存储并通过临时的 admin-only route 写入,或使用 CLI 中的 ),运行一次后将其删除。
railcode app kv由用户拥有的记录需要转换 owner。旧应用的 user id 在 Railcode 中没有任何意义,因此使用旧 id 导入的行将无法访问。应先建立映射:旧 id → email → email 对应的 Railcode member(),向用户展示未匹配项,确认后再导入,并使用 Railcode id 写入每条记录。
appUsers5. Verify, then report
5. 验证,然后报告
Load the deployed app as a real user and exercise each migrated feature; a green deploy says
only that the bundle uploaded. lists every invocation, and
shows its console output and errors.
railcode logs app --app <slug>railcode logs app <invocation-id>Report in this order: what works and how it was checked, what was rebuilt differently and
what changed for the user, what was left out and why, what the user must still do (secrets to
set, connectors to link, data to import).
以真实用户身份加载已部署的应用,并逐一操作每个迁移后的功能;部署成功只说明 bundle 已上传。 会列出每次 invocation, 会显示其 console output 和 errors。
railcode logs app --app <slug>railcode logs app <invocation-id>按以下顺序报告:哪些功能可用以及如何验证;哪些部分采用了不同的重建方式以及用户会看到哪些变化;哪些内容未迁移以及原因;用户还需要完成哪些操作(设置 secrets、关联 connectors、导入数据)。
Find another way
寻找替代方式
When a piece of the project has no direct equivalent, do not stop and do not drop it. Ask what
the piece is for, not what it is built from. A queue exists so that slow work finishes
without the user waiting. A webhook exists so the app learns about a payment. A websocket
exists so a list looks current. Each of those outcomes can usually be reached with a cron, the
store, and a frontend that polls.
The building blocks you have:
- A cron that fires as often as once a minute and can use ,
db,files,llm,email, egress, SQL and org connectors.secrets - A store you can use as a queue, a cache, a lock or a cursor.
- A frontend that can call the worker as often as it likes. A browser tab has no subrequest budget and stays open, so it can drive long work one step at a time.
- Managed agents for work that is long, needs code execution, or reads files with AI.
- Connectors to the org's existing databases and SaaS accounts.
- Outbound HTTP to any host you declare, so a hosted API can do what a local binary did.
Shapes that work:
| The project does this | Build it like this | What changes for the user |
|---|---|---|
| Receives a webhook to learn that something happened (a payment, a new issue, a form entry) | A cron polls the provider's list or events API. Keep the last-seen id or timestamp in | Up to a minute of delay |
| Runs a job queue (BullMQ, Celery, Sidekiq) | A | Jobs start within a minute, not instantly |
| Does one long task in a request (a big import, a report over thousands of rows) | Split it into steps with a cursor in | A progress bar instead of a spinner |
| Pushes live updates over websockets or SSE | The frontend polls a cheap route every few seconds, only while the tab is visible. Return an | Updates arrive within the poll interval |
| Streams text to the browser | Return a streamed | Nothing |
| Joins and filters in SQL on its own database | Design keys for the reads the screens make ( | Nothing, if the keys match the screens |
| Writes to a relational database that must stay relational (transactions, constraints, other systems read it) | Keep the database and use it directly from the worker with a secret and an HTTPS driver (references/databases.md). Data connectors are read-only, so they cover the reads only. If the database has no HTTPS interface, put one in front of it or keep a small write service on the old host | Nothing, when an HTTPS driver exists |
| Caches in Redis or in process memory | A | Nothing |
| Rate-limits or locks with Redis | A | Nothing |
| Full-text search over its own records | For a few thousand records, load and filter in the worker or the browser. Beyond that, query the source database through a connector, or call a hosted search API through | Nothing |
| Shells out to a binary (ffmpeg, ImageMagick, Chromium, pandoc) | First look for a pure-JavaScript library that fits in the worker bundle; PDF and spreadsheet generation usually do. Otherwise call a hosted API through | Possibly a slower or asynchronous result |
| Runs its own OAuth flow against Google, Slack, GitHub and so on | A connector. An admin links an org account, or each user links their own; the worker calls | Users link the account once in Railcode instead of in the app |
| Receives email, or sends from a real person's or team's address | A Gmail connector for that account: polled on a cron with a stored cursor when org-owned, or read by a personal managed agent on a schedule for one person's own inbox | Up to a minute of delay on inbound mail |
Needs embeddings, vision or another model feature the | Call that provider directly: the key in | Nothing |
| Sends push or chat notifications | | The notification arrives in email or Slack |
| Has one public page among many internal ones (a public form, a status page) | Split it. Leave the public page on the old host writing to its database; the Railcode app reads that database through a data connector | Two deployments instead of one |
| Renders HTML on the server with templates (Jinja, ERB, EJS) | A static frontend that fetches JSON from | Nothing |
| Has several services in docker-compose | One worker with several route groups. If two parts have different audiences, make them two apps | Nothing |
Rules for doing this well:
- Say what changes. Every row trades something, usually latency. State it in one sentence and get agreement before building.
- Prefer the simplest block. A frontend poll beats a cron; a cron beats an agent.
- Check the cron limits before designing around one: one-minute minimum, five schedules
per app, no caller (is
ctx.user), and it cannot start or read managed agent runs. One cron route can dispatch several kinds of work when five schedules is not enough.null - Do not fake a guarantee. If the original relied on a transaction, exactly-once delivery or an instant response to a third party, a polling version does not provide it. That belongs in the next section.
If the user needs something that is not in this table, design it from the building blocks,
tell them it is a new pattern, and report it (see Feedback) so it can be added.
当项目的某一部分没有直接对应物时,不要停止,也不要将其丢弃。应询问这部分功能是为了什么,而不是它由什么构成。Queue 的存在是为了让耗时工作无需等待用户即可完成。Webhook 的存在是为了让应用获知支付事件。Websocket 的存在是为了让列表看起来保持最新。这些结果通常都可以通过 cron、存储和定期轮询的前端来实现。
可用的 building blocks:
- 最快可每分钟触发一次的 cron,可使用 、
db、files、llm、email、egress、SQL 和组织 connectors。secrets - 可用于 queue、cache、lock 或 cursor 的 store。
- 可按任意频率调用 worker 的前端。 浏览器 tab 没有 subrequest budget,且会保持打开,因此可以逐步驱动耗时工作。
- Managed agents,适用于耗时较长、需要执行代码或使用 AI 读取文件的工作。
- Connectors,用于连接组织现有的数据库和 SaaS 账号。
- 可向任意已声明 host 发出的 Outbound HTTP,从而让托管 API 替代原本在本地运行的二进制文件。
可行的改造方式:
| 项目当前行为 | 建议实现方式 | 用户看到的变化 |
|---|---|---|
| 接收 webhook 以获知某事件(支付、新 issue、表单提交) | Cron 轮询 provider 的 list 或 events API。在 | 最多延迟一分钟 |
| 运行 job queue(BullMQ、Celery、Sidekiq) | 创建一个 | 任务在一分钟内启动,而不是立即启动 |
| 在单个 request 中执行耗时任务(大型导入、针对数千行的报表) | 使用 | 显示进度条,而不是加载指示器 |
| 通过 websockets 或 SSE 推送实时更新 | 前端仅在 tab 可见时每几秒轮询一个低成本 route。返回 | 更新会在轮询间隔内到达 |
| 将文本流式发送到浏览器 | 返回 streamed | 无变化 |
| 在自有数据库中使用 SQL 进行 join 和 filter | 根据界面读取方式设计 key( | 如果 key 与界面匹配,则无变化 |
| 写入必须保持关系型的数据库(transactions、constraints、其他系统也会读取) | 保留数据库,并在 worker 中使用 secret 和 HTTPS driver 直接访问(references/databases.md)。Data connectors 是只读的,因此只能覆盖读取操作。如果数据库没有 HTTPS interface,应在其前面增加代理,或在旧 host 上保留一个小型 write service | 存在 HTTPS driver 时无变化 |
| 使用 Redis 或进程内存缓存 | 使用带 | 无变化 |
| 使用 Redis 进行 rate limit 或 lock | 为每个 key 使用一行 | 无变化 |
| 对自身记录进行 full-text search | 对于数千条记录,可在 worker 或浏览器中加载并过滤。超出该范围时,通过 connector 查询源数据库,或通过 | 无变化 |
| 调用二进制文件(ffmpeg、ImageMagick、Chromium、pandoc) | 首先寻找适合 worker bundle 的纯 JavaScript library;PDF 和 spreadsheet generation 通常都适用。否则通过 | 结果可能更慢或变为异步 |
| 针对 Google、Slack、GitHub 等运行自有 OAuth flow | 使用 connector。由管理员关联组织账号,或由每个用户关联自己的账号;worker 调用 | 用户改为在 Railcode 中关联一次账号,而不是在应用中关联 |
| 接收邮件,或从真人或团队的邮箱地址发送邮件 | 使用对应账号的 Gmail connector:组织账号可通过 cron 轮询并保存 cursor;个人收件箱可由 personal managed agent 按计划读取 | 接收邮件最多延迟一分钟 |
需要 embeddings、vision 或 | 直接调用对应 provider:key 存放在 | 无变化 |
| 发送 push 或 chat 通知 | 使用 | 通知通过 email 或 Slack 送达 |
| 多个内部页面中有一个公共页面(公共表单、状态页) | 将其拆分。公共页面继续保留在旧 host 并写入其数据库;Railcode 应用通过 data connector 读取该数据库 | 变成两个部署,而不是一个 |
| 在服务端使用模板渲染 HTML(Jinja、ERB、EJS) | 使用静态前端,从 | 无变化 |
| docker-compose 中包含多个服务 | 使用一个 worker 和多个 route groups。如果两部分面向不同受众,则创建两个应用 | 无变化 |
良好实践的规则:
- 说明会发生什么变化。 每一项改造通常都会牺牲某些能力,最常见的是延迟。用一句话说明并获得用户同意后再开始构建。
- 优先采用最简单的 block。 前端轮询优于 cron,cron 优于 agent。
- 围绕 cron 设计之前,先检查其限制:最短周期为一分钟,每个应用最多五个 schedule,没有调用者(为
ctx.user),并且不能启动或读取 managed agent runs。如果五个 schedule 不够,一个 cron route 可以分派多种工作。null - 不要伪造保证。 如果原实现依赖 transaction、exactly-once delivery 或对第三方的即时响应,轮询版本无法提供这些保证。这些情况将在下一节中讨论。
如果用户需要的功能不在此表中,应基于现有 building blocks 进行设计,告知用户这属于一种新模式,并进行报告(参见反馈),以便将其补充进来。
What Railcode cannot host today
Railcode 目前无法承载的功能
Some things have no workaround, because they need the internet to reach the app, a process
that stays alive, or a runtime the platform does not offer. Recognise these during the
inventory, not after the port.
| The project needs | Why it does not fit |
|---|---|
| Inbound webhooks that must be answered — Slack slash commands and interactive buttons, Twilio voice or SMS replies, a provider that retries until it gets an acknowledgement and offers no API to poll | Nothing outside the organization can call the worker. A webhook that only notifies can be replaced by polling (above); one that expects the app's response cannot |
| A public API or public endpoints for customers, partners, mobile apps or other servers | Same reason. Requests come from a signed-in member's browser or from Railcode's own agents, never from an outside system |
| Public or customer-facing pages: a marketing site, a storefront, self-signup, anything meant for search engines | Every viewer is a signed-in org member |
| Its own identity system: logging in people who are not org members, issuing its own API keys or tokens to third parties | Identity is the organization's membership |
| True real time: collaborative editing, presence, multiplayer, a websocket server | There is no push surface. Polling covers "looks current", not "keystroke by keystroke" |
A long-lived process: a daemon, a bot holding a socket open, a stream consumer (Kafka, Postgres | The worker runs per request and then stops |
Non-HTTP protocols: a database driver over TCP ( | No raw TCP in or out. Databases are reached through a data connector (reads) or an HTTPS driver with a secret (reads and writes); see references/databases.md. A database with only a socket interface and nothing in front of it cannot be reached |
| The container itself: a Python, Go, Ruby, Java or PHP server run as it is, system packages, native addons, a GPU, a local model | The backend is one JavaScript module. Other languages are ported, not hosted — see the container guide |
A large or multi-file backend bundle: | The worker is a single ESM module |
| A custom domain, a native mobile app, browser push notifications | Apps are web apps at |
Its own mail domain: an inbound mail server, an address the app owns, or | |
When the project needs one of these:
-
Tell the user at once, plainly. Name the feature, and say in a sentence that it cannot run on Railcode today and why. Do not present a polling imitation of something that needs a response as if it were equivalent.
-
Offer what is still possible. Usually the rest of the project migrates and the one piece stays where it is, sharing a database that Railcode reads through a connector. If the missing piece is the core of the project (a public storefront, a Slack bot), say the project should stay on its current host for now.
-
Submit the request with the CLI. The Railcode team decides what to build next from these reports. Send one for each distinct missing capability, even when part of the project migrated:bash
railcode agent-feedback --category suggestion \ --message "Migration blocked on inbound webhooks. The project receives POST /webhooks/slack for slash commands and must reply within 3 seconds; there is no API to poll instead. Request: a way for an app to expose a public, signature-verified endpoint." \ --context "Source: Express + Postgres in a container, about 40 routes. Everything else mapped to db, secrets and crons. The Slack routes stayed on the old host; the rest was migrated." \ --agent "<your assistant name>" --model "<your model>"Write it so someone who has never seen the project understands the need: what the project is (stack and rough size), exactly what it needed, what you did instead, and whether the migration went ahead. Leave out credentials, customer data, source code and anything that identifies the user's customers. The command needs an existing login and prints; all options are inFeedback accepted.under "Report Railcode feedback". If it fails, tell the user the report was not sent and carry on.create-railcode-app -
Tell the user you sent it, and what it said.
Do not file a request for something the platform already does a different way; check
Find another way and first.
create-railcode-app有些功能没有可行的替代方案,因为它们需要公共互联网访问应用、需要持续运行的进程,或需要平台不提供的 runtime。应在盘点阶段识别这些问题,而不是移植完成后才发现。
| 项目需要 | 不适合承载的原因 |
|---|---|
| 必须返回响应的入站 webhooks——Slack slash commands 和 interactive buttons、Twilio voice 或 SMS replies,以及会持续重试直至收到确认且不提供轮询 API 的 provider | 组织以外的任何内容都无法调用 worker。仅用于通知的 webhook 可以改为轮询(见上文);需要应用返回响应的 webhook 则不行 |
| 面向客户、合作伙伴、移动应用或其他服务器的公共 API 或公共 endpoints | 原因相同。请求只能来自已登录成员的浏览器或 Railcode 自身的 agents,绝不会来自外部系统 |
| 公共或面向客户的页面:营销站点、storefront、自助注册,以及任何面向搜索引擎的内容 | 每个访问者都是已登录的组织成员 |
| 自有身份系统:允许非组织成员登录、面向第三方签发自有 API keys 或 tokens | 身份由组织成员资格决定 |
| 真正的实时能力:协作编辑、presence、multiplayer、websocket server | 没有 push surface。轮询可以保证“看起来是最新”,但无法做到逐按键更新 |
长驻进程:daemon、保持 socket 打开的 bot、stream consumer(Kafka、Postgres | Worker 每次 request 执行一次,随后即停止 |
非 HTTP 协议:基于 TCP 的 database driver( | 不支持 raw TCP。数据库通过 data connector(读取)或配合 secret 的 HTTPS driver(读取和写入)访问;参见 references/databases.md。只有 socket interface 且前面没有任何服务的数据库无法访问 |
| 容器本身:按原样运行的 Python、Go、Ruby、Java 或 PHP server、system packages、native addons、GPU、本地模型 | 后端是一个 JavaScript module。其他语言需要移植,而不是直接托管——参见容器指南 |
大型或多文件后端 bundle: | Worker 是单个 ESM module |
| 自定义域名、原生移动应用、浏览器 push notifications | Apps 是部署在 |
自有邮件域名:入站 mail server、应用拥有的地址,或使用自定义 sender 调用 | |
当项目需要上述能力时:
-
立即且明确地告知用户。 指明具体功能,并用一句话说明它目前无法在 Railcode 上运行及其原因。不要把需要返回响应的 webhook 伪装成与原功能等价的轮询实现。
-
提供仍然可行的方案。 通常可以迁移项目的其余部分,只让缺失的部分继续留在原 host,并通过 connector 让 Railcode 读取共享的数据库。如果缺失部分正是项目的核心(例如公共 storefront 或 Slack bot),则应说明项目目前应继续保留在当前 host。
-
使用 CLI 提交请求。 Railcode 团队会根据这些报告决定接下来构建什么。针对每项不同的缺失能力分别提交一份报告,即使项目只有一部分完成迁移:bash
railcode agent-feedback --category suggestion \ --message "Migration blocked on inbound webhooks. The project receives POST /webhooks/slack for slash commands and must reply within 3 seconds; there is no API to poll instead. Request: a way for an app to expose a public, signature-verified endpoint." \ --context "Source: Express + Postgres in a container, about 40 routes. Everything else mapped to db, secrets and crons. The Slack routes stayed on the old host; the rest was migrated." \ --agent "<your assistant name>" --model "<your model>"撰写内容时,应确保从未接触过该项目的人也能理解需求:项目是什么(技术栈和大致规模)、确切需要什么、你改用了什么,以及迁移是否继续进行。不要包含 credentials、客户数据、源代码或任何能够识别用户客户的信息。该命令需要已有登录,并会输出;所有选项列于Feedback accepted.中的“Report Railcode feedback”。如果执行失败,应告知用户报告未发送成功,并继续后续工作。create-railcode-app -
告知用户报告已发送,以及报告的具体内容。
如果平台已经以其他方式支持某项功能,不要提交请求;应先检查寻找替代方式 和 。
create-railcode-appMachine safety
机器安全
Framework builds are heavy, and a migration runs many of them.
- Run one build or dev server at a time, and stop every process you start before finishing a
turn. Check with rather than assuming.
ps - Never point a
package.jsonscript at something that calls the framework's adapter if that adapter runsbuilditself. That is an unbounded chain of builds. The Next.js guide has the specific rule.npm run build - Do not start the project's docker-compose stack to see how it works unless the user asks. Read the code.
框架构建开销较大,而一次迁移会执行许多次构建。
- 每次只运行一个 build 或 dev server,并在本轮结束前停止所有已启动的进程。使用 检查,不要凭空假设。
ps - 绝不要让 的
package.jsonscript 指向某个 adapter,而该 adapter 自身又会调用build。这会造成无限循环的构建链。Next.js 指南中有具体规则。npm run build - 除非用户明确要求,否则不要启动项目的 docker-compose 技术栈来了解其行为。请阅读代码。
Feedback
反馈
After every migration, report concrete friction with (usage above
and in ), one report per finding: what the source project used, what had
no equivalent, which rebuilt pattern you used, and what broke that the guide did not predict.
A missing capability is ; a wrong or unclear step in this skill is
. That is how the next guide gets written.
railcode agent-feedbackcreate-railcode-app--category suggestion--category friction每次迁移完成后,使用 (用法见上文及 )报告实际遇到的具体障碍,每个发现单独提交一份:源项目使用了什么、什么没有对应物、你采用了哪种重建模式,以及哪些问题超出了本指南的预期。缺失能力使用 ;本 skill 中错误或不清晰的步骤使用 。下一版指南将据此编写。
railcode agent-feedbackcreate-railcode-app--category suggestion--category friction