白泽

把面向人浏览的 Wiki 编译成 Agent 能渐进检索、带来源边界且可持续同步的知识 Skill。创建和更新都必须先完成全量导航盘点，再写入目标目录；不能用搜索结果数量代替完整性验证。

依赖

确定性脚本只依赖 Python 3.10+ 标准库，先用 python3 --version 验证，不需要安装第三方包。缺少兼容 Python 时停止并报告；不要手工替代哈希、原子写入或目录逃逸校验。网页抓取使用当前环境已有的 HTTP、浏览器或官方导出能力，没有固定的付费服务依赖。

工作流

复制并持续更新这份清单：

白泽进度：
- [ ] 1. Scope：确认来源、访问权限、语言与完整范围
- [ ] 2. Map：盘点 Wiki 导航树和预期页面数
- [ ] 3. Capture：逐页转换到临时目录并生成 inventory.json
- [ ] 4. Build/Sync：预演哈希差异，再创建或增量更新 Skill
- [ ] 5. Verify：核对覆盖率、目录树、索引、清单和本地检索
- [ ] 6. Install：安装到当前 Agent；需要时配置自动更新

1. 确定模式、名称与落点

1. 新建时根据 Wiki 的产品名或知识域起一个简短、贴切的 lowercase-hyphen 名称，默认以 -wiki 结尾，例如 qoder-wiki。不要直接使用完整域名、docs、help-center 等泛名。
2. 更新时先定位已有 Skill，读取 references/wiki-manifest.json，沿用名称、来源范围和路径映射；不要把更新做成第二份 Skill。
3. 按 位置与安装规则 选择目标：显式路径优先，其次是当前选中的 Skills 仓库或工作目录；没有选中目录时才直接写入当前 Agent 的 Skills 目录。
4. 若同名目录已存在但没有白泽清单，停止并请用户决定新名称或是否接管，不能覆盖。

2. 盘点并抓取 Wiki

完整阅读 抓取与转换协议，先得到导航树、范围边界和预期页面数，再抓正文。优先使用官方导出、官方源码、llms.txt/站点地图与 Wiki 自身导航；动态页面再使用可渲染的浏览器工具。

所有材料先写到用 mktemp -d 创建的临时目录：

<staging>/
├── inventory.json
├── docs/       # 与 Wiki 导航层级对应的 Markdown
└── assets/     # 可选；承载信息的图片等本地资源

若有页面失败、覆盖数不一致、访问范围不明或正文为空，先重试并修正；仍失败就停止，不得声称“完整转换”，也不得用不完整快照覆盖已有 Skill。

3. 创建或更新

新建 Skill：

python3 <baize-root>/scripts/build_wiki_skill.py \
  --staging-dir <staging> \
  --target-parent <target-parent> \
  --name <product-wiki> \
  --title "<Wiki title>" \
  --source-url "<canonical wiki root>" \
  --description "<包含知识范围和真实触发词的 description>"

更新已有 Skill 时先预演：

python3 <skill-root>/scripts/sync_wiki_docs.py \
  --skill-root <skill-root> \
  --staging-dir <staging> \
  --dry-run

预演无异常后去掉 --dry-run。脚本以规范化 Markdown 的 SHA-256 为准：内容和元数据均未变化时不重写文档、索引或 JSON 清单。发现上游删页或改路径时，默认停止；只有用户明确同意同步删除，或自动更新已获得持续授权，才加 --prune，旧文件会移入 references/.baize-trash/ 而非直接删除。

清单、索引和生成结果的固定结构见 生成 Skill 契约。不得手工伪造哈希或只更新时间戳。