@openprd/cli 0.1.11 → 0.1.18

package/skills/openprd-shared/SKILL.md

@@ -20,6 +20,9 @@ description: OpenPrd 工作区与产物的共用守则。凡是需要查看、
 - 涉及第三方 API、模型、云服务、付费工具或外部供应商时，优先比较多家可行方案，用表格列出效果、价格、接入成本、限制、风险和推荐理由，并给出性价比最好的默认选择。
 - 当用户的问题包含多个对象、方案、文件、场景、风险、验证项、素材或任务，并且需要同时呈现状态、证据、影响、动作或推荐时，Agent 应主动使用 Markdown 表格，不等用户要求。先用一句话给结论，再给表格。
 - 表格优先用于方案对比、状态盘点、问题排查、风险审查、多对象 QA、文件/命令清单、需求场景覆盖和内容/素材规划；单一结论、单一动作、代码示例、命令示例和叙事型说明不要强行表格化。
+- 当用户需要理解复杂关系、状态跳转、因果链、边界分工、路径差异、风险传播或方案取舍时，优先用“结论 + 解释型 SVG 图 + 少量补充”的图解优先表达；能被一张图讲清的内容，不要先输出长段落文字。
+- 解释型 SVG 是对话辅助，不是正式评审或验收产物；它用于让用户快速看懂，不替代 `review.html`、`openprd diagram`、`visual-compare`、测试证据、调研证据或实现截图。
+- 图解优先不等于所有问题都画图：单一事实、短命令输出、简单 yes/no、精确错误文本、合规/安全必须逐字说明的内容，仍用简短文字或表格。
 - 如果用户明确说质量优先、稳定性优先或体验优先，就降低价格权重，优先保证效果、可靠性和长期可维护性。
 
 ## 共用运行规则
@@ -30,10 +33,11 @@ description: OpenPrd 工作区与产物的共用守则。凡是需要查看、
    - 只读命令：`status`、`validate`、`next`、`history`、`diff`、`interview`、`doctor`
    - 写入命令：`init`、`setup`、`update`、`classify`、`synthesize`、`diagram`、`release`、`freeze`、`handoff`
    - 执行命令：`loop --run`、`tasks --advance`、`discovery --advance`、`loop --finish --commit`、git commit、git push，必须有当前用户明确执行意图。
+   - 实现授权不包含云端热修复、生产远端写入、业务兜底、写死逻辑、客户端/服务端补业务数据或缓存补行；这些动作需要当前用户单独明确批准，并给出本地源码/配置/迁移同步与回滚计划。
 3. 不要虚构 OpenPrd 命令或产物类型。
    - 不确定时先对照 `openprd --help`。
 4. 共用规则放在这里，领域规则放到对应 skill。
-5. 默认用简体中文生成用户可见文档、报告，以及 Agent 产出的 spec 和 tasks；必要专有名词、品牌名、命令名、路径、字段名和 API 术语可以保留原文。
+5. 用户可见文档、报告，以及 Agent 产出的 spec 和 tasks 跟随用户当前主语言；无法判断时用简体中文兜底。必要专有名词、品牌名、命令名、路径、字段名和 API 术语可以保留原文。
    - OpenPrd 自身及随包 workspace / template / skill README 默认把简体中文放在 `README.md`，英文放在 `README_EN.md`；如需兼容旧链接，可保留 `README_CN.md` 作为跳转入口。
    - 如果 README、概览图或发布说明存在双语版本，带文字的图片资产也要与 `README.md` / `README_EN.md` 成对维护并同步更新，避免一边改了文案、另一边还停留在旧说法。
    - 入口路由优先看 `skills/openprd-router/SKILL.md`
@@ -61,36 +65,41 @@ description: OpenPrd 工作区与产物的共用守则。凡是需要查看、
    - 用户给出会话 ID 并要求继续时，按工具无关的历史会话精确续接；不要要求工具专属 ID，也不要用当前 active change、相似历史或 requirement gate 替代指定会话。
    - 用户没有给 ID、但明确描述了某个已有需求、change、task 或 work unit 时，先按描述解析对应对象；只有解析不出来时，才把当前工作区状态当作背景继续看。
    - 使用 `.openprd/harness/install-manifest.json`、`hook-state.json`、`events.jsonl` 和 `drift-report.json` 判断生成引导是否健康。
