blog-demo · 规划

仓库文档与网站同步规划

两个仓库的文档分层、公开路由、私有白名单导出与验证边界。

状态
已完成
最后核对
源码修订
e0d3baa2

仓库文档与网站同步规划

状态：已完成；仓库文档统一从“兴趣书房 → 代码”发现，详情路由保持稳定。本轮没有触发生产部署。

已确认决定：沿用复数目录名；ai-infra 仅导出显式白名单且通过脱敏审计的快照。根据上线前复核意见，仓库文档不再作为全站一级“文档库”，统一收进“兴趣书房 → 代码”的工程文档区；/docs/... 只承担稳定详情链接。

背景

blog-demo 的文档已经出现 archive、operations、plans、releases 的雏形，但顶层仍散落着内容维护、开发流程、Studio 和股票复盘说明，早期迁移资料也单独占用 migration/。ai-infra 的说明、运维手册、实验记录和公网 Edge 资料则分布在仓库根目录、deploy/ 与各个 demo 中。

本轮把两个仓库统一成四类文档，并让可公开部分直接进入网站的文档库。Markdown 只在所属仓库维护一份；网站展示由构建工具读取或由脱敏导出流程生成，不再人工复制第二份。

目标

  • 两个仓库都以 docs/archive、docs/operations、docs/plans、docs/releases 作为唯一文档分类入口。
  • archive 保存仓库说明、模块说明、已经完成且仍有参考价值的架构背景。
  • operations 保存开发与运维手册、部署步骤、故障复盘和踩坑记录。
  • plans 保存整体架构规划和子模块规划，并明确草案、已批准、已完成或已废弃状态。
  • releases 只保存版本准备、验收和发布记录，不进入公开网站。
  • 网站在“兴趣书房 → 代码”页展示工程文档，不把运维手册和规划混进普通博客时间线；文档可以被站内搜索、稳定链接和关联入口找到。
  • 私有 ai-infra 原文继续留在私有仓库；公开站只接收经过白名单选择和脱敏审计的生成快照。

非目标

  • 不把仓库文档改写成一批零散博客文章。
  • 不把 docs/releases、真实凭据、内网地址、登录账号、宿主机私有路径、设备清单、未公开拓扑、运行日志或实验原始输出发布到网站。
  • 不在普通 Git 提交后自动部署生产；文档变更仍服从现有版本和内容发布边界。
  • 不借此迁移 Astro、引入独立 CMS 或维护第二套手写 Markdown。
  • 不删除 Git 历史；文件移动使用 git mv，历史仍可追溯。

目录约定

沿用仓库已有的复数目录名，避免把已经存在的 operations、plans、releases 再整体改名：

docs/
├── README.md
├── archive/
│   ├── repository/
│   └── modules/
├── operations/
│   ├── development/
│   ├── deployment/
│   └── incidents/
├── plans/
│   ├── architecture/
│   └── modules/
└── releases/
    ├── README.md
    └── vX.Y.Z.md

第二层按内容规模按需创建，不为只有一篇文档的主题制造空目录。docs/README.md 是仓库内总索引，同时也是公开文档库的分类说明。

blog-demo 初步迁移映射

