企业官网建设流程全解析

OpenClaw 生成的文档基线制品（docs/.generated）与配置漂移检测机制

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

导读

在 OpenClaw 仓库中，docs/.generated/目录保存着一批由脚本自动生成、用于漂移检测（drift detection）的基线制品：配置基线（config baseline）与 SQLite 会话/转录模式基线（SQLite sessions/transcripts schema baseline）。它们并非给人阅读的普通文档，而是仓库 CI 与本地检查门禁用来发现"配置面或数据库模式发生无意识变化"的机器可读证据。读完本文，你将掌握这 4 类跟踪制品与 4 个本地生成/校验命令的用途，理解 SHA-256 哈希、计数棘轮（count ratchet）的防漂移原理，并能在改动配置 Schema 或会话存储 DDL 后正确执行重新生成与提交流程。

一、docs/.generated/目录的定位：跟踪的漂移检测制品

OpenClaw 把文档与工程自动化深度耦合：配置的 JSON Schema、帮助文本、UI 提示（uiHints）以及会话存储的 SQLite DDL，都会被脚本"快照"成基线文件，再提交进 git 供 CI 对比。根据 docs/.generated/README.md 的说明：

Generated contract files are tracked drift-detection artifacts. Full pretty snapshots remain local inspection artifacts.

翻译过来即：提交到 git 的"契约文件"是漂移检测制品；完整的美化快照则只是本地检查制品。这是理解整个目录的关键——仓库刻意区分"用于对比的最小契约"与"供人阅读的完整快照"两类文件。

跟踪制品（committed to git）

• config-baseline.sha256— 配置基线 JSON 制品的 SHA-256 哈希文件；
• config-baseline.counts.json— 每种配置基线类型（core / channel / plugin）的最大条目数；
• sqlite-session-transcript-schema-baseline.sha256— sessions/transcripts SQLite 模式基线的 SHA-256 哈希文件。

仅本地制品（gitignored）

• config-baseline.json（combined）、config-baseline.core.json、config-baseline.channel.json、config-baseline.plugin.json— 完整的美化 JSON 快照；
• .artifacts/sqlite-session-transcript-schema-baseline.sql— 规范化后的 SQL 基线文本。

一句话记忆：哈希文件与计数文件进 git（契约），完整 JSON 与 SQL 快照只留本地（检查用）。

二、配置基线（Config Baseline）：core / channel / plugin 三种类型

配置基线由 scripts/generate-config-doc-baseline.ts 驱动，核心实现位于 src/config/doc-baseline.ts。它从配置 Schema 元数据出发，为每一类配置面生成条目化快照，每条ConfigDocBaselineEntry记录如下字段（见src/config/doc-baseline.ts中的类型定义）：

• path— 配置键的完整路径；
• kind— 所属类型：core/channel/plugin；
• type— Schema 声明的 JSON 类型；
• required— 是否必填；
• enumValues— 枚举取值；
• defaultValue— 默认值；
• deprecated— 是否已废弃；
• sensitive— 是否为敏感项；
• tags、label、help— 标签与帮助文本元数据；
• hasChildren— 是否包含子节点（用于判断叶子/分组层级）。

三种类型覆盖的配置面

三份 JSON 之外还会合并生成一份config-baseline.json（combined）供整体检查。

当前计数快照

仓库当前提交的 config-baseline.counts.json 记录了三类配置面的条目上限：

{ "core": 2421, "channel": 3730, "plugin": 4139 }

这些数字不是摆设——它们是"只降不升"的棘轮（shrink-only ratchet）：任何导致条目数增长的 Schema 改动都会让 CI 门禁失败，直到你在同一 PR 中有意识地更新计数文件。

三、SQLite 会话/转录模式基线（Schema Baseline）

与配置基线并列的第二个契约，是 SQLite 会话与转录存储的模式基线。它的生成脚本是 scripts/generate-sqlite-session-schema-baseline.ts，核心逻辑在 scripts/lib/sqlite-session-schema-baseline.ts。

输入与输出