+   - 使用 `.openprd/harness/runtime-environment.json` 判断最近 hook/session 观察到的当前对话环境；协议和能力清单看 `.openprd/harness/install-manifest.json` 的 `runtimeDetection` / `platformCapabilityPacks`。
+   - 判断当前用户正在和 Codex、Claude Code 还是 Cursor 对话时，按 hook/session payload > 显式 launcher > SDK/headless session > 子进程 env > config/CLI probe > agent 自述的优先级处理。Codex 原生 Image 2、Computer Use、Codex-owned browser window、对话协同画布和当前线程文本桥接属于 surface-dependent 能力，只有当前工具面或 hook/session 证据明确支持时才使用；当前线程桥接只在 Codex App 明确提供线程发送工具时使用，画布图片仍以导出路径或 Markdown 图片引用作为证据；不要仅凭 Codex CLI、`.codex/config.toml` 或 `CODEX_HOME` 推断可用。
    - 前端体验任务进入实现前，优先读取 `skills/openprd-frontend-design/SKILL.md` 与 `.openprd/design/`，先锁定 lens、theme、layout 和组件，再决定是否实现。
-   - 使用 `.openprd/harness/visual-reviews/` 承接用户已经确认纳入后续对比的 reference-set、选中方向、实现后视觉对比证据、局部焦点证据板和并行实验证据板；候选效果图默认不要直接登记进去。
+   - 使用 `.openprd/harness/visual-reviews/` 承接用户已经确认纳入后续对比的 reference-set、选中方向、实现后视觉对比证据、局部焦点证据板、并行实验证据板、截图实测证据板和对齐辅助线证据板；候选效果图默认不要直接登记进去。
    - 使用 `.openprd/quality/config.json`、`.openprd/quality/reports/` 和 `.openprd/knowledge/` 判断实现就绪、当前场景必需 EVO 证据和可复用经验。
    - 使用 `.openprd/growth/` 承接收工阶段的自我成长复盘；工具识别补全和减少重复打扰这类高置信低风险项可自动补齐，用户偏好、项目协作规矩和 OpenPrd 默认行为留到收工时集中确认。
-10. 生成图片内容时默认使用 `imagegen`，也就是 Codex 原生 Image 2。
+10. 生成图片内容时默认使用 `imagegen`，也就是 Codex 原生 Image 2；Image 2 是工具路径，不是审美豁免。
    - 当用户要求生成图片、封面图、配图、海报、插画、图标、贴纸、头像、banner、主视觉/KV、运营图、效果图、视觉稿、mockup、先看样子或先确认设计方向时，默认直接调用 `imagegen` 产出图片。
+   - 生成前先写清用途、受众、气质、约束和记忆点，并把这些写进 prompt；没有品牌或参考图依据时，用 `.openprd/design/anti-slop.md` 排除默认紫白/蓝紫渐变、通用字体、白底卡片堆叠和无语境装饰。
    - 对 logo、icon、avatar、badge 等开发素材，如果用户没有明确要求 mockup、场景图、设备框、卡片承载、名片/包装展示或参考界面复刻，默认按 `独立素材输出（standalone asset）` 处理：使用全画布单主体，不额外添加 UI frame、卡片、设备壳、名片、桌面陈列、手持实拍或其他展示容器。
    - 只有当用户明确要求 mockup、场景化效果图、容器化呈现，或参考图本身就包含这些承载结构时，才生成对应的容器或场景。
    - 除非用户明确指定 HTML、SVG、CSS、Canvas、代码稿或可编辑矢量/source artifact，不要改用临时 HTML/SVG/CSS 再截图。
    - 只有实际发生 `imagegen` 调用后，才能汇报生图结果、失败或限流；未调用 `imagegen` 前，不要声称“生图限流”或“生图失败”。
