visual-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Purpose

用途

Render a plan as a visual MDX page instead of a wall of text, using the

vplan

CLI. The component vocabulary is general: although the examples below are code-flavored, it fits any structured plan (a product launch, a research agenda, an incident response), not just software changes. Use the components that fit the plan and skip the ones that do not.

Above all, show, don't tell: a reader should grasp the plan by scanning its diagrams, phases, and tables, with prose only connecting the visuals, not carrying the plan itself. The Show, don't tell section below is the heart of this skill.

If the
vplan
command is not found, install it globally first:
npm i -g vplan@latest
(published on npm). Re-run the failed command afterward.

通过

vplan

CLI将计划渲染为可视化MDX页面，而非大段文字。组件词汇具有通用性：尽管以下示例偏向代码场景，但它适用于任何结构化计划（如产品发布、研究议程、事件响应），不仅限于软件变更。选择符合计划需求的组件，跳过不需要的组件。

最重要的是展示而非描述：读者应通过浏览图表、阶段和表格就能理解计划，文字仅用于衔接可视化内容，而非承载计划本身。下文的“展示而非描述”部分是此技能的核心。

如果未找到
vplan
命令，请先全局安装：
npm i -g vplan@latest
（发布在npm上）。之后重新运行失败的命令。

Workflow

工作流程

Write the plan to a
```
.mdx
```
file, starting with a single
```
# Title
```
heading (it becomes the plan title; no frontmatter). Then use the components below; you never write
```
import
```
statements, they are always in scope.
Validate before showing the user:
```
vplan check <file>.mdx
```
. Fix every reported
```
file:line:col
```
issue (it names valid enum values and flags unknown components).
```
check
```
also runs a quality lint that flags weak renders (the enforced Gotchas below); its warnings fail
```
check
```
, so fix them too.
Present the plan with
vplan <file>.mdx
. An interactive review is the default way to deliver a plan, not a special mode reserved for sign-off. It opens the plan with a feedback layer where the user comments on whole sections or on selected text, answers any
<Questions>
directly (each question becomes an inline answer field; a question with nested option bullets becomes clickable choices, and the picked option's text (or the typed "Other" text) is the answer, printed back as
```
Answer to "<question>":
```
), then clicks Approve / Deny / Iterate. It blocks until they submit, prints the decision, comments, and answers to stdout, and exits: approve 0, deny 1, iterate 2, timeout 3 (
```
--timeout
```
, default 15m; closing the tab counts as deny). It is a long-running foreground server, so run it in the background. (The explicit
```
--review
```
flag still works but is redundant now that review is the default.) A comment may carry a severity tag: treat a
```
[must-fix]
```
comment as blocking (it must be addressed before the plan can be approved) and a
```
[suggestion]
```
or untagged comment as non-blocking input. Then act on the printed feedback:
- Approve -> proceed with the plan as written.
- Iterate -> revise the plan addressing each comment, then simply re-run
```
vplan <file>.mdx
```
  ; the review tab updates the same plan in place and the round number increments automatically (pass
```
-i N
```
  only to override it). Repeat until Approve or Deny. Edit the same
  .mdx
  file in place and re-render:
```
vplan
```
  snapshots each plan it presents (keyed by the file path), so the next render automatically marks what changed since the last view with a subtle git-gutter accent and a "N changed" summary, letting the user re-review only the delta. Pass
```
--diff <baseline.mdx>
```
  to diff against an explicit file instead of the snapshot, or
```
--no-diff
```
  to suppress diffing (e.g. a clean first look).
- Deny -> stop and reconsider; do not proceed.
Review is the right default for every non-trivial plan. Targeted comments and in-place
```
<Questions>
```
answers drive sharper revisions than back-and-forth chat, and the loop ends in an explicit Approve so you know it is settled. Reach for a static render (step 4) only when the user just wants to look, not shape or decide.
A static page, a live-reloading preview, or a PDF/JPG export are the non-review outputs, for when the user only wants to look or wants a shareable file rather than review one. When you need one, load
references/static-exports.md
; it holds the commands and flags for these (kept out of here so review stays the default path). Authoring the plan (everything below) is identical whichever output you choose.

