Skip to content

fix(docs): exclude v1 migration fields from schema coverage#334

Merged
innomentats merged 2 commits into
mainfrom
fix/docs-schema-v1-compat
Jul 17, 2026
Merged

fix(docs): exclude v1 migration fields from schema coverage#334
innomentats merged 2 commits into
mainfrom
fix/docs-schema-v1-compat

Conversation

@eetoc

@eetoc eetoc commented Jul 17, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • exclude temporary AgentSpec.display_name, AgentSpec.description, scheduler presentation metadata, and WorkspaceSpec.commit from public YAML schema coverage
  • scope compatibility exclusions by Go struct and YAML field so future fields with the same YAML name still require documentation
  • add a focused regression test for the schema coverage filter

Testing

  • npm test (in tools/genpages)
  • task docs:build --force
  • git diff --check

Checklist

  • Documentation coverage remains aligned with the public v2 authoring surface.
  • Tests added or updated for changed behavior.
  • No generated build/pages files committed.
  • No secrets, private endpoints, or local runtime state included.

@monkeyscan

monkeyscan Bot commented Jul 17, 2026

Copy link
Copy Markdown

PR Title: fix(docs): exclude v1 migration fields from schema...

Commit: 4236b66

本次 PR 对 schema 覆盖率工具进行了两处核心修改:

  1. 字段排除粒度从全局改为类型级别documentedYAMLSchemaFields 函数不再简单地全局排除 descriptiondisplay_name 等字段,而是通过正则匹配 type X struct { ... } 结构,按 ${TypeName}.${field} 的形式精确排除。这样可以避免误伤其他类型中同名的合法字段。

  2. 新增 WorkspaceSpec.commit 到 v1 迁移兼容排除列表:对应从文档中移除 workspace 的 commit 字段说明,并同步更新了中英文文档。

  3. 测试更新:测试用例重构为包含 AgentSpecWorkspaceSpecReleaseSpec 三个结构体,验证 WorkspaceSpec.commit 被排除的同时 ReleaseSpec.commit 仍被保留。

整体评估:变更目标明确,实现逻辑正确,测试覆盖了核心场景,文档与代码保持一致。正则 type\s+(\w+)\s+struct\s*\{([\s\S]*?)\n\} 在标准 Go 代码格式下能正确工作,未发现引入的行为回归或严重缺陷。

@innomentats innomentats left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@innomentats
innomentats merged commit e14c4db into main Jul 17, 2026
10 checks passed
@innomentats
innomentats deleted the fix/docs-schema-v1-compat branch July 17, 2026 13:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants