fcode-ama

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Factorial Code — platform guide (AMA)

Factorial Code — 平台指南（AMA）

Factorial Code (fcode) is Factorial's platform for building apps and automations against the Factorial Public API. This skill covers using the platform — the journey from requesting access to a published marketplace app — and how to behave when supporting users through it. For building the app itself (processes, modules, CLI, forms), route to the owning skills (see the routing table below).

The full stage-by-stage walkthrough is in

references/journey.md

; common problems and fixes are in

references/troubleshooting.md

Factorial Code (fcode) 是 Factorial 用于基于 Factorial Public API 构建 App 和自动化的平台。本 skill 涵盖平台的使用——从申请访问权限到发布 Marketplace App 的完整旅程——以及在此过程中支持用户时应遵循的行为规范。若要构建 App 本身（processes、modules、CLI、forms），请路由到相应的负责 skill（见下方路由表）。

完整的分阶段操作指南位于

references/journey.md

；常见问题及修复方法位于

references/troubleshooting.md

。

Who you're helping

正在帮助的用户

Three user roles use the platform. Establish which one you're talking to early — several flows diverge by role:

Role	Who	Key differences
Factorial internal	Developers at Factorial	Create their own OAuth apps in the Factorial Backoffice; create demo companies directly (using the Demo generator); Slack `#factorial-code-users` available
Partner	External companies building apps/integrations with Factorial	OAuth app preconfigured by an administrator; demo companies by request
Individual Contributor	Someone building their own app or automation (may be a customer, but not always — never call this role "end customer")	Same as Partner

All roles talk to Factorial through the Public API, and all belong to a development team: every app a team creates is shared by all its members. When someone requests access and an administrator sees their organization already has a team on the platform, they are added to that existing team.

共有三类用户角色使用该平台。尽早确定正在与哪一类用户沟通——多个流程会因角色而异：

角色	用户群体	主要差异
Factorial 内部人员	Factorial 的开发者	在 Factorial Backoffice 中创建自己的 OAuth App；使用 Demo generator 直接创建演示公司；可使用 Slack `#factorial-code-users`
Partner	与 Factorial 共同构建 App 或集成的外部公司	OAuth App 由管理员预先配置；演示公司需按申请创建
Individual Contributor	构建自己 App 或自动化的个人（可能是客户，但并非总是如此——绝不要将此类角色称为“终端客户”）	与 Partner 相同

所有角色都通过 Public API 与 Factorial 通信，并且都隶属于某个开发团队：团队创建的每个 App 都由所有成员共享。当有人申请访问权限，且管理员发现其组织在平台上已有相应团队时，该用户会被加入现有团队。

Support-agent behavior rules

支持 Agent 行为规则

Answer only from documented flows — this skill, its references, the other
```
fcode-*
```
skills, and the public docs. Never invent UI elements, URLs, commands, or policies. If it isn't covered, say so and escalate.
Identify the user's role first when the answer differs by role.
Describe flows by page and section name (e.g. "the Getting started checklist on the App detail page"), not by exact button pixels — labels change; flows are stable.
Admin actions: outcome only. When a step is performed by an administrator (access approval, demo provisioning, OAuth preconfiguration, release review), tell the user what they will observe and what to do next. Never describe admin-side mechanics or how credentials are delivered.
Answer in the user's language.
Fetch before deep-diving. When you have web access, read the linked docs page before answering a detailed question; the live docs win over this skill on details. Without web access, answer from this skill and say which docs page has more.
Escalate when needed — an admin action, a stuck request, or an uncovered question. Escalation paths are in the last section.

仅依据有文档说明的流程作答——本 skill、其 references、其他
```
fcode-*
```
skills 以及 Public Docs。绝不可臆造 UI 元素、URL、命令或政策。如果文档未涵盖，应说明情况并升级处理。
如果答案因角色而异，先确定用户的角色。
按页面和分区名称描述流程（例如，App detail 页面上的“Getting started checklist”），而不是描述按钮的精确像素位置——标签会变化，但流程是稳定的。
管理员操作：只说明结果。 当某一步由管理员执行（访问审批、演示环境配置、OAuth 预配置、版本审核）时，告诉用户将会看到什么以及接下来该做什么。绝不描述管理员端的操作机制或凭据交付方式。
使用用户的语言回答。
深入之前先查阅资料。 如果具备 Web 访问能力，应先阅读链接的 Docs 页面，再回答详细问题；实时文档在细节上优先于此 skill。如果无法访问 Web，则根据本 skill 回答，并说明还有哪个 Docs 页面包含更多信息。
必要时升级处理——涉及管理员操作、请求卡住或文档未涵盖的问题。升级路径见最后一节。

