dev-context-multi-repo

多仓库上下文

使用此技能为多个仓库盘点、规范化并发布一个统一的知识中心。最稳妥的默认方案是采用两层系统：原始来源采集内容，以及由 LLM 维护、包含仓库画像、概念页面、反向链接和衍生报告的编译型 Markdown 知识中心。该技能负责发现仓库、提取高价值信息、进行跨仓库推断、生成成套产物并构建知识图谱。它不能替代单仓库上下文或代码图谱工作。

快速参考

任务	使用
发现仓库并分类项目组合形态	scripts/discover_repos.py、references/repo-discovery-patterns.md
扫描仓库并生成规范化画像	scripts/scan_repo.py、scripts/scan_portfolio.py、references/repo-classification-rules.md
构建标准产物集	scripts/build_artifact_set.py、references/output-model-and-gap-analysis.md
构建并验证图谱输出	scripts/build_knowledge_graph.py、scripts/validate_graph.py、scripts/check_graph_consistency.py、references/knowledge-graph-patterns.md
根据证据校准图谱边权重	scripts/calibrate_weights.py、references/knowledge-graph-patterns.md
查询图谱邻域、路径、影响、排名、PPR 和社区	scripts/query_graph.py --node|--from|--impact|--rank|--ppr|--communities、references/knowledge-graph-patterns.md
检测社区（Louvain）并生成各社区摘要	scripts/query_graph.py --communities --resolution、assets/community-summary-template.md
双时态时间切片查询	scripts/query_graph.py --as-of <date> --known-at <date>、references/knowledge-graph-patterns.md §12
创建或运营协调中心	assets/coordination-repo-layout-template.md、references/hub-operations-playbook.md
运行从原始采集到编译型知识库的工作流	docs-notes-retrieval 技能、references/hub-design-patterns.md、references/hub-operations-playbook.md
检查新鲜度和漂移	scripts/report_drift.py、scripts/check_hub_freshness.sh、references/hub-freshness-checking.md

适用场景

• 为多个服务或仓库构建主上下文仓库或文档中心。
• 为每个仓库生成一个规范化画像，而不是临时编写摘要。
• 根据结构化 JSON 画像和图谱边生成一致的仓库描述，而不是手工撰写摘要。
• 对 Agent 运行时、远程桥接器、终端优先的 CLI、插件宿主和工作树协调器等复杂编排仓库进行分类，避免将其归为 unknown。
• 映射整个项目组合中的技术栈、接口、依赖项、负责人和集成边。
• 为入职、迁移规划、架构评审或 RAG 生成知识中心产物。
• 为现有协调中心添加知识图谱。
• 运营包含 raw/ 证据层和编译型 Markdown 维基的仓库项目组合。
• 维护或刷新大型仓库项目组合，包括 100+ 个仓库的知识中心；在这类场景中，增量编译比一次性生成摘要更重要。

重建 Requirements-Hub

assets/hub-scaffold/ 提供了一个可直接复制的空白中心。它的结构与此技能生成的内容相同——热层（AGENTS.md、rules/）、编译层（context/）和一个示例领域文件夹——不包含任何特定组织的内容。

cp -r assets/hub-scaffold ~/repos/requirements-hub

然后，按照 assets/hub-scaffold/context/scripts/README.md 中的说明执行端到端命令序列：discover_repos.py → scan_portfolio.py → build_knowledge_graph.py → query_graph.py --rank → validate_graph.py，接着使用复用的 dev-context-engineering 脚本构建并验证中心自身的上下文图。脚手架中的 rules/ 存根指向 dev-context-engineering/assets/ 中明确标注为通用模板的内容——请将每条法规引用替换为你自己的监管背景。

选择其他路径

• 单仓库上下文层以及跨工具推广：使用 dev-context-engineering。
• 单个仓库内的符号或文件图：使用 dev-context-code-graph。
• 编写规范或决策文档：使用 docs-ai-prd。
• 文档时效性审计：使用 qa-docs-coverage。
• 通过明确委派并行探索多个仓库：使用 agents-swarm-orchestration。

默认做法

• 优先结构化元数据，其次叙述性内容。
• 每个仓库仅维护一个规范档案。
• 先原始摄取，再编译为 Wiki。
• 将仓库知识视为事实来源，并让根目录中的 Agent 文件充当地图，而非百科全书。
• 默认采用即时加载：存储稳定标识符、路径、图节点 ID 和报告链接，并在执行任务时加载相关内容。
• 先读取高信号文件，再深入阅读。
• 将原始证据、规范化元数据和人工摘要分开存放。
• 优先使用原生支持 Markdown 的索引页、摘要和反向链接，再添加更复杂的检索层。
• 让 LLM 维护编译后的中心；由人审阅、精简并纠正偏差，而不是手动编辑每个页面。
• 将持久有效的答案、图表和报告归档到中心，以便随着时间推移不断积累资产组合查询成果。
• 将隐藏的差异化特征视为一等提取目标：传输模型、控制平面、权限桥接、会话生命周期、工作树模型、插件生命周期和恢复策略，往往比语言或包元数据更重要。
• 覆盖不完整时，将声明标记为 verified、subset-verified、inferred 或 unverified。
• 将生成的内容统一存放在一个产物根目录下，而不是分散到各处文档中。
• 不要为每次资产组合查询都创建独立的 Markdown 报告；应将可复用的输出归入中心目录、报告生命周期或生成的上下文产物集合。

2026 年 5 月的立场

当前最佳默认做法不是“索引所有内容，然后塞进提示词”。而是构建一个小型、可导航的上下文系统，以便在运行时选择恰当的证据。

• 保持 AGENTS.md 和同级运行时文件简短；它们应引导 Agent 前往中枢，而不是重复中枢内容。
• 将结构化产物作为编译器输入：配置文件、代码图、系统边、时效性报告和证据引用。
• 将 markdown 作为运维界面：目录页、概念说明、架构图和可复用的查询结果。
• 当关系结构会影响答案时，使用图遍历：依赖路径、归属、影响范围、共享提供方、跨仓库流程、迁移边界，或“帮我快速了解这个系统”之类的问题。
• 对于简单的查找问题，使用词法搜索、索引页或直接读取文件；每个查询都优先使用图检索会增加延迟和噪声。
• 当问题以仓库、领域或流程为起点，但需要超出 1～2 跳邻域且受预算限制的上下文时，使用 Personalized PageRank。
• 当问题是全局性的（“平台是什么样的？”），且单个种子节点的遍历会遗漏整体结构时，使用多个分辨率的社区检测（--communities）。当作品集超过 1k 个节点且需要更强的连通性保证时，通过 igraph 或 graspologic 引入 Leiden。
• 当说明文字、Mermaid、清单和架构都提供边时，校准权重；来自多个来源的直接证据应优先于来自单一来源的说明文字边。
• 将符号级图保留为 dev-context-code-graph 生成的每仓库产物；将摘要或链接导入中枢，而不是把每个符号都合并到作品集图中。
• 发布前应用上下文卫生门槛：相关性、来源、时效性、ACL/敏感性范围、矛盾风险和有界的 token 规模。
• 优先动态裁剪无关的图社区或子图，而不是使用静态的“包含整个图”提示词。

工作流

1. 清点候选仓库并分类仓库形态。
2. 先索引原始证据：仓库根目录、架构文档、API 契约、数据集、屏幕截图及其他来源记录应存放在原始层，而不是被压平成摘要。
3. 仅阅读高信号的清单、文档、CI 文件、架构线索和指令产物。
4. 将证据规范化为每个仓库一个 RepoProfile。
5. 如果仓库看起来是以编排为主的运行时，则围绕传输、远程/会话、审批、工作树、插件和恢复文件深入扫描，然后再接受通用分类。
6. 推断仓库类型、接口、依赖关系、存储、归属和能力类别，但不要过度断言。
7. 根据规范化配置文件和关系边，为每个仓库生成或刷新一份仓库描述，并根据证据覆盖率标注置信度。
8. 增量编译 markdown 中枢：仓库目录页、跨仓库概念说明、反向链接和索引文件，帮助 Agent 导航，而无需每次都扫描整个语料库。
9. 尽可能只重建发生变化的页面、索引和图边；默认不要重新汇总整个作品集。
10. 生成产物集：配置文件、目录页、图和报告。
11. 验证图的一致性和时效性，然后运行中枢健康检查，检查过时的断言、缺失的摘要、未编入索引的报告，以及值得新增的候选页面，再将中枢标记为最新。

