visual-docs-team

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Visual docs team

可视化文档团队

A multi-phase workflow that turns a codebase into an interactive docs site using parallel agents. One agent per domain cluster, all running concurrently, all writing into disjoint files in the same scaffold. The skill is repo-independent — drop it into any

.claude/skills/

directory and it works.

一个多阶段工作流，通过并行Agent将代码库转换为交互式文档站点。每个领域集群对应一个Agent，所有Agent同时运行，在同一脚手架中写入互不重叠的文件。该Skill与代码库无关——只需将其放入任意

.claude/skills/

目录即可运行。

When to use

使用场景

Trigger this skill when the user asks for documentation that goes beyond plain markdown — animated explainers, interactive walkthroughs, wire-format inspectors, or visual diagrams.

What you'll produce is a running React + Vite + Tailwind app. Not markdown. Not static HTML. Not a generator. The user opens it in a browser and clicks through it.

Three explainer categories, each backed by named components:

Workflows →
```
Stepper
```
driving
```
PacketTracer
```
or
```
SequenceLane
```
(step-by-step animations: request flow, handshakes, lifecycle transitions, state machines).
Data types & wire formats →
```
MessageInspector
```
(Fields ↔ JSON toggle),
```
CodePeek
```
(collapsible struct/SQL snippets with file:line citations),
```
Card
```
grids for schema columns.
Architecture & reference →
```
ComponentNode
```
-based static diagrams, error matrices, API endpoint tables, vocabulary grids, custom SVG state diagrams.

Signal phrases that trigger this skill: "make beautiful docs", "interactive docs", "agent team", "one page per domain", "animate how my service handles requests", "explainer site for my wire protocol", "visualize the architecture".

For a single markdown page or a one-off ASCII diagram, this is overkill — recommend something lighter.

当用户要求生成超越纯Markdown的文档时触发此Skill，例如动画讲解器、交互式演示、有线格式检查器或可视化图表。

你将产出一个可运行的React + Vite + Tailwind应用。不是Markdown，不是静态HTML，也不是生成器。用户可在浏览器中打开并点击浏览。

三类讲解组件，各由命名组件支持：

工作流 →
```
Stepper
```
驱动
```
PacketTracer
```
或
```
SequenceLane
```
（分步动画：请求流、握手、生命周期转换、状态机）。
数据类型与有线格式 →
```
MessageInspector
```
（字段↔JSON切换）、
```
CodePeek
```
（带文件:行号引用的可折叠结构体/SQL代码片段）、用于模式列的
```
Card
```
网格。
架构与参考 → 基于
```
ComponentNode
```
的静态图表、错误矩阵、API端点表、词汇网格、自定义SVG状态图。

触发此Skill的标志性表述："制作美观的文档"、"交互式文档"、"Agent团队"、"按领域分页面"、"动画演示我的服务如何处理请求"、"为我的有线协议生成讲解站点"、"可视化架构"。

如果用户只需要单个Markdown页面或一次性ASCII图表，此Skill过于复杂——建议使用更轻量化的工具。

Reference implementation

参考实现

The skill bundles four working reference pages under

<skill-dir>/references/examples/

, each demonstrating a distinct structural pattern. Content agents read the closest analog before writing their cluster's page. The pages contain real domain terms (a Go orchestration project's wire protocol) — agents are told to ignore the content and mirror the structure.

Output cluster wants to explain…	Bundled reference
An end-to-end workflow / request flow	`examples/workflow-walkthrough.tsx`
A handshake or message lifecycle	`examples/sequence-handshake.tsx`
A data model / schema / state machine	`examples/data-model.tsx`
A landing page	`examples/landing.tsx`

See

references/examples/README.md

for what to extract from each file. The same patterns apply whether the host project is a Go service, a Python web app, or a Rust CLI — only the prose and the cluster names change.

该Skill在

<skill-dir>/references/examples/

