DeterminFlow AI Agent

<div align="center"> <h1> <picture> <source media="(prefers-color-scheme: dark)" srcset="web/public/brand/determinflow-lockup-dark.svg"> <img src="web/public/brand/determinflow-lockup.svg" alt="DeterminFlow" width="720"> </picture> </h1> <p><strong>让不确定的模型，运行在确定的流程里。</strong></p> <p>把复杂 AI 流程快速开发、验证、恢复，并稳定交付为服务。</p> <p> <a href="https://github.com/alikon-art/DeterminFlow/releases"><img src="https://img.shields.io/github/v/release/alikon-art/DeterminFlow?display_name=tag&sort=semver" alt="Release"></a> <a href="https://github.com/alikon-art/DeterminFlow/actions/workflows/ci.yml"><img src="https://github.com/alikon-art/DeterminFlow/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://github.com/alikon-art/DeterminFlow/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue" alt="许可证：AGPL-3.0"></a> <img src="https://img.shields.io/badge/Python-3.11-3776AB?logo=python&logoColor=white" alt="Python 3.11"> </p> <p> <a href="#why-determinflow"><u>为什么是 DeterminFlow</u></a> · <a href="#production-proof"><u>案例</u></a> · <a href="#features"><u>主要能力</u></a> · <a href="#quick-start"><u>快速开始</u></a> · <a href="#plugins"><u>插件</u></a> · <a href="#community"><u>社区与合作</u></a> </p> <p><a href="README.en.md">English</a> · <strong>简体中文</strong></p> </div> <p align="center"> <a href="https://bishuxiezuo.cn/"> <img src="docs/assets/screenshots/bishu-writing-workflow.png" alt="运行在 DeterminFlow 上的笔枢写作正文生产 Workflow" width="100%"> </a> </p> <p align="center">_{真实正文生产流程：导演、上下文、专业写手、整合、校验、渲染与落库。}</p>

DeterminFlow 是一个面向生产的 AI 工作流运行框架。它把 LLM、脚本、API、数据库操作 和人工审批组织成有版本、可校验、可重试、可恢复、可审计的工作流。

每个 Agent 只负责一个边界清楚的节点：读取这一步需要的上下文，使用被授权的工具， 交付可校验的结果。DeterminFlow 负责控制流、数据流、重试与恢复，让整条流程稳定跑完。

DeterminFlow 已经在 笔枢写作 的真实 AI 小说生产链路中 完成生产验证。

<a id="why-determinflow"></a>

为什么不直接用 Codex、Claude 这类单智能体框架？

Codex、Claude 等单智能体框架很适合探索未知问题。但流程已经明确时，让一个 Agent 反复阅读全部上下文、自己记住每一步，还要负责调用所有工具，通常更慢、更贵，也更难维护。

要解决的问题	Codex、Claude 等单智能体框架	DeterminFlow
改流程	修改 Prompt、Skill 和自然语言约束	调整版本化节点、变量、分支和子流程
上下文隔离	长链执行通常持续携带越来越长的历史	每个 Agent Node 只看自己的局部上下文
结构化输出	依赖模型持续遵守自然语言约定	结构化输出、脚本校验、自动修复和定向重试
失败处理	人工判断从哪里重来	从失败节点继续，已经完成的部分不用重跑
控制权限	单个 Agent 通常拿到整条流程所需的工具	每个节点只拿自己需要的工具
成本审计	消耗通常汇总在整次任务中	每个节点、尝试和模型调用单独记账
对外交付	需要额外搭建交付外壳	包装成 API、后台服务、Automation 或 Plugin

带来的变化很直接：

• 开发更快： 把可靠节点组合起来，验证通过就能接 API 或业务服务。
• 维护更轻松： 流程、参数和输出都有固定结构，不靠一大段 Prompt 维持秩序。
• 运行更稳定： 模型只处理需要判断的部分，控制流和数据流交给 Runtime。
• 失败不重来： 任意节点都能审计、重试和恢复，长流程不必从头再跑。
• Token 更省： 每个模型只读取自己需要的上下文，不重复背完整历史。
• 权限更小： 工具可以按节点收窄，更强的 LLM 工作区沙箱也在 Roadmap 中。