ASCII 流程图

multi-repo context request
  -> discover repos and classify portfolio shape
  -> ingest raw evidence without flattening it into prose
  -> scan high-signal files into one RepoProfile per repo
  -> build compiled hub: catalog pages, indexes, backlinks, reports
  -> build graph artifacts: system edges and knowledge graph
  -> query with lexical search, direct reads, graph paths, PPR, or communities
  -> validate coverage, freshness, consistency, and unindexed outputs
  -> publish only durable hub artifacts, not free-floating reports

核心决策

输出模型

默认产物集：

• profiles/<repo>.json
• catalog/<repo>.md
• graphs/system-edges.json
• graphs/knowledge-graph.json
• reports/coverage.md
• reports/drift.json

除非下游使用方需要转换层，否则不要另造其他结构。

默认将 catalog/ 和 reports/ 作为编译后的 Markdown 层。只有在有明确的下游使用方需要概念文章或查询输出时，才添加 concepts/ 或 research/ 等文件夹。

仓库描述页通常应根据以下内容生成：

• profiles/<repo>.json 中经过验证的字段
• graphs/system-edges.json 中的关系边
• 数量有限的直接证据引用

不要让描述页沦为缺乏依据的文字摘要。

对于复杂仓库，配置文件应记录能力类别，而不只是表层元数据。可靠的配置文件通常需要包含以下字段或衍生章节：

• 运行时或部署模式
• 控制平面和传输模型
• 远程或桥接职责
• 会话与恢复语义
• 权限与审批流程
• 工作树或并行任务隔离模型
• 插件、钩子或热重载生命周期
• 恢复或重试策略

提取策略

从能快速揭示仓库实际情况的文件入手：

• 清单和锁文件
• CI 工作流
• 容器和基础设施文件
• 原生或移动项目清单，例如 Package.swift、project.yml、.xcodeproj 和 .xcworkspace
• 架构文件和迁移文件
• API 契约
• 仓库指令文件
• 规范和计划

如果中心还存储非仓库证据，应将这些内容保留在原始层，并将其摘要整理到编译后的中心，而不是把截图、导出文件或文章剪辑当作一等目录页面。

只有在高信号层不足以对仓库分类或证明集成时，才进行深入读取。

对于编排密集型仓库，高信号层必须包含运行时核心文件，而不只是清单：

• 传输实现
• 远程桥接或客户端／服务端会话管理器
• 权限和审批桥接代码
• 工作树和任务编排设置
• 插件、钩子和热重载加载器
• 重新连接、背压、批处理和恢复逻辑

许多最重要的差异化特征无法从包元数据中看出。如果提取器只检查语言、锁文件和 README 文本，就会低估那些真正胜在运行时设计上的仓库。

复杂运行时分类

如果仓库包含以下多项对应的文件或模块，应优先归类为复杂运行时，而不是 unknown：

• 远程桥接或远程执行支持
• 明确的传输抽象，例如 SSE、WebSocket 或混合读写传输
• 会话管理器或恢复生命周期
• 权限或审批中介机制
• 任务、协调器、协作者或工作器编排
• 工作树创建、分支隔离或 tmux／会话引导
• 插件、钩子或延迟加载器基础设施
• 明确的恢复、抑制重试、缓冲或背压机制

值得识别的典型分类：

• Agent 运行时
• 编码 Agent CLI
• 远程执行桥接
• 终端 UI 宿主
• 插件平台
• 多仓库协调器

验证范围

综合整理前：

• 区分直接证据与推断出的结构
• 除非检查了所有相关仓库，否则避免对整个项目组合做出普遍性断言
• 根据清单和驱动程序验证存储引擎，而不是依据 README 文本
• 在摘要和表格中明确标注覆盖不完整的部分