• 输入：仓库根目录下的 src/state/openclaw-agent-schema.sql（默认DEFAULT_SCHEMA_INPUT）；
• 本地 SQL 输出：.artifacts/sqlite-session-transcript-schema-baseline.sql；
• 跟踪哈希输出：docs/.generated/sqlite-session-transcript-schema-baseline.sha256。

目标表白名单

生成器不会把整个 Schema 文件全部纳入基线，而是只提取与会话/转录相关的 12 张目标表（TARGET_TABLES，见scripts/lib/sqlite-session-schema-baseline.ts）：

session_nodes session_participants session_windows session_members conversations session_conversations transcript_events transcript_rewrite_watermarks transcript_event_identities session_transcript_index_state session_transcript_active_events session_transcript_archives

规范化与哈希流程

从源码可以看出，基线生成包含三步关键处理：

1. 语句切分（splitSqlStatements）：按分号 + 换行把openclaw-agent-schema.sql切分为独立 SQL 语句；
2. 目标过滤（isTargetSessionSchemaStatement）：通过正则解析CREATE TABLE IF NOT EXISTS与CREATE INDEX ... ON语句，只保留目标表及其索引的 DDL；
3. 规范化与哈希（normalizeStatement+computeSqliteSessionSchemaBaselineHashFileContent）：对语句做去尾空白、统一结尾分号等规范化，再对规范化文本计算 SHA-256，生成形如<hash> sqlite-session-transcript-schema-baseline.sql的哈希文件内容。

由于比较的是规范化后的 SQL 文本，单纯的格式变化不会误报漂移，而任何影响表结构、列定义、索引的 DDL 改动都会改变哈希，从而被--check模式捕获。

四、四个管理命令：生成与校验

原文 README 给出的四个 pnpm 命令，在仓库根 package.json 中均有对应定义（第 1690-1691、1904-1905 行）：

# 重新生成配置基线（写模式） pnpm config:docs:gen # 校验配置基线（检查模式） pnpm config:docs:check # 重新生成 SQLite sessions/transcripts 模式基线（写模式） pnpm sqlite:sessions-schema:gen # 校验 SQLite sessions/transcripts 模式基线（检查模式） pnpm sqlite:sessions-schema:check

它们分别对应两个 Node 脚本的--write与--check参数：

两个脚本都严格互斥--check与--write：同时传入会直接报错退出（如Use either --check or --write, not both.）。

写模式（--write）的输出

pnpm config:docs:gen成功后会打印写出路径，例如：

Wrote docs/.generated/config-baseline.sha256 Wrote docs/.generated/config-baseline.counts.json Wrote docs/.generated/config-baseline.json (gitignored, local only) Wrote docs/.generated/config-baseline.core.json (gitignored, local only) Wrote docs/.generated/config-baseline.channel.json (gitignored, local only) Wrote docs/.generated/config-baseline.plugin.json (gitignored, local only)

pnpm sqlite:sessions-schema:gen则输出：

Wrote docs/.generated/sqlite-session-transcript-schema-baseline.sha256 Wrote .artifacts/sqlite-session-transcript-schema-baseline.sql (gitignored, local only)

检查模式（--check）的行为

• 基线与磁盘内容一致时输出OK <相对路径>并返回退出码 0；
• 配置基线哈希漂移时，scripts/generate-config-doc-baseline.ts会区分两种失败原因并给出指引：
  • 计数预算违规（count budget）：提示运行pnpm config:docs:gen重建计数文件；
  • 哈希漂移：提示"如果是有意的配置面变更，运行pnpm config:docs:gen并提交更新后的哈希文件；如果不是有意的，视为文档漂移或潜在的破坏性配置变更，先修复 Schema/帮助文本改动"。
• SQLite 基线哈希漂移时，scripts/generate-sqlite-session-schema-baseline.ts会提示：如果是有意的 Schema 变更，运行pnpm sqlite:sessions-schema:gen并提交哈希文件；如果不是有意的，应保持 Schema 稳定，或将无关状态迁移到独立的表/存储中。

五、漂移检测与计数棘轮：CI 门禁原理

docs/.generated的制品最终服务于仓库的工程门禁。docs/ci/local-proof.md 明确将config-baseline.counts.json描述为配置面的shrink-only 预算：

