Python 后端项目的 AI Agent 规则约束实践：让 AI 乖乖按你的规矩写代码

---
applyTo: "**"
description: "新功能或重大变更前必须先创建实施计划并等待批准，完成后生成执行报告"
---
# AI 工作流核心准则：先规划，后编码，后总结

## 指导原则
- 在为新功能或重大变更编写任何代码之前，你必须首先以 Markdown 格式创建一份详细的实施计划。
- 你必须将这份计划呈现给我，以供审查和批准。计划长度一般限制在300行以内，大规模更改则不超过600行。
- 在我明确表示批准（例如，我说"计划通过"、"同意这个计划"或"可以开始"）之前，绝对不要编写任何代码。
- 代码实现完成后，必须生成一份执行报告（见步骤 4）。

## 步骤 0：查看仓库对应的代码

分析需求可能需要查看的代码，去查看对应代码再开始分析详细需要变化的代码。

## 步骤 1：分析需求并创建 MD 计划文档

当我提出一个新的开发任务时，你的首要行动是生成一个名为 `implementation_plan_xxxxx.md` 的 Markdown 文件到当前项目 `docs/plan` 目录下。这份计划必须包含以下几个部分：

1.  **需求概述：** 用你自己的话简要重述任务目标，以确认你的理解无误。
2.  **文件结构变更：** 清晰地列出所有需要新建的文件和需要修改的现有文件。无需写全文，清晰简要即可。
3.  **核心组件/函数设计：** 详细说明关键的类、函数、组件的职责和它们的核心逻辑。
4.  **数据流与逻辑：** 描述数据将如何在系统中流转，以及实现业务逻辑的关键步骤。
5.  **问题与澄清：** 如果需求的任何部分让你感到模糊或不确定，在此处列出你的问题。

## 步骤 1 的标准回应格式：

"好的，收到。这是关于新功能的实施计划，请您审阅并批准。"

*（然后 AI 会生成 `implementation_plan_xxxxx.md` 的详细内容）*

## 步骤 2：等待批准

在提交计划后，你必须停下所有工作，等待我发出明确的批准指令。

## 步骤 3：执行已批准的计划

一旦我批准了计划，你将严格按照该 MD 文档中描述的方案开始编写代码。在编码过程中，要始终参考这份计划，确保最终实现与方案一致。

## 步骤 4：完成后生成执行报告

代码实现完成并自测通过后，在当前项目 `docs/reports` 目录下生成一份 `report_xxxxx.md`（文件名与对应的 `implementation_plan_xxxxx.md` 使用相同的 `xxxxx` 后缀，便于对照），内容必须包括：

1.  **变更文件清单：** 本次新增了哪些代码文件、修改了哪些现有文件（列出完整路径，简要说明每个文件的改动内容）。
2.  **新增/改动功能说明：** 本次改动具体实现或调整了哪些功能点，与最初计划相比是否有偏差及原因。
3.  **前后端对接说明：** 新增或修改的接口（路径、方法、请求/响应结构），以及前端具体在哪些页面/组件中调用了这些接口、如何联调；若无前后端交互可注明"不涉及"。
4.  **遗留问题/后续 TODO：** 尚未处理的边界情况、已知限制或后续建议（如有）。

生成报告后，用一句话告知我报告路径，例如："已生成执行报告：docs/reports/report_xxxxx.md"。

---
applyTo: "**"
description: "编写或修改代码文件时始终遵循的长度与低耦合准则"
---
# 代码长度与低耦合准则

## 核心原则
追求低耦合、高内聚的代码结构。文件和函数过长会显著增加阅读和维护成本，应主动拆分。

## 硬性限制
- **单个代码文件**：正常情况下不超过 500 行，特殊情况（如确有必要）最多不超过 1000 行。
- **单个函数/方法**：正常情况下不超过 200 行，特殊情况（如确有必要）最多不超过 400 行。

## 执行方式
1. 在新建文件或给现有文件添加代码之前，先检查当前文件行数。如果即将超出限制，**主动提出拆分方案**（例如拆分成多个模块/子组件/工具函数文件），而不是直接把代码堆进去。
2. 如果一个函数逻辑复杂、接近或超过 200 行，优先考虑：
   - 提取独立的子函数，每个子函数只负责单一职责
   - 将不同关注点（如数据获取、校验、业务逻辑、渲染/输出）拆分到不同函数或文件中
3. 拆分时以"职责单一"为准则，而不是简单地按行数机械切割；避免为了凑数而拆出没有实际意义的函数。
4. 如果因为语言/框架限制（比如某些配置文件、生成代码）无法满足限制，需要在代码注释或提交说明中简要说明原因。

