Back to Details

richdocs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

richdocs — rich HTML companions for discovery docs

richdocs — 为发现文档提供富HTML伴生文档

Markdown stays the source of truth. This skill generates an HTML companion that renders the same 
.md
with higher fidelity — interactive graphs, tinted provider icons, branded theming — and serves it reliably on localhost.
Markdown始终是唯一可信的内容源。本工具会生成HTML伴生文档，以更高保真度渲染相同的
.md
文件——包含交互式图形、着色服务商图标、品牌化主题——并可在本地主机上可靠提供服务。

Route by intent

按意图选择操作

IntentDo this
"Make an HTML version of DOC.md"
md2html.py DOC.md
then 
serve.py
(multi-file, live-editable)
"One file I can open / attach"
md2html.py DOC.md --inline
(self-contained, opens over 
file://
)
"I need an AWS/GCP/Azure/K8s icon"
stencil.py search TERM
→ 
stencil.py extract ID --color HEX
"Build a custom SVG diagram with real icons"read 
resources/stencil-library.md
(registry + compose pattern)
"Interactive graph / chart in the doc"fenced 
```cytoscape
/ 
```plotly
block — see 
resources/rich-blocks.md
"3D scene, colour-space study, or a map"fenced 
```deckgl
block — see 
resources/rich-blocks.md
"Why is my palette not the palette I designed?"
```deckgl
with 
space: "oklch"
, 
gamut: [L]
and 
targetChroma
— draws the request against the sRGB gamut
"HTML looks broken opened from Finder"
file://
blocks fetch — run 
serve.py
(see 
resources/serving.md
)
"Render it in a brand theme"default is 
osakanights
; 
md2html.py DOC.md --theme NAME
for another (see 
--help
for installed themes)
"Re-brand the output"edit 
<stem>.tokens.json
in the output dir, refresh — no rebuild
"Override a theme for this project"drop 
tmp/richdocs/theme/<name>/design-tokens.json
(+ optional 
theme.css
) — shadows the built-in of that name
"Add a new brand theme"
resources/themes/<name>/design-tokens.json
(+ optional 
theme.css
)
"Is this theme readable?"
themecheck.py
— contrast gate over every brandpack; part of 
make ci
"Show off / compare the themes"
showcase.py
→ gallery of all brands; 
showcase.py --theme NAME
→ that brand alone
"Upgrade one of this repo's root docs"read 
resources/discovery-docs.md
(per-archetype recipes)
意图操作方式
"生成DOC.md的HTML版本"执行
md2html.py DOC.md
，再运行
serve.py
（支持多文件、实时编辑）
"生成可直接打开/附加的单文件"执行
md2html.py DOC.md --inline
（自包含文件，可通过
file://
打开）
"需要AWS/GCP/Azure/K8s图标"执行
stencil.py search TERM
→ 
stencil.py extract ID --color HEX
"使用真实图标构建自定义SVG图"阅读
resources/stencil-library.md
（注册表+组合模式）
"在文档中添加交互式图形/图表"使用
```cytoscape
/ 
```plotly
代码块——详见
resources/rich-blocks.md
"添加3D场景、色彩空间研究或地图"使用
```deckgl
代码块——详见
resources/rich-blocks.md
"为什么我的调色板不是设计好的样式？"在
```deckgl
中添加
space: "oklch"
, 
gamut: [L]
和
targetChroma
——会根据sRGB色域渲染请求
"从Finder打开HTML显示异常"
file://
协议会阻止资源获取——运行
serve.py
（详见
resources/serving.md
）
"按品牌主题渲染"默认主题为
osakanights
；执行
md2html.py DOC.md --theme NAME
切换其他主题（执行
--help
查看已安装主题）
"重新定制输出品牌风格"编辑输出目录中的
<stem>.tokens.json
，刷新页面即可——无需重新构建
"为当前项目覆盖主题"添加
tmp/richdocs/theme/<name>/design-tokens.json
（可选
theme.css
）——会覆盖同名内置主题
"添加新品牌主题"在
resources/themes/<name>/
目录下创建
design-tokens.json
（可选
theme.css
）
"检查主题可读性"执行
themecheck.py
——对所有品牌包进行对比度检查；属于
make ci
的一部分
"展示/对比所有主题"执行
showcase.py
→ 所有品牌的主题画廊；执行
showcase.py --theme NAME
→ 仅展示指定品牌
"升级仓库根目录下的文档"阅读
resources/discovery-docs.md
（针对不同文档类型的操作指南）

