ScienceDiscovery 开发手册

交付标准：明确用户问题，缺陷复现现状、feature 分析现有能力缺口，先设计匹配场景的验证，再以最小完整改动解决问题。PR 声明的范围不得超过实际验证范围。

1. 理解 issue，确认当前版本与需求类型

• 读取 issue 正文、相关讨论、附件与关联 PR；没有访问权限时使用用户提供的内容，明确缺失信息。区分原始诉求、后续补充和实现建议，不能把建议直接当成根因。
• 记录目标仓库、分支、基线 SHA、工作区状态、必要环境和数据。用户指定版本时以指定版本为准；否则记录当前版本，不擅自换成历史版本来证明问题存在。
• 先根据 issue 的实际诉求区分缺陷与 feature（新增能力）；混合 issue 按场景分别处理。feature 不要求复现问题或运行基线失败用例，只需分析当前目标版本的代码为何不支持需求，记录相关入口、调用链、能力缺口及代码位置，作为实现依据。
• 缺陷在改动产品代码前，通过原问题的入口和前置条件执行复现，记录步骤、输入、预期、实际、命令和脱敏证据。UI 问题用浏览器，API/CLI 问题走相应产品入口。
• 缺陷不能复现时区分“目标版本已修复”“条件尚不完整”“环境阻塞”和“尚未找到触发条件”。继续检查调用链、已有测试与版本差异；如需用户信息，只问影响判断的关键问题。不得凭猜测改代码或声称复现成功。可继续独立分析，但未复现必须明确报告，不能宣称已验证修复。
• 阅读仓库的 AGENTS.md、CONTRIBUTING.md 和相关目录约定。保留用户未提交的改动；在任务工作树开发，不把其他任务的代码或运行中的服务当作自己的基线。

2. 写代码前确定验收和验证

先建立一份简短的场景表；小问题可以直接写在工作记录中，复杂任务保存在任务的非提交目录。拆分依据是用户可观察的契约，不是即将修改的函数。

ID	issue 要求与场景/前置条件	基线 SHA 与实际结果/能力缺口	预期结果	验证入口、用例和命令	本 PR 覆盖？	候选 SHA、结果与证据
S1	用户如何触发什么问题	缺陷复现结果或 feature 代码分析结论	可判定的结果	UT/ST/E2E 或其他合适检查	是/否	待验证

• 表中保留 issue 的全部验收范围，包括本 PR 不处理的部分。覆盖全部适用的入口、模式、配置、平台及关键异常/恢复路径；按需求和风险选择代表性组合，不机械穷举无关组合。
• 明确这次交付是完整解决还是部分解决。默认完成用户要求的全部范围，不得为节省工作自行缩小；有必要分期时说明具体边界及原因。
• 为每个本 PR 场景先确定：如何触发、断言什么、在哪里运行、需要什么依赖、如何证明缺陷修复或新增能力满足需求。测试只能证明其实际覆盖的契约。
• 缺陷修复优先添加能在未修改产品代码的基线上因同一缺陷失败的回归用例，再用于候选版本。feature 通过代码分析说明现有实现为何不支持，提前定义验收结果，无需基线复现或红测试；实现后仍须执行匹配需求的验收验证。纯文档等改动使用适合的检查，不强造红测试。
• 单测验证局部规则；跨模块契约用集成测试；用户可观察行为必须验证相应产品旅程。内部函数断言、健康检查、请求已提交或 mocked browser CI 不能替代完整用户结果。
• 测试依赖不可用时先解决可解决的环境问题；其余记为 BLOCKED，不能降低断言、替换真实语义或把未运行写成通过。设计好验证后继续实现，不增加例行等待用户批准的步骤。

3. 分析根因或能力缺口，完成最小完整改动

• 沿用户入口追踪调用链，形成必要的“功能地图”：入口 → 关键模块/状态 → 外部边界 → 用户结果，并标记测试位置。只绘制相关路径，不生成整个仓库的目录百科。
• 缺陷用复现证据检验根因假设，feature 用代码分析确认能力缺口与所需扩展；检查所有相关调用方、类型、配置、错误处理和测试。优先复用现有边界与工具，避免顺手重构和预设通用框架。
• 实现后检查是否只遮盖症状，是否影响错误反馈、兼容性、权限、数据或恢复路径。注释解释必要的原因，保留许可证及有用说明；不套用“禁止所有注释”。
• 新发现的相关场景回填验收表。需求有实质歧义时明确问题，同时推进不依赖回答的工作。

4. 验证修复或新增能力，运行仓库检查

• 缺陷重跑最初复现路径和对应回归测试，比较同一场景的前后结果；确认失败确实由缺陷造成，而非导入失败、错误环境、空断言或零用例。
• feature 按预先定义的验收场景验证新增能力与相关兼容行为；基线记录代码分析结论，不要求补做问题复现。
• 按当前仓库规则运行必要检查。读取 CONTRIBUTING.md、package.json、.ci/README.md；准备 PR 时再读 .agents/skills/create-github-pr/SKILL.md，产品旅程读 .agents/skills/e2e-testing/SKILL.md。专项文件缺失时依据现有文档和脚本完成，不凭空编造命令。
• 当前 CONTRIBUTING 要求 PR 前运行 L1、UT、ST、E2E 四个 hermetic slices（目前为 pnpm ci:l1 / ci:ut / ci:st / ci:e2e，或 test:shared）；执行时核实当前版本入口，不复制过期说明。CI 浏览器子集不代表所有 API/CLI/真实服务场景。
• 正式验证记录实际候选 SHA；修改代码、测试或构建输入后，旧结果不能冒充新版本结果。保持工作树、构建、服务、端口和数据归属一致。
• 记录 planned/executed/passed/failed/blocked/skipped 及证据位置，以实际报告字段为准，未提供的数字不得编造。退出码为零或 CI 绿色不等于所有验收场景执行并通过。
• 失败先归因：候选引入、基线已有、环境阻塞或暂未确定；需要时用独立基线工作树对照。禁止删测试、缩小范围或弱化断言来换取通过。

