Fractalic：用可执行Markdown重构AI工作流开发与自动化

1. 项目概述：用Markdown文件驱动AI工作流

如果你和我一样，每天都要和各种各样的AI模型、API工具打交道，那你肯定也经历过这种痛苦：为了完成一个简单的任务，比如“搜一下今天的AI新闻，然后整理好发到Notion”，你得写一个Python脚本，调用OpenAI的API，再调Tavily的搜索接口，最后还得处理Notion的OAuth认证和页面创建。代码越写越长，依赖越来越多，调试起来像在走迷宫。更别提想换个模型试试效果，或者把其中一步换成别的工具了——那基本等于重写。

这就是为什么当我第一次看到Fractalic这个项目时，有种“终于等到你”的感觉。它的核心思想极其简单，却又充满力量：用一个可执行的Markdown文件，来定义和运行你的整个AI工作流。没有胶水代码，没有复杂的YAML配置，就是纯文本的Markdown，加上几行类似YAML的指令。你写下的文档，本身就是可以运行的“程序”。

想象一下，你有一个daily_news.md文件，里面写着“搜一下AI新闻，总结成五点，发到Notion”。你只需要在命令行输入fractalic daily_news.md，它就能自动调用对应的AI模型和工具，一步步执行，并把每一步的结果和变化都记录在同一个文件里，形成一个完整、可追溯的执行日志。这不仅仅是自动化，这是一种全新的、以文档为中心的AI应用开发范式。它特别适合需要快速原型验证的AI工程师、希望将复杂手动流程自动化的运营人员，以及任何厌倦了在代码和文档之间反复横跳的开发者。

2. 核心理念与架构设计解析

2.1 为什么是“可执行的Markdown”？

传统的AI工作流开发存在一个根本性的割裂：设计（文档）和实现（代码）是分离的。你可能会在Notion里写下流程步骤，然后在IDE里用Python实现。一旦需求变更，你需要同时更新文档和代码，很容易出现不同步。

Fractalic提出的“可执行Markdown”理念，旨在彻底消除这种割裂。它的设计基于几个关键洞察：

1. 文档即运行时：你的工作流规格说明（Markdown）就是可以直接执行的“源代码”。你不再需要将自然语言描述“翻译”成编程语言。你写下的“搜索新闻”指令，会由Fractalic解释器直接理解并分派给合适的工具（如tavily_search）执行。
2. 上下文作为可寻址树：Fractalic将整个Markdown文档解析为一棵结构化的树。每个标题（#,##,###）及其下的内容构成一个独立的“块”（Block）。这些块拥有唯一的标识符（通常是标题文本转换成的kebab-case，如# AI新闻变成ai-news）。工作流中的操作（如@llm）可以精确地引用（block:参数）或修改（to:参数）特定的块。这实现了精确的上下文控制——AI模型在每一步只能看到你明确指定的内容，没有隐藏的提示词污染。
3. 无胶水代码的编排：Fractalic内置了一套核心操作（@llm,@shell,@run,@import,@return），这些操作以简洁的YAML语法嵌入在Markdown中。它们取代了传统编排中大量的if-else逻辑、错误处理和结果传递代码。工具的输出会自动作为新的块插入文档树，供后续操作使用，形成了一个天然的、可视化的数据流。

这种架构带来的直接好处是极致的可读性和可维护性。一个新同事接手你的项目，他不需要理解复杂的Python异步框架，只需要阅读这个Markdown文件，就能立刻明白整个工作流在做什么、怎么做。版本控制（Git）也变得无比清晰，因为每一次运行的差异（Diff）都直接体现在Markdown文件的内容变化上。

2.2 核心操作引擎：工作流的原子指令

Fractalic的工作流由一系列顺序执行的“操作”构成。你可以把它们理解为这个领域的“汇编指令”，虽然高级，但足够基础来构建任何复杂流程。理解这五个核心操作是掌握Fractalic的关键：