下捆绑了四个可用的参考页面，每个页面展示一种独特的结构模式。内容Agent在编写对应集群的页面之前，会先阅读最相似的参考页面。这些页面包含真实的领域术语（一个Go编排项目的有线协议）——需告知Agent忽略内容，只复制结构。

输出集群需讲解的内容…	捆绑的参考页面
端到端工作流/请求流	`examples/workflow-walkthrough.tsx`
握手或消息生命周期	`examples/sequence-handshake.tsx`
数据模型/模式/状态机	`examples/data-model.tsx`
着陆页	`examples/landing.tsx`

查看

references/examples/README.md

了解每个文件需提取的内容。无论宿主项目是Go服务、Python Web应用还是Rust CLI，相同的模式均适用——仅需修改文本和集群名称。

Phase 0 — Preflight: verify agent teams is enabled

阶段0 — 预检：验证Agent团队功能已启用

Run the preflight script first. The skill dispatches multiple background agents that run concurrently, which requires the experimental agent-teams runtime.

bash

bash <skill-dir>/scripts/check_agent_teams.sh

Exit 0 → continue. Exit 1 → STOP and show the user the JSON to add (the script prints it on stderr). Do not try to work around a missing flag — without it, parallel dispatch falls back to sequential and the workflow loses most of its value.

If the user is on a fresh machine, prefer adding the env to the project-local

.claude/settings.json

rather than the user-global one — this keeps the flag scoped to projects that want it.

首先运行预检脚本。该Skill会调度多个后台Agent并行运行，这需要实验性的agent-teams运行时支持。

bash

bash <skill-dir>/scripts/check_agent_teams.sh

返回值0 → 继续。返回值1 → 停止操作，并向用户展示需添加的JSON（脚本会在stderr中打印）。不要尝试绕过缺失的标志——若无该标志，并行调度会退化为串行执行，工作流将失去大部分价值。

如果用户使用新机器，建议将环境变量添加到项目本地的

.claude/settings.json

而非用户全局配置中——这样可将该标志的作用范围限定在需要它的项目内。

Phase 1 — Clarify scope

阶段1 — 明确范围

Before any code touches disk, ask the user up to four short questions using

AskUserQuestion

. These four are the same ones the original workflow asked — they shape the entire downstream pipeline, so don't skip them.

Output format. Recommend "Interactive docs site (Vite app)" by default. The scaffold this skill ships is Vite — alternative formats require abandoning the bundled assets.
Topic clusters. Multi-select. Pre-fill with the clusters you inferred from the repo survey (Phase 2). Let the user add or drop.
Interactivity. Animated walkthroughs vs. static diagrams. The bundled components support both; animated is the default.
Audience. Layered (both) / new-contributor / reviewer. Layered is the recommended default — each page leads with friendly prose then drills into struct-level detail.

If the user has already specified any of these in their initial prompt, skip those questions.

在任何代码写入磁盘之前，使用

AskUserQuestion

向用户提出最多四个简短问题。这四个问题与原始工作流中的问题一致——它们会影响整个下游流程，请勿跳过。

输出格式。默认推荐"交互式文档站点（Vite应用）"。此Skill提供的脚手架基于Vite——其他格式需要放弃捆绑的资源。
主题集群。多选。预填你从代码库调研（阶段2）中推断出的集群。允许用户添加或删除。
交互性。动画演示vs静态图表。捆绑的组件支持两种模式；默认使用动画模式。
受众。分层（两者兼顾）/新贡献者/审核者。分层是推荐的默认选项——每个页面先以友好的文本开头，再深入到结构体级别的细节。

如果用户在初始提示中已指定了其中任何一项，可跳过对应问题。

Phase 2 — Survey the repo and propose domain clusters

阶段2 — 调研代码库并提出领域集群建议

Read the project's orientation files before proposing anything:

