diagram

图是承重结构，不是装饰。 只有当散文迫使读者在脑中同时装下整个形状时，才去画图——然后选择最小的视图，让读者直接看到形状，而不是从句子中重建它。这里的一切都以文本块或 Mermaid 的形式渲染在对话中；最多只会写出一个产物文件。

词汇表

选一种视图；最多两种。更多就是噪音。

伪代码 — 不带语言噪音的逻辑。把决策简化为它的分支形状：

on(request)
  if state file locked by another writer
    queue and return pending
  acquire lock
  write
  release

调用树 — 运行时控制流。深度显示谁拥有流程；在有趣的分支处标注：

acquireStateFileLockSync()
  resolveLockPath()
  openExclusive()
  writePid()

组件树 — UI 或模块结构，内联标注重要的边界：

<SettingsPage> (src/routes/settings)
  <SessionList> (owns its fetches)
  <DangerZone>
    <ConfirmButton> (disabled until typed confirmation)

文件树 — 职责所在之处；保持浅层，每个目录一条注释：

src/
├── hooks/        # hook registry + types
├── tools/        # MCP tool handlers
└── workflow/     # registry + projections

Mermaid — 各方之间的交互、数据流或状态转换：

sequenceDiagram
    participant CLI
    participant Hook
    participant State
    CLI->>Hook: PreToolUse
    Hook->>State: read mode
    Hook-->>CLI: allow / deny + facts

Diff — 当周围结构已经存在时，变更的形状。让 diff 与主题匹配：

组件变更：

 <SettingsPage>
   <SessionList />
   <DangerZone>
+    <ConfirmButton />
   </DangerZone>

文件布局变更：

 src/tools/
-└── state-tools.ts
+└── state-tools/
+   ├── handlers.ts
+   └── schema.ts

控制流变更：

 commit()
   stage()
     hashBlobs()
+  writeObject()
   updateRef()
+    acquireStateFileLock()

状态机变更：

 on(request)
-  write immediately
+  if locked
+    queue and return pending
+  acquire lock
+  write
+  release

整个块 — 当省略会隐藏谁拥有什么或事情的运行顺序时，完整展示一次该单元，可复制：

export function isRegistryEnabled(): boolean {
  const flag = process.env.OMC_WORKFLOW_REGISTRY;
  return flag !== '0' && flag !== 'false';
}

当文字不够用时

一个 UI 布局、一个前后对比，或一个对 Mermaid 来说过于密集的概念：写一个聚焦的 HTML 文件——一张图、一张信息图，或几张幻灯片——按照产品自身的颜色、字体和组件来设计，填入真实的标签和数据，在桌面端和移动端都能正常工作。用平台打开器打开它（Windows 上用 start，macOS 上用 open，Linux 上用 xdg-open），然后到此为止：一个产物，而不是一个画廊。

纪律

• 把每个可视化直接放在它所支持的两三句话旁边。
• 只携带回答当前问题所需的调用、文件、props、状态和边界——每一个多余的节点都是读者的解码负担。
• 如果诚实的答案一句话就够了，就写那句话。