ai-dev-flow 3.10.0__tar.gz

ai_dev_flow-3.10.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ding An
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ai_dev_flow-3.10.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: ai-dev-flow
+Version: 3.10.0
+Summary: Stateful, resumable, auditable pipeline for agentic coding — requirements to design to tasks to code to review, with human checkpoints and one commit per task.
+Author: Ding An
+License: MIT
+Project-URL: Homepage, https://github.com/293498733/AI_A_PLANT
+Project-URL: Repository, https://github.com/293498733/AI_A_PLANT
+Project-URL: Changelog, https://github.com/293498733/AI_A_PLANT/blob/main/CHANGELOG.md
+Keywords: agentic-coding,ai-agents,codex,llm-orchestration,developer-tools,goose,workflow-automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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 :: Build Tools
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.14; extra == "dev"
+Dynamic: license-file
+
+# AI Dev Flow
+
+> One command drives the full pipeline: requirements → analysis → design → code → review → delivery.
+> Interruptible and resumable, with a human in the loop at every decision point.
+
+**Status**: Active development (v3.10.0) · [中文文档](README.md)
+
+---
+
+## What this is
+
+An orchestration layer for agentic coding, not a chat wrapper. It turns
+requirements → design → coding → verification → delivery into a stateful,
+resumable, auditable machine: decision points force human sign-off, all context
+is externalized to files, every task ends in a git commit, and failures preserve
+the working tree for inspection.
+
+| Design goal | Trade-off |
+|-------------|-----------|
+| Process stays controlled | 5 mandatory checkpoints; AI drafts, humans decide. Not unattended automation |
+| Context stays trustworthy | Requirements, design and `tasks.yaml` all live on disk; tasks never share conversation memory |
+| Interruptions are recoverable | Stage and task state persist; rerunning the same command resumes from the break point |
+| Changes stay traceable | One git commit per task; failed verification keeps the sandbox for debugging |
+
+**Who it is for**: developers and small teams with existing Java / Vue / Python
+codebases who want AI inside a real delivery process — and who need to answer
+"who made this change, and under what constraints". **Not for**: IDE autocomplete,
+throwaway scripts, or teams that refuse any manual confirmation step.
+
+---
+
+## Pipeline overview
+
+```
+ai-dev-flow --project /path/to/your/project
+
+Phase 1 ─── requirement refinement (structured requirement doc)
+  ⚠ Checkpoint A ─ confirm requirements
+Phase 2 ─── analysis (features, data flow, open questions)
+  ⚠ Checkpoint B ─ close open questions
+Phase 3 ─── engineering design (architecture, interfaces, data model)
+  ⚠ Checkpoint C ─ confirm design
+Phase 3.5 ─ task decomposition (atomic tasks with context_notes)
+  ⚠ Checkpoint C2 ─ confirm decomposition
+█████████ task graph execution (each task = fresh session + git commit) █████████
+Phase 5 ─── build + test
+Phase 6 ─── code + security review
+  ⚠ Checkpoint D ─ security sign-off (high-risk only)
+Phase 7 ─── delivery (change list, build verification, review verdict)
+```
+
+---
+
+## Quick start
+
+### Prerequisites
+
+| Dependency | Purpose |
+|------------|---------|
+| Python 3.9+ | orchestration engine |
+| goose CLI >= 1.33 | AI execution engine |
+| LLM API key | DeepSeek or any goose-compatible provider |
+
+### Install
+
+```bash
+# install from PyPI
+pip install ai-dev-flow
+
+# or run from a source checkout
+git clone https://github.com/293498733/AI_A_PLANT.git
+cd AI_A_PLANT && pip install -r requirements.txt
+
+# supply the API key via environment variable
+export CUSTOM_DEEPSEEK_API_KEY=your_key      # Windows: set CUSTOM_DEEPSEEK_API_KEY=your_key
+```
+
+### Usage
+
+```bash
+ai-dev-flow                                          # interactive start
+ai-dev-flow --project /path/to/project               # target a project directory
+ai-dev-flow --project . --from-stage phase3          # start from a specific stage
+ai-dev-flow --project . --dry-run                    # preview stages without executing
+```
+
+---
+
+## Core mechanisms
+
+### Resume after interruption
+
+Whatever stops the run — Ctrl+C, a reboot, a crashed engine — rerun the same
+command and it continues from the break point. Global progress lives in
+`.ai-dev/.pipeline_stage` inside the target project; per-task state lives in
+`.ai-dev/task_state.json`.
+
+### Task-driven execution with externalized context
+
+Large projects are not written in a single AI session. Phase 3.5 decomposes the
+design into atomic tasks in `tasks.yaml`. Each task:
+
+- runs in a **fresh engine session** (20–60 turns) and never relies on chat memory
+- gets all its context from **files** (`input_files` + `reference_docs` + `context_notes`)
+- ends with an **automatic git commit**, so the change is traceable
+- is individually resumable — a crash restarts the failed task, not the phase
+
+### Error handling
+
+Every AI stage offers 4 options on failure, and task-graph execution offers its
+own 4: retry, fix/skip, write a note and exit, skip/abort.
+
+---
+
+## Project structure
+
+```
+ai-dev-flow/
+├── pipeline.py              source-tree launcher (same as the `ai-dev-flow` command)
+├── ai_dev_flow/             orchestration engine package
+│   ├── cli.py               CLI entry point
+│   └── data/                stage definitions, recipes, profile templates (installed with the package)
+├── tests/                   212 tests
+├── ARCHITECTURE.md          architecture design
+└── CHANGELOG.md             release history
+```
+
+---
+
+## Configuration
+
+| Variable | Purpose |
+|----------|---------|
+| `CUSTOM_DEEPSEEK_API_KEY` | LLM API key used by the engine |
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ai_dev_flow-3.10.0/README.en.md

