treg 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点击查看免费下载tools-registry-context是 treg 仓库内置的 Agent 技能位于 .agents/skills/tools-registry-context/SKILL.md它解决两个核心问题如何在会话中按需加载正确的设计文档片段Mode A以及如何在代码变更后让设计文档与实现保持一致Mode B。读完本文你将掌握这套文档即事实来源docs as source of truth的维护体系fragments 的组织方式、MAP.md反向索引的用法、drift.sh漂移检测脚本的语义以及build-map.py生成器的工作原理——这套机制同样适用于任何希望让 Agent 快速上手大型代码库的项目。为什么需要这样一个技能文档碎片化的代价treg 的架构文档不是一本连贯的大书而是fragments片段docs/context/下每个子系统一个 Markdown 文件例如 architecture/proxy-model.md代理模型、architecture/money.md计费与账本、interface/api.mdFastAPI 接口。这种设计让每份文档保持小、聚焦、可独立阅读——但代价是检索成本当会话主题涉及某个具体源文件时你需要知道这个文件被哪份 fragment 文档覆盖。tools-registry-context技能正是为这个成本而生的路由层。它的定位在技能文档开头写得很清楚tools-registry 的设计文档是docs/context/下的片段每个子系统一个每个片段在 frontmatter 中声明它覆盖的源文件。紧邻本文件的MAP.md是生成的反向索引源文件 → 记录它的片段。技能自身保持薄——它只持有生成的MAP.md、两个脚本和一个 JSON 配置真正的知识全部留在docs/context/片段里。核心架构片段、frontmatter、反向索引与生成器1. 片段fragments与 frontmatter每个片段文件以 YAML frontmatter 开头声明title、status、sources和related。以 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 ---status的合法取值在 MAINTAINING.md 中定义shipped已上线、reference参考、foundational基础、living持续演进、archived归档、backlog待办。从 docs/context/README.md 可以看到实际使用情况绝大多数 fragment 状态为shipped少数为building建设中或foundational。related字段建立片段之间的导航关系例如 charter 片段把读者引向代理模型、密钥与接口三份核心文档。2. MAP.md源文件 → 片段的逆向索引MAP.md 是技能的接线图由build-map.py自动生成文件顶部带有明确的 GENERATED 横幅!-- GENERATED by scripts/build-map.py — do not edit by hand; edit fragment frontmatter instead --它包含两个方向的表格Source file → fragment(s)按源文件排序例如src/treg/application/call/resolve.py同时被architecture/instagram-oauth.md、architecture/import-boundaries.md、architecture/money.md、architecture/multi-tenancy.md、architecture/proxy-model.md、interface/api.md六份文档覆盖Fragment → sources按 fragment 列出全部源文件。这份索引覆盖了仓库几乎所有源码、前端、脚本和测试文件——单是src/treg/alembic/versions/下的迁移文件就逐一映射到了对应的架构文档这让改了某个表结构应该同步哪篇文档成为一次纯查表操作。3. fragments.config生成器的全部配置.agents/skills/tools-registry-context/fragments.config 是一个 JSON 文件定义了生成器的行为{ project: tools-registry, docs_dir: docs/context, categories: [ { dir: foundation, label: Foundation }, { dir: architecture, label: Architecture (proxy, auth, data model) }, { dir: interface, label: Interfaces (API · CLI · skill) }, { dir: ops, label: Ops (deploy, scale) }, { dir: reference, label: Reference } ], source_globs: [src, skill], source_exts: [py, ts, js, sh, json, yaml] }docs_dir片段所在目录categories控制 README 索引的分类顺序与标题目录分类source_globs/source_exts限定哪些变更算源码变更drift 检测只对这两项过滤后的文件感兴趣。新增分类时只需在categories追加{dir, label}新增源码区域时则追加 pathspec 与扩展名——无需改动脚本本身。4. build-map.py手写 frontmatter 解析器与双输出生成器scripts/build-map.py 是一个零第三方依赖的 Python 脚本行为完全由fragments.config驱动。关键实现点解析 frontmatterparse_frontmatter()手写解析器只支持项目自己约定的小子集——识别key: value、key: []、[a, b]列表以及- item列表行见 build-map.py 第 37-65 行收集片段collect()递归扫描docs/context/下所有.md跳过各目录的README.md读取 title/status/sources 等元数据双输出render_readme()生成人类可读的分类索引 docs/context/README.md带 Status 与 Covers 列render_map()生成 MAP.md 的反向索引缺失检测任何 fragment 缺少 frontmatter 时打印警告并返回退出码 1见 build-map.py 第 152-159 行防止无元数据的孤儿文档混入索引。调用方式python3 .agents/skills/tools-registry-context/scripts/build-map.py脚本是幂等的输出形如✓ 25 fragments · N mapped source files的摘要。注意只能编辑 fragment 本体永远不要手改生成文件——它们带 GENERATED 横幅且会被覆盖。Mode A — LOAD context按需加载正确的文档片段Mode A 是技能的默认模式核心原则是根据调用时机自适应Adapt towhenyoure called。冷启动全新会话的暖机warm-up当会话几乎没有先验上下文时技能按以下流程暖机阅读索引 docs/context/README.md了解整套 fragment 的分布与状态阅读当前主题相关的片段——foundation风格的概览片段如 charter加上查询或仓库状态指向的子系统片段运行git log --oneline -15与git status捕获最近的提交与未提交的工作输出一段简短 orientationtreg 是什么、涉及的子系统有哪些、最近发生了什么变化然后表示就绪。会话中途保持目标聚焦stay targeted当某个任务/主题已经在进行中技能要求不要重新暖机整棵文档树而是通过 MAP.md 的 Source file → fragment(s) 表把当前手头的工件/主题映射到具体的 fragment 上只读取那些 fragment继续干活。聚焦查询显式指定关注区域技能接受可选参数形如/tools-registry-context area或/tools-registry-context sync。技能文档明确规定显式查询永远优先A focus query always wins——无论处于哪种场景只要提供了查询词就用它来选择 fragment 并聚焦暖机范围。无论何时都成立的行为准则改动任何东西之前先读数据模型 / 行为 / RCA / 符号锚点read the data model / behavior / RCAs / symbol anchors before changing anything只加载相关的绝不 dump 整棵文档树如果触碰的工件没有对应 fragment把它记为 Mode B 的 gap文档缺口——这正是漂移检测要解决的问题。Mode B — SYNC docs让文档跟上代码Mode B 在两种时机触发显式运行/tools-registry-context sync或临近向 main 分支推送时。技能文档明确只能先提醒用户得到用户同意后才继续——proceed only on their yes。这是不变量No automation behind the users back的体现没有 git hook同步永远是提醒 → 批准 → 应用三步。第 1 步用 drift.sh 检测漂移.agents/skills/tools-registry-context/scripts/drift.sh 是漂移检测入口默认范围为origin/main..HEAD即所有未推送的提交bash .agents/skills/tools-registry-context/scripts/drift.sh # 或指定范围 bash .agents/skills/tools-registry-context/scripts/drift.sh HEAD~20..HEAD脚本从fragments.config读取source_globssrc、skill与source_exts过滤出本次范围内的源码变更然后逐文件在MAP.md中查找其文档映射输出两类结果Changed sources in range → fragments to review: src/treg/foo.py → architecture/catalog.md ... ⚠ changed sources with NO fragment (possible doc gap — fold in or write a new fragment): src/treg/bar.py值得特别注意的是脚本对**空范围的防御**见 drift.sh 第 22-47 行如果站在 main 分支上运行默认范围origin/main..HEAD之间没有任何提交diff 为空——这会给出无漂移的假通过。脚本专门检测这种情况打印⚠ NOTHING TO COMPARE — this is not a pass.并以退出码 2 结束防止空范围被误当成干净范围。它还只把版本形态的 tagv[0-9]*、[0-9]*当作发布边界建议避免证据型 tag如pr-evidence干扰git describe的判断。正确用法是在合并前、站在功能分支上运行。第 2 步起草更新对每个受影响的 fragment通读 fragment 本体与git diff range -- file更新叙述以匹配变更后的行为重新 grep 校验被引用的符号仍然存在——no line-number chasing — symbols dont drift。这是整个体系的关键设计引用锚定的是可搜索的符号函数/类名而不是行号。行号每次编辑都会漂移、拖慢同步只有真正的行为变更/重命名才让 fragment 失准。对于没有任何 fragment 覆盖的新子系统用fragment.md.tmpl模板在正确的分类目录下新建 fragment目标篇幅约 70–130 行、带引用、现在时态叙述。第 3-4 步展示、批准、重新生成先展示后应用把拟议变更呈现给用户获得批准后才写入present proposed changes and get approvalbeforewriting重新生成索引运行build-map.py它会同时重写docs/context/README.md与MAP.md若任何 fragment 缺 frontmatter 则警告并以退出码 1 结束必须修复后才能提交。第 5 步文档与代码同 commit 一起推送同步的产物跟随代码进入同一个 commit/pushcommit 使用docs(context):前缀并遵循仓库的提交规范——doc updates ride with the code in the same commit/push。这保证了推送时文档与代码永远处于一致状态。五条不变量这套体系的底线技能文档以Invariants一节总结了整套机制的底线理解它们是正确使用技能的前提不变量含义文档是事实来源技能只是一面透镜片段只存在于docs/context/技能目录绝不复制它们技能只持有生成的MAP.md 脚本配置frontmatter 驱动一切sources:同时喂养索引、MAP 和漂移检测fragment 开始覆盖新文件时把它加入sources:并重跑build-map.py引用稳定符号不引用行号每个论断都锚定到可 grep 的符号描述实际交付了什么而非意图是什么不在用户背后自动化同步提醒 → 批准 → 应用没有 git hook交接文档与计划不是文档它们位于docs/context/之外如.context/绝不读取、折叠或扫描进 fragment 输入维护指南深入MAINTAINING.md 补充细节技能是路由器细节属于 MAINTAINING.md。其中有几条对实践者格外重要的补充Scope boundary技能只文档化docs/context/会话 handoffs 与 plans 在.context/等位置是明确的范围外对象mental modeldocs/context/**/*.md事实来源→build-map.py读取全部 frontmatter config → 生成docs/context/README.md人类索引与MAP.md路由/漂移映射Fragment conventions每个 fragment 必须有title、status、sources:、related:四项 frontmatter分类 docs/context/下的子目录一个子系统一个 fragment超过约 150 行就要拆分演进方式新分类 → 给fragments.config的categories加{dir,label}新源码区域 → 加 pathspec 与扩展名上游脚本改进 → 用全局 codemap 技能的 refresh 模式重拷build-map.py/drift.sh不触碰本地 fragment 与配置。一次完整的同步演练综合 Mode B 的五步与 MAINTAINING 的七步工作流一次典型的文档同步是这样完成的# 1. 检测漂移默认范围 origin/main..HEAD bash .agents/skills/tools-registry-context/scripts/drift.sh # 2. 对每个受影响的 fragment读 fragment git diff range -- file # 更新叙述grep 校验引用符号仍存在新文件加入 sources: # 3. 展示给用户 → 获准 → 应用 # 4. 重新生成索引缺 frontmatter 会以退出码 1 告警 python3 .agents/skills/tools-registry-context/scripts/build-map.py # 5. 与代码同 commit 推送docs(context): 前缀这套机制的可复用价值虽然tools-registry-context是 treg 仓库的内部技能但它体现的方法论可以迁移到任何中大型代码库以小片段 frontmatter 元数据组织设计文档、以反向索引解决文档检索、以符号锚定保证文档引用的稳定性、以漂移检测生成器把文档同步变成可验证的机械流程。对 Agent 开发者而言它同时示范了如何设计一个会自己查资料、自己发现文档缺口的上下文技能——冷启动暖机、会话中聚焦、同步前提醒三种模式的分工本身就是一套值得借鉴的 Agent 技能设计范式。相关文件速查技能主体.agents/skills/tools-registry-context/SKILL.md维护协议.agents/skills/tools-registry-context/MAINTAINING.md反向索引.agents/skills/tools-registry-context/MAP.md生成器配置.agents/skills/tools-registry-context/fragments.config漂移检测脚本.agents/skills/tools-registry-context/scripts/drift.sh索引生成脚本.agents/skills/tools-registry-context/scripts/build-map.py人类可读的片段索引docs/context/README.md片段示例foundation 类docs/context/foundation/charter.md片段示例interface 类docs/context/interface/skill.md赞分享后端API网关MCP 服务dsh-plugin【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址https://gitcode.com/GitHub_Trending/treg/treg点击查看免费下载相关推荐Slang 编译期性能基准套件设计解析tools/compile-perf 的架构、工作负载与 CI 漂移检测Slang 编译期性能基准套件设计解析tools/compile perf 的架构、工作负载与 CI 漂移检测本篇技术指南以 tools/compile p编译器图形学编程语言cheat.sh 路由系统设计多源代码片段的智能匹配与整合cheat.sh 路由系统设计多源代码片段的智能匹配与整合 cheat.sh 是一个强大的命令行速查工具它的核心优势在于能够从多个来源智能整合编程语言的代码开发工具文档后端样式漂移怎么查?Fallow CSS 设计系统失同步检测实战样式漂移怎么查?Fallow CSS 设计系统失同步检测实战做前端的朋友都遇到过这种糟心场景:组件库明明定义了完整的设计令牌 Design Tokens ,结创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

treg tools-registry-context 技能全解：设计文档片段路由、漂移检测与代码同步工作流

相关推荐

B2B发布入口的简化设计

GHelper：华硕笔记本的奥创平替，3 步装好不折腾

免费CRM与私人网站的区别：永久在线客户管理系统如何驱动销售闭环

更多资讯

互联网大事记：技术演进与商业变革双线复盘

Windows上用VS2008编译zhparser：PostgreSQL中文全文检索扩展指南

Hugo Blox Portfolio 的 Accomplishments 组件：证书与成就时间线配置实战

通讯优先的CRM系统落地实践：从桌面端到客户档案

MySQL批量删除相同前缀数据表：安全清理与防误删全攻略

Atlas 300V 24G推理加速卡评测：从环境搭建到YOLOv5部署优化

今日更新

AI元人文：从工具使用到思维重构的深度探索

Python+CNN车牌识别实战：从数据预处理到模型训练与部署

Vim基础操作全攻略：保存退出、模式切换与高频命令实战

本周精选

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？