-   - 生图结果先当候选效果图，不要默认登记到 `.openprd/harness/visual-reviews/`。如果用户还要继续做实现，主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现；只有确认后才把选定方向、整张图或其中子图整理成 reference-set。
-   - OpenPrd 的 `review.html` 只用于需求评审，不能替代图片或效果图生成；`visual-compare` 只用于实现阶段视觉证据：已有确认参考图时做“效果图 / 实现截图”对比；没有参考图时先判断新建界面还是修改既有界面，新建界面回到实现前 3 方向方案评审，修改既有界面做“修改前 / 修改后”自检；当局部细节更重要时，优先改用 `--board` 生成“局部焦点证据板”；当并行跑了多个优化方向时，优先改用 `--board` 生成“并行实验证据板”。
+   - 生图结果先当候选效果图，不要默认登记到 `.openprd/harness/visual-reviews/`。看图时不仅判断是否生成成功，还要判断气质、层级、字体/色彩/表面角色和记忆点是否成立。如果用户还要继续做实现，主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现；只有确认后才把选定方向、整张图或其中子图整理成 reference-set。
+   - OpenPrd 的 `review.html` 只用于需求评审，不能替代图片或效果图生成；`visual-compare` 只用于实现阶段视觉证据：已有确认参考图时做“效果图 / 实现截图”对比；没有参考图时先判断新建界面还是修改既有界面，新建界面回到实现前 3 方向方案评审，修改既有界面做“修改前 / 修改后”自检；当局部细节更重要时，优先改用 `--board` 生成“局部焦点证据板”；当并行跑了多个优化方向时，优先改用 `--board` 生成“并行实验证据板”；普通截图、Computer/Browser/Playwright 实测截图要作为视觉证据时，优先改用 `--board` 生成“截图实测证据板”；新功能或改动包含同构列表、卡片、网格或表格，或用户反馈没有对齐/排版漂移时，优先改用 `--board` 生成“对齐辅助线证据板”，叠辅助线并量相同槽位的 x/y/宽高 spread。visual evidence 同时检查气质、层级、字体/色彩/动效/表面角色和记忆点，不只检查截图是否存在。
 11. 界面视觉实现有参考图时，必须留下左右对比图。
    - 只要任务涉及界面、页面、视觉、样式或前端体验，并且已经有效果图、设计稿、截图或用户给图且进入实现阶段，阶段性完成后先截取实现截图。
-   - 运行 `openprd visual-compare . --reference <效果图> --actual <实现截图>`，默认输出 JPG 到 `.openprd/harness/visual-reviews/`。
+   - 运行 `openprd visual-compare . --reference <效果图> --actual <实现截图> --locale <zh-CN|en>`，默认输出 JPG 到 `.openprd/harness/visual-reviews/`。
    - 如果一张参考图里有多个子图、网格或对象，先运行 `openprd visual-prepare . --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>`，检查 contact sheet 后再逐项对比。
-   - 合成图左侧必须标注“效果图”，右侧必须标注“实现截图”；查看合成图后继续对标，直到没有明显视觉差异。若用户后续说“跟效果图”“不一致”“好丑”“复刻”，至少先产出一份视觉证据图，不要只口头说已经对比过了。
-   - 如果整体图之外还要审局部细节，再补一份 `openprd visual-compare . --board <focus-board.json>`，把整体标框和局部放大放在同一张证据板里。
+   - 合成图左侧必须标注“效果图”，右侧必须标注“实现截图”；查看合成图后继续对标，直到结构、气质、层级、字体/色彩/表面角色和记忆点都没有明显差异。若用户后续说“跟效果图”“不一致”“好丑”“复刻”，至少先产出一份视觉证据图，不要只口头说已经对比过了。
+   - 如果整体图之外还要审局部细节，再补一份 `openprd visual-compare . --board <focus-board.json> --locale <zh-CN|en>`，把整体标框和局部放大放在同一张证据板里。
+   - 如果新开发或修改了同构列表、卡片、网格或表格，或用户反馈没对齐/排版漂移，再补一份 `openprd visual-compare . --board <alignment-board.json> --locale <zh-CN|en>`，把真实截图、对齐辅助线、标题/标签/描述/状态/操作区等相同槽位的 x/y/宽高 spread 放在同一张证据板里。
    - 未生成并查看对比图，或对比图仍有明显差异时，不要声称界面复刻或视觉实现完成。
 12. 界面视觉实现无参考图时，先区分新建界面和修改既有界面。
    - 只要任务涉及界面、页面、视觉、样式或前端体验，但没有明确效果图、设计稿、截图或用户给图，先判断这是新建界面还是修改既有界面。
    - 新建首屏、首页、控制台或核心页面时，回到实现前 3 方向方案评审；修改既有界面时，动手前先用 Computer Use、Browser、Playwright 或项目现有工具截取修改前截图。
