teable-app-builder
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTeable App Builder (local workspace)
Teable App Builder(本地工作区)
A Teable app is a Next.js project that reads and writes a Teable project (base) through the
Teable SDK, hosted and published by Teable. Normally Teable's own agent (Cuppy) builds it in a
sandbox. This skill does the same work on the user's machine: you are the agent, the
CLI materializes everything the sandbox would have provided, and saves
versions back to Teable.
teableteable app pushYou run on the user's machine, not in that sandbox. There is no in-app chat around you: no
credential cards, no sandbox paths, no Teable-side preview you control. Where the sandbox would
show a card, ask the user in your own conversation; the a checkout gets is already
the local variant.
AGENTS.mdData questions (query records, change rows) go through the Teable MCP tools when they are
available; everything that produces files, touches git or needs the app checkout goes through
the CLI. Do not mix the two for the same job.
This skill covers only the local checkout. Two neighbouring jobs belong to the
skill: having Teable's own builder write or change the app from a prompt
(, no checkout involved), and work on the project itself
(creating tables, fields and views, imports, automations). Use it for the tables a new app needs.
teable-assistant-opsteable app create|update --promptTeable 应用是一个 Next.js 项目,通过 Teable SDK 读写 Teable 项目(base),并由 Teable 托管和发布。通常,Teable 自有的 Agent(Cuppy)会在沙箱中构建它。本 skill 会在用户的机器上完成同样的工作:你就是 Agent, CLI 会生成沙箱本应提供的全部内容,而 会将版本保存回 Teable。
teableteable app push你运行在用户的机器上,而不是沙箱中。周围没有应用内聊天:没有凭据卡片、没有沙箱路径,也没有由你控制的 Teable 端预览。沙箱本应显示卡片的地方,应在你自己的对话中询问用户;检出目录所获得的 已经是本地版本。
AGENTS.md数据问题(查询记录、修改行)在可用时通过 Teable MCP 工具处理;所有会生成文件、涉及 git 或需要应用检出目录的操作都通过 CLI 完成。不要对同一项工作混用两者。
本 skill 仅涵盖本地检出目录。两个相邻任务属于 skill:让 Teable 自有的 builder 根据提示词编写或修改应用(,不涉及检出目录),以及处理项目本身(创建表、字段和视图、导入、自动化)。新应用所需的表应由该 skill 创建。
teable-assistant-opsteable app create|update --promptPrerequisites
前置条件
- Node.js 22+, git and pnpm on PATH.
- The CLI: use when it is on PATH; otherwise run every command as
teable(no install step). The app checkout commands need a CLI whosenpx -y @teable/cli@latest <command>liststeable app --help.init - Sign-in happens once and you do it, not the user: when a command answers
, run
Authorization is required— it opens the browser, the user approves, done.teable auth loginshows the account and endpoint. Self-hosted Teable:teable auth statusor--endpoint <url>.TEABLE_ENDPOINT - The deployment has a git registry for app code (teable.ai does). Without it the CLI says so;
then the app is built in the in-app App Builder and gives a read-only copy.
teable app get-code
- Node.js 22+,且 和
git位于 PATH 中。pnpm - CLI:如果 已在 PATH 中,直接使用;否则,将每条命令都运行为
teable(无需安装步骤)。应用检出相关命令需要npx -y @teable/cli@latest <command>中列出teable app --help的 CLI。init - 登录只需执行一次,而且由你执行,而不是用户:当命令返回 时,运行
Authorization is required——它会打开浏览器,用户批准后即完成。teable auth login会显示账户和端点。对于自托管 Teable:使用teable auth status或--endpoint <url>。TEABLE_ENDPOINT - 部署环境需要为应用代码提供 git registry(teable.ai 具备该能力)。如果没有,CLI 会明确提示;此时应用将在应用内 App Builder 中构建,而 提供只读副本。
teable app get-code
1. Resolve the project (base) first
1. 首先解析项目(base)
Every app belongs to one project. First read what the user is asking for:
- Building on data they already have ("an app for my inventory table", a pasted URL, a project name) → find that project (below).
- A new system from scratch ("make me a CRM", "build a booking app") with nothing pointing
at existing data → usually a new project: , then create the tables the app needs and
teable base create --space-id spc… --name "<name>". A request like this is not a reason to drop tables into some unrelated project the user happens to have.teable link <baseId> - Unclear → ask once, offering the close existing projects and "a new project" side by side.
Finding an existing project, most specific first:
- Explicit: a Teable URL (take the id from it), an id, or a name →
bse…. One hit: use it. Several: ask the user which.teable base list --search "<name>" - Directory binding: the current directory (or a parent) holds (an app checkout) or
.teable/app.json(.teable/cli/config.json). Commands run there need noteable link.--base-id - Ask: without arguments lists the projects the account can use. Show the candidates and ask once; then
teable link.teable link <baseId>
Creating a project is visible to everyone in that space, so say where it goes before or as you
do it ("creating project CRM in space Sales"). The space: the one the user named; else the
only one they have (spaces show up in ); else the obvious one from context;
otherwise ask, together with any other open question rather than as a separate round. Don't
stop to ask about anything you can reasonably decide and mention instead.
teable base listTables need no choosing: the checkout receives for every table of the project.
schema/*.json每个应用都属于一个项目。首先阅读用户的需求:
- 基于已有数据构建(“为我的库存表创建一个应用”、粘贴的 URL 或项目名称)→ 找到该项目(见下文)。
- 从零构建新系统(“帮我做一个 CRM”、“构建一个预订应用”),且没有任何内容指向现有数据 → 通常应新建项目:,然后创建应用需要的表并执行
teable base create --space-id spc… --name "<name>"。此类请求并不意味着应把表放进用户恰好拥有的某个无关项目中。teable link <baseId> - 需求不明确 → 询问一次,并同时提供最接近的现有项目和“新建项目”两个选项。
查找现有项目时,按以下顺序从最具体到最宽泛:
- 明确指定:Teable URL(从中获取 id)、id 或名称 →
bse…。命中一个则使用;命中多个则询问用户选择。teable base list --search "<name>" - 目录绑定:当前目录(或父目录)中包含 (应用检出目录)或
.teable/app.json(.teable/cli/config.json)。在此处运行的命令无需teable link。--base-id - 询问:不带参数运行 会列出账户可用的项目。展示候选项并询问一次;随后执行
teable link。teable link <baseId>
在某个 space 中创建项目对该 space 中的所有人都可见,因此应在执行前或执行时说明创建位置(“正在 space Sales 中创建项目 CRM”)。space 的确定方式:用户指定的;否则使用其唯一的 space(space 会显示在 中);否则根据上下文选择明显的 space;其他情况下,应将这个问题与其他尚未解决的问题一并询问,而不是另起一轮。不要停下来询问任何你可以合理决定的事项,只需说明你的决定。
teable base list表无需选择:检出目录会收到项目中每个表的 。
schema/*.json2. Create or clone the checkout
2. 创建或克隆检出目录
bash
teable app init --name "<App name>" --dir ./<dir> # new app, scaffold as version 1
teable app clone --app-id app… --dir ./<dir> # existing app (ids from `teable app list`)Which app: the one the user named or linked. Otherwise run first. Several
apps and no name → ask which one. A request for a new app when a similar one already exists →
ask once whether to change that one or start a new one; do not pick silently.
teable app listBoth leave a git checkout whose remote is the app repository, plus:
teable| File | Purpose |
|---|---|
| The platform's instructions for this app: stack, scaffold map, locked files, data rules, credential rules. Read it before writing code. |
| Platform variables (API URL, app token, app and project ids, AI gateway). Never edit or commit; |
| SDK usage and the current table schemas. Regenerated by |
| Workspace marker (app, project, endpoint). Gitignored; do not edit. |
Then , , (port 3000) and build. is authoritative
for conventions; this skill only covers the workflow around it.
cd <dir>pnpm installpnpm devAGENTS.mdbash
teable app init --name "<App name>" --dir ./<dir> # new app, scaffold as version 1
teable app clone --app-id app… --dir ./<dir> # existing app (ids from `teable app list`)选择应用:用户指定或已关联的应用。否则先运行 。如果有多个应用但未指定名称,询问用户选择。如果用户要求创建新应用,但已经存在类似应用,则询问一次是修改现有应用还是创建新应用;不要默默替用户选择。
teable app list两种命令都会生成一个 git 检出目录,其名为 的 remote 是应用仓库,此外还会得到:
teable| 文件 | 用途 |
|---|---|
| 平台针对此应用的说明:技术栈、脚手架结构映射、锁定文件、数据规则和凭据规则。编写代码前先阅读。 |
| 平台变量(API URL、应用 token、应用和项目 id、AI gateway)。切勿编辑或提交; |
| SDK 用法和当前表结构。由 |
| 工作区标记(应用、项目、端点)。由 Git 忽略;不要编辑。 |
然后执行 、、(端口 3000)并构建。 是约定规范的权威来源;本 skill 仅涵盖其外围的工作流程。
cd <dir>pnpm installpnpm devAGENTS.md3. Work, then push
3. 开发,然后推送
bash
teable app pull # start of a session, or when tables/app may have changedbash
teable app pull # start of a session, or when tables/app may have changed... edit, verify with curl -s http://127.0.0.1:3000 ...
... edit, verify with curl -s http://127.0.0.1:3000 ...
teable app push -m "<what changed>" # commit (if needed), pre-check, push, record a Teable version
`push` refuses when platform-owned files changed, when a `.env` file is tracked, when
`teable/queries.yaml` is invalid, or when the app repository moved ahead (then `teable app pull`,
resolve, push again). On success Teable records the version under the user's name, refreshes a
running preview and notes the push in the app chat. A plain `git push` does not create a version.
`clone` and `pull` also bring the checkout to what the Teable sandbox would run: they rewrite the
platform's own files and apply pending template upgrades to an older app (Next 16 `proxy.ts`,
`pnpm-workspace.yaml`, …). On a clean tree that lands as its own commit ("Upgrade app template" or
"Sync platform files"), pushed with your next `teable app push`; check `notes` in the output for
anything left to do by hand.
`pull` reports table-schema changes since the last sync ("field added", "type changed", …) and
pending named-query repairs. Adjust code for the changes; review repairs with
`teable query repairs` and `teable query repair-apply --repair-id <id>` (details in
`references/workflow.md`).teable app push -m "<what changed>" # commit (if needed), pre-check, push, record a Teable version
如果平台所有的文件发生更改、`.env` 文件被 Git 跟踪、`teable/queries.yaml` 无效,或者应用仓库已向前移动,`push` 都会拒绝执行(后一种情况下,先执行 `teable app pull`,解决冲突后再次推送)。成功后,Teable 会以用户名记录该版本,刷新正在运行的预览,并在应用聊天中注明此次推送。普通的 `git push` 不会创建版本。
`clone` 和 `pull` 还会将检出目录同步到 Teable 沙箱本应运行的状态:它们会重写平台自身的文件,并为旧应用应用待处理的模板升级(Next 16 的 `proxy.ts`、`pnpm-workspace.yaml` 等)。在干净的工作树上,这会形成一个独立提交(“Upgrade app template”或“Sync platform files”),并随下一次 `teable app push` 一起推送;检查输出中的 `notes`,了解是否还有需要手动处理的事项。
`pull` 会报告自上次同步以来的表结构变更(“field added”、“type changed”等)和待处理的命名查询修复。根据这些变更调整代码;使用 `teable query repairs` 审查修复,并通过 `teable query repair-apply --repair-id <id>` 应用修复(详细信息见 `references/workflow.md`)。4. Publish, inspect, roll back
4. 发布、检查与回滚
bash
teable app publish --wait # only when the user asks; streams build steps, prints the URL
teable app versions --app-id app… # history
teable app rollback --app-id app… --to <n> # restores as a new version; then `teable app pull`bash
teable app publish --wait # only when the user asks; streams build steps, prints the URL
teable app versions --app-id app… # history
teable app rollback --app-id app… --to <n> # restores as a new version; then `teable app pull`Rules that keep the checkout valid
保持检出目录有效的规则
- Never edit the locked files lists (
AGENTS.md,lib/teable.ts,lib/credentials.ts, reporters, beacon route, …): the platform rewrites them.next.config.mjs - Never ask the user to paste a secret into the chat, and never pass yourself. The user runs
--valuein a terminal window of their own (not viateable secret set --key <KEY> --grant app:<appId> --dev-envin Claude Code: no TTY there): it prompts for the value without echo, stores it as their personal secret granted to the app, and writes the same key to the checkout's!for.env.local.pnpm dev - An app that reads a third-party service (Stripe, HubSpot, Gmail…) gets a connection, not an
API key, whenever one exists: finds it,
teable integration search --query "<task>"opens the consent screen, thenteable integration connect --toolkit <slug> --wait. A toolkit that takes an API key prompts for it in the terminal, so the user runs that command themselves in a terminal window of their own — not via Claude Code'steable secret grant --type connection --id <connectionId> --resource app:<appId> --alias <ALIAS>prefix, which has no TTY, so the prompt cannot read the value. AGENTS.md has the runtime helpers (!,getConnectionToken); both work undercallConnection.pnpm dev - Login flows redirect to the Teable preview origin, not localhost: verify them after a push in the app's Preview panel in Teable.
- Keep commits user-facing: one commit per completed request, subject under 72 characters, no
/
feat:prefixes.fix: - Codex: the first and CLI network calls need network approval.
git push
See for the end-to-end script and for what
goes wrong and how to recover.
references/workflow.mdreferences/pitfalls.md- 绝不编辑 列出的锁定文件(
AGENTS.md、lib/teable.ts、lib/credentials.ts、reporters、beacon route 等):平台会重写这些文件。next.config.mjs - 绝不要让用户在聊天中粘贴 secret,也绝不要自行传入 。用户需要在自己的终端窗口中运行
--value(不要通过 Claude Code 中的teable secret set --key <KEY> --grant app:<appId> --dev-env运行:那里没有 TTY):该命令会在不回显的情况下提示输入值,将其保存为授予该应用的个人 secret,并把同一个 key 写入检出目录的!,供.env.local使用。pnpm dev - 如果应用要读取第三方服务(Stripe、HubSpot、Gmail 等),只要存在相应连接,就应使用连接而不是 API key:查找连接,
teable integration search --query "<task>"打开授权界面,然后执行teable integration connect --toolkit <slug> --wait。需要 API key 的 toolkit 会在终端中提示输入,因此用户必须在自己的终端窗口中运行该命令,而不是使用 Claude Code 的teable secret grant --type connection --id <connectionId> --resource app:<appId> --alias <ALIAS>前缀;后者没有 TTY,提示无法读取该值。!提供了运行时辅助函数(AGENTS.md、getConnectionToken);两者在callConnection下均可正常工作。pnpm dev - 登录流程会重定向到 Teable 预览源,而不是 localhost:推送后,应在 Teable 的 Preview 面板中验证登录流程。
- 保持提交面向用户:每个已完成请求对应一个提交,主题行少于 72 个字符,不使用 /
feat:前缀。fix: - Codex:首次 和 CLI 网络调用需要网络访问批准。
git push
有关端到端脚本,请参阅 ;有关常见问题及恢复方法,请参阅 。
references/workflow.mdreferences/pitfalls.md