现位置 目标分类 处理原则
docs/archive/2026-08-27-content-architecture-design.md archive/repository/ 保留为已完成架构背景
docs/content-guide.md archive/modules/content-model.md 内容模型与字段说明，不作为日常运维手册
docs/editorial-edition.md archive/modules/editorial-edition.md 已落地的编选版说明；未完成事项拆回计划
docs/development-workflow.md operations/development/workflow.md 开发、验证与发版边界
docs/maintenance.md operations/development/maintenance.md 依赖、内容和站点维护手册
docs/operations/ecs-static-runbook.md operations/deployment/ecs-static-site.md 生产手册；公开前移除现场值和私密拓扑
docs/migration/ecs-bootstrap-record.md operations/incidents/ecs-bootstrap.md 已发生的迁移与踩坑记录
docs/migration/repository-readiness.md operations/deployment/repository-readiness.md 上线前检查清单
docs/migration/plan.md plans/architecture/ecs-migration.md 历史规划，标记完成状态
docs/plans/v1-production-edge.md plans/architecture/production-edge.md 保留决策与验收边界
docs/studio-remote-editing-plan.md plans/modules/studio-remote-editing.md Studio 总体规划
docs/studio-roadmap.md plans/modules/studio-roadmap.md 子模块路线图
docs/stock-review/README.md 拆分到 archive/modules/stock-review.md 与 operations/development/stock-review.md 稳定契约和每日操作分开，避免模块说明被步骤淹没
docs/releases/* releases/ 原位保留，仅更新内部链接，不公开
docs/migration/README.md 合并进 docs/README.md 完成索引迁移后删除旧目录

最终映射在实施分支里逐篇阅读后确认；不能只按文件名机械移动。若一篇文档同时包含稳定说明和临时操作，优先拆成两个有明确职责的文档，并保留相互链接。

ai-infra 初步迁移映射

现位置 目标分类 处理原则
README.md、AI学习路线.md archive/repository/ 仓库入口与学习背景；公开版去除设备和私有连接信息
各 demos/*/README.md archive/modules/ 每个模块一份稳定说明
操作手册.md operations/deployment/ 只在私有仓库保留完整值，网站使用脱敏快照
配置与脱敏规范.md operations/development/ 作为跨模块维护规范，可生成公开版
deploy/public-edge/README.md operations/deployment/public-edge.md 公开版只保留通用架构和安全边界
demos/eval-lab/实验记录-*.md operations/incidents/eval-lab/ 作为实验踩坑与复盘；公开前核对数据来源和机器信息
demos/eval-lab/runs/*.md 默认不公开，必要时归 operations/incidents/eval-lab/runs/ 原始运行结果可能含模型、路径和环境信息
deploy/public-edge/plan.md plans/architecture/public-edge.md 公网入口规划
尚未形成文档的模块规划 plans/modules/ 后续按模块补充，不从 CLAUDE.md 自动生成
未来版本记录 releases/ 私有保存，不同步网站
根目录和 demo 中的 CLAUDE.md 不直接迁入公开文档 属于代理上下文；提炼稳定规则到仓库说明或 AGENTS.md，不当作读者文档发布
网关信息.md 私有归档或删除前审计 名称和内容都提示可能包含真实拓扑，默认禁止公开

ai-infra 的最终分类必须在它自己的独立分支和 worktree 中完成，并先运行敏感信息审计。由于它是私有基础设施仓库，不能采用“除 release 外一律原样公开”的默认值。

网站同步设计

公开信息结构

  • 在 /interests/coding/ 增加带稳定锚点 #repository-docs 的“工程文档”区，按“归档 / 运维 / 规划”展示；release 不出现在构建输入中。
  • “代码”页继续以技术文章为主。工程文档作为同一兴趣主题下的第二组内容出现，不伪装成博客文章，也不挤占文章分页。
  • 全站菜单、页脚和搜索推荐不再提供独立“文档库”入口；需要浏览文档时统一进入“兴趣书房 → 代码”。
  • 文档路由使用稳定的显式 slug，不直接依赖磁盘相对路径。后续移动分类时可以保留 URL。
  • 文档页展示所属仓库、分类、状态、最后核对日期和源码修订；规划文档必须醒目标明“草案 / 已批准 / 已完成 / 已废弃”。
  • 文档参与全站搜索，但不进入普通博客列表、RSS 和首页“最近文章”，避免再次制造没有上下文的碎片文章。
  • 公开文档沿用现有阅读版式、代码高亮、亮暗主题与无脚本可读能力，不另起一套后台风格。

单一来源

  • blog-demo/docs：Astro 构建直接读取仓库 Markdown；用元数据清单排除 releases 和明确的私有文档，不复制到 src/content/essays。
  • ai-infra/docs：私有仓库维护原文和同目录发布元数据；导出脚本只处理显式 publish: true 的条目，执行结构化脱敏和敏感信息审计后生成公共 Markdown artifact。
  • 导出 artifact 进入 blog-demo 的生成目录并标注来源提交。该目录可追踪但不可手改；更新由受审工作流或本地发布脚本完成。
  • 如果原文不能可靠自动脱敏，则维护一段可公开摘要字段，而不是复制整篇手写公开版。摘要仍和原文元数据放在同一个源文件中。

公开白名单和脱敏

blog-demo 文档因仓库本身公开，可默认进入文档库，但 releases、包含 visibility: private 的文档和敏感审计命中的文件必须排除。ai-infra 一律默认私有，仅显式白名单可导出。

导出至少拒绝以下内容：

  • secret、token、Cookie、私钥、公钥指纹和带凭据 URL；
  • 内网 IP、SSH 用户名、家庭设备名、宿主机真实目录与未公开端口映射；
  • ACR 完整私有地址、镜像摘要、运行日志、备份位置与恢复材料；
  • 未脱敏的公网管理地址和能拼出私有拓扑的组合信息。

公开站可以保留已经公开的域名、开源技术选择、抽象端口角色和通用故障结论，但不应为了“文档完整”牺牲基础设施边界。

兼容与迁移

  • 全仓更新 Markdown 链接、源码注释、测试、CI path filter、脚本默认路径和 AGENTS.md 引用。
  • 保留所有 /docs/<slug>/ 详情路由，避免破坏已发布链接、搜索索引和外部引用。
  • 原 /docs/ 首页改为跳转到 /interests/coding/#repository-docs，不再维护第二份分类首页；跳转必须兼容根路径部署和无脚本访问。
  • 文档详情页的面包屑和分类返回链接改指向“代码 → 工程文档”及其分类锚点。
  • 保留现有 /blog/ecs-migration-* 到建站长文的跳转，不把它们重新拆回零散博客。
  • 新文档 URL 从第一版起使用稳定 slug；后续文件移动通过 redirect map 兼容。
  • GitHub 文件旧链接无法由 Astro 重定向，实施提交中提供清楚的 docs/README.md 总索引，并在发布说明中记录映射。
  • Studio 需要支持文档元数据和预览时另立子计划；本轮先保证公开站构建与仓库维护，不把文档编辑权限扩到远程 Studio。

风险

  • 私有资料泄漏：ai-infra 必须默认拒绝公开，审计失败即停止生成和发布。
  • 链接大面积失效：移动前生成引用清单，移动后运行 Markdown 链接测试和构建产物路由检查。
  • 文档被误当成最新事实：每篇显示状态和最后核对日期；历史计划不能包装成当前运行状态。
  • 搜索与字体膨胀：文档进入 Pagefind，但代码和运维长文不应自动扩大标题字体字表；记录构建大小与搜索索引增量。
  • 内容发布边界扩大：公开文档变更是否允许走 Studio 快速发布需单独评审；默认仍走稳定版本，不直接放宽现有 allowlist。
  • 跨仓自动化耦合：ai-infra 导出失败不能阻断私有基础设施日常维护，也不能让公共 CI 持有读取整个私有仓库的凭据。

已确认决定

  1. 沿用 archive / operations / plans / releases 这四个现有英文复数目录名，不新建单数 operation / plan / release。
  2. 上线前复核否决独立 /docs/ 一级入口，改为收进“兴趣书房 → 代码”。
  3. ai-infra 采用“默认私有、显式白名单、脱敏 artifact”规则；并非所有非 release 原文都会逐字公开。

验收标准

  • 两个仓库的受管文档只存在于四个分类目录，根目录只保留仓库入口和代理指令等必要文件。
  • 每篇文档可从仓库总索引到达，内部链接检查无断链。
  • blog-demo 的 archive、operations、plans 文档在“代码”页的工程文档区可浏览，并拥有稳定公开详情路由；搜索、直接访问和无脚本阅读正常，releases 构建产物中不可见。
  • 全站菜单和页脚不再出现独立“文档库”；访问 /docs/ 会进入 /interests/coding/#repository-docs，已有 /docs/<slug>/ 链接保持有效。
  • ai-infra 的完整私有文档没有进入 blog-demo Git 历史、构建日志或 artifact；公开快照能追溯源提交并通过敏感信息审计。
  • 普通博客列表、RSS 和首页最近文章没有被仓库文档刷屏。
  • Astro check、单元测试、根路径构建、文档链接测试、Edge 浏览器关键路由和相关视觉基线通过。
  • 两个仓库分别检查完整 diff、提交和合并；普通提交不自动部署生产。

实施分支与提交分组

用户批准后，先分别 fetch 并确认两个仓库 canonical main 与主工作树干净，再创建独立 worktree：

  1. docs: classify blog repository documentation
  2. feat: publish repository documentation in coding interest
  3. test: cover documentation routes and privacy boundaries
  4. docs: classify private infrastructure documentation
  5. feat: export sanitized infrastructure documentation
  6. docs: record documentation migration and maintenance rules

两个仓库分别评审和验证；先完成私有仓库的分类与脱敏导出契约，再接入公开站，避免公共端先假设一个不安全的数据源。