Platform map

平台地图

Everything lives under

https://code.factorialhr.com

, split across three surfaces users often conflate:

Docs (
```
/docs/...
```
) — public documentation, plus the landing page with the request-access form.
App console (
```
/dashboard/...
```
) — apps, teams, demo companies, marketplaces, installations. Where the journey below happens.
Workspace console (
```
/platform/...
```
) — inside a workspace: processes, executions, schedules, variables, versions, API credentials. The app console links into it — every such jump is labelled "Open on platform"; for a
```
deploy-
```
(installation) workspace it lands on the executions page.

App console areas (the sidebar groups them into Build, Operate, and Admin sections):

Area	What it's for
Apps	The team's apps; where a new app is created
App detail page	Per-app home: the Getting started checklist and the Development / Production / Publication / README tabs
App settings	Configuration (marketplace visibility, lifecycle) and OAuth (requested scopes plus the development and production credentials)
Demo companies	Demo Factorial companies for testing installs
Test marketplace	Simulation of the production marketplace, run against demo companies

Plus the self-describing Marketplace, Team, and Installations areas.

所有内容都位于

https://code.factorialhr.com

下，并分为三个经常被用户混淆的界面：

Docs（
```
/docs/...
```
）——Public Docs，以及包含访问申请表单的 Landing Page。
App Console（
```
/dashboard/...
```
）——管理 Apps、Teams、Demo Companies、Marketplaces 和 Installations。后续旅程主要在此完成。
Workspace Console（
```
/platform/...
```
）——位于 Workspace 内部，用于管理 processes、executions、schedules、variables、versions 和 API Credentials。App Console 会链接到 Workspace Console——每次此类跳转均标为 “Open on platform”；对于
```
deploy-
```
（installation）workspace，会直接进入 executions 页面。

App Console 的各区域在侧边栏中归入 Build、Operate 和 Admin 分组：

区域	用途
Apps	团队的 Apps；用于创建新 App
App detail page	单个 App 的主页：Getting started 检查清单，以及 Development / Production / Publication / README 标签页
App settings	Configuration（Marketplace 可见性和生命周期）以及 OAuth（申请的 scopes，以及开发和生产凭据）
Demo companies	用于测试安装的 Factorial 演示公司
Test marketplace	生产 Marketplace 的模拟环境，可针对演示公司运行

此外还有 Marketplace、Team 和 Installations 区域。

The journey at a glance

旅程总览

#	Stage	Where	What happens
1	Request access	Landing page → request-access form	An administrator reviews it and you're notified; joins an existing development team when one matches
2	Create an App	Apps → create	Name and purpose; language (JavaScript or Python); OAuth scopes; the integrations framework opt-in (decision rule in `references/journey.md` )
3	Getting started	App detail page checklist	Ordered setup steps: build locally, link the Factorial integration (framework apps only), configure OAuth (when scopes were requested), publish a release, add marketplace metadata
4	Configure OAuth	App settings → OAuth tab	Per-environment client credentials for the OAuth flow (per-role setup in `references/journey.md` )
5	Build locally	Your machine	Install the CLI, `fcode clone` the dev workspace (or `fcode team:clone` for every App of your team at once), code with your own agent + the `fcode-*` skills, test locally, `fcode push`
6	Demo company	Demo companies page	Internal: create directly. Partner/IC: request one; you're notified by email
7	Test installs	Test marketplace	Run the real OAuth flow with the demo company's credentials, install, exercise the `appRole` forms and any UI trigger buttons inside the demo company's Factorial
8	Release	App detail → Production tab	Request a release (semver + notes); after validation it's promoted to the prod workspace — self-service for a Factorial admin of the owning team, by an operator otherwise ( `references/journey.md` §8)
9	Publish listing	App detail → Publication tab	Marketplace listing metadata: a linked DatoCMS record and/or the fallback fields
10	Production	Marketplace	Visible and installable; each install gets its own isolated workspace

Per-stage detail, per-role callouts, and lifecycle states:

references/journey.md

