# 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 `
` 调试入口不是 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 或用户私密数据。