fcode-core-concepts

Factorial Code 核心概念

Factorial Code（fcode）是一个企业集成与自动化平台。 你可以使用 JavaScript 或 Python 编写流程（以及可复用的模块）；平台会负责沙箱隔离、依赖项、密钥、调度和执行。

本技能介绍了基本思维模型。要编写实际代码，还需使用 fcode-javascript 或 fcode-python；要了解 CLI 工作流，请使用 fcode-cli。

注意事项

以下情况容易违背合理预期——如果处理错误，流程就会中断：

• 数据存储仅保存字符串和数字。 使用 set 前，先用 JSON.stringify / json.dumps 序列化对象；使用 get 后再解析。
• 模块文件以其 slug 命名，而不是 index/main。 模块文件路径为 modules/<slug>/<slug>.js（或 .py），例如： modules/shopify-client/shopify-client.js。切勿使用 modules/<slug>/index.js 或 main.py（这些名称保留给流程入口文件），也切勿将模块文件直接放在 modules/ 下而不创建专属文件夹。
• 切勿覆盖整个 variables.env。 先读取文件，然后仅追加或更新 特定变量；重写文件会删除新内容中不存在的所有变量，并可能导致其他流程出错。
• 切勿编辑继承的资源（variables.inherited.env、 i18n/<locale>.inherited.yaml、继承的流程/模块）——这些资源归父工作区所有，并会在每次拉取时重新生成。要覆盖变量或 locale 键，请在此工作区自己的文件中定义；要编辑流程和模块，请前往拥有它们的工作区。
• 切勿硬编码或记录密钥。 使用变量/环境变量；在日志中屏蔽或省略密钥。
• 运行时版本固定： JavaScript = Node.js v22，Python = 3.13。
• 每个工作区的限制固定不变：每次执行 12 h、并发执行 50 次、50 req/s、返回值 500 KB、每条数据存储条目 50 KB。若要提高限制，请联系我们，而不是更改计划。请参阅 Plans & limits。

核心概念

概念	定义	要点
流程	执行单元（业务逻辑）	定义输入参数，并返回结构化结果
模块	可复用代码库	可供多个流程共享，并支持版本控制
工作区版本	一个标签（例如 v1.0.0），会发布到团队拥有的每个流程和模块上	通过 Web UI 发布；重试同一标签是安全的
版本别名	指向某个版本的可移动指针	stable 始终存在——将使用方固定到它；移动该别名即为发布/回滚
变量	配置和密钥	环境变量；从父工作区继承；切勿硬编码密钥
数据存储	持久化键值存储	仅支持字符串和数字；可按需加密静态存储的数据
存储	文件存储	二进制文件、文档、大型负载
语言区域	每种语言对应的翻译文件（i18n/<locale>.yaml）	由 fcode.i18n 解析；逐个键从父工作区继承——请参阅 fcode-i18n
电子邮件	内置事务性电子邮件	fcode.sendMail / send_mail；无需设置 SMTP，凭据由管理器保存

流程

基本执行单元，使用 JavaScript（index.js）或 Python（main.py）编写。 流程可以通过 JSON Schema 声明输入参数（parametersSchema.json， 请参阅 fcode-json-schema），并通过 fcode.context.parameters 读取这些参数。 返回结构化 JSON；若要返回 Webhook 风格的响应，请使用 { status, headers, body }。

模块

供多个流程共享的可复用库——可用于避免重复、封装 API 客户端/集成、精简流程代码并支持版本控制。请参阅上文的模块命名注意事项。

执行上下文

每个流程都在隔离环境中运行，并可访问：

• 输入参数：fcode.context.parameters
• 环境变量：process.env.* / os.getenv(...)（或 fcode.env.*）
• 执行元数据：fcode.execution.*
• 请求数据（Webhook）：适用时可读取请求正文/标头

变量（配置和密钥）

将基础 URL、超时设置、API 密钥和令牌存储为变量（切勿硬编码）。 variables.env 保存团队变量（KEY=VALUE）；variables.local.env 保存 仅本地使用的覆盖值。请参阅上文关于覆盖的注意事项。

