# AGENTS.md

## 目的

本文件定义 AI 编码代理在本仓库中的工作方式。它是操作指南，不是产品需求文档。

不要在这里复述或替代产品规格。产品需求、UI 决策、技术决策和测试期望都放在 `docs/` 中。

## 信息源

开始实现前，按以下顺序阅读相关文档：

1. `docs/PRD.md`
2. `docs/RequirementsDoc.md`（如果仓库中存在；不存在则跳过）
3. `docs/FeatureSummary.md`
4. `docs/DevelopmentPlan.md`
5. `docs/Tasks.md`
6. `docs/TDD.md`
7. `docs/UIDesign.md`
8. `docs/API-Spike-Xiaohongshu.md`
9. `docs/API-Spike-Douyin.md`

如果存在 `docs/review-*.md` 文件，请在对应源文档之后阅读。
评审文件包含修正和澄清，可覆盖源文档中的模糊点。
例如，阅读 `Tasks.md` 后再阅读 `review-Tasks-kiro.md`。

使用 `docs/DevelopmentPlan.md` 判断架构和技术选型。使用 `docs/Tasks.md` 判断实现顺序。使用 `docs/TDD.md` 判断测试策略。使用 `docs/UIDesign.md` 判断页面结构和 UI 行为。使用 API Spike 文档判断平台字段映射和外部 API 流程。

如果文档之间存在冲突，或提供的上下文不足以做决定，
不要猜测或编造。立即停止执行，概述冲突或信息缺口，引用相关文件，
并在实现前向用户确认。该规则适用于所有层级的冲突，包括架构、
实现细节、命名约定和行为预期。
当源文档对必需决策表述模糊或没有说明时，绝不要带着假设继续。

如果无法在上述文档中找到答案，并且你自己的知识也不确定，请明确说明：
"I don't have enough context to decide this. Please provide [specific document or clarification]."
不要用虚构行为填补空白。

## 项目约束

- 先构建轻量级 MVP。
- 优先保证可工作的端到端流程，而不是大量未完成的功能。
- 整个项目遵循 TDD（Test-Driven Development，测试驱动开发）。对于每个功能、
  bug 修复、数据转换、服务或行为变更，先编写相关的失败测试，
  再实现让测试通过的最小代码，然后只在测试通过后进行重构。
  如果某个任务确实不适合测试先行，先说明原因，并添加尽可能贴近变更的验证覆盖。
- 保持架构与当前计划一致：FastAPI、SQLite、SQLAlchemy、Jinja2 模板、简单 CSS 或 Bootstrap、原生 JavaScript，以及 Docker Compose。
- 除非用户明确改变范围，否则不要引入前端 SPA 框架、Redis、Celery、PostgreSQL、登录系统、定时任务或分布式 worker。
- 不要提交真实 API key、token、cookie 或私密凭据。
- 将 TikHub 和 AI 提供商视为必须在测试中 mock 的外部依赖。
- 后台任务运行在 ThreadPoolExecutor 线程中，而不是 async event loop 中。
  后台任务中的所有外部 HTTP 调用都使用同步 `httpx.Client`。
  不要在后台任务函数中使用 `httpx.AsyncClient` 或 `await`。
- 报告在任务完成后预生成，并存储在 `reports` 表中。
  页面渲染和文件导出必须读取同一份预生成报告数据。
  不要在页面路由处理器中即时计算统计信息。
- 任务执行使用 `ThreadPoolExecutor(max_workers=1)`。一次只能运行一个任务。
  如果已经存在 `status=running` 的任务，创建新任务时返回 HTTP 400。

## MVP 纪律（为速度优化）

无论时间线如何，§Project Constraints 中的约束始终生效。
本节提供优先级指导，不代表可以跳过 `docs/Tasks.md` 中定义的 P0 功能。

当用户要求快速交付时，优化目标是尽早拿出可演示的切片。
但必须交付 `docs/Tasks.md` §7 中定义的全部 P0 任务（T01-T23）。
未经用户明确确认，不得延期任何 P0 功能。

只有在用户明确确认后才可以延期的项目：

- Playwright e2e 测试（仅 T23 的 Playwright 部分）
- P1 可选任务（docs/Tasks.md §9：自动轮询、JSON 调试面板、进度条）
- 高级 UI 打磨（面包屑、`<title>` 命名、进度动画）

未经用户明确确认绝不能延期的项目：