Run

vplan components

anytime for the exact prop signatures.

将计划写入
```
.mdx
```
文件，开头以单个
```
# 标题
```
作为标题（它会成为计划的标题；无需前置元数据）。然后使用以下组件；无需编写
```
import
```
语句，它们始终处于可用状态。
展示给用户前先验证：
```
vplan check <file>.mdx
```
。修复所有报告的
```
file:line:col
```
问题（会列出有效的枚举值并标记未知组件）。
```
check
```
还会运行质量检查，标记效果不佳的渲染（即下文强制要求避免的问题）；其警告会导致
```
check
```
失败，因此也需要修复。
使用
vplan <file>.mdx
展示计划。交互式评审是交付计划的默认方式，并非仅用于签署的特殊模式。它会打开带有反馈层的计划页面，用户可以对整个章节或选定文本发表评论，直接回答
<Questions>
中的每个问题（每个问题会变成内联回答字段；带有嵌套选项项目符号的问题会变成可点击选项，选中选项的文本（或输入的“其他”文本）即为答案，会以
Answer to "<question>":
的形式输出），然后点击“批准/拒绝/迭代”。它会阻塞直到用户提交，将决策、评论和答案输出到标准输出后退出：批准返回0，拒绝返回1，迭代返回2，超时返回3（可通过
```
--timeout
```
设置，默认15分钟；关闭标签页视为拒绝）。它是一个长期运行的前台服务器，因此建议在后台运行。（显式的
```
--review
```
标志仍然有效，但现在评审已是默认模式，所以该标志多余。）评论可能带有严重性标签：将
```
[must-fix]
```
评论视为阻塞项（必须在计划批准前解决），
```
[suggestion]
```
或无标签评论视为非阻塞输入。然后根据输出的反馈采取行动：
- 批准 -> 按原计划执行。
- 迭代 -> 修改计划以解决每条评论，然后只需重新运行
```
vplan <file>.mdx
```
  ；评审标签页会原地更新计划，迭代次数会自动递增（仅在需要覆盖时传递
```
-i N
```
  ）。重复此过程直到获得批准或拒绝。原地编辑同一个
  .mdx
  文件并重新渲染：
```
vplan
```
  会为展示的每个计划创建快照（按文件路径标识），因此下次渲染会自动标记自上次查看以来的变更，带有细微的git-gutter高亮和“N处变更”摘要，让用户仅需重新评审变更部分。传递
```
--diff <baseline.mdx>
```
  可与指定文件对比差异，而非与快照对比；或传递
```
--no-diff
```
  禁用差异对比（例如首次查看时）。
- 拒绝 -> 停止并重新考虑；不要继续执行。
**对于所有非琐碎计划，评审都是正确的默认选择。**针对性评论和
```
<Questions>
```
的内联回答比来回沟通更能推动精准修订，且循环会以明确的批准结束，让你知道计划已确定。仅当用户只想查看而非调整或决策时，才使用静态渲染（步骤4）。
静态页面、实时重载预览或PDF/JPG导出是非评审输出，适用于用户仅需查看或需要可共享文件而非评审的场景。当需要这些输出时，加载
references/static-exports.md
；其中包含相关命令和标志（此处未列出，以便评审保持为默认流程）。无论选择哪种输出，计划的编写（以下所有内容）方式都是相同的。

随时运行

vplan components

查看确切的属性签名。

Components

组件

The data components (

FileTree

Chart

Stat

Compare

Matrix

Questions

Checklist

) take their data as markdown children, not props: write a normal markdown list (or, for

Matrix

and a multi-series

Chart

, a markdown table) between the tags. Only the scalar settings (

title

type

status

) are attributes. This is fewer tokens and avoids the

{[{ ... }]}

brace errors that break a render.

