agents-md-sync

面向编程代理的仓库说明工具：在保留人工撰写内容的前提下，为任意仓库生成或刷新带标记的 AGENTS.md 托管区块，可选兼容 AGENT.md（符号链接），并支持保守的单仓/嵌套子项目策略。

功能概要

• 根据 package.json、pyproject.toml、go.mod 等清单自动推测常用命令（安装、开发、构建、类型检查、测试、Lint、格式化）。
• 用 HTML 注释标记托管区间，只替换托管块，不覆盖标记外的手写说明。
• 通过根目录或子目录的 .agents-md-sync.json 覆盖命令、语言、安全/PR 提示等（详见本仓库 SKILL.md）。
• --dry-run + --json：便于 CI 或自动化校验，不落盘。
• --nested auto：在疑似 monorepo 时仅为独立作用域生成嵌套 AGENTS.md（策略保守，细节见 SKILL.md）。

官方背景与撰写约定见 references/official_spec.md。

环境要求

• Python 3（标准库即可，无需额外依赖）。

快速使用

在本仓库根目录下对目标项目执行（将 /path/to/your/repo 换成实际路径；若已在目标仓库根目录，可用 --repo .）：

python3 scripts/sync_agents_md.py \
  --repo /path/to/your/repo \
  --compat-link \
  --nested auto \
  --dry-run \
  --json

确认输出合理后，去掉 --dry-run 与 --json（若仅需人类可读摘要可保留一种输出方式）再执行一次以写入文件。

命令行参数

参数	说明
--repo PATH	目标仓库路径，默认 .
--compat-link	在合适时创建缺失的 AGENT.md → AGENTS.md 符号链接
--dry-run	仅预览，不写文件
--json	打印结构化 JSON（与 --dry-run 常一起用于自动化）
--lang en | zh	托管区块输出语言
--nested off | auto	是否生成嵌套 AGENTS.md
--nested-max-depth N	auto 模式下扫描目录的最大深度
--generated-at UTC	覆盖写入托管块中的时间戳（多用于测试）

测试

在本仓库根目录执行：

python3 -m unittest discover -s tests -p "test_*.py" -v

目录结构

路径	作用
scripts/sync_agents_md.py	同步入口脚本
SKILL.md	完整工作流、质量要求与 .agents-md-sync.json 说明
references/official_spec.md	与 AGENTS.md 相关的缓存规范摘要
agents/openai.yaml	代理/工具链相关补充配置（若适用）
tests/	单元测试

许可与贡献

若本技能来自上游分发，请遵循上游许可；修改行为时建议同步运行测试并阅读 SKILL.md 中的决策规则，避免破坏「托管块 vs 手写区」的约定。