Superflow

将高级工程师方法论"安装"到任意项目，让 AI 编程助手自动遵循 理解 → 聚焦 → 方案 → 评估 → 执行 → 验证 的工作流。

Superflow 是一个 CLI 工具，为项目生成标准化的指令文件、Prompt、Agent 和经验库，配合 VS Code + GitHub Copilot Chat 使用，显著提升 AI 辅助编程的质量和一致性。

特性

• 一键初始化 — 自动生成 .github/ 指令文件和 .superflow/ 数据空间，零配置开箱即用
• 项目扫描 — 离线分析目录结构、技术栈、入口文件、构建命令，生成结构化扫描报告
• 经验积累 — 持久化记录踩坑 (pitfall)、有效模式 (pattern)、经验教训 (lesson)，防止重蹈覆辙
• 状态总览 — 一目了然查看项目理解文档、扫描报告、经验库统计和 Skill 文件状态
• 非侵入式 — 不修改项目原有文件，所有生成内容在 .github/ 和 .superflow/ 中

生成的文件结构

你的项目/
├── .github/
│   ├── copilot-instructions.md           # 全局工作流指令
│   ├── prompts/
│   │   ├── understand-project.prompt.md  # /understand-project 触发
│   │   ├── change-code.prompt.md         # /change-code 触发
│   │   └── record-lesson.prompt.md       # /record-lesson 触发
│   ├── skills/
│   │   └── explore/SKILL.md              # 探索模式技能
│   └── agents/
│       ├── explorer.agent.md             # 只读探索 Agent
│       └── reviewer.agent.md             # 影响评估 Agent
│
└── .superflow/
    ├── config.yaml                       # CLI 配置
    ├── scan-report.md                    # 项目扫描报告
    ├── project.md                        # AI 生成的项目理解文档
    └── memory/
        ├── lessons.md                    # 经验教训
        ├── pitfalls.md                   # 踩坑记录
        └── patterns.md                   # 有效模式

前置要求

• Python >= 3.9
• VS Code + GitHub Copilot Chat 扩展

安装

Windows PowerShell 一键安装：

irm https://raw.githubusercontent.com/yxxxxx0123/superflow/dev/install.ps1 | iex

脚本会自动安装 superflow 并配置 PATH，无需手动操作。

或手动安装：

pip install git+https://github.com/yxxxxx0123/superflow.git@dev

如果安装后提示 superflow 命令找不到，需要将 Python Scripts 目录加入 PATH，或使用 python -m superflow。一键安装脚本已自动处理此问题。

快速开始

安装完成后，打开终端，进入你的项目目录：

cd your-project
superflow init

就这么简单。init 会自动生成工作流文件并扫描项目结构。

然后在 VS Code Copilot Chat 中使用：

/understand-project          ← AI 深入理解你的项目，生成项目文档
/change-code                 ← 标准化代码修改流程（方案→评估→执行→验证）
/record-lesson               ← 对话结束前，提取并记录经验教训

卸载

移除 superflow 在项目中生成的文件：

cd your-project
superflow uninstall

卸载 superflow CLI：

pip uninstall superflow

命令参考

superflow uninstall 说明

cd path/to/your-project
superflow uninstall

执行后会列出将要删除的文件，并要求确认，不会静默删除任何内容。对于 .github/copilot-instructions.md，会单独询问是否删除（因为可能包含你自己的内容）。

superflow lesson 示例

superflow lesson                         # 交互式输入
superflow lesson -t pitfall "PyQt5 截图不要保存文件，直接用 QBuffer"
superflow lesson -t pattern "复杂任务先拆分再逐步执行"

工作流概览

superflow init → superflow scan → /understand-project → /change-code → /record-lesson
     │                │                  │                    │               │
  生成指令文件     生成扫描报告      AI 生成项目理解     标准化代码修改    积累经验

依赖

• Typer — CLI 框架
• Rich — 终端美化输出
• PyYAML — YAML 读写
• pathspec — .gitignore 风格路径匹配

许可证

MIT