Quickstart

快速入门

bash
undefined
bash
undefined

1. Render a markdown doc into a rich HTML companion (multi-file, live mode)

1. 将Markdown文档渲染为富HTML伴生文档（多文件、实时模式）

uv run --no-project .claude/skills/richdocs/scripts/md2html.py TARGET_ARCHITECTURE.md
uv run --no-project .claude/skills/richdocs/scripts/md2html.py TARGET_ARCHITECTURE.md

2. Serve it (no-store headers, CDN libs load fine over http://localhost)

2. 启动服务（禁用缓存头，CDN库可通过http://localhost正常加载）

uv run --no-project .claude/skills/richdocs/scripts/serve.py tmp/richdocs --open
uv run --no-project .claude/skills/richdocs/scripts/serve.py tmp/richdocs --open

3. Or produce one self-contained file (no server needed)

3. 或生成单个自包含文件（无需服务器）

uv run --no-project .claude/skills/richdocs/scripts/md2html.py REVIEW.md --inline
uv run --no-project .claude/skills/richdocs/scripts/md2html.py REVIEW.md --inline

3b. Render in a brand theme (default is osakanights; pass --theme for another)

3b. 按品牌主题渲染（默认主题为osakanights；使用--theme指定其他主题）

uv run --no-project .claude/skills/richdocs/scripts/md2html.py DOC.md --theme v2ai
uv run --no-project .claude/skills/richdocs/scripts/md2html.py DOC.md --theme v2ai

4. Grab a tinted provider icon

4. 获取着色后的服务商图标

uv run --no-project .claude/skills/richdocs/scripts/stencil.py search lambda uv run --no-project .claude/skills/richdocs/scripts/stencil.py extract "mxgraph.aws4/lambda"
--color '#ED7100' --out diagrams/lambda.svg

Run everything from the repo root. Never `cd`.
uv run --no-project .claude/skills/richdocs/scripts/stencil.py search lambda uv run --no-project .claude/skills/richdocs/scripts/stencil.py extract "mxgraph.aws4/lambda"
--color '#ED7100' --out diagrams/lambda.svg

所有操作需在仓库根目录执行，请勿切换目录。

Mermaid gate (mandatory before rendering)

Mermaid检查（渲染前必须执行）

Any doc containing 
```mermaid
fences MUST pass this skill's vendored parse + contrast gates on the source markdown, before 
md2html.py
:
bash
bun run .claude/skills/richdocs/vendor/mermaidjs-diagrams/scripts/mermaid_complexity.ts SOURCE.md
bun run .claude/skills/richdocs/vendor/mermaidjs-diagrams/scripts/mermaid_contrast.ts SOURCE.md
First run only: 
bun install --cwd .claude/skills/richdocs/vendor/mermaidjs-diagrams/scripts --frozen-lockfile
.
Non-zero exit is a blocker — 
ParserFailure … yielded 0 nodes
means the fence is invalid mermaid and will render as a broken block in the companion. 
md2html.py
passes fences through verbatim; it cannot catch this for you. The vendored 
vendor/mermaidjs-diagrams/SKILL.md
documents both tools in full (profiles, complexity presets, authoring pitfalls like quoted mindmap labels and HTML entities). Prior adjudications on this class of failure live in 
resources/learned/
— treat them as already-decided, don't re-litigate.
任何包含
```mermaid
代码块的文档，在执行
md2html.py
前，必须通过本工具内置的解析+对比度检查，针对源Markdown文件：
bash
bun run .claude/skills/richdocs/vendor/mermaidjs-diagrams/scripts/mermaid_complexity.ts SOURCE.md
bun run .claude/skills/richdocs/vendor/mermaidjs-diagrams/scripts/mermaid_contrast.ts SOURCE.md
首次运行需执行：
bun install --cwd .claude/skills/richdocs/vendor/mermaidjs-diagrams/scripts --frozen-lockfile
。
非零退出码表示检查不通过——
ParserFailure … yielded 0 nodes
意味着代码块是无效的Mermaid语法，在伴生文档中会显示为损坏的块。
md2html.py
会直接传递代码块，无法为你捕获此类错误。内置的
vendor/mermaidjs-diagrams/SKILL.md
详细说明了这两个工具（配置文件、复杂度预设、编写陷阱如带引号的思维导图标签和HTML实体）。此前关于此类错误的判定记录在
resources/learned/
目录下——请直接遵循已有判定，无需重新讨论。

Command reference

命令参考

showcase.py [--theme NAME] [--out DIR]

showcase.py [--theme NAME] [--out DIR]

Emits a theme showcase exercising the full brand surface: colour ramps, the glyph disambiguation gate, type specimens, components, Plotly charts, a Cytoscape graph, Mermaid, and architecture diagrams built from the stencil pack.
  • no 
    --theme
     — a gallery: every installed brand, with a brand switcher and a light/dark toggle. Each brand honours its own 
    defaultTheme
    when selected.
  • --theme NAME
     — that brand alone: no switcher, and no other brand's tokens or CSS anywhere in the file. Safe to hand to a client.
Architecture SVGs carry their 
mxfile
source in a 
content
attribute, so "Download editable SVG" / "Download .drawio" re-open in diagrams.net as real AWS shapes rather than a flat image.
bash
uv run --no-project .claude/skills/richdocs/scripts/showcase.py                     # gallery
uv run --no-project .claude/skills/richdocs/scripts/showcase.py --theme osakanights # one brand
生成主题展示页面，全面展示品牌特性：色彩渐变、图标区分检查、字体样本、组件、Plotly图表、Cytoscape图形、Mermaid图，以及使用模板包构建的架构图。
  • 不指定
    --theme
     ——生成画廊：展示所有已安装品牌，包含品牌切换器和明暗模式切换。每个品牌被选中时会遵循自身的
    defaultTheme
    设置。
  • 指定
    --theme NAME
     ——仅展示该品牌：无切换器，文件中不包含其他品牌的令牌或CSS。可安全交付给客户。
架构SVG文件会在
content
属性中携带
mxfile
源，因此“下载可编辑SVG”/“下载.drawio”文件可在diagrams.net中重新打开为真实的AWS形状，而非扁平图像。
bash
uv run --no-project .claude/skills/richdocs/scripts/showcase.py                     # 生成画廊
uv run --no-project .claude/skills/richdocs/scripts/showcase.py --theme osakanights # 仅展示指定品牌

md2html.py DOC.md [--out DIR] [--inline] [--theme NAME] [--tokens FILE] [--title T]

md2html.py DOC.md [--out DIR] [--inline] [--theme NAME] [--tokens FILE] [--title T]

  • --theme NAME
     — a named brand theme. Supplies both the brandpack (
    design-tokens.json
    ) and its 
    theme.css
    — which is the only place a webfont can actually be 
    @import
    ed and a display face assigned to headings. A brandpack alone cannot do either. Overrides 
    --tokens
    . An unknown name fails loudly and lists what is installed. Run 
    --help
    to see the current set.
    • Default theme is 
      osakanights
       — a plain 
      md2html.py DOC.md
      renders branded, not neutral. Pass 
      --theme NAME
      for a different brand, or 
      --tokens FILE
      (with no 
      --theme
      ) for the raw-brandpack escape hatch.
    • Themes resolve from two roots, project first: 
      tmp/richdocs/theme/<name>/
      (optional project overrides, run from repo root) then the skill's built-in 
      resources/themes/<name>/
      . A project theme shadows the built-in of the same name and can add project-only themes. With no override dir the skill is the built-in set only — fully self-contained.
  • Multi-file (default, 
    --out
    = 
    tmp/richdocs
    )     — writes 
    <stem>.html
    plus a copy of the 
    .md
    and 
    design-tokens.json
    . The HTML fetches the paired markdown at runtime (
    ?v=<BUILD_ID>
    , 
    cache: no-store
    ) and renders client-side. Edit the copied 
    .md
    , refresh the browser: live authoring loop. Requires 
    serve.py
     — 
    file://
    blocks fetch by design.
  • --inline
     — one self-contained HTML with the markdown embedded on 
    window.__DOC_MD__
    and tokens on 
    window.__DOC_TOKENS__
    . Opens over 
    file://
    . Network still needed for the pinned CDN libraries.
  • --tokens FILE
     — raw-brandpack escape hatch (see schema in 
    resources/rich-blocks.md
    ). Applies only when passed and 
    --theme
    is not; otherwise the default 
    osakanights
    theme wins.
  • --theme NAME
     ——指定品牌主题。同时提供品牌包（
    design-tokens.json
    ）和对应的
    theme.css
    ——这是唯一可
    @import
    网页字体并为标题指定显示字体的地方。仅使用品牌包无法实现上述功能。该参数会覆盖
    --tokens
    。如果指定的主题名称不存在，会报错并列出已安装的主题。执行
    --help
    查看当前可用主题列表。
    • 默认主题为
      osakanights
       ——直接执行
      md2html.py DOC.md
      会渲染为品牌化样式，而非中性样式。执行
      --theme NAME
      切换其他品牌，或不指定
      --theme
      仅使用
      --tokens FILE
      （原始品牌包应急方案）。
    • 主题从两个目录加载，优先项目目录：
      tmp/richdocs/theme/<name>/
      （可选的项目覆盖目录，需在仓库根目录执行），然后是工具内置的
      resources/themes/<name>/
      。项目主题会覆盖同名内置主题，并可添加项目专属主题。如果没有覆盖目录，则仅使用工具内置主题——完全自包含。
  • 多文件模式（默认，
    --out
    = 
    tmp/richdocs
    ）     ——生成
    <stem>.html
    文件，同时复制对应的
    .md
    和
    design-tokens.json
    文件。HTML会在运行时获取配对的Markdown文件（
    ?v=<BUILD_ID>
    ，
    cache: no-store
    ）并在客户端渲染。编辑复制后的
    .md
    文件，刷新浏览器即可实现实时编辑循环。需要使用
    serve.py
    ——
    file://
    协议会阻止资源获取。
  • --inline
     ——生成单个自包含HTML文件，Markdown内容嵌入在
    window.__DOC_MD__
    中，令牌嵌入在
    window.__DOC_TOKENS__
    中。可通过
    file://
    打开。仍需网络连接加载固定CDN库。
  • --tokens FILE
     ——原始品牌包应急方案（详见
    resources/rich-blocks.md
    中的 schema）。仅当指定该参数**且未指定
    --theme
    **时生效；否则默认使用
    osakanights
    主题。

Reporting a generated doc (worktree-aware)

报告生成的文档（支持工作树）

md2html.py
ends every run with a 
── richdoc output ──
block: the slug (doc stem — use it as the shared shorthand), the worktree dir and branch the output landed in (resolved from the output file, not the process cwd), the absolute source 
.md
and 
.html
paths (so they cmd+click open in the editor across worktrees), and two serve commands for the absolute output dir (
serve.py
with no-store, and stdlib 
python3 -m http.server <port> --directory <abs-dir>
). When you report a generated doc back to the user, relay these verbatim — absolute paths and the slug, never a bare relative path.
md2html.py
每次运行结束后会输出
── richdoc output ──
块：包含slug（文档主干——用作共享缩写）、输出文件所在的工作树目录和分支（从输出文件解析，而非进程当前目录）、源
.md
和
.html
文件的绝对路径（支持跨工作树在编辑器中通过cmd+click打开），以及两个针对输出目录绝对路径的服务命令（禁用缓存的
serve.py
，以及标准库的
python3 -m http.server <port> --directory <abs-dir>
）。当你向用户报告生成的文档时，请直接转发这些信息——使用绝对路径和slug，切勿使用相对路径。

serve.py [DIR] [--port 8642] [--open]

serve.py [DIR] [--port 8642] [--open]

Serves DIR (default 
tmp/richdocs
) on 
127.0.0.1
with 
Cache-Control: no-store
on every response, so a browser refresh always re-fetches fresh markdown/JSON. Busy port and missing dir fail loudly. 
--open
launches the browser. This is the answer to "reliably serve localhost HTML that pulls Tailwind / Google Fonts / Cytoscape / deck.gl / plotly / mermaid" — third-party CDNs load fine over 
http://localhost
; only 
file://
breaks fetch.
在
127.0.0.1
上提供DIR目录的服务（默认
tmp/richdocs
），所有响应均带有
Cache-Control: no-store
头，因此浏览器刷新时总会重新获取最新的Markdown/JSON文件。端口被占用或目录不存在时会报错。
--open
参数会启动浏览器。这是“可靠提供可加载Tailwind / Google Fonts / Cytoscape / deck.gl / plotly / mermaid的本地HTML服务”的解决方案——第三方CDN可通过
http://localhost
正常加载；仅
file://
协议会阻止资源获取。

stencil.py packs | list | search | extract

stencil.py packs | list | search | extract

Vendored draw.io stencil library (
assets/stencils.json.zip
, thousands of provider icons keyed 
"<pack>/<name>"
, packs: 
mxgraph.aws4
, 
mxgraph.gcp2
, 
mxgraph.azure
, 
mxgraph.mscae*
, 
mxgraph.kubernetes*
).
bash
stencil.py packs                       # pack prefixes + counts
stencil.py list --pack mxgraph.gcp2 --limit 40
stencil.py search "cloud run"
stencil.py extract "mxgraph.aws4/lambda" --color '#ED7100' --size 64 --out lambda.svg
Every stencil paints 
currentColor
; 
--color
tints by string-replace (works in every renderer). Omit 
--color
and the SVG inherits its parent's 
color
— ideal for inlining into themed HTML. Unknown ID exits 1 with close-match suggestions.
内置draw.io模板库（
assets/stencils.json.zip
，包含数千个服务商图标，键为
"<pack>/<name>"
，包包括：
mxgraph.aws4
, 
mxgraph.gcp2
, 
mxgraph.azure
, 
mxgraph.mscae*
, 
mxgraph.kubernetes*
）。
bash
stencil.py packs                       # 列出包前缀及图标数量
stencil.py list --pack mxgraph.gcp2 --limit 40
stencil.py search "cloud run"
stencil.py extract "mxgraph.aws4/lambda" --color '#ED7100' --size 64 --out lambda.svg
所有模板均使用
currentColor
着色；
--color
参数通过字符串替换实现着色（适用于所有渲染器）。省略
--color
参数时，SVG会继承父元素的
color
——非常适合嵌入到主题化HTML中。如果指定的ID不存在，会退出并返回1，同时提供近似匹配的建议。

Fenced rich blocks (in the rendered markdown)

富代码块（在渲染后的Markdown中）

Beyond standard markdown + 
```mermaid
, the HTML companion renders:
markdown
```cytoscape
{ "elements": [ {"data": {"id": "a", "label": "API"}},
                {"data": {"id": "b", "label": "DB"}},
                {"data": {"source": "a", "target": "b"}} ],
  "height": 420 }
```

```plotly
{ "data": "cost_series.json" }
```
  • Payload is either inline JSON or 
    { "data": "relative/path.json" }
    — the external file is fetched with cache-busting: the data-driven mode. Generate the 
    .json
    from real sources (terraform plan, dbt manifest, pricing API) and the doc stays current on refresh.
  • Canvas colours come from 
    design-tokens.json
    (
    canvas.cytoscape.*
    , 
    canvas.plotly.*
    ), never CSS — canvases can't read CSS variables. Theme toggle re-feeds the palette and re-renders.
  • Full block contract + token schema: 
    resources/rich-blocks.md
    .
除标准Markdown + 
```mermaid
外，HTML伴生文档还支持渲染：
markdown
```cytoscape
{ "elements": [ {"data": {"id": "a", "label": "API"}},
                {"data": {"id": "b", "label": "DB"}},
                {"data": {"source": "a", "target": "b"}} ],
  "height": 420 }
```

```plotly
{ "data": "cost_series.json" }
```
  • payload可以是内联JSON或
    { "data": "relative/path.json" }
    ——外部文件会通过缓存破坏机制获取：即数据驱动模式。从真实数据源（terraform计划、dbt清单、定价API）生成
    .json
    文件，刷新页面即可保持文档内容最新。
  • 画布颜色来自
    design-tokens.json
    （
    canvas.cytoscape.*
    , 
    canvas.plotly.*
    ），而非CSS——画布无法读取CSS变量。切换主题时会重新加载调色板并重新渲染。
  • 完整的代码块规范+令牌schema：详见
    resources/rich-blocks.md
    。

Cross-cutting conventions

通用约定

  • Escalators, not stairs: a missing hard requirement (input file, busy port, unknown stencil id) crashes loudly with the reason. No silent skips.
  • Determinism: same input → same output modulo 
    {{BUILD_ID}}
    . Cache-bust every runtime fetch with 
    ?v=<BUILD_ID>
    .
  • Inline-embed safety: anything embedded in a 
    <script>
    escapes 
    </
    as 
    <\/
    — a stray 
    </script>
    in doc content must not terminate the tag.
  • Brandpack is data, not code: re-skin = edit 
    design-tokens.json
    in the output dir and refresh. 
    FALLBACK_TOKENS
    baked into the JS is a soft-fail net only, never the source of truth.
  • Outputs land in project-local 
    tmp/richdocs/
    (gitignored), never system 
    /tmp
    .
  • Authored prose follows the global-audience standard: when this skill writes prose (showcase copy, UI/error strings, its own docs, or a discovery doc it is asked to upgrade), apply resources/prose-style.md: no em-dash, Australian English, short coherent clauses, inclusive language, standardised vocabulary. The user's canonical markdown is rendered as written, never silently corrected.
  • 直接报错，不静默跳过：缺少硬依赖（输入文件、端口被占用、未知模板ID）时会直接报错并说明原因。不会静默跳过。
  • 确定性：相同输入→相同输出（除
    {{BUILD_ID}}
    外）。所有运行时获取均使用
    ?v=<BUILD_ID>
    实现缓存破坏。
  • 内联嵌入安全：任何嵌入到
    <script>
    中的内容都会将
    </
    转义为
    <\/
    ——文档内容中的
    </script>
    不会终止脚本标签。
  • 品牌包是数据，而非代码：重新定制样式只需编辑输出目录中的
    design-tokens.json
    并刷新页面。JS中内置的
    FALLBACK_TOKENS
    仅作为软失败保障，并非可信源。
  • 输出文件存放在项目本地的
    tmp/richdocs/
    目录（已加入.gitignore），而非系统
    /tmp
    目录。
  • 编写的文案遵循全球受众标准：当本工具编写文案时（展示页面内容、UI/错误字符串、自身文档，或被要求升级的发现文档），需遵循resources/prose-style.md：不使用破折号、使用澳大利亚英语、短句连贯、包容性语言、标准化词汇。用户的原始Markdown内容会按原样渲染，不会被自动修正。

Resources

资源

FileContent
resources/serving.md
Localhost serving contract, pinned CDN table (Tailwind, fonts, cytoscape, deck.gl, plotly, mermaid), 
file://
vs 
http://
failure modes
resources/stencil-library.md
Stencil pack schema, tint mechanism, registry pattern, composing full custom SVG diagrams from icons
resources/rich-blocks.md
Fenced block contract, design-tokens schema, two-palette (chrome vs canvas) theming
resources/discovery-docs.md
Recipes for upgrading each discovery-doc archetype (diagram-driven, table-driven, prose review) to rich HTML
resources/prose-style.md
Global-audience standard for prose this skill authors: no em-dash, Australian English, short clauses, inclusive language, standardised vocabulary (self-contained copy)
scripts/serve.py
No-store localhost server
scripts/stencil.py
Stencil library query/extract CLI
scripts/md2html.py
Paired markdown → rich HTML generator
assets/stencils.json.zip
Vendored draw.io icon library (see 
assets/NOTICE
)
assets/design-tokens.json
Default neutral brandpack
vendor/mermaidjs-diagrams/
Vendored mermaid toolchain: parse/complexity gate, WCAG contrast gate, color-theming references, render script
resources/learned/
Prior adjudications and self-taught facts — read before re-litigating
richdocs is self-contained: every tool and reference it operates with lives inside this skill directory. Never point runtime instructions at another skill's files.
文件内容
resources/serving.md
本地服务规范、固定CDN列表（Tailwind、字体、cytoscape、deck.gl、plotly、mermaid）、
file://
vs 
http://
的失败模式
resources/stencil-library.md
模板包schema、着色机制、注册表模式、使用图标构建完整自定义SVG图的方法
resources/rich-blocks.md
富代码块规范、设计令牌schema、双调色板（界面元素 vs 画布）主题机制
resources/discovery-docs.md
将不同类型发现文档（图表驱动、表格驱动、评审文案）升级为富HTML的指南
resources/prose-style.md
本工具编写文案的全球受众标准：不使用破折号、澳大利亚英语、短句、包容性语言、标准化词汇（自包含文案）
scripts/serve.py
禁用缓存的本地服务器
scripts/stencil.py
模板库查询/提取CLI
scripts/md2html.py
Markdown→富HTML配对生成工具
assets/stencils.json.zip
内置draw.io图标库（详见
assets/NOTICE
）
assets/design-tokens.json
默认中性品牌包
vendor/mermaidjs-diagrams/
内置Mermaid工具链：解析/复杂度检查、WCAG对比度检查、颜色主题参考、渲染脚本
resources/learned/
此前的判定记录和经验总结——重新讨论前请先阅读
richdocs是自包含工具：其运行所需的所有工具和参考文档均位于本工具目录内。切勿在运行时指向其他工具的文件。