## 目的
- 便于代码审查和后续维护
- 降低修改一处影响多处的风险（降低耦合）
- 让每个文件/函数的职责一目了然

---
applyTo: "**"
description: "编写或修改代码结构、模块划分、依赖关系时始终遵循"
---
# 低耦合架构原则

## 背景
仅靠限制文件/函数行数不足以保证低耦合——文件很短但相互直接依赖内部实现细节、共享全局状态，同样会导致高耦合。本规则补充架构层面的原则。

## 核心原则

1. **单一职责**
   - 每个模块/类/函数只负责一件事。如果一个函数需要用"并且"才能描述它做了什么（如"校验参数并写数据库并发通知"），就应该拆分。

2. **依赖方向清晰，避免循环依赖**
   - 模块之间的依赖关系应该是单向的（如：路由层 → 服务层 → 数据访问层），禁止出现 A 依赖 B、B 又依赖 A 的情况。
   - 上层模块不应该反向依赖下层模块的内部实现细节，只依赖其对外暴露的接口。

3. **通过接口/参数传递依赖，而非硬编码或直接引用全局状态**
   - 优先通过函数参数、构造函数参数传入依赖（依赖注入），而不是在函数内部直接 import 并使用某个具体实现，或者依赖全局变量/单例的内部状态。
   - 这样便于替换实现、便于测试（可以传入 mock/fake）。

4. **对外暴露稳定的接口，隐藏内部实现**
   - 模块只暴露必要的函数/类给外部使用，内部辅助函数/中间状态不应该被外部模块直接调用或读取。
   - 修改模块内部实现时，只要对外接口（函数签名、返回结构）不变，其他模块不应该被影响。

5. **避免"上帝对象/上帝模块"**
   - 不要把项目中大部分逻辑都塞进一个类或一个文件（如一个 `utils.py` 塞下所有逻辑，或一个 `Manager` 类管理所有业务）。发现这种趋势时应主动提出拆分建议。

6. **共享逻辑下沉，而不是复制粘贴**
   - 多个模块需要同样的逻辑时，应该提取为公共函数/公共模块，而不是复制一份代码到各处（避免后续修改一处、遗漏其他处）。

## 执行方式
- 在设计新功能的模块结构、或修改现有模块的依赖关系之前，先说明你打算如何划分职责、模块间如何依赖，确认这个划分符合上述原则。
- 如果发现现有代码已经存在循环依赖、上帝对象等问题，在改动相关代码时可以顺带提出重构建议（但不要在未经同意的情况下擅自做大范围重构）。

---
applyTo: "backend/**/*.py"
description: "FastAPI 路由 docstring 接口文档规范"
---
# FastAPI 路由 docstring 接口文档规范

## 背景
本项目基于 FastAPI。`/docs`（Swagger UI）与 `/openapi.json` 完全由代码生成：
- 路由函数 **docstring 第一行** → 接口 `summary`
- docstring **空行后正文** → 接口 `description`
- Pydantic 模型的 `Field(description=...)` → body 参数说明
- `Query/Form/Path(description=...)` → query/form/path 参数说明

不需要任何 YAML、`swag_from`、`@api` 等装饰器。

## 核心要求

1. **每个新增路由必须编写完整的中文 docstring**，至少包含：
   - 一句话功能摘要（第一行，动作式，如"获取工作流任务详情"）
   - 空行后的详细说明：关键业务规则、边界行为（如"若 xx 为空则不修改""超时时长强制 4~15 秒"）
   - `Args:` 段（Google 风格）：列出 path/query/form 参数，每个写明含义与约束
   - `Returns:` 段：按「外层结构 + 关键字段及类型」展开，写清各字段含义；返回文件流时写明流类型与文件名规则
   - `Raises:` 段（可选）：列出常见错误状态码与触发条件（400/404/500 等）

2. **修改路由时同步更新 docstring**，包括：
   - 新增/删除/重命名请求参数（path/query/body/form）
   - 参数类型、是否必填、取值范围变化
   - 响应结构新增/删除/修改字段
   - 新增错误状态码或触发条件变化
   - 不允许"代码改了但文档还是旧版"——docstring 与代码行为不一致视为改动未完成

3. **参数描述的三种写法**
   - **body 参数**：在 Pydantic 模型字段上写 `Field(..., description="中文含义与取值范围")`
   - **query/form/path 参数**：简单参数用 `Query/Form/Path(..., description="...")`；复杂说明写在 docstring 的 `Args:` 段
   - **通用补充**：docstring 的 `Args:` 段对所有参数都可再补充上下文信息（如"下标列表，来自 xx 接口的返回顺序"）

