Skip to content

README.zh-CN.md

Latest commit

 

History

History
201 lines (140 loc) · 6.99 KB

README.zh-CN.md

File metadata and controls

201 lines (140 loc) · 6.99 KB

AgentFlow Logo

AgentFlow

让 AI Agent 自己干 12 小时，然后悄悄惊艳所有人

License: MIT AgentFlow Hub

中文 | English

编排复杂、长时间运行的任务——模块迁移、AI 自动化、代码深度清理——以 Cursor / OpenCode / Claude Code 为可切换后端。

AgentFlow Projects

Pipeline Editor

Running Status

解决什么问题

Cursor、Claude Code 这些 Coding Agent 很好用——直到任务变长。

1. 上下文窗口是硬天花板。 跑 10 分钟的任务没问题，跑 10 小时的大型迁移？模型开始遗忘前面的步骤、重复已做过的工作、或悄悄偏离方向。上下文压缩能续命，但它是有损的——agent 看到的已经不是完整画面。

2. 流程可靠性随时间衰减。 你告诉 agent："step 1 结束后让我确认，step 2 完成后跑测试。"前几次没问题。三小时后，确认步骤被上下文压缩吃掉了，agent 就直接跳过了。这和之前AI 误删用户邮件是同一类问题——不是恶意，只是丢了上下文。

3. Markdown 清单不是控制流。 你可以在 prompt 里写编号计划，但你没法表达"循环直到编译通过"或"如果测试失败就回到第 3 步"。真实工作流需要真正的分支和循环——而不是一个扁平列表让模型自由发挥。

AgentFlow 的做法：把编排逻辑从上下文里拿出来。 工作流定义为节点图，有明确的边、循环和条件分支。每个节点在独立的 agent 会话中运行，只拿到自己的输入——没有会衰减的上下文。节点之间的状态持久化到磁盘，一个 10 小时的工作流就是一连串专注的 10 分钟任务。

核心特性

  • 复用你的 AI 订阅 — Cursor Pro、OpenCode（阿里云等）、Claude Code；无需购买 LLM API key
  • 可视化编辑器 + AI Composer — 拖拽节点或用自然语言描述工作流
  • 状态持久化 — 每个节点的输入输出缓存到磁盘（类似 Gradle task cache），任意节点失败可续跑
  • 循环 / 分支 / 并行 — control_if、control_anyOne、control_toBool 实现真正的控制流
  • CI/CD 友好 — 确定性图结构、支持长时间运行、--machine-readable JSON 事件流

快速开始

环境要求： Node >= 18，以及 Cursor CLI (agent) / OpenCode CLI / Claude Code 任一

# 安装
npm install -g @fieldwangai/agentflow

# 启动 Web UI（端口 8765）
agentflow ui

# 或直接运行流程
agentflow apply <FlowName>

从源码开发：git clone → npm install → npm link

AgentFlow Hub

在 agentflow-hub.com 浏览、下载和分享社区工作流。

# 浏览社区工作流
agentflow list-remote

# 下载工作流
agentflow download <slug>

# 发布你的工作流
agentflow login
agentflow publish <FlowName> --tags "migration,review"

创建流程

方式一：可视化编辑器

Web UI 中 — 新建流水线 → 从面板拖节点到画布 → 连线 → 保存。

方式二：AI Composer（推荐）

打开右侧 Composer 面板，用自然语言描述需求：

创建一个代码检查流程：
1. 扫描代码库找出问题
2. 自动修复
3. 重新检查
4. 没通过就继续修，直到全过

Composer 会自动识别循环模式，生成正确的控制流节点。复杂流程分三阶段构建：拓扑 → 节点详情 → 连线校验（自动修复最多 5 次）。

运行与恢复

# 执行
agentflow apply <FlowName>

# 查看状态
agentflow run-status <FlowName> <uuid>

# 断点续跑
agentflow resume <FlowName> <uuid>

# 重试单个节点
agentflow replay <FlowName> <uuid> <instanceId>

# 查看 agent 推理过程
agentflow extract-thinking <FlowName> <uuid>

技能

AgentFlow 提供专用技能用于常见操作：

技能 说明
agentflow-flow-add-instances 向 flow.yaml 添加新节点，包括正确的 YAML 结构、连线设计和位置定位
agentflow-flow-edit-node-fields 编辑已有节点的允许字段（label、body、role、input/output 值）而不破坏拓扑
agentflow-flow-sync-ui 保存 flow.yaml 到磁盘后同步变更到 Web UI 画布
nestjs-route-order-debug 调试 NestJS 路由冲突（参数路由 :id 与具体路由之间）

技能在检测到相关任务时自动加载，提供领域特定的指令和工作流。

教程

CLI 参考

命令 说明
list 列出所有流水线
ui 启动 Web UI
apply 执行流程
validate 校验流程结构
resume 断点续跑
replay 重试单个节点
run-status 查看执行状态
extract-thinking 提取 agent 思考过程

选项

参数 说明
--workspace-root <path> 工作区根目录
--dry-run 只预览就绪节点，不执行
--model <name> 覆盖模型
--parallel 并行执行无依赖节点
--machine-readable JSON 事件流（供 UI/CI 集成）
--lang <code> 语言（zh / en）

环境变量

变量 默认值 说明
CURSOR_AGENT_CMD agent Cursor CLI 命令
CURSOR_AGENT_MODEL — 默认模型
OPENCODE_CMD opencode OpenCode CLI 命令
CLAUDE_CODE_CMD claude Claude Code CLI 命令
AGENTFLOW_CLAUDE_CODE_BYPASS_PERMISSIONS 1 向 Claude Code 传递 --dangerously-skip-permissions；设置 0 走交互式审批
AGENTFLOW_CLAUDE_CODE_STDERR_INHERIT 0 Claude Code stderr 直接转发到终端用于调试
AGENTFLOW_HOME ~/agentflow 用户数据目录

目录结构

~/agentflow/                          # 用户数据（流水线、agent、配置）
<workspace>/.workspace/agentflow/
  ├── pipelines/<flowId>/             # 项目内流水线副本
  ├── nodes/                          # 自定义节点定义
  └── runBuild/<flowId>/<uuid>/       # 运行产物 & 节点状态

国际化

  • CLI：--lang 参数或 LANG 环境变量
  • Web UI：自动检测浏览器语言
  • Agent 提示词：agents/<lang>/ 目录

支持：zh（中文）、en（English）

贡献

查看 CONTRIBUTING.zh-CN.md。

许可证

MIT