用途:以一个确定性的基础模板工作流维护项目 README.md,作为 README 维护的主层,定义共享的规范化 README 契约;下游语言、框架、技术栈或仓库专属定制应通过显式扩展适配,而非随意改变结构。
主要能力:在 check-only 模式审计标题与摘要要求、顶层章节名称与顺序、必需子章节名称、必需目录以及占位式内容;在 apply 模式仅编辑目标 README.md,将其规范化到配置的规范结构。保留首个 H2 之前的徽章、提示块、截图与额外引言等前言材料。引导缺失 README 时,先向用户询问 Overview > Status、Overview > What This Project Is、Overview > Motivation 文本再写入;用户未提供时子章节正文保持 TBD。对 skills、插件或混合仓库保持同一强制 schema,安装、发现、打包与维护者措辞基于真实仓库界面,不虚构未提供的普通应用章节。完成后重跑同一审计确认修复状态。
使用方式:必需参数为 --project-root <path> 与 --run-mode <check-only|apply>;可选参数为 --readme-path <path> 与 --config <path>。规范基础契约的来源为 config/readme-customization.template.yaml 与 assets/README.template.md。输出 Markdown 加 JSON,含 run_context、customization_state、schema_contract、schema_violations、content_quality_issues、fixes_applied、post_fix_status、errors;无问题且无错误时输出 No findings。用户明确要求或工作流指引允许且用户授权时,可用子代理做只读的 README 发现;apply 编辑留在主线程。
适用场景:需要统一仓库 README 结构、审计 README 合规性或对缺失 README 进行引导的项目。
限制:不自动提交、推送或开 PR;不发明仓库未提供的命令、步骤或产品声明;除目标 README.md 外不编辑其他文件;不把贡献者或维护者流程移入 README(应归 CONTRIBUTING.md 或维护者文档);不因仓库是插件、skills 或混合类型而放宽 schema。README 默认控制在约 250 行以内,300 行为软上限;多数自动或代理编辑的顶层章节约 40 行以内。