zmice 基于官方文档的开发
概述
当实现依赖外部框架、库或平台的当前 API、版本差异、弃用状态、兼容性或安全约束时，先核对对应版本的第一方资料。项目内已固定的契约、封装、类型、源码、测试和运行证据能证明局部行为时，不为形式重复联网或逐行引用；外部资料用于补足会随版本漂移的事实，不覆盖项目自己的约定。
何时使用
- 用户明确要求当前、官方、引用或跨版本结论
- 构建模板、脚手架或将被跨项目复制的模式
- 使用不熟悉、变化快或版本敏感的 API
- 判断迁移、弃用、兼容性、认证或安全约束
- 审查会改变公共框架边界的模式
不需要使用的场景：
- 正确性不依赖特定版本的操作（重命名变量、修复拼写、移动文件）
- 在所有版本中行为一致的纯逻辑（循环、条件、数据结构）
- 沿用仓库已有 wrapper / pattern，且类型、测试或运行路径足以证明局部行为
- 项目私有配置、约定和不改变外部 API 边界的局部修复
没有网络时不得假装已核对上游。可以使用锁定版本、依赖源码、类型声明、现有测试和实际构建证明局部正确性，并把“上游当前推荐方式”明确标为未核对。
流程
检测 ──→ 拉取 ──→ 实现 ──→ 引用
│ │ │ │
▼ ▼ ▼ ▼
识别 获取 按照 标注
技术栈 相关文档 文档模式 来源
步骤 1：检测技术栈和版本
读取项目的依赖文件，识别精确版本：
package.json → Node/React/Vue/Angular/Svelte
composer.json → PHP/Symfony/Laravel
requirements.txt / pyproject.toml → Python/Django/Flask
go.mod → Go
Cargo.toml → Rust
Gemfile → Ruby/Rails
明确陈述发现：
技术栈检测结果：
- React 19.1.0（来自 package.json）
- Vite 6.2.0
- Tailwind CSS 4.0.3
→ 正在拉取相关模式的官方文档。
版本缺失或模糊时，先检查 lockfile、resolved dependency、类型声明、运行时版本和 CI。只有版本选择会实质改变实现且本地无法确定时才询问用户。
步骤 2：拉取官方文档
拉取你正在实现的功能对应的具体文档页面。不是首页，不是全部文档——是相关页面。
来源优先级（按权威性排序）：
| 优先级 | 来源 | 示例 |
|---|---|---|
| 1 | 官方文档 | react.dev, docs.djangoproject.com, symfony.com/doc |
| 2 | 官方博客/更新日志 | react.dev/blog, nextjs.org/blog |
| 3 | Web 标准参考 | MDN, web.dev, html.spec.whatwg.org |
| 4 | 浏览器/运行时兼容性 | caniuse.com, node.green |
不具权威性——不可作为主要来源引用：
- Stack Overflow 回答
- 博客文章或教程（即使是热门的）
- AI 生成的文档或摘要
- 你自己的训练数据（这正是需要验证的——不要自引自证）
精确拉取：
错误：拉取 React 首页
正确：拉取 react.dev/reference/react/useActionState
错误：搜索"django authentication best practices"
正确：拉取 docs.djangoproject.com/en/6.0/topics/auth/
拉取后，提取关键模式并记录任何弃用警告或迁移指引。
当官方来源之间相互矛盾时（如迁移指南与 API 参考不一致），向用户说明差异并针对检测到的版本验证哪个模式实际有效。
步骤 3：按文档模式实现
编写与文档一致的代码：
- 使用文档中的 API 签名，而非凭记忆
- 如果文档展示了新的做法，使用新做法
- 如果文档弃用了某个模式，不要使用弃用版本
- 如果文档没有覆盖某些内容，标记为未验证
**当文档与现有项目代码冲突时：**项目 wrapper、兼容层、ADR、测试和团队约定优先于通用示例。只有迁移到新模式会改变公共 API、兼容范围或任务范围时才列出选项请求决定；否则保持本地一致，并在 handoff 说明差异。
步骤 4：标注来源
引用非显而易见且会随版本漂移的关键决策。优先集中放在 handoff、设计说明或 ADR；代码注释只保留维护者需要理解的版本陷阱或兼容原因。
需要解释版本陷阱时才在代码注释中引用：
// React 19 表单处理 useActionState
// 来源：https://react.dev/reference/react/useActionState#usage
const [state, formAction, isPending] = useActionState(submitOrder, initialState);
在对话中：
我使用 useActionState 而非手动 useState 管理表单提交状态。
React 19 用此 hook 替代了手动的 isPending/setIsPending 模式。
来源：https://react.dev/blog/2024/12/05/react-19#actions
"useTransition 现在支持异步函数 [...] 自动处理 pending 状态"
引用规则：
- 完整 URL，不使用缩短链接
- 尽可能使用带锚点的深链接（如
/useActionState#usage优于/useActionState） - 当支撑非显而易见且版本敏感的决策时，引用相关段落
- 推荐平台特性时，附上浏览器/运行时兼容性数据
- 如果找不到某个模式的文档，明确说明：
未验证：未找到此模式的官方文档。
此实现基于训练数据，可能已过时。
请在用于生产前自行验证。
诚实说明未能验证的内容，比虚假自信更有价值。
常见借口
| 借口 | 现实 |
|---|---|
| "我对这个 API 很有信心" | 信心不是证据。训练数据里充满了看起来正确但在当前版本会出错的过时模式。验证它。 |
| "拉取文档浪费 token" | 编造 API 浪费更多。用户花一小时调试，才发现函数签名变了。一次拉取能省数小时返工。 |
| "文档里不会有我需要的" | 如果文档没覆盖，这本身就是有价值的信息——该模式可能不是官方推荐的。 |
| "我会注明可能已过时" | 免责声明没用。要么验证并引用，要么明确标记为未验证。模棱两可是最差选项。 |
| "仓库里已有 wrapper，所以永远不用查" | 局部修复可沿用已验证封装；迁移、兼容性、安全或公共模板仍需核对当前第一方资料。 |
危险信号
- 处理版本敏感 API 前既没有查第一方资料，也没有本地锁定版本证据
- 对 API 使用"我认为""应该是"而非引用来源
- 实现模式时不知道它适用于哪个版本
- 引用 Stack Overflow 或博客而非官方文档
- 因为出现在训练数据中而使用弃用的 API
- 实现前没有读
package.json/ 依赖文件 - 交付时没有说明关键版本敏感决策的来源或本地证据
- 需要一个页面却拉取了整个文档站
检查清单
实现完成后自查：
- 已从依赖文件中识别框架和库的版本
- 已为版本敏感、兼容性或安全决策核对第一方资料
- 所有来源都是官方文档，不是博客或训练数据
- 代码遵循当前版本文档中展示的模式
- 非显而易见且会漂移的决策在 handoff / ADR 中包含可验证来源
- 未使用弃用 API（已对照迁移指南检查）
- 文档与现有代码的冲突已向用户说明
- 无法验证的内容已明确标记为未验证