meijiali/hot_comment_radar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c612afd217407c6cae945181d977898d3e8bca80
hot_comment_radar/docs/CodexPrompts.md
T

28 KiB
Raw Blame History

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 勾选项时由主协调者统一勾选，避免文档冲突。

当前推荐执行顺序

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 或用户私密数据。
Reference in New Issue View Git Blame Copy Permalink