Merge pull request openai#12 from eaglecloud-inc/release/v0.1.5

release: v0.1.5 - 旧版 Flow 架构版本留存

Author: liuzhongyu-eagle

.augment/rules/delivery_spec.md

@@ -0,0 +1,93 @@
+---
+type: "manual"
+---
+
+# **交付规范 (Delivery Specification)**
+
+本规范是项目代码从 `git push` 到部署上线的**唯一指令集**。
+
+---
+## 1. 核心规则
+- **主干保护**: **禁止**直接向 `develop` 和 `main` 分支推送代码。
+- **PR 驱动**: 所有代码变更**必须**通过 Pull Request (PR) 合入。
+- **自动化守卫**: PR **必须**通过所有自动化检查，才可被合并。
+
+---
+## 2. 交付指令集
+
+### **/pr --create**
+- **功能**: 创建一个拉取请求 (Pull Request)。
+- **输入**:
+    - `--title "<string>"` (可选, hotfix时必需)
+    - `--body "<string>"` (可选, hotfix时必需)
+- **前置条件**: 当前必须在一个作战分支上 (`feature/`, `refactor/`, `fix/`, `hotfix/`)。
+- **执行动作**:
+    1.  **确定目标分支 (Determine Target Branch)**:
+        - **IF** 当前分支为 `hotfix/*`, **THEN** 目标分支为 `main`。
+        - **ELSE** (对于所有其他分支), **THEN** 目标分支为 `develop`。
+    2.  **确定PR内容 (Determine PR Content)**:
+        - **IF** 当前分支为 `hotfix/*`:
+            - **必须**使用 `--title` 和 `--body` 参数作为 PR 的标题和描述。
+        - **ELSE**:
+            - **必须**执行**反向追溯算法**，找到关联的 `Work Item` 文档：
+                > a. **获取当前分支名**: 获取当前 Git 分支的全名。
+                > b. **扫描目录**: 在 `docs/todo/` 目录下，遍历所有 `.md` 文件。
+                > c. **读取并匹配**: 读取每个文件的元数据，并将其 `关联分支` 字段的值与当前分支名进行比较。
+                > d. **精确定位**: `关联分支` 字段内容与当前 Git 分支名**完全匹配**的文件，即为本次 PR 唯一关联的 `Work Item` 文档。
+            - **必须**使用 `Work Item` 的标题作为 PR 标题。
+            - **必须**在 PR 描述中引用 `Work Item` 的任务目标、验收标准和文件链接。
+    3.  向已确定的目标分支创建 PR。
+- **产出**: GitHub Pull Request 的 URL。
+
+### **/review --pr**
+- **功能**: 对指定的 PR 发起自动化评审。
+- **输入**: `<pr_url>`
+- **触发**: 通常由系统在 PR 创建后自动触发。
+- **执行动作**:
+    1.  **静态/模式检查**: 运行 `ruff`, `mypy` 及项目级实践检查。
+    2.  **逻辑预审**: 比对代码实现与 `Work Item` 的目标和验收标准。
+    3.  在 PR 页面发布一条**结构化的评审评论**。
+    4.  **IF** 发现阻塞性问题, **必须**为 PR 添加 `status:changes-required` 标签。
+    5.  **ELSE IF** 所有检查通过, **必须**移除 `status:changes-required` 标签 (如果存在)，发布评论 `✅ 自动化预审通过，等待人工评审。`, 并 **@-提及** 代码库维护者。
+- **产出**: PR 评论和标签变更。
+
+### **/release --start**
+- **功能**: 启动新版本发布流程。
+- **输入**: `--version <vX.X.X>`
+- **执行动作**:
+    1.  从 `develop` 创建 `release/<vX.X.X>` 分支。
+    2.  更新项目中的版本号文件。
+    3.  基于 Conventional Commits 生成 `CHANGELOG.md`。
+- **产出**: 状态消息。
+
+### **/release --finish**
+- **功能**: 完成版本发布。
+- **输入**: 无 (在 `release/*` 分支上执行)。
+- **执行动作**:
+    1.  合并 `release/*` 分支到 `main`。
+    2.  为 `main` 上的合并 `commit` 创建版本标签。
+    3.  合并 `main` 分支到 `develop`。
+    4.  删除 `release/*` 分支。
+- **产出**: 状态消息，报告新版本已发布。
+
+### **/hotfix --start**
+- **功能**: 启动线上紧急修复流程。
+- **输入**: `--issue "<issue_desc>"`
+- **执行动作**:
+    1.  **生成 Issue ID**: 创建一个新的、唯一的 `ISSUE[NNNN]` 编号 (例如 `ISSUE0125`)。
+    2.  **创建分支**: 从 `main` 创建 `hotfix/ISSUE[NNNN]-<issue_desc>` 分支。
+- **产出**: 状态消息，报告 `hotfix` 分支已创建，并**返回生成的 `ISSUEID`** (例如：`Created hotfix/ISSUE0125-critical-payment-bug. Issue ID: ISSUE0125`)。
+
+### **/hotfix --finish**
+- **功能**: 完成紧急修复。
+- **输入**:
+    - `--version <vX.X.X+1>` (在 `hotfix/*` 分支上执行)
+    - `--issue-id <ISSUE-NNNN>` (必填)
+    - `--issue-desc "<original_issue_desc>"` (必填)
+- **执行动作**:
+    1.  合并 `hotfix/*` 分支到 `main`。
+    2.  为 `main` 上的合并 `commit` 创建补丁版本标签。
+    3.  合并 `main` 分支到 `develop`。
+    4.  删除 `hotfix/*` 分支。
+    5.  **(事后追溯)** 基于 `--issue-id` 和 `--issue-desc`，自动创建并提交一份符合 `fix-ISSUE[NNNN]-[主题]_done.md` 格式的 `Work Item` 文档，记录问题和已应用的修复。
+- **产出**: 状态消息，报告紧急修复已上线并已归档。