生成仓库描述时：

• 区分由清单或工作流证实的内容，与根据命名或拓扑推断的内容
• 优先采用简洁、结构化的描述，不要营造叙述上的确定感
• 无法可靠分类仓库时，明确列出未知项

知识图谱

当枢纽需要查询跨仓库、系统和制品之间的关系时，使用知识图谱。不要在这一层处理符号级图谱工作；这属于单仓库代码图谱工作流。

图谱是 Markdown 枢纽的补充，而非替代。最佳默认做法是使用图谱支持的 Markdown 页面，配有反向链接、索引笔记和简明摘要，让 Agent 在语料规模较小或中等时可以直接阅读。

对于复杂运行时，除了依赖关系边，还要添加能力和行为边。实用示例：

• uses_transport
• splits_read_write_channels
• supports_resumable_streams
• bridges_permissions
• manages_remote_sessions
• supports_worktree_isolation
• supports_plugin_hot_reload
• serializes_writes
• buffers_stream_events
• has_recovery_policy

问答和衍生输出

优先将答案保存为文件，而不是仅输出到终端：

• 针对架构问题或迁移映射的 Markdown 报告
• 用于展示关系的 Mermaid 或其他图表
• 如果有可用的查看器，且问题偏重演示，则使用幻灯片或图像输出

如果答案很可能会再次派上用场，就将其存入枢纽，并从相关仓库或概念页面链接到它。

添加文件前，先运行枢纽归档检查：

• 它是否属于现有的仓库目录、概念页面或报告？
• 它是否会从枢纽索引或相关仓库页面链接到？
• 它是否由结构化输入生成？如果是，是否知道重建命令？
• 如果它是某个时间点的分析，是否有生命周期状态？

如果都不是，就将其留在任务线程中，或更新现有枢纽页面。

在 100+ 个仓库规模下运行

在大型项目组合规模下，应优化维护循环，而不是追求一次性的高强度扫描：

• 维护仓库注册表和上次刷新状态
• 增量编译，而不是每次运行都重建每个页面
• 维护简短的索引页面，帮助 LLM 快速找到合适的仓库或概念
• 优先采用可进行差异比较、检查和修复的 JSON、Markdown 和图谱制品
• 在采用更重型的检索系统之前，先添加轻量级 CLI，用于搜索、新鲜度检查和定向重建

枢纽布局

优先使用包含以下内容的协调仓库：

• 根目录入口文件
• 根目录下的领域文件夹
• 位于 context/ 或 docs/context/ 下的生成式枢纽基础设施
• 可选的 raw/ 采集区域，用于存放 LLM 编译到枢纽中的证据

让根目录专注于导航。不要将清单粘贴到 AGENTS.md 中。

对于原生／移动仓库，默认扫描器应先根据高信号项目文件进行分类，再回退到通用语言启发式规则。如果存在 project.yml、.xcodeproj 或 .xcworkspace 证据，Swift/Xcode 仓库应被准确识别为 app 仓库；扫描还应忽略 .build、DerivedData、Pods 和 SourcePackages 等生成的构建目录。

输出模式

默认采用以下模式之一：

• 项目组合清单： 仓库注册表、分类和扫描覆盖范围。
• 上下文枢纽： 配置文件、目录页面、关系边和知识图谱。
• 编译式 Wiki： 原始证据注册表、Markdown 索引、概念笔记、反向链接和可复用的查询输出。
• 仓库描述集： 根据配置文件 JSON、图谱边和已验证证据，为每个仓库编译一个有依据的页面。
• 能力映射： 根据源代码证据（而不是 README 级别的摘要）整理每个仓库的运行时能力、差异化特点和运行行为。
• 迁移映射： 活跃与旧版系统、集成边和迁移热点。
• 新鲜度报告： 偏差、过时文档和待重新验证队列。

已知陷阱

