知识库与 Wiki

Wiki 从规划到治理（skill-flow-block）

Agent 搭库时先定导航维度（角色 / 系统边界 / 生命周期），再统一模板字段与链接规则，最后把复审与外链检查接进节奏；主顺序可按下示意对齐团队仪式。

  [ 定读者与边界：开发 / 运维 / 支持 或 按系统域切分 ]
                    │
                    ▼
              [ 画顶层导航 + 每空间 owner ]
                    │
                    ▼
         [ 页面模板：摘要 / owner / last_reviewed / 标签 / 相关 ADR·Runbook ]
                    │
                    ▼
              [ 交叉链接：Canonical 页 + 禁止长期多份矛盾副本 ]
                    │
                    ▼
         [ 检索：标题可预测 + 同义词表 + 工单/IM 词条互链 ]
                    │
                    ▼
              [ 治理：僵尸页扫描 / 外链失效 / 重大流程必改 wiki ]
                    │
                    ▼
           [ 迁移：URL 映射表 + 重定向 + 搜索索引回填 ]

Wiki 目录结构设计

顶层导航按读者角色或按系统边界拆分；每页顶部用两三句说明受众与前置知识，降低误入率。推荐目录结构：

# 推荐的 Wiki 顶层目录结构（按读者角色 + 系统域混合）

wiki/
├── getting-started/          # 新成员入口
│   ├── README.md             # "从这里开始"总入口
│   ├── local-setup.md        # 环境搭建（→ 链接到各仓库 README）
│   └── onboarding-checklist.md
│
├── engineering/              # 开发者文档
│   ├── adr/                  # Architecture Decision Records
│   │   ├── README.md         # ADR 索引与格式说明
│   │   └── 0042-postgres-events.md
│   ├── api/
│   │   └── payment-service-api.md
│   └── guides/
│       ├── code-review.md
│       └── release-process.md
│
├── operations/               # 运维文档
│   ├── runbooks/             # 按服务分组
│   │   ├── README.md         # Runbook 索引
│   │   ├── payment-svc/
│   │   └── user-svc/
│   ├── oncall/               # 值班相关
│   │   ├── rotation.md       # 轮值表
│   │   └── escalation.md     # 升级路径
│   └── postmortems/          # 按年/月存档
│
├── architecture/             # 系统设计
│   ├── overview.md           # 系统全貌
│   └── service-dependencies.md
│
└── support/                  # 支持团队文档
    ├── billing-faq.md
    └── customer-escalation.md

Wiki 页面元数据标准模板（每页顶部必须包含）：

---
title: "数据库连接池耗尽处理 Runbook"
owner: "@sre-team"
last_reviewed: "2024-03-20"
review_cycle: "quarterly"   # monthly / quarterly / annually
status: "active"             # active / outdated / archived
tags: [runbook, database, postgresql, oncall]
related:
  - ../adr/0042-postgres-events.md
  - ../../operations/oncall/escalation.md
audience: "L1 on-call engineers"
prerequisites: "kubectl access to prod cluster"
---

## 概述
（2-3句说明：这页解决什么问题，目标读者，前置知识）

文档所有权与维护规则：

# 文档所有权规则（在团队 Wiki Guidelines 中固化）

## 每页必须指定 owner
- owner 负责：内容准确性、定期复审、响应「内容有误」反馈
- 团队离职时：owner 字段必须在同一 PR 中更新

## 定期复审周期
| 文档类型 | 复审周期 | 触发复审的事件 |
|----------|----------|----------------|
| Runbook | 每季度 | 事故后必复审 |
| ADR | 实现后 6 个月 | 架构重大变化 |
| 入职文档 | 每半年 | 工具链变更后 |
| API 文档 | 随代码变更 | 接口变更时 |

## 僵尸页检测（CI 或定期脚本）
# 查找 last_reviewed 超过 180 天的页面
grep -r "last_reviewed:" wiki/ \
  | awk -F'"' '{print $2, $1}' \
  | awk '$1 < "'$(date -d '-180 days' +%Y-%m-%d)'"' \
  | sort

检索、同义词与示例树

为高频口语与正式名维护同义词（如「网关」「API Gateway」指向同一 Canonical）；标题与首段包含团队常用检索词，便于 Agent 与人类搜索一致命中。

内容质量标准与搜索优化

内容质量判断标准——好文档 vs 差文档：

# 好文档 vs 差文档 判断清单

## 好文档具备（全部满足才算）：
✅ 开头两句说清：受众是谁、解决什么问题
✅ 步骤可执行：有命令、有预期输出、有失败处理
✅ 有 owner 和 last_reviewed 日期
✅ 外链有效（定期检查）
✅ 与相关文档有双向链接（从这里可以跳到哪，谁链接到这里）
✅ 搜索友好：标题包含用户真实搜索词（"数据库慢"而非"DB Performance Issue"）

## 差文档特征（任一出现需修订）：
❌ 只有标题和"待补充"
❌ 步骤缺乏具体命令（"检查一下配置"）
❌ last_reviewed 超过 180 天无更新
❌ 所有外链 404
❌ 与另一页内容矛盾（两份"真实文档"）
❌ 标题使用团队内部缩写（外部新成员不明白）

治理：定期僵尸页扫描、外链失效检查、与 Slack/工单的关键词条目互链；重大流程变更必须更新对应 wiki 而非只口头同步。

• 权限：敏感段落在独立空间，避免与公开文档混库。
• 重复：Canonical 页 + 短链别名，禁止多份矛盾副本长期并存。
• 迁移：工具切换时的 URL 映射与重定向清单。

SKILL 与页面元数据模板

---
name: knowledge-base-wiki
description: 规划 Wiki 信息架构与页面模板
model: claude-sonnet-4-5
---

# 目录结构原则
structure:
  top_level: [getting-started, engineering, operations, architecture, support]
  owner_per_section: true
  canonical_pages_only: true  # 禁止多份矛盾副本

# 每页元数据必含
page_metadata:
  required: [title, owner, last_reviewed, status, tags, audience]
  review_cycles:
    runbook: quarterly
    adr: 6months-after-impl
    onboarding: biannual
    api: on-change

# 内容质量门禁
quality_gates:
  - 开头说明受众与解决的问题
  - 步骤包含命令和预期输出
  - 外链有效（CI 检查）
  - last_reviewed 不超过 180 天

# 搜索优化规则
search_optimization:
  - 标题包含用户真实搜索词（中英文同义词）
  - tags 字段包含别名（如 "数据库" "database" "DB"）
  - 高频术语的 Canonical 页使用同义词重定向