```
<Phase title="..." status="planned|active|done">
```
: one step in a numbered vertical timeline; wraps markdown (ordered lists, prose, nested components). The steps auto-number in order. One per major step of the plan.
```
```mermaid
```
fenced block, for diagrams: architecture (
```
flowchart
```
),
```
sequenceDiagram
```
, dependency graphs,
```
stateDiagram-v2
```
,
```
classDiagram
```
,
```
erDiagram
```
, and
```
xychart-beta
```
. Reach for this first for anything structural. (gantt and pie are not supported; use
```
<Chart>
```
for quantitative data.
```
check
```
now validates each diagram, so an unsupported type fails check with a
```
file:line:col
```
instead of rendering an error box.)
```
```math
```
fenced block, a display formula written in LaTeX, typeset as math (complexity bounds, probabilities, linear algebra). Example:
```
```math
```
then
```
T(n) = O(n \log n)
```
.
```
<Callout type="note|tip|risk|decision|warn">
```
: highlight a risk, decision, tip, or note; wraps markdown. (
```
note
```
is blue,
```
tip
```
is green,
```
decision
```
is purple,
```
risk
```
is red,
```
warn
```
is yellow.)
```
<FileTree>
```
: file-change map. One bullet per file,
```
- <change> <path>
```
, where
```
change
```
is
```
add|modify|delete|move
```
. A move needs both ends,
```
- move <from> -> <to>
```
(the file renders at its destination with the origin shown). A path ending in
```
/
```
marks a whole directory (e.g.
```
- delete src/legacy/
```
). A colored file-type icon is added automatically from the path's extension. Append
```
 -- <note>
```
to any line for a short inline comment on that change (what it does or why); keep it to a phrase, since it shares the row with the file name.
mdx
```
<FileTree>
- add src/gateway/rate-limiter.ts -- sliding-window check against Redis
- modify src/gateway/middleware.ts -- mount the limiter behind the flag
- delete src/gateway/legacy/
</FileTree>
```

<Chart type="bar|line|area|scatter|radar|gauge|funnel|treemap|pie" title="...">

: estimates/metrics. Single series: one bullet per point,

- <label>: <value>

(a number). Multi-series (

bar

line

area

radar

): a table whose header is

category | series1 | series2

(cells after the first name the series and become the legend; the first column is the category axis). Specifics:

scatter

is a table with exactly two value columns read as x and y (

| point | x | y |

);

pie

gauge

funnel

treemap

are always single-series, list form only (a table is rejected), with

gauge

on a 0-100 scale and

funnel

descending. Add

stacked

to a multi-series

bar

area

(

<Chart type="bar" stacked>

) to stack rather than group.

mdx

<Chart type="bar" title="Effort (days)">
- Limiter: 2
- Dashboards: 1
</Chart>

<Chart type="line" title="Latency by stage (ms)">
| Stage | p50 | p95 |
|-------|-----|-----|
| Auth  | 12  | 30  |
| DB    | 40  | 120 |
</Chart>

<Compare>

: weigh approaches side by side as pros/cons cards. Each option is a

## Name

heading (append

(pick)

to mark the recommended one) followed by as many

- pro:

- con:

bullets as you need.

mdx

<Compare>
## Redis sliding window (pick)
- pro: accurate
- pro: shared across nodes
- con: network hop

## In-memory token bucket
- pro: fast
- con: per-node only
</Compare>

<Matrix>

: a comparison grid (options across the columns, criteria down the rows) for scoring several choices against several dimensions. Write a markdown table; the first column is the row labels, and you append

(pick)

to one column header to highlight it. Use

<Compare>

for pros/cons,

<Matrix>

for a scorecard.

mdx

<Matrix>
| Dimension | Postgres (pick) | ClickHouse | DynamoDB |
|-----------|-----------------|------------|----------|
| Writes    | medium          | high       | high     |
| Querying  | high            | medium     | low      |
</Matrix>

```
<Questions>
```
: open questions you want the reader to resolve before building, one per bullet. Use this instead of burying uncertainties in prose. The title defaults to "Open questions"; override with
```
title="..."
```
. In a
```
--review
```
session each question is directly answerable, so prefer a
```
<Questions>
```
block over prose when you want the reviewer to answer specific questions. Nest bullets under a question to offer multiple-choice options: in a review they become clickable choices (plus an "Other" free-text field), and the chosen option's text comes back as the answer. Offer options whenever you can enumerate the likely answers; they get you a crisp, actionable answer instead of prose. A question with no nested bullets stays free-text.
mdx
```
<Questions>
- Should the limiter fail open or fail closed if Redis is unreachable?
  - Fail open, availability first
  - Fail closed, safety first
