跳转至

insight

第 2 周：B1-B3 收官 + 部署就绪 🎉

本周完成 3 大板块、~20 个文件、~1500 行文档。 最重要的成就：mkdocs --strict 0 warnings 通过 + 部署就绪。

📊 数字

指标 数量
新增 commits 17+
新增 markdown 行数 ~1,500 行（B1 docs + B2 配置 + B3 根文件）
修复 anchor warnings 188（glossary 176 + cross-doc 12）
strict build 状态 0 warnings, exit 0

✅ B1 mkdocs 增强（10/10 全部完成）

# 任务 状态
B1-1 修最后 1 个 anchor warning ✅
B1-2 validation 链接检查插件 ✅
B1-3 mkdocstrings TS 评估 ✅
B1-4 favicon + logo ✅
B1-5 blog 插件 ✅
B1-6 RSS / Atom feed ✅
B1-7 social links ✅
B1-8 中文搜索同义词 ✅
B1-9 requirements-docs.txt ✅
B1-10 GitHub Pages 自动部署 ✅

关键文件： - mkdocs.yml 启用 4 个插件（search / git-revision-date / blog / RSS） - requirements-docs.txt 锁定版本（mkdocs 1.6.1 / material 9.5.49） - deploy-check.sh 部署前 10 步验证 - DEPLOY.md 完整部署流程文档

✅ B2 GitHub 配置（9/9 全部完成）

.github/
├── ISSUE_TEMPLATE/
│   ├── bug.md
│   ├── feature.md
│   └── question.md
├── PULL_REQUEST_TEMPLATE.md
├── CODEOWNERS
├── FUNDING.yml
├── dependabot.yml
└── workflows/
    ├── ci.yml        # 新增：4 个 job（test + build + lint + commit check）
    └── docs.yml      # 已有：build + deploy

CI 流程： 1. test —— 跑 vitest + typecheck 2. build-docs —— mkdocs build --strict 3. lint-md —— pymarkdownlnt 4. check-commits —— 扫描 commit 是否含 AI 署名（自动 reject）

✅ B3 仓库根补 6 个

  • CHANGELOG.md（~130 行）—— 2026-06-04 至今所有变更
  • SECURITY.md（~110 行）—— 报告流程 + Claude Code 商业产品的边界
  • LICENSE（~85 行）—— 双重许可：src/ 归 Anthropic 专有 / learn_doc+docs/ 用 CC BY-SA 4.0
  • CODE_OF_CONDUCT.md（~100 行）—— Contributor Covenant 2.1
  • AUTHORS.md（~95 行）—— 维护者/贡献者/安全致谢
  • .github/FUNDING.yml（~20 行）—— GitHub Sponsor

🐛 修复的坑

1. glossary_addendum.md 176 个 anchor warning

  • 引用了大量 #appstate #react #agent 等内部 anchor
  • 但 glossary.md 没有对应 heading
  • 解决：批量替换 [xxx](#yyy) 为 xxx（去掉链接，保留文字）

2. cross-doc 链接 12 个 warning

  • build/*.md 之间互引 B1-N-X.md（旧命名）→ 实际是 mkdocs-X.md
  • topics/deep-dive-*.md 引 ../../docs/BRIDGE_PROTOCOL.md → 改成 GitHub 绝对 URL
  • docs/MIGRATION_GUIDE.md 引 ../CHANGELOG.md → 改成 GitHub 绝对 URL

3. pip SSL 错误

  • 国内直连 PyPI 报 SSL: UNEXPECTED_EOF_WHILE_READING
  • 解决：自动回退到 mirrors.aliyun.com
  • deploy-check.sh 已内置 fallback

🚀 部署就绪

部署流程（5 步）： 1. 本地改文档 2. 跑 ./deploy-check.sh 3. 看 "✅ 全部检查通过" 4. git add + commit + push origin main 5. GitHub Actions 自动 build + deploy → 1-2 min 后生产 URL 生效

生产 URL：https://dvxiaofan.github.io/cc-claude-code/

🔮 下周计划

  • F2 内嵌内容（blog 持续更新 / changelog / showcase / faq）
  • G1 探索类 grep（TODO / env / as any / console.log 挖掘）
  • D1 部署（push 远端 + 验证 GitHub Pages 真的工作）

📈 累计（本周 + 上周）

  • 总 commits：~50
  • 总 markdown：~6,500 行（含所有 docs/tutorials/topics/walkthrough）
  • 总测试：79（vitest 全过）
  • strict build：0 warnings
  • CI：5 个 GitHub Actions

—— devxiaofan @ 2026-06-06