用途
Factorial Code（fcode）是一个企业级集成与自动化平台。用户以 JavaScript 或 Python 编写流程（processes）和可复用模块（modules），平台负责沙箱、依赖、密钥、调度与执行。本技能提供其核心概念与心智模型；编写实际代码需配合 fcode-javascript 或 fcode-python，CLI 工作流见 fcode-cli。
主要能力与核心概念
- 流程（Process）：执行单元（业务逻辑），定义输入参数并返回结构化结果。JavaScript 入口为 index.js，Python 入口为 main.py。可通过 JSON Schema（parametersSchema.json）声明输入参数，经 fcode.context.parameters 读取。返回结构化 JSON；webhook 风格响应返回 { status, headers, body }。
- 模块（Module）：跨流程共享的可复用代码库，可版本化，用于避免重复、封装 API 客户端/集成、保持流程代码精简。
- 执行上下文：每个流程隔离运行，可访问输入参数（fcode.context.parameters）、环境变量（process.env.* / os.getenv(...) 或 fcode.env.）、执行元数据（fcode.execution.）以及 webhook 请求数据。
- 变量（Variables）：存储基础 URL、超时、API 密钥和令牌，绝不硬编码。variables.env 保存团队变量（KEY=VALUE），variables.local.env 保存本地覆盖。variables.meta.json 标记每个变量的 isSensitive 标志。敏感值不离开云端，本地以 ******** 占位符出现。运行时通过 fcode.env.* 读取；流程内可用 fcode.variables 助手（set/get/list/delete）以编程方式增删改，作用域为团队，无需 API 令牌。webhook 保护也通过团队变量实现：流程指定持有期望令牌的变量名，调用方以 Authorization: Bearer <token> 发送。
- 从父工作区继承：工作区像使用自己的资源一样使用 parentTeams 父级的流程、模块、变量、i18n 语言文件和依赖。解析顺序为工作区自身，然后按配置顺序的直接父级，最多 5 个，不具传递性。继承资源可自由读取、调用和导入，但在继承处只读，不可修改、删除或重新调度。变量、语言文件和依赖通过本地重定义覆盖（逐键、逐包），删除覆盖即恢复父级。仅父级已安装的依赖会继承。密钥也会继承，其真实值会到达沙箱。工作区版本从不发布继承资源。
- 将父级固定到某个版本：每个父级链接可携带可选版本固定（标签或 stable 等别名）。无固定则父级实时解析；有固定则父级贡献该发布版本而非工作副本。别名固定跟随别名。依赖也跟随固定。变量始终实时解析。子级不能选择继承资源的版本。固定按父级在 Web UI（团队设置 → Details → parent teams）或工作区 settings.json 中设置。
- 调度（Schedules）：按 cron 或一次性日期/时间运行流程。可用 fcode.schedule 助手（create/list/get/update/pause/resume/delete/deleteForProcess）从流程代码管理。
- 数据存储（Datastore）与文件存储（Storage）：Datastore 是跨运行的持久键值状态（上次运行时间戳、游标、去重 ID、小缓存），仅字符串/数字。值可在 set 的第三个参数传 true 以工作区自有密钥静态加密，读取透明。Storage 存放不适合 Datastore 的文件（报告、导出、图片、PDF、数据提取）。
- 发送邮件：使用内置 fcode.sendMail（Python 为 fcode.send_mail），预认证、无需 SMTP 配置。邮件服务器和凭据位于执行器管理器。每次执行默认最多发送 3 封邮件。所有应用从同一固定 Factorial 地址发送，内置邮件器仅用于向客户 Factorial 账户已知人员的交易邮件，应用验证会阻止其他用途。超出该范围的邮件需使用专用邮件提供商并以应用自有凭据调用。
- 版本与别名：流程和模块可单独版本化，工作区版本一次为团队拥有的每个流程和模块发布一个标签（如 v1.0.0），继承资源不受影响。每个实体的结果（created/skipped/failed）记录在版本清单中。发布工作区版本时，工作区自有模块的裸 fcode.import("mod") / fcode.import_module("mod") 调用仅在已发布快照内固定到该标签，工作副本不变。版本别名是指向版本的可移动指针，stable 别名始终存在。webhook、表单、调度和模块导入在接受标签处也接受别名。fcode push 不影响固定到 stable 的消费者。删除工作区版本会级联删除。被其他工作区固定的版本或别名受保护。版本从 Web UI（团队设置 → Versions 标签）发布和链接别名。版本标签与 metadata.json 标签无关。
使用方式
流程以 JavaScript（index.js）或 Python（main.py）编写，可声明 JSON Schema 输入参数。模块位于 modules/<slug>/<slug>.js（或 .py），例如 modules/shopify-client/shopify-client.js，绝不使用 modules/<slug>/index.js 或 main.py，也不将模块文件直接放在 modules/ 下。变量通过 variables.env 管理，运行时经 fcode.env.* 读取。调度、数据存储、邮件、版本与别名均通过对应助手或 Web UI 操作。CLI 工作区结构包含 dependencies、i18n、modules 等目录。
适用场景
企业集成与自动化：编写业务流程、封装 API 客户端与集成、跨流程共享代码、管理配置与密钥、持久化跨运行状态、存储文件、发送交易邮件、按计划运行任务、通过版本与别名进行发布与回滚。
限制
- 数据存储仅存字符串和数字，对象需 JSON.stringify / json.dumps 序列化后 set，get 时解析。
- 绝不整体覆盖 variables.env，先读取再仅追加/修补特定变量。
- 绝不编辑继承资源（variables.inherited.env、i18n/<locale>.inherited.yaml、继承的流程/模块）。
- 绝不硬编码或记录密钥。
- 运行时固定：JavaScript = Node.js v22，Python = 3.13。
- 限制按工作区固定：每次执行 12 小时、50 个并发执行、50 req/s、返回值 500 KB、每个数据存储条目 50 KB。提高限制需请求，而非更改计划。
- 每次执行默认最多 3 封邮件。
- 每个工作区数据存储条目 20,000 个；存储文件 1,000 个、每个 50 MB。
- 输入参数文本 500 KB、文件总计 15 MB；执行日志 500 行和 500 KB。
- 流程、表单、依赖、执行次数每天/每月无限制。
命名约定
流程 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()）。
决策指南
- 多个流程使用的 API 客户端：创建模块。
- 使用 2 次以上的工具助手：创建模块。
- 一次性转换/单次逻辑：保持内联。
- 很少变化的配置、密钥/凭据：变量。
- 运行间变化的状态、缓存的 API 响应：数据存储。
- 流程获取且需跨运行保留的密钥（OAuth 令牌）：数据存储，set(key, value, true)。
- 二进制文件/大型导出：文件存储。