manage-app

适用场景

当用户希望操作、排查问题或发布现有的 Twenty 应用时，选择此技能——涵盖从“我有一个应用”到“它已在生产环境运行”之间的所有事项。典型请求包括：

• “将我的应用更改同步到服务器”
• “将我的 Twenty 应用部署到生产环境”
• “查看我的逻辑函数日志”
• “切换到另一个 Twenty 远程服务 / 实例”
• “为预发布环境添加一个远程服务”
• “为我的 Twenty 应用设置 CI/CD”
• “排查部署 / 同步 / 构建失败的问题”
• “从生产环境卸载我的应用”
• “为我的 Twenty 应用运行测试”
• “手动运行我的逻辑函数进行测试”

不要使用此技能来搭建应用脚手架（使用 create-app）、更改应用实体或代码（使用 develop-app）、准备市场素材（使用 publish-app）或查询工作区记录（使用 use-twenty-mcp）。

边界

有关 Twenty 应用的运作方式——SDK 包、远程服务、同步生命周期和渲染模型——请阅读 ../../references/concepts/how-apps-work.md。适用于所有 Twenty 应用任务的跨技能操作规则位于 ../../references/concepts/operating-rules.md；这些规则具有权威性，不会在每个技能中重复说明。

不要在此处搭建新应用脚手架。应用不存在时，请使用 $create-app。

不要在此处添加或修改应用实体。对象、字段、逻辑函数、角色、视图、导航、页面布局、技能、Agent、连接提供方、前端组件注册和设置菜单项，请使用 $develop-app。

不要在此处准备市场 README、截图、徽标或 npm 列表文案。公开列表相关工作请使用 $publish-app。

不要在此处检索 CRM 记录。检索工作区数据请使用 $use-twenty-mcp。

操作规则

首先确认当前目录是 Twenty 应用：

test -f package.json
test -f src/application-config.ts

运行操作命令前，检查当前应用和脚本：

sed -n '1,220p' package.json
twenty remote list

部署、卸载、更改生产环境远程服务以及同步到生产环境都属于对外可见的操作。如果目标是生产环境，或可能影响用户数据，运行这些操作前必须征得用户明确确认。

有关命令详情、远程服务、验证命令语义、同步模式、故障排查、构建、部署、日志、exec 和 CI/CD，请阅读 ../../references/manage-app/cli-and-sync.md。

如果用户要求运行测试，运行任何测试命令前还要阅读 ../../references/develop-app/tests.md。完整测试套件包含集成测试，会在目标服务器上安装和卸载应用，因此请启动或确认隔离的测试实例，并运行：

docker start twenty-app-dev-test
TWENTY_API_URL=http://localhost:2021 yarn test

除非用户明确指定该目标，否则不要对 http://localhost:2020 上的开发实例运行集成测试。如果用户只要求单元测试，请使用包的单元测试脚本，无需覆盖 TWENTY_API_URL。

远程服务

远程服务是应用可以向其同步或部署的 Twenty 服务器。凭据由独立 CLI 管理。使用 twenty auth login 和 twenty remote list。

常用命令：

# Add a remote interactively.
twenty auth login

# Connect to a local Twenty server.
twenty auth login --url http://localhost:2020

# Add a remote non-interactively.
printf '%s' "$TWENTY_API_KEY" | twenty auth login --with-token --url https://your-twenty-server.com --name production

# List configured remotes.
twenty remote list

# Switch the active remote.
twenty remote use <name>

当用户提到“prod”“production”或“workspace de prod”时，请在同步或部署前确认目标远程服务。如果目标缺失，请使用 --as production 或用户提供的名称添加。

开发同步

始终使用有边界的 apply，将应用更改同步到当前远程服务：

twenty app apply

不要使用不带参数的 twenty app dev（监视模式）。每次需要同步更改时，都运行 twenty app apply。

有边界的 apply 需要经过身份验证的远程服务。如果身份验证失败，请重新添加或切换远程服务，然后重试。

故障排查

首先确定发生故障的层级：

• 远程服务／身份验证。
• 开发同步或有界应用。
• 构建／软件包生成。
• 部署／上传／安装。
• 运行时函数执行。
• CI/CD 环境或密钥。

更改配置前，收集最少但有用的上下文：

sed -n '1,220p' package.json
sed -n '1,220p' src/application-config.ts
twenty remote list
twenty app apply --json

远程服务或身份验证问题：

• 检查当前使用的远程服务是否为预期的工作区或服务器。
• 对于本地应用开发服务器，重新运行 twenty auth login --url http://localhost:2020。
• 对于远程服务，重新运行 twenty auth login --url <url> --name <name>。
• 确认目标 URL 后，再覆盖生产环境的远程服务。

同步问题：

• 优先使用 twenty app apply --json，以获取范围明确的故障信息。
• 编辑应用实体前，先检查生成的类型或架构错误。
• 如果应用依赖已更改的数据模型，请使用 $develop-app 修复实体定义。

构建或部署问题：

• 运行 twenty app publish --private 或 twenty app publish 前，先运行 twenty app build。
• 更新已部署的应用时，检查 package.json 中的版本。
• 涉及生产环境时，使用 twenty app publish --private --remote <name> 确认目标，而不要依赖当前使用的远程服务。

运行时行为问题：

• 使用 twenty app logs 检查函数执行日志。
• 使用 twenty app exec --name <function-name> --payload '<json>'，通过受控的载荷复现逻辑函数。

CI/CD 故障：

• 检查 .github/workflows/。
• 确认运行器可以访问 TWENTY_DEPLOY_URL 指向的服务器。
• 确认 TWENTY_DEPLOY_API_KEY 已配置为密钥，而非提交到了源代码中。

构建和部署

用户要求确认是否已做好发布准备，或正在排查软件包问题时，应先构建再部署：

twenty app build

将应用发布到 npm，或私下发布到已配置的 Twenty 服务器注册表：

twenty app publish
twenty app publish --private --remote production
twenty app install --remote production

部署更新前，检查 package.json 中的 version 是否严格高于当前已部署版本。重复部署相同版本会被拒绝。私下发布后，如果目标工作区需要使用该版本，请通过 twenty app install 安装已部署的版本。

如果用户需要发布到 npm 市场、撰写列表文案、制作截图或准备公开应用商店元数据，请改用 $publish-app。

日志、执行和清理

在已连接的服务器上排查运行时行为时，使用函数日志：

twenty app logs
twenty app logs --name <function-name>

在不触发触发器的情况下手动运行逻辑函数，以测试其行为：

twenty app exec --name <function-name>
twenty app exec --name <function-name> --payload '{"key":"value"}'

仅在确认后卸载：

twenty app uninstall
twenty app uninstall --yes

CI/CD

使用 twenty app init 生成的应用可以通过 GitHub Actions 进行 CI 和 CD。配置部署自动化时，请检查应用的 .github/workflows/ 文件，并配置：

• TWENTY_DEPLOY_URL
• TWENTY_DEPLOY_API_KEY

不要将 API 密钥放入源文件中。请使用代码仓库或 CI 密钥存储。