Twenty 应用脚手架模板 README 详解：从 create-twenty-app 生成到 npm 可信发布

本文以 create-twenty-app 脚手架内置的应用模板 README 为骨架，逐节解读一个新建 Twenty 应用工程文档的组织方式：Features、Getting started（本地开发环境搭建）、Publishing（基于 npm trusted publishing 的带来源证明发布）、Changelog 四个章节各自对应的工程文件与命令，并结合仓库中的脚手架源码（目录复制、dotfiles 改名、UUID 生成、package.json 改写）与 GitHub Actions 工作流，说明这套模板从脚手架落地到发布 npm 的完整链路。读完后，你能独立复现一个可发布 Twenty 应用工程，并理解其 CI/CD 与发布流程的每个配置项。

模板 README 的位置与生成机制

模板 README 位于 packages/create-twenty-app 包的 src/constants/template/ 目录下，它不是一份静态文档，而是 create-twenty-app CLI 创建应用时整体复制到用户目录的模板文件之一。同目录下的 SETUP.md、CHANGELOG.md、package.json、AGENTS.md 以及 src/、public/、github/workflows/ 等文件共同构成一个可运行的最小应用骨架。

从 脚手架源码 可以看到，执行 create-twenty-app 后的核心步骤依次是：创建项目目录、调用 copyBaseApplicationProject 拷贝模板、安装依赖、初始化 Git。而模板拷贝的细节实现在 app-template.ts：

1. 整目录复制：fs.copy 将 template/ 全量复制到目标目录；
2. dotfiles 改名：由于 npm 发布包时会剥离点文件，模板中 .gitignore、.github/、.yarnrc.yml 在仓库里以 gitignore、github、yarnrc.yml 的无点形式存放，复制后再统一改回带点名称（见 renameDotfiles）；
3. 生成唯一标识：将 src/constants/universal-identifiers.ts 中的 DISPLAY-NAME-TO-BE-GENERATED、DESCRIPTION-TO-BE-GENERATED、UUID-TO-BE-GENERATED（每个占位符替换为新的 UUID v4）替换为实际应用值；
4. 改写 package.json：把包名 TO-BE-GENERATED 换成应用名，并将 twenty-sdk、twenty-client-sdk 的版本锁定为 create-twenty-app 自身版本（见 updatePackageJson）。

模板 README 因此是「每个新应用出生时自带的第一份文档」，它约定了应用工程后续应维护的四类内容。

章节一：Features —— 应用功能清单

模板要求开发者用一两句话描述应用，并列出核心功能（Feature one / two / three 为占位项）。这一节没有对应代码，纯粹是面向应用市场或协作者的说明性内容，但它是发布到 Twenty 应用市场前最基本的自述材料。

章节二：Getting started —— 本地开发环境搭建

README 将安装说明外置到 SETUP.md，模板中的 SETUP.md 给出了完整的本地运行步骤，这也是脚手架跑通后的实际验证路径。

前置条件

• Node.js（模板 package.json 中 engines 声明为 ^24.5.0，npm 字段写死 please-use-yarn，yarn 要求 >=4.0.2，即强制使用 Yarn 4）；
• Docker（用于拉起本地 Twenty 服务器）。

操作步骤

# 1. 安装依赖
yarn install

# 2. 启动本地 Twenty 服务器（Docker）
yarn twenty docker:start
# 随时可用 yarn twenty docker:status 查看状态

# 3. 启动开发服务器并同步应用
yarn twenty dev

然后打开 http://localhost:2020，使用默认开发账号 [e-mail] / [e-mail] 登录。

这里与脚手架行为可以互相印证：create-twenty-app 在交互流程中已经会自动完成「启动 Docker 服务 → 认证（开发 API key，即 [e-mail] 对应凭证）→ 执行 yarn twenty dev --once 同步应用 → 打开应用欢迎页」的链路，见 create-app.command.ts 的 execute 流程 与 syncApplication。也就是说 SETUP.md 是 CLI 自动化流程失败时的手动兜底路径。

工程自检命令

模板 package.json 的 scripts 定义了四个常用脚本，SETUP.md 将其归纳为「验证环境是否搭好」的检查清单：

脚本	命令	用途
yarn lint	oxlint -c .oxlintrc.json .	使用 oxlint 做静态检查
yarn typecheck	tsgo --noEmit -p tsconfig.spec.json	基于 TypeScript native preview 做类型检查
yarn test:unit	vitest run --config vitest.unit.config.ts	仅跑单元测试（vitest.unit.config.ts）
yarn test	vitest run	跑集成测试，需要连到 Twenty 实例

模板的 application-config.test.ts 与 schema.integration-test.ts 就是这两类测试的基线示例。

章节三：Publishing —— 基于 npm trusted publishing 的发布

这是模板 README 中最具技术含量的部分。README 指出：Publish 工作流（.github/workflows/publish.yml）会把应用发布到 npm 并附带来源证明（provenance），依赖 npm trusted publishing 机制（原文档中的外部链接）。对应到仓库文件即 publish.yml，其完整配置为：