#	阶段	位置	发生的内容
1	申请访问权限	Landing Page → request-access form	管理员进行审核并通知申请人；如果组织已有匹配的开发团队，用户会加入该团队
2	创建 App	Apps → create	填写名称和用途；选择语言（JavaScript 或 Python）；设置 OAuth scopes；决定是否启用 integrations framework（决策规则见 `references/journey.md` ）
3	Getting started	App detail page 检查清单	按顺序完成设置步骤：在本地构建、关联 Factorial integration（仅限 framework apps）、配置 OAuth（申请了 scopes 时）、发布 release、添加 Marketplace metadata
4	配置 OAuth	App settings → OAuth tab	为 OAuth 流程配置各环境的客户端凭据（按角色配置方式见 `references/journey.md` ）
5	本地构建	本机	安装 CLI，使用 `fcode clone` 克隆开发 workspace（或使用 `fcode team:clone` 一次克隆团队的所有 App），使用自己的 Agent + `fcode-*` skills 编写代码，在本地测试，然后执行 `fcode push`
6	演示公司	Demo companies 页面	Factorial 内部人员可直接创建；Partner/IC 需按申请创建，準備完成后会收到邮件通知
7	测试安装	Test marketplace	使用演示公司的凭据运行真实的 OAuth 流程，执行安装，并在演示公司的 Factorial 中测试 `appRole` 表单及所有 UI trigger 按钮
8	发布版本	App detail → Production tab	申请发布版本（semver + 说明）；验证通过后会提升至 prod workspace——所属团队的 Factorial 管理员可自助完成，否则由 operator 处理（ `references/journey.md` §8）
9	发布上架信息	App detail → Publication tab	填写 Marketplace 上架信息：关联的 DatoCMS record 和/或 fallback fields
10	生产环境	Marketplace	App 可见且可安装；每次安装都会获得独立的隔离 workspace

各阶段的详细说明、角色提示和生命周期状态见

references/journey.md

。

Workspaces behind the journey

旅程背后的 Workspaces

Naming caution: a Factorial Code workspace is also called a "team" in the workspace console, in the platform API, and in a few CLI surfaces ("team variables", the

parentTeams

field) — that sense is unrelated to the development team of humans described above. The CLI's

fcode team:*

commands mean the development team: they operate on every App it owns (see

fcode-cli

Each app maps to workspaces (slugs carry an encoded token, not the raw id):

```
dev-{appId}
```
— the development workspace you clone and push to.
```
prod-{appId}
```
— production copy, created when the first release is requested. Treat its code as read-only — changes belong in dev and reach it through the release flow; only operators and the app's Factorial team admins can write to it at all. Its variables are live — shared defaults and credentials for all installations are managed there.
```
deploy-{installationId}
```
— one per company installation, inheriting from the app workspace: it holds only that company's variables and executions, fully isolated from other companies. A change in the parent workspace is automatically available in every installation workspace.
```
base-app
```
/
```
base-integration-app
```
(language-matched variants,
```
-js
```
/
```
-py
```
) — shared bases every app inherits: API clients, webhook/schedule/email/form helpers, and (for framework apps) the integration templates.

Released versions are pinned tags and the stable
alias points at the current one (model in

fcode-core-concepts

). For a marketplace app, ship through the release flow (stage 8) — don't publish versions or move

stable

by hand.

命名注意事项：Factorial Code workspace 在 Workspace Console、Platform API 以及少数 CLI 界面（“team variables”、

parentTeams

字段）中也称为“team”——这种含义与上文所述由人员组成的开发团队无关。CLI 的

fcode team:*

命令指开发团队：这些命令会操作该团队拥有的每个 App（见

fcode-cli

）。

每个 App 都映射到若干 workspace（slug 携带编码后的 token，而不是原始 id）：

```
dev-{appId}
```
——用于 clone 和 push 的开发 workspace。
```
prod-{appId}
```
——生产副本，在首次申请发布版本时创建。应将其代码视为只读——修改应先在 dev 中完成，再通过发布流程进入 prod；只有 operators 和该 App 的 Factorial 团队管理员可以写入。其 variables 处于实际生效状态——所有 installations 共享的默认项和凭据均在此管理。
```
deploy-{installationId}
```
——每次公司安装对应一个，继承自 App workspace：其中仅保存该公司的 variables 和 executions，与其他公司完全隔离。父 workspace 中的变更会自动应用于所有 installation workspaces。
```
base-app
```
/
```
base-integration-app
```
（按语言匹配的变体：
```
-js
```
/
```
-py
```
）——每个 App 都会继承的共享基础 workspace：包含 API clients、webhook/schedule/email/form helpers，以及 framework apps 使用的 integration templates。

已发布版本使用固定版本标签，stable
alias 指向当前版本（模型见

fcode-core-concepts

）。对于 Marketplace App，应通过发布流程交付版本（阶段 8）——不要手动发布版本或移动

stable

。

Buttons inside Factorial — UI triggers

Factorial 内的按钮——UI Triggers

Besides forms and webhooks, an installed app can put its own buttons on Factorial's pages. Factorial teams declare locations in the product (a page header, an actions dropdown — e.g.

calendar.header.admin

); an app process that declares a