- 僵尸任务恢复（T05）
- 429 指数退避（T07）
- 评论分页（T10）
- AI 重试和降级（T13）
- 报告预生成（T14/T15/T16）
- CSV/Markdown 导出（T20）
- Docker Compose 打包（T22）

延期打磨、规模化、认证、调度以及未列入 `docs/Tasks.md` P0 范围的功能。
如果不确定某项是否属于 P0，请查看 `docs/Tasks.md`，它是权威任务列表。

## 开发流程

对于每个任务：

1. 检查相关文档和现有代码。
2. 确定最小的有用实现切片。
3. 在业务逻辑之前编写测试，覆盖：
   - 数据映射和字段转换（platforms -> models）
   - AI JSON Schema 校验和解析
   - 报告统计计算
   - 导出格式（CSV 结构、Markdown 结构）
   - 状态机转换（task status、analysis status）
   - 错误降级路径（重试耗尽 -> fallback behavior）
   对于 UI 模板、路由处理器接线和配置设置，
   在实现之前或同时编写测试，但绝不能在实现之后补写。
   这是 `docs/TDD.md` §2.1 的硬性规则："禁止先实现后补测试。"
4. 实现让测试通过的最小代码。
5. 运行聚焦的验证命令。
6. 汇报变更内容、已验证内容和剩余事项。

保持变更范围聚焦。避免无关重构。如果某个文件或设计问题阻塞当前请求，
提出服务于当前目标的最小修正方案。

### 项目记忆和对话经验

每次有价值的对话迭代后，代理都应考虑是否需要把经验保存在本 `AGENTS.md` 文件中，
以便未来代理更好地理解项目。例如：成功解决了反复出现的问题、
确认了模糊的项目约定、发现了可靠工作流，或澄清了代理之间应如何协作。

不要静默添加不确定或推测性的规则。如果经验存在歧义、可能改变产品行为，
或可能与信息源文档冲突，请在更新 `AGENTS.md` 前向用户确认。

新增内容应简洁且具备可操作性。`AGENTS.md` 应记录持久的代理工作规则，
而不是替代属于 `docs/` 的产品需求、实现规格或详细任务计划。

### 错误处理理念

这些原则定义于 `docs/DevelopmentPlan.md` §10 和 `docs/TDD.md` §13。
在所有实现中一致应用：

- 单个条目的失败不得导致整个任务崩溃。按每条评论或每个内容项隔离失败。
- 外部 API 失败（4xx/5xx）应使用指数退避重试（1s -> 2s -> 4s），
  然后优雅降级，并将错误记录到数据库中。
- AI 分析失败应按评论记录为 `ai_analysis_status=failed`，
  并反映到 `analysis_success_rate` 中，不得作为任务级失败向外抛出。
- 页面渲染绝不能因为缺少报告数据而返回 HTTP 500。
  使用默认文本或空状态 UI 替代。
- 每个处理单元（内容项、评论批次）都应独立提交到数据库。
  不要在整个任务期间持有一个长事务。

## 开发约定

- 修复任何工单必须在独立的 git worktree 中进行；开工前先用 `git worktree add` 创建专属工作目录，避免污染主工作区、便于多工单并行。修 CI 配置（Dockerfile、Drone 流水线等）可以直接在主仓库改，因为 CI 改动要打 tag 才能触发构建。
- 处理任何工单必须先检查并使用适用的 Superpowers Skill；在分析、提问、制定计划或改代码前，至少先启用 `using-superpowers`，并按任务性质继续使用 `systematic-debugging`、`test-driven-development`、`using-git-worktrees`、`verification-before-completion` 等相关技能。若判断没有适用技能，必须简短说明原因后再继续。
- 新功能需求类工单必须先使用 Superpowers 的 `brainstorming` 技能帮助澄清目标、约束和方案，再进入计划或实现；缺陷类工单必须先使用 `systematic-debugging` 技能复现问题并分析 root cause，再开始修复，禁止在根因未明确时直接改代码。
- 实现或修复工单完成后，必须继续按 Superpowers 收尾流程执行验证、代码审查、PR/合并准备和工作区清理；通常应依次使用 `verification-before-completion`、`requesting-code-review`、`finishing-a-development-branch` 等适用技能，在完成这些流程前不得声称工单已结束。

