---
name: te-wiki-synthesize
description: 基于 ~/.ae-tracking/wiki/te-docs/raw/ 和 index.md 综合输出主题页到 synthesis/。触发词：综合文档、wiki 整理、synthesize docs、生成综合页。走 load-index → propose-topics → dispatch-subagents → collect → log → commit 六步。
---

# te-wiki-synthesize

## 何时触发

由其他 skill（如埋点专家 skill）或用户显式调用，目标是将散落在 `~/.ae-tracking/wiki/te-docs/raw/` 下的 219 个原始页面归纳为若干主题综合页，输出到 `~/.ae-tracking/wiki/te-docs/synthesis/`。

---

## Phase 1 — Load Index

读 `~/.ae-tracking/wiki/te-docs/index.md`，了解 raw/ 的页面覆盖与分类。

**禁止**直接读 `raw/` 目录——raw 文件量巨大，直接读会污染主 agent 上下文。主 agent 在整个流程中仅读 `index.md`，不触碰 `raw/` 或 `synthesis/` 正文。

---

## Phase 2 — Propose Topics

基于 index 内容动态归纳 3–8 个综合主题。参考方向（按 index 实际覆盖决定，非固定）：

| 建议主题 slug | 方向描述 |
|---|---|
| `sdk-selection` | SDK 选型矩阵（客户端 vs 服务端 vs 批量导入） |
| `js-sdk-cheatsheet` | JS / H5 / 小程序 SDK 速查 |
| `mobile-sdk-cheatsheet` | iOS / Android / Unity SDK 速查 |
| `log-ingestion` | 日志接入方案对比（logbus / datax / kafka） |
| `restful-api-reference` | RESTful 接口速查 |
| `debug-checklist` | Debug 与数据校验流程 |
| `identity-system` | 用户 ID 体系 / 属性体系 |

每个主题需关联至少 3 个 raw 源文件；否则合并到相近主题或放弃。确定主题列表后向用户展示（一行一条），等待 `ok` 或调整意见后再进入 Phase 3。

---

## Phase 3 — Dispatch Subagents（并行）

每个主题派发一个 subagent，每批并行 3–4 个（避免 token 风暴）。

### Subagent 入参

```json
{
  "topic": "<主题名（中文）>",
  "rawPaths": ["~/.ae-tracking/wiki/te-docs/raw/xxx.md", "..."],
  "outPath": "~/.ae-tracking/wiki/te-docs/synthesis/<slug>.md"
}
```

### Subagent 执行步骤

1. 读 `rawPaths` 指向的所有文件
2. 写综合页到 `outPath`，格式要求见下方「综合页格式」
3. 返回 `{ status: "ok"|"fail", title: string, outPath: string, reason?: string }`
   **不回传正文**（主 agent 只看标题和文件名）

### 综合页格式

```markdown
---
topic: <主题名>
sources:
  - raw/xxx.md
  - raw/yyy.md
generated: <ISO date, e.g. 2026-04-15>
---

# <主题名>

<正文>
```

正文规则：

- **选型 / 决策类**主题：用 Markdown 表格对比各方案
- **速查 / API 类**主题：代码片段 + 简短说明
- 每个论点必须追溯到某个 raw 文件，行内标注 `[[raw/xxx.md]]`
- 不引外网 URL；如需外链，只引 raw 文件 frontmatter 里的 `sourceUrl`
- 每篇综合页至少引用 3 个不同 raw 源；不足 3 个的主题不单独成文

---

## Phase 4 — Collect Results

主 agent 汇总各 subagent 返回值：

- `ok`：记录 `title`、`outPath`、源文件数
- `fail`：记录 `reason`，提示用户是否跳过或重试

主 agent **不读** synthesis 正文，仅依据标题和文件名判断结果。

---

## Phase 5 — 追加日志

在 `~/.ae-tracking/wiki/te-docs/log.md` 末尾追加一个段落：

```markdown
## Synthesis (<ISO date>)

| 主题 | 文件 | 源文件数 |
|---|---|---|
| <title> | synthesis/<slug>.md | <n> |
| ... | ... | ... |
```

---

## Phase 6 — Commit

```bash
git add ~/.ae-tracking/wiki/te-docs/synthesis ~/.ae-tracking/wiki/te-docs/log.md
git commit -m "feat(wiki): synthesis pages for <N> topics"
```

---

## 约束

- `synthesis/*.md` 只写不读——subagent 写完即 exit，不做反复迭代
- 主 agent 全程不读 `raw/` 或 `synthesis/` 正文
- 禁止修改 `raw/` 下任何文件
- 每篇 synthesis 至少引用 3 个 raw 源；不足则合并或跳过

---

## 产物示例

```
~/.ae-tracking/wiki/te-docs/synthesis/
├── sdk-selection.md
├── js-sdk-cheatsheet.md
├── mobile-sdk-cheatsheet.md
├── log-ingestion.md
├── restful-api-reference.md
├── debug-checklist.md
└── identity-system.md
```