1. @llm：这是最常用的操作。它负责与AI模型对话。你需要指定一个prompt（指令），并可以可选地提供tools（工具列表，如tavily_search）、block（要引用的上下文块）、model（使用的模型，如openai/gpt-4）等参数。它的执行结果是，模型的回复（包括可能的工具调用和响应）会作为一个新的“LLM响应块”插入到文档中。
2. @shell：用于执行系统命令。这是连接外部世界和本地环境的桥梁。比如，你可以用@shell调用curl下载文件、用ffmpeg处理媒体、或者运行一个本地Python脚本。命令的stdout和stderr会被捕获并作为新的块插入。
3. @run：实现工作流的模块化和复用。你可以在一个主工作流中，使用@run操作来调用另一个Fractalic Markdown文件（子工作流）。参数可以通过文件路径或内联内容传递，子工作流的@return操作结果会被带回到主工作流。这让你可以像编写函数一样编写和组合复杂的工作流。
4. @import：用于将外部文件的内容静态地包含到当前文档的指定位置。这与@run的动态执行不同，@import更像是编译时的“复制粘贴”，适用于引入模板、配置或静态数据。
5. @return：专门用于被@run调用的子工作流中，用于向父工作流返回指定的数据块。这定义了子工作流的“输出接口”。

实操心得：理解“块”的生命周期每个操作执行后，都会在文档中生成新的内容块。这些块默认会追加在文档末尾。但通过mode: replace和to:参数，你可以让新内容替换掉已有的某个块。这种“块”的创建、引用和替换机制，是Fractalic实现动态数据流和上下文管理的基石。在设计工作流时，要有意识地规划好块的命名和流向，这能让流程更清晰。

2.3 工具集成生态：MCP与内置工具

工具是AI的“手和脚”。Fractalic在工具集成上做得非常出色，主要通过两种方式：

1. 内置工具：开箱即用，如示例中的tavily_search（网络搜索）、shell_tool（执行命令）。这些工具经过封装，使用起来非常简单，只需在@llm操作的tools参数中列出即可。

2. MCP（Model Context Protocol）集成：这是Fractalic的一大亮点。MCP是一种新兴的开放协议，旨在为AI模型提供标准化的工具调用接口。Fractalic内置了完整的MCP客户端支持。

这意味着，任何实现了MCP服务器的服务（如Notion、GitHub、Jira，甚至是你的内部数据库），都可以被Fractalic工作流直接调用。项目提到了“MCP市场”，你可以像安装插件一样，一键添加新的工具服务。例如，连接Notion的MCP服务器后，你的工作流中就可以使用tools: mcp/notion来创建页面、查询数据库。

注意事项：MCP的配置与认证使用MCP工具通常需要先完成服务配置和OAuth 2.0等认证流程。Fractalic Studio（其IDE）提供了图形化的MCP管理界面，大大简化了这一过程。但在纯CLI环境下，你可能需要手动配置环境变量或认证文件。初次使用复杂MCP工具时，建议先在Studio中完成连接测试，再迁移到纯文件工作流。

3. 从零开始：五种部署与使用方式详解

Fractalic提供了极高的灵活性，你可以根据使用场景选择最适合的安装方式。下面我将逐一拆解，并分享我的选择建议和踩坑经验。

3.1 方法一：Docker一键部署（推荐给大多数用户）

这是最快速、最完整的上手方式，尤其适合想立即体验所有功能（包括Web IDE - Fractalic Studio）的用户。

docker run -d \ --name fractalic \ --network bridge \ -p 3000:3000 \ -p 8000:8000 \ -p 8001:8001 \ -p 5859:5859 \ -v /var/run/docker.sock:/var/run/docker.sock \ --env HOST=0.0.0.0 \ ghcr.io/fractalic-ai/fractalic:main

命令参数解析：

• -p 3000:3000：映射Fractalic Studio Web界面，访问http://localhost:3000。
• -p 8000:8000：映射后端REST API端口。
• -p 8001:8001：映射AI服务器端口（用于处理模型请求）。
• -p 5859:5859：映射MCP管理器端口。
• -v /var/run/docker.sock:/var/run/docker.sock：关键参数。这将宿主机的Docker守护进程套接字挂载到容器内，使得Fractalic Studio能够从内部启动和管理其他Docker容器（例如，用于部署你创建的工作流）。没有这个权限，部署功能会受限。
• --env HOST=0.0.0.0：让服务监听所有网络接口，方便从宿主机访问。