```
AGENTS.md
```
/
```
CLAUDE.md
```
(these are usually symlinks to one another)
```
CONTEXT.md
```
if it exists
```
README.md
```
The module-map section of any of the above

Then run a quick survey:

bash

ls -la <repo-root>
find <repo-root> -maxdepth 3 -type d -name 'internal' -o -name 'pkg' -o -name 'src' -o -name 'lib' | head -20

Identify 4–6 domain clusters. A good cluster has:

a clear scope with no overlap with siblings
maps to 1–2 doc pages
corresponds to a coherent subsystem (not a random grab-bag)

Map each cluster to one of the four accent colors. The accents are fixed by the scaffold's CSS:

arch

(green),

tunnel

(blue),

shell

(amber),

auth

(violet). If you have more than four clusters, let related clusters share an accent — adjacent topics on the same color reads as grouped in the sidebar.

Present the cluster list back to the user (in Phase 1's question #2) and confirm before proceeding.

在提出任何建议之前，先阅读项目的定位文件：

```
AGENTS.md
```
/
```
CLAUDE.md
```
（通常彼此为符号链接）
若存在则阅读
```
CONTEXT.md
```
```
README.md
```
上述文件中的模块映射部分

然后运行快速调研：

bash

ls -la <repo-root>
find <repo-root> -maxdepth 3 -type d -name 'internal' -o -name 'pkg' -o -name 'src' -o -name 'lib' | head -20

识别4–6个领域集群。优质集群需满足：

范围清晰，与其他集群无重叠
对应1–2个文档页面
对应一个连贯的子系统（而非随机组合）

将每个集群映射到四种强调色之一。脚手架的CSS中固定了这些强调色：

arch

（绿色）、

tunnel

（蓝色）、

shell

（琥珀色）、

auth

（紫色）。若集群数量超过四个，可让相关集群共享一种强调色——侧边栏中相同颜色的相邻主题会被视为一组。

将集群列表反馈给用户（在阶段1的问题#2中）并确认后再继续。

Phase 3 — Research pass

阶段3 — 调研阶段

Dispatch ONE research agent with

subagent_type: Explore

. Its only job is to produce a single markdown fact-sheet that all downstream content agents will cite from. This avoids each content agent re-grepping the same files and improves accuracy.

See

references/research-prompt.md

for the full prompt template. Fill in the cluster-specific bullets (which files to read, which structs and constants matter).

Save the result to

/tmp/<project-slug>-factsheet.md

. The path is the contract between this phase and Phase 5.

Wait for the research agent to complete before continuing.

调度一个

subagent_type: Explore

的调研Agent。它的唯一任务是生成一个Markdown事实表，供所有下游内容Agent引用。这样可避免每个内容Agent重复搜索相同的文件，提高准确性。

查看

references/research-prompt.md

获取完整的提示模板。填写集群特定的项目符号（需读取的文件、重要的结构体和常量）。

将结果保存到

/tmp/<project-slug>-factsheet.md

。该路径是此阶段与阶段5之间的约定。

等待调研Agent完成后再继续。

Phase 4 — Audit existing UI stack, then scaffold

阶段4 — 审核现有UI栈，然后搭建脚手架

If the project has an existing frontend (e.g.,

server/web

frontend/

ui/

), read its

package.json

and primary CSS to identify the design language — fonts, color palette, component library. The docs site should feel like a sibling, not a stranger.

Then run the scaffold script:

bash

bash <skill-dir>/scripts/scaffold_site.sh [base_dir]

base_dir

defaults to

docs

. The script always creates a timestamped target so every generation is a non-destructive snapshot of the docs at a point in time:

<base_dir>/site-YYYYMMDDTHHMMSSZ/

The timestamp is UTC ISO-8601 compact (e.g.

docs/site-20260518T095612Z/

). Capture the printed

scaffold ready at:

path — that's the directory the rest of the workflow operates in. Pass it as

<docs-site-path>

to every subsequent command.

What the script does:

Creates
```
<base_dir>/site-<UTC_TS>/
```
(will not clobber)
Copies
```
assets/scaffold/
```
into it
Writes
```
metadata.json
```
capturing the documented repo's git state (commit, short hash, branch, dirty status, remote URL, describe, HEAD message + author + committed_at)
Runs
```
npm install
```
Rebuilds
```
<base_dir>/index.html
```
— the wrapper index that lists every previous run so the user can browse generations side by side
Leaves the scaffold ready for project-specific customization

What the script does NOT do (you do these next):

Write
```
src/lib/topics.ts
```
from the chosen clusters
Write
```
src/App.tsx
```
with the cluster routes
Write
```
src/pages/Home.tsx
```
(landing page)
Write stub
```
src/pages/<Cluster>.tsx
```
files for every cluster
Update
```
metadata.json
```
with the cluster list (do this in Phase 6, after the team finishes)

Templates for all four are in

references/templates.md

. Use them verbatim, substituting cluster data. The bundled

references/examples/landing.tsx

is a working reference for the landing page structure.

Smoke-test the empty scaffold build before dispatching content agents:

bash

cd <docs-site-path>
npm run build 2>&1 | tail -25

Build must pass with stubs. If it fails at this stage, finding the problem now (one orchestrator context) is far cheaper than finding it inside four parallel agents.

如果项目已有前端（例如

server/web

、

frontend/

、

ui/

），读取其

package.json

和主CSS文件以识别设计语言——字体、调色板、组件库。文档站点应与项目风格一致，而非格格不入。

然后运行脚手架脚本：

bash

bash <skill-dir>/scripts/scaffold_site.sh [base_dir]

base_dir

默认为

docs

。脚本始终创建一个带时间戳的目标目录，因此每次生成都是文档在特定时间点的非破坏性快照：

<base_dir>/site-YYYYMMDDTHHMMSSZ/

时间戳采用UTC ISO-8601紧凑格式（例如

docs/site-20260518T095612Z/

）。记录打印出的

scaffold ready at:

路径——这是后续工作流操作的目录。将其作为

<docs-site-path>

传递给所有后续命令。

脚本执行的操作：

创建
```
<base_dir>/site-<UTC_TS>/
```
（不会覆盖现有内容）
将
```
assets/scaffold/
```
复制到该目录
写入
```
metadata.json
```
，记录被文档化代码库的git状态（提交记录、短哈希、分支、脏状态、远程URL、描述、HEAD提交消息+作者+提交时间）
运行
```
npm install
```
重建
```
<base_dir>/index.html
```
——该索引页面会列出所有之前的生成结果，以便用户可并排浏览不同版本的文档
使脚手架准备好进行项目特定的自定义

脚本不执行的操作（需你后续完成）：

根据所选集群编写
```
src/lib/topics.ts
```
编写包含集群路由的
```
src/App.tsx
```
编写
```
src/pages/Home.tsx
```
（着陆页）
为每个集群编写占位符
```
src/pages/<Cluster>.tsx
```
文件
更新
```
metadata.json
```
中的集群列表（在阶段6中完成，待所有Agent完成后）

所有四个文件的模板均位于

references/templates.md

中。直接使用这些模板，替换集群数据。捆绑的

references/examples/landing.tsx

是着陆页结构的可用参考。

在调度内容Agent之前，对空脚手架进行构建冒烟测试：

bash

cd <docs-site-path>
npm run build 2>&1 | tail -25

占位符文件必须能通过构建。若此时构建失败，在一个编排器上下文中查找问题比在四个并行Agent中查找要高效得多。写入占位符后运行30秒的

npm run build

可提前捕获所有此类错误。

Phase 5 — Dispatch content agents in parallel

阶段5 — 并行调度内容Agent

This is the heart of the workflow. One

general-purpose

agent per cluster, all dispatched in a single turn with multiple Agent tool calls so they run concurrently. Set

run_in_background: true

on each — the orchestrator will get completion notifications instead of polling.

See

references/content-agent-prompt.md

for the full prompt template. Each agent receives:

The cluster label, accent, and file list (their disjoint write targets)
The fact-sheet path with their cluster section
The path to
```
CONTRIBUTING.md
```
in the scaffold (the component API contract — also available at
```
references/components.md
```
in this skill)
The expected page structure (PageHeader → Overview → Walkthrough → Wire → Reference)
An instruction to run
```
npm run build
```
and fix any TS errors before returning

File ownership rules (these are why parallelism is safe):

Each cluster owns one or two
```
src/pages/*.tsx
```
files
Each cluster optionally owns
```
src/data/<cluster>.ts
```
for diagram data
No agent touches shared components, the App, the topics file, or another cluster's pages

While the agents work, do not touch any files in

src/pages/

src/data/

. You can write the README, polish unrelated files, or just wait for notifications.

这是工作流的核心。为每个集群分配一个

general-purpose

Agent，在同一轮中通过多个Agent工具调用进行调度，使其并行运行。为每个Agent设置

run_in_background: true

——编排器将收到完成通知，而非轮询。

查看

references/content-agent-prompt.md

获取完整的提示模板。每个Agent会收到：

集群标签、强调色和文件列表（它们的独立写入目标）
包含其集群部分的事实表路径
脚手架中
```
CONTRIBUTING.md
```
的路径（组件API约定——也可在此Skill的
```
references/components.md
```
中找到）
预期的页面结构（PageHeader → Overview → Walkthrough → Wire → Reference）
返回前需运行
```
npm run build
```
并修复所有TS错误的指令

文件所有权规则（这是并行操作安全的原因）：

每个集群拥有一个或两个
```
src/pages/*.tsx
```
文件
每个集群可选择拥有
```
src/data/<cluster>.ts
```
用于图表数据
任何Agent不得修改共享组件、App、topics文件或其他集群的页面

在Agent工作期间，请勿修改

src/pages/

或

src/data/

中的任何文件。你可以编写README、完善无关文件，或等待通知。

Phase 6 — Integrate and verify

阶段6 — 集成与验证

When all content agents have returned:

Run the combined build:
bash
```
cd <docs-site-path>
npm run build 2>&1 | tail -30
```
Each agent's individual build check doesn't catch type errors that only surface when all pages compile together. This is the integration test.

Update

<docs-site>/metadata.json

with the cluster list and any decisions from Phase 1. Use

Edit

Write

to merge keys — the file already has

generated_at

generator

, and

source

; add:

json

{
  "clusters": [
    { "key": "arch", "label": "Architecture", "accent": "arch" },
    { "key": "tunnel", "label": "Tunnel & wire protocol", "accent": "tunnel" }
  ],
  "format": "vite-react",
  "audience": "layered"
}

The

write_metadata.py

helper preserves these keys across re-runs, so the list is durable even if you later refresh the git state after a new commit.

Refresh the wrapper index so the new run's cluster chips show up:
bash
```
python3 <skill-dir>/scripts/rebuild_index.py <base_dir>
```
The wrapper lives at
```
<base_dir>/index.html
```
. Each card on it shows date, branch, commit, dirty status, the HEAD commit message, the cluster chips, and direct links into that run's built bundle.
Host the wrapper and open it. This is the user-facing payoff — they shouldn't have to figure out the right
```
npm run preview
```
incantation or remember the dist/ path:
bash
```
python3 <skill-dir>/scripts/serve.py <base_dir>
```
What this does:
- Starts
```
python3 -m http.server
```
  on port 4173 (or +1/+2 if busy) bound to 127.0.0.1, with
```
--directory <base_dir>
```
  , fully detached so it survives this turn ending.
- Writes
```
<base_dir>/.visual-docs-team.{pid,port,log}
```
  so re-runs replace the previous server cleanly.
- Opens the URL:
  - Inside VS Code (or a fork like Cursor — detected via
```
TERM_PROGRAM=vscode
```
    ,
```
VSCODE_PID
```
    , or
```
VSCODE_IPC_HOOK
```
    ): prints the Cmd+Shift+P → "Simple Browser: Show" recipe with the URL pre-formatted for copy-paste. VS Code's CLI does not expose
```
simpleBrowser.show
```
    , so a manual one-liner is the most reliable cross-version path.
  - Outside VS Code: opens the system default browser via Python's
```
webbrowser
```
    module.
- Pass
```
--external
```
  to force the system browser even inside VS Code; pass
```
--no-open
```
  to start the server silently.
To stop the server later:
bash
```
bash <skill-dir>/scripts/stop_server.sh <base_dir>
```
Report to the user:
- The live URL (
```
http://localhost:<port>/
```
  ) — the wrapper is open in front of them, this is just so they can re-find it
- The timestamped target path (
```
docs/site-<TS>/
```
  ) and what commit it was generated from (read from
```
metadata.json
```
  )
- How to stop the server when they're done (
```
bash <skill-dir>/scripts/stop_server.sh <base>
```
  )
