fcode-ama

Factorial Code — 平台指南（AMA）

Factorial Code（fcode）是 Factorial 的平台，用于基于 Factorial Public API 构建应用和自动化。本技能涵盖平台的使用方式——从申请访问权限到发布 Marketplace 应用的整个过程，以及在协助用户使用平台时应如何应对。至于应用本身的构建（流程、模块、CLI、表单），请转到负责这些内容的技能（参见下方的路由表）。

完整的分阶段指南见 references/journey.md；常见问题及其解决方法见 references/troubleshooting.md。

你正在帮助谁

有三种用户角色会使用该平台。请尽早确认你正在与哪种角色交流——不同角色的若干流程有所不同：

角色	用户	主要区别
Factorial 内部人员	Factorial 的开发者	在 Factorial Backoffice 中创建自己的 OAuth 应用；直接创建演示公司（使用 Demo generator）；可使用 Slack 频道 #factorial-code-users
合作伙伴	使用 Factorial 构建应用或集成的外部公司	OAuth 应用由管理员预先配置；可按需申请演示公司
个人贡献者	构建自己的应用或自动化的人员（可能是客户，但不一定——绝不能将此角色称为“终端客户”）	与合作伙伴相同

所有角色都通过 Public API 与 Factorial 交互，并且都属于一个开发团队：团队创建的每个应用都会与所有成员共享。当有人申请访问权限，而管理员发现其组织已在平台上拥有团队时，便会将其加入该现有团队。

支持人员行为准则

• 仅依据已记录的流程作答——本技能、相关参考资料、其他 fcode-* 技能以及公开文档。绝不编造 UI 元素、URL、命令或政策。若文档未涵盖，请如实说明并升级处理。
• 当答案因用户角色而异时，先确认用户角色。
• 按页面和版块名称描述流程（例如“App 详情页上的 Getting started 检查清单”），不要描述具体按钮的位置——标签可能会变化，流程则较为稳定。
• 管理员操作：只说明结果。 如果某个步骤由管理员执行（访问权限审批、演示环境配置、OAuth 预配置、发布审核），请告知用户会看到什么以及接下来该做什么。绝不描述管理员一侧的操作机制或凭证的交付方式。
• 使用用户所用的语言作答。
• 深入解答前先查阅文档。 如果可以访问网络，请在回答详细问题前阅读链接中的文档页面；具体细节以最新文档为准，而非本技能。无法访问网络时，请依据本技能作答，并指出可进一步查阅的文档页面。
• 必要时升级处理——例如涉及管理员操作、请求卡住或问题未涵盖的情况。升级途径见最后一节。

平台地图

所有内容都位于 https://code.factorialhr.com 下，分为三个用户经常混淆的界面：

• 文档（/docs/...）— 公开文档，以及包含访问申请表单的落地页。
• 应用控制台（/dashboard/...）— 应用、团队、演示公司、市场、安装。下文介绍的流程就在此处进行。
• 工作区控制台（/platform/...）— 工作区内的流程、执行、计划、变量、版本、API 凭证。应用控制台会链接到此处——每个此类跳转都标记为 “在平台中打开”；对于 deploy-（安装）工作区，会跳转到执行页面。

应用控制台区域（侧边栏将它们分为 构建、运营 和 管理 部分）：

区域	用途
应用	团队的应用；在此创建新应用
应用详情页	单个应用的主页：入门清单以及 开发 / 生产 / 发布 / README 标签页
应用设置	配置（市场可见性、生命周期）和 OAuth（请求的范围以及开发和生产凭证）
演示公司	用于测试安装的 Factorial 演示公司
测试市场	在演示公司中运行的生产市场模拟环境

此外还有介绍清晰的 市场、团队 和 安装 区域。

流程概览

#	阶段	位置	操作
1	申请访问权限	落地页 → 访问申请表单	管理员审核后会通知你；如果有匹配的现有开发团队，你将加入该团队
2	创建应用	应用 → 创建	名称和用途；语言（JavaScript 或 Python）；OAuth 范围；是否启用 集成框架（判断规则见 references/journey.md）
3	入门	应用详情页清单	按顺序完成设置步骤：在本地构建、关联 Factorial 集成（仅限框架应用）、配置 OAuth（请求了范围时）、发布版本、添加市场元数据
4	配置 OAuth	应用设置 → OAuth 标签页	为 OAuth 流程配置各环境的客户端凭证（按角色设置见 references/journey.md）
5	本地构建	你的计算机	安装 CLI，使用 fcode clone 克隆开发工作区（或使用 fcode team:clone 一次性克隆团队的所有应用），使用你自己的 Agent 和 fcode-* 技能编写代码，在本地测试，然后运行 fcode push
6	演示公司	演示公司页面	内部人员：直接创建。合作伙伴/IC：提交申请；你会收到邮件通知
7	测试安装	测试市场	使用演示公司的凭证运行真实 OAuth 流程，安装，然后在演示公司的 Factorial 中测试 appRole 表单和任何 UI 触发按钮
8	发布版本	应用详情 → 生产标签页	申请发布版本（semver + 说明）；验证通过后，将其提升到生产工作区——由所属团队的 Factorial 管理员自行操作，否则由运营人员操作（references/journey.md §8）
9	发布列表	应用详情 → 发布标签页	市场列表元数据：关联的 DatoCMS 记录和/或备用字段
10	生产环境	市场	应用将公开显示并可供安装；每次安装都会获得独立的隔离工作区

各阶段详情、按角色划分的说明和生命周期状态：references/journey.md。

旅程背后的工作区

命名注意事项：Factorial Code 工作区在工作区控制台、平台 API 和少数 CLI 界面（“团队变量”、parentTeams 字段）中也称为“团队”——这与上文所述由人组成的开发团队无关。CLI 的 fcode team:* 命令指的是开发团队：它们会操作该团队拥有的每个 App（参见 fcode-cli）。

