App Display Name

One-sentence summary of what the app adds to Twenty.

What It Does

• Concrete user-facing capability.
• Concrete user-facing capability.
• Concrete user-facing capability.

What It Adds To Twenty

• Objects:
• Fields:
• Views and navigation:
• Page layouts:
• Front components:
• Logic functions:
• Skills and agents:
• Connections:

Requirements

• Twenty server/version requirement, if any.
• Third-party account or OAuth app requirements, if any.
• Required server variables or application variables.

Setup

1. Install or deploy the app.
2. Configure required variables.
3. Add any required connections.
4. Open the relevant Twenty view or app settings page.

Usage

Short workflow with concrete user actions and expected result.

Development

Commands for local setup, dev sync, tests, build, deploy, and publish.

Permissions And Data

What the app reads, writes, updates, deletes, and sends to third-party services.

Support

Support email, issue tracker, docs, terms, or website links.

写作原则是"准确、具体"：**不要在 README 中断言某个实体、工作流、权限、集成或市场能力存在，除非它在代码里真实存在**。面向的读者是安装与评估应用的人，而非原始实现者。

### 文案与表述红线

- 用平实的"产品语言"开篇，**先讲 workspace 能获得的结果**，而不是实现细节；
- 点名用户实际会交互的 Twenty 对象与视图；
- 配置变量用**精确的变量名**说明，不要口语化改写；
- 区分"服务器管理员设置"与"workspace 成员使用"两类流程；
- 涉及 OAuth 连接时，明确写出提供方的重定向 URI：`<SERVER_URL>/auth/apps/callback`；
- 权限要站在**用户风险**角度描述：读、创建、更新、软删除、销毁、第三方发送；
- 需要规避：营销空话；没有应用支撑的安全/合规/可用性/认证声明；含真实客户数据的截图与示例；API Key、OAuth 密钥、token、私有服务器 URL。

## 视觉素材：Logo 与截图规范

把市场和运行时的视觉素材统一放进 `public/`：

```text
public/
  logo.png
  screenshot-1.png
  screenshot-2.png
  screenshot-3.png

文件名使用稳定、具描述性的命名；Marketplace 视觉优先使用 PNG；只有当项目原本就保留可编辑美术源文件时才保留源文件。

Logo 要点：小尺寸下可辨识；使用简洁几何或产品化符号；除非品牌确有需要，避免文字堆叠；除非应用由 Twenty 官方拥有且确有此意，不要用 Twenty 的 Logo 冒充应用 Logo。

截图要点：必须在 yarn twenty apply 或 watch-mode 同步之后截取真实应用界面；优先覆盖最有价值的用户路径——应用列表/About 页、对象索引视图、记录页布局、前端组件界面、连接设置、AI Skill/Agent 行为；只使用种子或合成数据；除非有助于说明配置，隐藏浏览器装饰；严禁用生成的图片伪造产品截图——生成式视觉只可用于 Logo、示意图、空状态插画或概念素材。生成或编辑后的视觉，最终位图放入 public/ 并在 defineApplication() 中引用；若图片出现在 README Markdown 中，务必附带有用的 alt 文本。

元数据配置实战：一份可发布的 application-config.ts

参考文档给出的"上架前完整形态"如下（字段均已核对为 Skill 清单所要求的市场字段）：

export default defineApplication({
  universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
  displayName: APP_DISPLAY_NAME,
  description: APP_DESCRIPTION,
  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
  author: 'Your Company',
  category: 'Productivity',
  logoUrl: 'public/logo.png',
  screenshots: [
    'public/screenshot-1.png',
    'public/screenshot-2.png',
  ],
  websiteUrl: 'https://example.com',
  termsUrl: 'https://example.com/terms',
  emailSupport: '[e-mail]',
  issueReportUrl: 'https://github.com/org/app/issues',
});

几点补充：

• aboutDescription 只在"About 页必须与 npm README 不同"时才设置。多数情况下请让 README.md 保持唯一事实来源，Marketplace About 页会自动回落到 npm README 内容；
• 若应用要求特定 Twenty 服务器版本，在 package.json 的 engines.twenty 中声明（真实应用 exa 即声明 ">=2.19.0"）；若打算发布 npm，则加上 twenty-app 关键字；
• application-config.ts 是应用入口，调 defineApplication() 时传的应用标识、显示名、描述、默认角色与市场元数据，都会被实例读取（参见 how-apps-work.md 中的应用目录结构说明）。

校验：上线前的最后一轮自查

在认定 README 与视觉素材"完成"之前，先执行构建链验证：

yarn twenty apply
yarn twenty dev:build

yarn twenty apply 是开发阶段把变更同步到活动远程的标准方式——它一次完成构建、部署与安装，Twenty 实例会更新 schema、注册新对象与字段、挂载前端组件并激活逻辑函数；dev:build 对应 SDK 中的 dev:build [appPath] 命令（dev 命令注册）。随后逐项核对：

• 每个 logoUrl 与 screenshots 路径在 public/ 中都真实存在；
• README.md 的 Setup 步骤与实际变量、连接、命令一致；
• 打算发布 npm Marketplace 时，package.json 含 keywords: ["twenty-app"]；
• defineApplication() 元数据中没有任何占位 URL、占位支持邮箱、占位截图或占位条款；
• 截图为最新、可读，且不含密钥或真实个人数据；
• 公共资源在前端组件、逻辑函数、README 或市场元数据使用处均能正常渲染。

若视觉正确性至关重要，应在浏览器中实际运行应用并重新截取，而不是依赖可能过期的旧文件。

执行发布：命令语义与选项

发布命令的底层实现在 app 命令注册 与 deploy.ts 中：

# 发布到 npm（公开 Marketplace）
yarn twenty app:publish

# 用 npm dist-tag 发布（如 beta、next）
yarn twenty app:publish --tag <tag>

# 发布到某个 Twenty 实例的私有 registry
yarn twenty app:publish --private --remote <name>