@@ -0,0 +1,140 @@
+# AI Dev Flow
+
+> One command drives the full pipeline: requirements → analysis → design → code → review → delivery.
+> Interruptible and resumable, with a human in the loop at every decision point.
+
+**Status**: Active development (v3.10.0) · [中文文档](README.md)
+
+---
+
+## What this is
+
+An orchestration layer for agentic coding, not a chat wrapper. It turns
+requirements → design → coding → verification → delivery into a stateful,
+resumable, auditable machine: decision points force human sign-off, all context
+is externalized to files, every task ends in a git commit, and failures preserve
+the working tree for inspection.
+
+| Design goal | Trade-off |
+|-------------|-----------|
+| Process stays controlled | 5 mandatory checkpoints; AI drafts, humans decide. Not unattended automation |
+| Context stays trustworthy | Requirements, design and `tasks.yaml` all live on disk; tasks never share conversation memory |
+| Interruptions are recoverable | Stage and task state persist; rerunning the same command resumes from the break point |
+| Changes stay traceable | One git commit per task; failed verification keeps the sandbox for debugging |
+
+**Who it is for**: developers and small teams with existing Java / Vue / Python
+codebases who want AI inside a real delivery process — and who need to answer
+"who made this change, and under what constraints". **Not for**: IDE autocomplete,
+throwaway scripts, or teams that refuse any manual confirmation step.
+
+---
+
+## Pipeline overview
+
+```
+ai-dev-flow --project /path/to/your/project
+
+Phase 1 ─── requirement refinement (structured requirement doc)
+  ⚠ Checkpoint A ─ confirm requirements
+Phase 2 ─── analysis (features, data flow, open questions)
+  ⚠ Checkpoint B ─ close open questions
+Phase 3 ─── engineering design (architecture, interfaces, data model)
+  ⚠ Checkpoint C ─ confirm design
+Phase 3.5 ─ task decomposition (atomic tasks with context_notes)
+  ⚠ Checkpoint C2 ─ confirm decomposition
+█████████ task graph execution (each task = fresh session + git commit) █████████
+Phase 5 ─── build + test
+Phase 6 ─── code + security review
+  ⚠ Checkpoint D ─ security sign-off (high-risk only)
+Phase 7 ─── delivery (change list, build verification, review verdict)
+```
+
+---
+
+## Quick start
+
+### Prerequisites
+
+| Dependency | Purpose |
+|------------|---------|
+| Python 3.9+ | orchestration engine |
+| goose CLI >= 1.33 | AI execution engine |
+| LLM API key | DeepSeek or any goose-compatible provider |
+
+### Install
+
+```bash
+# install from PyPI
+pip install ai-dev-flow
+
+# or run from a source checkout
+git clone https://github.com/293498733/AI_A_PLANT.git
+cd AI_A_PLANT && pip install -r requirements.txt
+
+# supply the API key via environment variable
+export CUSTOM_DEEPSEEK_API_KEY=your_key      # Windows: set CUSTOM_DEEPSEEK_API_KEY=your_key
+```
+
+### Usage
+
+```bash
+ai-dev-flow                                          # interactive start
+ai-dev-flow --project /path/to/project               # target a project directory
+ai-dev-flow --project . --from-stage phase3          # start from a specific stage
+ai-dev-flow --project . --dry-run                    # preview stages without executing
+```
+
+---
+
+## Core mechanisms
+
+### Resume after interruption
+
+Whatever stops the run — Ctrl+C, a reboot, a crashed engine — rerun the same
+command and it continues from the break point. Global progress lives in
+`.ai-dev/.pipeline_stage` inside the target project; per-task state lives in
+`.ai-dev/task_state.json`.
+
+### Task-driven execution with externalized context
+
+Large projects are not written in a single AI session. Phase 3.5 decomposes the
+design into atomic tasks in `tasks.yaml`. Each task:
+
+- runs in a **fresh engine session** (20–60 turns) and never relies on chat memory
+- gets all its context from **files** (`input_files` + `reference_docs` + `context_notes`)
+- ends with an **automatic git commit**, so the change is traceable
+- is individually resumable — a crash restarts the failed task, not the phase
+
+### Error handling
+
+Every AI stage offers 4 options on failure, and task-graph execution offers its
+own 4: retry, fix/skip, write a note and exit, skip/abort.
+
+---
+
+## Project structure
+
+```
+ai-dev-flow/
+├── pipeline.py              source-tree launcher (same as the `ai-dev-flow` command)
+├── ai_dev_flow/             orchestration engine package
+│   ├── cli.py               CLI entry point
+│   └── data/                stage definitions, recipes, profile templates (installed with the package)
+├── tests/                   212 tests
+├── ARCHITECTURE.md          architecture design
+└── CHANGELOG.md             release history
+```
+
+---
+
+## Configuration
+
+| Variable | Purpose |
+|----------|---------|
+| `CUSTOM_DEEPSEEK_API_KEY` | LLM API key used by the engine |
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ai_dev_flow-3.10.0/README.md