如果当前环境不支持 `superpowers:*` 前缀，请手动应用同样的认知顺序：
brainstorm -> plan -> test-first -> implement -> debug -> verify。进入验证阶段前，删除占位注释、调试 print/console.log，以及无说明的注释掉代码块。

## 多代理规则

仅在任务彼此独立、且可由主代理评审和集成时使用多个代理。

适合并行的任务：

- 审查文档是否存在冲突。
- 调研一个平台 API 映射。
- 为一个服务起草测试。
- 根据 `docs/UIDesign.md` 审查 UI 行为。
- 功能完成后审查实现中的 bug。
- 实现两个独立的平台适配器（例如 T08 Xiaohongshu 和 T09 Douyin）。
- 构建两个不共享数据查询的页面模板（例如 T17 和 T18）。
- 一个代理实现导出服务（T20），另一个代理处理模板宏（T21）。
- 一个代理为模块 A 编写单元测试，另一个代理实现与 A 没有依赖关系的模块 B。

避免为以下事项使用并行代理：

- 同时编辑同一个核心文件。
- 做出相互竞争的架构决策。
- 在没有单一负责人的情况下修改共享数据模型。
- 在没有集成计划的情况下实现广泛的横切变更。

主代理仍然负责最终决策、集成、验证和 Git 提交。

## 测试和验证

遵循 `docs/TDD.md`。

默认验证目标：

```bash
pytest tests/unit -q
pytest tests/integration -q
pytest tests/unit tests/integration -q
curl -f http://localhost:8000/health
```

在声称里程碑或任务完成前，运行覆盖率检查：

```bash
pytest tests/unit tests/integration --cov=app --cov-branch --cov-report=term-missing
```

以下模块的目标行覆盖率为 80% 或以上：

- `app/platforms/`（所有平台适配器）
- `app/services/ai_service.py`
- `app/services/report_service.py`
- `app/services/export_service.py`

如果这些模块的覆盖率低于 80%，先补充测试再继续。

开发期间使用聚焦命令，然后在完成前运行更广泛的验证。不要在单元测试中依赖真实 TikHub 或 AI API 调用。mock 外部 HTTP 调用和 AI 响应。

对于 UI 工作，在可行时通过手动或浏览器自动化验证渲染页面。
检查文本不重叠、核心操作可见，并且页面符合 `docs/UIDesign.md`。

## Git 工作流

使用小而聚焦的提交。一个提交应代表一个清晰变更。

### 单人提交纪律

对于这个单人项目，在完成每个独立功能/任务后，运行相关测试，
并为该任务相关文件创建一个聚焦的 git commit。除非用户明确要求，否则不要 push。
不要提交无关文件。

"独立功能/任务" 指能够被单独理解、测试和回滚的最小有用变更。例如：

- 一个 `docs/Tasks.md` 任务，例如 T07 API 重试、T20 导出或 T22 Docker。
- 一个狭窄 bug 修复，例如修复 401 错误显示或 CSV 换行处理。
- 一个内聚的页面或路由改进，例如添加任务详情页。
- 一个仅测试变更，用于记录或锁定某个行为。

不要把无关变更混在一个提交中。例如，不要把 Docker 部署、UI 重设计、
AI 重试逻辑和文档编辑合并在一个提交里，除非它们确实都严格服务于同一任务。

本项目的提交消息必须用中文书写，同时保留标准前缀。示例：

- `feat: 接入真实 AI 评论分析`
- `fix: 修复评论分页停止条件`
- `test: 补充导出 CSV 注入防护测试`
- `docs: 记录单人项目提交规则`

### 当前单人执行模式

当前项目阶段是初始单人开发和流程练习。除非用户明确启用并行工作或 PR 工作流，
否则按依赖顺序串行执行任务：一次一个任务。

除 CI 配置修复外，每个工单都应先在主仓库外创建独立 git worktree，再在该 worktree 中创建或检出对应任务分支。分支命名建议继续使用
`feat/tXX-short-description`、`fix/tXX-short-description` 或工单系统约定名称。
任务通过所需检查后，在可行时为该任务创建一个聚焦提交。
如果单个提交难以评审或安全回滚，大型任务可以拆分为多个有意义的提交。

前一个任务未完成评审、验证，并合并到工作基线或被明确批准作为下一个分支基线前，
不要开始下一个任务。除非用户要求，否则不要打开 PR。

推荐提交前缀：

- `docs:` 文档变更
- `feat:` 新的用户可见功能
- `fix:` bug 修复
- `test:` 仅测试
- `chore:` 维护、工具或项目设置