4. **格式细节**
   - 返回结构要写到具体字段层级，不能只写"返回任务详情"。
   - 涉及业务规则的隐含行为（如"若当前集存在同名同类型资产则跳过"）要在说明或字段描述里体现。
   - 中文书写，字段名保持代码中的英文原名。

## 参考模板

```python
@router.get("/workflow_tasks/{task_id}")
def get_workflow_task(task_id: str, include_content: bool = Query(True, description="是否包含脚本等大字段内容")):
    """
    获取单个工作流任务的详情。

    返回任务的基础信息、各 Tab 状态与资源清单；当 include_content 为 true 时，
    额外返回脚本内容等大字段，供编辑页加载使用。

    Args:
        task_id: 工作流任务 ID（创建接口返回的 task_id）
        include_content: 是否包含脚本、文案等大字段内容

    Returns:
        任务详情对象（外层固定包一层 "task" 键）。

    Raises:
        404: 任务不存在
    """
    ...
```

## 执行方式
- 新建路由时，docstring 与路由实现在同一次改动中一起完成，不要先写代码、"回头再补文档"。
- 修改路由时，先检查现有 docstring 的 `Args:`/`Returns:` 是否仍然准确；若本次改动涉及入参/响应变化，必须同步更新，并在回复中提醒同步更新了哪些文档字段。

---
mode: ask
description: "看当前暂存的更改的代码，按 Header/Body/Footer 规范写中文 commit message。"
---
看当前暂存的更改的代码，写 commit message（不要运行 git commit，只需要生成信息即可）。全部使用中文书写。

## 整体结构

message 由三部分组成：**Header（必需）**、**Body（可选）**、**Footer（可选）**，三部分之间用空行分隔：

```
<type>(<scope>): <subject>
（空一行）
<body>
（空一行）
<footer>
```

Body 和 Footer 不是每次都要写，改动简单直接省略即可，不要为了凑格式硬写。

## Header（必需，只有一行）

格式：`<type>(<scope>): <subject>`

**type**（必需）：从以下选择，根据改动内容判断，选最贴切的一个；涉及多种类型时选影响最大的那个：
- feat：新增功能
- fix：修复 bug
- docs：仅文档改动
- style：不影响代码逻辑的格式调整（空格、分号等）
- refactor：重构代码（不新增功能也不修复 bug）
- perf：性能优化
- test：新增或修改测试
- chore：构建流程、依赖管理、工具配置等杂项
- ci：CI/CD 配置相关

**scope**（可选）：本次改动影响的范围/模块，例如 `user`、`api`、`build` 等；判断不出合适的范围就整体省略（连括号一起省略，不要写空括号）。

**subject**（必需）：
- 用简明中文描述这次改动做了什么，动词开头（如"新增""修复""调整""重构"）
- 不超过 50 个字
- 结尾不加句号

## Body（可选）

改动较复杂、影响面较大、或者需要说明"为什么这么改"时才写：
- 说明改动的动机，以及和之前行为的对比
- 可以分多行、用 `-` 列点说明
- 每行尽量不超过约 72 个字符，避免过长换行影响阅读

## Footer（可选）

只在以下两种情况使用：

1. **不兼容变更**：以 `BREAKING CHANGE:` 开头，说明变动内容、原因和迁移方式。
2. **关闭 issue**：写 `Closes #123`；一次关闭多个用逗号分隔，如 `Closes #123, #245`。

## Revert（特殊情况）

如果本次改动是撤销之前的某次提交：
- Header 写成 `revert: <被撤销提交的原 Header>`
- Body 固定写：`This reverts commit <hash>.`（hash 为被撤销提交的 SHA）

## 其他要求

- 描述部分只说明改了什么、为什么改，不需要写实现过程细节。

---
description: 接口文档规范
globs: backend/**/*.py
alwaysApply: false
---

# 项目 AI 协作规则

## 一、先规划，后编码，后总结

- 在为新功能或重大变更编写任何代码之前，必须先以 Markdown 格式创建一份详细的实施计划，呈现给我审查和批准。计划长度一般限制在 300 行以内，大规模更改则不超过 600 行。
- 在我明确表示批准（例如"计划通过""同意这个计划""可以开始"）之前，绝对不要编写任何代码。
- 分析需求前，先查看仓库中对应的现有代码，再开始分析详细需要变化的部分。