docs/.generated/config-baseline.counts.jsoncaps the per-kind (core/channel/plugin)openclaw.jsonschema entry counts. Checked bypnpm config:docs:check; regenerate withpnpm config:docs:genafter any schema change.

其门禁语义可以概括为三点：

1. 拒绝未记录的配置面增长：pnpm config:docs:check会拒绝"配置面增长但未同步更新基线"的改动，以及损坏或过期的计数快照；
2. 有意的增长必须同 PR 提交：当产品评审确认某次改动需要新增 Schema 路径时，应运行pnpm config:docs:gen，人工检查 core/channel/plugin 计数增量与生成的 SHA-256 文件，并把有意识抬高的基线随 Schema、帮助文本、标签、迁移与测试一起提交；
3. 禁止手工绕过：不能手工编辑计数文件来绕过棘轮（"Do not hand-edit the counts file to bypass the ratchet"）。

配置基线在 changed-lane 门禁中的角色

docs/ci/local-proof.md还说明：配置 Schema/帮助文本、捆绑插件元数据、源 Schema 条目的相对导入依赖、生成器/选择器属主以及跟踪的配置基线变更都会触发pnpm config:docs:check；基线文件混在普通文档中时同样会被检查，且 all-lane 与 release 元数据计划会执行一次。这意味着即使只是修改了某个配置项的 help 文案，本地与 CI 的 changed-lane 路由也会自动把检查范围路由到配置基线门禁上。

六、推荐工作流：何时 gen、何时 check、何时提交

结合文档与脚本行为，可以总结出如下可复现的工作流：

场景 A：日常开发未改配置面/Schema

pnpm config:docs:check pnpm sqlite:sessions-schema:check

两条命令都应输出OK并返回退出码 0。若此时失败，说明你的工作区存在未同步的基线漂移，需要先排查改动来源。

场景 B：有意新增配置 Schema 路径

1. 在 Schema 中完成新增（含 help、label、advanced 分级等元数据）；
2. 运行pnpm config:docs:gen重新生成基线；
3. 审查 core/channel/plugin 的计数增量与config-baseline.sha256的哈希变化是否符合预期；
4. 连同 Schema 改动、迁移、测试以及更新后的config-baseline.counts.json、config-baseline.sha256一起提交。

场景 C：有意变更会话/转录 SQLite DDL

1. 修改 src/state/openclaw-agent-schema.sql 中目标表的 DDL；
2. 运行pnpm sqlite:sessions-schema:gen；
3. 确认sqlite-session-transcript-schema-baseline.sha256与本地.artifacts/sqlite-session-transcript-schema-baseline.sql的变化；
4. 提交哈希文件；若属破坏性变更，还需评估数据迁移路径（脚本提示：若非有意，应保持 Schema 稳定或把无关状态移到独立表/存储）。

必须遵守的红线

• 不要手工编辑docs/.generated下任何文件（原文明确 "Do not edit any of these files by hand"），所有变更都应由脚本重新生成；
• 完整 JSON/SQL 快照是 gitignored 的本地检查制品，不应提交；
• 计数文件是棘轮而非普通统计，增长必须伴随有意的产品决策。

七、从源码结构看整体设计意图

从 src/config/doc-baseline.ts 的实现可以进一步确认设计意图：脚本先解析配置 Schema 响应（ConfigSchemaResponse），结合 UI 提示（uiHints）与仓库内捆绑插件环境（resolveRepoBundledPluginEnv），把 schema 树展平为按路径排序的条目数组，再渲染成 JSON 并用 SHA-256 哈希出契约文件。replaceFileAtomicSync的原子写入方式也说明这些制品被当作正式契约对待——避免半写状态污染 CI 对比。

综合来看，docs/.generated/体现的是一套"代码即文档、契约进仓库、漂移即失败"的工程实践：让配置面与数据库模式的变化像代码一样可评审、可追溯，同时用哈希与计数双重机制把"无意识的破坏性变更"挡在合入之前。对 OpenClaw 的贡献者而言，理解这四个命令与两类基线，是安全改动配置 Schema 与会话存储结构的必要前提。

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw