fsm-to-skill · 将复杂流程转换成状态机控制的 SKILL

让大模型回归“推理”本职，将“流程控制”交还给经典而严谨的有限状态机（FSM）。

基于状态机的完全本地化、轻量级 的 SKILL 编排与生成工具。 画布建流程，本地可调式，一键导出技能。

English · 使用文档 · License

当 Agent Skill 变得复杂...

流程失控与幻觉： 复杂的 Skill 往往包含各种分支判断和流程约束。随着冗余和冲突描述的增加，AI 越改越费力。Skill 越庞大和复杂，越容易诱发大模型的奖励黑客行为和逻辑幻觉。

维护成本: 复杂的 Skill 没有清晰的逻辑边界。 一旦业务逻辑发生变更，面对成百上千行的 Prompt，开发者难以进行有效的维护和迭代。 AI 越改越费力，SKILL越改越庞大。

关键约束被遗忘: 执行链路一旦过长，LLM注意力就会分散，导致重要约束被忽略。 例如，当要求逐个执行100个相似但复杂的任务时，大模型往往无法逐个严谨地完成任务，容易发生遗漏关键约束或跳过步骤。

核心思想:

• 状态机作为唯一的流程控制器，流程完全由状态机控制。
• 唯一入口：状态机作为 Agent 交互的唯一入口，输出每一步（Step）的标准 SOP 引导和专属 Prompt。
• 按需呈现：Agent 每一步只看该看的内容，降低认知负载，彻底避免遗忘关键约束。
• 输入校验：每步自定义对 Agent 的输出进行严格校验，并将校验结果循环返回给 Agent 纠错。

fsm to skill解决的痛点:

• 复杂推理流程散落在多次手写 prompt 里，难以复用、难以组合。
• 想让 LLM Agent 具备「多步、可分支、可循环、可计算」的确定性流程能力，却不想写状态机。
• SKILL 编写完成后，调试不透明，不知道在哪一步发生偏移。
• 编排结果难以沉淀为可分享、可版本化的 Skill 资产。

• 完全本地：无云端依赖，数据与密钥仅保存在本机。
• 7 种节点：start / code / llm / if / for / aggregate / end，覆盖编排所需的基本能力。
• 可视化编排：拖拽建连、实时校验、一键定位错误节点。
• 真实 LLM 调试：可视化暂时运行流程。 统计流式输出、Token 统计、节点级变量快照。
• 一键导出 Skill：生成 SKILL.md、agent_interface.json、workflow.yaml、inference/、scripts/。
• 状态机驱动：导出的 scripts/main.py 是自包含状态机线程，Agent 只需执行一条命令即可进入 DAG。
• 结构校验：无环、单开始、变量可追溯、类型匹配、禁嵌套 For 等。
• 替换转换skill: 将已经编写好的复杂业务流程skill转换为 fsm skill，支持在应用中打开。
• 稳定性保障: code执行错误处理 、 节点重试次数 、状态机等待超时配置等。
• 内置工具集: 内置 shell（bash / powershell 自动识别）、read_file、write_file 工具，Agent 可直接执行命令、读写任务工作区文件。
• pi-agent 集成: 内置 Node 驱动（pi-agent/driver.mjs），「运行」页一键以 pi-agent 模拟外部 Agent 端到端驱动 FSM Skill，实时转发进度与 Token 统计。
• FSM Skill 端到端验证: 已通过 pi-agent 实测验证「执行 → Prompt → 再执行 → 终止」完整循环与 Terminal Prompt 收尾逻辑。

• Python 3.10+（推荐 3.12+）
• Node.js 18+（仅 pi-agent 驱动模式需要）

# 1. 克隆仓库
git clone https://github.com/xu10311737/fsm-to-skill.git
cd fsm-to-skill

# 2. 创建虚拟环境（可选但推荐）
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate

# 3. 安装依赖
pip install -r requirements.txt

# 4.（可选）开发 / 运行测试依赖
pip install -r requirements-dev.txt

# 5. 安装 pi-agent 驱动依赖（使用「pi-agent 运行」模式时需要）
cd pi-agent
npm install
cd ..

python run.py

启动后浏览器自动打开 http://localhost:8000（默认端口，可在 run.py 中调整）。

