Metadata-Version: 2.4
Name: superflow
Version: 0.1.0
Summary: AI 辅助工作流工具 - 将高级工程师方法论安装到任意项目
Project-URL: Homepage, https://github.com/yxxxxx0123/superflow
Project-URL: Repository, https://github.com/yxxxxx0123/superflow
Project-URL: Issues, https://github.com/yxxxxx0123/superflow/issues
License-Expression: MIT
Keywords: ai,cli,copilot,developer-tools,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: pathspec>=0.11.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=12.0.0
Requires-Dist: typer>=0.9.0
Description-Content-Type: text/markdown

# 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](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) 扩展

## 安装

**Windows PowerShell 一键安装：**

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

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

**或手动安装：**

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

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

## 快速开始

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

```bash
cd your-project
superflow init
```

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

然后在 **VS Code Copilot Chat** 中使用：

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

## 卸载

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

```bash
cd your-project
superflow uninstall
```

**卸载 superflow CLI：**

```bash
pip uninstall superflow
```

## 命令参考

| 命令 | 说明 |
|------|------|
| `superflow init` | 初始化项目，生成指令文件和数据目录 |
| `superflow scan` | 扫描项目结构、技术栈、入口文件等 |
| `superflow lesson` | 记录经验（支持交互式和命令行模式） |
| `superflow status` | 查看工作流状态和经验库统计 |
| `superflow uninstall` | 从项目中卸载 Superflow 生成的所有文件 |

### `superflow uninstall` 说明

```bash
cd path/to/your-project
superflow uninstall
```

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

### `superflow lesson` 示例

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

## 工作流概览

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

## 依赖

- [Typer](https://typer.tiangolo.com/) — CLI 框架
- [Rich](https://rich.readthedocs.io/) — 终端美化输出
- [PyYAML](https://pyyaml.org/) — YAML 读写
- [pathspec](https://github.com/cpburnz/python-pathspec) — .gitignore 风格路径匹配

## 许可证

MIT
