fcode-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Factorial Code — agent workflow

Factorial Code — Agent工作流

How to build Factorial Code processes and modules through an iterative, confirmation-driven approach, using the Factorial Code MCP tools. Pair this with

fcode-core-concepts

fcode-javascript

fcode-python

, and

fcode-cli

如何通过迭代式、确认驱动的方法，使用Factorial Code MCP工具构建Factorial Code流程和模块。请结合

fcode-core-concepts

、

fcode-javascript

fcode-python

以及

fcode-cli

使用本工作流。

Core principles

核心原则

Explain before acting — describe what you'll do and why.
Confirm before changing — get explicit approval before significant or destructive changes (refactors, dependency changes, variable changes).
Iterate in small steps — deliver working increments, validate, then expand.
Be safe by default — never hardcode or log secrets.

行动前先说明——描述你要做什么以及原因。
变更前先确认——在进行重大或破坏性变更（重构、依赖变更、变量变更）前，需获得明确批准。
小步迭代——交付可运行的增量版本，验证后再扩展。
默认安全优先——切勿硬编码或记录机密信息。

Workflow

工作流

Phase 1 — Plan & confirm

阶段1——计划与确认

Before writing code or using any tool, produce a short plan and confirm it.

Analyze current context. Check the process language (
```
index.js
```
→ JS,
```
main.py
```
→ Python; new code must match), what the current script does, which variables/dependencies/modules already exist (don't remove or overwrite them).
Identify alternatives. For common needs (email, SMS, payments, storage), present options — third-party service vs direct protocol, library choices — with brief trade-offs, and ask the user to choose. Don't assume an approach when alternatives exist.
Identify needed components: config variables, secrets (the user must create these), input parameters (+ types), dependencies (verify they exist, prefer recent stable versions), and modules worth creating for reuse.
Define input-parameter requirements (fields, types, validations, any dynamic fields needing API calls). See
```
fcode-json-schema
```
.
Present the plan (what you'll build, variables you'll create vs the user must create, input parameters, dependencies, reusable modules, expected behavior) and ask "Shall I proceed?"
Wait for explicit confirmation before proceeding.

在编写代码或使用任何工具之前，制定简短计划并获得确认。

分析当前上下文。检查流程语言（
```
index.js
```
对应JS，
```
main.py
```
对应Python；新代码必须匹配现有语言）、当前脚本的功能、已存在的变量/依赖/模块（请勿删除或覆盖）。
确定替代方案。对于常见需求（邮件、短信、支付、存储），提供选项——第三方服务vs直接协议、库选择——并简要说明优缺点，请求用户选择。当存在替代方案时，不要默认采用某一种方法。
确定所需组件：配置变量、机密信息（需由用户创建）、输入参数（含类型）、依赖项（验证是否存在，优先选择近期稳定版本），以及值得创建的可复用模块。
定义输入参数要求（字段、类型、验证规则、需要API调用的动态字段）。详见
```
fcode-json-schema
```
。
提交计划（你将构建的内容、你创建的变量vs用户必须创建的变量、输入参数、依赖项、可复用模块、预期行为），并询问“是否可以开始？”
等待明确确认后再继续。

Phase 2 — Iterative development

阶段2——迭代开发

Work in small steps, confirming at each one.

Iteration 1 (setup & discovery): create config variables and ask the user to create the sensitive ones; if useful, write a discovery script and run it with
```
run_code
```
to validate connectivity and learn the API/data shapes. Share results.
- When a secret value is needed for discovery/testing, ask the user for it — or, if they prefer not to share it, ask them to put it in
```
variables.local.env
```
  themselves. For
```
FACTORIAL_TOKEN
```
  , follow the OAuth procedure in
```
fcode-cli
```
  .
- Remind the user that local secret values aren't pushed — they must create those variables manually in the remote demo environment (except
```
FACTORIAL_TOKEN
```
  , which is auto-populated remotely).
Iteration 2+: for each step — explain it, get confirmation, implement following the language code rules (validation, error handling, logging), validate pieces with
```
run_code
```
, then create/update the process (code, parameters, descriptions). Tell the user what changed and let them review before the next iteration.

分小步骤推进，每一步都需确认。

迭代1（设置与发现）：创建配置变量，请求用户创建敏感变量；如有必要，编写发现脚本并通过
```
run_code
```
运行，以验证连通性并了解API/数据结构。分享结果。
- 当发现/测试需要机密值时，请求用户提供——或者如果用户不愿分享，请求他们自行将其放入
```
variables.local.env
```
  。对于
```
FACTORIAL_TOKEN
```
  ，请遵循
```
fcode-cli
```
  中的OAuth流程。