1. 配置：在「配置」页填写服务商 base_url 与 api_key、设置默认模型；如需运行 Code 节点可指定 Python 解释器路径。
2. 编排：在编辑页画布中，点击/拖拽左侧组件到画布；点击节点右侧 + 追加后继节点，从 + 拖拽到目标输入端口建立连线。
3. 配置节点：选中节点，在右侧面板完成参数配置；工具栏「校验」随时检查结构错误。
4. 运行：切到「运行」页，填写开始节点声明的输入变量，点击 ▶ 运行，实时观察各节点状态。
5. 导出：校验通过后「导出 SKILL」，生成 Skill 目录供 Agent 使用。

• 实时状态：节点状态实时追踪: 各节点耗时、状态根据运行实时显示。
• 节点详情：查看 Prompt、思考过程、stdout/stderr、错误信息与产出变量。
• 统计：总耗时、各状态节点数、LLM 调用次数与 Token 用量、变量快照。
• 日志：全部引擎事件流，可「导出日志」为文本。
• 单节点调试：Code 节点可单独输入参数运行，快速验证脚本逻辑。
• pi-agent 运行：内置 Node 驱动（pi-agent/driver.mjs），可模拟外部 Agent 端到端驱动 FSM Skill。

「运行」页支持 pi-agent 运行 模式：后端把工作流推进到首个 Prompt 出口后，spawn pi-agent/driver.mjs（Node 子进程）充当外部 Agent，自主完成「读 Prompt → 调 LLM → 执行 Code step → 再读 Prompt」直到任务结束。

• 实时转发：首个 Prompt、后续每轮 Prompt / 模型回复 / 工具调用 / Token 统计均经 SSE 转发到界面。
• 正确收尾：driver 每轮交互后若未执行任何 step，会调用 main.py --task-id X --finalize 收尾，保证 Terminal Prompt 后任务正确结束，避免死循环。
• 工作区隔离：每个任务的独立工作区位于 data/runtime/<safe_task_id>，与项目根路径隔离。
• 前置依赖：需安装 Node.js，并在 pi-agent/ 目录执行 npm install。

校验通过后，选择目标目录一键导出：

my-skill/
├── SKILL.md              # 说明文档（入参表 / 输出 / 结构）
├── agent_interface.json  # Agent 到 Code / Prompt 的路由表
├── workflow.yaml         # 工作流定义
├── inference/            # LLM 提示词模板
└── scripts/              # Code 节点脚本 + 自动生成的 main.py 状态机入口

• scripts/main.py 是导出 Skill 的总状态机线程；
• code 节点 = 入口: 总线程由入参路由到各个code节点的入口并执行。
• Prompt 节点 = 出口：引擎运行到 Prompt 节点即暂停，把渲染后的字符串返回给 Agent；Agent 的下一次调用再从一个 Code 节点进入。

内置 Agent 工具：Agent 运行时内置 shell（bash / powershell 自动识别）、read_file、write_file 工具，可执行命令、读写任务工作区文件；本次发布已通过 pi-agent 端到端测试验证 FSM Skill 的完整执行循环。

Agent 调用方式：

python main.py --task-id task-001 --step-id code-1 --step-param '{"arg-1":"hello"}'

• --task-id：标识同一次任务。
• --step-id：本次输入要进入哪个 Code 节点。
• --step-param：入参 JSON 字符串。

状态机继续执行 DAG，直到遇到 Prompt 出口并把渲染后的字符串返回给 Agent。

fsm-to-skill/
├── app/                    # 后端源码
│   ├── engine/             # DAG 状态机执行引擎
│   ├── services/           # 调试服务、Agent 运行时、配置存储等
│   ├── validator/          # 19 项结构校验
│   └── web/                # 路由 / API
├── static/                 # 纯静态前端（画布、运行、配置界面）
│   ├── index.html          # 主界面
│   ├── docs.html           # 使用文档
│   └── js/ css/
├── data/
│   ├── config.yaml         # 本地配置
│   └── workflows/          # 本地工作流
├── trans-fsm-skill/        # 预制skill,将已经编写好的skill转成fsm skill
├── work/                   # 运行产物/调试脚本
├── main.py                 # FastAPI 入口
├── run.py                  # 启动脚本
├── requirements.txt        # 运行依赖
├── requirements-dev.txt    # 测试依赖
├── README.md
└── LICENSE

MIT# fsm-to-skill