用途:面向已存在的 Twenty 应用,负责运营、排障与发布,即从“我已有应用”到“它在生产运行”之间的环节,包括同步应用改动、部署到生产、查看逻辑函数日志、切换或新增 Twenty 远程实例、配置 CI/CD、排查部署/同步/构建失败、卸载应用、运行测试以及手动执行逻辑函数。不适用于初始化新应用(用 create-app)、修改应用实体或代码(用 develop-app)、准备市场素材(用 publish-app)或查询工作区记录(用 use-twenty-mcp)。
必要前提:确认当前目录是 Twenty 应用,先执行 test -f package.json 与 test -f src/application-config.ts,并检查 sed -n '1,220p' package.json 与 yarn twenty remote:list。
远程管理:Remotes 指可同步或部署的 Twenty 服务器,凭据存于 ~/.twenty/config.json。常用命令包括 yarn twenty remote:add、yarn twenty remote:add --local、yarn twenty remote:add --url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as production、yarn twenty remote:list、yarn twenty remote:use <name>。涉及生产时先确认目标远程。
同步:使用有界 apply,即 yarn twenty apply,不要用 watch 模式的 yarn twenty dev;认证失败则重加或切换远程。
排查:按远程/认证、开发同步、构建打包、部署安装、运行时执行、CI/CD 环境逐层定位,收集 package.json、application-config.ts、remote:list 与 yarn twenty apply --verbose 等信息。运行时用 yarn twenty dev:function:logs 与 yarn twenty dev:function:exec -n <function-name> -p '{...}' 排查逻辑函数。
构建与部署:yarn twenty dev:build,随后 yarn twenty app:publish、yarn twenty app:publish --private --remote production、yarn twenty app:install --remote production。更新前需将 package.json 的 semver 版本严格提高,重复部署同版本会被拒绝。卸载需确认后再执行 yarn twenty app:uninstall。
CI/CD:检查 .github/workflows/,配置 TWENTY_DEPLOY_URL 与 TWENTY_DEPLOY_API_KEY,密钥应放仓库或 CI 密钥库,不得写入源码。测试方面,完整测试含集成测试会安装并卸载应用,需先启动隔离实例并运行 yarn twenty docker:start --test 与 TWENTY_API_URL=http://localhost:2021 yarn test;不要对 http://localhost:2020 的 dev 实例运行集成测试,仅单元测试无需覆盖 TWENTY_API_URL。部署、卸载、生产远程变更与生产同步属于外部可见操作,面向生产或可能影响用户数据时必须先获得明确确认。