From e34dceb1a9923950887e5ef38b7c83710156cca6 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Sat, 31 Oct 2026 06:04:46 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3(=E5=9B=BE=E4=BC=98=E5=85=88?= =?UTF-8?q?=E8=A1=A8=E8=BE=BE=E6=89=B9):=20AGENTS.md=20=E5=9B=9E=E7=AD=94?= =?UTF-8?q?=E9=A3=8E=E6=A0=BC=E8=A7=84=E5=88=99=E5=8A=A0=E5=9B=BE=E4=BC=98?= =?UTF-8?q?=E5=85=88=E5=B0=8F=E8=8A=82+=E6=A0=BC=E5=BC=8F=E4=BC=98?= =?UTF-8?q?=E5=85=88=E7=BA=A7=E6=8D=A2=E4=BB=A3=E2=80=94=E2=80=94=E5=88=A4?= =?UTF-8?q?=E6=8D=AE=3D=E5=A4=9A=E5=AE=9E=E4=BD=93=E6=98=8E=E7=A1=AE?= =?UTF-8?q?=E5=85=B3=E7=B3=BB(=E9=A1=BA=E5=BA=8F/=E5=8C=85=E5=90=AB/?= =?UTF-8?q?=E4=BE=9D=E8=B5=96/=E7=8A=B6=E6=80=81=E8=BD=AC=E7=A7=BB/?= =?UTF-8?q?=E5=B8=83=E5=B1=80=E5=AF=B9=E6=AF=94)=E5=86=85=E5=AE=B9?= =?UTF-8?q?=E7=9B=B4=E6=8E=A5=E7=94=BB=E5=9B=BE=E4=B8=8D=E5=86=99=E9=95=BF?= =?UTF-8?q?=E6=AE=B5,=E5=8D=95=E7=82=B9=E4=BA=8B=E5=AE=9E=E4=B8=8E?= =?UTF-8?q?=E7=BA=AF=E6=95=B0=E6=8D=AE=E4=B8=8D=E7=94=BB;=E8=BD=BD?= =?UTF-8?q?=E4=BD=93=3D=E8=8A=82=E7=82=B9=E8=BF=9E=E8=BE=B9=E5=9B=BE?= =?UTF-8?q?=E9=BB=98=E8=AE=A4Mermaid=E4=BB=A3=E7=A0=81=E5=9D=97=C2=B7?= =?UTF-8?q?=E7=A9=BA=E9=97=B4=E5=AF=B9=E6=AF=94=E4=B8=8E=E5=83=8F=E7=B4=A0?= =?UTF-8?q?=E7=BA=A7=E7=A4=BA=E6=84=8F=E8=B5=B0visualize=E6=8A=80=E8=83=BD?= =?UTF-8?q?HTML/SVG=C2=B7=E6=97=A0=E6=B8=B2=E6=9F=93=E6=9F=A5=E7=9C=8B?= =?UTF-8?q?=E7=AB=AF=E9=80=80=E5=9B=9E=E5=AD=97=E7=AC=A6=E7=94=BB;?= =?UTF-8?q?=E8=BE=B9=E7=95=8C=3D=E7=A1=AC=E6=95=B0=E5=80=BC=E4=B8=8E?= =?UTF-8?q?=E5=89=8D=E6=8F=90=E7=95=99=E6=96=87=E5=AD=97=C2=B7=E5=9B=BE?= =?UTF-8?q?=E4=B8=8D=E6=89=BF=E8=BD=BD=E5=94=AF=E4=B8=80=E6=95=B0=E5=80=BC?= =?UTF-8?q?=E4=BE=9D=E6=8D=AE=C2=B7=E5=9B=BE=E6=96=87=E7=A6=81=E9=87=8D?= =?UTF-8?q?=E5=A4=8D;doc-conventions=20=E8=A1=A8=E8=BE=BE=E5=88=86?= =?UTF-8?q?=E5=B7=A5=E5=90=8C=E6=AD=A5=E6=89=A9(=C2=A73=E6=B5=81=E7=A8=8B?= =?UTF-8?q?=E8=A1=8C=E6=89=A9=E3=80=8C=E5=AD=97=E7=AC=A6=E7=94=BB=E6=88=96?= =?UTF-8?q?Mermaid=E3=80=8D=E6=94=B6=E7=BC=96=E7=BB=93=E6=9E=84=E5=85=B3?= =?UTF-8?q?=E7=B3=BB=E7=B1=BB,=E5=A4=8D=E6=9D=82=E7=BB=93=E6=9E=84?= =?UTF-8?q?=E5=9B=BE=E4=BC=98=E5=85=88Mermaid=E6=BA=90=E7=A0=81=E5=8D=B3?= =?UTF-8?q?=E6=96=87=E6=9C=AC,=C2=A72=E7=AE=AD=E5=A4=B4=E9=93=BE=E5=8F=A5?= =?UTF-8?q?=E4=B8=8E=E8=8A=82=E7=82=B9=E5=86=85=E9=A1=BA=E5=BA=8F=E5=8F=A5?= =?UTF-8?q?=E9=9A=8F=E6=94=B9);=E4=BE=9D=E6=8D=AE=3Dcnoe-io/LMCache/vercel?= =?UTF-8?q?-labs=E4=B8=89=E4=BB=BDAGENTS.md=E5=9C=A8=E6=A1=88=E6=9D=A1?= =?UTF-8?q?=E6=AC=BE+Anthropic=E7=B3=BB=E7=BB=9F=E6=8F=90=E7=A4=BA?= =?UTF-8?q?=E8=AF=8Dartifacts=E5=9B=BE=E7=A4=BA=E5=BF=85=E9=A1=BB=E5=8F=AF?= =?UTF-8?q?=E8=A7=86=E5=8C=96=E8=A7=84=E5=88=99,2026-10-31=20=E7=94=A8?= =?UTF-8?q?=E6=88=B7=E8=A3=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 10 +++++++++- design/engineering/doc-conventions.md | 6 +++--- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9be8b476..a8a1f2ac 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -77,7 +77,15 @@ ### 格式优先级 -枚举用列表，二维对照用表格，按内容形态选；散文是最后手段。 +能画图的内容一律画图说明，图是第一优先载体；枚举用列表，二维对照用表格；散文是最后手段。 + +### 图优先 + +**判据**：描述含多个实体、实体间有明确关系（先后顺序、包含、依赖、状态转移、布局对比）的内容时，直接画图说明，不写长段文字；单点事实（一句装得下）不画，纯数据对照用表格。 + +**载体**：节点连边图（流程/状态/结构/实体关系）默认用 Mermaid 代码块；需要空间对比、像素级示意、界面草图时用 visualize 技能出 HTML/SVG；查看端不支持渲染时退回字符画。 + +**边界**：硬数值与前提条件留在文字里，图不承载唯一数值依据；图与文禁重复说同一件事，文字只留图说不清的部分。 ## 主动检索提醒 diff --git a/design/engineering/doc-conventions.md b/design/engineering/doc-conventions.md index 8d5f9bb9..24adccdf 100644 --- a/design/engineering/doc-conventions.md +++ b/design/engineering/doc-conventions.md @@ -18,7 +18,7 @@ 写文档像向朋友当面解释你的游戏： 1. **完整句子优先**：一段只说一件事，长句拆短句。 -2. **禁止碎片笔记体**：不写压缩碎片，不把 `A→B→C` 箭头链当叙述（流程交给字符画，见第 3 节），不用只有作者自己懂的缩略语。 +2. **禁止碎片笔记体**：不写压缩碎片，不把 `A→B→C` 箭头链当叙述（流程交给图，见第 3 节），不用只有作者自己懂的缩略语。 3. **每节人话开头**：每小节第一段先用白话说清"这是什么、为什么需要它"；只读各节第一段就能看懂全文故事线。 4. **术语首现即解释**：专业术语或项目概念首次出现用一句话解释；玩家可见专属名词（如"显影尘"）同样要说清。 5. **叙述优先于引用**：AC-x、F-x 等编号引用不进正文叙述，只出现在验收标准与附录。 @@ -30,11 +30,11 @@ |---|---|---| | 规则的来龙去脉、行为逻辑 | 散文段 | 每段 ≤240 字，一段一件事 | | 枚举、数值、边界、依赖 | 表格 | 表格只放可列举的事实；禁把需要解释的内容塞进单元格让读者自己拼 | -| 流程、状态流转 | 字符画（代码块） | 禁用散文逐步描述流程 | +| 流程、状态流转、结构关系 | 字符画或 Mermaid 代码块 | 禁用散文逐步描述流程；多分支状态机、实体关系、模块依赖这类复杂结构图优先 Mermaid（源码即文本，查看端不渲染也可读可改），简单线性流程与无渲染查看环境用字符画 | | 公式 | 结论先行 | 先一行加粗结论，再放公式代码块、变量表与验算表 | | 体验锚点 | 关键词表 | 支柱/关键词/机制承诺 三列表，禁长篇情绪描述 | -节点内顺序：先人话，再表格枚举，再字符流程图，最后公式举证。**规则两段式**：先写"人话阶段"（作用于哪个系统、什么情况下、谁触发、触发后发生什么），再写"举证阶段"（逐效果给出计算方法；纯流程规则明写"无计算"）。规则名禁止纯名词短语（反面例："获取路由"）。 +节点内顺序：先人话，再表格枚举，再流程图（字符画或 Mermaid），最后公式举证。**规则两段式**：先写"人话阶段"（作用于哪个系统、什么情况下、谁触发、触发后发生什么），再写"举证阶段"（逐效果给出计算方法；纯流程规则明写"无计算"）。规则名禁止纯名词短语（反面例："获取路由"）。 ## 4. 用语纪律（见名知意 · 所见即所得 · 禁自造黑话）