- Is a 15-minute access-token TTL acceptable?
</Questions>
```

<Checklist title="Done when">

: acceptance criteria / definition of done, as a markdown task list:

- [x]

for done,

- [ ]

for todo.

mdx

<Checklist title="Done when">
- [x] Returns 429 over the limit
- [ ] Dashboards live
</Checklist>

```
<Stat>
```
: headline plan metrics as a grid of cards (files changed, estimated uptime, rollout). One card per bullet,
```
- <label>: <value> (<intent>) -- <caption>
```
, where intent is one of
```
note|good|warn|risk
```
and both
```
(intent)
```
and
```
-- caption
```
are optional. The value is free text (
```
5 min
```
,
```
99.9%
```
), not a number. Use this for static facts, not time series (use
```
<Chart>
```
for those). Only add a
```
<Stat>
```
when the plan genuinely has standout numbers worth surfacing; most plans have none, and an invented or filler metric is worse than omitting the component entirely.
mdx
```
<Stat>
- Files changed: 12
- Est. uptime: 99.9% (good)
- RPO: 5 min (risk) -- worst-case data loss
</Stat>
```
Fenced code blocks are syntax-highlighted (Expressive Code): write
```
```ts
```
(or js, json, bash, python, go, rust, sql, yaml, etc.) to show a key snippet. Add a file name with
```
```ts title="src/path/file.ts"
```
to render a filename header on the block.
Mark lines and text inside a code block with Expressive Code props in the fence meta string (no component needed). Three marker types:
```
mark
```
(neutral, the default),
```
ins
```
(green, inserted),
```
del
```
(red, removed). Each takes line numbers, ranges, quoted strings, or a
```
/regex/
```
. Use this to call attention to the lines a plan changes.
- Lines/ranges (neutral):
```
```ts {2}
```
,
```
```ts {2-4}
```
  ,
```
```ts {1, 3, 5-6}
```
- Typed lines:
```
```ts ins={3-4} del={2} mark={6}
```
(combine freely in one block)
- Inline text:
```
```ts "TokenBucket"
```
, a rename as
```
```ts del="oldName" ins="newName"
```
- Regex (and capture group):
```
```ts /\bTODO\b/
```
,
```
```ts ins=/const (\w+) =/
```
  (marks the group)

数据组件（

FileTree

、

Chart

、

Stat

、

Compare

、

Matrix

、

Questions

、

Checklist

）将数据作为Markdown子元素而非属性传入：在标签之间编写普通Markdown列表（对于

Matrix

和多系列

Chart

，则编写Markdown表格）。只有标量设置（

title

、

type

、

status

）是属性。这样可以减少令牌数量，并避免导致渲染失败的

{[{ ... }]}

括号错误。

```
<Phase title="..." status="planned|active|done">
```
：编号垂直时间线中的一个步骤；可包裹Markdown（有序列表、文字、嵌套组件）。步骤会按顺序自动编号。每个计划的主要步骤对应一个
```
<Phase>
```
。
```
```mermaid
```
代码块，用于绘制图表：架构图（
```
flowchart
```
）、
```
sequenceDiagram
```
、依赖图、
```
stateDiagram-v2
```
、
```
classDiagram
```
、
```
erDiagram
```
和
```
xychart-beta
```
。任何结构化内容都优先使用此组件。（不支持gantt和pie图；定量数据请使用
```
<Chart>
```
。
```
check
```
现在会验证每个图表，因此不支持的类型会在
```
check
```
时以
```
file:line:col
```
的形式报错，而非渲染错误框。）
```
```math
```
代码块，使用LaTeX编写的显示公式，会渲染为数学格式（复杂度边界、概率、线性代数）。示例：
```
```math
```
后接
```
T(n) = O(n \log n)
```
。
```
<Callout type="note|tip|risk|decision|warn">
```
：突出显示风险、决策、提示或说明；可包裹Markdown。（
```
note
```
为蓝色，
```
tip
```
为绿色，
```
decision
```
为紫色，
```
risk
```
为红色，
```
warn
```
为黄色。）
```
<FileTree>
```
：文件变更映射。每个项目符号对应一个文件，格式为
```
- <change> <path>
```
，其中
```
change
```
为
```
add|modify|delete|move
```
。移动操作需要两端路径：
```
- move <from> -> <to>
```
（文件会渲染在目标路径，并显示来源）。路径以
```
/
```
结尾表示整个目录（例如
```
- delete src/legacy/
```
）。系统会根据路径的扩展名自动添加彩色文件类型图标。可在任何行后追加
```
 -- <note>
```
，为该变更添加简短的内联注释（说明变更内容或原因）；注释需简洁，因为它与文件名共享同一行。
mdx
```
<FileTree>
- add src/gateway/rate-limiter.ts -- sliding-window check against Redis
- modify src/gateway/middleware.ts -- mount the limiter behind the flag
- delete src/gateway/legacy/
</FileTree>
```
```
<Chart type="bar|line|area|scatter|radar|gauge|funnel|treemap|pie" title="...">
```
：估算/指标数据。单系列：每个项目符号对应一个数据点，格式为
```
- <label>: <value>
```
（数字）。多系列（
```
bar
```
/
```
line
```
/
```
area
```
/
```
radar
```
）：表格表头为
```
category | series1 | series2
```
（第一列之后的单元格为系列名称，会成为图例；第一列为分类轴）。细节说明：
```
scatter
```
是包含恰好两个值列的表格，分别作为x和y轴（格式为
```
| point | x | y |
```
）；
```
pie
```
/
```
gauge
```
/
```
funnel
```
/
```
treemap
```
始终为单系列，仅支持列表形式（表格会被拒绝），
```
gauge
```
使用0-100的刻度，
```
funnel
```
按降序排列。可为多系列
```
bar
```
/
```
area
```
添加
```
stacked
```
属性（
```
<Chart type="bar" stacked>
```
），以堆叠而非分组显示。
mdx
```
<Chart type="bar" title="Effort (days)">
- Limiter: 2
- Dashboards: 1
</Chart>

<Chart type="line" title="Latency by stage (ms)">
| Stage | p50 | p95 |
|-------|-----|-----|
| Auth  | 12  | 30  |
| DB    | 40  | 120 |
</Chart>
```