<a id="production-proof"></a>

案例：在 AI 小说正文生产环节中节省 70%–89% Token

笔枢写作 使用 DeterminFlow 串起导演、世界状态、角色维护、多个 专业写手、整合、校验、渲染和落库，形成一条可以断点恢复的正文生产流程。

一次真实完成的生产任务包含 11 个独立模型会话，在 DeterminFlow 中运行一次共消耗 176,584 Token。如果把同一套流程交给一个长链 Agent，让它反复携带上下文、工具 结果和返工记录，估算 Token 消耗最高可达到 DeterminFlow 的 9.1 倍：

单智能体场景	估算总 Token	相对 DeterminFlow	DeterminFlow 节省	Terra API 等价成本	Sol API 等价成本
极度优化、几乎没有额外工具循环	约 59.5 万	3.4×	约 70%	$0.90	$2.26
正常工具调用与上下文增长	约 97.0 万	5.5×	约 82%	$1.47	$3.68
出现校验修复、重试或长上下文	约 161.0 万	9.1×	约 89%	$2.43	$6.08

以上基于真实 Workflow Token 账本，以及长链 Agent 重复携带上下文、工具结果和返工 的典型开销估算；成本按估算时的 API 输入 Token 单价换算。

在这条真正的生产流程中，使用节点级上下文隔离预计可以减少约 70%–89% 的 Token 消耗。

<a id="features"></a>

DeterminFlow 的主要能力

Workflow 编排

• 可视化 Workflow Editor，支持变量、条件、并行、循环、人工审批和子流程
• Agent、Script、Approval、Subprocess 四类 Core Node
• 每个节点独立配置输入、输出、模型和失败处理
• 通用 Core Node 抽象，贡献者或 Fork 可以继续开发新节点类型

可靠执行

• Task 启动时冻结 Workflow 定义和输入
• 自动重试、人工重试、跳过，以及从失败节点恢复
• 跨进程重启保存执行检查点
• 并行、循环和子流程拥有独立的尝试历史

LLM 运行边界

• 每个 Agent Node 都有独立会话和 Token 账本
• 工具白名单、黑名单、Workspace 和最大轮次可以按节点配置
• JSON 输出检测、解析、修复和模型重试
• 下游节点可以拒绝结果，让上游定向返工

观察与交付

• 按 Workflow、Task、Node、尝试和模型调用查看状态与用量
• FastAPI、React 控制台、Cron Automation、WebSocket 事件和健康检查
• MCP、Agent/Prompt 模板、Skill 和 Rule 都可以成为 Workflow 的可复用资产
• Core 可以独立运行，不依赖任何业务 Plugin

资源广场与统一账号

• 浏览、搜索、安装和投稿社区 Skill，首期只分发 Skill
• 从 Skills 页面查看更新并定位资源详情，安装和更新校验版本、来源与内容摘要
• 使用统一账号登录资源广场和公益模型，支持浏览器授权与返回桌面客户端

围绕 Workflow 的统一工作区

对话、Workflow、Cron、Skills、Rules 和 Plugins 都在同一个控制台中。

它怎么工作

flowchart LR
    I["API / Event / Manual Input"] --> W["Versioned Workflow"]
    W --> A["Agent Node<br/>local context + minimum tools"]
    A --> V["Output validation"]
    V -->|"invalid"| A
    V -->|"valid"| S["Script / API / Database"]
    S --> C["Checkpoint + audit trail"]
    C --> O["API / Service / Plugin Output"]

1. Task 启动时冻结 Workflow、参数和节点输入。
2. Agent Node 在独立会话中运行，只装配自己需要的工具。
3. 输出不合格时修复、重试、跳过，或者请求人工处理。
4. Script Node 负责文件转换、API 调用和数据库落库等确定性工作。
5. 每次尝试、错误、Token、产物和检查点都会保存，进程重启后仍可继续。

<a id="plugins"></a>

扩展：用 Plugin 交付完整的 AI 业务

DeterminFlow 解决流程怎么执行，Plugin 则把它和运行所需的能力一起打包交付。常见场景 包括：