启动后验证：

1. 打开浏览器，访问http://localhost:3000。你应该能看到Fractalic Studio的登录/注册界面。
2. 首次使用需要创建一个账户。这账户信息是本地存储的，用于管理你的项目和工作流会话。
3. 进入主界面后，你可以创建新的.md文件，开始编写和运行工作流。

踩坑记录：Docker socket权限问题在Linux系统上，/var/run/docker.sock通常属于root用户和docker组。如果你在运行上述docker run命令时遇到权限错误，有两种解决方案：

1. （推荐）将当前用户加入docker组：sudo usermod -aG docker $USER，然后注销并重新登录生效。
2. 使用sudo运行Docker命令，但这可能带来安全风险。 在MacOS的Docker Desktop下，通常不会遇到此问题。

3.2 方法二：从源码构建（适合开发者与定制）

如果你想体验最新特性，或者需要修改源码，这是最佳选择。这个脚本会拉取前后端所有代码，在本地构建Docker镜像。

curl -s https://raw.githubusercontent.com/fractalic-ai/fractalic/main/deploy/docker-deploy.sh | bash

这个脚本做了以下几件事：

1. 克隆fractalic-ai/fractalic（后端）和fractalic-ai/fractalic-ui（前端）仓库。
2. 在本地构建一个包含所有服务的Docker镜像。
3. 启动容器，映射的端口与方式一相同。

优缺点分析：

• 优点：获取的是主分支最新代码，包含尚未发布到Docker Hub的特性。构建过程透明，适合调试。
• 缺点：依赖本地构建环境，耗时较长（首次构建可能需要10-20分钟）。如果GitHub网络不畅，脚本可能失败。

3.3 方法三：本地开发环境搭建（深度开发必备）

如果你打算为Fractalic贡献代码，或者进行深度二次开发，需要完整的本地开发环境。

git clone https://github.com/fractalic-ai/fractalic.git cd fractalic ./local-dev-setup.sh

这个脚本会：

1. 克隆前端UI仓库到同级目录。
2. 为后端创建Python虚拟环境并安装所有依赖。
3. 安装前端依赖（Node.js）。
4. 同时启动后端开发服务器和前端开发服务器。
5. 自动打开浏览器。

开发体验：

• 后端运行在http://localhost:8000，支持热重载。
• 前端运行在http://localhost:3000，同样支持热重载。
• 你可以直接修改前后端代码，并立即在浏览器中看到变化。这是参与开源贡献的标准流程。

3.4 方法四：Python包 - CLI模式（轻量级、自动化首选）

对于只需要在服务器或命令行中自动化运行工作流的场景，这是最简洁、最资源高效的方式。它只包含Fractalic的核心运行时，没有Web界面。

# 安装 pip install fractalic # 验证安装 fractalic --help # 运行一个工作流文件 fractalic my_workflow.md

核心优势：

• 轻量：仅安装必要的Python依赖，不启动任何常驻服务。
• 易于集成：可以轻松地集成到CI/CD流水线、定时任务（cron）或现有的Python项目中。
• 资源消耗低：适合在资源受限的环境（如小型VPS）中运行后台任务。

典型使用场景：

• 每天凌晨2点自动运行一个数据抓取和报告生成工作流。
• 作为Webhook的响应器，接收请求后触发特定的Fractalic工作流。
• 在数据分析管道中，作为一个处理环节被调用。

3.5 方法五：Python包 - API模式（嵌入式调用）

如果你希望在自己的Python应用程序中调用Fractalic工作流，将其作为一个库来使用，那么API模式就是为你设计的。