<Compare>

：将不同方案作为优缺点卡片并排展示。每个选项以

## 名称

标题开头（追加

(pick)

标记推荐方案），后跟任意数量的

- pro:

- con:

项目符号。

mdx

<Compare>
## Redis sliding window (pick)
- pro: accurate
- pro: shared across nodes
- con: network hop

## In-memory token bucket
- pro: fast
- con: per-node only
</Compare>

<Matrix>

：对比网格（列代表选项，行代表评估标准），用于针对多个维度对多个选项打分。编写Markdown表格；第一列为行标签，可在某列表头后追加

(pick)

以高亮该列。优缺点对比使用

<Compare>

，评分卡使用

<Matrix>

。

mdx

<Matrix>
| Dimension | Postgres (pick) | ClickHouse | DynamoDB |
|-----------|-----------------|------------|----------|
| Writes    | medium          | high       | high     |
| Querying  | high            | medium     | low      |
</Matrix>

```
<Questions>
```
：希望读者在开始执行前解决的开放式问题，每个项目符号对应一个问题。使用此组件替代将不确定性隐藏在文字中。标题默认为“开放式问题”；可通过
```
title="..."
```
覆盖。在
```
--review
```
会话中，每个问题都可直接回答，因此当你希望评审者回答特定问题时，优先使用
```
<Questions>
```
块而非文字。在问题下嵌套项目符号可提供多选选项：在评审中它们会变成可点击选项（外加“其他”自由文本字段），选中选项的文本会作为答案返回。只要能枚举可能的答案，就提供选项；这样能获得清晰、可执行的答案，而非冗长的文字。无嵌套项目符号的问题为自由文本输入。
mdx
```
<Questions>
- Should the limiter fail open or fail closed if Redis is unreachable?
  - Fail open, availability first
  - Fail closed, safety first
- Is a 15-minute access-token TTL acceptable?
</Questions>
```