@@ -0,0 +1,160 @@
+# AI Dev Flow
+
+> 一条命令驱动「需求→分析→方案→编码→审查→交付」的完整开发管线。
+> 中断可恢复，失败可介入，全过程可追溯。
+
+**Status**: Active development (v3.10.0) · [English](README.en.md)
+
+---
+
+## 定位与受众
+
+**agentic coding 的基础设施** —— 不是"AI 写代码"的对话框，而是把
+「需求 → 方案 → 编码 → 验证 → 交付」变成一台有状态、可恢复、可审计的机器：
+决策点强制人工确认，上下文全部外化到文件，每个任务一个 commit，失败保留现场。
+
+| 设计目标 | 取舍 |
+|----------|------|
+| 过程可控 | 5 个强制检查点，AI 起草、人拍板；不做无人值守全自动 |
+| 上下文可信 | 需求/方案/tasks.yaml 全部落文件，任务之间不共享对话记忆 |
+| 中断可续 | 阶段 + 任务状态落盘，重跑同一命令从断点继续 |
+| 变更有痕 | 每任务一次 git commit，验证失败保留沙箱现场供排查 |
+
+**Who uses this**：有存量 Java / Vue / Python 项目、要把 AI 接进真实交付流程的
+开发者与小团队；需要回答"这行改动是谁、在什么约束下做的"的交付场景。
+
+**不适合**：想要 IDE 内即时补全；单文件脚本或一次性试验；不接受任何人工确认节点。
+
+---
+
+## 一句话理解
+
+这是一个 **AI 项目经理** — 你告诉它要做什么，它帮你走完整个软件开发流程，每一步产出文档，每一步你可以审核、修改、打断、恢复。
+
+---
+
+## 流程总览
+
+```
+ai-dev-flow --project D:/MyPrj/你的项目
+
+Phase 1 ─── 需求精炼 (AI 输出结构化需求文档)
+  ⚠ 检查点 A ─ 确认需求
+Phase 2 ─── 需求分析 (拆功能点、数据流、不确定项)
+  ⚠ 检查点 B ─ 闭环不确定项
+Phase 3 ─── 工程方案 (架构设计、接口定义、数据模型)
+  ⚠ 检查点 C ─ 确认方案
+Phase 3.5 ─ 任务拆分 (AI 拆分为原子任务，含 context_notes)
+  ⚠ 检查点 C2 ─ 确认任务拆分合理性
+█████████ 任务图执行 (每个任务 = 全新AI会话 + git commit) █████████
+Phase 5 ─── 编译 + 测试
+Phase 6 ─── 代码 + 安全审查
+  ⚠ 检查点 D ─ 安全确认（仅高危暂停）
+Phase 7 ─── 交付 (变更清单、构建验证、审查结论)
+```
+
+---
+
+## 快速开始
+
+### 前置条件
+
+| 依赖 | 说明 |
+|------|------|
+| Python 3.9+ | 编排引擎 |
+| goose CLI >= 1.33 | AI 执行引擎 |
+| LLM API Key | DeepSeek 或其他 goose 兼容的 Provider |
+
+### 安装
+
+```bash
+# 从 PyPI 安装
+pip install ai-dev-flow
+
+# 或直接用源码树运行（根目录 python pipeline.py 等价）
+git clone https://github.com/293498733/AI_A_PLANT.git
+cd AI_A_PLANT && pip install -r requirements.txt
+
+# 配置 API Key
+set CUSTOM_DEEPSEEK_API_KEY=你的key
+# 或写入系统环境变量
+```
+
+### 使用
+
+```bash
+# 交互式启动
+ai-dev-flow
+
+# 指定项目路径
+ai-dev-flow --project D:/MyPrj/my-project
+
+# 从指定阶段开始
+ai-dev-flow --project D:/MyPrj/my-project --from-stage phase3
+
+# 预览模式（不实际执行）
+ai-dev-flow --project D:/MyPrj/my-project --dry-run
+```
+
+---
+
+## 核心机制
+
+### 中断恢复
+
+任何原因中断（Ctrl+C、关机、goose 崩溃），重新运行相同命令即可从断点继续。
+
+**原理**：项目目录下的 `.ai-dev/.pipeline_stage` 记录全局进度，`task_state.json` 记录每个任务的完成状态。
+
+### 任务驱动 + 上下文外化 (v3.0.0)
+
+大项目不再用一个 AI 会话硬写所有代码。Phase 3.5 将工程方案拆分为原子任务（`tasks.yaml`），每个任务：
+- 在**全新 goose 会话**中执行（20-60 turns），不依赖对话记忆
+- 上下文完全来自**文件**（input_files + reference_docs + context_notes）
+- 完成后**自动 git commit**，变更可追溯
+- 崩溃后从**失败任务继续**，而非整阶段重跑
+
+### 错误处理
+
+每个 AI 阶段失败时提供 4 个选项；任务图执行阶段提供独立的 4 选项：
+
+| 选项 | 行为 | 适用场景 |
+|------|------|---------|
+| 1) retry | 原地重试 | 网络波动 |
+| 2) fix/skip | 手动修改后重试 / 跳过该任务 | 编译错误 / 已手动完成 |
+| 3) write note | 写说明笔记并退出 | 问题复杂，晚点处理 |
+| 4) skip/abort | 跳过该阶段 / 终止任务图 | 不可恢复的错误 |
+
+---
+
+## 项目结构
+
+```
+ai-dev-flow/
+├── pipeline.py              ← 源码树启动器（等价 ai-dev-flow 命令）
+├── ai_dev_flow/             ← 编排引擎包
+│   ├── cli.py               ← CLI 入口
+│   └── data/                ← 阶段定义、Recipe、Profile 模板（随包安装）
+├── tests/                   ← 212 个用例
+├── ARCHITECTURE.md          ← 架构设计
+└── CLAUDE.md                ← 开发进度
+```
+
+---
+
+## 与原项目 (ai-dev-platform) 的区别
+
+| 维度 | ai-dev-platform | ai-dev-flow |
+|------|-----------------|-------------|
+| 编排语言 | Windows Batch | Python 3.9+ |
+| 阶段定义 | 硬编码在 bat 中 | 数据驱动 (pipeline.yaml) |
+| 日志 | 屏幕输出 | 结构化日志到文件 |
+| 加新阶段 | 改 bat 代码 | 改 YAML 配置 |
+| 测试 | 不可测试 | 可单测 |
+| Recipe 文件 | YAML | YAML (不变) |
+
+---
+
+## 许可证
+
+MIT — 见 [LICENSE](LICENSE)。

