diff --git a/AGENTS.md b/AGENTS.md index a8a1f2ac..ba1932c0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -83,7 +83,7 @@ **判据**:描述含多个实体、实体间有明确关系(先后顺序、包含、依赖、状态转移、布局对比)的内容时,直接画图说明,不写长段文字;单点事实(一句装得下)不画,纯数据对照用表格。 -**载体**:节点连边图(流程/状态/结构/实体关系)默认用 Mermaid 代码块;需要空间对比、像素级示意、界面草图时用 visualize 技能出 HTML/SVG;查看端不支持渲染时退回字符画。 +**载体**:默认用 visualize 技能出 HTML/SVG(会话内联渲染,表现力优先),流程/状态/结构/实体关系与空间对比、像素级示意、界面草图同一通道;查看端不支持内联渲染时退回 Mermaid 代码块,仍不行用字符画。 **边界**:硬数值与前提条件留在文字里,图不承载唯一数值依据;图与文禁重复说同一件事,文字只留图说不清的部分。 diff --git a/design/engineering/doc-conventions.md b/design/engineering/doc-conventions.md index 24adccdf..80efd0c8 100644 --- a/design/engineering/doc-conventions.md +++ b/design/engineering/doc-conventions.md @@ -30,11 +30,11 @@ |---|---|---| | 规则的来龙去脉、行为逻辑 | 散文段 | 每段 ≤240 字,一段一件事 | | 枚举、数值、边界、依赖 | 表格 | 表格只放可列举的事实;禁把需要解释的内容塞进单元格让读者自己拼 | -| 流程、状态流转、结构关系 | 字符画或 Mermaid 代码块 | 禁用散文逐步描述流程;多分支状态机、实体关系、模块依赖这类复杂结构图优先 Mermaid(源码即文本,查看端不渲染也可读可改),简单线性流程与无渲染查看环境用字符画 | +| 流程、状态流转、结构关系 | 文档内嵌 HTML/SVG(默认)· Mermaid(网页发布保底)· 字符画(无渲染环境保底) | 禁用散文逐步描述流程;默认在文档内嵌 HTML/SVG(表现力优先,本地预览即渲染,图体行数计入节点篇幅);发布到会过滤内嵌 HTML 的网页端时改 Mermaid;无渲染查看环境用字符画 | | 公式 | 结论先行 | 先一行加粗结论,再放公式代码块、变量表与验算表 | | 体验锚点 | 关键词表 | 支柱/关键词/机制承诺 三列表,禁长篇情绪描述 | -节点内顺序:先人话,再表格枚举,再流程图(字符画或 Mermaid),最后公式举证。**规则两段式**:先写"人话阶段"(作用于哪个系统、什么情况下、谁触发、触发后发生什么),再写"举证阶段"(逐效果给出计算方法;纯流程规则明写"无计算")。规则名禁止纯名词短语(反面例:"获取路由")。 +节点内顺序:先人话,再表格枚举,再流程图(内嵌 HTML/SVG 或字符画),最后公式举证。**规则两段式**:先写"人话阶段"(作用于哪个系统、什么情况下、谁触发、触发后发生什么),再写"举证阶段"(逐效果给出计算方法;纯流程规则明写"无计算")。规则名禁止纯名词短语(反面例:"获取路由")。 ## 4. 用语纪律(见名知意 · 所见即所得 · 禁自造黑话)