FlowCopilot

编排和自动化 GitHub Copilot Agent 多步骤工作流

FlowCopilot 是一个 VS Code 扩展插件，用于编排和自动化 GitHub Copilot Agent 模式的多步骤工作流。用户仅需输入一个高层次的需求描述，FlowCopilot 就能按照预定义（或自定义）的流程，依次调用 Copilot Agent 完成"设计 → 步骤拆分 → 循环执行"全流程，实现从需求到代码的端到端自动化。

功能特性

• 🔄 自动化多步骤 Agent 工作流 — 输入需求后自动完成设计、步骤生成、代码实现
• 📋 自定义流程模板 — 支持任意步数的串行流程，其中任一步可标记为"循环步骤"
• 💬 每步新开 Agent 对话 — 避免上下文污染，保持每步执行环境干净
• 🤖 指定模型 — 可在流程级别或步骤级别指定 LLM 模型（如 Claude Opus 4.5、GPT-5 Mini 等）
• 📊 JSON 驱动的子步骤 — 中间步骤输出结构化 JSON，后续步骤自动逐条执行
• 🔧 模板创建向导 — 交互式多步向导，快速创建自定义工作流模板
• 📁 独立输出目录 — 每次运行自动创建隔离目录，产出互不干扰可追溯
• ♻️ 流程中断恢复 — 支持断点续跑，异常中断后自动检测并提示恢复
• 🛡️ AI JSON 修复 — 智能修复 AI 生成的不规范 JSON（注释、截断、尾部逗号等）

前置要求

• VS Code ≥ 1.100.0
• GitHub Copilot 扩展（已安装并登录）
• GitHub Copilot Chat 扩展

快速开始

1. 安装

从 VS Code Marketplace 搜索 FlowCopilot 并安装，或通过命令行：

code --install-extension MutilAgentSystem-FlowCopilot.flowcopilot

2. 初始化工作区

首次在项目中使用时，FlowCopilot 会自动在工作区创建 .flowcopilot/ 目录并复制内置模板：

.flowcopilot/
├── .env                             # 统一 API / 中转配置（仅本机，不进 Git）
├── .gitignore                       # 防止误提交 .env
├── flows/
│   └── dev-workflow.flow.json    # 默认三阶段开发工作流
├── prompts/
│   ├── design.prompt.md          # Phase 1: 全局扫描与基线确立
│   ├── plan.prompt.md            # Phase 2: 技术蓝图与原子化拆解
│   └── execute.prompt.md         # Phase 3: 循环执行单个步骤
└── output/                       # 输出目录（自动管理）

公开版首次初始化时会从内置 .env.example 创建 .flowcopilot/.env，其中已预设所有支持的变量名。只需在这一个文件中粘贴实际 Key；扩展升级不会覆盖已有配置。个人构建则可预置本机 templates/.env，并使用 npm run vsix:personal 打包。

3. 一键启动工作流

方式 A — 左侧任务配置面板（推荐）：

1. 点击活动栏中的 FlowCopilot 图标，打开侧边栏
2. 在「任务配置」面板中输入需求描述
3. 选择流程模板和模型
4. 点击「▶ 启动」按钮

方式 B — 命令面板：

1. Ctrl+Shift+P 打开命令面板
2. 输入 FlowCopilot: 运行工作流
3. 选择模板 → 输入需求 → 自动执行

方式 C — 资源管理器右键：

• 右键点击任意 .flow.json 文件 → FlowCopilot: 从此文件运行

4. 观察执行过程

启动后，FlowCopilot 会自动：

1. 在右侧 Copilot Chat 中新建对话并发送 Prompt
2. 等待 Agent 完成并检测输出文件
3. 自动进入下一步骤
4. 侧边栏 TreeView 和状态栏实时显示进度

自定义流程模板

流程定义文件（flow.json）

{
  "$schema": "../../schemas/flow.schema.json",
  "name": "my-workflow",
  "version": "1.0.0",
  "description": "我的自定义工作流",
  "defaultModel": "gpt-5-mini",
  "context": {
    "projectName": "MyProject"
  },
  "steps": [
    {
      "id": "step1",
      "name": "第一步",
      "type": "normal",
      "promptTemplate": "step1.prompt.md",
      "output": { "type": "file", "path": "step1-output.md" }
    },
    {
      "id": "step2",
      "name": "循环执行",
      "type": "loop",
      "promptTemplate": "step2.prompt.md",
      "input": { "source": "step", "stepId": "step1" },
      "output": { "type": "json", "path": "steps.json" }
    }
  ]
}

