Skill Seekers sync-config 完全指南将配置中的文档 URL 与线上站点实时同步【免费下载链接】Skill_SeekersConvert documentation websites, GitHub repositories, and PDFs into Claude AI skills with automatic conflict detection项目地址: https://gitcode.com/gh_mirrors/sk/Skill_Seekers本文以 Skill Seekers 的sync-config命令为切入点讲解如何将抓取配置config JSON中的start_urls与文档网站的当前实际状态进行比对自动发现新增页面、失效页面与 URL 变更。你将掌握在 Claude Code 插件中以/skill-seekers:sync-config斜杠命令使用该功能、通过skill-seekers sync-config命令行精细控制同步过程、理解 BFS 链接发现与 diff 的底层原理以及如何将同步结果安全地写回配置文件并触发重新抓取。sync-config 解决什么问题文档网站是持续演进的新版本发布会增加页面、旧页面可能被删除或改版迁移。而 Skill Seekers 的抓取配置中start_urls记录了要抓取的文档页面清单。如果这份清单长期不更新生成的 Skill 就会缺失新内容或引用失效链接导致知识库质量下降。sync-config命令的核心职责正如其在 源码 开头的文档字符串所描述的Sync a config files start_urls against whats currently live on a docs site. Crawls navigation links from seed pages, diffs them against the configsstart_urls, and optionally writes the updated list back.即以配置中的种子页面为起点爬取站点导航链接 → 与配置中已有的start_urls做差异比对 → 报告新增/移除/变更 → 可选地将最新 URL 清单写回配置文件。它只同步 URL 清单不下载页面正文因此比完整重新抓取轻量得多。在 Claude Code 插件中该命令的定位是让既有 Skill 保持新鲜与create-skill从零创建、install-skill全流程安装形成互补。插件 README 中将其描述为 Sync config URLs against live docs。在 Claude Code 插件中使用基本用法在 Claude Code 会话中直接调用斜杠命令/skill-seekers:sync-config config-path-or-name参数可以是配置文件路径也可以是预设名preset name。插件文档 sync-config.md 给出了两个典型示例/skill-seekers:sync-config configs/react.json /skill-seekers:sync-config react第一种写法直接指定仓库内 configs/ 目录下的配置文件第二种写法传入预设名如react、godot由插件在configs/目录中查找对应的react.json或通过 API 获取。插件侧的指令流程根据 sync-config.md 的 Instructions 部分当用户通过$ARGUMENTS提供配置路径或预设名后Claude 需要按以下步骤执行解析参数来源如果是预设名如react、godot先在configs/目录中查找对应配置找不到再从 API 获取。执行同步命令运行skill-seekers sync-config $CONFIG。汇报变更向用户报告发现了哪些新 URL、移除了哪些 URL以及存在的冲突。询问后续动作询问用户是否要更新配置并重新抓取。这套流程将检测变更与落地变更分成两步把最终是否改配置、是否重新抓取的决定权交给用户避免 Agent 擅自修改知识库。命令行等价操作插件最终调用的是底层 CLI。你也可以在终端中直接执行skill-seekers sync-config --config configs/react.json skill-seekers sync-config --config configs/react.json --apply第一条命令是**干跑dry-run**模式只输出差异报告第二条加上--apply才会把更新后的start_urls写回配置文件。命令在 main.py 中以sync-config: skill_seekers.cli.sync_config注册也可通过python -m skill_seekers.cli.sync_config独立执行。命令行参数详解sync-config的所有参数定义在 arguments/sync_config.py完整参数如下参数简写类型默认值说明--config-cstr必填要同步的配置 JSON 文件路径--apply—flagFalse将更新后的start_urls写回配置文件默认干跑--depth—int2从种子页面开始的 BFS 爬取深度--max-pages—int-1无限制最多发现的页面数-1表示不限制--rate-limit—float使用配置值两次 HTTP 请求之间的等待秒数覆盖配置中的rate_limit--source-index—int0要同步的 documentation 源在sources数组中的下标--verbose-vflagFalse输出详细信息--quiet-qflagFalse抑制信息输出几个关键参数的行为细节--apply默认关闭。只有在检测到新增或移除的 URL 时才会写回文件如果配置已是最新即使加了--apply也不会触碰文件有测试专门验证这一点。--depth控制 BFS 跳数。depth1只发现种子页面的直接链接depth2还会发现这些页面的子链接。深度越大发现越全但请求量也越大。--max-pages发现上限保护避免大型站点造成过多请求。默认值来自 defaults.json 中scraping.max_pages -1即默认不限制。--source-index支持多源配置。一个配置的sources数组中可能同时有多个documentation源例如同时抓取中文与英文文档该参数选择同步哪一个。测试 test_sync_config.py 的TestSyncConfigCLI验证了这些默认值applyFalse、depth2、max_pages-1、rate_limitNone、source_index0。配置文件结构统一格式与旧版扁平格式sync-config需要从配置中提取文档源信息。它兼容两种格式见 源码 的_get_doc_source统一格式unified配置含sources数组命令从中筛选type documentation的源。以 configs/react.json 为例{ name: react, version: 1.1.0, sources: [ { type: documentation, base_url: https://react.dev/, extract_api: true, selectors: { main_content: article, title: h1, code_blocks: pre code }, url_patterns: { include: [], exclude: [/blog/, /community/] }, rate_limit: 0.5 }, { type: github, repo: facebook/react } ], base_url: https://react.dev/ }旧版扁平格式legacybase_url与start_urls直接位于配置顶层没有sources数组。命令通过config.get(base_url)是否存在来判断。影响同步行为的关键字段从 sync_config.py 的实现可以看出以下字段直接决定同步结果字段作用base_url域名前缀白名单只有以它开头的 URL 才会被接受start_urls当前已配置的抓取页面清单与发现结果做 diff 的基准nav_seed_urlsBFS 的种子页面存在时优先于start_urls见测试test_nav_seed_urls_used_over_start_urlsurl_patterns.includeURL 必须包含的子串列表任一命中即通过url_patterns.excludeURL 不得包含的子串列表任一命中即拒绝rate_limit请求间隔单位为秒配置级的速率控制种子页面的选择逻辑是nav_seed_urls优先 → 否则用start_urls→ 再否则用base_url。如果你只想从文档首页的导航菜单开始发现链接可以在配置中显式指定nav_seed_urls这样即使start_urls之后被--apply整体替换种子也不会丢失。url_patterns的过滤规则与文档抓取器保持一致源码注释明确说明 mirrors DocToSkillConverter.is_valid_url logicURL 必须满足startswith(base_url)、命中任一 include 模式、且不命中任何 exclude 模式三条件同时满足才有效。底层原理BFS 链接发现与差异比对轻量级 BFS 发现discover_urls核心函数 discover_urls 实现了一个轻量级的广度优先爬虫以种子 URL 初始化队列每个元素携带当前深度。弹出一个 URL先检查是否访问过、是否通过 URL 过滤。发起requests.get请求带User-Agent: Mozilla/5.0 (Skill-Seekers sync-config)、15 秒超时。只有成功获取未抛异常的 URL 才计入 discovered 集合——404 或网络错误意味着该页面在线上已不存在。若未达到depth上限用 BeautifulSoup 解析页面中所有a href链接用urljoin解析相对链接、剥离#锚点片段、经sanitize_url清洗后入队。若rate_limit 0每次请求后 sleep 相应秒数礼貌抓取。测试 test_sync_config.py 的TestDiscoverUrls覆盖了关键行为外部链接被过滤、深度限制生效深度超限的孙页面只发现不继续追踪、max_pages封顶、HTTP 错误不崩溃、锚点片段被剥离为同一 URL。差异比对diff_urls比对逻辑极简但精确见 diff_urlsdef diff_urls(discovered: set[str], configured: list[str]) - tuple[list[str], list[str]]: configured_set set(configured) added sorted(discovered - configured_set) removed sorted(configured_set - discovered) return added, removedadded线上存在但配置中没有的 URL新页面removed配置中有但线上已无法成功获取的 URL失效页面。两组结果均排序输出保证报告稳定可读。TestDiffUrls对空配置、空发现、同时增删、排序等边界情况都有断言。报告与写回sync_config主流程sync_config.py在 diff 之后无变化时输出Config is up to date. No changes detected.有变化时输出带/-前缀的 URL 清单路径部分相对base_url展示以及汇总行Summary: N new, M removed (discovered X total, configured Y)。--apply模式下将完整的新发现集合而非仅新增项排序后写入正确的start_urls字段统一格式写入sources[idx].start_urls旧版格式写入顶层start_urls文件以indent2, ensure_asciiFalse重写。除start_urls外的所有字段保持不变——E2E 测试test_sync_config_preserves_other_config_fields验证了name、description、version、selectors、rate_limit以及同数组中的 github 源均不受影响。有变化但未加--apply时提示Run with --apply to update config。从 MCP 工具调用Agent 自主同步sync-config功能同样以 MCP 工具形式暴露封装在 mcp/tools/sync_config_tools.py 的sync_config_tool中。它接受以下参数参数默认值说明config_path必填配置 JSON 文件路径applyFalse是否写回变更depth2BFS 深度max_pages500最大发现页数rate_limit配置值请求间隔source_index0文档源下标工具返回结构化的文本报告新增/移除清单 汇总并在applytrue时提示文件已更新。缺少config_path或文件不存在时返回明确的错误文本。这也解释了 Claude Code 插件中 Agent 如何自主完成同步skill-builder技能会自动识别用户意图并调用对应 MCP 工具。MCP 工具层面的测试可见 test_mcp_tools_common.py其中验证了sync_config_tool({})缺少参数时返回错误。端到端验证与真实站点集成仓库提供了两层测试来验证 sync-config 的可靠性E2E 本地服务器测试test_sync_config_e2e.py启动一个内存版多页面文档站含/docs/导航、嵌套页面、/blog/站外路径、GitHub 外链验证从根页面能发现全部 8 个/docs/页面而/blog/与外部域名被排除depth1只发现直接子页面嵌套页面不被纳入include/exclude 模式生效干跑不修改文件--apply正确写回全部发现 URL幂等性第一次--apply后第二次运行检测不到任何变化不会重复写文件配置中不存在的 URL 被正确识别为 removed配置中的非start_urls字段在同步后保持不变。真实站点集成测试TestSyncConfigRealSite默认跳过需-m integration运行以https://docs.python.org/3/library/为基准验证discover_urls对真实 HTTP 站点的兼容性——只发现base_url前缀内的 URL。CLI 子进程测试直接以子进程方式调用python -m skill_seekers.cli.sync_config验证干跑输出包含 new page、--apply后配置文件被更新、--help正常、不存在的配置路径返回非零退出码。推荐的工作流与注意事项典型工作流保持 Skill 新鲜度/skill-seekers:sync-config react # 1. 干跑查看差异 /skill-seekers:sync-config configs/react.json --apply # 2. 确认后写回 # 3. 重新抓取或增量更新让 Skill 纳入新页面将第 1 步的干跑结果与用户确认后再执行第 2 步是插件文档建议的安全路径——sync-config本身只更新 URL 清单不会触发重新抓取需要用户确认后再执行抓取命令。注意事项--apply是破坏性操作它用线上发现到的全部 URL整体替换start_urls。如果某次抓取因网络原因只发现部分页面可能导致清单缩水。建议先干跑、检查total_discovered是否合理再决定是否应用。base_url决定边界发现过程只接受base_url前缀内的 URL。多语言站点请确认前缀设置正确必要时用--source-index分别同步不同文档源。善用url_patterns.exclude在配置中排除/blog/、/changelog/等非正文页面参考 react.json 的做法既避免无效发现也减少请求量。控制--depth与--max-pages大型站点建议限制深度与最大页数配合--rate-limit礼貌抓取避免被站点限流。旧版扁平配置兼容如果仍在使用旧格式顶层base_url/start_urlssync-config 可以直接读取并写回但建议迁移到带sources数组的统一格式以获得多源支持与更清晰的字段归属。小结sync-config是 Skill Seekers 知识库保鲜机制的关键一环它通过轻量 BFS 发现线上文档的真实 URL 集合与配置中的start_urls做集合差输出新增/移除报告并可在确认后安全写回。无论是 Claude Code 中的/skill-seekers:sync-config斜杠命令、独立的skill-seekers sync-configCLI还是 MCP 的sync_config工具底层都复用同一套 sync_config.py 实现参数与行为保持一致。理解了过滤规则、种子选择与 diff 语义你就能精确控制文档同步让基于文档构建的 Claude Skills 始终与官方站点保持同步。【免费下载链接】Skill_SeekersConvert documentation websites, GitHub repositories, and PDFs into Claude AI skills with automatic conflict detection项目地址: https://gitcode.com/gh_mirrors/sk/Skill_Seekers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
