ai-dev-flow 3.10.0__py3-none-any.whl

ai_dev_flow/data/recipes/steps/03.5-decompose.yaml

@@ -0,0 +1,120 @@
+version: "1.0.0"
+title: "阶段 3.5 - 任务拆分"
+description: "将工程方案拆分为原子化的独立执行任务，每个任务可独立在新 AI 会话中执行"
+instructions: |
+  你是任务拆分专家。基于已确认的工程方案，将实施工作拆分为原子化的独立任务。
+
+  拆分原则：
+  1. 每个任务必须足够小，能在 20-60 个 AI turn 内完成
+  2. 每个任务只做一个明确的事情（单一职责）
+  3. 任务之间通过文件依赖，不通过对话上下文
+  4. 基础设施层先于应用层，数据库变更加业务代码
+  5. 每个任务必须附带 context_notes——足够让一个全新 AI 会话理解要做什么
+parameters:
+  - key: requirement
+    input_type: string
+    requirement: required
+    description: "精炼需求文件路径"
+  - key: input_analysis
+    input_type: string
+    requirement: required
+    description: "需求分析报告路径"
+  - key: input_plan
+    input_type: string
+    requirement: required
+    description: "工程方案路径"
+  - key: profile
+    input_type: string
+    requirement: required
+    description: "项目画像文件路径"
+  - key: project_root
+    input_type: string
+    requirement: required
+    description: "项目根目录"
+  - key: output_tasks
+    input_type: string
+    requirement: required
+    description: "任务文件输出路径 (YAML)"
+prompt: |
+  阅读以下文档并扫描项目代码，将实施工作拆分为原子化任务，输出到 {{ output_tasks }}：
+
+  1. 需求文档：{{ requirement }}
+  2. 需求分析：{{ input_analysis }}
+  3. 工程方案：{{ input_plan }}
+  4. 项目画像：{{ profile }}
+  5. 扫描项目代码：{{ project_root }}
+
+  ## 拆分原则
+
+  1. **原子性**：每个任务做一件事，有明确的输入和输出文件
+  2. **可控规模**：每个任务预计 20-60 个 AI turn
+  3. **依赖清晰**：用 depends_on 明确前置任务
+  4. **文件可传递**：列出 input_files（需要读取的文件）和 output_files（需要生成的文件）
+  5. **上下文自包含**：context_notes 必须足够详细，让新 AI 会话仅凭它就能理解该任务的全部意图和约束
+  6. **基础设施优先**：数据库 Schema、公共模块、配置变更先于业务逻辑
+
+  ## 每个任务必须包含
+
+  - id: 唯一标识（如 task-db-schema, task-user-api）
+  - name: 中文任务名
+  - description: 具体做什么（1-2句话）
+  - category: infrastructure | backend-api | frontend | database | config | test
+  - estimated_turns: 预估 turns（20-60）
+  - priority: P0 | P1 | P2
+  - depends_on: 前置任务 ID 列表（可为空）
+  - input_files: 需要读取的现有文件路径（项目根目录的相对路径）
+  - output_files: 需要创建或修改的文件路径
+  - context_notes: 实现上下文说明（这是**最关键**的字段！必须包含：技术选型、关键约束、接口约定、与上下游的契约）
+  - reference_docs: 参考的设计文档名（如 "03-plan.md"）
+  - parallel_group: 可并行组名（可选，独立任务使用相同组名表示可并行）
+
+  ## 输出格式
+
+  将任务列表以 YAML 格式写入 {{ output_tasks }}：
+
+  ```yaml
+  version: "1.0"
+  project: "项目名"
+  created_at: "当前ISO时间"
+  total_estimated_turns: <总和>
+  tasks:
+    - id: task-xxx
+      name: "任务名"
+      description: "具体描述"
+      category: backend-api
+      estimated_turns: 40
+      priority: P0
+      depends_on: []
+      parallel_group: "group1"
+      input_files:
+        - "src/main/resources/application.yml"
+        - "pom.xml"
+      output_files:
+        - "src/main/java/com/example/XxxService.java"
+        - "src/main/java/com/example/XxxController.java"
+      context_notes: |
+        详细实现说明：
+        - 技术选型：Spring Boot + MyBatis
+        - 关键约束：不能修改已有接口路径
+        - 接口约定：POST /api/v1/xxx，JSON 格式
+      reference_docs:
+        - "03-plan.md"
+      retry_limit: 2
+      timeout_minutes: 15
+  ```
+
+  ## 完成后
+
+  输出：
+  ```
+  === 任务拆分完成 ===
+  任务总数: N
+  预估总 turns: M
+  P0 任务数: X
+  可并行组: [group1, group2]
+  ```
+extensions:
+  - type: builtin
+    name: developer
+    timeout: 600
+    bundled: true

