Docs Build

docs-build —— AIWeave docs 独立构建 / 同步入口

> 框架不可变铁律（复用自 [AGENTS.md](../../AGENTS.md) 第 7 条，所有 skill 一致） > 本 SKILL.md 及其 scripts/ / templates/ 等框架文件在"使用本 skill"过程中只读。 > 即便发现 bug / 参数漏传 / 模板缺漏 / 质检误判，也必须立刻停下当前工作流， > 向用户报告问题原文，由用户决定是否开新会话以"维护 nexus-harness 框架"为唯一目标修复。 > 唯一豁免：用户在当前会话明确声明"现在就是来改这个 skill 的"。 > 违反此条 = 边用边改，框架即刻失去"可分发给其他用户使用"的基本属性。

> vendor 不可改铁律（复用自 [AGENTS.md](../../AGENTS.md) 第 7.5 条） > ~/.nexus-harness/aiweave/** 一律只读；本 skill 全程只调 runtime，不改 runtime。

> 业务产物归属铁律（复用自 [AGENTS.md](../../AGENTS.md) 第 7.6 条） > 所有写盘目标必须是 project_path/docs/... 或 project_path/.claude/skills/... 或 project_path/BUILD_STATUS.md； > 写入前必过 assert_write_target.py；非 Go 项目（无 go.mod）整条流程降级。

核心原则

本 skill 不发明 vendor schema。T0 冷启动 dispatch 1 个 aiweave-snapshot 子 Agent 一次性扫描真实代码并写完 19 篇 docs；T1/T2 增量精修继续复用 vendor 标准 skill sync-feature-to-docs，路径与 finish-project 阶段最终同步一致。 所有路径都必须经过 lint_aiweave_invariants.py --check-docs-quality、doc-sync-check 与 docs-build-reviewer 兜底。

与现有 AIWeave 集成的等价关系

| 维度 | finish-project（已落地） | docs-build（本 skill） | |---|---|---| | 写 docs 内容 | invoke_skill dispatch --skill sync-feature-to-docs（git diff） | T0 用 dispatch_snapshot.py（stage=all 单子 Agent 一次性 19 篇）；T1/T2 用 sync-feature-to-docs | | 检查一致性 | invoke_skill dispatch --skill doc-sync-check | 同上 | | 写盘白名单 | assert_write_target.py | 同上 | | 翻 BUILD_STATUS | sync-feature-to-docs 内部完成 | 同上 | | 非 Go 降级 | 跳过 AIWeave 直接归档 | 告知用户不支持后结束 |

差异点：T0 不再把 vendor 增量工具当 whole-codebase 冷启动；T1 缺口补齐仍可用 whole-codebase + scope_filter，T2 增量同步用真实 diff / auto-detect。

状态机

Step 1 — 确定 project_path（优先自动检测）

先自动检测：检查当前工作目录（shell cwd）是否存在 go.mod。

• cwd 存在 go.mod（即当前目录是 Go 项目根）：
• 直接把 cwd 作为 project_path，不询问用户。
• 向用户展示一行确认（不超过一行）：

检测到当前目录 为 Go 项目，将对其构建/同步 AIWeave docs/。

• 进入 Step 2。

• cwd 不存在 go.mod（nexus-harness 本仓库或非 Go 目录）：
• 向用户提问：

`` 请告诉我要构建/同步知识库的业务项目仓库根目录绝对路径： （例：/Users/me/code/my-go-service） ``

• 用户回复后校验路径存在且为目录；不满足则重新 ASK。
• 进入 Step 2。

Step 2 — 调 detect.py 探测项目状态

python3 skills/aiweave-bridge/scripts/detect.py --project_path= --json

读取返回的 aiweave_status：

• non_go → 跳 Step 3a
• T0 → 跳 Step 3b
• T1 → 跳 Step 3c
• T2 → 跳 Step 3d

向用户展示一行状态汇报（不超过两行），然后进入对应分支。

Step 3a — 非 Go 项目降级（终止节点）

向用户输出（一字不改）：

检测结果：当前项目根目录未发现 `go.mod`，AIWeave 仅支持 Go 项目。
nexus-harness 在非 Go 项目上整体降级到 dev_notes 路径，无独立的「提取知识库」入口。
返回主菜单：回复 `nexus` 或 `Agent`。

结束。

Step 3b — T0 冷启动构建路径（all-in-one 单子 Agent）

> 与 prd-to-trd 内置 bootstrap 路径完全对齐：1 个 aiweave-snapshot 子 Agent 在自己的上下文里串行写完全部 19 篇 docs，外层只在末尾跑 1 次 lint + 1 次 reviewer + 1 次 doc-sync-check。 > 禁止把 1 个子 Agent 拆成 B1-B6 六个独立子 Agent 串行——历史日志验证那种做法 = 6× Stage A 冷启动 + 5 道中间闸门 = 慢 2-3 倍且需要多次人工修补。

Step 3b.1 复制骨架

python3 skills/aiweave-bridge/scripts/bootstrap.py --project_path=

读返回值；任何错误立刻停止并报告（铁律：不改 bridge 脚本）。

Step 3b.2 一次性构建共享代码索引（让 snapshot 子 Agent 跳过 Glob 全树）

python3 skills/aiweave-bridge/scripts/build_snapshot_context.py --project=

产出 /.aiweave_snapshot_context.json（gofiles / routergroups / models / controllers / errors / constants / configfiles / rediskeys 索引）。snapshot 子 Agent 必须先读这份 JSON，禁止再 Glob **/*.go 全树。已存在则自动跳过；如代码大改可加 --force 重扫。