name: Publish

on:
  push:
    tags:
      - 'v*'
  workflow_dispatch:

permissions:
  contents: read
  # Required for npm trusted publishing (OIDC provenance).
  id-token: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 24
          registry-url: https://registry.npmjs.org

      - name: Update npm
        # Trusted publishing requires npm 11.5.1 or later.
        run: npm install -g npm@latest

      - name: Install dependencies
        run: yarn install --immutable

      - name: Publish to npm
        # Uncomment if publishing from a private source repo: npm rejects
        # OIDC provenance for private repos
        # env:
        #   TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'
        run: yarn twenty app:publish

对照 README 中的发布步骤，逐项解读：

第 1 步：在 npmjs.com 注册可信发布源。在包的 Settings > Trusted Publisher 页面把该仓库与 publish.yml 工作流登记为可信发布源。这正是工作流里 permissions: id-token: write 的用途——OIDC token 让 npm 校验「这次发布请求确实来自 GitHub Actions 的某条可信工作流」，全程无需保存 NPM_TOKEN。工作流注释中明确写出这是 "Required for npm trusted publishing (OIDC provenance)"。

第 2 步：打版本 tag 或手动触发。两个触发器与之对应：push: tags: 'v*'（例如 git tag v1.0.0 && git push --tags）和 workflow_dispatch（Actions 页面手动运行）。发布命令是 yarn twenty app:publish，yarn install --immutable 保证依赖锁文件不被修改，npm install -g npm@latest 则是因为可信发布要求 npm 11.5.1 及以上版本。

私有仓库的特殊处理：工作流注释提示，若应用源码仓库为私有，需取消 TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true' 的注释——因为 npm 不接受来自私有仓库的 OIDC provenance，此时只能关闭来源证明发布。

Provenance 与所有权声明：README 最后强调，provenance 证书的是「这个 npm 包由哪个 GitHub 仓库构建」，这同时也是在 Twenty 应用市场（marketplace）申请认领应用时证明所有权的方式——认领流程会校验你拥有 provenance 所指向的 GitHub 账号或组织（publish.yml 头部注释 对此有同样说明）。

章节四：Changelog 与 Learn more

模板 CHANGELOG.md 初始化时只有一条记录：0.1.0 - Initial application scaffolded with create-twenty-app，与 package.json 中初始 "version": "0.1.0" 对应，约定后续每次发版在文件内追加变更说明。

Learn more 部分在仓库内的对应资源包括：

• 应用开发文档：本仓库 packages/twenty-docs/developers/extend/ 下收录了完整的 Twenty Apps 开发文档（.mdx），其中 应用扩展总览目录 覆盖 config、data、logic、layout、operations 各主题；
• 可参考的完整示例：postcard 示例应用 是功能最齐全的参考工程（含 e2e/、CLAUDE.md、完整 src/ 布局），模板 AGENTS.md 也将其列为 rich app example；
• 实体生成命令：模板 AGENTS.md 列出了 yarn twenty dev:add <entity> 全量命令表（object、field、logicFunction、frontComponent、role、view、navigationMenuItem、pageLayout 等 15 类实体），是开发阶段替代手写骨架的标准做法。

配套 CI/CD：模板自带的质量与部署工作流

README 只直接引用了 publish.yml，但模板 github/workflows/ 目录还内置了两个工作流，构成完整的工程闭环，简要说明其与文档章节的关系：

• ci.yml：在 push 到 main 或 PR 时，先用 spawn-twenty-app-dev-test action 拉起一个测试用 Twenty 实例（TWENTY_VERSION: latest），再依次执行 yarn lint、yarn typecheck、yarn test:unit、yarn test（后者注入 TWENTY_API_URL 与 TWENTY_API_KEY）——这正对应 SETUP.md 中「Verifying your setup」四条命令在云端的重放；
• cd.yml：push 到 main 或 PR 打上 deploy 标签时，通过 deploy-twenty-app / install-twenty-app action 将应用部署并安装到 TWENTY_DEPLOY_URL（默认 http://localhost:2020，可用仓库 secret TWENTY_DEPLOY_API_KEY 指向远端实例），实现「合入即部署」的持续交付。

小结

模板 README 虽然只有几十个词，但它锚定了 create-twenty-app 脚手架产出工程的全部关键文档面：

1. Features：面向市场与协作者的功能自述；
2. Getting started → SETUP.md：Node 24 + Yarn 4 + Docker 的本地环境，yarn twenty docker:start / yarn twenty dev 两步启动，lint / typecheck / test:unit / test 四道自检；
3. Publishing → publish.yml：npm trusted publishing（id-token: write + npm ≥ 11.5.1 + v* tag 触发），provenance 同时服务供应链溯源与 marketplace 所有权认领；
4. Changelog / Learn more：版本变更记录起点与官方文档、示例应用的入口。

配合 ci.yml、cd.yml 两个内建工作流，新建的 Twenty 应用在 git tag v1.0.0 之后即可走通「CI 质量门禁 → 部署 → 带来源证明发布」的完整交付链路。