ai_dev_flow/data/recipes/steps/05-build.yaml

@@ -0,0 +1,72 @@
+version: "1.0.0"
+title: "阶段 5 - 编译 + 测试验证"
+description: "自动编译项目并运行现有测试"
+instructions: |
+  你是一个构建验证工程师。
+
+  你的任务是在代码变更后自动编译项目，并运行现有测试用例。
+  确保代码可编译通过、现有功能不被破坏。
+
+parameters:
+  - key: project_root
+    input_type: string
+    requirement: required
+    description: "项目根目录"
+  - key: profile
+    input_type: string
+    requirement: required
+    description: "项目画像文件路径"
+  - key: output_result
+    input_type: string
+    requirement: required
+    description: "构建结果输出路径"
+
+prompt: |
+  基于以下信息执行编译和测试验证：
+
+  1. 项目代码仓库：{{ project_root }}
+  2. 项目画像：{{ profile }}
+
+  ## 执行步骤
+
+  ### 1. 编译
+  - 根据项目类型（从 profile.yml 读取）执行编译命令
+  - 如果 profile.yml 中有 build 命令，直接使用
+  - 如果 profile.yml 中没有，根据项目类型推测编译命令
+
+  ### 2. 运行测试
+  - 如果 profile.yml 中有 test 命令，执行
+  - 如果没有 test 命令，搜索项目中现有的测试框架配置并尝试运行
+  - 如果找不到测试配置，记录"未找到测试，跳过"
+
+  ### 3. 处理编译失败
+  - 如果编译失败，列出所有错误位置和原因
+  - 尝试修复编译错误（确保与工程方案一致的前提下）
+  - 如果修复后仍然失败，记录失败详情到 {{ output_result }}，停止
+
+  ## 输出
+
+  将结果写入 {{ output_result }}：
+
+  ```markdown
+  # 构建验证结果
+
+  ## 编译
+  - 状态：通过/失败
+  - 错误列表（如有）：
+    - 文件:行号 - 错误信息
+
+  ## 测试
+  - 状态：通过/失败/未运行
+  - 测试结果明细
+
+  ## 总结
+  - 构建是否通过
+  - 是否可以进入下一阶段
+  ```
+
+extensions:
+  - type: builtin
+    name: developer
+    timeout: 600
+    bundled: true

ai_dev_flow/data/recipes/steps/06-review.yaml