uiTrigger

for that location shows up there as a button, with the app's label and icon, for every company that installed the app. Clicking it runs the process with the page's context (the record on screen, the company), or opens the process's form when it has one — so a "Sync to Acme" action can live next to Factorial's native actions without Factorial shipping any integration-specific UI.

What to tell users:

It works only for installed marketplace apps — the buttons are read from the company's
```
deploy-
```
workspace, so a trigger reaches customers through the release flow (stage 8) like any other change; in development, the demo company shows the dev workspace's triggers (stage 7).
The location id comes from Factorial: there is no catalogue in the platform. A developer who wants a button on a page that has no location yet needs the owning Factorial team to add one — escalate as a product request.
Some locations admit one app at a time; installing a second app that claims such a location fails with a message naming the first.
Configuration lives on the process page (Trigger from Factorial, the section of a Factorial Action that also covers forms and, in later phases, Factorial One tools and backend jobs —
```
fcode-factorial-actions
```
) or in
```
metadata.json
```
; the developer-facing rules for the button are in
```
fcode-ui-triggers
```
.

除了表单和 webhook，已安装的 App 还可以在 Factorial 页面上放置自己的按钮。Factorial 团队会在产品中声明 locations（例如页面 header、操作下拉菜单——如

calendar.header.admin

）；为该 location 声明

uiTrigger

的 App process 会显示为按钮，并使用该 App 的标签和图标，所有安装了该 App 的公司均可看到。点击按钮会使用当前页面的上下文（屏幕上的 record、公司）运行 process，或者在 process 带有表单时打开该表单——因此“Sync to Acme”等操作可以与 Factorial 原生操作并列显示，而无需 Factorial 专门交付集成 UI。

应向用户说明：

它仅适用于已安装的 Marketplace Apps——按钮从公司的
```
deploy-
```
workspace 读取，因此与其他变更一样，trigger 需要通过发布流程（阶段 8）才能触达客户；在开发环境中，演示公司会显示 dev workspace 的 triggers（阶段 7）。
location id 来自 Factorial——平台中没有相关目录。如果开发者希望在尚未定义 location 的页面上添加按钮，则需要 Factorial 的负责团队添加该 location，并作为产品需求升级处理。
某些 locations 同时只允许一个 App 使用；安装第二个声明相同 location 的 App 时，操作会失败，错误信息会指明第一个 App。
配置位于 process 页面（Trigger from Factorial，即 Factorial Action 中同时涵盖 forms，并将在后续阶段涵盖 Factorial One tools 和 backend jobs 的分区——
```
fcode-factorial-actions
```
）或
```
metadata.json
```
中；面向开发者的按钮规则见
```
fcode-ui-triggers
```
。

Routing — where deep questions live

路由——深入问题所在的位置

Question is about	Route to
Platform model: processes, modules, variables & inheritance, datastore/storage, versioning & `stable`	`fcode-core-concepts`
CLI commands, `metadata.json` / `settings.json` fields, `appRole` field reference, webhook auth, `FACTORIAL_TOKEN`	`fcode-cli` — docs: `/docs/cli/`
Writing process/module code	`fcode-javascript` / `fcode-python` — docs: `/docs/processes/`
Input-parameter schemas (forms definition)	`fcode-json-schema`
Embedding forms on webpages, themes, pre-fill	`fcode-forms` — docs: `/docs/forms/`
Exposing a process to Factorial ( `factorial` block, Factorial One tool contract, lifecycle slugs)	`fcode-factorial-actions` — docs: `/docs/factorial-actions/`
Buttons inside Factorial ( `factorial.uiTrigger` , locations, result envelope)	`fcode-ui-triggers`
Recommended agent working method, MCP tools	`fcode-agent` — docs: `/docs/mcp-server/`
Worked examples (integration, install/uninstall lifecycle)	`fcode-examples`
Executions, schedules, webhooks at runtime	docs: `/docs/executions/`
Integrations framework	docs: `/docs/building-apps/integrations-framework/`
OAuth & API tokens	docs: `/docs/building-apps/oauth/`
Workspace hierarchy	docs: `/docs/building-apps/workspaces/`
Roles & permissions: who can read/write/promote per workspace	`references/journey.md` §8 — docs: `/docs/building-apps/permissions/`
The end-to-end journey (public version)	docs: `/docs/building-apps/developer-journey/`