- File inventory (
```
find <docs-site>/src -name '*.tsx' -o -name '*.ts' | xargs wc -l
```
  )
- Combined gzipped size from the build output
- How to run dev with hot reload (
```
cd <docs-site> && npm run dev
```
  )

当所有内容Agent返回结果后：

运行组合构建：
bash
```
cd <docs-site-path>
npm run build 2>&1 | tail -30
```
每个Agent的单独构建检查无法捕获仅在所有页面一起编译时才会出现的类型错误。这是集成测试。

更新

<docs-site>/metadata.json

，添加集群列表和阶段1中的任何决策。使用

Edit

或

Write

合并键——文件已包含

generated_at

、

generator

和

source

；添加：

json

{
  "clusters": [
    { "key": "arch", "label": "Architecture", "accent": "arch" },
    { "key": "tunnel", "label": "Tunnel & wire protocol", "accent": "tunnel" }
  ],
  "format": "vite-react",
  "audience": "layered"
}

write_metadata.py

助手会在重新运行时保留这些键，因此即使你在新提交后刷新git状态，列表也会保持不变。

刷新索引页面，使新生成结果的集群芯片显示出来：
bash
```
python3 <skill-dir>/scripts/rebuild_index.py <base_dir>
```
索引页面位于
```
<base_dir>/index.html
```
。每个卡片显示日期、分支、提交、脏状态、HEAD提交消息、集群芯片以及指向该次生成构建包的直接链接。
托管索引页面并打开它。这是面向用户的最终成果——用户无需自行摸索正确的
```
npm run preview
```
命令或记住dist/路径：
bash
```
python3 <skill-dir>/scripts/serve.py <base_dir>
```
该脚本执行的操作：
- 在端口4173（若繁忙则+1/+2）启动
```
python3 -m http.server
```
  ，绑定到127.0.0.1，设置