Step 3b.3 dispatch aiweave-snapshot 单子 Agent（写 19 篇 docs）

python3 skills/aiweave-bridge/scripts/dispatch_snapshot.py --project=

禁止传 --stage=B1..B6（默认 stage=all）。脚本返回 dispatch_aiweave_snapshot 派发指令包后，主 Agent 必须用 Task 同步阻塞派一个独立上下文子 Agent（subagent_type="aiweave-snapshot"，无注册时 fallback generalPurpose），prompt = task_prompt_template。子 Agent 在自己的上下文里按 vendor docs-spec 19 篇规范一次性写完所有 docs，最后写 /.aiweave_snapshot.json checkpoint 并打印 [snapshot] done → ...。Task 阻塞期间禁止主 Agent 输出任何文字、菜单或暗示。

Step 3b.4 回流验证 + 产物质量 lint（一次性全量）

子 Agent Task 返回后：

# 1) 回流验证
python3 skills/aiweave-bridge/scripts/dispatch_snapshot.py \
  --project= \
  --snapshot_done=true

# 2) 全量 lint（含 BUILD_STATUS 事实对账 + API 规格深度对账）
python3 skills/aiweave-bridge/scripts/lint_aiweave_invariants.py \
  --project= \
  --check-docs-quality \
  --gap-density-threshold=0.30 \
  --gap-density-max=20 \
  --check-build-status-facts \
  --check-api-spec-depth

--check-build-status-facts 会对账 BUILD_STATUS.md 与代码事实：

• 路由组（router/**/*.go 真实 .Group() 调用 vs BUILD_STATUS 表格里以 / 开头的路径）
• .claude/skills/（实际目录 vs BUILD_STATUS 是否还在写"尚未创建/待启用"）
• snapshot.stub_only（标为 stub 的文件实际有效行数）

--check-api-spec-depth 会扫 docs/api/audience_*_interfaces.md，按 #### METHOD path 切接口章节， 统计"缺代码块 + 缺字段表 + 字符

dispatch_reviewer 内部先跑机械评审（秒级）：
- `action=mechanical_accept` → 直接进入 Step 3b.6，不派 subagent；汇报标注 `mechanical_only=true`。
- `action=dispatch_docs_build_reviewer` → 必须用 Task 同步派 `docs-build-reviewer` 子 Agent 深度复核；`decision=repair` → 通知 snapshot 子 Agent 定点修复，再回到 Step 3b.4 复检；`accept` → 进入 Step 3b.6。
- 强制 subagent 复核可加 `--no-mechanical-first`。

**Step 3b.6 doc-sync-check 全量校验**

python3 skills/aiweave-bridge/scripts/invoke_skill.py dispatch \ --skill=doc-sync-check \ --project= \ --extra-inputs='{"scope":"all"}'

按报告：全绿 → 进入 Step 4；有 🔴 → 派 snapshot 子 Agent 定点修复，再复检；不得直接声明"完成"。

### T1/T2 docs 写入规则

加载 `vendor_skill_md` 路径下的 `sync-feature-to-docs/SKILL.md`，严格按 vendor 规则逐篇填充 docs：
- 禁止发明字段、禁止改字段顺序、禁止合并多个职责进同一篇
- 每篇写盘前过 `assert_write_target.py`，每篇写盘后过 `lint_aiweave_invariants.py --check-docs-quality --gap-density-threshold=0.30 --gap-density-max=20`；T1/T2 全量收尾再加一次 `--check-build-status-facts --check-api-spec-depth` 对账
- vendor 字段在代码里找不到对应实现 → 在 docs 顶部插 ``，**不得**自行调整模板
- 贴 `` 前必须在业务代码里 grep 至少 2 次确认确无
- 严禁裸 `待补充` / `TODO` / `FIXME` / `XXX`，所有空白必须用 `` 包裹并附理由
- 每篇 md 完成后报告 gap 密度，> 30% 自我拒收重做

### Step 3c — T1 补齐缺口路径

**Step 3c.1 展示 missing_specs（ASK）**

把 detect.py 返回的 `missing_specs` 列表逐行展示给用户：

当前项目已有部分 docs/，但以下篇章缺失：

1. docs/
2. docs/

...

[1] 全部补齐 [2] 跳过个别（请告诉我编号，用逗号分隔） [3] 取消本次构建