Doc paths are relative to

https://code.factorialhr.com

问题主题	路由至
平台模型：processes、modules、variables 及其继承、datastore/storage、versioning 与 `stable`	`fcode-core-concepts`
CLI 命令、 `metadata.json` / `settings.json` 字段、 `appRole` 字段参考、webhook 认证、 `FACTORIAL_TOKEN`	`fcode-cli` ——文档： `/docs/cli/`
编写 process/module 代码	`fcode-javascript` / `fcode-python` ——文档： `/docs/processes/`
输入参数 schemas（forms 定义）	`fcode-json-schema`
在网页、主题中嵌入 forms，以及预填充	`fcode-forms` ——文档： `/docs/forms/`
将 process 暴露给 Factorial（ `factorial` block、Factorial One tool contract、lifecycle slugs）	`fcode-factorial-actions` ——文档： `/docs/factorial-actions/`
Factorial 内的按钮（ `factorial.uiTrigger` 、locations、结果封装）	`fcode-ui-triggers`
推荐的 Agent 工作方式、MCP tools	`fcode-agent` ——文档： `/docs/mcp-server/`
实例教程（integration、install/uninstall 生命周期）	`fcode-examples`
运行时的 executions、schedules、webhooks	文档： `/docs/executions/`
Integrations framework	文档： `/docs/building-apps/integrations-framework/`
OAuth 与 API tokens	文档： `/docs/building-apps/oauth/`
Workspace 层级结构	文档： `/docs/building-apps/workspaces/`
角色与权限：谁可以按 workspace 读取、写入或提升版本	`references/journey.md` §8——文档： `/docs/building-apps/permissions/`
端到端完整旅程（公开版本）	文档： `/docs/building-apps/developer-journey/`

文档路径均相对于

https://code.factorialhr.com

。

Escalation & admin actions

升级处理与管理员操作

Need	What to do
Access request pending	It's under review; you'll be notified of the outcome
OAuth app for a Partner / Individual Contributor	Preconfigured by an administrator — visible on the App settings' OAuth tab once done
Demo company (Partner / IC)	"Request a demo company" on the Demo companies page; you're emailed when it's ready
Release review outcome	The release either deploys or you're notified of required changes; fix and request again with a higher version
Promote a release to production	A Factorial admin of the owning team does it themselves (the App detail page's "How to promote" dialog has the commands); everyone else's route is an operator — `references/journey.md` §8
Private app installed for a specific company	A production installation created from the App detail page — by an administrator or by a developer who provides the Factorial company ID (e.g. how Factorial's Forward Deployed Engineers roll out private apps)
Need a higher limit (execution time, concurrency, datastore, rate, …)	Every workspace is on the same fixed plan — there is no self-service upgrade. Ask us: internal Factorial users in Slack `#factorial-code-users` , others through their Factorial contact. Current values: `fcode-core-concepts` › Plans & limits
Anything not covered	Internal Factorial users: Slack `#factorial-code-users` . Others: the in-platform request flows above

需求	处理方式
访问申请仍在审核中	当前正在审核；审核结果出来后会收到通知
Partner / Individual Contributor 的 OAuth App	由管理员预先配置——完成后可在 App settings 的 OAuth tab 中看到
演示公司（Partner / IC）	在 Demo companies 页面选择“Request a demo company”；准备完成后会收到邮件
版本审核结果	Release 要么完成部署，要么会收到需要修改的通知；修复后使用更高的版本号重新申请
将 Release 提升至生产环境	所属团队的 Factorial 管理员可以自行完成（App detail 页面中的“How to promote”对话框包含相关命令）；其他用户的处理途径是 operator—— `references/journey.md` §8
为特定公司安装私有 App	从 App detail 页面创建生产 installation——可以由管理员完成，也可以由能够提供 Factorial company ID 的开发者完成（例如 Factorial 的 Forward Deployed Engineers 部署私有 App 的方式）
需要提高上限（执行时长、并发数、datastore、速率等）	所有 workspace 都使用相同的固定套餐——不支持自助升级。请联系我们：Factorial 内部用户使用 Slack `#factorial-code-users` ，其他用户通过其 Factorial 联系人。当前数值见 `fcode-core-concepts` › Plans & limits
任何未涵盖的问题	Factorial 内部用户：Slack `#factorial-code-users` 。其他用户：使用上述平台内的申请流程