@@ -0,0 +1,115 @@
+version: "1.0.0"
+title: "阶段 6 - 审查（代码 + 安全）"
+description: "合并代码审查和安全审查，核对待办项"
+instructions: |
+  你是一个代码审查 + 安全审查专家。
+
+  同时做代码审查和安全审查，一次性输出完整的审查报告。
+  不涉及文件修改，只做审查。
+
+parameters:
+  - key: project_root
+    input_type: string
+    requirement: required
+    description: "项目根目录"
+  - key: requirement
+    input_type: string
+    requirement: required
+    description: "精炼后的需求文件路径"
+  - key: input_analysis
+    input_type: string
+    requirement: required
+    description: "需求分析报告路径"
+  - key: input_engineering_plan
+    input_type: string
+    requirement: required
+    description: "工程方案路径"
+  - key: input_change_list
+    input_type: string
+    requirement: required
+    description: "变更清单路径"
+  - key: input_build_result
+    input_type: string
+    requirement: required
+    description: "构建结果路径"
+  - key: profile
+    input_type: string
+    requirement: required
+    description: "项目画像文件路径"
+  - key: output_review
+    input_type: string
+    requirement: required
+    description: "审查报告输出路径"
+
+prompt: |
+  基于以下文件进行审查：
+
+  1. 精炼需求：{{ requirement }}
+  2. 需求分析：{{ input_analysis }}
+  3. 工程方案：{{ input_engineering_plan }}
+  4. 变更清单：{{ input_change_list }}
+  5. 构建结果：{{ input_build_result }}
+  6. 项目画像：{{ profile }}
+  7. 项目代码仓库：{{ project_root }}
+
+  ## 执行规则
+
+  1. 仅输出审查报告到 {{ output_review }}，禁止修改任何项目源代码文件（.java/.py/.ts/.js/.go 等）。
+  2. 禁止编写任何源代码，只做审查分析。
+  3. 只做审查，输出报告。
+
+  ## 审查内容
+
+  将结果写入 {{ output_review }}，包含以下章节：
+
+  ### A. 代码审查
+
+  #### A1. 变更与需求一致性
+  逐条核对变更清单中的每个修改是否对应需求文档中的功能点：
+  - [ ] 功能 A — 已实现/未实现/部分实现
+  - [ ] 功能 B — 已实现/未实现/部分实现
+
+  #### A2. 变更与工程方案一致性
+  核对实际代码变更是否与工程方案一致：
+  - [ ] 接口定义一致
+  - [ ] 数据模型一致
+  - [ ] 无未列入方案的变更
+
+  #### A3. 代码质量
+  - 编码规范一致性
+  - 命名规范
+  - 注释完整度
+  - 重复代码
+
+  ### B. 安全审查
+
+  #### B1. 暴露面
+  - 新增接口是否有鉴权
+  - 是否有敏感信息泄露风险
+  - 是否有未授权访问路径
+
+  #### B2. 注入安全
+  - SQL 注入
+  - 命令注入
+  - XSS
+
+  #### B3. 凭据处理
+  - 密码/密钥是否硬编码
+  - 敏感配置是否泄露
+
+  #### B4. 风险等级
+  - critical（必须修复）
+  - high（强烈建议修复）
+  - medium（建议修复）
+  - low（可忽略）
+
+  ### C. 总结
+  - 审查结论：通过/有条件通过/不通过
+  - 需要修复的问题列表
+  - 是否建议合并
+
+extensions:
+  - type: builtin
+    name: developer
+    timeout: 600
+    bundled: true

ai_dev_flow/data/recipes/steps/07-delivery.yaml

@@ -0,0 +1,76 @@
+version: "1.0.0"
+title: "阶段 7 - 交付"
+description: "输出变更清单，管线结束"
+instructions: |
+  你是交付管理助手。
+
+  汇总全流程产出，输出简洁的交付清单。
+  不做代码修改。
+
+parameters:
+  - key: requirement
+    input_type: string
+    requirement: required
+    description: "精炼后的需求文件路径"
+  - key: input_change_list
+    input_type: string
+    requirement: required
+    description: "变更清单路径"
+  - key: input_build_result
+    input_type: string
+    requirement: required
+    description: "构建结果路径"
+  - key: input_review
+    input_type: string
+    requirement: required
+    description: "审查报告路径"
+  - key: output_delivery
+    input_type: string
+    requirement: required
+    description: "交付清单输出路径"
+
+prompt: |
+  基于以下文件生成交付清单：
+
+  1. 精炼需求：{{ requirement }}
+  2. 变更清单：{{ input_change_list }}
+  3. 构建结果：{{ input_build_result }}
+  4. 审查报告：{{ input_review }}
+
+  ## 执行规则
+
+  1. 仅生成交付清单到 {{ output_delivery }}，禁止编写任何源代码文件（.java/.py/.ts/.js/.go 等）。
+  2. 禁止修改项目中的任何文件（交付清单除外）。
+
+  ## 输出
+
+  将交付清单写入 {{ output_delivery }}：
+
+  ```markdown
+  # 交付清单
+
+  ## 需求
+  （需求名称和简要说明）
+
+  ## 变更文件
+  - 新增：N 个文件
+  - 修改：N 个文件
+  - 删除：N 个文件
+
+  ## 构建验证
+  - 编译：通过/失败
+  - 测试：通过/失败/未运行
+
+  ## 审查结论
+  - 代码审查：通过/有条件通过/不通过
+  - 安全审查：无风险/有风险（见报告）
+
+  ## 待办（如有）
+  - [ ] 需要后续处理的遗留问题
+  ```
+
+extensions:
+  - type: builtin
+    name: developer
+    timeout: 300
+    bundled: true