-   - 修改既有界面完成后，用同一入口、视口、账号和数据状态截取修改后截图，再运行 `openprd visual-compare . --before <修改前截图> --after <修改后截图>`。
-   - 合成图左侧必须标注“修改前”，右侧必须标注“修改后”；查看合成图后确认预期变化出现，并检查未改区域没有明显布局、颜色、密度或状态漂移。
-   - 如果并行试了多条优化方向，再补一份 `openprd visual-compare . --board <parallel-board.json>`，把多方案截图、GIF 首帧和指标放到同一板里对比。
+   - 修改既有界面完成后，用同一入口、视口、账号和数据状态截取修改后截图，再运行 `openprd visual-compare . --before <修改前截图> --after <修改后截图> --locale <zh-CN|en>`。
+   - 合成图左侧必须标注“修改前”，右侧必须标注“修改后”；查看合成图后确认预期变化出现，并检查本轮审美意图、记忆点和未改区域没有明显布局、颜色、密度或状态漂移。
+   - 如果并行试了多条优化方向，再补一份 `openprd visual-compare . --board <parallel-board.json> --locale <zh-CN|en>`，把多方案截图、GIF 首帧和指标放到同一板里对比。
+   - 如果只是普通截图或 Computer/Browser/Playwright 实测截图作为视觉或运行态证据，再补一份 `openprd visual-compare . --board <verification-board.json> --locale <zh-CN|en>`，把检查路径、截图和 checkpoint 放到同一板里。
    - 这类自检不能替代大界面方向性改造的实现前方案评审。
 13. 大界面改动实现前必须先完成视觉方案评审。
    - 触发条件：会明显改变页面信息架构、主视觉、核心布局、关键路径、组件层级/密度，或用户需要先选择设计方向。
    - 位置：需求分流之后、PRD 定稿或实现开工之前；它不是 `review.html`，也不是实现后的 `visual-compare`。
-   - 步骤：已有界面时用 Codex Computer Use 进入产品内对应功能并截当前真实界面；冷启动没有现有界面时，基于已确认 PRD、用户群体、第一版切片和视觉目标生成设计 brief；用 `imagegen`（Codex 原生 Image 2）基于截图或设计 brief 至少生成 3 个不同设计思想方向；把效果图横向拼成一张大图，每张左上角标注 1/2/3，先作为候选效果图展示。
+   - 步骤：已有界面时用 Codex Computer Use 进入产品内对应功能并截当前真实界面；冷启动没有现有界面时，基于已确认 PRD、用户群体、第一版切片、视觉目标、气质端点和记忆点生成设计 brief；用 `imagegen`（Codex 原生 Image 2）基于截图或设计 brief 至少生成 3 个不同设计思想方向；每个方向都要有具体审美主张和 anti-slop 自检；把效果图横向拼成一张大图，每张左上角标注 1/2/3，先作为候选效果图展示。
    - 交互：主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现；只有确认后才把选定方向、整张图或其中子图整理到 `.openprd/harness/visual-reviews/`。用户确认前，不进入大 UI 实现，也不要声称界面方案已定。
 14. 界面任务进入实现前，先用 `.openprd/design/` 锁定设计框架。
    - 页面涉及具体产品事实、版本、发布时间、规格、价格、引用数据或地点事实时，先补 `.openprd/design/active/facts-sheet.md`，不要凭记忆写页面。
@@ -101,13 +110,14 @@ description: OpenPrd 工作区与产物的共用守则。凡是需要查看、
 15. 把文档与结构回顾视为实现的一部分，而不是开工前的噪声。
    - 代码修改完成后、最终回复前，针对本轮实际新增或修改的 code files 运行 `openprd dev-check . <file...>` 或 `node scripts/openprd-dev-check.mjs . <file...>`。
    - dev-check 默认是收工回顾，不是开工许可证；只有用户明确询问影响文件、拆分边界，或你已经判断需要先设计拆分范围时，才在开发前额外运行。