```
--directory <base_dir>
```
  ，完全后台运行，即使本轮操作结束也会继续运行。
- 写入
```
<base_dir>/.visual-docs-team.{pid,port,log}
```
  ，以便重新运行时可干净地替换之前的服务器。
- 打开URL：
  - 在VS Code中（或其分支如Cursor——通过
```
TERM_PROGRAM=vscode
```
    、
```
VSCODE_PID
```
    或
```
VSCODE_IPC_HOOK
```
    检测）：打印Cmd+Shift+P → "Simple Browser: Show"的操作说明，并预格式化URL以便复制粘贴。VS Code的CLI不支持
```
simpleBrowser.show
```
    ，因此手动单行命令是跨版本最可靠的方式。
  - 在VS Code外：通过Python的
```
webbrowser
```
    模块打开系统默认浏览器。
- 传递
```
--external
```
  参数可强制在VS Code内使用系统浏览器；传递
```
--no-open
```
  参数可静默启动服务器。
后续停止服务器的命令：
bash
```
bash <skill-dir>/scripts/stop_server.sh <base_dir>
```
向用户报告：
- 实时URL（
```
http://localhost:<port>/
```
  ）——索引页面已在用户面前打开，此信息仅用于用户重新查找
- 带时间戳的目标路径（
```
docs/site-<TS>/
```
  ）及其生成时对应的提交记录（从
```
metadata.json
```
  读取）
- 完成后如何停止服务器（
```
bash <skill-dir>/scripts/stop_server.sh <base>
```
  ）
- 文件清单（
```
find <docs-site>/src -name '*.tsx' -o -name '*.ts' | xargs wc -l
```
  ）
- 构建输出的总压缩大小
- 如何运行带热重载的开发服务（
```
cd <docs-site> && npm run dev
```
  ）

Orchestration anti-patterns

编排反模式

These are the failure modes the original workflow hit and recovered from — avoid them.

这些是原始工作流遇到并解决的失败模式——请避免。

Tailing agent transcripts

跟踪Agent转录内容

The agent's JSONL output file is enormous and will blow your context window. The completion notification already contains the summary, the token count, and the duration. Trust it.

Agent的JSONL输出文件非常庞大，会耗尽你的上下文窗口。完成通知已包含摘要、令牌计数和持续时间。请信任这些信息。

Writing pages while agents run

在Agent运行时编写页面

If the orchestrator writes a page file at the same time as a content agent, last-write-wins. Always finish your scaffold writes before dispatching. Once dispatched, only touch files outside

src/pages/

and

src/data/

如果编排器与内容Agent同时写入同一个页面文件，最后写入的内容会覆盖之前的。请在调度Agent前完成所有脚手架写入操作。调度完成后，仅修改

src/pages/

和

src/data/

之外的文件。

Skipping the empty-build smoke test

跳过空构建冒烟测试

It's tempting to dispatch agents immediately after scaffolding. Don't. A typo in

src/lib/topics.ts

src/App.tsx

will fail every single agent's build verification, and you'll spend an hour debugging four parallel transcripts to find one mistake the orchestrator made. The 30-second

npm run build

after writing stubs catches every such bug upfront.

很容易在搭建脚手架后立即调度Agent。请勿这样做。

src/lib/topics.ts

或

src/App.tsx

中的一个拼写错误会导致所有Agent的构建验证失败，你将花费数小时调试四个并行转录内容以查找编排器犯下的一个错误。写入占位符后运行30秒的

npm run build

可提前捕获所有此类错误。

Reusing fact-sheet across very different projects

在差异较大的项目间复用事实表

The fact-sheet is project-specific. If the user runs the skill again on a different codebase, generate a new fact-sheet with a new slug (

/tmp/<project-slug>-factsheet.md

事实表是项目特定的。如果用户在不同的代码库上再次运行此Skill，请使用新的slug生成新的事实表（

/tmp/<project-slug>-factsheet.md

）。

Hand-editing the timestamp out of the path

手动编辑路径中的时间戳

Don't. The timestamp is the provenance — every generation is a snapshot tied to a specific commit. If the user wants a stable URL like

<base>/latest/

, recommend a symlink:

bash

ln -sfn site-<TS> docs/latest

Renaming the directory breaks the link between the docs and the

source.commit

recorded in

metadata.json

请勿这样做。时间戳是来源证明——每次生成都是与特定提交绑定的快照。如果用户想要一个稳定的URL如

<base>/latest/

，建议使用符号链接：

bash

ln -sfn site-<TS> docs/latest

重命名目录会破坏文档与

metadata.json

中记录的

source.commit

之间的关联。

Inventing new accent colors

发明新的强调色

The four accents (

arch

tunnel

shell

auth

) are baked into the CSS at multiple places. Adding a fifth accent means updating

src/index.css

src/lib/topics.ts

accentClasses

helper, and the

Badge

Callout

variant maps. If you have more than four clusters, group them and share accents — don't add new ones at the orchestrator layer.

四种强调色（

arch

、

tunnel

、

shell

、

auth

）已在CSS的多个位置固化。添加第五种强调色意味着需要更新

src/index.css

、

src/lib/topics.ts

中的

accentClasses

助手，以及

Badge

Callout

变体映射。若集群数量超过四个，请将它们分组并共享强调色——不要在编排器层添加新的强调色。

Files in this skill

此Skill中的文件

Path	Purpose
`scripts/check_agent_teams.sh`	Phase 0 preflight
`scripts/scaffold_site.sh`	Phase 4 scaffold copy + install (creates `<base>/site-<TS>/` )
`scripts/write_metadata.py`	Phase 4 metadata.json writer (idempotent, preserves user keys)
`scripts/rebuild_index.py`	Phase 4/6 — rebuilds `<base>/index.html` , the wrapper listing every run
`scripts/serve.py`	Phase 6 — hosts `<base>/` over HTTP and opens it (VS Code Simple Browser when available, else system browser)
`scripts/stop_server.sh`	Stops a server started by `serve.py`
`assets/scaffold/`	Vite app shell + shared components + CONTRIBUTING.md
`references/research-prompt.md`	Phase 3 — research agent prompt template
`references/content-agent-prompt.md`	Phase 5 — content agent prompt template
`references/components.md`	Component API contract (mirrors CONTRIBUTING.md)
`references/templates.md`	topics.ts / App.tsx / page stub templates

路径	用途
`scripts/check_agent_teams.sh`	阶段0预检
`scripts/scaffold_site.sh`	阶段4脚手架复制+安装（创建 `<base>/site-<TS>/` ）
`scripts/write_metadata.py`	阶段4 metadata.json写入器（幂等，保留用户键）
`scripts/rebuild_index.py`	阶段4/6 — 重建 `<base>/index.html` ，即列出所有生成结果的索引页面
`scripts/serve.py`	阶段6 — 通过HTTP托管 `<base>/` 并打开页面（可用时使用VS Code Simple Browser，否则使用系统浏览器）
`scripts/stop_server.sh`	停止由 `serve.py` 启动的服务器
`assets/scaffold/`	Vite应用外壳+共享组件+CONTRIBUTING.md
`references/research-prompt.md`	阶段3 — 调研Agent提示模板
`references/content-agent-prompt.md`	阶段5 — 内容Agent提示模板
`references/components.md`	组件API约定（与CONTRIBUTING.md镜像）
`references/templates.md`	topics.ts / App.tsx / 页面占位符模板

Quick mental model

快速心智模型

Preflight ─▶ Clarify ─▶ Survey ─▶ Research ─▶ Scaffold + stubs ─▶ Dispatch ─▶ Integrate ─▶ Serve
   (1)        (4 Qs)   (clusters) (1 agent)   (orchestrator)     (N agents)   (1 build)    (open)
                                                                 parallel

Each arrow is a phase boundary you should not cross until the previous phase verifies cleanly. The pattern is: do the work that's hard to parallelize sequentially, then explode into a parallel team for the content, then converge back for the integration verify.

预检 ─▶ 明确范围 ─▶ 调研代码库 ─▶ 调研阶段 ─▶ 搭建脚手架+占位符 ─▶ 调度Agent ─▶ 集成 ─▶ 托管
   (1)        (4个问题)   (集群)     (1个Agent)   (编排器)     (N个并行Agent)   (1次构建)    (打开)

每个箭头都是阶段边界，需在前一阶段验证通过后再进入下一阶段。模式是：先按顺序完成难以并行化的工作，然后让内容团队并行工作，最后回归到集成验证阶段。