<Checklist title="Done when">

：验收标准/完成定义，以Markdown任务列表形式呈现：

- [x]

表示已完成，

- [ ]

表示待完成。

mdx

<Checklist title="Done when">
- [x] Returns 429 over the limit
- [ ] Dashboards live
</Checklist>

```
<Stat>
```
：计划的关键指标以卡片网格形式展示（变更文件数、预计正常运行时间、部署情况）。每个项目符号对应一张卡片，格式为
```
- <label>: <value> (<intent>) -- <caption>
```
，其中
```
intent
```
为
```
note|good|warn|risk
```
之一，
```
(intent)
```
和
```
-- caption
```
均为可选。值为自由文本（如
```
5 min
```
、
```
99.9%
```
），而非数字。此组件用于展示静态事实，而非时间序列（时间序列请使用
```
<Chart>
```
）。仅当计划确实有值得突出的关键数字时才添加
```
<Stat>
```
；大多数计划不需要，虚构或填充的指标比省略该组件更糟糕。
mdx
```
<Stat>
- Files changed: 12
- Est. uptime: 99.9% (good)
- RPO: 5 min (risk) -- worst-case data loss
</Stat>
```
代码块会进行语法高亮（使用Expressive Code）：编写
```
```ts
```
（或js、json、bash、python、go、rust、sql、yaml等）展示关键代码片段。可通过
```
```ts title="src/path/file.ts"
```
添加文件名，在代码块上渲染文件名标题。
使用代码块元字符串中的Expressive Code属性标记代码块内的行和文本（无需组件）。三种标记类型：
```
mark
```
（中性，默认）、
```
ins
```
（绿色，表示新增）、
```
del
```
（红色，表示删除）。每种类型可接受行号、范围、引号字符串或
```
/regex/
```
。使用此功能突出计划变更的行。
- 行/范围（中性）：
```
```ts {2}
```
、
```
```ts {2-4}
```
  、
```
```ts {1, 3, 5-6}
```
- 指定类型的行：
```
```ts ins={3-4} del={2} mark={6}
```
（可在一个代码块中自由组合）
- 内联文本：
```
```ts "TokenBucket"
```
，重命名可写为
```
```ts del="oldName" ins="newName"
```
- 正则表达式（及捕获组）：
```
```ts /\bTODO\b/
```
、
```
```ts ins=/const (\w+) =/
```
  （标记捕获组）

Show, don't tell

展示而非描述

The whole point of a visual plan is to replace a wall of prose with something the reader grasps by scanning. Default to a component over a sentence: if a fact has structure, show it; do not describe it in paragraphs. Prose is the connective tissue between visuals, never the substance.

Lead with the structure. Open with at most a one-paragraph context, then a
```
```mermaid
```
architecture diagram, then the
```
<Phase>
```
timeline. The reader should understand the shape of the plan before reading a single full sentence.
Prefer a diagram or a
<FileTree>
to describing structure in words. A flowchart of the data path beats a paragraph tracing it; a file-change map beats sentences listing the files.
Move the meaning out of prose into the component that carries it. Risks and decisions go in
```
<Callout>
```
s, open questions in
```
<Questions>
```
, tradeoffs in
```
<Compare>
```
/
```
<Matrix>
```
, acceptance criteria in
```
<Checklist>
```
, not buried in paragraphs where they are easy to skim past.
Keep prose tight inside phases. A
```
<Phase>
```
is a step, not an essay: a line or two of intent, then the visual. The visual is the point.
Right-size what you show. A large effort opens with a diagram and several phases; a two-or-three-file change may need only a short
```
<FileTree>
```
and a
```
<Checklist>
```
. Do not add a diagram or phase that carries no information: an empty 2-node flowchart shows nothing and is worse than one plain sentence. Show when there is structure to show; otherwise a tight sentence is fine (this applies to
```
<Stat>
```
too, as its own entry notes).

可视化计划的核心是用读者可快速浏览的内容替代大段文字。优先使用组件而非句子：如果事实具有结构化，就展示它；不要用段落描述。文字只是可视化内容之间的衔接，绝非核心。

以结构开头。最多先用一段文字介绍背景，然后是
```
```mermaid
```
架构图，再是
```
<Phase>
```
时间线。读者应在阅读完整句子前就理解计划的整体框架。
优先使用图表或
<FileTree>
而非文字描述结构。数据路径的流程图胜过一段文字描述；文件变更映射胜过列出文件的句子。
将核心信息从文字转移到对应的组件中。风险和决策放入
```
<Callout>
```
，开放式问题放入
```
<Questions>
```
，权衡对比放入
```
<Compare>
```
/
```
<Matrix>
```
，验收标准放入
```
<Checklist>
```
，不要将它们隐藏在段落中，以免被读者忽略。
<Phase>
内的文字要简洁。
```
<Phase>
```
是一个步骤，而非一篇文章：一两句话说明意图，然后展示可视化内容。可视化内容才是重点。
合理选择展示内容。大型项目以图表和多个阶段开头；仅涉及两三个文件的变更可能只需简短的
```
<FileTree>
```
和
```
<Checklist>
```
。不要添加无信息的图表或阶段：一个空的2节点流程图毫无意义，不如用一句话说明。有结构需要展示时才使用可视化；否则简洁的句子即可（
```
<Stat>
```
组件也适用此原则，如前文所述）。