.augment/rules/dev_spec.md

@@ -0,0 +1,93 @@
+---
+type: "always_apply"
+---
+
+# 开发规范 (Development Specification)
+
+该开发规范既是**通用编程指南**，也定义了用于执行具体开发任务的 **`/code` 指令**。它的管辖范围从**创建分支**到**推送分支 (`git push`)** 结束。
+
+---
+## 1. 指令模式 (Command Mode)
+
+### 1.1\. 标准模式：常规开发
+- **命令签名**: `/code --task <work_item_path>`
+- **功能**: 读取并实现一个**自包含的**、指定的工作项文档。
+- **核心流程**:
+  1.  **输入解析**: **仅需**读取并完全理解 `<work_item_path>` 这一个文件。**不再需要**回溯查找其关联的 PRD 或 Design 文档。
+  2.  **上下文分析**: **必须**扫描项目源码，理解待修改区域和相关依赖。
+  3.  **澄清与反问**: **基于输入和上下文分析**，如果实现细节不明确，**必须**向用户提问。
+  4.  **编码与推送**: **必须**严格遵循下文定义的 **[核心开发规范](#2-核心开发规范)** 完成从编码到**推送 (`git push`)** 的全过程。
+
+### 1.2\. 特殊模式：紧急修复
+  - **命令签名**: `/code --hotfix --issue "<issue_desc>"`
+  - **功能**: 在当前的 `hotfix/*` 分支上，直接执行紧急修复任务。
+  - **前置条件**: 当前必须在一个由 `/hotfix --start` 命令创建的 `hotfix/*` 分支上。
+  - **核心流程**:
+    1.  **输入解析**: 理解 `--issue` 描述，明确修复目标。
+    2.  **上下文分析**: **必须**扫描源码，定位问题。
+    3.  **澄清与反问**: **必须**与用户紧密互动，确认修复方案。
+    4.  **编码与推送**: **必须**严格遵循下文定义的 **[核心开发规范](#2-核心开发规范)** 完成从编码到**推送 (`git push`)** 的全过程。
+
+---
+## 2. 核心开发规范 (Core Development Specification)
+
+### 2.1 核心原则
+- **TDD (测试驱动开发)**: 先写测试，再写实现。这是首要开发原则。
+- **文档即代码 (Docs as Code)**: 代码变更 ➔ **必须**同步更新相关文档。
+
+### 2.2 环境与依赖
+- **环境**: Python >= 3.11, 使用 `uv` 管理。
+- **工作流**: `uv venv` → `source .venv/bin/activate` → `uv pip compile pyproject.toml --extra dev -o requirements-dev.txt` → `uv pip sync requirements-dev.txt`
+
+### 2.3 Git 工作流
+- **分支创建**:
+  1.  与上游 `develop` (或 `main` 对于 hotfix) 分支同步。
+  2.  基于正确的基础分支创建新分支。
+  3.  **分支命名 (强制)**:
+        - **计划性工作**: `[prefix]/PRD[NNN]-[主题]`
+        - **响应式工作**: `[prefix]/ISSUE[NNNN]-[主题]`
+  4.  **(关键链接步骤)** 对于非 hotfix 任务，分支创建后**必须立即回写**工作项的 `关联分支` 字段。
+- **分支前缀映射**:
+    - 工作项 `类型: feat` ➔ 分支前缀 `feat/`
+    - 工作项 `类型: refactor` ➔ 分支前缀 `refactor/`
+    - 工作项 `类型: fix` ➔ 分支前缀 `fix/`
+- **提交规范 (Conventional Commits)**:
+    - **格式**: **强制**为 `<type>(<scope>): <subject>`。
+    - **一致性**: Commit `<type>` **必须**与工作项 `类型` 字段一致。
+    - **追溯性**: 描述部分**必须**引用其根ID (`PRD[NNN]` 或 `ISSUE[NNNN]`)。
+    - **示例**:
+        - `feat(api): PRD007 - 添加用户注册端点`
+        - `fix(validation): ISSUE0123 - 修复日期校验错误`
+
+### 2.4 代码规范
+- **类型注解**: **强制** ➔ 所有公共函数/方法。
+- **文档字符串**: **强制** ➔ Google 风格，覆盖所有模块、类、公有函数。
+- **日志**:
+  - **来源**: `from loguru import logger`
+  - **上下文**: 自动注入，**禁止**手动拼接 ➔ `f"job: {job_id}"` (❌)
+  - **异常**: **必须**使用 `logger.exception()` 记录完整堆栈。
+- **错误处理**: **必须**捕获具体异常 ➔ `except ValueError:` (✅)
+
+### 2.5 测试驱动开发 (TDD)
+- **框架**: `pytest`
+- **测试金字塔与目录**:
+  - **单元 (~70%)**: `tests/unit/` ➔ `@pytest.mark.unit`
+  - **集成 (~20%)**: `tests/integration/` ➔ `@pytest.mark.integration`
+  - **E2E (~10%)**: `tests/e2e/` ➔ `@pytest.mark.e2e`
+- **测试基础设施 (`tests/conftest.py`)**:
+  - **设计**: 会话级资源 (`scope="session"`) + 工厂模式 (`_factory`) + Mock分离。
+  - **实践**: 优先使用工厂创建数据，合理选择 Fixture 作用域。
+
+### 2.6 文档更新规则
+- `api/`, `schemas/` 变更 ➔ **必须**更新 `docs/api/`
+- `Dockerfile` 变更 ➔ **必须**检查 `docs/deployment/`
+
+### 2.7 本地验证与推送 (Local Validation & Push)
+- **本地验证 (强制)**:
+  1.  `uv run python scripts/dev_check.py test` (单元+集成测试)
+  2.  `uv run python scripts/dev_check.py type` (静态类型检查)
+  3.  `uv run python scripts/dev_check.py lint --fix` (检查与格式化)
+- **推送流程**:
+  1.  本地验证通过 ➔ `git commit`
+  2.  `git commit` ➔ `git push`
+ - **最终产出**: 一个**已推送到远程**的、**合格的**、**待评审的**作战分支 (`feat/`, `refactor/`, `fix/`, `hotfix/`)。**本规范的使命至此结束。**

.augment/rules/plan_spec.md

@@ -0,0 +1,91 @@
+---
+type: "manual"
+---
+
+# **规划规范 (Planning Specification)**
+
+## **1. 核心原则**
+本规范定义了 `/plan` 命令套件，用于指导你 (Coding Agent) 执行标准的规划与设计流程。
+
+**[全局规则]**:
+1.  **模板遵从**: 所有产出格式、模板和结构，**必须**严格遵循 **`docs/development/07-文档管理指南.md`** 的定义。
+2.  **原则遵从**:
+    - **需求规约原则**: 撰写用户故事和 EARS 规约时，必须遵循 **`docs/development/04-需求描述规约.md`** 中定义的框架和语法。
+    - **设计原则**: 进行技术设计时，必须遵循 **`docs/development/05-技术设计原则.md`** 中定义的各项原则。
+    - **拆分原则**: 任务拆分时，**必须**参考 **`docs/development/06-任务拆分与估算指南.md`** 的拆分技巧和工作项结构体定义。
+    - **估算原则**: **必须**遵循两级估算体系：**早期宏观需求（PRD）使用T恤尺码，具体工作项（Work Item）使用故事点**。
+3.  **通用工作流**: 所有命令**必须**遵循一个标准工作流程：**输入解析 → 上下文分析 → 澄清与反问 → 生成产出**。
+
+---
+## **2. 命令详解**
+**命令套件覆盖了项目两大核心工作流**：
+1.  **功能开发流程 (`feat`/`refactor`)**: 一个自上而下的流程，使用 `--prd` → `--design` → `--split` → `--tasks`命令链。
+2.  **缺陷修复流程 (`fix`)**: 一个自下而上的流程，使用独立的 `--fix` 命令。
+
+*注意：对于 `refactor` 类型的任务，其流程起点 `/plan --prd` 的输入 `<需求描述>` 通常是一份**“技术改进提案”**，例如‘将用户认证模块重构为独立服务’。*
+
+---
+### **功能开发工作流 (`feat` / `refactor`)**
+
+#### **/plan --prd**
+- **命令签名**: `/plan --prd "<需求描述>"`
+- **功能**: **(流程起点)** 创建一份产品需求文档 (PRD)。
+- **核心流程**:
+  1.  **输入解析**: 理解 `<需求描述>`。
+  2.  **上下文分析**: **必须**扫描项目现有 PRD 和源码，理解当前功能全貌。
+  3.  **澄清与反问**: **基于输入和上下文分析**，若对场景、功能定义等存疑，向用户提出具体问题以澄清。
+  4.  **生成产出**:
+      - 在 `docs/prd/` 目录下创建并撰写 PRD 文档。
+      - **必须**为文档中的每个 User Story 和 EARS 需求生成符合 **《07》** 中定义的、层级化的唯一ID (如 `PRD007-US01`, `PRD007-US01-ER01`)。
+      - **必须**在文档元数据中给出一个初步的宏观估算（T恤尺码）。
+      - **如果**宏观估算为 `L` 或 `XL`，**必须**在产出文档的末尾向用户明确建议下一步应执行 `/plan --design` 命令。
+
+#### **/plan --design**
+- **命令签名**: `/plan --design <prd_path>`
+- **功能**: 基于 PRD 创建一份技术设计文档。
+- **核心流程**:
+  1.  **输入解析**: 读取并理解 `<prd_path>` 文件。
+  2.  **上下文分析**: **必须**深度扫描与 PRD 相关的项目源码模块、数据模型和服务依赖。
+  3.  **澄清与反问**: **基于输入和上下文分析**，如果对技术实现的关键决策点（如方案选型、性能权衡）存在不确定性，**必须**向用户提问以确认方向。
+  4.  **生成产出**: 在 `docs/development/design/` 目录下创建并撰写技术设计文档。
+
+#### **/plan --split**
+- **命令签名**: `/plan --split <prd_path> [--design <design_path>]`
+- **功能**: **(规划拆分)** 基于需求和设计，提出一份结构化的、待评审的任务拆分表格。
+- **核心流程**:
+  1.  **输入解析**: 读取 `<prd_path>` 和可选的 `<design_path>`。
+  2.  **上下文分析**: **必须**扫描源码，评估每个潜在子任务的实现细节。
+  3.  **澄清与反问**: **基于输入和上下文分析**，对拆分的粒度或依赖关系有疑问时，**必须**向用户提问。
+  4.  **生成产出**: 直接更新 `<prd_path>` 文件，在 `## 关联工作项` 区域生成一个结构化的 Markdown 表格。表格中的**“估算”列必须使用“故事点”**。
+
+#### **/plan --tasks**
+- **命令签名**: `/plan --tasks <prd_path> [--design <design_path>] [--task-id <task_id>]`
+- **功能**: **(创建文档)** 读取 PRD 中已评审通过的任务表格，为**指定的一个或全部**工作项创建详细文档。
+- **核心流程**:
+  1.  **输入解析**: 读取 `<prd_path>` 和可选的 `<design_path>` 文件，并定位到 PRD 中的任务表格。
+  2.  **上下文分析**: **必须**整体分析 **PRD (需求)、技术设计文档 (方案)** 和 **任务表格 (目标)** 的完整上下文。对于即将创建的每一个工作项文档：
+      - **必须**读取其关联的 EARS 需求 ID。
+      - **必须**将这些 ID 及其内容作为“继承的上下文”注入到工作项文档的 `关联需求ID` 字段和内容中。
+  3.  **澄清与反问**: 此阶段原则上不反问。若发现明显逻辑冲突，可提出警告。
+  4.  **生成产出**:
+      - **如果提供了 `--task-id <task_id>`**:
+        - 在表格中找到 `ID` 匹配的行，并为其创建对应的、内容完整的 `feat_...` 或 `refactor_...` 工作项文件。
+        - 创建成功后，**必须**回到 PRD 表格中，将该行的 `状态` 更新为 `Created`。
+      - **如果未提供 `--task-id`**:
+        - 遍历表格中所有 `状态` 为 `Pending` 的行，并为**每一行**创建对应的工作项文件。
+        - 每成功创建一个，**必须**回到 PRD 表格中，将对应行的 `状态` 更新为 `Created`。
+
+---
+### **缺陷修复工作流 (`fix`)**
+
+#### **/plan --fix**
+- **命令签名**: `/plan --fix "<缺陷描述>"`
+- **功能**: **(独立流程)** 创建一份 `fix` 类型的工作项。
+- **核心流程**:
+  1.  **输入解析**: 理解 `<缺陷描述>`。
+  2.  **上下文分析**: **必须**根据描述，尝试在源码中定位可能出错的代码区域，并分析其逻辑。
+  3.  **澄清与反问**: **基于输入和上下文分析**，如果无法稳定复现问题，**必须**主动向用户追问**明确的复现步骤**、**期望行为**和**实际行为**。
+  4.  **生成产出**:
+      - 在 `docs/todo/` 目录下创建 `fix_..._pending.md` 文件。
+      - **必须**在文档中清晰填写「复现步骤」。
+      - **必须**基于上下文分析，给出一份详尽的「根因分析 (RCA)」和明确的「修复方案」。

.augment/rules/project_summary.md

@@ -0,0 +1,68 @@
+---
+type: "always_apply"
+---
+
+# 项目摘要 (Project Summary)
+
+## 1. 定位 (Identity)
+- **核心**: 智能体 (Agent) 工作流执行引擎, 面向企业级 helpdesk agent 中台。
+- **目标**: 提供统一 API，用于动态配置与运行复杂的多 Agent 工作流。
+
+## 2. 核心 API (Core API)
+- `POST /api/v1/flows/execute` ➔ **核心执行入口**
+  - **Body (动态)**: 支持 `assistant` | `supervisor` | `swarm` 三种工作流。
+  - **Query (`?stream=true`)**: 切换为 NDJSON 流式响应。
+- `POST /api/v1/jobs/{job_id}/cancel` ➔ **运行时任务取消**
+
+## 3. 核心架构与流程 (Architecture & Flow)
+- **逻辑调用链**:
+  `POST /execute` → `routers.flows.execute_flow_endpoint` → `flows.flow_execute.execute_flow_job`
+
+- **请求-响应流程**:
+  ```mermaid
+  graph TD
+      A[Client] -- FlowExecutionRequest --> B(API Router);
+      B --> C{Flow Executor};
+      C -- 1. Instantiate --> D(Flow Strategy);
+      D -- 2. Create --> E(Agent Factory);
+      E -- 3. Assemble --> F[Agent Instance];
+      D -- 4. Execute --> F;
+      F -- run() --> G[Agent SDK];
+      G -- Result --> C;
+      C -- 5. Format Response --> A;
+  ```
+
+ - **物理代码结构**:
+     - `helpdesk_agent/`
+         - `api/`       ➔ **[API 层]** - FastAPI 路由
+         - `flows/`     ➔ **[业务编排层]** - Flow 策略实现
+         - `agents/`    ➔ **[Agent 定义层]** - Agent 工厂
+         - `tools/`     ➔ **[工具能力层]** - Agent 技能
+         - `schemas/`   ➔ **[数据模型层]** - Pydantic API 契约
+         - `config/`    ➔ **[配置注册中心]** - `app_config.py`
+         - `utils/`     ➔ **[通用工具]** - `logging_utils.py`
+     - **`tests/`**: 测试代码 (单元, 集成, E2E)。
+     - **`docs/`**: 项目文档（包含 prd/ 需求文档，todo/ 工作项文档）。
+     - **`scripts/`**: 辅助脚本 (如 `dev_check.py`)。
+
+## 4\. 关键设计模式 (Key Design Patterns)
+
+  - **配置中心 (`config/app_config.py`)**:
+      - 全局注册 `AVAILABLE_TOOLS` & `BUILTIN_AGENTS`&`ALLOWED_MODELS`。
+      - **扩展点**: 新增 Tool/Agent → 在此注册使其可用。
+  - **Flow 策略模式 (`flows/`)**:
+      - `BaseFlow` ← `AssistantFlow` | `SupervisorFlow` | `SwarmFlow`
+      - `flow_execute.py` 根据请求的 `flow_mode` 选择相应策略，实现逻辑解耦。
+  - **Pydantic 多态 API (`schemas/`)**:
+      - `Annotated[..., Field(discriminator="...")]` → 根据 `flow_mode` 字段，对不同请求体进行精确校验。
+  - **自动化日志上下文 (`utils/logging_utils.py`)**:
+      - `LoggingContext` | `@with_logging_context` → 自动为日志注入 `job_id` 等追踪 ID。
+      - **规范**: 严禁在日志消息中手动拼接上下文。
+
+## 5\. 技术栈 (Tech Stack)
+
+  - **后端**: FastAPI, Pydantic (V2)
+  - **核心依赖**: Loguru, `openai-agents-python-enhanced`
+  - **环境管理**: uv
+  - **代码质量**: Ruff, Mypy
+  - **测试**: Pytest, httpx