后端API网关MCP 服务dsh-plugin【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址https://gitcode.com/GitHub_Trending/treg/treg点击查看免费下载tregTools RegistryOpenRouter for agent tools用一套“碎片化”设计文档体系支撑其庞大代码库每个子系统对应docs/context/下的一篇片段fragment由 frontmatter 声明覆盖的源文件。本篇指南讲解.agents/skills/tools-registry-context/技能中的维护规程MAINTAINING覆盖“代码变更后如何让文档不漂移”的完整流程漂移检测、片段更新、索引重建、随代码提交并对照仓库中的 drift.sh、fragments.config、MAP.md 与 SKILL.md 给出源码级验证。读完你将掌握一套可复用的“代码 → 文档 → 索引”三方同步方法论并理解它为什么用“符号引用”而非“行号引用”来保持同步廉价且防误报。背景为什么设计文档需要一台“同步机器”treg 的代码面很宽src/treg/下既有 FastAPI 应用组合、代理中继、OAuth、计费也有 catalog 路由与容量调度前端、CLI、技能、部署脚本分布在全仓库各处。设计文档如果写成“大而全”的单篇一旦代码演进就会整体失真。因此仓库采用**片段fragments**体系docs/context/下按子系统拆成多篇短文每篇通过 frontmatter 的sources:显式声明“我覆盖哪些源文件”。配套的tools-registry-context技能提供两条主线Mode A加载上下文根据任务/查询定位相关片段让会话带着准确的、可溯源的上下文开工Mode B同步文档在推送主干前用drift.sh找出“改过的代码有没有对应的文档更新”按“展示 → 批准 → 应用”的节奏把文档与代码一起提交。MAINTAINING.md 就是 Mode B 的完整规程——它声明自己是“sub-skill”在运行/tools-registry-context sync时读取该体系由全局codemap技能脚手架搭建。范围边界只维护docs/context/规程第一条就是划定边界这是整套体系不出错的前提本技能只记录docs/context/。会话交接与计划handoffs and plans存放在别处例如.context/明确不属于片段集合——绝不可把它们当作输入阅读、折叠进片段或扫入索引。build-map.py按设计只遍历docs/context/。SKILL.md 的 Invariants 一节再次强调同一条Handoffs and plans are NOT documentation. They live outsidedocs/context/如.context/且超出范围——绝不作为片段输入读取、折叠或扫描。这条约束的意义在于让“文档”这个词有精确指称只有docs/context/下的片段是产品文档的一部分交接记录属于过程资产二者混用会导致索引被过程噪音污染。心智模型片段是唯一真相源索引是生成物维护工作围绕下面这张数据流展开原文图docs/context/**/*.md ← 片段真相源人可浏览、有版本管理 frontmatter: title / status / sources: [...] / related: [...] │ scripts/build-map.py 读取全部 frontmatter fragments.config → ▼ docs/context/README.md 人工索引按分类分组 .agents/skills/tools-registry-context/MAP.md 源文件 → 片段用于路由 漂移核心纪律是编辑片段绝不编辑生成文件——README.md与MAP.md都带有 “GENERATED” 横幅例如 MAP.md 顶部明确写着 “do not edit by hand; edit fragment frontmatter instead”任何手工改动都会在下次重新生成时被覆盖。真相源是片段本身及其 frontmattersources:喂给索引、MAP 和漂移检测三处。同步工作流七步走完整闭环MAINTAINING.md 给出了七步流程逐条展开并结合脚本实现说明步骤 1确定范围默认比较范围是origin/main..HEAD即所有未推送的提交需要时可用显式范围覆盖例如HEAD~20..HEAD或某个版本标签到 HEAD。步骤 2用drift.sh检测漂移运行bash .agents/skills/tools-registry-context/scripts/drift.sh [range]脚本会输出两类结果(a) 变更的源文件 → 它被哪篇片段覆盖提示你需要审查/更新哪些片段(b) 变更的源文件没有对应片段文档缺口需要折叠进现有片段或新建片段。源码层面的实现细节见 drift.sh路径与扩展名来自配置而非硬编码脚本用python3读取 fragments.config 的source_globs当前为src、skill与source_extspy/ts/js/sh/json/yaml再以git diff --name-only $RANGE -- $globs取变更文件并做扩展名过滤因此它本身是“项目无关”的。空范围 ≠ 干净范围脚本特意区分“没有可比较的提交”与“没有变更”。如果范围内提交数为 0它会输出 “NOTHING TO COMPARE — this is not a pass” 并以非零码退出exit 2而不是报“无漂移”。这是有历史教训的设计——脚本注释记载曾有“四个过期片段在生产环境上线”正是因为在合并后站在主干上跑默认范围把“分支对自己 diff”误读成了“同步通过”。间隙检测对每个变更文件脚本在MAP.md中按字面量查找文件名行命中则打印对应的片段未命中则收入gap数组单独以“⚠ changed sources with NO fragment”警告输出。步骤 3逐个更新受影响的片段对每个受影响的片段完整读取它 git diff range -- 文件按变更行为更新正文并重新 grep 确认文中引用的符号仍然存在新纳入的源文件要加入sources:。这里有一条关键的工程约定决定了整个同步流程能保持“快”引用的是符号symbols不是行号。因此别处的无关插入不会让该片段漂移——只有真正的行为/改名变更才会。这就是同步能保持快速的原因。行号会在每次编辑后移动导致“文档与代码是否一致”出现大量误报符号函数名、类名、配置键则稳定得多可 grep 即可验证。步骤 4处理文档缺口gaps对于有变更但无片段覆盖的源文件二选一折叠进现有片段把新文件追加到该片段的sources:新建片段从对应分类目录下的fragment.md.tmpl模板起步体量控制在70–130 行必须带引用、用现在时态撰写。步骤 5先展示后应用生成变更草稿后先向用户展示得到批准后才写入——这与 SKILL.md 的 Invariants 一致“No automation behind the users back. Sync is reminder → approve → apply. There is no git hook.” 同步不是后台自动化而是有节制的“提醒 → 批准 → 应用”。步骤 6重新生成索引python3 .agents/skills/tools-registry-context/scripts/build-map.py该命令会同时重写docs/context/README.md与MAP.md两个生成文件任何片段缺少 frontmatter 都会告警并以 exit 1 退出——必须在提交前修好。步骤 7与代码一起提交文档变更与引发它的代码变更放在同一个提交/推送里commit scope 使用docs(context):遵循仓库既有的提交约定。这保证任何一次代码变更的文档证据都是原子性的、可回溯的。片段约定frontmatter 是工具链的契约为了让build-map.py与drift.sh正常工作每个片段必须满足frontmatter 必填字段title片段标题status枚举取值shipped | reference | foundational | living | archived | backlogsources:仓库相对路径列表叙述/参考类片段可写作[]related:其他片段的路径。分类 子文件夹docs/context/下的目录即分类其在索引中的顺序与标签由fragments.config的categories定义。一个子系统一篇片段超过约 150 行就要拆分。仓库中可看到真实的 frontmatter 实例例如 foundation/charter.md--- title: Tools Registry — charter (what it is, why, the proxy model) status: foundational sources: - external:meetings/2026-06-30-jason-tools-registry.md - README.md related: - architecture/proxy-model.md - architecture/auth-secrets.md - interface/api.md ---architecture/composition.md 则展示了status: shipped与一个较大的sources:列表覆盖bootstrap.py、bootstrap_handlers.py、call_surface.py、各 routers 与测试文件等 20 余项。这正是“frontmatter 驱动一切”的体现sources:同时喂给索引、MAP 与漂移检测三处。演进技能与配置改分类、改源范围、拉取上游改进维护工作本身也会演进MAINTAINING 给出了对应操作新增分类在 fragments.config 的categories数组追加{dir, label}条目——它控制索引的分组顺序与标题。当前配置定义了五个分类foundationFoundation、architectureArchitecture (proxy, auth, data model)、interfaceInterfaces (API · CLI · skill)、opsOps (deploy, scale)、referenceReference外加guides目录。新增源码区在配置的source_globs增加 pathspec并在source_exts增加扩展名。这两个字段正是drift.sh判断“哪些变更文件属于文档跟踪范围”的依据见 fragments.config。拉取上游脚本改进重新以refresh模式运行全局codemap技能——它会把build-map.py/drift.sh从全局技能重新复制进来而不会触碰你的片段与配置。这解释了为什么当前仓库快照的 scripts 目录 只直接可见drift.shbuild-map.py属于由全局技能维护并复制的生成性工具。最后保持 SKILL.md 薄而精它只做“路由”选对 Mode、选对片段细节沉淀在 MAINTAINING 与各片段里。用仓库实物验证整套闭环把规程与仓库实际产物对照可以完整串起这条链路片段docs/context/下 20 篇片段每篇带 frontmatter按foundation/architecture/interface/ops/reference/guides分类存放生成索引docs/context/README.md 按分类列出每个片段、其status与覆盖的源文件如 charter 覆盖2026-06-30-jason-tools-registry.md、README.mdcomposition 覆盖一长串应用组合源文件顶部带 “GENERATED” 横幅反向索引MAP.md 提供两个方向的表——Source file → fragment(s)约 400 行映射与Fragment → sources供技能在“你触碰某个文件时”路由到正确片段也是drift.sh判断变更归属的数据源漂移脚本drift.sh 默认比较origin/main..HEAD空范围时报错而非假通过命中 MAP 输出“变更源文件 → 需审查片段”未命中则输出缺口清单技能壳SKILL.md 声明两种模式与五条 Invariants把“加载上下文”和“同步文档”统一在一个/tools-registry-context入口下。这套体系的核心价值可以归结为三点片段是唯一真相源生成物可被安全重建、符号引用让同步保持快速且不误报、展示-批准-应用让文档更新与代码变更原子化。对于任何“代码演进速度快、文档必须可溯源”的项目这套模式都值得直接迁移复用。赞分享后端API网关MCP 服务dsh-plugin【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址https://gitcode.com/GitHub_Trending/treg/treg点击查看免费下载相关推荐用「设计片段」维护大型开源项目架构文档treg docs/context 索引与生成机制深度解析用「设计片段」维护大型开源项目架构文档treg docs/context 索引与生成机制深度解析 导读 tregOpenRouter for agent后端API网关MCP 服务dsh-pluginOnyxdanswerDocker Compose 部署文件生成管线与维护指南模板指令、内嵌同步与漂移防护OnyxdanswerDocker Compose 部署文件生成管线与维护指南模板指令、内嵌同步与漂移防护 导读 本文以 deployment/READM网页爬虫数据分析SpacetimeDB Codex 插件维护指南Skills 同步机制、漂移检查与发布流程SpacetimeDB Codex 插件维护指南Skills 同步机制、漂移检查与发布流程 导读 本文围绕 codex plugin/DEVELOP.md 展数据库关系型数据库后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考