doc-weaver

name	doc-weaver
version	1.1.0
description	项目文档编织器。基于lat.md格式规范，自动为项目生成覆盖所有模块的知识图谱文档，并用并行子agent做源码级比对验证。当用户说'写文档'、'补充文档'、'生成项目文档'、'document this project'、'weave docs'时触发。适用于AI-first的多项目管理场景——文档主要供AI agent阅读，而非人类。
metadata	{"requires":[]}

doc-weaver v1 — AI-First 项目文档编织器

核心理念: 不是用 lat.md 的工具链，而是用 Claude Code 的 agent 能力，实现他的格式规范和验证逻辑。

文档由 AI agent 生成，由 AI agent 维护，由 AI agent 验证。人类只需在关键决策点给出设计意图。

---

文档格式规范（继承自 lat.md）

项目文档存放在 docs/ 目录下，按类别分目录组织：

目录结构

docs/
  index.md                # 根索引：所有文档的入口点
  project/
    index.md              # [Tier 1] 入口文档：一句话描述 + 模块清单
    architecture.md       # 架构总览：模块依赖关系、数据流向、技术选型
    glossary.md           # 术语表：每个概念在项目中定义且仅定义一次
  modules/
    index.md              # 模块索引
    <module>.md           # [Tier 2] 模块知识文档，每个模块一个文件
    <module>/             # 子模块目录（可选）
      index.md
      <submodule>.md
  schema/                 # [Tier 3] 结构化数据
    <module>.schema.json
  graph.json              # 全模块依赖图

Section ID

每个 section 拥有层次化 ID：file#Heading#Subheading#Subsubheading

• 第一段：项目根相对路径，去掉 .md 扩展名
• 之后每段：各级标题文本，精确链
• 示例：docs/modules/auth#OAuth Flow#Token Refresh
• 根标题（h1）在引用时可省略（解析器自动补全）

Wiki Link 语法

