用 INTEGRATIONS.md 模板系统化梳理代码库外部集成来自 acquire-codebase-knowledge 技能的最佳实践【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot本指南聚焦于 GitHub Copilot 生态社区仓库 awesome-copilot 中 acquire-codebase-knowledge 技能所附带的INTEGRATIONS.md模板讲解如何系统化盘点一个代码库的全部外部集成——外部 API、数据库、密钥处理、可靠性策略与可观测性——并产出一份可追溯、可验证的集成文档。读完本文你将掌握模板中六大必需区块与可选扩展区块的填写方法、每个字段的证据收集路径以及如何结合scan.py的扫描输出把代码库对外依赖变成可审计、可交接的工程资产。模板在技能工作流中的定位INTEGRATIONS.md是 acquire-codebase-knowledge 技能七大输出文档之一位于 assets/templates/INTEGRATIONS.md。该技能的目标是在目标仓库下生成docs/codebase/目录其中固定包含七份文档STACK.md、STRUCTURE.md、ARCHITECTURE.md、CONVENTIONS.md、INTEGRATIONS.md、TESTING.md、CONCERNS.md并在 SKILL.md 中通过Output Contract输出契约强制约束——文档中的每一条结论都必须可追溯到源文件、配置文件或终端输出未知项一律标记为[TODO]依赖团队意图的决策标记为[ASK USER]。在 SKILL.md 规定的四阶段工作流中INTEGRATIONS.md在 Phase 3填充模板中位列第五紧随CONVENTIONS.md之后STACK.md— 语言、运行时、框架与全部依赖STRUCTURE.md— 目录布局、入口、关键文件ARCHITECTURE.md— 分层、模式、数据流CONVENTIONS.md— 命名、格式、错误处理、导入规范INTEGRATIONS.md— 外部 API、数据库、认证、监控TESTING.md— 测试框架、文件组织、Mock 策略CONCERNS.md— 技术债、缺陷、安全风险、性能瓶颈它被排在 STACK 与 STRUCTURE 之后是因为盘点外部集成必须建立在对技术栈知道用什么客户端库和目录结构知道封装层在哪里已有认知的基础上。同时它又早于 CONCERNS因为集成点的脆弱性、密钥泄露风险、超时配置缺失等发现往往是后续安全与性能风险章节的一手证据来源。必需区块一Integration Inventory集成清单模板要求以一张清单表回答这个代码库到底对外调用了什么SystemType (API/DB/Queue/etc)PurposeAuth modelCriticalityEvidence[name][type][purpose][auth][high/med/low][file]六个字段分别回答集成对象是谁系统名、它属于哪一类交互外部 HTTP API、数据库、消息队列、文件存储、第三方 SaaS 等、业务上为什么要连它、用什么认证模型API Key、OAuth 2.0、JWT、mTLS、连接字符串等、故障时对系统的影响等级以及证据出处具体文件路径。关于如何发现这些集成references/inquiry-checkpoints.md 第 5 节给出了非常具体的检索路径外部 API在源码中搜索axios.、fetch(、http.Get(等调用以及常量文件中的 base URL数据库检查 manifest 文件中的pg、mongoose、prisma、typeorm、sqlalchemy等驱动或 ORM 包名网关与代理确认应用与外部服务之间是否存在 API Gateway、服务网格service mesh或反向代理消息中间件查找 Kafka、RabbitMQ、SQS、Pub/Sub 等队列或事件总线的接入代码。这条检查清单与scan.py的探测能力是配合关系扫描脚本负责给出全量候选manifest、配置文件、目录树而清单负责把候选转成集成事实。填写时严格遵循技能总纲的纪律——只记录能从代码验证的东西例如不能仅凭一个dbUrl变量名就断言数据库类型而应去 manifest 中确认是否存在pg、mysql2、mongoose、prisma等依赖见 SKILL.md 中的 Anti-Patterns 表格。必需区块二Data Stores数据存储与集成清单并列的是系统自己持有/访问哪些存储StoreRoleAccess layerKey riskEvidence[db/cache/etc][role][module][risk][file]Store存储实例本身如 PostgreSQL、Redis、Elasticsearch、S3、本地文件系统Role它在系统中的角色——是主数据库、缓存层、搜索引擎、还是对象存储Access layer访问该存储的代码模块如仓储层repositories/、缓存封装cache/、数据访问层Key risk该存储的突出风险例如缺少迁移、无索引、缓存一致性隐患、单点部署Evidence支撑上述判断的文件路径。这部分与架构文档ARCHITECTURE.md的数据流章节共享证据基础但视角不同架构文档回答数据如何流动INTEGRATIONS 的 Data Stores 关注存储本身的角色划分与风险暴露。填写时同样要从 manifest 与源码确认访问层模块的真实位置不能凭目录名猜测。必需区块三Secrets and Credentials Handling密钥与凭据处理密钥处理是集成文档中安全价值最高的一节模板给出三个固定检查点Credential sources凭据来源env/secrets manager/config——记录凭据实际从哪里读取。技能总纲在 SKILL.md 的 Gotchas 中特别提醒密钥永远不会被提交到仓库应通过.env.example、.env.template或.env.sample来发现项目要求的全部环境变量这些模板文件才是需要哪些凭据的合法证据Hardcoding checks硬编码检查记录是否发现凭据被硬编码在源码、配置或注释中并给出结果与位置Rotation or lifecycle notes轮换与生命周期记录凭据轮换机制是已知还是未知。scan.py为这一节提供了辅助证据。脚本内置的SECURITY_CONFIGS列表见 scripts/scan.py会探测.snyk、security.txt、SECURITY.md、.dependabot.yml、sbom.json、sbom.spdx、.bandit.yaml等安全与合规配置文件并在扫描输出的SECURITY COMPLIANCE区块中汇总。若仓库中存在这些文件意味着团队已有安全基线凭据处理策略可能在这些配置中有所体现若不存在应明确记为未知项[TODO]而不是替团队臆测。必需区块四Reliability and Failure Behavior可靠性与故障行为这一节回答外部调用失败时系统会怎样是集成文档中最容易被忽略、却在线上事故中价值最高的部分Retry/backoff behavior重试与退避implemented/none/partial——记录外部调用是否配置了重试是否带指数退避Timeout policy超时策略记录在哪里配置如 HTTP 客户端、连接池、环境变量值是多少Circuit-breaker or fallback behavior熔断与降级记录是否存在熔断器如 resilience4j、Hystrix、Polly或降级兜底逻辑。在检索这类证据时可以把集成清单中标记为high关键度的系统作为重点排查对象。实际经验中很多仓库存在重试没有退避超时值写死在常量里失败直接抛异常无降级等问题这些发现应如实记录为none或partial并在后续CONCERNS.md中转化为风险条目——例如 CONCERNS.md 的Performance and Scaling Concerns与Top Risks表格都要求携带证据与影响分析可靠性的缺口正是典型的高价值风险输入。必需区块五Observability for Integrations集成的可观测性外部集成是故障的高发地带可观测性决定了故障时能否快速定位。模板要求记录三个层次Logging around external calls外部调用日志yes/no 具体位置——记录出站调用是否有日志日志是否包含请求/响应摘要、耗时、状态码Metrics/tracing coverage指标与链路追踪yes/no 具体位置——记录是否有 APM、Prometheus 指标、分布式追踪如 OpenTelemetry覆盖到外部调用Missing visibility gaps可见性缺口列出当前观测不到的部分例如第三方回调无入站日志队列消费延迟无指标数据库连接池水位不可见。填写依据同样要落到文件例如在 references/inquiry-checkpoints.md 第 5 节中明确要求确认监控或可观测性工具是什么APM、Prometheus、日志管线。scan.py也会在PERFORMANCE TESTING区块探测benchmark、perf.data、k6.js、locustfile.py、jmeter.jmx等性能与压测标记见 scripts/scan.py这些标记的位置往往与观测基础设施共存可作为定位日志与指标配置的辅助线索。必需区块六Evidence证据清单每个模板区块都要求携带证据INTEGRATIONS.md 的末尾则要求汇总三类证据路径path/to/integration-wrapper— 集成封装层HTTP 客户端封装、Repository 实现、SDK 包装模块path/to/config-or-env-template— 配置或环境变量模板.env.example、配置文件、连接配置path/to/monitoring-or-logging-config— 监控或日志配置。这一设计直接呼应技能总纲的 Output Contract 第 2、4 条每条结论必须可追溯到源文件、配置或终端输出每份文档必须包含具体的证据文件路径列表SKILL.md。证据是 INTEGRATIONS.md 与普通架构笔记的本质区别——它让文档可以被审计、被复核也让后续维护者在代码变更时能快速判断文档是否已过时。可选扩展区块按需加深模板在必需区块之外提供了四个可选扩展方向仅在仓库复杂度确实需要时启用Endpoint-by-endpoint catalog逐端点目录对每个外部 API 的每个端点记录方法、路径、参数、错误码适合网关类或 SDK 密集的项目Auth flow sequence diagrams认证流程时序图当认证涉及多步握手OAuth 授权码、令牌刷新、mTLS 证书交换时用时序图把流程固定下来SLA/SLO per integration按集成的 SLA/SLO记录每个外部依赖承诺的可用性/时延指标以及本系统的预算Region/failover topology notes区域与故障转移拓扑多区域部署或多活架构下记录外部依赖的地域分布与故障转移路径。是否启用扩展区块的判断标准与技能总纲中的Template usage mode一致默认模式只完成所有必需区块扩展模式仅在仓库复杂度证明其必要时才添加SKILL.md。与扫描脚本的协同从候选到事实INTEGRATIONS.md的填写并不是纯手工活它与 scripts/scan.py 构成扫描候选 → 人工取证的两段式流水线。Phase 1 中从目标仓库根目录运行python3 $SKILL_ROOT/scripts/scan.py --output docs/codebase/.codebase-scan.txt其中$SKILL_ROOT是技能目录的绝对路径跨平台适用于 Windows、macOS、Linux要求 Python 3.8 与 git见 SKILL.md 的元信息。扫描脚本会输出CI/CD PIPELINES检测 GitHub Actions、GitLab CI、Jenkins、CircleCI 等配置CI_CD_CONFIGS字典见 scripts/scan.py这些流水线本身常含外部集成的部署与回调信息CONTAINERS ORCHESTRATIONDocker、Docker Compose、Kubernetes、Vagrant 配置CONTAINER_FILES列表见 scripts/scan.py容器编排文件是发现外部依赖依赖服务、卷、网络的高价值来源SECURITY COMPLIANCESnyk、Dependabot、SECURITY.md、SBOM 等见上文为密钥与合规小节提供基线证据CODE METRICS与PERFORMANCE TESTING文件规模、代码行数、压测标记用于识别高风险集成点的复杂度信号。扫描输出解决的是有什么可查而 INTEGRATIONS.md 的每个区块解决的是事实是什么、证据在哪。二者结合正好落实技能总纲反复强调的纪律只记录能从文件或终端输出验证的内容绝不推断或假设无法确认的标[TODO]依赖团队意图的标[ASK USER]并在 Phase 4 的强制验证循环中复查每一条非平凡结论是否都有证据引用。典型填写误区与正确姿势结合技能总纲的 Anti-PatternsSKILL.md与模板字段设计可以提炼出填写 INTEGRATIONS.md 时最常见的几个误区❌ 错误做法✅ 正确做法凭一个变量名dbUrl就推断数据库类型在 manifest 中确认pg、mysql2、mongoose、prisma等依赖后再下结论把dist/、build/、node_modules里的调用模式当成集成事实只以源码目录中的实现为证据扫描脚本的EXCLUDE_DIRS同样排除这些产物目录见 scripts/scan.pyREADME 说用了 Redis 就直接记录README 常描述预期架构而非现状须与真实文件结构交叉验证密钥相关小节留白通过.env.example/.env.template/.env.sample发现必需环境变量未知部分标[TODO]把 devDependencies 里的测试工具当成生产依赖记录只把dependencies或等价的生产依赖声明计入运行时集成面此外技能总纲的 Gotchas 中还有一条与集成文档直接相关monorepo 场景下根目录的package.json可能没有源码应检查workspaces、packages/、apps/目录每个子包可能有独立的依赖与约定需要分别盘点其外部集成SKILL.md。同理TypeScript 的tsconfig.jsonpaths别名会让/foo这类导入无法直接映射到文件系统记录集成封装层路径时应先把别名映射到真实路径。总结INTEGRATIONS.md模板把盘点代码库外部集成这一高度发散的任务收敛为六个必需区块与四个可选扩展方向的确定性产出集成清单回答连了谁数据存储回答存了什么密钥处理回答凭据怎么管可靠性回答挂了怎么办可观测性回答出问题怎么发现证据清单回答凭什么这么说。它与scan.py的探测能力、inquiry-checkpoints.md的取证路径以及技能总纲的仅记录可验证事实纪律共同工作最终产出一份可直接用于交接、审计与风险追踪的集成资产文档——这正是它在七份 codebase 文档体系中不可替代的价值所在。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考