variables.meta.json 会标记每个变量的 isSensitive 标志。敏感值永远不会离开云端——在本地，它们在 variables.env 中显示为 ******** 占位符；请将实际值放入 variables.local.env。详情请参阅 fcode-cli。

本地运行需要密钥的实际值时，请向用户索取，或者如果他们不愿分享，也可以让他们自行将值放入 variables.local.env。FACTORIAL_TOKEN 来自 Factorial Code 应用详情页中的 OAuth 流程，仅在本地需要（远程环境会自动填充）；操作步骤请参阅 fcode-cli。

团队变量还可用于保护 Webhook：进程会指定它所期望的令牌所在变量的名称，而调用方通过 Authorization: Bearer <token> 发送该值。进程只会存储变量名称，因此令牌不会出现在导出内容或提交的文件中。

在运行时通过 fcode.env.* 读取变量。要从进程中以编程方式创建、更新或删除变量，请使用 fcode.variables 辅助工具 （set/get/list/delete）——作用范围限于你的团队，无需 API 令牌。请参阅 fcode-javascript / fcode-python。

从父工作区继承

工作区会使用其 parentTeams 父级的进程、模块、变量、i18n 区域设置和 依赖项，就像这些资源属于它自己一样。 所有资源的解析方式相同：先查找当前工作区，再按配置顺序查找其直接父级，最多 5 个——因此 不支持传递继承（祖父级的资源不会传递到孙级工作区）。

• 可以自由读取、调用和导入继承的资源——继承的模块导入方式与自有模块完全相同，子级代码也可以依赖父级进程——但这些资源在继承时为只读：切勿修改、删除或重新安排它们，无论是编辑文件还是使用 MCP 工具。 请在拥有这些资源的工作区中编辑它们。
• 变量、区域设置和依赖项通过在本地重新定义来覆盖： 子级的 variables.env、i18n/<locale>.yaml 或 dependencies/package.json / requirements.txt 中的键会覆盖父级对应项——变量按键覆盖，依赖项按包覆盖；子级的版本约束符会替换父级的，因为同一个包无法并排安装两个版本。删除覆盖项即可恢复父级的值。进程和模块没有覆盖机制——请在所属工作区中更改它们。
• 只继承父级已安装的依赖项。 父级已保存但尚未安装的清单更改不会传递给子级；安装后，子级会在下次执行时获取这些依赖项，无需在子级安装。父级已提供的包无需在子级声明。
• 不要在子级中重新创建父级的变量。 这些变量已经可以在子级中解析。这就是为什么 deploy-{installationId} 工作区只包含特定客户的值，而共享默认值和凭据保留在 prod-{appId} / base-app 中。在 Web UI 中，继承的变量会带有继承徽标，并提供在此处覆盖选项。
• 密钥也会继承，其实际值会传递到沙盒。 子级工作区中的进程会在执行时读取父级的密钥。除此之外，这些密钥在所有位置都会被屏蔽（GraphQL 中为 null，REST 中为 ******，CLI 的继承文件中为 ********），因此只有进程代码能够读取其值——请将子级工作区中的代码视为可访问父级凭据的可信代码。 本地运行会获取占位符——请将实际值放入 variables.local.env。
• 工作区版本不会发布继承的资源——只有自有资源会带有标签（请参阅版本控制和别名）。

将父级固定到其中一个版本

每个父级链接都可选携带一个版本固定项：标签，或 stable 这类别名，指向该父级的某个工作区版本。不设置时，父级会实时解析——使用其当前代码，即上述行为。设置后，该父级提供的是发布版本，而非工作副本：