语法	含义
[[target]]	链接到 target.md 文件的根 section
[[target#Heading]]	链接到 target.md 中的特定 heading
[[target|alias]]	带别名的链接
[[src/auth.ts#validateToken]]	链接到源码符号

源码注解

// @lat: [[section-id]]     // TypeScript, JavaScript, Rust, Go, C
# @lat: [[section-id]]      // Python

前文规则

每个 section 必须有前导段落：紧跟在 heading 后的第一段文字，≤250 字符（不计 wiki link 语法），保证搜索摘要的简洁性。

目录索引约定

docs/ 下每个子目录必须有一个同名索引文件（如 docs/modules/modules.md → 改为 docs/modules/index.md），包含该目录所有文件的 wiki link 清单：

# Modules

- [[modules/auth]] — 鉴权模块
- [[modules/database]] — 数据访问层

---

核心工作流

整个流程分为 5 个阶段，按顺序执行。

Phase 0：项目扫描（项目级上下文收集）

在开始写任何文档之前，先扫描整个项目收集上下文：

1. 读取 package.json / Cargo.toml / pyproject.toml / go.mod 获取项目元数据和技术栈
2. 读取 README.md / CLAUDE.md 获取现有项目描述
3. 扫描 src/ 或源码根目录，识别所有顶级模块/包
4. 对每个模块，快速扫描其 exports、关键 types/interfaces、外部依赖
5. 识别 entry points（main、HTTP handlers、CLI commands）

输出：一份项目全景清单，包含模块列表、每个模块的关键符号、模块间依赖关系。

Phase 1：生成 Tier 1 入口文档

生成 docs/ 目录下的索引和入口文件：

docs/index.md — 根索引：

# docs
- [[project/index]] — 项目概述与模块清单
- [[project/architecture]] — 架构设计与模块依赖
- [[project/glossary]] — 术语表
- [[modules/auth]] — 鉴权模块
- [[modules/api]] — API 路由层
- [[modules/database]] — 数据访问层

docs/project/index.md — 项目入口文档（Tier 1，~1K tokens）：

# Project

**Tech Stack**: TypeScript + Node.js + PostgreSQL + Redis
**Architecture Pattern**: Clean Architecture

## Modules

- [[modules/auth]] — 用户鉴权，OAuth 2.0，JWT 管理
- [[modules/api]] — HTTP API 路由与中间件
- [[modules/database]] — 数据访问层，迁移管理
- [[modules/worker]] — 后台任务队列处理
- [[modules/config]] — 配置管理

## Dependency Graph

依赖关系见 [[project/architecture#Module Dependencies]]。

docs/project/architecture.md — 架构总览

docs/project/glossary.md — 术语表

Phase 2：生成 Tier 2 模块知识文档

对 Phase 0 识别出的每个模块，生成一个 markdown 文档到 docs/modules/ 下：

模板：

# 模块名

一句概述：这个模块负责什么、为什么存在。

## Responsibilities

- 核心职责 1
- 核心职责 2

## Key Concepts

### 概念名

概念解释。内部机制概要。

Reference: [[src/module/file.ts#SymbolName]]

### 概念名 2

...

## Dependencies

该模块依赖的其他模块和原因：

- [[modules/database]] — 持久化存储用户数据
- [[modules/config]] — 读取配置参数

## Consumed By

哪些模块使用本模块：

- [[modules/api]] — 通过 service 层调用鉴逻辑
- [[modules/worker]] — 在后台任务中使用

## Error Conditions

可机器解析的错误码和恢复路径（见 [[schema/module.schema.json]]）

关键规则：

• 每个 section 必须有 ≤250 字符的前导段落
• 涉及其他模块的必须用 [[wiki link]]
• 涉及源码符号的必须用 [[src/path#symbol]]

Phase 3：生成 Tier 3 结构化数据

对每个模块，生成机器可读的 JSON schema：

docs/schema/<module>.schema.json：

{
  "module": "auth",
  "version": "1.0.0",
  "exports": [
    { "name": "login", "kind": "function", "params": ["email", "password"], "returns": "Token" },
    { "name": "refreshToken", "kind": "function", "params": ["token"], "returns": "Token" }
  ],
  "dependencies": {
    "internal": ["database", "redis"],
    "external": ["jsonwebtoken"]
  },
  "consumers": ["api", "websocket"],
  "errors": {
    "TOKEN_EXPIRED": { "code": 401, "recovery": "Call refreshToken" },
    "INVALID_CREDENTIALS": { "code": 403, "recovery": null }
  },
  "entryPoints": ["src/auth/service.ts"],
  "configKeys": ["JWT_SECRET", "JWT_EXPIRY"]
}

同时生成 docs/graph.json — 全模块依赖图：

{
  "modules": [
    { "name": "auth", "dependsOn": ["database", "redis"], "usedBy": ["api", "worker"] },
    { "name": "database", "dependsOn": [], "usedBy": ["auth", "api", "worker"] }
  ],
  "entryPoints": ["src/server.ts", "src/worker.ts"],
  "techStack": { "language": "TypeScript", "runtime": "Node.js" }
}

Phase 4：添加源码注解

在源码中添加 @lat: 注解。规则：

1. 对 docs/modules/ 中每个描述了代码行为的 leaf section，在对应源码中添加 // @lat: [[section-id]]
2. 放在对应的函数/类/测试前一行
3. 不要重复——每个 section 对应一个注释
4. 不要在简单 getter/setter 或明显无业务含义的代码上添加

Phase 5：并行源码级比对验证（关键步骤）

这是整个流程的质量保证环节。派出并行子 agent，每个模块一个，做源码级比对。

验证协议

每个验证 agent 的 prompt 模板：

你是 doc-weaver 验证 agent。
你的任务：比对 `docs/modules/<module>.md` 和源代码，找出所有不一致。

请做以下检查：

1. **接口完整性检查**：文档中描述的 exports、函数签名、参数、返回值是否与源码一致？
   - 文档写了但代码没有 → `doc_claim_not_in_code`
   - 代码有但文档没写 → `code_feature_not_documented`

2. **依赖关系检查**：文档中声明的 dependencies/consumers 是否正确？
   - 源码中 import/require 了但文档没提 → 遗漏依赖
   - 文档声明了但源码中没有 import → 过期依赖

3. **错误条件检查**：文档中描述的 error codes 和 recovery 路径是否真实存在？
   - 文档写了某个 error 但源码中从未 throw → 虚构错误
   - 源码中 throw 了某个 error 但文档没记录 → 遗漏错误

4. **行为描述检查**：文档中的业务逻辑描述是否准确反映了源码实现？
   - 文档说"使用 JWT"但源码用 session → 描述错误
   - 文档描述了一个流程但实际代码逻辑不同 → 描述不准确

5. **符号引用检查**：文档中的 `[[src/path#symbol]]` 引用是否都指向真实存在的符号？

输出格式（JSON）：
```json
{
  "module": "auth",
  "verdict": "passed" | "needs_fix" | "failed",
  "issues": [
    {
      "severity": "error" | "warning",
      "category": "doc_claim_not_in_code" | "code_feature_not_documented" | "wrong_dependency" | "incorrect_error" | "behavior_mismatch" | "broken_symbol_ref",
      "docLocation": "docs/modules/auth#OAuth Flow#Token Refresh",
      "codeLocation": "src/auth/token.ts:42",
      "description": "文档声明 refreshToken 返回类型为 Token，但源码返回类型为 { accessToken, refreshToken }",
      "suggestion": "更新文档返回类型为 { accessToken: string, refreshToken: string }"
    }
  ]
}

验证完成后输出 SUMMARY：

• 总问题数
• 按严重程度/类型分类
• 推荐操作：自动修复 / 需人工判断

#### 并行执行

所有模块的验证 agent **同时启动**（使用 Agent 工具的非 background 模式）。

#### 结果汇总 + 修复

汇总所有验证结果后，根据严重程度决定修复策略：

- **error 级别 + 可自动修复**（如符号引用错了、参数名过时）→ 自动修复
- **error 级别 + 需判断**（如行为描述不准确）→ 报告给用户
- **warning 级别**（如遗漏了次要 feature）→ 记录但不阻塞

---

## 触发方式

| 你想干什么 | 怎么说 |
|-----------|--------|
| 🆕 首次生成文档 | `写文档` 或 `weave docs` |
| 🔄 补充/更新文档 | `补充文档` 或 `update docs for <module>` |
| ✅ 验证文档准确性 | `验证文档` 或 `verify docs` |
| 🏗️ 为新模块写文档 | `给 <module> 写文档` |
| 🔗 添加 wiki 引用 | `给 <module> 添加 cross-ref` |

---

## 关键规则

1. **Phase 0 必须先跑**：不要凭已有知识写文档，必须先扫描项目代码获取真实结构
2. **Phase 5 不可跳过**：所有文档生成/更新后，必须做并行源码级验证
3. **Tier 3 结构化数据的生成时机**：在 Phase 2 生成完 markdown 文档后立即生成，保证 schema 反映最新设计
4. **@lat: 注解不冗余**：一个 leaf section 对应一个 `@lat:` 注解，不重复
5. **第一次运行覆盖所有模块**：后续运行只处理变更的模块
6. **Section ID 不可变**：一旦发布，不轻易修改 section ID（wiki link 会断）
7. **docs/project/index.md 是唯一入口**：AI agent 到达项目后首先读 docs/project/index.md，决定加载哪些模块文档
8. **永不自动 commit**：文档生成和验证完成后，将结果报告给用户，由用户决定何时、以什么 message 提交。不允许在流程末尾执行 `git add`、`git commit` 或 `git push`

---

---

## 端到端示例：为 AI agent 准备一个完整的文档体验

编写完成后，项目的文档应该能让一个**从未看过源码的 AI agent** 在几分钟内准确回答以下所有问题。用 glue-engineer 在 doc-weaver 上测试时，Explore agent 仅凭文档（0 行源码）就给出了准确的项目理解。

以下是一个成功的端到端验证流程：

### 验证方法

1. 派出一个 Explore 类型的子 agent，只给它极模糊的提示词（如"帮我看下这个项目是干什么的、怎么用、实现原理"），不指定读什么文件
2. 检查 agent 的报告是否能准确回答：
   - 项目是做什么的（一句话总结）
   - 核心 CLI 用法和技术栈
   - 模块划分和依赖关系
   - 关键设计决策
3. 如果 agent 依赖了自己的知识而不是文档引用 → 文档不够，需要补
4. 如果 agent 漏掉了重要模块 → 文档索引不足，检查 wiki link 覆盖
5. 如果 agent 给出了错误理解 → 文档表述有歧义，需要修正

### 成功指标

| 指标 | 达标标准 |
|------|---------|
| 项目概述 | Agent 能给出准确的一句话总结 |
| CLI 用法 | Agent 能列出主要命令和参数 |
| 架构理解 | Agent 能画出模块依赖关系图 |
| 设计决策 | Agent 能列出 3+ 个关键设计决策 |
| 无需源码 | Agent 未主动读任何 `.py`/`.ts` 等源码文件 |
| 无幻觉 | Agent 所有结论都在文档中有可靠引用 |

### 失败模式

| 现象 | 根因 | 修复 |
|------|------|------|
| Agent 回答"我不确定" | 文档覆盖不足 | 补写该模块的 Tier 2 文档 |
| Agent 说"以 xxx 库为例"但用了自己的知识 | 缺少使用示例 | 在 Project.md 或 README 中添加最小示例 |
| Agent 漏掉某个核心模块 | 索引缺失 | 检查 docs/index.md → docs/project/index.md 的 wiki link 链是否完整 |
| Agent 错误描述实现方式 | 文档行为描述与源码不一致 | Phase 5 验证未通过，修正文档或代码 |