LoopX 文档治理与资产完整性指南docs-smoke 如何守住 3 道公开文档质量防线【免费下载链接】loopxLong-horizon agent control plane for durable, governed work across Codex, Claude Code, and other harnesses.项目地址: https://gitcode.com/GitHub_Trending/lo/loopxLoopX 是横跨 Codex、Claude Code 等多种 Agent 运行时的长程控制面Long-horizon agent control plane其docs/文档树包含架构、协议、指南等数百个文件。为了让如此庞大的公开文档不腐烂LoopX 在examples/目录提供了两道轻量但严格的文档治理 smoke 检查docs-governance-smoke.py 守护文档信息架构docs-asset-integrity-smoke.py 校验图片等资产完整性。它们和 CI 一起构成 LoopX 公开文档的质量防线。️为什么长程控制面需要专门的文档治理LoopX 的文档同时服务四类读者试用产品的用户、运行长期 Goal 的运维者、修改控制面的贡献者、审阅协议与维护证据的维护者。不同读者需要的路径完全不同。因此 文档布局与迁移策略 明确规定docs/根目录只保留少量高流量稳定锚点如架构、配额分配、状态数据契约新文档必须放入最小归属目录例如指南进docs/guides/、协议进docs/reference/protocols/移动文档时必须修复仓库内所有调用方链接且私有材料本地路径、凭据、原始对话严禁进入公开文档。但策略写在纸上不等于策略被遵守。这正是 docs-smoke 登场的地方把文档治理规则变成可执行、可重复、失败的代码。第一道防线docs-governance-smoke 守护文档信息架构docs-governance-smoke.py 是整个仓库最大的文档检查脚本约 860 行它覆盖了六大类契约目录清单精确匹配docs 根目录不放杂物脚本顶部定义了ROOT_DOCS集合约 10 个文件和PRODUCT_ROOT_DOCS集合7 个文件随后断言docs/根目录下的.md文件集合恰好等于清单——多一个少一个都会失败。这防止了随手在根目录丢一份新文档的长期劣化。迁移路径台账MOVED_PATHS 保证搬得走、找得到MOVED_PATHS迁移台账docs-governance-smoke.py登记了 14 组旧路径 → 新路径的迁移记录例如旧路径新路径CONTRIBUTOR_TASKS.mddocs/development/contributor-tasks.mddocs/commit-readiness-manifest-20260603.mddocs/archive/release-readiness/下对应文件DESIGN.mddocs/development/design.md检查逻辑双向验证旧路径必须已消失、新路径必须真实存在并且所有公开索引页README、各类目录页不得再引用旧路径、必须能定位到新路径。这保证文档重组后用户手里的旧链接认知仍然平滑过渡。导航一致性mkdocs nav 与入口链接双向校验assert_hosted_docs_nav_parity 函数做三件事孤儿导航检查mkdocs.yamlnav 中列出的每个页面必须对应真实文件或生成文档来源杜绝导航挂了空气链接入口可达检查docs/README.md 目录页和docs/index.md引用的每个.md目标必须存在且要么出现在 nav 中要么出现在带理由的 allowlist 里allowlist 必须写明为什么豁免稳定入口契约README 中约 25 条进阶文档入口链接docs-governance-smoke.py必须持续可达——这些是用户从首页进入深文档的主干道。双语 RFC 镜像英文与中文必须互链LoopX 的架构 RFC 要求双语。check_rfc_language_mirrors 会遍历docs/architecture/rfcs/下每份英文 RFC验证存在同名.zh-CN.md中文镜像且双向互链、双方都标注了镜像声明。历史遗留 RFC 通过显式 allowlist 管理而不是悄悄放宽规则。全库本地链接可达性扫描assert_local_doc_links_resolve 遍历docs/下全部.md与.html文件用正则提取所有 Markdown 链接、引用式链接和图片src逐一解析相对路径并断言目标文件存在。任何一条断链都会让检查失败并精确报出哪个文件 → 哪条链接。此外脚本还校验内容契约贡献者任务板的必需/过期条目、技术方向治理文档的双语同步、RFC 中禁止出现私有路径如/Users/、本地研究目录等公开安全边界。第二道防线docs-asset-integrity-smoke 校验文档资产文档里的截图是资产资产也会烂图片被误删、被压缩成空壳、或者同一张图以不同文件名重复占用空间。docs-asset-integrity-smoke.py全文仅约 50 行用四步验证 Personal Workspace 用户指南 所引用的资产引用清单从指南中提取所有图片引用与 HTMLsrc引用合并去重要求不少于 6 个存在且非空每个被引用的资产必须真实存在且体积大于 1 KB防占位空文件SHA-256 去重对所有 PNG 计算哈希两两比对——哈希完全相同的重复资产直接判失败docs-asset-integrity-smoke.py公开边界扫描指南正文不得出现Users/chou、localhost:、Cookie:、session-private等私有/本地令牌docs-asset-integrity-smoke.py保证截图与文案不会泄漏本地环境信息。下面这张图正是该指南中被完整性校验覆盖的 LoopX 管家总览截图之一全部通过后脚本输出一行简洁回执docs-asset-integrity-smoke: ok (9 assets verified, all PNG hashes distinct)两道 smoke 如何融入日常运行在 LoopX 的质量分层体系中docs-smoke 属于稳定公开 smoke层——用公开安全的 fixture 保护已交付行为本地开发时聚焦运行主干每日全量运行运行方式说明单个脚本直接运行python3 examples/docs-governance-smoke.py本地即时反馈smoke 套件运行器run-smokes.py 支持按模块过滤、并发与预览canary 全量套件loopx canary smoke-suite --suite full-public主干与每日 CI 使用值得一提的是什么是好的 Smoke 对什么样的 smoke 值得长期保留给出了审阅清单期望结果必须来自独立审阅的规则而非当前输出、结果必须确定性可重复、fixture 必须公开安全。docs-smoke 本身就是这些原则的示范样本。上图的 frontstage 展示页右侧Boundary Warnings面板与 smoke 中的公开边界扫描是同一套理念私有材料被主动省略而不是悄悄混入。给贡献者的 3 条实践建议 新文档先问归属提交前对照文档布局策略的定位清单五问——谁会读、属于哪类、哪个索引负责、是否公开安全、用什么验证移动即修链搬动文档时同步更新仓库内所有 Markdown 链接、smoke 断言与生成导航并在MOVED_PATHS台账中登记写完先跑 smokepython3 examples/docs-governance-smoke.py与python3 examples/docs-asset-integrity-smoke.py都是秒级反馈比等到 CI 红得更早一步。延伸阅读LoopX 文档首页按你想做什么选择最短路径测试与质量体系从单元测试到发布资格门的完整分层文档布局与迁移策略目录归属与稳定锚点规则什么是好的 Smokesmoke 的语义 oracle 与合并原则【免费下载链接】loopxLong-horizon agent control plane for durable, governed work across Codex, Claude Code, and other harnesses.项目地址: https://gitcode.com/GitHub_Trending/lo/loopx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考