docs: 将 AGENTS 指南翻译为中文
This commit is contained in:
meijiali
@@ -1,17 +1,17 @@
|
|||||||
# AGENTS.md
|
# AGENTS.md
|
||||||
|
|
||||||
## Purpose
|
## 目的
|
||||||
|
|
||||||
This file defines how AI coding agents should work in this repository. It is an operating guide, not a product requirements document.
|
本文件定义 AI 编码代理在本仓库中的工作方式。它是操作指南，不是产品需求文档。
|
||||||
|
|
||||||
Do not restate or replace the product specs here. Product requirements, UI decisions, technical decisions, and test expectations live in `docs/`.
|
不要在这里复述或替代产品规格。产品需求、UI 决策、技术决策和测试期望都放在 `docs/` 中。
|
||||||
|
|
||||||
## Source Of Truth
|
## 信息源
|
||||||
|
|
||||||
Before implementation, read the relevant docs in this order:
|
开始实现前，按以下顺序阅读相关文档：
|
||||||
|
|
||||||
1. `docs/PRD.md`
|
1. `docs/PRD.md`
|
||||||
2. `docs/RequirementsDoc.md` (if it exists in the repository; skip if absent)
|
2. `docs/RequirementsDoc.md`（如果仓库中存在；不存在则跳过）
|
||||||
3. `docs/FeatureSummary.md`
|
3. `docs/FeatureSummary.md`
|
||||||
4. `docs/DevelopmentPlan.md`
|
4. `docs/DevelopmentPlan.md`
|
||||||
5. `docs/Tasks.md`
|
5. `docs/Tasks.md`
|
||||||
@@ -20,188 +20,176 @@ Before implementation, read the relevant docs in this order:
|
|||||||
8. `docs/API-Spike-Xiaohongshu.md`
|
8. `docs/API-Spike-Xiaohongshu.md`
|
||||||
9. `docs/API-Spike-Douyin.md`
|
9. `docs/API-Spike-Douyin.md`
|
||||||
|
|
||||||
If `docs/review-*.md` files exist, read them after the corresponding source document.
|
如果存在 `docs/review-*.md` 文件，请在对应源文档之后阅读。
|
||||||
Review files contain corrections and clarifications that override ambiguous points
|
评审文件包含修正和澄清，可覆盖源文档中的模糊点。
|
||||||
in the source document. For example, read `review-Tasks-kiro.md` after `Tasks.md`.
|
例如，阅读 `Tasks.md` 后再阅读 `review-Tasks-kiro.md`。
|
||||||
|
|
||||||
Use `docs/DevelopmentPlan.md` for architecture and technology choices. Use `docs/Tasks.md` for implementation sequencing. Use `docs/TDD.md` for test strategy. Use `docs/UIDesign.md` for page structure and UI behavior. Use the API Spike docs for platform field mapping and external API flow.
|
使用 `docs/DevelopmentPlan.md` 判断架构和技术选型。使用 `docs/Tasks.md` 判断实现顺序。使用 `docs/TDD.md` 判断测试策略。使用 `docs/UIDesign.md` 判断页面结构和 UI 行为。使用 API Spike 文档判断平台字段映射和外部 API 流程。
|
||||||
|
|
||||||
If documents conflict or if the provided context is insufficient to make a decision,
|
如果文档之间存在冲突，或提供的上下文不足以做决定，
|
||||||
DO NOT guess or hallucinate. Stop execution immediately, summarize the conflict or
|
不要猜测或编造。立即停止执行，概述冲突或信息缺口，引用相关文件，
|
||||||
information gap, cite the files involved, and ask the user for confirmation before
|
并在实现前向用户确认。该规则适用于所有层级的冲突，包括架构、
|
||||||
implementing. This applies to all levels of conflict -- architecture, implementation
|
实现细节、命名约定和行为预期。
|
||||||
details, naming conventions, and behavioral expectations alike.
|
当源文档对必需决策表述模糊或没有说明时，绝不要带着假设继续。
|
||||||
Never proceed with an assumption when the source documents are ambiguous or silent
|
|
||||||
on a required decision.
|
|
||||||
|
|
||||||
If you cannot find the answer in the listed documents and your own knowledge is
|
如果无法在上述文档中找到答案，并且你自己的知识也不确定，请明确说明：
|
||||||
uncertain, state explicitly: "I don't have enough context to decide this. Please
|
"I don't have enough context to decide this. Please provide [specific document or clarification]."
|
||||||
provide [specific document or clarification]." Never fill gaps with invented behavior.
|
不要用虚构行为填补空白。
|
||||||
|
|
||||||
## Project Constraints
|
## 项目约束
|
||||||
|
|
||||||
- Build a lightweight MVP first.
|
- 先构建轻量级 MVP。
|
||||||
- Prefer a working end-to-end flow over broad incomplete features.
|
- 优先保证可工作的端到端流程，而不是大量未完成的功能。
|
||||||
- The entire project follows TDD (Test-Driven Development). For every feature,
|
- 整个项目遵循 TDD（Test-Driven Development，测试驱动开发）。对于每个功能、
|
||||||
bug fix, data transformation, service, or behavior change, write the relevant
|
bug 修复、数据转换、服务或行为变更，先编写相关的失败测试，
|
||||||
failing test first, implement the smallest code to pass it, then refactor only
|
再实现让测试通过的最小代码，然后只在测试通过后进行重构。
|
||||||
after tests pass. If a task cannot reasonably be test-first, state the reason
|
如果某个任务确实不适合测试先行，先说明原因，并添加尽可能贴近变更的验证覆盖。
|
||||||
before implementation and add verification coverage as close to the change as possible.
|
- 保持架构与当前计划一致：FastAPI、SQLite、SQLAlchemy、Jinja2 模板、简单 CSS 或 Bootstrap、原生 JavaScript，以及 Docker Compose。
|
||||||
- Keep the architecture aligned with the current plan: FastAPI, SQLite, SQLAlchemy, Jinja2 templates, simple CSS or Bootstrap, native JavaScript, and Docker Compose.
|
- 除非用户明确改变范围，否则不要引入前端 SPA 框架、Redis、Celery、PostgreSQL、登录系统、定时任务或分布式 worker。
|
||||||
- Do not introduce a frontend SPA framework, Redis, Celery, PostgreSQL, login system, scheduled jobs, or distributed workers unless the user explicitly changes the scope.
|
- 不要提交真实 API key、token、cookie 或私密凭据。
|
||||||
- Do not commit real API keys, tokens, cookies, or private credentials.
|
- 将 TikHub 和 AI 提供商视为必须在测试中 mock 的外部依赖。
|
||||||
- Treat TikHub and AI providers as external dependencies that must be mocked in tests.
|
- 后台任务运行在 ThreadPoolExecutor 线程中，而不是 async event loop 中。
|
||||||
- Background tasks run in a ThreadPoolExecutor thread, not in the async event loop.
|
后台任务中的所有外部 HTTP 调用都使用同步 `httpx.Client`。
|
||||||
Use synchronous `httpx.Client` for all external HTTP calls in background tasks.
|
不要在后台任务函数中使用 `httpx.AsyncClient` 或 `await`。
|
||||||
Do not use `httpx.AsyncClient` or `await` in background task functions.
|
- 报告在任务完成后预生成，并存储在 `reports` 表中。
|
||||||
- Reports are pre-generated after task completion and stored in the `reports` table.
|
页面渲染和文件导出必须读取同一份预生成报告数据。
|
||||||
Page rendering and file exports must read from the same pre-generated report data.
|
不要在页面路由处理器中即时计算统计信息。
|
||||||
Do not compute statistics on-the-fly in page route handlers.
|
- 任务执行使用 `ThreadPoolExecutor(max_workers=1)`。一次只能运行一个任务。
|
||||||
- Task execution uses `ThreadPoolExecutor(max_workers=1)`. Only one task can run at
|
如果已经存在 `status=running` 的任务，创建新任务时返回 HTTP 400。
|
||||||
a time. If a task with `status=running` already exists, reject new task creation
|
|
||||||
with HTTP 400.
|
|
||||||
|
|
||||||
## MVP Discipline (Optimized for Speed)
|
## MVP 纪律（为速度优化）
|
||||||
|
|
||||||
The constraints in §Project Constraints are always active regardless of timeline.
|
无论时间线如何，§Project Constraints 中的约束始终生效。
|
||||||
This section provides prioritization guidance, not permission to skip P0 features
|
本节提供优先级指导，不代表可以跳过 `docs/Tasks.md` 中定义的 P0 功能。
|
||||||
defined in `docs/Tasks.md`.
|
|
||||||
|
|
||||||
When the user asks for fast delivery, optimize for the earliest demonstrable slice.
|
当用户要求快速交付时，优化目标是尽早拿出可演示的切片。
|
||||||
But you MUST deliver all P0 tasks defined in `docs/Tasks.md` §7 (T01-T23).
|
但必须交付 `docs/Tasks.md` §7 中定义的全部 P0 任务（T01-T23）。
|
||||||
Do NOT defer any P0 feature without explicit user confirmation.
|
未经用户明确确认，不得延期任何 P0 功能。
|
||||||
|
|
||||||
Items that may be deferred only with explicit user confirmation:
|
只有在用户明确确认后才可以延期的项目：
|
||||||
|
|
||||||
- Playwright e2e tests (T23 Playwright portion only)
|
- Playwright e2e 测试（仅 T23 的 Playwright 部分）
|
||||||
- P1 optional tasks (docs/Tasks.md §9: auto-polling, JSON debug panel, progress bar)
|
- P1 可选任务（docs/Tasks.md §9：自动轮询、JSON 调试面板、进度条）
|
||||||
- Advanced UI polish (breadcrumbs, `<title>` naming, progress animations)
|
- 高级 UI 打磨（面包屑、`<title>` 命名、进度动画）
|
||||||
|
|
||||||
Items that must NOT be deferred without explicit user confirmation:
|
未经用户明确确认绝不能延期的项目：
|
||||||
|
|
||||||
- Zombie task recovery (T05)
|
- 僵尸任务恢复（T05）
|
||||||
- 429 exponential backoff (T07)
|
- 429 指数退避（T07）
|
||||||
- Comment pagination (T10)
|
- 评论分页（T10）
|
||||||
- AI retry and degradation (T13)
|
- AI 重试和降级（T13）
|
||||||
- Report pre-generation (T14/T15/T16)
|
- 报告预生成（T14/T15/T16）
|
||||||
- CSV/Markdown export (T20)
|
- CSV/Markdown 导出（T20）
|
||||||
- Docker Compose packaging (T22)
|
- Docker Compose 打包（T22）
|
||||||
|
|
||||||
Defer polish, scale, authentication, scheduling, and features not listed in
|
延期打磨、规模化、认证、调度以及未列入 `docs/Tasks.md` P0 范围的功能。
|
||||||
`docs/Tasks.md` P0 scope. When in doubt about whether something is P0,
|
如果不确定某项是否属于 P0，请查看 `docs/Tasks.md`，它是权威任务列表。
|
||||||
check `docs/Tasks.md` -- it is the authoritative task list.
|
|
||||||
|
|
||||||
## Development Workflow
|
## 开发流程
|
||||||
|
|
||||||
For each task:
|
对于每个任务：
|
||||||
|
|
||||||
1. Inspect the relevant docs and existing code.
|
1. 检查相关文档和现有代码。
|
||||||
2. Identify the smallest useful implementation slice.
|
2. 确定最小的有用实现切片。
|
||||||
3. Write tests BEFORE business logic for:
|
3. 在业务逻辑之前编写测试，覆盖：
|
||||||
- Data mapping and field transformation (platforms -> models)
|
- 数据映射和字段转换（platforms -> models）
|
||||||
- AI JSON Schema validation and parsing
|
- AI JSON Schema 校验和解析
|
||||||
- Report statistics calculation
|
- 报告统计计算
|
||||||
- Export formatting (CSV structure, Markdown structure)
|
- 导出格式（CSV 结构、Markdown 结构）
|
||||||
- State machine transitions (task status, analysis status)
|
- 状态机转换（task status、analysis status）
|
||||||
- Error degradation paths (retry exhaustion -> fallback behavior)
|
- 错误降级路径（重试耗尽 -> fallback behavior）
|
||||||
For UI templates, route handler wiring, and configuration setup,
|
对于 UI 模板、路由处理器接线和配置设置，
|
||||||
write tests before or alongside implementation -- but never after.
|
在实现之前或同时编写测试，但绝不能在实现之后补写。
|
||||||
This is a hard rule from `docs/TDD.md` §2.1: "禁止先实现后补测试。"
|
这是 `docs/TDD.md` §2.1 的硬性规则："禁止先实现后补测试。"
|
||||||
4. Implement the minimum code needed to pass the tests.
|
4. 实现让测试通过的最小代码。
|
||||||
5. Run focused verification commands.
|
5. 运行聚焦的验证命令。
|
||||||
6. Report what changed, what was verified, and what remains.
|
6. 汇报变更内容、已验证内容和剩余事项。
|
||||||
|
|
||||||
Keep changes scoped. Avoid unrelated refactors. If a file or design issue blocks the requested work, propose the smallest corrective change that serves the current goal.
|
保持变更范围聚焦。避免无关重构。如果某个文件或设计问题阻塞当前请求，
|
||||||
|
提出服务于当前目标的最小修正方案。
|
||||||
|
|
||||||
### Project Memory And Conversation Learnings
|
### 项目记忆和对话经验
|
||||||
|
|
||||||
After any valuable conversation iteration, agents should consider whether the
|
每次有价值的对话迭代后，代理都应考虑是否需要把经验保存在本 `AGENTS.md` 文件中，
|
||||||
learning should be preserved in this `AGENTS.md` file so future agents understand
|
以便未来代理更好地理解项目。例如：成功解决了反复出现的问题、
|
||||||
the project better. Examples include successfully resolving a recurring problem,
|
确认了模糊的项目约定、发现了可靠工作流，或澄清了代理之间应如何协作。
|
||||||
confirming an ambiguous project convention, discovering a reliable workflow, or
|
|
||||||
clarifying how agents should coordinate work in this repository.
|
|
||||||
|
|
||||||
Do not silently add uncertain or speculative rules. If the learning is ambiguous,
|
不要静默添加不确定或推测性的规则。如果经验存在歧义、可能改变产品行为，
|
||||||
could change product behavior, or might conflict with the source documents, ask the
|
或可能与信息源文档冲突，请在更新 `AGENTS.md` 前向用户确认。
|
||||||
user for confirmation before updating `AGENTS.md`.
|
|
||||||
|
|
||||||
Keep additions concise and operational. `AGENTS.md` should capture durable agent
|
新增内容应简洁且具备可操作性。`AGENTS.md` 应记录持久的代理工作规则，
|
||||||
working rules, not replace product requirements, implementation specs, or detailed
|
而不是替代属于 `docs/` 的产品需求、实现规格或详细任务计划。
|
||||||
task plans that belong in `docs/`.
|
|
||||||
|
|
||||||
### Error Handling Philosophy
|
### 错误处理理念
|
||||||
|
|
||||||
These principles are defined in `docs/DevelopmentPlan.md` §10 and `docs/TDD.md` §13.
|
这些原则定义于 `docs/DevelopmentPlan.md` §10 和 `docs/TDD.md` §13。
|
||||||
Apply them consistently across all implementations:
|
在所有实现中一致应用：
|
||||||
|
|
||||||
- A single item failure must not crash the entire task. Isolate failures at the
|
- 单个条目的失败不得导致整个任务崩溃。按每条评论或每个内容项隔离失败。
|
||||||
per-comment or per-content-item level.
|
- 外部 API 失败（4xx/5xx）应使用指数退避重试（1s -> 2s -> 4s），
|
||||||
- External API failures (4xx/5xx) should be retried with exponential backoff
|
然后优雅降级，并将错误记录到数据库中。
|
||||||
(1s -> 2s -> 4s), then gracefully degraded with error recorded in the database.
|
- AI 分析失败应按评论记录为 `ai_analysis_status=failed`，
|
||||||
- AI analysis failures should be recorded per-comment via `ai_analysis_status=failed`
|
并反映到 `analysis_success_rate` 中，不得作为任务级失败向外抛出。
|
||||||
and reflected in `analysis_success_rate`, not propagated as task-level failures.
|
- 页面渲染绝不能因为缺少报告数据而返回 HTTP 500。
|
||||||
- Page rendering must never return HTTP 500 due to missing report data.
|
使用默认文本或空状态 UI 替代。
|
||||||
Use default text or empty-state UI instead.
|
- 每个处理单元（内容项、评论批次）都应独立提交到数据库。
|
||||||
- Each processing unit (content item, comment batch) should commit to the database
|
不要在整个任务期间持有一个长事务。
|
||||||
independently. Do not hold a single transaction open for the entire task duration.
|
|
||||||
|
|
||||||
## Superpowers Workflow
|
## Superpowers 工作流
|
||||||
|
|
||||||
Superpowers are structured thinking modes available in certain AI coding environments
|
Superpowers 是某些 AI 编码环境（例如 Codex）中可用的结构化思考模式。
|
||||||
(e.g., Codex). If the current environment does not support `superpowers:*` prefixes,
|
如果当前环境不支持 `superpowers:*` 前缀，请手动应用同样的认知顺序：
|
||||||
apply the same cognitive sequence manually: brainstorm -> plan -> test-first -> implement
|
brainstorm -> plan -> test-first -> implement -> debug -> verify。
|
||||||
-> debug -> verify.
|
|
||||||
|
|
||||||
When superpowers skills are available, use them as the development process layer:
|
当 superpowers 技能可用时，将其作为开发过程层使用：
|
||||||
|
|
||||||
- Use `superpowers:brainstorming` before unclear feature design, scope decisions, or behavior changes.
|
- 在不明确的功能设计、范围决策或行为变更前，使用 `superpowers:brainstorming`。
|
||||||
- Use `superpowers:writing-plans` before substantial implementation.
|
- 在较大的实现前，使用 `superpowers:writing-plans`。
|
||||||
- Use `superpowers:test-driven-development` for business logic, data mapping, parsing, reporting, and bug fixes when practical.
|
- 对业务逻辑、数据映射、解析、报告和 bug 修复，在可行时使用 `superpowers:test-driven-development`。
|
||||||
|
|
||||||
Before moving from implementation to the verification step:
|
从实现阶段进入验证阶段前：
|
||||||
|
|
||||||
- Remove all placeholder comments (e.g., `# TODO: implement this`, `# FIXME`).
|
- 删除所有占位注释（例如 `# TODO: implement this`、`# FIXME`）。
|
||||||
- Remove all debugging print/console.log statements.
|
- 删除所有调试用 print/console.log 语句。
|
||||||
- Ensure no commented-out code blocks remain unless they serve as documentation
|
- 确保没有注释掉的代码块，除非它们是对刻意设计决策的文档说明（并标明原因）。
|
||||||
for a deliberate design decision (annotated with a reason).
|
|
||||||
|
|
||||||
- Use `superpowers:systematic-debugging` before fixing failing behavior or unexpected test results.
|
- 在修复失败行为或意外测试结果前，使用 `superpowers:systematic-debugging`。
|
||||||
- Use `superpowers:verification-before-completion` before claiming work is complete.
|
- 在声称工作完成前，使用 `superpowers:verification-before-completion`。
|
||||||
- Use `superpowers:requesting-code-review` for large changes or milestone completion.
|
- 对于大型变更或里程碑完成，使用 `superpowers:requesting-code-review`。
|
||||||
|
|
||||||
If the skills are unavailable, follow the same principles manually: clarify scope, write a short plan, test first where practical, debug from evidence, verify before completion, and keep commits focused.
|
如果技能不可用，请手动遵循同样原则：澄清范围、编写简短计划、尽量测试先行、
|
||||||
|
基于证据调试、完成前验证，并保持提交聚焦。
|
||||||
|
|
||||||
## Multi-Agent Rules
|
## 多代理规则
|
||||||
|
|
||||||
Use multiple agents only for independent work that can be reviewed and integrated by the main agent.
|
仅在任务彼此独立、且可由主代理评审和集成时使用多个代理。
|
||||||
|
|
||||||
Good parallel tasks:
|
适合并行的任务：
|
||||||
|
|
||||||
- Review docs for conflicts.
|
- 审查文档是否存在冲突。
|
||||||
- Investigate one platform API mapping.
|
- 调研一个平台 API 映射。
|
||||||
- Draft tests for one service.
|
- 为一个服务起草测试。
|
||||||
- Review UI behavior against `docs/UIDesign.md`.
|
- 根据 `docs/UIDesign.md` 审查 UI 行为。
|
||||||
- Review implementation for bugs after a feature is complete.
|
- 功能完成后审查实现中的 bug。
|
||||||
- Implementing two independent platform adapters (e.g., T08 Xiaohongshu and T09 Douyin).
|
- 实现两个独立的平台适配器（例如 T08 Xiaohongshu 和 T09 Douyin）。
|
||||||
- Building two page templates that do not share data queries (e.g., T17 and T18).
|
- 构建两个不共享数据查询的页面模板（例如 T17 和 T18）。
|
||||||
- Implementing export service (T20) while another agent works on template macros (T21).
|
- 一个代理实现导出服务（T20），另一个代理处理模板宏（T21）。
|
||||||
- Writing unit tests for module A while another agent implements module B that has no
|
- 一个代理为模块 A 编写单元测试，另一个代理实现与 A 没有依赖关系的模块 B。
|
||||||
dependency on A.
|
|
||||||
|
|
||||||
Avoid parallel agents for:
|
避免为以下事项使用并行代理：
|
||||||
|
|
||||||
- Editing the same core file at the same time.
|
- 同时编辑同一个核心文件。
|
||||||
- Making competing architecture decisions.
|
- 做出相互竞争的架构决策。
|
||||||
- Changing shared data models without one owner.
|
- 在没有单一负责人的情况下修改共享数据模型。
|
||||||
- Implementing broad cross-cutting changes without an integration plan.
|
- 在没有集成计划的情况下实现广泛的横切变更。
|
||||||
|
|
||||||
The main agent remains responsible for final decisions, integration, verification, and Git commits.
|
主代理仍然负责最终决策、集成、验证和 Git 提交。
|
||||||
|
|
||||||
## Testing And Verification
|
## 测试和验证
|
||||||
|
|
||||||
Follow `docs/TDD.md`.
|
遵循 `docs/TDD.md`。
|
||||||
|
|
||||||
Default verification targets:
|
默认验证目标：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
pytest tests/unit -q
|
pytest tests/unit -q
|
||||||
@@ -210,81 +198,75 @@ pytest tests/unit tests/integration -q
|
|||||||
curl -f http://localhost:8000/health
|
curl -f http://localhost:8000/health
|
||||||
```
|
```
|
||||||
|
|
||||||
Before claiming a milestone or task complete, run the coverage check:
|
在声称里程碑或任务完成前，运行覆盖率检查：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
pytest tests/unit tests/integration --cov=app --cov-branch --cov-report=term-missing
|
pytest tests/unit tests/integration --cov=app --cov-branch --cov-report=term-missing
|
||||||
```
|
```
|
||||||
|
|
||||||
Target line coverage: 80% or above for the following modules:
|
以下模块的目标行覆盖率为 80% 或以上：
|
||||||
|
|
||||||
- `app/platforms/` (all platform adapters)
|
- `app/platforms/`（所有平台适配器）
|
||||||
- `app/services/ai_service.py`
|
- `app/services/ai_service.py`
|
||||||
- `app/services/report_service.py`
|
- `app/services/report_service.py`
|
||||||
- `app/services/export_service.py`
|
- `app/services/export_service.py`
|
||||||
|
|
||||||
If coverage drops below 80% for these modules, add tests before proceeding.
|
如果这些模块的覆盖率低于 80%，先补充测试再继续。
|
||||||
|
|
||||||
Use focused commands while developing, then run broader verification before completion. Do not rely on real TikHub or AI API calls for unit tests. Mock external HTTP calls and AI responses.
|
开发期间使用聚焦命令，然后在完成前运行更广泛的验证。不要在单元测试中依赖真实 TikHub 或 AI API 调用。mock 外部 HTTP 调用和 AI 响应。
|
||||||
|
|
||||||
For UI work, verify rendered pages manually or with browser automation when practical. Check that text does not overlap, core actions are visible, and the page follows `docs/UIDesign.md`.
|
对于 UI 工作，在可行时通过手动或浏览器自动化验证渲染页面。
|
||||||
|
检查文本不重叠、核心操作可见，并且页面符合 `docs/UIDesign.md`。
|
||||||
|
|
||||||
## Git Workflow
|
## Git 工作流
|
||||||
|
|
||||||
Use small, focused commits. One commit should represent one clear change.
|
使用小而聚焦的提交。一个提交应代表一个清晰变更。
|
||||||
|
|
||||||
### Solo Commit Discipline
|
### 单人提交纪律
|
||||||
|
|
||||||
For this solo project, after completing each independent feature/task, run the
|
对于这个单人项目，在完成每个独立功能/任务后，运行相关测试，
|
||||||
relevant tests and create one focused git commit for the files related to that
|
并为该任务相关文件创建一个聚焦的 git commit。除非用户明确要求，否则不要 push。
|
||||||
task. Do not push unless the user explicitly asks. Do not commit unrelated
|
不要提交无关文件。
|
||||||
files.
|
|
||||||
|
|
||||||
An "independent feature/task" means the smallest useful change that can be
|
"独立功能/任务" 指能够被单独理解、测试和回滚的最小有用变更。例如：
|
||||||
understood, tested, and reverted on its own. Examples:
|
|
||||||
|
|
||||||
- One `docs/Tasks.md` task such as T07 API retry, T20 export, or T22 Docker.
|
- 一个 `docs/Tasks.md` 任务，例如 T07 API 重试、T20 导出或 T22 Docker。
|
||||||
- One narrow bug fix, such as fixing 401 error display or CSV newline handling.
|
- 一个狭窄 bug 修复，例如修复 401 错误显示或 CSV 换行处理。
|
||||||
- One cohesive page or route improvement, such as adding the task detail page.
|
- 一个内聚的页面或路由改进，例如添加任务详情页。
|
||||||
- One test-only change that documents or locks down one behavior.
|
- 一个仅测试变更，用于记录或锁定某个行为。
|
||||||
|
|
||||||
Do not mix unrelated changes in one commit. For example, do not combine Docker
|
不要把无关变更混在一个提交中。例如，不要把 Docker 部署、UI 重设计、
|
||||||
deployment, UI redesign, AI retry logic, and documentation edits unless they are
|
AI 重试逻辑和文档编辑合并在一个提交里，除非它们确实都严格服务于同一任务。
|
||||||
strictly required to complete one same task.
|
|
||||||
|
|
||||||
Commit messages for this project must be written in Chinese while keeping the
|
本项目的提交消息必须用中文书写，同时保留标准前缀。示例：
|
||||||
standard prefix. Examples:
|
|
||||||
|
|
||||||
- `feat: 接入真实 AI 评论分析`
|
- `feat: 接入真实 AI 评论分析`
|
||||||
- `fix: 修复评论分页停止条件`
|
- `fix: 修复评论分页停止条件`
|
||||||
- `test: 补充导出 CSV 注入防护测试`
|
- `test: 补充导出 CSV 注入防护测试`
|
||||||
- `docs: 记录单人项目提交规则`
|
- `docs: 记录单人项目提交规则`
|
||||||
|
|
||||||
### Current Solo Execution Mode
|
### 当前单人执行模式
|
||||||
|
|
||||||
The current project phase is initial solo development and process practice. Unless
|
当前项目阶段是初始单人开发和流程练习。除非用户明确启用并行工作或 PR 工作流，
|
||||||
the user explicitly enables parallel work or PR workflow, execute tasks
|
否则按依赖顺序串行执行任务：一次一个任务。
|
||||||
sequentially: one task at a time, in dependency order.
|
|
||||||
|
|
||||||
For this phase, use one task branch per `docs/Tasks.md` task, named
|
在此阶段，每个 `docs/Tasks.md` 任务使用一个任务分支，命名为
|
||||||
`feat/tXX-short-description` (for example, `feat/t01-project-skeleton`). After the
|
`feat/tXX-short-description`（例如 `feat/t01-project-skeleton`）。
|
||||||
task passes its required checks, create one focused commit for that task when
|
任务通过所需检查后，在可行时为该任务创建一个聚焦提交。
|
||||||
practical. Large tasks may be split into multiple meaningful commits only when a
|
如果单个提交难以评审或安全回滚，大型任务可以拆分为多个有意义的提交。
|
||||||
single commit would be hard to review or safely revert.
|
|
||||||
|
|
||||||
Do not start the next task until the previous task has been reviewed, verified,
|
前一个任务未完成评审、验证，并合并到工作基线或被明确批准作为下一个分支基线前，
|
||||||
and either merged into the working baseline or explicitly approved as the base for
|
不要开始下一个任务。除非用户要求，否则不要打开 PR。
|
||||||
the next branch. Do not open a PR unless the user asks for one.
|
|
||||||
|
|
||||||
Recommended commit prefixes:
|
推荐提交前缀：
|
||||||
|
|
||||||
- `docs:` documentation changes
|
- `docs:` 文档变更
|
||||||
- `feat:` new user-visible functionality
|
- `feat:` 新的用户可见功能
|
||||||
- `fix:` bug fixes
|
- `fix:` bug 修复
|
||||||
- `test:` tests only
|
- `test:` 仅测试
|
||||||
- `chore:` maintenance, tooling, or project setup
|
- `chore:` 维护、工具或项目设置
|
||||||
|
|
||||||
Before committing:
|
提交前：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git status --short
|
git status --short
|
||||||
@@ -292,57 +274,53 @@ git diff
|
|||||||
git diff --check
|
git diff --check
|
||||||
```
|
```
|
||||||
|
|
||||||
Commit only files related to the current task. Do not revert unrelated user changes. Push only after the commit is verified and the user wants the branch updated remotely.
|
只提交与当前任务相关的文件。不要回滚无关的用户变更。只有在提交已验证且用户希望更新远端分支时才 push。
|
||||||
|
|
||||||
### Branch Strategy
|
### 分支策略
|
||||||
|
|
||||||
For single-agent development: work directly on `main` unless the user specifies
|
单代理开发：除非用户指定其他分支，否则直接在 `main` 上工作。
|
||||||
a different branch.
|
|
||||||
|
|
||||||
For multi-agent parallel development: each agent MUST operate on a separate Git
|
多代理并行开发：每个代理必须在从当前 `main` 派生的独立 Git 分支上工作。
|
||||||
branch derived from the current `main`. Branch naming convention:
|
分支命名约定：`agent/<agent-id>/<task-id>`（例如 `agent/codex-1/T08`）。
|
||||||
`agent/<agent-id>/<task-id>` (e.g., `agent/codex-1/T08`).
|
|
||||||
|
|
||||||
Only the primary agent (or the user) may perform merges back to `main`.
|
只有主代理（或用户）可以合并回 `main`。
|
||||||
Before merging, the branch must pass all tests defined in §Testing And Verification.
|
合并前，该分支必须通过 §Testing And Verification 中定义的所有测试。
|
||||||
|
|
||||||
Never have two agents editing the same file on different branches simultaneously.
|
绝不能让两个代理在不同分支上同时编辑同一个文件。
|
||||||
If task dependencies require touching the same file, serialize the work.
|
如果任务依赖要求触碰同一文件，请串行处理。
|
||||||
|
|
||||||
## Safety Rules
|
## 安全规则
|
||||||
|
|
||||||
- Never store secrets in source files, docs, tests, fixtures, or commit messages.
|
- 绝不要把密钥保存在源文件、文档、测试、fixture 或提交消息中。
|
||||||
- Use `.env.example` for variable names only.
|
- `.env.example` 只用于变量名。
|
||||||
- Keep raw external API responses only where the docs require them and avoid including private user data in fixtures.
|
- 仅在文档要求时保留原始外部 API 响应，并避免在 fixture 中包含私有用户数据。
|
||||||
- In test fixtures, replace real usernames, avatar URLs, user IDs, and IP addresses
|
- 在测试 fixture 中，将真实用户名、头像 URL、用户 ID 和 IP 地址替换为占位值
|
||||||
with placeholder values (e.g., "test_user_001", "https://example.com/avatar.png",
|
（例如 "test_user_001"、"https://example.com/avatar.png"、
|
||||||
"user_id_placeholder_001"). Do not copy production API responses directly into
|
"user_id_placeholder_001"）。不要未经脱敏就把生产 API 响应直接复制到 fixture 文件中。
|
||||||
fixture files without sanitization.
|
- 数据库中的 `raw_data` JSON 字段可能包含用户生成内容。
|
||||||
- The `raw_data` JSON field in the database may contain user-generated content.
|
编写断言 `raw_data` 的测试时，只使用合成 fixture 数据。
|
||||||
When writing tests that assert on `raw_data`, use synthetic fixture data only.
|
- 如果对话中暴露了凭据，提醒用户轮换或删除它们。
|
||||||
- If credentials are exposed during the conversation, remind the user to rotate or delete them.
|
- 除非用户明确要求，否则不要使用破坏性 Git 命令。
|
||||||
- Do not use destructive Git commands unless the user explicitly asks for them.
|
|
||||||
|
|
||||||
## Completion Standard
|
## 完成标准
|
||||||
|
|
||||||
A task is complete only when:
|
只有满足以下条件，任务才算完成：
|
||||||
|
|
||||||
1. The requested behavior or document exists.
|
1. 请求的行为或文档已经存在。
|
||||||
2. Relevant tests or checks have been run, or the reason they could not be run is stated.
|
2. 已运行相关测试或检查，或说明了无法运行的原因。
|
||||||
3. The work is scoped to the request.
|
3. 工作范围限定在请求内。
|
||||||
4. The final response explains the result in plain language.
|
4. 最终回复用通俗语言解释结果。
|
||||||
5. Any remaining risks or follow-up tasks are clearly named.
|
5. 清楚列出任何剩余风险或后续任务。
|
||||||
6. If the completed task corresponds to a checkbox in `docs/Tasks.md`, mark it
|
6. 如果完成的任务对应 `docs/Tasks.md` 中的复选框，将其标记为完成
|
||||||
as done (change `- [ ]` to `- [x]`).
|
（把 `- [ ]` 改为 `- [x]`）。
|
||||||
7. The final response MUST explicitly state which tests were run and passed,
|
7. 最终回复必须明确说明哪些测试已运行并通过、哪些边界情况已验证或 mock，
|
||||||
which edge cases were verified or mocked, and any known limitations of the
|
以及当前实现的已知限制。
|
||||||
current implementation.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Changelog
|
## 变更日志
|
||||||
|
|
||||||
| Date | Version | Changes |
|
| 日期 | 版本 | 变更 |
|
||||||
|---|---|---|
|
|---|---|---|
|
||||||
| 2025-07-10 | v1.0 | Initial version |
|
| 2025-07-10 | v1.0 | 初始版本 |
|
||||||
| 2025-07-10 | v1.1 | Post-review revision based on dual review merge (12 instructions): §Two-Day MVP Discipline rewritten as "MVP Discipline (Optimized for Speed)" -- no longer a cutting list, explicitly prohibits deferring P0 features without user confirmation; §Project Constraints gains three architecture constraints (httpx sync-only in background threads, pre-generated reports, single-task executor with 400 rejection); §Source Of Truth gains review-file inclusion, absolute-stop conflict resolution policy, anti-hallucination directive, and RequirementsDoc.md existence guard; §Development Workflow TDD instruction upgraded from "when practical" to mandatory-by-category with explicit TDD.md §2.1 citation; Error Handling Philosophy subsection added; §Testing And Verification gains coverage command and 80% target; §Git Workflow gains branch strategy with mandatory multi-agent branch isolation; §Multi-Agent Rules gains 4 construction-type parallel task examples; §Superpowers Workflow gains environment compatibility note and pre-verification cleanup rule; §Safety Rules gains raw_data sanitization guidance for fixtures; §Completion Standard gains Tasks.md checkbox sync requirement and explicit test-result reporting requirement. |
|
| 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 复选框同步要求和明确测试结果汇报要求。 |
|
||||||
|
|||||||
Reference in New Issue
Block a user