Repository navigation
fix(contracts): 契约文档链接与 schema $id 检查对齐 lithe-plugin-docs 同步规则 - #1643
Merged
Merged
Conversation
- proposals/toolchains/README.md 文件表里指向 fixtures/ 目录的链接改为代码文本；lithe-plugin-docs 的 contract.mjs sync 要求相对链接指向副本里的文件，这条链接让 #1581 合并后的同步被拒 - verify-shared-contracts.sh 检查契约目录下每个 Markdown 文件（原来只查顶层 README），相对链接必须指向目录内的文件，不能指向目录 - verify-shared-contracts.sh 检查目录下每个 *.schema.json 的 $id 等于 docs 发布地址（原来只查三份顶层 schema） - 更新契约发布 Agent Note，写明两边规则一致的要求和这次被拒的原因
ghfind-review
Bot
added
the
review: high
xiaoyumuxi
marked this pull request as ready for review
November 1, 2026 15:41
xiaoyumuxi
added
the
matrix-exempt
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
#1581 合并后，在 lithe-plugin-docs 运行
node scripts/contract.mjs sync --revision ef6e70c3c…被拒，报错是：docs 的同步规则要求：契约目录里每个 Markdown 的相对链接都指向副本里的文件，每份 schema 的
$id等于它的发布地址。主仓库的verify-shared-contracts.sh只检查顶层 README，而且允许链接指向目录，所以这个问题在合并前没被发现。本 PR 修掉这条链接，并把主仓库的检查收紧到和 docs 一致，以后同类问题在主仓库 CI 就会失败。改动
shared/contracts/plugins/v1/proposals/toolchains/README.md：文件表里[fixtures/](fixtures/)改成代码文本`fixtures/`。raw 地址取不到目录，docs 不接受指向目录的链接。契约内容没有其他变化。scripts/architecture/verify-shared-contracts.sh：README.md，扩大到契约目录下的每个.md（包括toolchains.md、proposals/toolchains/*.md）。相对链接按所在文件的目录解析，必须指向目录内的文件；指向目录或目录外，都会失败。*.schema.json的$id必须等于published_plugin_schema_base/<目录内路径>。原来只检查顶层三份，proposals/toolchains/的 5 份 schema 没有检查。三份顶层 schema 原有的检查保留不动。.agents/notes/implemented/architecture/2026-10-23-plugin-contract-publishing.md：把“两份 schema”“契约 README”更新为目录下全部 schema 和 Markdown；写明相对链接不能指向目录、两边规则必须一致，并记录这次同步被拒的原因。功能矩阵
没有用户可见的变化：只改了一处契约文档链接和一个 CI 校验脚本。
verify-platform-feature-matrix-change会因为动了shared/contracts而要求更新矩阵，请 reviewer 确认后加matrix-exempt。验证（本地）
./scripts/architecture/verify-shared-contracts.sh：通过。fixtures/改回目录链接：检查失败，报proposals/toolchains/README.md: link fixtures/ must be absolute or name a file inside shared/contracts/plugins/v1。proposals/toolchains/query.schema.json的$id改成顶层地址：检查失败，报出期望的完整地址。./scripts/agent-notes/verify-agent-notes.sh：188 篇通过。contract.mjs sync --checkout <本分支>对本 PR 的提交做试同步：76 个文件同步成功；contract.mjs verify和node --test scripts/*.test.mjs（15/15）都通过。试同步的结果已经丢弃，不会提交。合并后
在 lithe-plugin-docs 用本 PR 合并后的 preview commit 运行
sync，提交契约同步 PR。