862 lines
28 KiB
Markdown
862 lines
28 KiB
Markdown
# CodexPrompts.md：T01-T23 最小发送单元
|
||
|
||
## 使用说明
|
||
|
||
本文为每个 P0 Task 提供可复制发送给 Codex 的最小任务指令。
|
||
|
||
依据文件：
|
||
|
||
- `AGENTS.md`（当前仓库未发现 `docs/AGENTS.md`，规则文件位于仓库根目录）
|
||
- `docs/Tasks.md`
|
||
- `docs/TaskDependency.md`
|
||
- `docs/TDD.md`
|
||
|
||
全局执行口径：
|
||
|
||
- 严格 TDD：先写失败测试，再写最小实现，再重构。
|
||
- 不使用真实 TikHub / AI API；所有外部依赖必须 mock。
|
||
- 后台任务使用 `ThreadPoolExecutor(max_workers=1)` 和同步 `httpx.Client`。
|
||
- T13 固定 `AI_BATCH_SIZE=20`，不实现 batch size 减半。
|
||
- 报告总结失败默认文案统一为：`总结生成失败，请查看上方统计数据。`
|
||
- 当前处于初始单人开发和流程练习阶段，默认一次只发送一个 Task，不启用并行。
|
||
- 每个 Task 使用一个 `feat/tXX-short-description` 分支；完成验证后优先创建一个 focused commit。
|
||
- 不创建 PR，除非用户明确要求。
|
||
- 若未来启用并行，涉及 `docs/Tasks.md` 勾选项时由主协调者统一勾选，避免文档冲突。
|
||
|
||
## 当前推荐执行顺序
|
||
|
||
```text
|
||
T01 -> 审查/验证/commit
|
||
T02 -> 审查/验证/commit
|
||
T03 -> 审查/验证/commit
|
||
...
|
||
T23 -> 最终验收
|
||
```
|
||
|
||
当前阶段不要提前并行发送 T05/T06、T08/T09、T18/T19。等串行流程跑顺后，再由用户明确切换到并行模式。
|
||
|
||
## 未来并行发送参考
|
||
|
||
| 分组 | 任务 | 发送方式 |
|
||
|---|---|---|
|
||
| Group 1 | T01 -> T02 -> T03 -> T04 | 串行 |
|
||
| Group 2 | T05 + T06 | 可小心并行，需合并 `app/main.py` |
|
||
| Group 3 | T07 -> (T08 + T09) -> T10 -> T11 | T08/T09 可并行 |
|
||
| Group 4 | T12 -> T13 -> T14 -> T15 -> T16 | 基本串行 |
|
||
| Group 5 | T17 -> (T18 + T19 + T20 service 部分) -> T21 | T18/T19 可并行，T20 service 可并行 |
|
||
| Group 6 | T22 -> T23 | 串行；T22 可与页面收尾低冲突并行 |
|
||
|
||
---
|
||
|
||
### T01 任务指令
|
||
|
||
## 任务
|
||
完成 T01：初始化项目结构与依赖。
|
||
|
||
## 前置
|
||
前置任务：无。
|
||
|
||
并行发送：不可并行。T01-T04 是基础骨架，必须串行。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T01 部分
|
||
- `docs/TDD.md` §2、§3、§5.1
|
||
- `docs/DevelopmentPlan.md` §2、§4
|
||
|
||
## 分支
|
||
在分支 `feat/t01-project-skeleton` 上开发。
|
||
|
||
## 输出要求
|
||
- 创建 FastAPI 单体项目基础目录：`app/`、`app/services/`、`app/platforms/`、`app/templates/`、`app/static/`、`tests/`。
|
||
- 创建基础文件：`app/main.py`、`app/config.py`、`app/db.py`、`app/models.py`、`app/schemas.py`、依赖文件、`.env.example`。
|
||
- 实现 `/health`，返回 `{ "status": "ok" }`。
|
||
- 先写 `tests/unit/test_config.py` 和 `/health` 集成测试，再实现代码。
|
||
- 运行并通过：`pytest tests/unit tests/integration -q`。
|
||
|
||
## 边界
|
||
- 只做 T01，不实现任务 API、数据库模型细节或页面。
|
||
- 不提交真实 key、token、cookie。
|
||
- 若 `pyproject.toml` 与 `requirements.txt` 二选一，按现有仓库风格；若没有风格，优先 `pyproject.toml`。
|
||
|
||
---
|
||
|
||
### T02 任务指令
|
||
|
||
## 任务
|
||
完成 T02：配置管理与环境变量。
|
||
|
||
## 前置
|
||
前置任务：T01。
|
||
|
||
并行发送：不可并行。需等待 T01 项目骨架完成。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T02 部分
|
||
- `docs/TDD.md` §3.2、§5.1
|
||
- `docs/DevelopmentPlan.md` §2.1、§12.1
|
||
|
||
## 分支
|
||
在分支 `feat/t02-config-env` 上开发。
|
||
|
||
## 输出要求
|
||
- 修改 `app/config.py`，集中管理 TikHub、AI、数据库、HTTP 超时和任务配置。
|
||
- 修改 `.env.example`，只保留变量名和示例空值，不包含真实 key。
|
||
- 先写配置默认值和环境变量覆盖测试。
|
||
- 覆盖 `AI_CONCURRENCY=2`，硬上限不超过 3；`AI_MAX_RETRIES=3`；`CRAWL_PAGE_INTERVAL_SECONDS` 默认 1.5 且可从环境变量读取。
|
||
- 运行并通过：`pytest tests/unit/test_config.py -q`。
|
||
|
||
## 边界
|
||
- 只做配置，不实现数据库模型、任务 API、外部 HTTP client。
|
||
- 不引入超出计划的配置系统或服务发现。
|
||
|
||
---
|
||
|
||
### T03 任务指令
|
||
|
||
## 任务
|
||
完成 T03：数据库初始化与模型。
|
||
|
||
## 前置
|
||
前置任务：T01、T02。
|
||
|
||
并行发送：不可并行。模型是后续所有任务的共享基础。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T03 部分
|
||
- `docs/TDD.md` §3.2、§5.2、§5.3
|
||
- `docs/DevelopmentPlan.md` §5
|
||
|
||
## 分支
|
||
在分支 `feat/t03-database-models` 上开发。
|
||
|
||
## 输出要求
|
||
- 修改 `app/db.py` 和 `app/models.py`。
|
||
- 建立 SQLite + SQLAlchemy Base、engine、session。
|
||
- 启用 `check_same_thread=False`、`timeout=10`、WAL。
|
||
- 定义 `tasks`、`hotspots`、`content_items`、`comments`、`reports` 表。
|
||
- 实现任务状态、AI 分析状态、进度字段、报告字段和建议索引。
|
||
- 先写 `tests/unit/test_models.py`，断言所有表可创建、状态规则正确、`analysis_status=insufficient` 不改变 `Task.status`。
|
||
- 运行并通过：`pytest tests/unit/test_models.py -q`。
|
||
|
||
## 边界
|
||
- 只做模型和数据库初始化，不实现任务创建 API 或抓取流程。
|
||
- 不引入 Alembic。
|
||
|
||
---
|
||
|
||
### T04 任务指令
|
||
|
||
## 任务
|
||
完成 T04：任务创建 API 与单任务执行器。
|
||
|
||
## 前置
|
||
前置任务：T03。
|
||
|
||
并行发送：不可并行。该任务会修改核心 API、schema 和 task service。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T04 部分
|
||
- `docs/TDD.md` §6.1、§6.2
|
||
- `docs/DevelopmentPlan.md` §2.1、§9.3
|
||
|
||
## 分支
|
||
在分支 `feat/t04-task-api-executor` 上开发。
|
||
|
||
## 输出要求
|
||
- 修改 `app/schemas.py`、`app/main.py`。
|
||
- 创建 `app/services/task_service.py`。
|
||
- 实现 `POST /api/tasks`、`GET /api/tasks`、`GET /api/tasks/{task_id}`。
|
||
- 实现 `ThreadPoolExecutor(max_workers=1)`。
|
||
- 当已有 `status=running` 任务时，`POST /api/tasks` 返回 HTTP 400，响应体为 `{"detail": "当前有正在运行的任务，请稍后再试"}`，且不创建新任务。
|
||
- 先写 `tests/integration/test_task_creation.py` 和 `tests/unit/test_task_executor.py`。
|
||
- 运行并通过：`pytest tests/integration/test_task_creation.py tests/unit/test_task_executor.py -q`。
|
||
|
||
## 边界
|
||
- 只做任务创建、查询和执行器框架，不实现真实抓取、AI、报告。
|
||
- 不新增任务状态，任务主状态仅 `running` / `success` / `failed`。
|
||
|
||
---
|
||
|
||
### T05 任务指令
|
||
|
||
## 任务
|
||
完成 T05：僵尸任务恢复。
|
||
|
||
## 前置
|
||
前置任务：T04。
|
||
|
||
当前发送方式：串行发送。未来可与 T06 小心并行，但会共同修改 `app/main.py`，需主协调者合并。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T05 部分
|
||
- `docs/TDD.md` §6.3
|
||
- `docs/DevelopmentPlan.md` §4.3
|
||
|
||
## 分支
|
||
在分支 `feat/t05-task-recovery` 上开发。
|
||
|
||
## 输出要求
|
||
- 修改 `app/services/task_service.py` 和 `app/main.py`。
|
||
- 应用 lifespan 启动时，将遗留 `status=running` 的任务标记为 `failed`。
|
||
- 写入 `error_stage=system`、`error_type=unexpected_restart`、`error_message=系统重启，任务被中断`。
|
||
- 先写 `tests/integration/test_task_recovery.py`。
|
||
- 运行并通过：`pytest tests/integration/test_task_recovery.py -q`。
|
||
|
||
## 边界
|
||
- 只做启动恢复，不实现任务取消、补跑或复杂恢复。
|
||
- 若与 T06 并行，不要重构无关 route 结构。
|
||
|
||
---
|
||
|
||
### T06 任务指令
|
||
|
||
## 任务
|
||
完成 T06：首页 / 任务列表基础页面。
|
||
|
||
## 前置
|
||
前置任务：T04。
|
||
|
||
当前发送方式：串行发送。未来可与 T05 小心并行，但会共同修改 `app/main.py`，需主协调者合并。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T06 部分
|
||
- `docs/TDD.md` §12.1、§12.2、§12.4
|
||
- `docs/UIDesign.md`
|
||
|
||
## 分支
|
||
在分支 `feat/t06-index-task-list` 上开发。
|
||
|
||
## 输出要求
|
||
- 创建 `app/templates/base.html`、`app/templates/index.html`、`app/templates/partials/task_rows.html`。
|
||
- 创建 `app/static/app.css`、`app/static/app.js`。
|
||
- 修改 `app/main.py`，提供首页页面 route。
|
||
- 首页包含任务表单、任务列表、手动刷新、默认规模预估 1250。
|
||
- 任务创建成功后前端跳转至 `/tasks/{new_task_id}`。
|
||
- 实现基础面包屑 block。
|
||
- 先写 `tests/integration/test_routes.py` 和 `tests/unit/test_template_filters.py` 中相关测试。
|
||
- 运行并通过：`pytest tests/integration/test_routes.py tests/unit/test_template_filters.py -q`。
|
||
|
||
## 边界
|
||
- 只做首页和任务列表基础，不做任务详情、报告页、导出服务。
|
||
- 状态文案不要散落硬编码，优先集中映射或 macro。
|
||
|
||
---
|
||
|
||
### T07 任务指令
|
||
|
||
## 任务
|
||
完成 T07：外部 API 基础客户端与重试。
|
||
|
||
## 前置
|
||
前置任务：T02。
|
||
|
||
并行发送：不可并行。T08/T09 依赖本任务完成。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T07 部分
|
||
- `docs/TDD.md` §4.4、§6.2、§8.2、§13.3
|
||
- `docs/DevelopmentPlan.md` §6.1
|
||
|
||
## 分支
|
||
在分支 `feat/t07-api-client-retry` 上开发。
|
||
|
||
## 输出要求
|
||
- 创建 `app/platforms/base.py` 和 `app/services/crawl_service.py`。
|
||
- 封装同步 `httpx.Client` 调用、20s 超时、429 指数退避 1s -> 2s -> 4s、非 429 网络错误重试。
|
||
- 超过重试次数后返回或抛出可被上层捕获的结构化错误，不泄露 API key。
|
||
- 新增 `tests/fixtures/http_429_response.json` 或等价 fixture。
|
||
- 在 `tests/conftest.py` 补充 429/httpx mock fixture。
|
||
- 先写 `tests/unit/test_comment_pagination.py` 和 `tests/integration/test_failure_tolerance.py` 中相关测试。
|
||
- 运行并通过：`pytest tests/unit/test_comment_pagination.py tests/integration/test_failure_tolerance.py -q`。
|
||
|
||
## 边界
|
||
- 只做通用客户端和重试基础，不实现小红书/抖音字段映射。
|
||
- 禁止使用 `httpx.AsyncClient`。
|
||
|
||
---
|
||
|
||
### T08 任务指令
|
||
|
||
## 任务
|
||
完成 T08：小红书热点、笔记、评论字段映射。
|
||
|
||
## 前置
|
||
前置任务：T07。
|
||
|
||
当前发送方式：串行发送。未来可与 T09 并行发送；若并行，绝对不要修改 `app/platforms/douyin.py`。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T08 部分
|
||
- `docs/TDD.md` §4.1、§4.5、§7.1、§7.2
|
||
- `docs/API-Spike-Xiaohongshu.md`
|
||
- `docs/DevelopmentPlan.md` §6.2
|
||
|
||
## 分支
|
||
在分支 `feat/t08-xiaohongshu-mapping` 上开发。
|
||
|
||
## 输出要求
|
||
- 创建 `app/platforms/xiaohongshu.py`。
|
||
- 创建或补齐 fixtures：`xhs_hot_list.json`、`xhs_search_notes.json`、`xhs_comments_page_1.json`、`xhs_comments_page_2_empty.json`、`xhs_comments_missing_fields.json`。
|
||
- 实现 `fetch_hotspots()`、`search_items_by_hotspot()`、`fetch_comments()` 的最小字段映射。
|
||
- 热点读取 `data.data.items[]`，不误用外层 `data.data.title`。
|
||
- 笔记优先选择 `comments_count > 0`，不足时补充 `comments_count = 0`。
|
||
- 评论 ID 优先 `comment_id`，回退 `id`；保存 raw_data。
|
||
- 字段缺失不导致整批任务崩溃。
|
||
- 先写并通过：`pytest tests/unit/test_xiaohongshu_mapping.py -q`。
|
||
|
||
## 边界
|
||
- 只做小红书字段映射和最小抓取链路，不做分页通用停止条件和去重。
|
||
- 不发起真实 TikHub 请求。
|
||
|
||
---
|
||
|
||
### T09 任务指令
|
||
|
||
## 任务
|
||
完成 T09：抖音热点、视频、评论字段映射。
|
||
|
||
## 前置
|
||
前置任务：T07。
|
||
|
||
当前发送方式：串行发送。未来可与 T08 并行发送；若并行，绝对不要修改 `app/platforms/xiaohongshu.py`。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T09 部分
|
||
- `docs/TDD.md` §4.2、§4.5、§7.4、§7.5
|
||
- `docs/API-Spike-Douyin.md`
|
||
- `docs/DevelopmentPlan.md` §6.3
|
||
|
||
## 分支
|
||
在分支 `feat/t09-douyin-mapping` 上开发。
|
||
|
||
## 输出要求
|
||
- 创建 `app/platforms/douyin.py`。
|
||
- 创建或补齐 fixtures：`douyin_hot_list.json`、`douyin_search_videos.json`、`douyin_comments_page_1.json`、`douyin_comments_missing_fields.json`。
|
||
- 实现 `fetch_hotspots()`、`search_items_by_hotspot()`、`fetch_comments()` 的最小字段映射。
|
||
- 热点映射 `query_id`、`title`、`rank`、`hot_score`。
|
||
- 视频映射 `aweme_info.aweme_id`、`desc`、`author`、`statistics`。
|
||
- 评论 ID 优先 `comment_id`，回退 `cid`；保存 raw_data。
|
||
- 字段缺失不导致整批任务崩溃。
|
||
- 先写并通过：`pytest tests/unit/test_douyin_mapping.py -q`。
|
||
|
||
## 边界
|
||
- 只做抖音字段映射和最小抓取链路，不做分页通用停止条件和去重。
|
||
- 不发起真实 TikHub 请求。
|
||
|
||
---
|
||
|
||
### T10 任务指令
|
||
|
||
## 任务
|
||
完成 T10：评论分页、间隔与去重。
|
||
|
||
## 前置
|
||
前置任务：T08、T09、T02。
|
||
|
||
并行发送：不可并行。T10 会同时修改两个平台 adapter 和 `crawl_service.py`。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T10 部分
|
||
- `docs/TDD.md` §8.1、§8.2、§8.3
|
||
- `docs/DevelopmentPlan.md` §6.4
|
||
|
||
## 分支
|
||
在分支 `feat/t10-comment-pagination` 上开发。
|
||
|
||
## 输出要求
|
||
- 修改 `app/platforms/xiaohongshu.py`、`app/platforms/douyin.py`、`app/services/crawl_service.py`。
|
||
- 实现分页停止条件：达到评论数上限、空列表、最大 5 页、无下一页游标、连续失败超过重试次数。
|
||
- 实现小红书 cursor / index 推进；抖音 cursor 推进。
|
||
- 每次分页请求之间使用 1-2 秒基础间隔，默认读取 `CRAWL_PAGE_INTERVAL_SECONDS=1.5`。
|
||
- 实现同一任务同一内容条目同一评论 ID 去重。
|
||
- 先写并通过：`pytest tests/unit/test_comment_pagination.py -q`。
|
||
|
||
## 边界
|
||
- 只做评论分页、间隔、去重，不做任务主流程集成。
|
||
- 不改变 T08/T09 已验证的字段映射语义。
|
||
|
||
---
|
||
|
||
### T11 任务指令
|
||
|
||
## 任务
|
||
完成 T11：抓取任务主流程集成。
|
||
|
||
## 前置
|
||
前置任务：T04、T07、T08、T09、T10。
|
||
|
||
并行发送：不可并行。该任务集中修改任务主流程。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T11 部分
|
||
- `docs/TDD.md` §13.1、§13.2、§13.3、§13.4、§13.5
|
||
- `docs/DevelopmentPlan.md` §4.3、§13
|
||
|
||
## 分支
|
||
在分支 `feat/t11-crawl-task-flow` 上开发。
|
||
|
||
## 输出要求
|
||
- 修改 `app/services/task_service.py` 和 `app/services/crawl_service.py`。
|
||
- 串起热点、内容条目、评论抓取并入库。
|
||
- 更新 `processed_items_count`、`successful_items_count`、`failed_items_count`。
|
||
- 每处理完一个内容条目立即 `session.commit()`。
|
||
- 单个内容条目失败不阻断整批；热点接口失败导致任务 failed。
|
||
- 无任何内容条目成功时任务 failed；至少一个内容条目成功时任务 success。
|
||
- 覆盖跨热点重复 `source_item_id` 保留、同一热点重复去重。
|
||
- 先写并通过：`pytest tests/integration/test_task_flow_xiaohongshu.py tests/integration/test_task_flow_douyin.py tests/integration/test_failure_tolerance.py -q`。
|
||
|
||
## 边界
|
||
- 只做抓取主流程，不接入 AI 分析和报告生成。
|
||
- 不引入多 worker 或异步任务系统。
|
||
|
||
---
|
||
|
||
### T12 任务指令
|
||
|
||
## 任务
|
||
完成 T12：AI Prompt 与结构化输出校验。
|
||
|
||
## 前置
|
||
前置任务：T03、T02。
|
||
|
||
当前发送方式：串行发送。不建议与 T13 并行；未来最多仅并行准备 T14 报告统计测试数据，但不要实现 T14。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T12 部分
|
||
- `docs/TDD.md` §4.3、§4.6、§9.1、§9.2
|
||
- `docs/DevelopmentPlan.md` §7.1、§7.2
|
||
|
||
## 分支
|
||
在分支 `feat/t12-ai-schema` 上开发。
|
||
|
||
## 输出要求
|
||
- 创建 `app/services/ai_service.py`。
|
||
- 创建 `app/prompts/comment_analysis.txt`。
|
||
- 创建或补齐 fixtures：`ai_comments_success.json`、`ai_comments_invalid_json.txt`、`ai_comments_all_sentiments.json`。
|
||
- 实现 prompt 构造，输入包含 `comment_id` 和截断至 150 字的 `content`。
|
||
- AI 输出必须是 JSON Array，并用 Pydantic/schema 校验。
|
||
- 校验 sentiment 枚举、labels 最多 3 个、comment_id 必须匹配输入。
|
||
- 单条失败标记 `ai_analysis_status=failed`。
|
||
- 先写并通过：`pytest tests/unit/test_ai_schema.py -q`。
|
||
|
||
## 边界
|
||
- 只做 prompt 和 schema 校验，不做 AI 重试并发和任务流程接入。
|
||
- 不调用真实 AI 服务。
|
||
|
||
---
|
||
|
||
### T13 任务指令
|
||
|
||
## 任务
|
||
完成 T13：AI 重试、成功率统计。
|
||
|
||
## 前置
|
||
前置任务：T12、T04。
|
||
|
||
并行发送：不可并行。不要与 T16 同时修改 `task_service.py`。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T13 部分
|
||
- `docs/TDD.md` §9.3、§9.4、§9.5
|
||
- `docs/TaskDependency.md` §2.1
|
||
- `docs/DevelopmentPlan.md` §7.3、§7.4（若与 Tasks 冲突，以本指令和 Tasks 为准）
|
||
|
||
## 分支
|
||
在分支 `feat/t13-ai-retry-quality` 上开发。
|
||
|
||
## 输出要求
|
||
- 修改 `app/services/ai_service.py` 和必要的 `app/services/task_service.py` 质量状态逻辑。
|
||
- 固定 batch size 为 20，不做动态缩减，不实现 batch size 减半。
|
||
- 整批 JSON 解析失败时整批重试，最多 3 次。
|
||
- 第 3 次仍失败时，该批次全部评论标记 `ai_analysis_status=failed`，不阻断其他批次。
|
||
- 重试间隔符合 1s -> 2s -> 4s。
|
||
- 同一任务最多 2 个 AI 批量请求并发；同一内容条目多批评论串行。
|
||
- 实现 `analysis_success_rate` 和 `analysis_status`：>= 0.8 为 `normal`，< 0.8 为 `insufficient`，不改变任务主状态。
|
||
- 先写并通过：`pytest tests/unit/test_ai_schema.py -q`。
|
||
|
||
## 边界
|
||
- 不接入完整任务流程；T16 负责集成。
|
||
- 不使用 `httpx.AsyncClient`。
|
||
|
||
---
|
||
|
||
### T14 任务指令
|
||
|
||
## 任务
|
||
完成 T14：内容条目级报告生成。
|
||
|
||
## 前置
|
||
前置任务：T12、T13、T03。
|
||
|
||
并行发送：不建议与 T15 并行。T14/T15 都修改 `report_service.py`。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T14 部分
|
||
- `docs/TDD.md` §10.1、§10.2、§10.3、§10.5
|
||
- `docs/TaskDependency.md` §2.2
|
||
- `docs/DevelopmentPlan.md` §8.1、§8.3
|
||
|
||
## 分支
|
||
在分支 `feat/t14-item-report` 上开发。
|
||
|
||
## 输出要求
|
||
- 创建 `app/services/report_service.py`。
|
||
- 创建 `app/prompts/report_summary.txt`。
|
||
- 实现内容条目级报告生成，保存 `metrics_json`、`typical_comments_json`、`summary`、`markdown_content`。
|
||
- 统计情绪、Top 5 标签、典型评论；典型评论优先点赞数，缺失时按抓取顺序。
|
||
- 总结 AI 输入包含统计摘要和典型评论文本，每条评论截断至 150 字。
|
||
- 总结 AI 使用纯文本输出，不使用 JSON Schema。
|
||
- 内容条目总结超过 200 字时截断。
|
||
- 总结 AI 超时或失败时使用默认文案：`总结生成失败，请查看上方统计数据。`
|
||
- 先写并通过：`pytest tests/unit/test_report_stats.py -q`。
|
||
|
||
## 边界
|
||
- 只做内容条目级报告，不做热点级报告和任务流程接入。
|
||
- 不在页面 route 中临时计算统计。
|
||
|
||
---
|
||
|
||
### T15 任务指令
|
||
|
||
## 任务
|
||
完成 T15：热点级报告生成。
|
||
|
||
## 前置
|
||
前置任务：T14。
|
||
|
||
并行发送：不建议并行。T15 扩展 T14 的同一 `report_service.py`。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T15 部分
|
||
- `docs/TDD.md` §10.1、§10.2、§10.4、§10.5
|
||
- `docs/TaskDependency.md` §2.2
|
||
- `docs/DevelopmentPlan.md` §8.2、§8.3
|
||
|
||
## 分支
|
||
在分支 `feat/t15-hotspot-report` 上开发。
|
||
|
||
## 输出要求
|
||
- 修改 `app/services/report_service.py`。
|
||
- 实现热点级报告生成，聚合热点下所有内容条目。
|
||
- 统计内容条目数量、评论样本数、情绪分布、Top 5 标签、典型评论。
|
||
- 生成热点级 Markdown，并保存到 `reports`。
|
||
- 任务完成后报告生成顺序为：先内容条目报告，再热点报告。
|
||
- 热点总结超过 300 字时截断。
|
||
- 总结 AI 超时或失败时使用默认文案：`总结生成失败，请查看上方统计数据。`
|
||
- 先写并通过：`pytest tests/unit/test_report_stats.py -q`。
|
||
|
||
## 边界
|
||
- 只做热点级报告，不接入任务主流程。
|
||
- 页面展示和导出必须后续读取预生成报告，不在 route 中即时计算。
|
||
|
||
---
|
||
|
||
### T16 任务指令
|
||
|
||
## 任务
|
||
完成 T16：AI + 报告集成到任务流程。
|
||
|
||
## 前置
|
||
前置任务：T11、T13、T14、T15。
|
||
|
||
并行发送：不可并行。该任务是抓取、AI、报告的主集成点。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T16 部分
|
||
- `docs/TDD.md` §13.1、§13.2、§13.3、§9.5、§10
|
||
- `docs/DevelopmentPlan.md` §4.3、§7、§8、§13
|
||
|
||
## 分支
|
||
在分支 `feat/t16-ai-report-flow` 上开发。
|
||
|
||
## 输出要求
|
||
- 修改 `app/services/task_service.py`、`app/services/ai_service.py`、`app/services/report_service.py`。
|
||
- 在任务流程中调用 AI 分析和报告生成。
|
||
- 任务完成后评论有 sentiment、labels，reports 已入库。
|
||
- 写入 `analysis_success_rate` 和 `analysis_status`。
|
||
- 每完成一批 AI 分析（20 条评论）后立即 `session.commit()`。
|
||
- AI 单批失败不阻断其他批次。
|
||
- 扩展并通过：`pytest tests/integration/test_task_flow_xiaohongshu.py tests/integration/test_task_flow_douyin.py tests/integration/test_failure_tolerance.py -q`。
|
||
|
||
## 边界
|
||
- 不做页面、导出、Docker。
|
||
- 不改变 T13 固定 batch size 策略。
|
||
|
||
---
|
||
|
||
### T17 任务指令
|
||
|
||
## 任务
|
||
完成 T17：任务详情页。
|
||
|
||
## 前置
|
||
前置任务：T06、T11；建议 T16 完成后再做以展示 AI/报告状态。
|
||
|
||
并行发送：T17 是 T18/T19 的前置，不建议并行。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T17 部分
|
||
- `docs/TDD.md` §12.1、§12.4
|
||
- `docs/UIDesign.md`
|
||
|
||
## 分支
|
||
在分支 `feat/t17-task-detail-page` 上开发。
|
||
|
||
## 输出要求
|
||
- 创建 `app/templates/tasks/detail.html`。
|
||
- 修改 `app/main.py` 增加任务详情页 route。
|
||
- 展示任务概览：任务 ID、平台、创建时间、耗时、状态、AI 分析状态、进度、错误信息。
|
||
- 实现热点手风琴列表，默认展开 rank=1。
|
||
- 内容条目失败时展示失败原因。
|
||
- 任务 running 且热点为空时展示 Spinner。
|
||
- 面包屑：首页 -> 任务 `#{task_id}`，首页链接指向 `/`。
|
||
- 热点报告入口在 T18 前仅需 href 非空。
|
||
- 先写并通过：`pytest tests/integration/test_routes.py tests/unit/test_template_filters.py -q`。
|
||
|
||
## 边界
|
||
- 只做任务详情页，不实现热点报告页和内容条目详情页。
|
||
- 不在模板中做业务统计计算。
|
||
|
||
---
|
||
|
||
### T18 任务指令
|
||
|
||
## 任务
|
||
完成 T18：热点级报告页。
|
||
|
||
## 前置
|
||
前置任务：T15、T17。
|
||
|
||
当前发送方式：串行发送。未来可与 T19 并行，但二者都会修改 `app/main.py` 和 `tests/integration/test_routes.py`，需主协调者合并。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T18 部分
|
||
- `docs/TDD.md` §12.1、§12.4、§11.3、§11.4
|
||
- `docs/UIDesign.md`
|
||
|
||
## 分支
|
||
在分支 `feat/t18-hotspot-report-page` 上开发。
|
||
|
||
## 输出要求
|
||
- 创建 `app/templates/hotspots/report.html`。
|
||
- 修改 `app/main.py` 增加热点报告页 route。
|
||
- 页面读取预生成热点报告。
|
||
- 展示热点基础信息、内容条目数量、评论样本数、情绪分布、Top 5 标签、典型评论、AI 总结和分析不足 Alert。
|
||
- 添加 Markdown 导出按钮和热点下全部评论 CSV 导出按钮。
|
||
- 报告缺失时显示友好状态，不返回 HTTP 500。
|
||
- 实现面包屑：首页 -> 任务 -> 热点 -> 汇总报告。
|
||
- 先写并通过：`pytest tests/integration/test_routes.py -q`。
|
||
|
||
## 边界
|
||
- 只做热点报告页，不实现内容条目详情页。
|
||
- 页面不得即时计算报告统计，必须读取 reports 预生成数据。
|
||
|
||
---
|
||
|
||
### T19 任务指令
|
||
|
||
## 任务
|
||
完成 T19：内容条目详情页与评论明细。
|
||
|
||
## 前置
|
||
前置任务：T14、T17。
|
||
|
||
当前发送方式：串行发送。未来可与 T18 并行，但二者都会修改 `app/main.py` 和 `tests/integration/test_routes.py`，需主协调者合并。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T19 部分
|
||
- `docs/TDD.md` §12.3、§12.4、§12.5
|
||
- `docs/UIDesign.md`
|
||
|
||
## 分支
|
||
在分支 `feat/t19-item-detail-page` 上开发。
|
||
|
||
## 输出要求
|
||
- 创建 `app/templates/items/detail.html`。
|
||
- 修改 `app/main.py` 增加内容条目详情页 route。
|
||
- 展示内容条目基础信息、原始内容链接、内容条目级报告。
|
||
- 评论明细最多展示 100 条。
|
||
- 评论排序：点赞数降序；点赞数相同或缺失时评论时间降序。
|
||
- labels JSON Array 渲染为多个标签块。
|
||
- 评论为空时展示空状态。
|
||
- 实现面包屑：首页 -> 任务 -> 热点 -> 内容条目。
|
||
- 先写并通过：`pytest tests/integration/test_routes.py tests/unit/test_template_filters.py -q`。
|
||
|
||
## 边界
|
||
- P1 原始 JSON `<details>` 调试入口不是 P0，除非用户明确要求，不要实现。
|
||
- 不实现热点报告页或导出服务。
|
||
|
||
---
|
||
|
||
### T20 任务指令
|
||
|
||
## 任务
|
||
完成 T20：导出服务。
|
||
|
||
## 前置
|
||
前置任务：T14、T15、T18、T19。服务层可在 T14/T15 后先做，但 route 和按钮状态需等页面完成。
|
||
|
||
当前发送方式：串行发送。未来 T20 service/unit-test 部分可与 T18/T19 页面并行；完整 T20 不建议与 T21 并行。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T20 部分
|
||
- `docs/TDD.md` §11、§12.5
|
||
- `docs/DevelopmentPlan.md` §11
|
||
|
||
## 分支
|
||
在分支 `feat/t20-export-service` 上开发。
|
||
|
||
## 输出要求
|
||
- 创建 `app/services/export_service.py`。
|
||
- 修改 `app/main.py` 增加导出 routes：
|
||
- `GET /api/export/items/{item_id}/comments.csv`
|
||
- `GET /api/export/hotspots/{hotspot_id}/comments.csv`
|
||
- `GET /api/export/items/{item_id}.md`
|
||
- `GET /api/export/hotspots/{hotspot_id}.md`
|
||
- CSV 使用 `UTF-8-SIG`，字段符合 TDD §11.1。
|
||
- labels JSON Array 导出为中文逗号拼接。
|
||
- 防 CSV 公式注入：`=`、`+`、`-`、`@` 开头加单引号。
|
||
- 评论内容中的换行符替换为空格。
|
||
- 文件名安全处理符合 TDD §11.2。
|
||
- Markdown 直接读取 `reports.markdown_content`。
|
||
- 补充导出按钮 disabled 条件测试。
|
||
- 先写并通过：`pytest tests/unit/test_export.py tests/integration/test_routes.py -q`。
|
||
|
||
## 边界
|
||
- 不做 Excel 导出或 JSON 正式导出。
|
||
- 不重新计算报告 Markdown。
|
||
|
||
---
|
||
|
||
### T21 任务指令
|
||
|
||
## 任务
|
||
完成 T21：模板宏、过滤器与静态交互。
|
||
|
||
## 前置
|
||
前置任务：T06、T17、T18、T19、T20。
|
||
|
||
并行发送：不建议并行。T21 是页面共享层收敛任务。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T21 部分
|
||
- `docs/TDD.md` §12
|
||
- `docs/UIDesign.md`
|
||
|
||
## 分支
|
||
在分支 `feat/t21-template-macros-js` 上开发。
|
||
|
||
## 输出要求
|
||
- 创建 macro：`status_badge.html`、`sentiment_badge.html`、`label_tags.html`。
|
||
- 注册 `from_json` Jinja2 filter。
|
||
- 修改 `app/static/app.js` 和 `app/static/app.css`，实现表单范围校验、规模预估实时计算、导出 Blob 下载。
|
||
- 严禁对外部平台内容使用 `|safe`。
|
||
- 在 `base.html` 中定义 title block。
|
||
- 各页面 title 符合 Tasks T21 规范。
|
||
- 状态文案集中管理。
|
||
- 先写并通过：`pytest tests/unit/test_template_filters.py tests/integration/test_routes.py -q`。
|
||
|
||
## 边界
|
||
- 只做共享模板、filter、静态交互收敛，不新增页面功能。
|
||
- 不实现 P1 自动轮询或进度条，除非用户明确要求。
|
||
|
||
---
|
||
|
||
### T22 任务指令
|
||
|
||
## 任务
|
||
完成 T22：Docker Compose 与部署。
|
||
|
||
## 前置
|
||
前置任务：T01、T02、T03；建议 T16/T21 后执行以便完整验收。
|
||
|
||
当前发送方式：串行发送。未来可与页面 polish 收尾低冲突并行，但会修改 `.env.example`，需避开 T02/T21 的同文件修改。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T22 部分
|
||
- `docs/TDD.md` §15.1、§16.2
|
||
- `docs/DevelopmentPlan.md` §12.2
|
||
|
||
## 分支
|
||
在分支 `feat/t22-docker-compose` 上开发。
|
||
|
||
## 输出要求
|
||
- 创建 `Dockerfile`。
|
||
- 创建 `docker-compose.yml`，包含 app 服务和 `./data:/app/data` 数据卷。
|
||
- 暴露 8000 端口。
|
||
- 容器启动后可初始化数据库。
|
||
- SQLite 写入 `./data/app.db`。
|
||
- Dockerfile 使用非 root 用户 `appuser`。
|
||
- 确认挂载卷目录对 `appuser` 可写。
|
||
- 写测试或验证：容器内进程 `whoami` 不返回 root。
|
||
- 运行并通过：
|
||
- `docker compose up --build`
|
||
- `curl -f http://localhost:8000/health`
|
||
|
||
## 边界
|
||
- 只做 Docker Compose 单服务部署。
|
||
- 不引入 PostgreSQL、Redis、Celery、Nginx 或登录系统。
|
||
|
||
---
|
||
|
||
### T23 任务指令
|
||
|
||
## 任务
|
||
完成 T23：最终测试与手工验收。
|
||
|
||
## 前置
|
||
前置任务：T01-T22。
|
||
|
||
并行发送：不可并行。T23 是最终验收和文档收口任务。
|
||
|
||
请先读取：
|
||
- `AGENTS.md`
|
||
- `docs/Tasks.md` 中 T23 部分
|
||
- `docs/TDD.md` §15.2、§16.1、§16.2
|
||
- `docs/TaskDependency.md`
|
||
- `README.md`（如存在）
|
||
|
||
## 分支
|
||
在分支 `feat/t23-final-acceptance` 上开发。
|
||
|
||
## 输出要求
|
||
- 运行并通过：
|
||
- `pytest tests/unit -q`
|
||
- `pytest tests/integration -q`
|
||
- `pytest tests/unit tests/integration --cov=app --cov-branch --cov-report=term-missing`
|
||
- 若覆盖率低于目标，补测试后再继续。
|
||
- 运行 Docker 验收：
|
||
- `docker compose up --build`
|
||
- `curl -f http://localhost:8000/health`
|
||
- 按 T23 手工验收清单验证小红书和抖音默认任务流程。
|
||
- 如项目已有 `README.md`，补充启动和验收说明。
|
||
- 只有在对应任务真实完成且验证通过后，才更新 `docs/Tasks.md` 勾选项。
|
||
- 输出最终验收报告：通过项、失败项、已知限制、已运行命令。
|
||
|
||
## 边界
|
||
- 不新增 P1/P2 功能。
|
||
- 不为了通过验收而删除关键测试或降低断言。
|
||
- 不提交真实 API key 或用户私密数据。
|