• 过早接受笼统的仓库分类，忽略了真正能区分编排器、桥接器或控制平面的实际运行行为。
• 把 README 内容繁多的仓库当作权威信息来源，而清单、工作流和运行时脚本却表明事实并非如此。
• 每次扫描都重新构建整个知识中心，而不是根据实际发生变化的仓库增量编译。
• 在将推断出的跨仓库关系固化为“事实”之前，没有追溯到清单、架构或具体集成证据。
• 把组合概览当作事实来源，同时底层原始证据和规范化档案却悄然出现偏差。
• 将更长的模型上下文窗口视为加载整个知识中心的许可；大量无关上下文仍会造成干扰和上下文退化。
• 即使直接查询目录、词法搜索或有限范围的文件读取更加准确，也对所有问题使用 GraphRAG 或图遍历。
• 任由生成的 Markdown 和生成的 JSON 各自偏离，而不是根据结构化档案和图契约重新生成说明文字。
• 将 LLM 生成的摘要作为新证据重新导入，却没有保留原始来源和时间戳。

反模式

• 将单个仓库摘要当作组合模型。
• 没有经过验证的扫描注册表，却声称覆盖完整。
• 在同一个文件中混合原始证据、规范化数据和评论。
• 根据文档而非清单验证存储或运行时相关声明。
• 将有用的组合问题答案留在聊天输出中，而不归档到知识中心。
• 将组合清单粘贴到根目录的 Agent 记忆文件中。
• 将符号级代码图强行纳入组合知识图谱。
• 索引页面、简洁摘要和反向链接尚未维护，就急于采用繁重的 RAG。
• 只有部分仓库发生变化，却从头重写 130 个仓库的描述。
• 根据聊天印象直接编写仓库描述，而不是依据档案 JSON 和图边。
• 扫描器只检查清单和 README 文本，导致复杂仓库一直标记为 unknown。
• 只建模依赖关系，却遗漏权限桥接、会话控制平面、可恢复流或工作树隔离等运行关系。
• 用向量数据库、GraphRAG 技术栈或 MCP 服务替代仓库自有档案、证据引用和新鲜度检查。
• 声称拥有“完整代码库上下文”，却不提供解析覆盖率、扫描日期、排除路径和不支持的语言说明。
• 在同一上下文层中混合公开文档、私有代码证据、机密信息和客户数据，却不标注敏感级别，也不设置访问边界。

导航

• 核心参考资料：references/repo-discovery-patterns.md、references/repo-classification-rules.md、references/architecture-inference-rules.md、references/integration-signal-detection.md、references/confidence-scoring.md
• 中心仓库与图谱操作：references/output-model-and-gap-analysis.md、references/knowledge-graph-patterns.md、references/hub-design-patterns.md、references/hub-operations-playbook.md、references/hub-freshness-checking.md、references/large-portfolio-strategy.md
• references/network-science-applied.md — 将中心性、PageRank、社区检测、传染效应应用于多仓库知识图谱和项目组合拓扑。
• 资源：assets/hub-scaffold/（可复制粘贴的空白中心仓库——参见“重建 Requirements-Hub”）、assets/coordination-repo-layout-template.md、assets/repo-catalog-page-template.md、assets/architecture-map-template.md、assets/integration-matrix-template.md、assets/freshness-report-template.md、assets/legacy-transition-map-template.md、assets/hub-agents-template.md
• 脚本和架构：scripts/discover_repos.py、scripts/scan_repo.py、scripts/scan_portfolio.py、scripts/build_artifact_set.py、scripts/build_hub_views.py、scripts/build_knowledge_graph.py、scripts/query_graph.py、scripts/validate_profiles.py、scripts/validate_graph.py、scripts/check_graph_consistency.py、scripts/report_drift.py、scripts/check_hub_freshness.sh、schemas/repo-profile.schema.json、schemas/knowledge-graph.schema.json、schemas/system-edge.schema.json

事实核查

• 在将已知缺陷、回归问题、框架／编译器／运行时的易错点，以及特定版本的崩溃或规避方案视为当前事实之前，必须依据当前的第一手网络来源进行核实。
• 外部来源映射位于 data/sources.json。
• 项目组合摘要必须区分已核实的事实与推断出的边。
• 如果某项声明无法追溯到清单、架构、工作流或其他直接证据，应明确标注，而不是将其当作事实定论。