import fractalic # 最基本的使用：运行一个工作流文件 result = fractalic.run_fractalic('workflow.md') print(result['success']) # True or False print(result['ctx_file']) # 生成的上下文文件路径 # 带参数运行：向工作流传递动态输入 result = fractalic.run_fractalic( 'analyze_company.md', param_input_user_request='分析特斯拉2024年Q1财报' ) # 自定义模型和API密钥：覆盖工作流文件中的默认设置 result = fractalic.run_fractalic( 'creative_writing.md', model='anthropic/claude-3-opus', api_key='your-anthropic-api-key-here' ) # 结果字典结构详解 result = fractalic.run_fractalic('workflow.md') """ result 是一个字典，包含： - 'success': bool, 执行是否成功。 - 'branch_name': str, 本次执行创建的分支名（用于版本追踪）。 - 'ctx_file': str, 生成的上下文文件(.ctx)路径，包含了完整的执行状态。 - 'ctx_hash': str, 上下文的哈希值，唯一标识此次运行。 - 'output': str, 工作流的最终文本输出（取决于工作流设计）。 - 'error': str, 如果失败，错误信息。 """

设计模式建议：你可以将复杂的业务逻辑封装在不同的.md工作流文件中，然后在主Python程序中根据条件动态选择并执行它们。这实现了业务逻辑（Markdown）与控制逻辑（Python）的分离，让两者都更易于维护。

4. 实战进阶：核心模式与复杂工作流构建

掌握了基础操作和部署，我们来看看如何用Fractalic解决实际问题。下面通过几个扩展案例，深入讲解高级模式和设计思想。

4.1 模式一：条件判断与分支执行

Fractalic本身没有传统的if-else语句。但我们可以利用@llm的推理能力和@run操作来实现动态分支。

场景：根据用户查询的意图，自动选择不同的处理子流程（如“查询天气”、“搜索新闻”、“计算数学”）。

# 主路由工作流：intent_router.md ## 用户输入 用户说：{{user_query}} ## 意图分析 请分析用户的输入“{{user_query}}”，判断其属于以下哪类意图： 1. weather_query: 询问天气、温度、降水。 2. news_search: 搜索新闻、时事、资讯。 3. math_calculation: 计算、数学问题、公式。 4. other: 其他任何类型。 请只输出意图的英文关键词，例如：weather_query @llm model: openai/gpt-4o-mini prompt: 分析用户意图，只输出关键词。 block: - 用户输入 - 意图分析 ## 动态路由 根据上面分析出的意图，执行对应的子工作流。 @run file: | {% if llm_response contains "weather_query" %} ./workflows/weather.md {% elif llm_response contains "news_search" %} ./workflows/news.md {% elif llm_response contains "math_calculation" %} ./workflows/math.md {% else %} ./workflows/fallback.md {% endif %} params: user_query: "{{user_query}}"

如何运行：

fractalic intent_router.md --param user_query="上海明天天气怎么样？"

原理解析：

1. 第一个@llm操作分析用户输入，输出一个意图关键词。
2. 在@run操作中，我们使用了内联文件内容（file: |），并嵌入了一个简单的模板逻辑。Fractalic会解析{% if ... %}标签（这是一个类Jinja2的模板语法），根据上一步@llm输出的llm_response块的内容，动态决定加载哪个子工作流文件。
3. params将用户查询传递给子工作流。

子工作流示例 (weather.md)：

# 天气查询子流程 ## 接收参数 查询城市：{{user_query}} ## 提取城市名 从“{{user_query}}”中提取出城市名称，例如“上海明天天气怎么样？”应提取出“上海”。只输出城市名。 @llm prompt: 提取城市名。 block: 接收参数 ## 调用天气API 使用工具获取 {{llm_response}} 的天气信息。 @llm prompt: 获取上述城市的天气。 tools: weather_tool # 假设已配置天气MCP工具 ## 格式化回复 将天气信息整理成对用户友好的回复。 @llm prompt: 将以下天气数据转化为一句简短的中文回复。 block: - 调用天气API

这个模式展示了如何构建一个简单的“AI路由器”，实现了基于内容的动态工作流组合。

4.2 模式二：循环与迭代处理

Fractalic没有显式的循环语法，但通过@run操作递归调用自身，或者结合@llm生成批量操作，可以实现迭代。