步骤提示词模板（.prompt.md）

每个步骤对应一个 .prompt.md 文件，支持 ${variable} 模板变量：

---
mode: 'agent'
tools: ['search', 'edit', 'read']
model: ['${defaultModel}']
description: '步骤描述'
---

# 任务标题

你是一位专家。请根据以下信息完成任务：

- 项目名称：${context.projectName}
- 输入数据：${input}

## 输出要求
请将结果保存到 `${output.path}`

模板创建向导

运行 FlowCopilot: 创建流程模板 命令，通过交互式向导快速创建：

1. 输入流程名称和描述
2. 选择默认模型
3. 逐步配置各步骤（名称、类型、输入输出）
4. 自动生成 flow.json 和对应的 .prompt.md 骨架文件

配置项

在 VS Code 设置（settings.json）中可配置以下选项：

Codex 渠道的任务面板支持 GPT-5.6 Sol、Terra、Luna，以及 GPT-5.5/5.4 等兼容模型。Sol/Terra 可选到 ultra，Luna 可选到 max，GPT-5.5/5.4 可选到 xhigh；模型和推理强度会同时应用到新运行、队列运行与恢复元数据。

远程服务器执行（本地大脑 · 远程算力）

选 Claude CLI 渠道时，可在「任务配置」面板的 🖥 远程服务器 下拉选一台预配置的内网 GPU 服务器。 插件会把「远程执行铁律 + 该服务器连接信息」自动注入每个 Claude 提示词，本地 claude 据此用 ssh/rsync 把代码送到服务器跑、把结果取回——服务器无需联网。

• 第一次使用：命令面板运行 FlowCopilot: 打开远程服务器使用说明（或面板上「📖 服务器使用说明」按钮），按内置指引配置 SSH 免密与 flowcopilot.remoteServers。
• 设计与原理：见 docs/FlowCopilot-RemoteServer-Design.md；与多渠道改造的关系见 docs/FlowCopilot-MultiChannel-Design.md。
• Copilot 渠道或「不使用 · 本地执行」时行为与原先完全一致（零回归）。

命令列表

输出目录结构

每次执行会在 .flowcopilot/runs/ 下创建独立目录：

.flowcopilot/runs/
├── 001_20260226_143052_用户认证/
│   ├── meta.json          # 运行元数据（状态、耗时、各阶段记录）
│   ├── design.md          # Phase 1 输出
│   ├── steps.json         # Phase 2 输出
│   ├── execution.log      # 执行日志
│   └── checkpoints/       # 检查点（用于中断恢复）
└── 002_20260226_160015_权限管理/
    └── ...

开发

# 安装依赖
npm install

# 编译
npm run compile

# 监听模式开发
npm run watch

# 代码检查
npm run lint

# 运行测试
npm test

# 打包生成 .vsix 文件
npm run package

调试

1. 使用 VS Code 打开本项目
2. 按 F5 启动 Extension Host 调试
3. 在弹出的新窗口中测试插件功能

FAQ

Q: 启动后提示"未检测到 GitHub Copilot"？ A: 请确认已安装 GitHub Copilot 和 Copilot Chat 扩展并已登录。FlowCopilot 启动后会延迟 3 秒检测 Copilot 可用性。

Q: 流程执行中断了怎么办？ A: 下次打开项目时，FlowCopilot 会自动检测中断的流程并提示恢复。也可以在左侧任务配置面板中查看可恢复的历史运行。

Q: 如何切换测试环境和生产环境的模型？ A: 在 settings.json 中修改 flowcopilot.defaultModel。测试时推荐 gpt-5-mini（快速、低成本），生产环境推荐 claude-opus-4.5（高质量输出）。

Q: 模板变量 ${...} 如何工作？ A: FlowCopilot 使用 TemplateResolver 引擎解析模板变量。支持 ${context.*}（流程上下文变量）、${input}（上一步输出）、${output.path}（当前步输出路径），以及 ${currentTimestamp} / ${currentDateTime} 等由插件确定性生成的本地时间变量。

Q: 如何查看详细执行日志？ A: 打开 VS Code 输出面板（Ctrl+Shift+U），选择 FlowCopilot 通道，可看到完整的执行日志。

许可证

MIT