Composing a plan

计划组合

```
<Phase>
```
and
```
<Callout>
```
wrap arbitrary markdown and components: a
```
<FileTree>
```
,
```
<Chart>
```
,
```
<Matrix>
```
, a
```
```mermaid
```
diagram, a code block, or a
```
- [ ]
```
task list all nest inside them. Nest freely to group related content under a step or a highlight.
Diagrams and charts each render a hover "expand" button that opens a zoomable, pannable fullscreen viewer, so a dense diagram stays legible even when shrunk inline (code blocks do not). You can lean on it for a necessarily-large diagram, but splitting into smaller diagrams still reads better when the inline view must stand on its own.

```
<Phase>
```
和
```
<Callout>
```
可包裹任意Markdown和组件：
```
<FileTree>
```
、
```
<Chart>
```
、
```
<Matrix>
```
、
```
```mermaid
```
图表、代码块或
```
- [ ]
```
任务列表都可嵌套其中。自由嵌套以将相关内容分组到某个步骤或高亮部分下。
图表和图表都带有悬浮“展开”按钮，点击可打开可缩放、可平移的全屏查看器，因此即使内联显示的密集图表被缩小，仍能保持清晰（代码块无此功能）。对于必须较大的图表，可依赖此功能，但如果内联视图需要独立展示，将其拆分为多个较小的图表仍然更易阅读。

Rules

规则

Never pass
--no-open
for a user-facing plan. The point is that the user sees it; the review session opens automatically. Reserve
```
--no-open
```
for an explicit headless/CI request.
No images or external assets. The page is a single self-contained file, so a markdown image (
```
![](url)
```
) or any external asset cannot be embedded, and
```
check
```
rejects markdown images. Use a
```
```mermaid
```
diagram for anything visual, or describe it in text.

面向用户的计划切勿传递
--no-open
参数。核心是让用户看到计划；评审会话会自动打开。仅在明确的无头/CI请求时使用
```
--no-open
```
。
禁止使用图片或外部资源。页面是单个独立文件，因此Markdown图片（
```
![](url)
```
）或任何外部资源无法嵌入，
```
check
```
会拒绝Markdown图片。任何可视化内容请使用
```
```mermaid
```
图表，或用文字描述。

Gotchas

注意事项

Several of these (a wall-of-prose phase, a wide LR mermaid diagram, an over-long

Matrix

cell, a commented

FileTree

move row, a wildly-scaled

Chart

) are now enforced by the

check

quality lint and will fail it, so they are hard rules, not just style advice.