提交前：

```bash
git status --short
git diff
git diff --check
```

只提交与当前任务相关的文件。不要回滚无关的用户变更。只有在提交已验证且用户希望更新远端分支时才 push。

### 分支与 Worktree 策略

工单开发默认不直接在主工作区或 `main` 上修改业务代码。开工前从当前 `main` 创建专属 git worktree，并在 worktree 中使用任务分支完成开发。

修 CI 配置（Dockerfile、Drone 流水线等）可以直接在主仓库改，因为 CI 改动要打 tag 才能触发构建。除该例外外，如需直接在主仓库改动，必须先得到用户明确确认。

多代理并行开发：每个代理必须在从当前 `main` 派生的独立 Git 分支和独立 worktree 上工作。
分支命名约定：`agent/<agent-id>/<task-id>`（例如 `agent/codex-1/T08`）。

只有主代理（或用户）可以合并回 `main`。
合并前，该分支必须通过 §Testing And Verification 中定义的所有测试。

绝不能让两个代理在不同分支上同时编辑同一个文件。
如果任务依赖要求触碰同一文件，请串行处理。

## 安全规则

- 绝不要把密钥保存在源文件、文档、测试、fixture 或提交消息中。
- `.env.example` 只用于变量名。
- 仅在文档要求时保留原始外部 API 响应，并避免在 fixture 中包含私有用户数据。
- 在测试 fixture 中，将真实用户名、头像 URL、用户 ID 和 IP 地址替换为占位值
  （例如 "test_user_001"、"https://example.com/avatar.png"、
  "user_id_placeholder_001"）。不要未经脱敏就把生产 API 响应直接复制到 fixture 文件中。
- 数据库中的 `raw_data` JSON 字段可能包含用户生成内容。
  编写断言 `raw_data` 的测试时，只使用合成 fixture 数据。
- 如果对话中暴露了凭据，提醒用户轮换或删除它们。
- 除非用户明确要求，否则不要使用破坏性 Git 命令。

## 完成标准

只有满足以下条件，任务才算完成：

1. 请求的行为或文档已经存在。
2. 已运行相关测试或检查，或说明了无法运行的原因。
3. 工作范围限定在请求内。
4. 最终回复用通俗语言解释结果。
5. 清楚列出任何剩余风险或后续任务。
6. 如果完成的任务对应 `docs/Tasks.md` 中的复选框，将其标记为完成
   （把 `- [ ]` 改为 `- [x]`）。
7. 最终回复必须明确说明哪些测试已运行并通过、哪些边界情况已验证或 mock，
   以及当前实现的已知限制。

---

## 变更日志

| 日期 | 版本 | 变更 |
|---|---|---|
| 2025-07-10 | v1.0 | 初始版本 |
| 2025-07-10 | v1.1 | 基于双重评审合并后的修订（12 条指令）：§Two-Day MVP Discipline 重写为 "MVP Discipline (Optimized for Speed)"，不再是裁剪清单，并明确禁止未经用户确认延期 P0 功能；§Project Constraints 增加三项架构约束（后台线程中仅使用同步 httpx、预生成报告、单任务 executor 且冲突时返回 400）；§Source Of Truth 增加评审文件纳入规则、冲突时绝对停止策略、防幻觉指令和 RequirementsDoc.md 存在性保护；§Development Workflow 中的 TDD 指令从 "when practical" 升级为按类别强制执行，并明确引用 TDD.md §2.1；新增 Error Handling Philosophy 小节；§Testing And Verification 增加覆盖率命令和 80% 目标；§Git Workflow 增加分支策略和强制多代理分支隔离；§Multi-Agent Rules 增加 4 个构建类并行任务示例；§Superpowers Workflow 增加环境兼容性说明和验证前清理规则；§Safety Rules 增加 raw_data fixture 脱敏指导；§Completion Standard 增加 Tasks.md 复选框同步要求和明确测试结果汇报要求。 |
| 2026-07-07 | v1.2 | 融入新的开发约定：工单默认使用独立 git worktree；处理工单前必须检查并使用适用的 Superpowers Skill；新功能先 brainstorming，缺陷先 systematic-debugging；完成后按 verification、code review、finishing branch 流程收尾。同步删除旧的直接在 main 上工作的单代理分支规则，避免与 worktree 约定冲突。 |