-   - 行数状态按研发期标准解读：700 行以内正常；701-1500 行需留意；超过 1500 行说明后续改动成本较高。若出现需要关注的文件，最终回复必须以 **后续建议** 为标题，用 Markdown 表格列出影响位置、关注程度、规模信号、为什么需要关注、本次处理和后续建议，并按 🔴 → 🟠 → 🟡 排序；若只是窄 bugfix 或小修且暂不拆，要在表格里说明本次处理边界并留下后续拆分建议。
+   - 行数状态按研发期标准解读：700 行以内正常；701-1500 行需留意；超过 1500 行说明后续改动成本较高。自动优化开启（默认）时，命中需要关注的文件先在本轮直接完成高内聚低耦合拆分（不丢功能、行为不变），最终回复以 **OpenPRD 自动优化报告** 为标题复用 dev-check 表格（列：影响对象、问题级别、源文件规模、优化原因、本次处理结果、后续建议）并附开关确认；关闭后以 **后续建议** 为标题输出推荐表格（列：影响对象、关注程度、规模信号、预警原因、本次处理结果、后续建议）。两种模式都按 🔴 → 🟠 → 🟡 排序；若只是窄 bugfix 或小修且暂不拆，要在表格里说明本次处理边界并留下后续拆分建议。
    - 如果 dev-check 或执行过程发现可沉淀项，不要中途打断当前任务。高置信工具识别补全可自动固化并简短说明；用户偏好、项目协作规矩或 OpenPrd 默认行为先记录为候选，收工时运行 `openprd grow . --review` 集中确认。
    - 维护 OpenPrd 本身时，只要新增或修改配置类能力（阈值、规则、识别、豁免、命令别名、环境差异、用户偏好或策略开关），都要做 grow-aware 自检：高置信应可成长时默认纳入 `openprd grow`；不确定时主动问用户；明确一次性或固定规则时才保持静态配置。
    - 新增或修改文件时，检查 `docs/basic/`、文件说明书和文件夹 README 是否缺失或已过期。
    - 当职责、流程、结构、依赖或产品行为变化时，补齐缺失文档并更新已有文档。
    - 涉及后端、脚本、Agent、工具链、服务或数据处理变更时，把 CLI 与 API 视为同级接入面；检查命令入口、参数、输出契约、`help`/`doctor`/`dry-run`/`status` 与接口协议、返回结构、身份边界是否受影响，并同步更新 `docs/basic/backend-structure.md`；若某一面不适用也要明确写原因。
    - `.openprd/harness/install-manifest.json` 的 `optionalCapabilities` 用来记录非阻断式增强建议，例如 Context7、DeepWiki。当前任务明显受益但状态仍是 `recommended` 时，在后续建议里解释它能帮什么、附官方文档和 GitHub 链接，并可顺手提出“如果你愿意，我可以按当前客户端帮你补配置”；不要因为它未配置就阻断当前任务。
+   - `.openprd/harness/install-manifest.json` 的 `runtimeDetection` 和 `platformCapabilityPacks` 用来拆开不同 agent 平台的专属能力；Agent 应先识别当前对话客户端，再启用对应能力包，不要把 Codex、Claude Code、Cursor 的工具路径混在一套固定规则里。
 16. hook 重量要和任务风险匹配。
    - 默认 Codex hook profile 是 `lite`：`UserPromptSubmit` 注入上下文，轻量 `PreToolUse` 写入门禁阻断过早实现，`Stop` 在本轮结束前回顾是否值得沉淀项目经验。明确的 OpenPrd / 深度工作提示词，以及新的产品、模块、流程需求都会注入上下文。
    - 只有项目明确需要完整 hook 遥测或临时深度诊断时才使用 `full`。
@@ -159,11 +169,11 @@ description: OpenPrd 工作区与产物的共用守则。凡是需要查看、
 - 只有当当前用户消息明确要求开发、实现、修复、继续任务、深度调研、对标复刻或提交时，才执行 OpenPrd loop、task 或 discovery 推进。
 - 单纯的“请帮我实现/继续实现”只表示有执行意图，不表示可以跳过 requirement 摘要确认、`capture/classify/synthesize` 写入路径或 review；只有用户明确表示“不需要进行任何确认”时，才允许静默走完整 requirement write path。
 - 声称实现就绪前，要说明文档影响检查是新增、更新，还是有意保持 `docs/basic/`、文件说明书和文件夹 README 不变。