场景：批量处理一个文件列表中的每个文件。

# 批量文件处理：batch_process.md ## 待处理文件列表 - documents/report1.pdf - documents/report2.pdf - documents/report3.pdf ## 处理单个文件的通用子流程 我们有一个子工作流 `process_single_file.md`，它接受一个 `file_path` 参数，并返回处理结果。 ## 生成批量调用指令 请为“待处理文件列表”中的每一个文件路径，生成一行 `@run` 操作，调用 `process_single_file.md`，并传入对应的 `file_path` 参数。每个操作之间用空行隔开。 @llm prompt: 生成批量@run指令。 tools: fractalic_opgen block: - 待处理文件列表 - 处理单个文件的通用子流程 ## 执行批量处理 # 以下是生成的指令，将被执行 {{llm_response}}

执行过程：

1. 第一个@llm操作配合fractalic_opgen工具，会分析文档，生成类似下面的内容：

   @run file: ./process_single_file.md params: file_path: "documents/report1.pdf" @run file: ./process_single_file.md params: file_path: "documents/report2.pdf" @run file: ./process_single_file.md params: file_path: "documents/report3.pdf"

2. 由于llm_response块包含了有效的Fractalic操作，当解释器继续执行时，会依次执行这三个@run操作，从而实现循环效果。

注意事项：循环的终止条件这种“AI生成循环”的模式非常灵活，但需要注意控制循环次数和资源消耗。避免在循环内调用成本高昂的模型或API。对于已知的、确定的列表，上述模式很好。对于不确定数量的迭代，可能需要更复杂的逻辑，比如让AI在每次迭代后判断是否继续。

4.3 模式三：错误处理与重试机制

健壮的生产级工作流必须处理失败。Fractalic可以通过@run和状态检查来实现简单的错误恢复。

场景：调用一个可能失败的外部API（如支付网关），失败后重试最多3次。

# 带重试的API调用 ## 配置 最大重试次数: 3 当前重试次数: 0 目标API: https://api.example.com/process ## 执行支付 尝试调用支付API。 @shell cmd: | curl -X POST "{{目标API}}" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $API_KEY" \ -d '{"amount": 100, "currency": "USD"}' \ --max-time 30 \ --retry 2 \ --retry-delay 1 \ --fail if [ $? -eq 0 ]; then echo "STATUS: SUCCESS" echo "RESPONSE: $(cat)" else echo "STATUS: FAILED" echo "ERROR_CODE: $?" fi ## 检查结果 检查上一步shell命令的输出，判断是否成功。 @llm prompt: 检查下面的输出。如果包含“STATUS: SUCCESS”，则只输出“SUCCESS”；否则输出“FAILED”。 block: 执行支付 ## 决策与重试 根据检查结果决定下一步。 @run file: | {% if llm_response == "FAILED" %} {% if 当前重试次数 < 最大重试次数 %} # 重试逻辑 当前重试次数: {{当前重试次数 + 1}} 记录: 第{{当前重试次数}}次重试失败，等待2秒后重试。 @shell cmd: sleep 2 @run file: ./带重试的API调用.md params: 当前重试次数: {{当前重试次数}} 最大重试次数: {{最大重试次数}} {% else %} # 最终失败 记录: 已达到最大重试次数({{最大重试次数}})，任务最终失败。 @return block: 记录 {% endif %} {% else %} # 成功 记录: API调用成功！ @return block: 记录 {% endif %} params: 当前重试次数: "{{当前重试次数}}" 最大重试次数: "{{最大重试次数}}"

原理解析： 这是一个递归重试模式。主工作流执行API调用并检查结果。如果失败，且未达重试上限，它会通过@run递归调用自身，并将当前重试次数加1后作为参数传入。直到成功或超过重试次数为止。成功或最终失败时，使用@return将结果返回给可能的父工作流。

实操心得：状态保持在这个模式中，当前重试次数是作为一个“参数”在每次递归调用中传递的。Fractalic工作流本身是无状态的，状态需要通过块内容或参数来显式传递。设计这类流程时，清晰定义哪些是“状态变量”并管理好它们的传递路径至关重要。

