# workflow

**Repository Path**: lizhipengcoolest/workflow

## Basic Information

- **Project Name**: workflow
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-08
- **Last Updated**: 2026-08-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 需求 → 落地 全自动流水线工具（workflow）

把一份需求（文档或粘贴文字）自动变成已提交的代码。全程仅一次可选的人工确认（术语确认），其余全自动。

## 这个文件夹里有什么

| 文件 | 说明 |
|------|------|
| `workflow.py` | 核心引擎（需求→落地流水线） |
| `optimizer.py` | workflow.py 的依赖（AI 调用/验证/git 逻辑，需与其同目录） |
| `需求文档.md` | 本工具的需求说明书（验收标准） |
| `设计文档.md` | 完整设计（架构、决策、模块划分） |
| `README.md` | 本使用说明 |

> 注意：`workflow.py` 通过 `from optimizer import ...` 复用 AI/验证/git 逻辑，因此 `optimizer.py` 必须与它放在同一目录（本文件夹已包含），工具包自包含、可独立运行。

## 快速开始

### 方式一：命令行（开发者）

```bash
# 需求文档路径
python3 workflow.py <项目路径> <需求文档.md>

# 粘贴文字（用 - 从 stdin 读）
cat 需求.txt | python3 workflow.py <项目路径> -

# 常用参数
python3 workflow.py <项目> <需求.md> --engine claude   # 指定引擎
python3 workflow.py <项目> <需求.md> --dry-run          # 演练，不真改代码
python3 workflow.py <项目> <需求.md> --glossary off     # 关闭术语确认
python3 workflow.py <项目> <需求.md> --max-retry 3      # 失败重试次数
```

### 方式二：傻瓜式（普通用户，后续接入）

双击「开始落地.command」，把需求文档拖进去（或粘贴文字），回车即可。程序后台长跑，屏幕实时显示进度。

## 端到端示例

用一个简单需求演示完整流程。假设要为一个 FastAPI 后端加一个健康检查接口。

**1. 准备需求文档** `health_req.md`：

```markdown
# 健康检查接口

## 核心目标
给后端加一个健康检查接口。

## 验收标准
- GET /health 返回 200
- 响应体包含 {"status": "ok"}
```

**2. 跑流水线**（先演练，`--dry-run` 不真改代码）：

```bash
python3 workflow.py <项目路径> health_req.md --dry-run
```

**3. 观察输出**（dry-run 下只演示任务拆解，不实际改代码）：

```
[0/6] 文档规范化完成
[1/6] 预检: 目标=给后端加一个健康检查接口, 验收2条
[2/6] 术语确认完成
[3/6] 拆解完成: 4 个子任务
--- [T1] 实现/修正 GET /health 接口  ---
[dry-run] 将执行 ['brainstorm', 'ponytail', 'review']
--- [T2] 补充 /health 接口自动化测试  ---
[dry-run] 将执行 ['brainstorm', 'ponytail', 'review']
--- [T3] 启动链路与路由挂载验证  ---
[dry-run] 将执行 ['brainstorm', 'ponytail', 'review']
--- [T4] 接口文档记录 GET /health 用法  ---
[dry-run] 将执行 ['brainstorm', 'ponytail']
==== 汇总报告 ====
```

可以看到：流水线自动把需求规范化 → 预检 → 拆成 4 个边界清晰的子任务，并按类型为每个任务标注了适用阶段（backend 类走 brainstorm→ponytail→review，内容类走 brainstorm→ponytail）。

**4. 正式执行**（去掉 `--dry-run`）：

```bash
python3 workflow.py <项目路径> health_req.md --engine claude
```

此时程序会逐任务让 AI 直接改代码、跑 verify（语法/构建）、git 提交；失败自动回滚重试（默认 3 次）。全部跑完后输出整体验收核对清单 + 汇总报告。

## 运行流程

```
需求(任意格式)
  → 0️⃣ 文档规范化   任意格式转成规范 .md
  → 1️⃣ 全局预检     提取目标/deadline/验收/依赖
  → 2️⃣ 术语确认     (可选)AI提取 → 你确认 → 生成 glossary + ADR
  → 3️⃣ 四步法拆解   父任务 → 子任务 → 校验门
  → 4️⃣ 逐任务执行   串行：AI直接改文件 → verify → git提交/回滚重试
  → 5️⃣ 整体验收     未满足项自动补救一轮 → 输出清单
  → 6️⃣ 汇总报告
  → 7️⃣ 产出归档     把完成的代码复制到 <workflow>/projects/<需求名>/
```

## 工作区与进度查看

流水线运行时会**在项目下自动创建统一工作区** `<项目>/.workflow/`，所有产物集中放置：

```
<项目>/.workflow/
├── req/需求.md        # 规范化后的需求文档
├── plans/tasks.json   # 任务拆解清单
├── glossary.md        # 术语表
├── adr/               # 架构决策记录
├── state.json         # 运行状态（断点续跑依据）
└── progress.html      # 浏览器实时进度面板
```

**两种方式查看进度**：
1. **终端实时显示**：每步打印时间戳 + 阶段（如 `[10:32:31] [3/6] ✅ 拆解完成`）。
2. **浏览器进度面板**：用浏览器打开 `progress.html`，可看到：
   - 当前阶段、已完成/失败任务数、总进度百分比（每 3 秒自动刷新）
   - 全部任务清单（ID/任务/类型/状态/依赖）
   - 最近 80 条运行日志

## 使用要点

- **输入**：支持 `.md`、`.docx`/`.pdf`、以及直接粘贴的文字，都会被规范化成规范 `.md`。
- **术语确认**：启动时问一次 `(y/n)`。不懂术语可回车跳过（AI 默认理解）；懂的人可开启确认。
- **引擎**：主要用 claude（能做浏览器测试），codex 备选。
- **浏览器测试**：涉及前端/页面的任务会用 `@playwright/mcp` 操控浏览器做 QA；纯后端任务自动跳过。
- **断点续跑**：对同一项目重复运行时，若检测到上次的 `tasks.json`，会**复用任务清单并跳过已成功任务**，只重跑失败/跳过/未开始的任务，不从头再来。命令行加 `--output <目录>` 可改产出位置。
- **产出归档**：流水线完成后，把实际代码（排除 `.git`/`.workflow`/缓存）复制到 `<workflow>/projects/<需求名>/` 目录，方便交付。可用 `--output` 指定其他目录。
- **停止**：在项目目录放一个 `STOP` 文件，程序会在当前任务完成后安全停止。

## 依赖

- claude 或 codex CLI（本机已装）
- 目标项目是 git 仓库（用于快照/回滚/提交）
- 浏览器测试需要 `@playwright/mcp`（自动检测安装，全局一次）

## 与 optimizer.py 的关系

本工具复用 `optimizer.py` 的 AI 调用、验证、git 管理逻辑，将其从"单点循环优化"扩展为"完整需求落地流水线"。