维护者视角

发布前自检三件事 #

• 内容级泄漏扫描：发布产物里不能出现本机用户目录、私有仓名、密钥或令牌。扫描必须先解码 HTML 实体和 JS 转义再匹配，否则编码拼接能绕过字面检查。
• 文档树摘要锁：给每个文档的标题与章节结构算摘要，和上次比对。结构被误删或章节被改动时立刻发现。
• 链接越界断言：站内链接不能跳出本站范围；外链只允许指向已发布仓库的固定版本地址，禁用外部 CDN、webfont 或统计脚本。

本站的渲染器会在写入目标前做泄漏扫描，并生成 site-baseline.json 作为产物树摘要。--check 把内存渲染与磁盘基线比对；不一致即漂移。

两条铁律 #

• 声明式配置单一来源：发布什么、拷到哪、哪些路径禁止外泄，都写在一份配置里，脚本照着跑。Review 一份配置就能知道这次发版会带出什么。
• 物理公私隔离：私有内容与公开内容走不同目录，发布前做隔离校验。内容级正则、机器可读边界配置、路径禁止清单三层里任意一层拦到，发布就停。

把自检接进流水线 #

• 预提交：本地改了文档或站点，锁或基线变了就拦下，要求回到权威源并重新渲染。这防止只改渲染产物。
• 推送前：再跑完整性与锁审计，确保进共享仓库的内容干净。
• CI / 公开发布前：完整性校验、锁审计、测试与发布就绪性验证。任何一项失败都不进发布。

具体命令以目标仓库自己的发布配置为准。本页不列父工程私有脚本名。

OSS 合规与双语 #

对外发布的文档遵循 Apache-2.0 与 NOTICE。README、CHANGELOG、INSTALL 维持中英双语；本知识站正文以中文优先。克隆到新仓库时，onboarding 应能照着做就跑起来，这正是 bootstrap 向导存在的原因。许可证头、NOTICE、第三方归属要随每次发版复核。

重组与锁收尾 #

制品拆分、改号或跨批次移动之后，旧关系锁会变成孤儿。锁清理是发布前的显式维护动作，不是 自动收尾：

artifact-graph version-lock refresh --changed-only --worktree --remove-orphan-edge <edgeId>

只点名本次重组产生的那条边。--remove-orphans 是整体清理，与 --remove-orphan-edge 互斥； 同一锁文件里的既有孤儿不因本次重组被连带删除，清理前后的条目都能在锁文件 diff 里回看。 恢复材料默认保留，只有显式 restructure prune-recovery 才清理。

重组写入能力的成熟度是 candidate，资格环境仅为 Darwin / arm64 / APFS，前提是合作式写者， 恢复需要显式的双维护确认。维护者不得把它写成已发布的全平台事务保证，也不得因为 apply 能跑通就省略操作者确认。

派生文档防漂移 #

很多文档是渲染出来的副本，不是手写权威源。这类文档必须带生成横幅，并能重新渲染后与已提交基线比对；不一致即漂移。只在产物上改、不回改权威源，下次渲染会覆盖改动。外链必须钉到具体版本标签，不能指向会漂移的默认分支。

请使用 artifact-chain-maintainer 说明当前关系锁与文档派生检查该如何刷新；列出将写入的路径，等待授权后再执行。

未授权方向不得写成已实现能力。状态口径见路线图。