• 仅包含该版本发布的内容，且使用该版本的内容状态。 父级在发布后添加的进程或模块不会存在，解析会继续查找下一个父级，就像被固定的父级没有该项一样。父级可以继续编辑和发布，而子级运行的内容不会随之改变。
• 别名固定项会跟随别名。 将子级固定到 stable 后，只需在父级中重新指定 stable，所有固定到该别名的子级都会随之更新，一次操作即可。这就是基础应用向其安装实例推送修复的方式。
• 依赖项也会跟随固定项——子级安装的是创建该固定发布版本时所用的包，而不是父级当前安装的包。
• 变量始终实时解析，无论是否设置固定项：变量没有版本化形式。
• 子级无法选择继承资源的版本。 版本由固定项决定。在 Web UI 中，继承的进程、模块或区域设置会以只读方式显示其版本（固定标签或 Live），且没有 Versions 标签页；发布资源和设置资源别名属于拥有该资源的工作区。

可在 Web UI（团队设置 → Details → 父级团队）或工作区的 settings.json 中为每个父级设置固定项；字段说明见 fcode-cli。除非明确提出要求，否则不要添加或更改固定项——它决定工作区运行哪个发布版本。

继承资源的磁盘布局、gitignore 规则以及推送/拉取行为，详见 fcode-cli。

定时任务

按 cron 计划或一次性日期/时间运行进程。可在进程代码中使用 fcode.schedule 助手管理定时任务（create/list/get/update/pause/ resume/delete/deleteForProcess）——与其他助手一样，开箱即用，无需额外配置身份验证。参见 fcode-javascript / fcode-python。

Datastore 与 Storage

• Datastore — 用于在多次运行之间持久保存键值状态（上次运行时间戳、游标、去重 ID、小型缓存）。仅支持字符串/数字。调用 set 时将 true 作为第三个参数，即可使用工作区自有密钥对值进行静态加密。读取时会自动解密。进程本身必须在多次运行之间持久保存的机密（例如其获取的 OAuth 令牌）应存放在这里——参见 fcode-javascript / fcode-python。
• Storage — 不适合存放在 datastore 中的文件（报告、导出文件、图像、PDF、数据提取文件）。

发送电子邮件

使用内置的 fcode.sendMail（Python 中为 fcode.send_mail）发送电子邮件——已预先完成身份验证，无需配置 SMTP。邮件服务器和凭据存放在执行器管理器中，绝不会放在进程内。默认情况下，每次执行最多可发送 3 封电子邮件。用法参见 fcode-javascript / fcode-python。

所有应用都使用同一个固定的 Factorial 地址作为发件人，因此，一个滥用邮件功能的应用会成为其收件人的钓鱼风险，也会影响其他所有应用的邮件送达率。内置邮件发送器仅供向客户的 Factorial 账户已知人员发送事务性邮件；应用验证（fcode-code-validation）会阻止其他用途的版本发布。

超出此范围的邮件——面向客户的营销活动、大批量邮件、自定义发件人——必须使用专用邮件服务提供商，并通过应用自己的凭据调用（fcode-agent 中介绍了相应选择）；切勿使用内置邮件发送器绕过发送限制。

版本与别名

流程和模块可以单独进行版本管理，工作区版本会一次性为团队拥有的每个流程和模块发布同一个标签（例如 v1.0.0）——通过 parentTeams 继承的资源不会受到影响。每个实体的结果（已创建 / 已跳过 / 失败）都会记录在版本的清单中，因此部分失败后重新创建相同标签，只会发布仍缺失的内容。

发布工作区版本时，工作区拥有的模块中不带标签的 fcode.import("mod") / fcode.import_module("mod") 调用仅会在已发布的快照中固定到该标签——工作副本不会被修改，已有标签或别名的导入也不会受到影响。工作区版本还会发布所有自有区域语言，并以相同方式固定 fcode.i18n 调用——已经指定 version 的调用不会受到影响，其他调用（不带参数的调用、仅包含区域语言的选项）都会固定到该标签——这同样适用于代码和表单架构，因此发布版本会将翻译一并冻结——参见 fcode-i18n。

版本别名是指向某个版本的可移动指针。stable 别名始终存在，并指向工作区的稳定版本。Webhook、表单、计划任务和模块导入在接受标签的地方也接受别名，因此将 stable 移至其他版本，就能通过一次操作重新指向整个工作区——发布和回滚只需更改别名。始终将使用方（Webhook URL、表单嵌入代码）固定到 stable；相关方法见 fcode-cli 和 fcode-forms。

这一模型有两个结果：

• **fcode push 不会影响固定到 stable 的使用方。**推送会更新当前（未版本化的）代码；固定的使用方会继续运行已发布的版本，直到别名发生变更。
• 删除工作区版本会级联删除——所有带有该标签的自有流程 / 模块版本都会被删除，连同引用它们的别名、执行记录和计划任务。
• **其他工作区固定的版本或别名会受到保护。**删除操作会被拒绝，并列出受影响的工作区；这些工作区必须先取消固定。仍允许重新指向别名——这就是晋升发布版本的方式。

可通过 Web UI（团队设置 → Versions 选项卡）发布版本并关联别名。CLI 对应命令（fcode settings:versions:* / settings:aliases:*）见 fcode-cli 文档——除非收到明确要求，否则不要创建版本或移动 stable。

版本标签（v1.0.0）与 metadata.json 中的 tags 无关——后者是流程标签（例如用于 MCP 工具的暴露，参见 fcode-agent）。

计划与限制

每个工作区都采用相同的固定计划，因此以下限制适用于所有工作区——没有可供选择的计划，也无法自助升级。请据此设计应用。如果确有需求无法满足，请联系我们提高该工作区的限制（Factorial 内部用户：Slack #factorial-code-users；其他用户：请参阅 fcode-ama › Escalation）——绝不要绕过限制，例如将一项任务拆分到多次执行中，或串联数据存储键以规避上限。

限制	值	超出时的处理
每次执行时长	12 小时	终止此次执行
每个工作区的并发执行数	50	新执行将排队
每个工作区的排队执行数	1,000	拒绝新执行
Webhook 请求数	每个工作区 50 req/s	返回 HTTP 429 和 Retry-After
表单和 OAuth 端点请求数	每个进程和调用方 50 req/s	返回 HTTP 429 和 Retry-After
输入参数 — 文本	500 KB	返回 HTTP 413，不创建执行
输入参数 — 文件	总计 15 MB	返回 HTTP 413，不创建执行
返回值	500 KB	执行失败——将大型结果放入存储，并返回引用
执行日志	500 行且 500 KB	丢弃后续日志条目
数据存储条目	每个工作区 20,000 条	写入失败（HTTP 403）
数据存储条目大小	50 KB	写入失败（HTTP 413）
存储文件	1,000 个文件，每个 50 MB	上传失败
每次执行的电子邮件数	3（参见“发送电子邮件”）	后续发送操作将抛出异常
进程、表单、依赖项、每日／每月执行数	不限	—

决策指南

模块与内联代码

场景	建议
多个进程使用的 API 客户端	创建一个模块
使用 2 次或以上的实用工具函数	创建一个模块
一次性转换／仅使用一次的逻辑	保持内联

数据存储、变量与存储

需求	使用
很少变更的配置；密钥／凭据	变量
在不同运行之间会变化的状态；缓存的 API 响应	数据存储
进程获取并需要在不同运行之间保留的密钥（OAuth 令牌）	数据存储，set(key, value, true)
二进制文件／大型导出文件	存储

命名约定

资源	约定	示例
进程 slug	kebab-case	order-sync-shopify
模块 slug	kebab-case	shopify-client
变量	SCREAMING_SNAKE_CASE	SHOPIFY_API_KEY
JavaScript 函数	camelCase	fetchOrders()
Python 函数	snake_case	fetch_orders()

工作区结构（CLI）

由 fcode CLI 管理的本地工作区（参见 fcode-cli）：

📦 <workspace-name>
┣ 📂 dependencies          # shared deps: package.json (JS) / requirements.txt (Py)
┃ ┗ 📜 package.inherited.json    # inherited deps (read-only, gitignored); .txt for Py
┣ 📂 i18n
┃ ┣ 📜 <locale>.yaml       #   translations this workspace owns (see fcode-i18n)
┃ ┗ 📜 <locale>.inherited.yaml  # inherited translations (read-only, gitignored)
┣ 📂 modules
┃ ┗ 📂 <module-slug>       # one folder per module
┃   ┗ 📜 <module-slug>.js  #   entry file named after the slug (NOT index.js)
┣ 📂 processes
┃ ┗ 📂 <process-slug>      # one folder per process
┃   ┣ 📜 index.js          #   or main.py — the process entry file
┃   ┣ 📜 parametersSchema.json   # input parameter schema (the form)
┃   ┣ 📜 parameters.json   #   default test parameters for `fcode run`
┃   ┣ 📜 metadata.json     #   name, description, tags, webhook + the `factorial` action block
┃   ┣ 📜 README.md
┃   ┗ 📜 package.json      #   optional process-scoped dependencies
┣ 📜 datastore.json
┣ 📜 settings.json         # workspace settings: inheritance, timezone, error handler, webhook auth
┣ 📜 variables.env         # team variables this workspace owns (KEY=VALUE)
┣ 📜 variables.inherited.env  # variables from parent workspaces (read-only, gitignored)
┣ 📜 variables.local.env   # local overrides (not shared)
┣ 📜 variables.meta.json   # per-variable isSensitive flags
┗ 📂 .fcode

整个开发团队会在上一级目录中检出项目，每个 App 使用一个文件夹，并将工作区嵌套在其中——在 fcode-cli 中使用 fcode team:clone：

acme-payroll/               # the development team
┣ 📂 .fcode/team.json       # the team and the Apps cloned into it
┣ 📂 .claude/skills/        # installed once, symlinked into every App
┗ 📂 payroll-sync/          # one folder per App — a future git repo
  ┣ 📜 settings.json        #   the App — name, description (mirror, read-only)
  ┣ 📜 README.md            #   the App's README (editable, `fcode app:push`)
  ┣ 📜 MARKETPLACE.md       #   the marketplace listing (editable, `fcode app:push`)
  ┣ 📜 CHANGELOG.md         #   generated from the App's releases (read-only)
  ┣ 📂 marketplace/logo.*   #   the App logo (read-only)
  ┗ 📂 app/                 #   the workspace laid out above

进程和模块也包含 versions/<tag>/ 子文件夹（例如 versions/v1.0.0/），其中保存已发布的版本快照——参见上文的版本控制部分。dependencies/package.json 仅包含内部的 dependencies 对象（例如 { "axios": "^1.6.0" }）。

metadata.json 用于配置进程的 webhook 触发器及其 Factorial Action——编辑后运行 fcode push。Webhook 可以公开访问（authMode: NONE）、继承工作区在 settings.json 中设置的 webhookAuth（TEAM），或使用自己的请求头和团队变量（CUSTOM）。factorial 代码块说明 Factorial 如何调用该进程：一个主开关、Factorial 是否等待结果、用户所需的策略，以及每个入口点对应的子代码块——Factorial UI 中的按钮（fcode-ui-triggers）、表单（fcode-forms）、带有自身契约的 Factorial One 工具、后端任务（fcode-factorial-actions）。较旧的 form 和 uiTrigger 键属于旧版字段，会与其保持同步。四个进程 slug 保留用于应用生命周期——install、settings、uninstall、sync。完整字段参考请见 fcode-cli。

通用规则

• 尽早验证输入——在开始时检查必需参数和类型。
• 明确处理错误；抛出有意义且可执行的错误，并在重新抛出每个捕获的错误前，记录包含上下文的信息（执行了什么操作、使用了哪些输入）。
• 对外部调用使用超时和重试；注意速率限制。
• 通过共享的 fcode-logs 模块充分记录日志——使用团队变量 LOG_LEVEL 按级别控制日志（默认值为 info）。在 info 级别记录开始/结束、重要决策和外部调用；在 debug 级别记录详情（负载、中间状态）（生产环境中会关闭）。绝不记录密钥。在 fcode-javascript / fcode-python 中查看用法。
• 保持输出结构化（使用便于使用和调试的 JSON）。