用途 Guided Review 用于把一次代码变更集整理成有阅读顺序的分章导读。读者看到的不是扁平的文件列表，而是若干章节：每章说明一组文件共同做什么、为什么这样改，然后就地展示这些文件的 diff。最终产出一个独立 HTML 文件，任何人用浏览器即可打开，可从本地磁盘打开也可通过链接访问。
分工上，撰写者负责思考：读 diff、理解改动、写出导读；CLI 负责校验导读、补充来源信息并写出 HTML。
主要能力
- 按重要性而非文件路径或 diff 大小组织章节顺序，把实现核心放在最前，随后是后果与测试，最后归并接线、配置等低信号改动。
- 章节按逻辑单元切分，一个原因改动的多个文件可归为一章；同一文件的两处无关改动可拆成两章。
- 每章包含标题、概述（2-6 句，说明改了什么、为何存在、关键影响）与该章涉及的 diff 引用。
- 每个文件引用包含精确的仓库相对路径和 1-2 句语义摘要。
- 硬性覆盖规则：每个改动文件必须且只能出现一次（某个章节或 unplacedFiles 中），不得遗漏、重复或拼写错误。
- 输出 guide.json，再由 CLI 校验并导出 HTML 或分享链接。
使用方式
- 保存 diff。按需选择命令，例如分支对比、未提交改动或单个提交： git diff origin/main...HEAD > guide.patch git diff HEAD > guide.patch git show --format= <sha> > guide.patch 对 PR 可先 gh pr checkout <n> 再与其基线分支对比。从未 git add 的新文件不会出现在 git diff 中，可先运行 git add -N <files>。
- 编写 guide.json，包含 title、intent、sections（每节含 title、overview、diffs）与 unplacedFiles，还可包含 review（gitRef、可选 base）、generator（engine、可选 model）等字段。
- 导出： plannotator guide export --guide guide.json --patch guide.patch 若未安装 plannotator： curl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimal 成功时打印 HTML 文件路径；失败时以退出码 1 结束并说明问题（如文件不在 patch 中、文件被放置两次、缺少字段），修正 guide.json 后重跑，不要为迁就导读去改 patch。可用 --out <file.html> 指定输出位置。 如需链接而非文件： plannotator guide share --guide guide.json --patch guide.patch 该方式同样执行校验，但会把导读上传到 guides.show 并打印 URL。上传默认端到端加密，托管方看不到代码，密钥是链接中 # 之后的部分，持有完整链接者可阅读；同时会打印删除令牌，可用 plannotator guide unshare <id> --token <token> 移除链接。仅当需要链接预览时加 --public，此时导读以未加密方式存储。只有用户要求链接时才分享，默认产出文件。
适用场景 适合让评审者一次坐读完较大改动，快速把握实现核心、动机与影响，尤其是跨多文件、按路径顺序阅读难以理解的变更集。也适合为 PR 生成可分章的导读材料。
限制
- 导读面向解释与定位，不是找 bug 或写发现报告；若阅读中偶见疑似真实缺陷，可在相关章节概述中简要提及，但不以审查为主。
- 通常 2-6 个章节，绝不超过 10 个；改动很小就用一章，不要凑数。
- 输出中不得使用长破折号或代替它的双连字符，不得使用 emoji。
- diff 文件路径必须与 diff 中完全一致，不得臆造、缩写或改大小写。
- 主要来源是保存的 guide.patch；只做少量有针对性的查证，不广泛探索仓库或读取未改动文件。
- 文章未提供收费、价格、平台支持范围与效果数据，这些暂未提供。