用途
upstream-sync 是 acaprino/daodan 仓库中用于管理“上游同步”的规范文档与工作流说明。它面向那些从外部仓库移植（ported）过来的插件，目标是让这些插件在保留本地定制的前提下，持续与上游源保持同步。当用户要求更新某个已同步插件时，按此流程从上游 URL 获取最新内容并应用变更，然后遵循 AGENTS.md 中的标准市场更新工作流。
主要能力
- 同步表：列出每个已移植插件的上游来源与需要同步的本地文件，例如 codebase-xray、react-development、digital-marketing、docker、typescript-development、kotlin-development、project-knowledge 等。
- 默认上游更新策略：不盲目覆盖本地文件，因为大多数同步需要定向合并，本地存在合理定制。
- 文件分类机制：在改动前将每个文件归入四类——明确收益（上游新增文件或修复且无本地冲突，直接拉取）、小幅改进（措辞/元数据小改动，无冲突则拉取）、硬合并（上游重写了本地也演进过的段落，需叠加而非覆盖）、有意偏离（本地命名空间重写、本地润色、风格约定、本地独有新增等，不动）。
- 本地定制保留清单：文件顶部的来源署名行、frontmatter（本地化描述、tools、color、version、model）、插件特定风格（无破折号旁白、部分插件无 emoji）、命名空间替换、本地独有段落（如 Ecosystem Integration）。
- 决策征询：对未决的实质性选择，通过宿主提问机制询问用户，并复用已接受的范围与既有决定。
- 定向编辑优先：优先使用外科式编辑修复具体问题，仅在新建文件或整文件替换时使用 Write。
- 宿主中立：内核只声明所有权、隔离交付、屏障与证据要求，不命名原生团队或工具原语；宿主特定机制只放在对应适配器中。
- 版本提升与重建：在 plugins/<name>/plugin.toml 与 .claude-plugin/marketplace.json 中提升版本，用 python scripts/daodan_build.py 重建各宿主，用 python scripts/sync_plugin_docs.py 重新生成组件/依赖参考。
- 校验与提交：运行 --check 校验与仓库门禁，检查命名消费者与打包路径，查看 git status / git diff --stat，必要时用 python scripts/sync_codex_instructions.py 重新生成原生 Codex 适配并校验一致性，最后以描述性信息提交并推送。
使用方式
同步表给出上游仓库与本地目标文件。单文件模式使用 gh api 获取内容并 base64 解码；目录模式先列出子项再迭代获取。获取后与本地内核文件比对，保留本地新增内容，再执行版本、重建、校验与授权发布步骤。文档还给出若干非显而易见的逐插件同步注意事项，例如 domain-hunter 上游 Step 3 使用专用 Twitter/Reddit Python 脚本，需替换为针对 site:x.com / site:reddit.com 的 WebSearch 查询。
适用场景
适用于维护从外部仓库移植的插件集合、需要定期拉取上游更新同时保留本地定制的项目，以及需要明确“哪些文件该同步、哪些有意不同步”的仓库治理场景。
限制
- 文档明确：AGENTS.md 中“Deliberately not vendored”下列出的内容不属于同步表，不应在未来新增行；已退役的 obra/superpowers 导出行保持退役。
- 部分上游改动因本地结构不同而无对应目标，会被跳过（如 visual-companion.md 的 Copilot CLI 启动块、render-graphs.js 的 ESM 转换等）。
- 具体插件的版本号、发布时间、收费与平台支持等信息，资料中未提供。