每个 App 都映射到多个工作区（slug 中包含编码后的令牌，而不是原始 id）：

• dev-{appId} — 开发工作区，可在其中克隆和推送。
• prod-{appId} — 生产副本，在首次请求发布时创建。应将其中的代码视为只读——更改应在 dev 中进行，并通过发布流程送达；只有运维人员和该 App 的 Factorial 团队管理员可以写入。其变量是实时生效的——所有安装共用的默认值和凭据都在此管理。
• deploy-{installationId} — 每个公司安装各有一个，继承自 App 工作区：其中仅保存该公司的变量和执行记录，与其他公司完全隔离。父工作区中的更改会自动应用到每个安装工作区。
• base-app / base-integration-app（语言对应的变体，-js/-py）— 所有 App 都会继承的共享基础：API 客户端、webhook/计划任务/邮件/表单辅助工具，以及（对于框架 App）集成模板。

已发布的版本使用固定标签，stable 别名指向当前版本（模型见 fcode-core-concepts）。对于 marketplace App，请通过发布流程（第 8 阶段）发布——不要手动发布版本或移动 stable。

Factorial 中的按钮 — UI 触发器

除了表单和 webhook，已安装的 App 还可以在 Factorial 页面上放置自己的按钮。Factorial 团队会在产品中声明位置（例如页面标题栏、操作下拉菜单，如 calendar.header.admin）；声明了该位置 uiTrigger 的 App 流程会以按钮形式显示在那里，使用 App 的标签和图标，供安装了该 App 的每家公司使用。点击按钮后，会使用页面上下文（屏幕上显示的记录、公司）运行流程；如果流程有表单，则会打开该表单。因此，“同步到 Acme”操作可以显示在 Factorial 原生操作旁边，无需 Factorial 为特定集成提供专属 UI。

应向用户说明：

• 仅适用于已安装的 marketplace App——按钮从公司的 deploy- 工作区读取，因此触发器会像其他更改一样，通过发布流程（第 8 阶段）送达客户；在开发阶段，演示公司会显示 dev 工作区的触发器（第 7 阶段）。
• 位置 id 由 Factorial 提供：平台中没有目录。开发者若想在尚无位置的页面上添加按钮，需要联系负责该页面的 Factorial 团队添加位置——应将其作为产品需求上报。
• 有些位置一次只允许一个 App；如果安装的第二个 App 声明了此类位置，安装会失败，并显示一条指出第一个 App 的消息。
• 配置位于流程页面（从 Factorial 触发，这是 Factorial Action 中涵盖表单以及后续阶段中的 Factorial One 工具和后端作业的部分——fcode-factorial-actions）或 metadata.json 中；面向开发者的按钮规则见 fcode-ui-triggers。

路由 — 深入问题的归属

问题涉及	路由至
平台模型：进程、模块、变量与继承、数据存储／存储、版本控制与 stable	fcode-core-concepts
CLI 命令、metadata.json / settings.json 字段、appRole 字段参考、Webhook 身份验证、FACTORIAL_TOKEN	fcode-cli — 文档：/docs/cli/
编写进程／模块代码	fcode-javascript / fcode-python — 文档：/docs/processes/
输入参数架构（表单定义）	fcode-json-schema
在网页上嵌入表单、主题、预填	fcode-forms — 文档：/docs/forms/
向 Factorial 暴露进程（factorial 块、Factorial One 工具契约、生命周期 slug）	fcode-factorial-actions — 文档：/docs/factorial-actions/
Factorial 内的按钮（factorial.uiTrigger、位置、结果封装）	fcode-ui-triggers
推荐的 Agent 工作方法、MCP 工具	fcode-agent — 文档：/docs/mcp-server/
完整示例（集成、安装／卸载生命周期）	fcode-examples
运行时的执行、计划任务、Webhook	文档：/docs/executions/
集成框架	文档：/docs/building-apps/integrations-framework/
OAuth 与 API 令牌	文档：/docs/building-apps/oauth/
工作区层级	文档：/docs/building-apps/workspaces/
角色与权限：各工作区内谁可以读取／写入／提升版本	references/journey.md §8 — 文档：/docs/building-apps/permissions/
端到端流程（公开版）	文档：/docs/building-apps/developer-journey/

文档路径相对于 https://code.factorialhr.com。

升级处理与管理员操作

需求	操作方式
访问申请待处理	申请正在审核中；审核结果会通知你
Partner / Individual Contributor 的 OAuth 应用	由管理员预先配置 — 配置完成后，可在应用设置的 OAuth 选项卡中查看
Demo company（Partner / IC）	在 Demo companies 页面点击“Request a demo company”；准备就绪后会向你发送邮件
发布审核结果	发布要么会部署，要么会通知你需要进行的更改；修复后使用更高版本再次申请
将发布版本提升至生产环境	由所属团队的 Factorial 管理员自行操作（应用详情页中的“How to promote”对话框提供命令）；其他人需通过运营人员处理 — references/journey.md §8
为特定公司安装私有应用	通过应用详情页创建生产环境安装 — 可由管理员或提供 Factorial 公司 ID 的开发者创建（例如，Factorial 的 Forward Deployed Engineers 推出私有应用的方式）
需要提高限额（执行时间、并发数、数据存储、速率等）	所有工作区使用相同的固定套餐 — 不支持自助升级。请联系我们：Factorial 内部用户请在 Slack 联系 #factorial-code-users，其他用户请联系 Factorial 对接人。当前限额：fcode-core-concepts › 套餐与限额
其他未涵盖的事项	Factorial 内部用户：Slack #factorial-code-users。其他用户：使用上述平台内申请流程