ai_dev_flow/data/recipes/steps/task-template.yaml

@@ -0,0 +1,74 @@
+version: "1.0.0"
+title: "Task - {{ task_name }}"
+description: "执行单个原子开发任务。仅依赖文件上下文，不依赖对话记忆。"
+instructions: |
+  你正在执行一个独立的原子开发任务。
+  你拥有完成任务所需的全部上下文（已通过参数注入）。
+  不要超出任务范围。不要修改 output_files 之外的文件。
+
+parameters:
+  - key: task_name
+    input_type: string
+    requirement: required
+    description: "任务名称"
+  - key: task_description
+    input_type: string
+    requirement: required
+    description: "任务描述"
+  - key: project_root
+    input_type: string
+    requirement: required
+    description: "项目根目录"
+  - key: profile
+    input_type: string
+    requirement: required
+    description: "项目画像文件路径"
+  - key: context_file
+    input_type: string
+    requirement: required
+    description: "完整的任务上下文文件路径"
+
+prompt: |
+  ## 你的任务：{{ task_name }}
+
+  {{ task_description }}
+
+  ## 项目信息
+
+  项目根目录：{{ project_root }}
+  项目画像：{{ profile }}
+
+  ## 执行规则
+
+  1. 首先读取 {{ context_file }}，其中包含本任务的完整上下文（技术选型、约束、参考文档内容等）。
+  2. 只修改本任务指定的文件。不要修改任何其他文件。
+  3. 不要向用户提问。如有不确定的地方，记录下来并停止。
+  4. 不要做全局重构、批量重命名、或格式化清理。
+  5. 保持现有代码风格和命名习惯。
+
+  ## 完成后
+
+  确认所有 output_files 已正确创建/修改后，**必须**在文件末尾追加以下段落，然后输出任务完成标记。
+
+  ### 产出要求
+
+  在每个修改/创建的源代码文件末尾，追加 `## Key Decisions` 段落（作为注释），记录：
+  - 关键设计决策及原因
+  - 与现有代码的集成约定
+  - 需要注意的约束条件
+
+  ### 任务完成标记
+
+  最后输出：
+
+  === TASK COMPLETE ===
+  Task: {{ task_name }}
+  Files modified:
+  - path/to/file1 (变更摘要)
+  - path/to/file2 (变更摘要)
+
+extensions:
+  - type: builtin
+    name: developer
+    timeout: 600
+    bundled: true

ai_dev_flow/error_handler.py