-- 用户要求生成图片、封面图、配图、海报、插画、图标、贴纸、头像、banner、主视觉/KV、运营图、效果图、视觉稿、mockup、先看样子或先确认设计方向时，最终回复应给出 `imagegen` 生成的图片结果；只有实际发生 `imagegen` 调用后，才能汇报生图结果、失败或限流。生图结果先当候选效果图，并主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现。进入实现阶段后，已有确认参考图才给出 `openprd visual-compare --reference/--actual` 生成的 JPG 路径；如果参考图是一张整板、网格图或多对象组合，先运行 `openprd visual-prepare --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>` 并说明 contact sheet / compare-plan；没有参考图时先判断新建界面还是修改既有界面，新建界面先完成 3 方向方案评审，修改既有界面给出 `openprd visual-compare --before/--after` 生成的 JPG 路径，并说明是否仍有差异或漂移。
+- 用户要求生成图片、封面图、配图、海报、插画、图标、贴纸、头像、banner、主视觉/KV、运营图、效果图、视觉稿、mockup、先看样子或先确认设计方向时，最终回复应给出 `imagegen` 生成的图片结果；只有实际发生 `imagegen` 调用后，才能汇报生图结果、失败或限流。Image 2 是工具路径，不是审美豁免；最终回复要能说明候选图是否满足用途、受众、气质和记忆点。生图结果先当候选效果图，并主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现。进入实现阶段后，已有确认参考图才给出 `openprd visual-compare --reference/--actual` 生成的 JPG 路径；如果参考图是一张整板、网格图或多对象组合，先运行 `openprd visual-prepare --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>` 并说明 contact sheet / compare-plan；没有参考图时先判断新建界面还是修改既有界面，新建界面先完成 3 方向方案评审，修改既有界面给出 `openprd visual-compare --before/--after` 生成的 JPG 路径；普通截图实测补 `openprd visual-compare --board <verification-board.json>`，同构列表、卡片、网格、表格或用户反馈没对齐时补 `openprd visual-compare --board <alignment-board.json>`，并说明相同槽位 spread 是否仍有偏差；最终同时说明是否仍有结构、气质、层级、颜色、字号、间距或记忆点差异。
 - 大界面改动进入实现前，最终回复或阶段性回复应给出 3 方向横向候选效果图大图，并明确等待用户确认是否纳入后续对比和继续实现；只有确认后再进入实现。
 - 在系统形态、产品流程或外部依赖仍有实质不确定性时，需求定稿前先向用户确认。
 - 当用户还没看过最新的 synthesize 产物或图示产物时，handoff 前先确认。
-- 当用户要求可视化说明时，路由到 `$openprd-diagram-review`。
+- 当用户要求可视化说明，或当前解释明显包含复杂关系、路径、对比、边界或风险传播时，路由到 `$openprd-diagram-review`；优先判断是否适合轻量解释型 SVG，而不是默认进入正式评审图。
 
 ## 共用路由规则
 
@@ -171,7 +181,7 @@ description: OpenPrd 工作区与产物的共用守则。凡是需要查看、
 - 需要推进主工作流生命周期：使用 `$openprd-harness`
 - 需要前端审美框架、设计资产、主题/骨架/组件/任务 recipe、事实/素材/image-preflight/direction-plan：使用 `$openprd-frontend-design`
 - 需要最佳实践、benchmark、对标、参考产品、prompt engineering、Agent harness、context engineering、图标资源、CLI 或 skill 体系设计：先使用 `$openprd-benchmark-router` 选择证据源，再按 DeepWiki、Context7 或官方资料规则调研
-- 需要架构图、产品流程图、用户旅程或可视确认循环：使用 `$openprd-diagram-review`
+- 需要架构图、产品流程图、用户旅程、解释型 SVG 或可视确认循环：使用 `$openprd-diagram-review`
 - 需要更细的语言规则或命令分类说明时，阅读：
   - `references/operating-rules.md`
   - `references/language-and-review.md`

package/skills/openprd-standards/SKILL.md

@@ -15,7 +15,7 @@ OpenPrd standards 管三件事：
 - `.openprd/standards/file-manual-template.md` 定义的文件说明书规则
 - `.openprd/standards/folder-readme-template.md` 定义的文件夹 README 规则
 
-研发期还包含一个轻量标准层：`openprd dev-check <path> <file...>` 或 `node scripts/openprd-dev-check.mjs <path> <file...>`，用于 Agent 在代码修改完成后、最终回复前回顾本轮 touched code files 的行数状态和下一步动作建议。
+研发期还包含一个轻量标准层：`openprd dev-check <path> <file...>` 或 `node scripts/openprd-dev-check.mjs <path> <file...>`，用于 Agent 在代码修改完成后、最终回复前回顾本轮 touched code files 的行数状态和下一步动作建议。自动优化默认开启（`developmentStandards.autoRefactor.enabled`，`--auto-refactor on|off` 切换）：命中 attention/warning 时 Agent 在本轮直接完成高内聚低耦合拆分（不丢功能、行为不变、拆完重跑测试与 dev-check），最终回复以“OpenPRD 自动优化报告”呈现优化完成的结果（列：影响对象、问题级别、源文件规模、优化原因、本次处理结果、后续建议）并附开关确认一句话；关闭后回到“后续建议”推荐模式（列名回到关注程度、规模信号、预警原因）。dev-check 同时检测本轮是否触达界面文件：最近 24 小时没有拼图证据板时输出视觉证据提醒，附建议命令与对话流嵌入提示。
 
 自我成长标准层位于 `.openprd/growth/`：当 dev-check 高置信识别出新的代码扩展名时，可自动补齐识别规则并记录，减少后续重复提醒；执行中发现豁免路径、项目规矩、OpenPrd 默认行为或用户偏好需要增量时，先记录候选，收工时再运行 `openprd grow <path> --review` 集中确认。
 
@@ -48,7 +48,7 @@ OpenPrd standards 要求以下文档存在：
 ## 执行规则
 
 - 声称某个 change 就绪前，先运行 `openprd standards <path> --verify`
-- 代码修改完成后、最终回复前，针对本轮实际 touched code files 运行 `openprd dev-check <path> <file...>`；700 行以内正常，701-1500 行需留意，超过 1500 行说明后续改动成本较高。若出现需要关注的文件，最终回复必须以 **后续建议** 为标题，用 Markdown 表格列出影响位置、关注程度、规模信号、为什么需要关注、本次处理和后续建议，并按 🔴 → 🟠 → 🟡 排序
+- 代码修改完成后、最终回复前，针对本轮实际 touched code files 运行 `openprd dev-check <path> <file...>`；700 行以内正常，701-1500 行需留意，超过 1500 行说明后续改动成本较高。自动优化开启（默认）时，命中需要关注的文件先在本轮直接完成拆分，再以 **OpenPRD 自动优化报告** 为标题复用 dev-check 表格（列：影响对象、问题级别、源文件规模、优化原因、本次处理结果、后续建议）并附开关确认；用户要求关闭后运行 `openprd dev-check <path> --auto-refactor off`，之后以 **后续建议** 为标题输出推荐表格（列名回到关注程度、规模信号、预警原因）。两种模式都按 🔴 → 🟠 → 🟡 排序
 - dev-check 或执行过程产生自我成长项时，区分处理：高置信工具识别补全可以自动固化；用户偏好、项目协作规矩和 OpenPrd 默认行为只作为待确认候选，收工时集中 review
 - 新增配置类能力时同步评审 grow-aware 入口：候选类型、scope、review/apply 行为、拒绝后不重复提示，以及 user-local 与项目共享配置的边界
 - OpenPrd 自动生成的 change tasks 应包含 standards 维护任务
@@ -61,6 +61,8 @@ OpenPrd standards 要求以下文档存在：
 - 功能变更影响代码文件职责时，更新对应文件说明书
 - 功能变更影响文件夹职责或文件布局时，更新对应文件夹 README
 - 如果最终不需要改文档，也要说明已经做过影响检查，以及为什么现有文档依然准确
+- 更新 `docs/basic/` 时禁止 append-only 堆叠：同一事实只保留一处最新版本，过时段落直接删除或改写，不要写“更新：/补充：”式追加；单行不要超过 300 字符，长内容拆成分点或小节
+- `openprd standards <path> --verify` 会做文档质量体检：出现巨行（>300 字符）、平均行长退化（>200 字符）或 `prd.md` 落后超过 20 个 requirement 版本的警告时，先运行 `openprd docs-compact <path>` 查看按行号给出的压缩建议，压缩回填后再收口
 
 ## 文档影响检查