使用场景	可以随 Plugin 一起交付
把成熟流程交给团队或社区安装	Workflow、Agent、Prompt、Skill、Rule 和预设短语
把流程直接变成可调用的业务服务	API、托管后台进程、配置、健康检查和轻量页面
交付需要持久化的完整业务	Script Library、数据库迁移、落库与恢复逻辑

官方插件与开源案例

官方插件统一发布在 DeterminFlow-Plugins。其中 bishu-novel 是从笔枢写作真实生产链路整理出的开源 AI 小说 Workflow 案例。当前公开版包含：

生产 Workflow	编排节点	Agent / Prompt 组合	可复用脚本模块
7	84	33	15

它覆盖世界观、角色、故事规划、卷纲与近纲、正文生产、章节后验和润色。公开插件是纯本地文件 工作流，小说资料与检查点保存在用户工作区，不需要数据库、独立 API 服务或迁移。

同仓库还提供可选的 public-api 公益模型 Plugin。Windows 和 macOS 桌面版可在首次引导或 Plugin 页面安装；未安装或未启用时， Core 不加载公益模型服务逻辑。

社区插件

社区投稿发布在独立仓库 DeterminFlow-Community-Plugins， 与官方插件仓库分开。Core 内置该社区源，可在插件页浏览并安装。进入目录只表示结构与既定检查通过，不是官方安全背书或持续维护承诺。社区插件与 DeterminFlow 主进程以相同权限运行，没有沙箱；安装前需要确认风险。也可以自行添加 Git 仓库。

[!NOTE] Plugin 使用现有 Core Node 组合 Workflow。需要新节点类型时，可以 Fork Core 并扩展 通用 Node 抽象。

<a id="quick-start"></a>

快速开始

桌面安装包

从 GitHub Releases 下载，或使用 官网加速下载。桌面版自带运行环境，无需安装 Python、Node.js 或 Git。

平台	Core	Full
Windows x64	DeterminFlow_1.1.1_x64-setup.exe	DeterminFlow_1.1.1_x64-full-setup.exe
macOS Apple Silicon（M 系列芯片）	DeterminFlow_1.1.1_aarch64.dmg	DeterminFlow_1.1.1_aarch64-full.dmg

Core 不捆绑插件；Full 预装 bishu-novel 0.2.2 和 public-api 0.1.37。 首次启动按引导配置自有模型 API，或选择公益模型体验。

macOS 包采用 ad-hoc 签名，尚未经过 Apple 公证。将应用拖入“应用程序”后，若系统阻止打开， 在“系统设置 → 隐私与安全性”中选择“仍要打开”，再确认。macOS 当前通过下载安装包手动更新。

升级安装包保留用户数据、模型配置和已安装插件。已有插件不会被 Full 快照覆盖；请到插件页 检查更新，更新后重启应用。官方插件支持签名 HTTPS 加速下载，Git 是回退途径。

从源码运行

要求 Python 3.11+、Node.js 22.12+ 和 npm。根据你的系统选择一组命令。

macOS / Linux

git clone https://github.com/alikon-art/DeterminFlow.git
cd DeterminFlow
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.lock
cp .env.example .env
cp config/models_config.example.json config/models_config.json
python run.py

Windows PowerShell

git clone https://github.com/alikon-art/DeterminFlow.git
Set-Location DeterminFlow
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.lock
Copy-Item .env.example .env
Copy-Item config\models_config.example.json config\models_config.json
.\.venv\Scripts\python.exe run.py

可以先启动再到设置页面填写 API Key；也可以在 .env 中填写 DEEPSEEK_API_KEY，模型配置通过 ${DEEPSEEK_API_KEY} 读取它。

启动后可以访问：

• Web UI：http://localhost:8020
• API 文档：http://localhost:8020/docs
• Plugin 状态：GET /api/plugins

也可以使用 Docker：

docker compose up --build

新配置统一使用 DETERMINFLOW_* 前缀；已有的 AI_COMPANY_* 环境变量和 ai_company.extensions Entry Point 继续作为兼容别名使用，新旧配置同时存在时以新名称为准。 社区版默认以 4 个本机 Workflow Executor 进程执行普通 detached Workflow Task； 若要回退到单进程，设置 DETERMINFLOW_WORKFLOW_EXECUTOR_MODE=inline 和 DETERMINFLOW_WORKFLOW_EXECUTOR_COUNT=1。