5. PR 范围与关闭 issue 的硬性条件

准备 PR 时读取 PR 证据模板。核对 issue 全部场景，不只检查改动涉及的场景。

只有全部验收范围均有匹配的测试用例和实际通过证据，且不存在未覆盖、失败、阻塞或跳过的验收项，才允许使用关闭关键字。 全量 CI 通过、覆盖率升高或某个回归用例通过，都不能单独证明 issue 已完整解决。

• 部分解决：写明已解决、未解决、验证结果与后续工作；使用 Refs #123 或 Related to #123，明确 Partial fix; keep #123 open.。不得出现会关闭该 issue 的 Fixes、Closes、Resolves 等关键字关联，包括标题、正文和将被合并的提交信息。
• 完整解决：在 PR 中逐项提供全部场景的用例和结果，之后才使用 Closes #123。同一 PR 关联多个 issue 时逐个判定。
• 某些范围由先前 PR 解决时，也要在当前候选版本验证其仍然成立，不能仅引用旧 PR 已合并。不能为了关闭 issue 擅自重写或缩小原验收范围。
• 证据有缺口时保留 issue 打开，准确报告缺口；“已写测试但未执行”仍未验证。不得把待 CI、缺凭据或仅模拟测试写成真实场景通过。
• 创建或更新 PR 后核对实际标题、正文、提交信息和关闭关联，防止模板残留自动关闭。只有用户授权提交时才进行外部写操作；使用 GitHub fork 流程、英文标题正文及当前 release 标签约定，不向 GitCode 镜像写入。

Issue 认领与可修判定（硬性）

• 用户点名某个 issue 时，先读正文与全部评论，再决定是否动手；不得未经判断直接认领或改代码。
• 扫描与认领优先级（由高到低）：
  1. agent-ready（或等价“可交给 agent 修”）且无人认领；
  2. 明确、范围小、在 Linux/box 上可验证的 简单 bug；
  3. 其他可修 bug。feature / need-human / needs info 且缺关键信息时默认不认领。
• 直接 pass（不 assign、不改代码）：
  • 已有任何人认领（assignees 非空，含非 HongyeZhou）；
  • 问题仅出现在 Windows / macOS（或正文/评论表明仅 Win/Mac 可复现，Linux/box 无法有效验证）；
  • 评论或标签表明“现在还不能修 / 先别动 / blocked / waiting / need-human / 依赖未就绪”等。
• 认领：判定可修后，将 issue assign 给 HongyeZhou，再进入复现与改动；未判定可修前不要 assign。
• 向用户说明：推荐或认领时，用大白话一两句说明该 issue 的具体需求/问题（用户要什么、现在坏在哪），不要只甩标题。
• 扫描候选时默认过滤：open、无人认领、非 Win/Mac-only；优先 agent-ready，其次简单 bug。

MiniMax / Claude Code 额度

• 本仓库开发任务优先下发给本机 Claude Code，并走 MiniMax（见 ~/.claude/settings.json），以节省上层助手额度。
• MiniMax 日额度可能触顶；每天 15:00 与 20:00（Asia/Shanghai）会重置。触顶时暂停继续烧额度的长跑，向用户报告并建议等到最近一次重置后再继续；不要假装任务已完成。
• 配额相关失败（限流、余额不足、鉴权报错）记为 BLOCKED，保留现场，重置后再从断点续跑。

提交与作者身份（硬性）

• 所有本地提交与将推送/出现在 PR 中的提交，author 与 committer 都必须是 HongyeZhou，不得使用 Claude、bot、其他协作者或默认本机身份。
• 提交前设置并核对：git config user.name "HongyeZhou"、git config user.email "HongyeZhou@users.noreply.github.com"（仓库级即可）；提交后用 git log -1 --format='%an <%ae> / %cn <%ce>' 确认两边都是 HongyeZhou。
• 禁止在提交信息、Co-authored-by、Signed-off-by、PR 正文或代码注释里标注 Claude、AI、bot 或其他作者。需要改写历史时，用 --author='HongyeZhou <HongyeZhou@users.noreply.github.com>' 且确保 committer 同为 HongyeZhou，再核对后再推送。
• 发现作者不是 HongyeZhou 时，先修正再继续；不得带着错误作者身份开 PR。

最终向用户报告：解决了什么、基线与候选版本、验证覆盖和结果、剩余缺口，以及“完整解决，可关闭”或“部分解决，保持打开”。只声明本次证据支持的结论。

手册维护

本 skill 是工作流程；仓库文档与专项 skills 是当前架构和命令的来源；场景表是本次任务的功能与验证地图。不要复制整份仓库手册或为每次任务新增永久规则。只有实际反复出现且值得复用的经验才更新手册。参考来源与取舍见 调研记录，仅在评估或调整流程时阅读。