superflow 0.1.0

AI 辅助工作流工具 - 将高级工程师方法论安装到任意项目

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 init	初始化项目，生成指令文件和数据目录
superflow scan	扫描项目结构、技术栈、入口文件等
superflow lesson	记录经验（支持交互式和命令行模式）
superflow status	查看工作流状态和经验库统计
superflow 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