5. 开发、调试与部署实战

5.1 使用Fractalic Studio进行可视化开发

对于复杂工作流，图形化界面能极大提升效率。Fractalic Studio正是为此而生。

核心功能体验：

1. 笔记本式编辑器：左侧是Markdown/YAML编辑器，右侧是实时预览。你可以边写边看块的结构。点击任意块旁边的“运行”按钮，可以单独执行该块之后的操作，非常适合分段调试。
2. 执行追踪与Diff视图：每次运行后，Studio会生成一个清晰的Diff视图，用绿色（新增）和红色（删除）高亮显示本次运行对文档所做的所有更改。这比看日志直观得多，你能一眼看出AI修改了哪里、工具输出了什么。
3. 调试检查器：点击Diff中的任何步骤，可以打开检查器，查看该步骤的详细输入、输出、工具调用请求和响应、令牌使用情况以及完整的AI消息历史。这是排查“为什么AI不按我想的做”的利器。
4. MCP工具市场：在Studio中，你可以浏览和安装MCP工具。例如，找到“Notion”工具，点击连接，按照指引完成OAuth授权，之后你的工作流中就可以直接使用tools: mcp/notion了。这省去了手动配置环境变量和认证文件的麻烦。
5. 部署面板：当你完成一个工作流的开发，可以一键将其“发布”。Fractalic会为你的工作流生成一个Docker镜像，并提供一个轻量级的REST API服务器。你会在部署面板获得一个API端点，例如http://localhost:8080/run，可以通过HTTP POST请求触发工作流执行。

开发工作流建议：我习惯在Studio中完成工作流的原型设计和初步测试，利用其强大的可视化调试能力。待流程稳定后，再将最终的.md文件保存出来，用于命令行或API模式的自动化部署。这样结合了交互式开发的便利和纯文本的便携性。

5.2 性能调优与成本控制

用Fractalic跑生产任务，必须关注效率和成本。

1. 上下文压缩是必修课：如基础示例所示，大量使用mode: replace。不要让无关的历史对话或冗长的工具输出堆积在上下文中。在每一步之后，思考“下一步真的需要所有这些信息吗？”，如果不需要，就用一个总结性的@llm操作替换掉大段内容。
2. 模型选择策略：在@llm操作中显式指定model参数。为不同的任务选择合适的模型：
   • 复杂推理/规划：使用能力强的模型，如openai/gpt-4、anthropic/claude-3-opus。
   • 简单提取/格式化：使用便宜快速的模型，如openai/gpt-4o-mini、anthropic/claude-3-haiku。
   • 本地实验：可以配置ollama/llama3.2等本地模型，实现零成本迭代。
3. 利用操作缓存：Fractalic Studio和高级CLI版本支持操作缓存。如果某次@llm操作的输入（提示词+上下文+参数）完全一样，且模型也相同，系统可能会直接返回缓存的结果，跳过实际的API调用，显著节省成本和时间。在开发时注意，如果需要强制刷新，可以微调提示词或增加一个随机参数。
4. 令牌使用分析：关注Studio调试器或CLI输出中的令牌计数。了解哪些步骤消耗最多令牌，并针对性优化。例如，是否向模型传递了过长的参考文档？是否可以通过更精确的block引用减少输入长度？

5.3 生产环境部署指南

将Fractalic工作流部署为常驻服务，推荐以下架构：

方案A：使用Fractalic Publisher（内置）这是最简单的方式。在Fractalic Studio中点击“发布”，它会生成一个包含你工作流的Docker镜像。你可以使用其自带的轻量级服务器（通常基于FastAPI），它提供了：

• REST API端点 (/run) 触发执行。
• 可选的API密钥认证。
• 自动生成的Swagger/OpenAPI文档。
• 基本的请求队列和并发控制。

部署命令示例：

# 假设发布的镜像名为 my-workflow:latest docker run -d \ -p 8080:8000 \ -e OPENAI_API_KEY=sk-... \ -e ANTHROPIC_API_KEY=sk-ant-... \ my-workflow:latest

然后通过curl -X POST http://localhost:8080/run -d '{"param_input": "value"}'调用。

方案B：将Fractalic作为Python库集成对于需要更复杂业务逻辑、用户认证、数据库交互的场景，可以将Fractalic嵌入到你自己的FastAPI或Django应用中。

# 在你的FastAPI应用中 from fastapi import FastAPI, HTTPException import fractalic import asyncio from concurrent.futures import ThreadPoolExecutor app = FastAPI() executor = ThreadPoolExecutor(max_workers=4) # 控制并发 @app.post("/run-workflow") async def run_workflow(workflow_data: dict): workflow_file = workflow_data.get("file", "default.md") user_input = workflow_data.get("input", "") try: # 在线程池中运行，避免阻塞事件循环 loop = asyncio.get_event_loop() result = await loop.run_in_executor( executor, fractalic.run_fractalic, workflow_file, {"param_input_user_request": user_input} ) if result['success']: return {"status": "success", "output": result.get('output', '')} else: return {"status": "error", "message": result.get('error', 'Unknown error')} except Exception as e: raise HTTPException(status_code=500, detail=str(e))

这种方案给你最大的控制权，可以集成日志、监控、报警、数据库持久化等企业级功能。

安全警告：API密钥管理永远不要将API密钥硬编码在Markdown工作流文件中。务必通过环境变量（OPENAI_API_KEY,ANTHROPIC_API_KEY等）传入。在Docker部署中，使用-e标志或Docker secrets。在Kubernetes中，使用Secrets。Fractalic会优先使用环境变量中的密钥。

6. 常见问题与故障排查实录

即使设计得再完美，实际运行中总会遇到问题。下面是我在大量使用Fractalic后总结出的“排错手册”。

6.1 问题：@llm操作无响应或报错“No model configured”

症状：运行工作流时，@llm步骤卡住，或者在日志/Studio中看到模型未配置的错误。

排查步骤：

1. 检查环境变量：这是最常见的原因。确保已设置正确的API密钥环境变量。

   # 检查变量是否存在 echo $OPENAI_API_KEY echo $ANTHROPIC_API_KEY # 如果没有，请设置 export OPENAI_API_KEY='sk-your-key-here'

2. 检查模型名称：在@llm操作中指定的model参数必须与LiteLLM支持的模型格式匹配。例如：
   • openai/gpt-4o
   • anthropic/claude-3-haiku
   • ollama/llama3.2(需要本地运行Ollama)
   • 如果不指定model，Fractalic会使用默认模型，你需要在全局配置或环境变量中设置DEFAULT_MODEL。
3. 验证LiteLLM连接：Fractalic通过LiteLLM调用模型。可以单独测试LiteLLM：

   litellm --model openai/gpt-4o --prompt "hello"

   如果失败，说明是LiteLLM配置或网络问题。
4. 查看详细日志：在CLI中增加--verbose标志，或在Studio中打开检查器，查看发送给模型的原始请求和错误响应。

6.2 问题：工具调用失败，提示“Tool X not found”或认证错误

症状：工作流在调用tavily_search或mcp/notion等工具时失败。

排查步骤：

1. 对于内置工具（如tavily_search）：
   • 需要配置对应的API密钥环境变量，如TAVILY_API_KEY。
   • 查阅Fractalic或LiteLLM文档，确认工具名称是否正确。
2. 对于MCP工具（如mcp/notion）：
   • 确保MCP服务器已启动并连接：在Fractalic Studio中，进入“MCP Manager”页面，查看对应工具的状态是否为“Connected”。
   • 检查OAuth配置：许多MCP工具需要OAuth授权。通常需要在Studio内点击“Connect”按钮，在打开的页面中完成授权流程。如果是在CLI下，可能需要手动配置token文件，路径通常为~/.config/fractalic/mcp/servers.json。
   • 验证工具权限：某些工具可能需要特定权限（如Notion的write权限），在授权时请确保已勾选。
3. 网络与防火墙：确保运行Fractalic的机器可以访问工具对应的外部API端点。

6.3 问题：@shell操作权限不足或命令未找到