ai_dev_flow-3.10.0/ai_dev_flow/__init__.py

@@ -0,0 +1,5 @@
+"""AI 全流程开发管线 - 编排引擎"""
+
+__version__ = "3.10.0"
+
+__all__ = ["__version__"]

ai_dev_flow-3.10.0/ai_dev_flow/__main__.py

@@ -0,0 +1,6 @@
+"""支持 `python -m ai_dev_flow`。"""
+
+from ai_dev_flow.cli import main
+
+if __name__ == "__main__":
+    main()

ai_dev_flow-3.10.0/ai_dev_flow/checkpoint.py

@@ -0,0 +1,65 @@
+"""人工确认检查点。"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+logger = logging.getLogger("ai-dev-flow")
+
+SEPARATOR = "=" * 60
+PREVIEW_LINES = 25
+
+ci_mode = False
+
+
+def set_ci_mode(enabled: bool) -> None:
+    global ci_mode
+    ci_mode = enabled
+
+
+def confirm(title: str, prompt: str, preview_file: Path | None = None) -> None:
+    """暂停并等待用户确认，可选展示产出文件摘要。"""
+    print()
+    print(SEPARATOR)
+    print(f"  [人工确认] {title}")
+    print(SEPARATOR)
+    if prompt:
+        print(f"  {prompt}")
+        print(SEPARATOR)
+
+    if preview_file and preview_file.exists():
+        preview(preview_file)
+
+    if ci_mode:
+        print("  [CI] 自动确认，继续执行...")
+        return
+    print()
+    input("按 Enter 继续...")
+
+
+def preview(filepath: Path, lines: int = PREVIEW_LINES) -> None:
+    """展示文件的前 N 行作为摘要。"""
+    try:
+        content = filepath.read_text(encoding="utf-8")
+        all_lines = content.splitlines()
+        print()
+        print(f"  --- {filepath.name} 摘要 (前 {min(lines, len(all_lines))} 行) ---")
+        for line in all_lines[:lines]:
+            print(f"  | {line}")
+        if len(all_lines) > lines:
+            print(f"  | ... (共 {len(all_lines)} 行，已省略)")
+        print(f"  --- {filepath.stat().st_size // 1024}KB ---")
+    except Exception:
+        print(f"  (无法预览 {filepath.name})")
+
+
+def ask_boolean(prompt: str, default: bool = True) -> bool:
+    if ci_mode:
+        print(f"  [CI] {prompt} → {'Y' if default else 'N'} (auto)")
+        return default
+    suffix = " (Y/n): " if default else " (y/N): "
+    answer = input(prompt + suffix).strip().lower()
+    if not answer:
+        return default
+    return answer in ("y", "yes")