<
,
{
, and
}
are MDX syntax in prose. A bare
```
<Thing>
```
or
```
{value}
```
can break the render. Wrap literal angle brackets, braces, generics (
```
List<T>
```
), or tag-like text in backticks or a code fence, where every character is safe and literal.
Raw inline HTML tags fail
check
.
```
<kbd>
```
,
```
<sub>
```
,
```
<sup>
```
,
```
<details>
```
and the like are read as unknown components and fail; use backticks or plain text instead. Plain markdown otherwise works alongside the components: GFM tables (outside
```
<Matrix>
```
/
```
<Chart>
```
), blockquotes, footnotes,
```
~~strikethrough~~
```
, autolinks,
```
- [ ]
```
task lists, and custom-start ordered lists all render.
<Chart>
shows the shape of the data, not exact figures. There are no on-bar value labels, so any number the reader must know precisely belongs in prose too. Keep labels to a word or two (long bar/line x-axis labels get dropped or crowded), and never put series of wildly different magnitudes on one chart: a value near 50 beside one near 2,000,000 shares a single y-axis and flattens the small series to the zero line. Split into separate charts or normalize to the same unit.
<Matrix>
cells do not wrap. A long sentence in one cell forces a horizontal scrollbar and pushes the other columns off-screen. Keep cells to a word or a short score; put rationale in prose or a
```
<Callout>
```
, not in a cell.
Avoid
-- comments
on
<FileTree>

move
rows. A move already shows its origin path (the
```
← <from>
```
annotation), which eats most of the row width, so a comment on the same row gets crowded out. Leave move rows uncommented and put any explanation in prose or a
```
<Callout>
```
; reserve
```
-- comments
```
for add/modify/delete rows, which have the space.
Wide mermaid diagrams shrink to illegibility. Prefer top-down (
```
flowchart TD
```
) once a diagram has many nodes; a long left-to-right (
```
LR
```
) chain shrinks to fit the page and becomes effectively unreadable inline. Split a large flow into a few smaller diagrams instead of one sprawling one.

其中一些问题（大段文字的

<Phase>

、过宽的LR方向mermaid图表、过长的

Matrix

单元格、带有注释的

<FileTree>

移动行、比例失衡的

Chart

）现在已被

check

质量检查强制要求，会导致检查失败，因此这些是硬性规则，而非仅为风格建议。

<
、
{
和
}
是MDX的语法字符。裸写的
```
<Thing>
```
或
```
{value}
```
可能导致渲染失败。将字面量尖括号、大括号、泛型（
```
List<T>
```
）或类似标签的文本包裹在反引号或代码块中，其中所有字符都是安全的字面量。
原始内联HTML标签会导致
check
失败。
```
<kbd>
```
、
```
<sub>
```
、
```
<sup>
```
、
```
<details>
```
等会被视为未知组件并导致失败；请使用反引号或纯文本替代。除组件外，普通Markdown语法均可正常使用：GFM表格（
```
<Matrix>
```
/
```
<Chart>
```
之外）、块引用、脚注、
```
~~删除线~~
```
、自动链接、
```
- [ ]
```
任务列表和自定义起始编号的有序列表都可正常渲染。
<Chart>
展示数据的趋势，而非精确数值。图表上没有数据标签，因此读者必须精确了解的任何数值都应同时在文字中说明。标签保持一两个词即可（过长的条形/折线图x轴标签会被截断或拥挤），切勿将数量级差异极大的系列放在同一个图表中：数值接近50和接近2,000,000的数据共享同一y轴，会将小数值系列压缩到零线上。应拆分为单独的图表或归一化到同一单位。
<Matrix>
单元格不换行。单元格中的长句子会导致水平滚动条，将其他列推到屏幕外。单元格内容保持一个词或简短评分；理由放在文字或
```
<Callout>
```
中，不要放在单元格内。
避免在
<FileTree>
的
move
行上添加
--
注释。移动操作已显示来源路径（
```
← <from>
```
注释），会占用大部分行宽，同一行的注释会被挤掉。移动行不要添加注释，如有说明需求放在文字或
```
<Callout>
```
中；
```
--
```
注释仅用于add/modify/delete行，这些行有足够空间。
过宽的mermaid图表会缩小到难以辨认。当图表有多个节点时，优先使用自上而下的方向（
```
flowchart TD
```
）；过长的左右方向（
```
LR
```
）链会缩小以适应页面，导致内联显示时几乎无法阅读。将大型流程图拆分为几个较小的图表，而非一个庞大的图表。