症状：@shell操作失败，返回Permission denied或command not found。

排查步骤：

1. 容器环境下的路径问题：如果你在Docker容器中运行Fractalic，容器内可能没有你需要的命令行工具（如jq,pandoc,imagemagick）。你需要构建自定义Docker镜像，在Dockerfile中安装这些依赖。

   FROM ghcr.io/fractalic-ai/fractalic:main RUN apt-get update && apt-get install -y curl jq python3-pip && pip3 install some-package

2. 用户权限：@shell操作以运行Fractalic进程的用户身份执行。如果命令需要sudo或访问特定目录，可能会失败。考虑：
   • 调整文件系统权限。
   • 在安全可控的前提下，以更高权限运行Fractalic服务（不推荐）。
   • 将需要特权的操作封装到具有适当权限的独立脚本中，然后通过@shell调用该脚本。
3. 命令路径：使用绝对路径调用命令，例如/usr/bin/curl而不是curl，以避免环境变量PATH不一致导致的问题。

6.4 问题：工作流逻辑错误，AI不按预期执行

症状：工作流能跑通，但结果不对。例如，AI没有使用指定的工具，或者误解了指令。

排查步骤：

1. 精炼你的提示词：AI的表现极度依赖提示词。确保你的prompt清晰、无歧义、包含所有必要约束。例如，与其说“总结这篇文章”，不如说“用不超过三句话总结这篇文章的核心论点，并列出两个支持性论据”。
2. 检查上下文隔离：使用block参数确保AI只看到它需要的信息。无关的上下文会干扰判断。利用mode: replace及时清理过长的输出。
3. 启用工具调用追踪：在Studio的检查器中，展开@llm步骤，查看完整的AI消息历史和工具调用记录。这能让你看到模型“思考”的过程，理解它为什么做出了错误的选择。
4. 使用更强大的模型进行复杂规划：如果工作流涉及多步骤推理或复杂决策，尝试在关键的规划步骤使用GPT-4或Claude Opus等顶级模型，而在简单的执行步骤使用廉价模型。
5. 分步调试：不要一次性运行整个工作流。在Studio中，利用“运行到此处”或单独运行某个@llm操作的功能，逐步验证每一步的输出是否符合预期。

6.5 问题：性能瓶颈，工作流执行缓慢

症状：工作流执行时间过长，尤其是包含多个串行@llm调用时。

优化策略：

1. 并行化：如果多个@llm或@shell操作之间没有数据依赖，可以考虑让它们并行执行。Fractalic本身是顺序执行的，但你可以通过设计，将独立的任务拆分成多个独立的子工作流，然后由一个主工作流使用异步方式（如果未来Fractalic支持）或外部脚本并发触发它们。
2. 减少不必要的模型调用：审视每个@llm操作是否真的必要。能否用规则（正则表达式）或简单的文本处理代替？能否合并多个小提示词为一个？
3. 设置超时和重试：对于@shell或调用外部API的工具，总是设置合理的超时（在工具参数或shell命令中），并考虑实现前面提到的重试逻辑，避免单个步骤卡死整个流程。
4. 缓存昂贵操作的结果：如果某些步骤（如调用某个数据API）的结果在短时间内不会变化，可以考虑将结果存储在外部（如文件、数据库），并在工作流开始时检查是否存在可用的缓存，跳过重复调用。

经过这些深入的探索和实战，你应该已经感受到Fractalic所带来的范式转变。它不是一个简单的“AI自动化工具”，而是一个全新的、以文档和可解释性为核心的AI应用构建平台。它将工作流从晦涩的代码中解放出来，使其变得可读、可版本控制、可协作。虽然它在处理极端复杂的逻辑流时可能不如传统编程语言灵活，但对于占日常开发80%的那些胶水代码、数据搬运和简单决策任务，它的效率和优雅是无可比拟的。我的建议是，从一个小而具体的任务开始尝试，比如自动备份ChatGPT对话到Markdown，或者每天自动生成团队站会摘要。当你熟悉了它的思维模式后，你会发现自己能用它组合出意想不到的强大自动化系统。