请回复编号。

- 用户选 `1` → `scope_filter = `
- 用户选 `2` 并给出跳过编号 → `scope_filter = missing_specs - 跳过项`
- 用户选 `3` → 结束

**Step 3c.2 dispatch sync-feature-to-docs（合成 diff + scope_filter）**

python3 skills/aiweave-bridge/scripts/invokeskill.py dispatch \ --skill=sync-feature-to-docs \ --project= \ --extra-inputs='{"featureid":"aiweave-t1-fill","diffmode":"whole-codebase","scopefilter":[...],"prompt_hint":"贴 前必须在业务代码里 grep 至少 2 次确认确无；严禁裸 待补充/TODO/FIXME/XXX；每篇 md 完成后报告 gap 密度，>30% 自我拒收重做。"}'

**Step 3c.3** 按 instruction 填充缺失篇章，与 3b.3 规则一致。

**Step 3c.4** dispatch doc-sync-check 验证；与 3b.5 一致。之后按缺失篇章逐篇派 `docs-build-reviewer`，blocking 则修复后复检。

### Step 3d — T2 检查 / 增量更新路径

**Step 3d.1 dispatch doc-sync-check（scope=all）**

python3 skills/aiweave-bridge/scripts/invoke_skill.py dispatch \ --skill=doc-sync-check \ --project= \ --extra-inputs='{"scope":"all"}'

按 doc-sync-check 规则跑 7 维度检查，收集结果。

**Step 3d.2 分支判断**

- 报告零 🔴 / 零 🟡 → 向用户输出：

  ```
  ✅ 当前 docs/ 与代码完全一致，知识库已是最新，无需同步。
  ```

  进入 Step 4。

- 报告含 🔴 / 🟡 → 进入 Step 3d.3。

**Step 3d.3 展示差异清单 + 询问是否同步（ASK）**

按维度逐条展示差异（建议每维度最多 5 条，超出折叠为「另有 N 条」），询问：

检测到上述差异。是否执行 sync-feature-to-docs 同步？

[1] 是，按 auto-detect diff_mode 同步（让 vendor skill 自行扫 git diff origin/main...HEAD） [2] 否，仅展示差异，不写盘

- 用户选 `1` → 进入 Step 3d.4
- 用户选 `2` → 进入 Step 4（结束语带"已展示差异，未同步"）

**Step 3d.4 dispatch sync-feature-to-docs（auto-detect）**

python3 skills/aiweave-bridge/scripts/invokeskill.py dispatch \ --skill=sync-feature-to-docs \ --project= \ --extra-inputs='{"featureid":"aiweave-t2-sync","diffmode":"auto-detect","prompthint":"贴 前必须在业务代码里 grep 至少 2 次确认确无；严禁裸 待补充/TODO/FIXME/XXX；每篇 md 完成后报告 gap 密度，>30% 自我拒收重做。"}'

**Step 3d.5** 按 instruction 执行同步，规则同 3b.3。

**Step 3d.6** dispatch doc-sync-check 复检；与 3b.5 一致。之后对变更篇章派 `docs-build-reviewer`，blocking 则修复后复检。

### Step 4 — 完成汇报（终止节点）

向用户输出（按分支选合适的措辞）：

- T0：`已完成 AIWeave 冷启动构建。新建 docs/ 篇章  份，BUILD_STATUS 模块  个。`
- T1：`已补齐  篇缺失 docs/。`
- T2 已同步：`已同步差异并通过复检；docs/ 与代码当前一致。`
- T2 已是最新：`docs/ 已是最新，未做任何写盘。`
- T2 用户拒绝同步：`已展示差异清单，未执行写盘。下次再调用本入口或在 finish-project 阶段会重新同步。`

结束语：`返回主菜单：回复 nexus 或 Agent。`

## 全局约束（贯穿所有 Step）

1. **逢 ASK 必停**：Step 1 / 3c.1 / 3d.3 必须真等用户回，不替用户选默认。
2. **路径白名单**：所有写盘必经 `assert_write_target.py`；任何尝试写 nexus-harness 仓库或 vendor 的路径立即报错停机。
3. **vendor 字段规范**：所有 docs 写入严格按 vendor SKILL.md 字段顺序与 schema；偏离即视为反 AIWeave 作弊，必须回滚。
4. **不与 finish-project 抢工**：本 skill 不更新 `context.json.pending_docs_sync[]`；finish-project 自有 docs 收尾逻辑，路径不重叠。
5. **必须引入 reviewer**：T0 每个 B 阶段、T1/T2 每批变更篇章都必须派 `docs-build-reviewer`；blocking 决策走 repair，禁止主 Agent 自评放行。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [xurb-nexus](https://github.com/xurb-nexus)
- **Source:** [xurb-nexus/nexus-harness](https://github.com/xurb-nexus/nexus-harness)
- **License:** Apache-2.0
- **Homepage:** https://xurb-nexus.github.io/nexus-harness/

Install and usage instructions live in the source repository linked above.