- 提醒用户本地机密值不会被推送——他们必须在远程演示环境中手动创建这些变量（
```
FACTORIAL_TOKEN
```
  除外，它会在远程环境中自动填充）。
迭代2及以后：每一步——先说明内容，获得确认，遵循语言代码规则实现（验证、错误处理、日志记录），通过
```
run_code
```
验证代码片段，然后创建/更新流程（代码、参数、描述）。告知用户变更内容，让他们在进入下一次迭代前进行审核。

Phase 3 — Test & refine (via the CLI)

阶段3——测试与优化（通过CLI）

Propose a full execution test using the

fcode

CLI (see

fcode-cli

), get confirmation, run it with test parameters, review results together, and iterate. Then offer next steps: scheduling, webhooks (public, inheriting the workspace

webhookAuth

configuration, or with their own header and team variable), a form (public, or restricted to Factorial users), or exposing the process as an MCP tool — and pushing to cloud when ready. Pushing never affects consumers pinned to the

stable

alias (model in

fcode-core-concepts

); don't create workspace versions or move

stable

unless explicitly asked.

建议使用

fcode

CLI进行完整执行测试（详见

fcode-cli

），获得确认后，使用测试参数运行，共同审查结果并迭代。然后提供后续步骤：调度、Webhook（公开、继承工作区

webhookAuth

配置，或使用自定义头部和团队变量）、表单（公开或仅限Factorial用户访问），或将流程暴露为MCP工具——准备就绪后推送到云端。推送操作不会影响固定到

stable

别名的使用者（详见

fcode-core-concepts

中的模型）；除非明确要求，否则不要创建工作区版本或移动

stable

别名。

Creating MCP tools

创建MCP工具

Do not write standalone MCP server code. Any Factorial Code process becomes an MCP tool: (1) create a process implementing the logic, (2) define its input parameters via

parametersSchema.json

(they become the tool's parameters), (3) tag the process (e.g.

mcp-tool

). It's then automatically available in any MCP client connected to the Factorial Code MCP Server — tag and go.

请勿编写独立的MCP服务器代码。任何Factorial Code流程都可成为MCP工具：(1) 创建实现逻辑的流程；(2) 通过

parametersSchema.json

定义其输入参数（这些参数将成为工具的参数）；(3) 为流程添加标签（例如

mcp-tool

）。之后，它会自动在连接到Factorial Code MCP Server的任何MCP客户端中可用——添加标签即可完成。

Available MCP tools

可用的MCP工具

run_code
— execute JS/Python for validation and testing before updating process files.

yc_api_<method>
— manage Factorial Code resources (e.g.

yc_api_create_process

yc_api_update_process

yc_api_delete_process

get_locales
/
get_locale
/
save_locale
/
delete_locale
— manage workspace translation files.
```
save_locale
```
replaces the whole file, so read-modify-write when adding keys; model in
```
fcode-i18n
```
.
Use other Factorial Code MCP tools when needed.

run_code
——在更新流程文件前执行JS/Python以进行验证和测试。

yc_api_<method>
——管理Factorial Code资源（例如

yc_api_create_process

、

yc_api_update_process

、

yc_api_delete_process

）。

get_locales
/
get_locale
/
save_locale
/
delete_locale
——管理工作区翻译文件。
```
save_locale
```
会替换整个文件，因此添加键时需采用读取-修改-写入的方式；详见
```
fcode-i18n
```
中的模型。
根据需要使用其他Factorial Code MCP工具。

Code quality & security

代码质量与安全

Try/catch (try/except) with meaningful messages; validate all inputs (external ones included) at the start; log key steps; extract reusable logic into modules; clean up resources.
See the module-naming and
```
variables.env
```
gotchas in
```
fcode-core-concepts
```
.

使用try/catch（JS）或try/except（Python）并提供有意义的消息；在开始时验证所有输入（包括外部输入）；记录关键步骤；将可复用逻辑提取到模块中；清理资源。
详见
```
fcode-core-concepts
```
中的模块命名和
```
variables.env
```
注意事项。

Error handling

错误处理

Explain what went wrong, propose a fix, and get confirmation — don't silently retry or trial-and-error. Ask the user instead of guessing on: ambiguous requirements, missing info (credentials, endpoints, package names), repeated failures, architecture or trade-off decisions, security concerns, or an unclear root cause.

说明问题所在，提出修复方案并获得确认——不要静默重试或反复试错。遇到以下情况时请询问用户而非猜测：模糊的需求、缺失的信息（凭证、端点、包名）、重复失败、架构或权衡决策、安全问题，或不明确的根本原因。

Example

示例

For a full worked example of this workflow (a Shopify → email integration), read

references/example-interaction.md

关于本工作流的完整示例（Shopify → 邮件集成），请阅读

references/example-interaction.md

。