@@ -0,0 +1,122 @@
+"""错误处理 - 4 选项交互。"""
+
+import logging
+from pathlib import Path
+from enum import Enum
+
+logger = logging.getLogger("ai-dev-flow")
+
+
+class Action(Enum):
+    RETRY = "retry"
+    FIX = "fix"
+    NOTE_EXIT = "note_exit"
+    SKIP = "skip"
+
+
+class TaskAction(Enum):
+    RETRY_TASK = "retry_task"
+    SKIP_TASK = "skip_task"
+    ABORT_GRAPH = "abort_graph"
+    NOTE_EXIT = "note_exit"
+
+
+SEPARATOR = "=" * 60
+
+ci_mode = False
+
+
+def set_ci_mode(enabled: bool) -> None:
+    global ci_mode
+    ci_mode = enabled
+
+
+def handle_error(ai_dev_dir: Path) -> Action:
+    """显示错误菜单，返回用户选择的操作。"""
+    if ci_mode:
+        print("\n  [CI] 阶段执行失败，自动跳过...")
+        return Action.SKIP
+    print()
+    print(SEPARATOR)
+    print("  阶段执行失败")
+    print(SEPARATOR)
+    print()
+    print("  1) retry      — 原地重试该阶段")
+    print("  2) fix        — 手动修改后按任意键重试")
+    print("  3) write note — 写说明笔记，保存并退出")
+    print("  4) skip       — 跳过该阶段，标记为完成")
+    print()
+
+    while True:
+        choice = input("  选择 (1/2/3/4): ").strip()
+
+        if choice == "1":
+            return Action.RETRY
+        elif choice == "2":
+            input("  修改完成后按 Enter 重试...")
+            return Action.RETRY
+        elif choice == "3":
+            note = input("  写说明: ").strip()
+            if note:
+                note_path = ai_dev_dir / ".pipeline_note"
+                note_path.write_text(note, encoding="utf-8")
+                logger.info("笔记已保存，下次运行时会提示")
+            return Action.NOTE_EXIT
+        elif choice == "4":
+            confirm = input("  确认跳过? 这会标记该阶段为已完成 (y/N): ").strip().lower()
+            if confirm == "y":
+                return Action.SKIP
+        else:
+            print("  无效输入，请输入 1/2/3/4")
+
+
+def handle_task_error(task_id: str, task_name: str, retries: int,
+                      retry_limit: int, ai_dev_dir: Path) -> TaskAction:
+    """任务级错误处理菜单。返回用户选择的操作。"""
+    if ci_mode:
+        if retries < retry_limit:
+            print(f"\n  [CI] Task {task_id} 失败 ({retries}/{retry_limit})，自动重试...")
+            return TaskAction.RETRY_TASK
+        else:
+            print(f"\n  [CI] Task {task_id} 失败 (已达上限)，自动跳过...")
+            return TaskAction.SKIP_TASK
+    print()
+    print(SEPARATOR)
+    print(f"  Task Failed: {task_name} ({task_id})")
+    print(f"  Retries: {retries}/{retry_limit}")
+    print(SEPARATOR)
+    print()
+    if retries < retry_limit:
+        print("  1) retry task — 重新执行此任务")
+    else:
+        print("  1) retry task — (已达重试上限)")
+    print("  2) skip task — 跳过此任务，继续后续")
+    print("  3) abort      — 终止任务图，保存进度")
+    print("  4) write note — 写说明笔记并退出")
+    print()
+
+    while True:
+        choice = input("  选择 (1/2/3/4): ").strip()
+
+        if choice == "1":
+            if retries >= retry_limit:
+                print("  已达重试上限，请选择其他选项")
+                continue
+            return TaskAction.RETRY_TASK
+        elif choice == "2":
+            confirm = input("  确认跳过? 该任务产出将缺失 (y/N): ").strip().lower()
+            if confirm == "y":
+                return TaskAction.SKIP_TASK
+        elif choice == "3":
+            confirm = input("  确认终止任务图? (y/N): ").strip().lower()
+            if confirm == "y":
+                return TaskAction.ABORT_GRAPH
+        elif choice == "4":
+            note = input("  写说明: ").strip()
+            if note:
+                note_path = ai_dev_dir / ".pipeline_note"
+                note_path.write_text(note, encoding="utf-8")
+                logger.info("笔记已保存")
+            return TaskAction.NOTE_EXIT
+        else:
+            print("  无效输入，请输入 1/2/3/4")