Factorial Code — agent 工作流
本文档介绍如何通过迭代式、以确认为驱动的方法，使用 Factorial Code MCP 工具构建 Factorial Code 流程与模块。建议与 fcode-core-concepts、fcode-javascript/fcode-python 以及 fcode-cli 配合使用。
一、核心原则
行动前先解释——描述将要做什么以及为什么。 变更前先确认——在进行重大或破坏性变更（重构、依赖变更、变量变更）前获得明确批准。 以小步迭代——交付可工作的增量，验证后再扩展。 默认安全——绝不硬编码或记录密钥。
二、工作流
阶段 1 — 规划与确认
在编写代码或使用任何工具之前，产出一份简短计划并确认。
分析当前上下文。检查流程语言（index.js → JS，main.py → Python；新代码必须匹配），当前脚本的作用，以及已存在哪些变量/依赖/模块（不要删除或覆盖它们）。
识别可选方案。对于常见需求（邮件、短信、支付、存储），列出选项——第三方服务还是直接使用协议、库的选择——并简要说明权衡，让用户选择。存在替代方案时不要假定某一种做法。
识别所需组件：配置变量、密钥（需用户自行创建）、输入参数（含类型）、依赖（确认其存在，优先使用近期稳定版本），以及值得为复用而创建的模块。
定义输入参数要求（字段、类型、校验、任何需要调用 API 的动态字段）。参见 fcode-json-schema。
呈现计划（将构建什么、你要创建哪些变量而哪些需用户创建、输入参数、依赖、可复用模块、预期行为），并询问“是否继续？”。
在继续前等待明确确认。
阶段 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（公开、继承工作区 webhookAuth 配置，或使用自己的请求头和团队变量）、表单（所有表单都是公开的）、Factorial UI 内的按钮（fcode-ui-triggers），或任何其他 Factorial Action 入口点（fcode-factorial-actions），或将该流程暴露为 MCP 工具——并在准备好时推送到云端。推送不会影响固定到稳定别名的消费方（模型见 fcode-core-concepts）；除非明确要求，不要创建工作区版本或移动稳定版本。
三、创建 MCP 工具
不要编写独立的 MCP 服务器代码。任何 Factorial Code 流程都能成为 MCP 工具：(1) 创建一个实现该逻辑的流程，(2) 通过 parametersSchema.json 定义其输入参数（它们会成为工具的参数），(3) 为该流程打标签（例如 mcp-tool）。之后它就会自动出现在任何连接到 Factorial Code MCP Server 的 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。