跳到主要内容

MAINTENANCE

知识库不是一次性产出，是持续运营的资产。本文档定义如何维护这套体系。

一、维护对象总览​

AI 知识体系（纵向，docx）
├── 阶段课程（1-x ~ 4-x）          稳定，半年 review 一次
├── 进阶专题（5-x）                 中频，季度 review
└── 扩展方向（6-x）                 高频（跟随技术变化）

AI 横向能力体系（md）
├── 理论基础（01/02/03/13）         稳定
├── 工作流方法论（04-09）           中频
├── 基础设施层（10-12）             高频
├── 应用新形态（14-16）             极高频（产品形态在变）
├── 持续优化（17-18）               中频
└── 延伸方向（19-20）               高频

不同频率不同维护节奏。

二、四级更新分类​

每次外部世界变化，按影响分级：

Level 1：术语/数字微调（每月）​

例：模型版本号更新、价格变化、新参数名。

  • 工作量：< 30 分钟
  • 流程：直接改 + 同步站点
  • 触发：日常使用中发现

Level 2：新工具/产品（每季度）​

例：新出一个像 v0 / bolt.new 的产品；新框架进入主流。

  • 工作量：1-3 小时
  • 流程：找到相关文档 + 加一段 + 更新对比表
  • 触发：行业重大发布

Level 3：方法论演进（每半年）​

例：新的 Agent 范式、新的安全防御、新的工程模式。

  • 工作量：1-2 天
  • 流程：可能整章重写
  • 触发：业界共识形成（比如 Lethal Trifecta 出现时）

Level 4：体系扩展（每年）​

例：新增整篇文档（如本次新加的 19/20）。

  • 工作量：1-2 周
  • 流程：写新文档 + 更新 README + 更新交叉引用
  • 触发：体系性缺口

三、定期 Review 节奏​

每月（30 分钟）​

  • 跑过去 30 天有重大事件吗？（看 Simon Willison 月报、各家厂商 release notes）
  • 每个文档"核对日期"超过 6 个月？标记。
  • 模型价格、API 参数有变化？批量更新。

每季度（半天）​

  • 行业关键事件复盘
  • 走读 Level 1-2 标记的修改
  • 更新 README 学习路径（如果适用）
  • 检查站点是否能正常构建

每半年（1-2 天）​

  • 完整 review 6-x 扩展方向（变化最快）
  • 重点 review 14-16 应用新形态
  • 评估是否需要新增文档
  • 删除已过时的"未来方向"内容

每年（1-2 周）​

  • 整套体系大盘点
  • 新增文档（按需）
  • 归档过时内容（不删，移到 archive/）
  • 更新核对日期到当前

四、变更流程​

小改动（直接改）​

适用：术语调整、错别字、数字更新。

# 在源目录改
vim "AI 横向能力体系/04 Lethal Trifecta...md"

# 同步到站点
cp "AI 横向能力体系/04 ...md" \
   "agent-docs-site/docs/horizontal-abilities/"

# 提交
cd agent-docs-site
git add . && git commit -m "fix: typo in 04"

中改动（PR）​

适用：章节重写、新增小节。

1. 创建分支：fix/lethal-trifecta-update
2. 改源文件
3. 同步站点
4. 本地构建：npm run build 通过
5. 提交 PR
6. Self-review or 团队 review
7. 合并

大改动（新文档）​

适用：新增整篇。

1. 写源文件 in AI 横向能力体系/
2. 同步到 agent-docs-site/docs/horizontal-abilities/
3. 更新 README.md 文档列表 + 学习路径
4. 更新可能的交叉引用（其他文档"前置"列表）
5. 本地构建测试
6. PR

五、信源订阅清单​

保持知识库新鲜的关键是订阅高质量信源：

必订阅（高信噪比）​

应订阅（行业动态）​

可选（深度）​

  • arXiv AI 板块（论文）
  • 学术会议（NeurIPS、ICML）
  • 各家厂商工程博客深度文章

六、过时检测​

自动化检测（推荐）​

写一个脚本扫描所有文档：

#!/bin/bash
# scripts/check-staleness.sh

echo "=== 核对日期超过 6 个月的文档 ==="
SIX_MONTHS_AGO=$(date -d "-6 months" +%Y-%m-%d)

for f in "AI 横向能力体系"/*.md; do
  date_line=$(grep "核对日期" "$f" | head -1)
  date=$(echo "$date_line" | grep -oP '\d{4}-\d{2}-\d{2}')
  
  if [[ "$date" < "$SIX_MONTHS_AGO" ]]; then
    echo "STALE: $f (核对日期: $date)"
  fi
done

每月跑一次，标记需要 review 的文档。

关键词检测​

某些表述会过时：

"目前最新" → 半年后必过时
"2025 年" → 进入 2027 后要审
"刚发布" → 1 年后过时
"还在 beta" → 持续验证

定期 grep 这些词，重新审视。

七、版本快照​

每年底打一个版本，归档当前状态：

2026年版/
├── AI 横向能力体系-v2026/
└── AI 知识体系-v2026/

好处：

  • 历史可追溯（看一年前你怎么想的）
  • 比较演进
  • 出错可回退

八、不要做的事​

反模式后果
一发现过时就大改改动量太大，频繁失控
想改完美才发布永远发不出
删除"已过时"章节失去历史价值
不留 changelog不知道何时改了什么
站点和源不同步双份维护成本
单人维护，不做文档化人走体系崩

九、changelog 模板​

每个文档开头可加：

---
title: ...
sidebar_position: ...
keywords: [...]
---

> **更新历史**
> - 2026-06-12：初版
> - 2026-09-01：更新模型价格 + 新增 Vercel AI SDK 章节
> - 2026-12-15：年度大 review，重写第三章

# 正文标题

或者集中维护一份 CHANGELOG.md。

十、协作机制​

单人维护​

  • 每月固定时间（比如月底周日）做 review
  • 用日历提醒
  • 信源订阅 RSS / 邮件

团队维护（推荐）​

  • 每个章节有 owner（写在 frontmatter）
  • 季度 review 会议
  • 重大改动 PR + review
  • 错误举报通道
---
title: ...
owner: alice@team.com
last_reviewed: 2026-06-12
---

十一、何时该停止维护​

不是所有内容值得永远维护：

信号处理
主题已被淘汰（如旧框架）归档到 archive/
维护成本 > 价值删除或合并到其他文档
6 个月内无人查看评估是否还需要
与核心定位无关移到其他知识库

健康的知识库会自己减负，不只是积累。

核对日期：2026-06-12