文档

• 资源广场与 Skill 安装、更新
• 统一账户接口
• 社区开发分支更新说明
• 架构说明
• Plugin Package 规范
• Extension 开发指南

开发与验证

python -m pip install -r requirements-dev.lock
python -m pytest -q
(cd web && npm run lint && npm run test:extensions && npm run build)
docker compose -f docker-compose.yml config -q

<a id="community"></a>

社区与合作

如果你想……	可以从这里开始
报告问题或提出建议	GitHub Issues
交流使用经验，讨论 Workflow 和 Plugin 开发	QQ 群或微信群（下方扫码）
定制 Workflow、Plugin、私有部署或产品集成	微信 Reactive404 · 邮箱

加入群聊

<table> <tr> <th align="center">QQ 群</th> <th align="center">微信群</th> </tr> <tr> <td align="center" valign="top"><a href="http://qm.qq.com/cgi-bin/qm/qr?_wv=1027&amp;k=kRVWN5s7xlG8nc_f5fjdrpmd6mucbZoj&amp;authKey=1Xv1LWqUNiW5YgKYPvO8v%2F52s7JxRANMJ17wKrJCQSROw3%2BKf0%2B3BEIxstgEkg%2FM&amp;noverify=0&amp;group_code=945515407"><img src="https://images.determinflow.com/community/qq-group.jpg" alt="笔枢写作与 DeterminFlow QQ 交流群：945515407" width="260"></a></td> <td align="center" valign="top"><img src="https://images.determinflow.com/community/wechat-group.jpg" alt="笔枢 DeterminFlow 微信交流群" width="260"></td> </tr> <tr> <td align="center"><a href="http://qm.qq.com/cgi-bin/qm/qr?_wv=1027&amp;k=kRVWN5s7xlG8nc_f5fjdrpmd6mucbZoj&amp;authKey=1Xv1LWqUNiW5YgKYPvO8v%2F52s7JxRANMJ17wKrJCQSROw3%2BKf0%2B3BEIxstgEkg%2FM&amp;noverify=0&amp;group_code=945515407">群号：<code>945515407</code></a></td> <td align="center">二维码失效时会在固定地址更新</td> </tr> </table>

社区贡献者

感谢通过代码、审查、设计与建议帮助改进 DeterminFlow 的社区成员。

<table> <tr> <td align="center" width="180"> <a href="https://github.com/Deitykiki1208"> <img src="https://github.com/Deitykiki1208.png?size=128" width="64" height="64" alt="@Deitykiki1208"><br> <code>@Deitykiki1208</code> </a> </td> <td>浅色主题设计与实现参考（<a href="https://github.com/alikon-art/DeterminFlow/pull/8">PR #8</a>）</td> </tr> <tr> <td align="center" width="180"> <a href="https://github.com/ZLaoliu"> <img src="https://github.com/ZLaoliu.png?size=128" width="64" height="64" alt="@ZLaoliu"><br> <code>@ZLaoliu</code> </a> </td> <td>会话恢复、上下文压缩与 Agent 输出重试的问题定位和实现建议（<a href="https://github.com/alikon-art/DeterminFlow/pull/9">PR #9</a>、<a href="https://github.com/alikon-art/DeterminFlow/pull/10">#10</a>、<a href="https://github.com/alikon-art/DeterminFlow/pull/12">#12</a>）</td> </tr> </table>

Roadmap

• 完成内部兼容标识的 DeterminFlow 命名迁移
• 为每个 Agent Node 提供更强的 Workspace 与 LLM 执行沙箱
• 完善 Workflow 到独立 API / Service 的发布模板
• 增加更多可复现的生产级 Workflow 案例

License

DeterminFlow 使用 GNU AGPL v3（AGPL-3.0-only）许可证。

---

<p align="center"> 由 alikon-art 创建并维护。<br> 来自 <a href="https://bishuxiezuo.cn/">笔枢写作</a> 真实 AI 小说生产流程的实践。 </p>