### 计划文档要求

新任务开始时，生成 `implementation_plan_xxxxx.md` 到项目 `docs/plan` 目录，包含：
1. 需求概述：用自己的话简要重述任务目标
2. 文件结构变更：列出所有需要新建/修改的文件
3. 核心组件/函数设计：关键类、函数、组件的职责和核心逻辑
4. 数据流与逻辑：数据如何在系统中流转
5. 问题与澄清：需求中模糊或不确定的部分

提交计划后必须停下等待明确批准，批准后严格按计划执行，编码过程中始终参考该计划。

### 执行报告要求

代码实现并自测通过后，在 `docs/reports` 目录生成 `report_xxxxx.md`（与对应 `implementation_plan_xxxxx.md` 使用相同后缀），包含：
1. 变更文件清单：新增/修改了哪些文件，简要说明改动内容
2. 新增/改动功能说明：具体实现了哪些功能点，与计划相比有无偏差
3. 前后端对接说明：新增/修改的接口（路径、方法、请求/响应结构），前端在哪些页面/组件中调用、如何联调；无前后端交互则注明"不涉及"
4. 遗留问题/后续 TODO

生成后用一句话告知报告路径。

## 二、代码长度与低耦合准则

- 单个代码文件：正常不超过 500 行，特殊情况最多不超过 1000 行。
- 单个函数/方法：正常不超过 200 行，特殊情况最多不超过 400 行。
- 新建或添加代码前先检查文件行数，接近超限时主动提出拆分方案，而不是直接堆代码。
- 拆分以"职责单一"为准则，不要为凑数机械切割。
- 因语言/框架限制无法满足时，在注释或提交说明中简要说明原因。

## 三、低耦合架构原则

- **单一职责**：一个模块/函数只做一件事，需要用"并且"描述功能时就该拆分。
- **依赖方向清晰**：模块间依赖单向（如路由层 → 服务层 → 数据访问层），禁止循环依赖；上层只依赖下层对外接口，不依赖内部实现细节。
- **依赖注入优先**：通过参数/构造函数传入依赖，而非硬编码 import 具体实现或依赖全局状态，便于替换和测试。
- **接口稳定，隐藏实现**：模块只暴露必要接口，内部辅助函数/中间状态不被外部直接调用。
- **避免上帝对象/上帝模块**：发现某个文件或类塞下了大部分逻辑时，主动提出拆分建议。
- **共享逻辑下沉**：多处需要相同逻辑时提取为公共函数/模块，不要复制粘贴。
- 设计新功能的模块结构或修改依赖关系前，先说明职责划分和依赖方向，确认符合以上原则。
- 发现现有代码已有循环依赖、上帝对象等问题，可在改动相关代码时顺带提出重构建议，但未经同意不要擅自做大范围重构。

# FastAPI 路由 docstring 接口文档规范

## 背景
本项目基于 FastAPI。`/docs`（Swagger UI）与 `/openapi.json` 完全由代码生成：
- 路由函数 docstring 第一行 → 接口 summary
- docstring 空行后正文 → 接口 description
- Pydantic 模型的 Field(description=...) → body 参数说明
- Query/Form/Path(description=...) → query/form/path 参数说明

不需要任何 YAML、swag_from、@api 等装饰器。

## 核心要求

1. 每个新增路由必须编写完整的中文 docstring，至少包含：
   - 一句话功能摘要（第一行，动作式，如"获取工作流任务详情"）
   - 空行后详细说明：关键业务规则、边界行为
   - Args 段（Google 风格）：列出 path/query/form 参数，写明含义与约束
   - Returns 段：外层结构 + 关键字段及类型，写清各字段含义
   - Raises 段（可选）：常见错误状态码与触发条件（400/404/500 等）

2. 修改路由时同步更新 docstring（参数变化、类型变化、响应结构变化、错误码变化等），不允许"代码改了文档没改"。

3. 参数描述写法：
   - body 参数：Pydantic 字段上写 Field(..., description="中文含义与取值范围")
   - query/form/path 参数：简单参数用 Query/Form/Path(..., description="...")；复杂说明写在 docstring 的 Args 段

4. 格式：返回结构写到具体字段层级；隐含业务规则要体现在说明里；中文书写，字段名保持代码中的英文原名。

## 执行方式
- 新建路由时，docstring 与实现同一次改动完成，不要"回头再补文档"。
- 修改路由时先检查现有 Args/Returns 是否仍准确，涉及入参/响应变化必须同步更新，并在回复中提醒同步更新了哪些字段。