fcode-agent

Factorial Code — Agent 工作流

如何通过迭代式、确认驱动的方式，使用 Factorial Code MCP 工具构建 Factorial Code 流程和模块。请搭配使用 fcode-core-concepts、fcode-javascript/fcode-python 和 fcode-cli。

核心原则

• 行动前先说明——描述你将采取的措施及其原因。
• 更改前先确认——在进行重大或具有破坏性的更改（重构、更改依赖项、更改变量）前，获取明确批准。
• 小步迭代——逐步交付可运行的增量，完成验证后再扩展。
• 默认保持安全——绝不硬编码或记录密钥。

工作流

阶段 1 — 规划并确认

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

1. 分析当前上下文。 检查流程使用的语言（index.js → JS， main.py → Python；新代码必须匹配）、当前脚本的功能，以及现有变量、依赖项和模块（不要删除或覆盖它们）。
2. 确定替代方案。 对于常见需求（电子邮件、短信、支付、存储），提供选项——第三方服务还是直接使用协议、库的选择——并简要说明利弊，请用户选择。存在替代方案时，不要擅自假设采用哪种方式。
3. **确定所需组件：**配置变量、密钥（必须由用户创建）、输入参数（及类型）、依赖项（确认其已存在，并优先选择近期稳定版本），以及值得创建以供复用的模块。
4. 定义输入参数要求（字段、类型、验证规则，以及任何需要调用 API 的动态字段）。请参阅 fcode-json-schema。
5. 呈现计划（将构建的内容、由你创建的变量与必须由用户创建的变量、输入参数、依赖项、可复用模块、预期行为），并询问“要继续吗？”
6. 等待明确确认后再继续。

阶段 2 — 迭代开发

分小步进行，每一步都要确认。

• 迭代 1（设置与探索）：创建配置变量，并请用户创建敏感变量；如有帮助，可编写探索脚本并使用 run_code 运行，以验证连接并了解 API/数据结构。 分享结果。
  • 如果探索或测试需要密钥值，请向用户索取；如果用户不愿分享，请让他们自行将密钥填入 variables.local.env。对于 FACTORIAL_TOKEN，请遵循 fcode-cli 中的 OAuth 流程。
  • 提醒用户：本地密钥值不会被推送——他们必须在远程演示环境中手动创建这些变量（FACTORIAL_TOKEN 除外，它会在远程环境中自动填充）。
• **迭代 2 及之后：**每一步都先说明并获得确认，再按照语言代码规则（验证、错误处理、日志记录）实现；使用 run_code 验证各部分，然后创建或更新流程（代码、参数、说明）。告知用户所做的更改，并让他们在开始下一次迭代前进行检查。

阶段 3 — 测试与完善（通过 CLI）

提出使用 fcode CLI 进行完整执行测试（参阅 fcode-cli），获得确认后，使用测试参数运行测试，与用户一起检查结果并迭代。 然后提供后续选项：安排运行时间、配置 webhook（公开 webhook、继承工作区的 webhookAuth 配置，或使用自定义请求头和团队变量）、创建表单（通过 Factorial 打开并验证用户身份）、在 Factorial 界面内添加按钮（fcode-ui-triggers），或使用其他 Factorial Action 入口（fcode-factorial-actions），或将流程公开为 MCP 工具——准备就绪后再推送到云端。推送不会影响固定使用 stable 别名的使用方（模型详见 fcode-core-concepts）；除非用户明确要求，否则不要创建工作区版本，也不要移动 stable。

创建 MCP 工具

不要编写独立的 MCP 服务代码。任何 Factorial Code 流程都可以成为 MCP 工具：（1）创建一个实现逻辑的流程；（2）通过 parametersSchema.json 定义其输入参数（这些参数将成为工具的参数）；（3）为流程添加标签（例如 mcp-tool）。之后，连接到 Factorial Code MCP 服务的任何 MCP 客户端都可以自动使用该工具——添加标签即可。

可用的 MCP 工具

• 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 工具。

代码质量与安全

• 使用带有明确消息的 try/catch（try/except）；在开始时验证所有输入（包括外部输入）；记录关键步骤；将可复用逻辑提取到模块中；清理资源。
• 请参阅 fcode-core-concepts 中关于模块命名和 variables.env 的注意事项。

错误处理

说明出了什么问题，提出修复方案并征求确认——不要悄悄重试或反复试错。遇到以下情况时，应询问用户，而不是猜测：需求含糊、缺少信息（凭据、端点、包名）、反复失败、架构或权衡决策、安全问题，或根本原因不明确。

示例

如需了解此工作流的完整示例（Shopify → 邮件集成），请阅读 references/example-interaction.md。