Compile Usage Docs From a Frozen Spec Hash, Not From Chat

说明与用途

使用冻结的规范快照生成使用文档，而不是从聊天生成，以确保来源可靠并防止过时或虚构的内容。

问题

Documentation generated from live chat transcripts can contain unverified claims and lack provenance, leading to inaccurate or misleading API usage pages.

结果

A reproducible, CI‑driven workflow that guarantees usage docs are tied to a specific spec snapshot, preventing stale or fabricated content from entering the documentation repository.

工作流

• Freeze the OpenAPI spec and write its SHA‑256 hash to docs/SPEC.lock
• Run a CI check that compares the current spec hash to the lockfile
• If the hash matches, allow the generator to produce usage Markdown in docs/usage/
• If the hash mismatches, delete or block the generated docs and fail the PR
• Use scripts/classify_usage.py to scan generated docs for human‑owned phrases and reject them
• Place any non‑draftable content under docs/policy/ where the generator cannot write
• Merge the PR only after all checks pass and human review confirms policy compliance

证据

Usage pages stay honest when they compile from a frozen interface snapshot instead of from a chat transcript.

来源

Rows marked “Yes” should live under docs/usage/ and should be deleted automatically when the spec hash changes.

来源