101 lines
5.3 KiB
Markdown
101 lines
5.3 KiB
Markdown
# Section 构建与多 Agent 并行
|
||
|
||
## 铁律：一个 Section = 一个组件文件
|
||
|
||
每个 Section **必须**是独立组件文件，**坚决不允许**把多个 Section 直接写进一个组件。
|
||
|
||
```text
|
||
article/
|
||
Article.tsx # assembler（主 Agent 拥有）：import + 排序各 Section
|
||
sections/
|
||
01-opening.tsx # export function SectionOpening() { return <Section .../> }
|
||
02-context.tsx
|
||
03-mechanism.tsx
|
||
raw-blocks/
|
||
01-token-flow.tsx # 大型 / 复用的 Raw 隔离到这里，被对应 section import
|
||
```
|
||
|
||
- 每个 `sections/NN-*.tsx` 导出一个组件，内部用 `<Section index="NN" title="...">…</Section>`。
|
||
- `Article.tsx` 只做组装：
|
||
```tsx
|
||
import { Article, Hero, Lead, Conclusion } from "reacticle";
|
||
import { SectionOpening } from "./sections/01-opening";
|
||
import { SectionContext } from "./sections/02-context";
|
||
export function ArticleDoc() {
|
||
return (
|
||
<Article toc width="regular">
|
||
<Hero ... /><Lead>…</Lead>
|
||
<SectionOpening />
|
||
<SectionContext />
|
||
<Conclusion>…</Conclusion>
|
||
</Article>
|
||
);
|
||
}
|
||
```
|
||
- 文件级隔离 + reacticle 无裸 CSS（样式全走主题 token）→ 多个 Agent 改不同 section 文件
|
||
**不会互相破坏**。
|
||
|
||
## 章节序号由主 Agent 统一编（避免序号错乱）
|
||
|
||
`Section` / `Subsection` 的 `index` 是**手写字符串**，组件既不自动编号、也不校验——它只会原样显示。
|
||
所以一旦哪个 section 文件写错了序号（典型：并行模式里 subagent 看不到自己在全篇的位置，凭空写出
|
||
"第 8 章下挂一个 5.1"），就会一路漏到成品里。规则：
|
||
|
||
- **全局序号归主 Agent（assembler）所有。** 在 `Article.tsx` 排定最终顺序后，主 Agent 据此把每个
|
||
`Section` 的 `index` 校准成 `01 / 02 / 03 …`，并把每个 `Subsection` 的序号前缀对齐到所属
|
||
`Section`（第 08 章下只能是 `8.1 / 8.2 …`）。
|
||
- **subagent 不自编全局序号。** 主 Agent 在派活时直接告诉它"你是第 `<NN>` 章"，subagent 用这个
|
||
`<NN>` 写 `Section index` 和本节 `Subsection` 的前缀；拿不准就留 outline 给的占位，最终由主
|
||
Agent 统一过一遍。
|
||
- **组装后必校验**：对照 TOC 显示与 `outline.md` 顺序，确认序号连续单调、子节前缀正确（并入终审
|
||
Technical Reviewer 的"章节序号全篇自洽"清单）。
|
||
|
||
## 两种开发模式（Checkpoint 2 由用户选定）
|
||
|
||
第一个 Section 无论哪种模式都先由**主 Agent 完成并验收**（风格锚点）。差异在第 2 个 Section 起：
|
||
|
||
### A · 单 Agent 顺序（默认，最稳）
|
||
|
||
主 Agent 顺序写 `02 → 03 → …`，风格最统一，随时验收。
|
||
|
||
### B · 多 Agent 并行（最快）
|
||
|
||
subagent 各**拥有一个** `sections/NN-*.tsx` 并行开发。**主 Agent 负责合并与稳定性**：
|
||
|
||
- 维护 `Article.tsx` 的 import 与 Section 顺序（唯一组装点，避免冲突），并据最终顺序**统一校准每个
|
||
Section 的 `index` 与各 Subsection 的序号前缀**（见上节"章节序号由主 Agent 统一编"）。
|
||
- 每轮并行结束跑 `npm run typecheck` + `npm run build`，修构建错误。
|
||
- 兜底主题与风格一致（颜色 / 字体 / 间距走 token，气质不跑偏）。
|
||
- 解决重复 / 衔接问题（相邻 section 论点是否承接）。
|
||
|
||
风格在并行下会有轻微差异（这是预期，主题 token 兜底视觉统一）。
|
||
|
||
### 并行 subagent 的 prompt 必须包含
|
||
|
||
```text
|
||
你负责文件 article/sections/<NN>-<id>.tsx，只改这一个文件，导出一个 Section 组件。
|
||
你是全篇第 <NN> 章（这个编号由主 Agent 指定，你看不到自己在全篇的位置，不要自己另编）。
|
||
读取：plan/plan.md 的 Outline 段本节段落 + Brief 段（信息保留比例）+
|
||
source/source.md 本节对应内容 + 选定主题 theme-profiles/<id>.md +
|
||
references/component-policy.md + references/raw-policy.md +
|
||
第一个 section 文件作为“代码风格”参考（不是抄袭对象）。
|
||
硬规则：
|
||
- 一个文件 = 一个 Section 组件；不要碰 Article.tsx 或别的 section 文件。
|
||
- 正文为主体，组件按需（默认核心组件优先），Raw 用 --ra-* token 现写。
|
||
- 符合本节 outline 任务与信息保留比例；与前后节衔接。
|
||
- 序号：<Section index="<NN>">；本节所有 <Subsection> 的序号前缀必须等于 <NN>
|
||
（如 <NN>=08 则小节是 8.1 / 8.2 …），不要从别的章节复制序号。
|
||
- 完工自检对照 references/review-checklist.md 的 Section 清单。
|
||
不要修改 Article.tsx（主 Agent 统一组装与序号校准），不要改主题。
|
||
```
|
||
|
||
## 每个 Section 完工（必走质检 · SubAgent · 消息返回）
|
||
|
||
按硬性质检协议创建 **Section Reviewer** SubAgent，对照清单核查：完成 outline 任务 / 符合
|
||
信息保留比例 / 与前后衔接 / 不过度组件化 / 正文充足 / Raw 与配图有明确目的 / **本节序号
|
||
自洽**（`Section index` 等于 `<NN>`，各 `Subsection` 序号前缀等于 `<NN>`）。
|
||
|
||
**SubAgent 以消息形式返回 pass/fail + 修复点**（pass 一行 OK，fail 列出修复点），**不要写
|
||
`review/section-NN-review.md` 文件**。主 Agent 收到 fail 项后直接修对应 section 文件，再
|
||
汇报本节交付。完整 prompt 模板见 `references/review-checklist.md` 的 Section 段。
|