wiki-adapter-prd
何时激活
- 用户提供的文档或 URL 是非 skillwiki 的 PRD 格式，并希望将其捕获到 vault 中。
- 用户提到 CodeStable、RFC、AIDE 或其他结构化设计文档格式。
- 需要把外部规格/计划规范化为 vault 的 raw + concept 结构。
输出语言
开始时运行 skillwiki lang。页面正文使用解析出的语言生成。Frontmatter 键、文件名和结构标记保持英文。
前置阅读
标准四项读取（SCHEMA、index、log，以及适用时的 project context）。
可识别的 PRD 格式
| 格式 | 结构线索 |
|---|---|
| CodeStable | REQ-NNN 需求 ID，## Requirements / ## Architecture 标题 |
| RFC | ## Motivation / ## Proposal / ## Drawbacks 标题 |
| AIDE directives | 特定 YAML frontmatter 键（aide-*） |
| Hermes spec | N1–N18 规范性需求标记 |
| 通用结构化 | 清晰的 ## 章节层级，含需求、决策或设计 |
若格式无法识别，按通用结构化 markdown 处理，并按章节层级映射。
映射策略
原始捕获（逐字）
- 将完整源文档写入 raw/articles/<slug>.md，使用 RawSourceSchema frontmatter（sha256、source_url、ingested、ingested_by: "wiki-ingest"）。
- 若来源是 URL，先运行 skillwiki fetch-guard <url>。
- 运行 skillwiki hash <raw-file> 计算 sha256。
知识提取
将源章节映射到分类型知识页：
| 源章节 | 目标类型 | 说明 |
|---|---|---|
| 需求列表 | concepts/ 或 entities/ | 每个主要需求成为独立页面或复合页面中的一节 |
| 架构决策 | concepts/ | 映射为概念页，标签 [architecture] |
| 动机/上下文 | entities/ | 捕获为描述系统或组件的实体页 |
| 权衡/对比 | comparisons/ | 当来源权衡备选方案时创建对比页；包含 Decision Closeout 块 |
| 行动项/后续步骤 | 跳过 | 不是知识——在项目工作项中跟踪 |
交叉引用处理
- 需求 ID（REQ-NNN、N1–N18）→ 保留为 frontmatter 标签或内联引用。
- 源内内部链接 → 在对应页面存在时转换为 [[wikilinks]]。
- 外部 URL → 在正文中原样保留。
步骤
- 解析 vault 与语言：skillwiki path 和 skillwiki lang。
- 用上述结构线索对输入格式分类。
- 若来源是 URL：运行 skillwiki fetch-guard <url>，然后抓取。
- 敏感内容防护。在写入原始捕获或生成的页面之前，扫描源与生成正文中的实时凭据、访问密钥、令牌、密码、Cookie、bearer 头或私钥。写入前对生成正文做脱敏。若源本身包含实时密钥且需要保持原样，则停止，而不是保留它。
- 写入原始捕获：frontmatter + 完整正文 → raw/articles/<slug>.md。
- 运行 skillwiki hash <raw-file>，嵌入 sha256。
- 按映射策略生成分类型知识页。 对于生成的对比或评估页，正文结尾为：
Decision Closeout
Disposition: no-op | concept | ADR | work-item | evidence-needed Reason: ... Follow-up: ...
仅使用一个 disposition。除非 closeout 明确说明 work-item，否则行动项保留为跳过的项目管理内容。
- 对每个页面：运行 skillwiki validate <page>。若任一失败，停止。
- 写入页面，然后更新 index.md 和 log.md。
来源默认值
- provenance: research（外部 PRD 来源）。
- sources: ["^[raw/articles/<slug>.md]"] 出现在每个生成页面上。
停止条件
- fetch-guard 返回非零。
- 任一页面 validate 返回非零。
- 同一来源的 sha256 已存在（跳过——已收录）。
- 源或生成内容包含未脱敏的实时凭据或其他认证密钥。
禁止事项
- 对 URL 来源跳过 fetch-guard。
- 在所有页面通过 validate 之前写入 index/log。
- 修改已有 raw 文件（N9）。
- 为行动项、时间线或流程步骤自动生成页面——那些属于项目管理，不是知识。
- 将实时凭据、访问密钥、令牌、密码、Cookie、bearer 头、私钥或其他认证密钥写入 vault。