技术栈识别指南awesome-copilot 中 acquire-codebase-knowledge 的 Stack Detection 参考手册【免费下载链接】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本文是围绕 awesome-copilot 仓库内acquire-codebase-knowledge技能Agent Skill中 Stack Detection 参考文档展开的深度指南。该参考文档服务于技能工作流的 Phase 2 调查阶段当目标仓库的技术栈模糊不清——例如同时存在多个 manifest 文件、出现陌生文件扩展名、或者找不到明显的package.json/go.mod时Agent 需要依据本文提供的方法完成技术栈判定。读完本文你将掌握一套清单文件 → 生态系统 → 运行时版本 → 框架 → 仓库形态的递进式检测方法论并能与技能自带的 scan.py 扫描器配合把检测结果落成带证据链的 STACK.md 文档。一、Stack Detection 在技能工作流中的定位acquire-codebase-knowledge技能用于在用户要求梳理代码库 / 记录架构 / 上手现有仓库时产出七份docs/codebase/文档STACK.md、STRUCTURE.md、ARCHITECTURE.md、CONVENTIONS.md、INTEGRATIONS.md、TESTING.md、CONCERNS.md。其四阶段工作流定义在 SKILL.md 中- [ ] Phase 1: Run scan, read intent documents - [ ] Phase 2: Investigate each documentation area - [ ] Phase 3: Populate all seven docs in docs/codebase/ - [ ] Phase 4: Validate docs, present findings, resolve all [ASK USER] itemsStack Detection 参考文档正是为 Phase 2 准备的按需加载资源。SKILL.md 明确写道If the stack is ambiguous (multiple manifest files, unfamiliar file types, nopackage.json), loadreferences/stack-detection.md.见 SKILL.md。也就是说这份参考文档不是默认加载项而是在初次扫描后判定技术栈存在歧义时才被读取的定向工具。它的存在价值在于避免 Agent 在多重信号并存时盲目猜测技术栈而是用系统化的信号优先级给出可追溯的结论。参考文档开篇即给出加载条件值得先记住这三类典型歧义场景歧义场景示例信号多个 manifest 并存同时存在package.json与go.mod、requirements.txt与Cargo.toml陌生文件扩展名无法凭扩展名判断语言归属如.ex、.nimble、.cabal缺少常见清单文件既没有package.json也没有go.mod但存在Dockerfile或源码目录二、Manifest 文件 → 生态系统映射技术栈判定的第一步是找到仓库中的依赖清单文件manifest file。不同的清单文件直接对应不同的语言生态系统也决定了后续读取哪些关键字段。参考文档给出的映射表如下FileEcosystemKey fields to readpackage.jsonNode.js / JavaScript / TypeScriptdependencies,devDependencies,scripts,main,type,enginesgo.modGoModule path, Go version,requireblockrequirements.txtPython (pip)Package list with pinned versionsPipfilePython (pipenv)[packages],[dev-packages],[requires]python versionpyproject.tomlPython (poetry / uv / hatch)[tool.poetry.dependencies],[project],[build-system]setup.py/setup.cfgPython (setuptools, legacy)install_requires,python_requiresCargo.tomlRust[dependencies],[[bin]],[lib]pom.xmlJava / Kotlin (Maven)dependencies,artifactId,groupId,java.versionbuild.gradle/build.gradle.ktsJava / Kotlin (Gradle)dependencies {},sourceCompatibilitycomposer.jsonPHPrequire,require-devGemfileRubygemdeclarations,rubyversion constraintmix.exsElixirdeps/0,elixir: ~ X.Ypubspec.yamlDart / Flutterdependencies,dev_dependencies,environment.sdk*.csproj.NET / C#PackageReference,TargetFramework*.sln.NET solutionReferences multiple.csprojprojectsdeno.json/deno.jsoncDeno (TypeScript runtime)imports,tasksbun.lockbBun (JavaScript runtime)Binary lockfile — checkpackage.jsonfor deps表内要点解读关键字段决定读取方向同一生态内不同字段的语义完全不同。以package.json为例dependencies是生产依赖、devDependencies是开发工具链、scripts暴露常用命令、type决定 CommonJS/ESM 模块语义、engines声明运行时版本约束。读取时应有先后顺序先判生态、再读生产依赖、最后看脚本与引擎约束。.sln是聚合信号而非语言信号解决方案文件本身不含代码它引用多个.csproj项目因此当检测到.sln时应继续下钻到各.csproj读取TargetFramework与PackageReference。二进制 lockfile 的陷阱bun.lockb是 Bun 的二进制锁文件无法直接解析内容正确做法是回到package.json读取依赖清单参考文档明确标注 Binary lockfile — checkpackage.jsonfor deps。与 scan.py 的对应实现参考文档的这张表是人工阅读层面的指引而技能自带的 scan.py 已经把这套逻辑自动化了。在 scan.py 中MANIFESTS常量列出了扫描器会识别的全部清单文件其覆盖面远超上表还包含package-lock.json、yarn.lock、pnpm-lock.yaml、poetry.lock、pdm.lock、uv.lock、go.sum、Cargo.lock、Gemfile.lock、settings.gradle、global.json、Package.swiftSwift、build.sbtScala、*.cabal/stack.yamlHaskell、dune-project/opamOCaml、*.nimbleNim、shard.ymlCrystal、DESCRIPTION/renv.lockR、Project.tomlJulia以及CMakeLists.txt、Makefile、BUILD/WORKSPACEBazel、justfile、Taskfile.yml、tox.ini、Vagrantfile等构建系统文件。扫描器在main()中会输出STACK DETECTION (manifest files)区块见 scan.py对每个命中的 manifest 读取前 80 行预览MANIFEST_PREVIEW_LINES 80见 scan.py并特殊处理bun.lockb——直接输出[Binary lockfile — see package.json for dependency details.]提示与参考文档的处理建议完全一致。若根目录没有命中的 manifest扫描器会输出 No recognized manifest files found in project root.此时就应触发 Stack Detection 的后续手段如 Dockerfile 判定。三、语言运行时版本检测确定生态之后下一步是确认具体的运行时版本。版本信息往往不写在单一位置参考文档给出的查找位置如下LanguageWhere to find the versionNode.js.nvmrc,.node-version,engines.nodeinpackage.json, DockerFROM node:XPython.python-version,pyproject.toml [requires-python], DockerFROM python:XGoFirst line ofgo.mod(go 1.21)Javajava.versioninpom.xml,sourceCompatibilityinbuild.gradle, DockerFROM eclipse-temurin:XRuby.ruby-version,Gemfileruby X.Y.ZRustrust-toolchain.toml,rust-toolchainfile.NETTargetFrameworkin.csproj(e.g.,net8.0)使用要点多信号交叉验证同一语言的版本可能同时出现在多个文件中例如 Node.js 既有.nvmrc又有engines.node当多信号不一致时应以约束更强、更贴近运行时构建的那一个为准并在 STACK.md 的 Evidence 列中同时列出多个来源路径方便读者自行判断。版本字段的精确位置Go 的版本固定写在go.mod第一行go 1.21格式Java 的 Maven 项目看java.version属性、Gradle 项目看sourceCompatibility.NET 则看.csproj的TargetFramework如net8.0表示 .NET 8。Docker 镜像作为兜底当语言级版本文件全部缺失时Dockerfile 的FROM行是可靠的运行时版本来源详见第七节。四、框架检测Node.js / TypeScriptmanifest 只能回答语言生态回答不了项目用了什么框架。框架判定要落到package.json的依赖名上。参考文档给出的 Node.js / TypeScript 框架映射如下Dependency inpackage.jsonFrameworkexpressExpress.js (minimal HTTP server)fastifyFastify (high-performance HTTP server)nextNext.js (SSR/SSG React — check forpages/orapp/directory)nuxtNuxt.js (SSR/SSG Vue)nestjs/coreNestJS (opinionated Node.js framework with DI)koaKoa (middleware-focused, no built-in router)hapi/hapiHapitrpc/servertRPC (type-safe API without REST/GraphQL schemas)routing-controllersrouting-controllers (decorator-based Express wrapper)typeormTypeORM (SQL ORM with decorators)prismaPrisma (type-safe ORM, checkprisma/schema.prisma)mongooseMongoose (MongoDB ODM)sequelizeSequelize (SQL ORM)drizzle-ormDrizzle (lightweight SQL ORM)reactwithoutnextVanilla React SPA (check forreact-router-dom)vuewithoutnuxtVanilla Vue SPA使用要点主依赖 排除法react或vue单独出现时并不能立即判定为 SPA 应用——必须先排除next/nuxt的存在。参考文档特意用 without next / without nuxt 来强调这一排除逻辑防止把 SSR 框架误判为纯 SPA。框架背后的目录信号判定next之后还需确认目录结构是pages/Pages Router还是app/App Router判定prisma后要检查prisma/schema.prisma是否存在。也就是说依赖名只负责启动猜测目录结构负责确认结论。用途细分HTTP 服务框架Express / Fastify / Koa / Hapi与数据层框架TypeORM / Prisma / Mongoose / Sequelize / Drizzle是两类不同维度的依赖一个项目中可能同时存在应分别记录而不是互相替代。五、框架检测PythonPython 生态的框架判定遵循同样的思路参考文档给出的映射如下PackageFrameworkfastapiFastAPI (async REST, auto OpenAPI docs)flaskFlask (minimal WSGI web framework)djangoDjango (batteries-included, checksettings.py)starletteStarlette (ASGI, often used as FastAPI base)alembicAlembic (SQLAlchemy migration tool)sqlalchemySQLAlchemy (SQL ORM; check foralembicmigrations)pydanticPydantic (data validation; core to FastAPI)celeryCelery (distributed task queue)aiohttpaiohttp (async HTTP client and server)使用要点依赖之间的隐含关系starlette常作为 FastAPI 的底层 ASGI 框架出现、pydantic是 FastAPI 的数据校验核心、sqlalchemy通常与alembic迁移工具成对出现。判定出某个核心框架后可以顺藤摸瓜确认周边配套依赖形成完整的框架图谱。框架判定 ≠ 功能模块判定celery是分布式任务队列而非 Web 框架它标记的是存在异步后台任务这一事实应同时反映到 INTEGRATIONS.md 或 ARCHITECTURE.md 的相关描述中而不只是在 STACK.md 里列一行依赖。从源码看判定依据scan.py 的SOURCE_EXTS见 scan.py与ENTRY_CANDIDATES见 scan.py为 Python 项目准备了main.py、app.py、server.py、run.py、cli.py、src/main.py等入口候选扫描器会把这些候选输出到 ENTRY POINTS 区块供 Phase 2 确认框架的实际入口使用。六、Monorepo 检测当仓库中存在多个子项目时单一生态判定会失效。参考文档给出的 Monorepo 检测信号按优先级排列如下pnpm-workspace.yaml— pnpm workspaceslerna.json— Lerna monoreponx.json— Nx monorepo (also checkworkspace.json)turbo.json— Turboreporush.json— Rush (Microsoft monorepo manager)moon.yml— Moonpackage.jsonwithworkspaces: [...]— npm/yarn workspacesPresence ofpackages/,apps/,libs/, orservices/directories with their ownpackage.json检测到 Monorepo 后的处理原则每个 workspace 可能拥有独立的依赖和约定应逐个在STACK.md中分别映射子包并在STRUCTURE.md中记录 Monorepo 结构。与 scan.py 的对应实现这个信号列表与扫描器的实现一一对应。scan.py 定义了MONOREPO_FILES [pnpm-workspace.yaml, lerna.json, nx.json, rush.json, turbo.json, moon.yml] MONOREPO_DIRS [packages, apps, libs, services, modules]detect_monorepo()函数见 scan.py依次检测Monorepo 工具文件是否存在、packages/等子包目录是否存在、package.json中是否含workspaces字段并将结果输出为 MONOREPO SIGNALS 区块。注意扫描器还额外支持modules目录可作为目录信号的补充。提示package.json的workspaces字段检测在扫描器中是通过字符串匹配workspaces完成的说明该字段只要出现即视为 Monorepo 信号而真正的子包边界仍需人工确认各子目录下是否有独立的package.json。七、TypeScript 路径别名检测TS/JS 项目中一个常见的结构陷阱是路径别名tsconfig.json中的paths配置会让/foo这类非相对路径不直接对应文件系统。参考文档给出的示例// tsconfig.json example paths: { /*: [./src/*], components/*: [./src/components/*], utils/*: [./src/utils/*] }处理原则import { foo } from /utils/bar实际解析到src/utils/bar因此在文档中应记录为src/utils/bar而不是/utils/bar。为什么必须做别名映射从文档准确性角度看把别名原样写进 STRUCTURE.md 会让读者找不到对应文件破坏每个结论都可追溯到具体文件的输出契约见 SKILL.md。从技能设计看这一规则也被写进了 SKILL.md 的 Gotchas 清单tsconfig.jsonpathsconfig means imports like/foodont map directly to the filesystem. Map aliases to real paths before documenting structure.见 SKILL.md。scan.py 也会在 LINT 配置检测中把tsconfig.json/tsconfig.base.json/tsconfig.build.json一并列出见 scan.py提醒 Phase 2 阶段去检查这些配置文件。八、Docker 基础镜像 → 运行时当仓库中没有任何 manifest 文件却存在Dockerfile时FROM行就是判定运行时的最后手段。参考文档给出的映射FROM line patternRuntimeFROM node:XNode.js XFROM python:XPython XFROM golang:XGo XFROM eclipse-temurin:XJava X (Eclipse Temurin JDK)FROM mcr.microsoft.com/dotnet/aspnet:X.NET XFROM ruby:XRuby XFROM rust:XRust XFROM alpine(alone)Check whats installed viaRUN apk add使用要点多阶段构建要逐层看现代 Dockerfile 常用多阶段构建builder 阶段与 runtime 阶段基础镜像不同。判定运行时应以最终运行阶段通常是FROM mcr.microsoft.com/dotnet/aspnet、FROM node:alpine这类精简运行时镜像的FROM行为准构建阶段如golang:1.22编译 Go只说明编译工具链。alpine单独出现时不能下结论Alpine 是通用极简 Linux 发行版本身不绑定任何语言必须继续阅读后续RUN apk add package命令安装了什么包如nodejs、python3、openjdk17才能推断运行时。与 scan.py 的配合扫描器的CONTAINER_FILES见 scan.py会检测Dockerfile、Dockerfile.*、docker-compose.yml/.yaml、.dockerignore、k8s目录、kustomization.yaml、Chart.yamlHelm、Vagrantfile、podman-compose.yml输出为 CONTAINERS ORCHESTRATION 区块直接列出仓库中有哪些容器化与编排信号。若扫描结果为空且无 manifest则可按本节方法查看是否存在Dockerfile。九、scan.py 自动扫描让 Stack Detection 可执行以上所有检测手段在acquire-codebase-knowledge技能中统一由 scan.py 落地为可重复执行的命令。运行方式需 Python 3.8 与 git跨平台# 在目标项目根目录运行输出到控制台 python3 /absolute/path/to/skills/acquire-codebase-knowledge/scripts/scan.py # 或输出到指定文件供后续调查引用 python3 $SKILL_ROOT/scripts/scan.py --output docs/codebase/.codebase-scan.txt扫描器输出与本文各节的对应关系从 scan.py 的main()流程看输出区块与本文内容一一对应输出区块对应检测维度相关实现DIRECTORY TREE目录结构初判深度 3、上限 200 项get_directory_tree()scan.pySTACK DETECTION (manifest files)本文第二节的 manifest → 生态映射find_manifest_files()scan.pyENTRY POINTS入口点候选src/index.ts、cmd/main.go、app.py等find_entry_points()scan.pyMONOREPO SIGNALS本文第六节的 Monorepo 检测detect_monorepo()scan.pyCI/CD PIPELINESGitHub Actions、GitLab CI、Jenkins 等 10 类平台detect_ci_cd_pipelines()scan.pyCONTAINERS ORCHESTRATIONDocker / Compose / K8s 等容器化信号detect_containers()scan.pyCODE METRICS语言文件数、代码行数、最大文件复杂度信号collect_code_metrics()scan.py扫描器的关键设计排除规则保护结论真实性EXCLUDE_DIRS见 scan.py包含node_modules、.git、dist、build、out、.next、.nuxt、__pycache__、venv、target、vendor、coverage、generated等目录——这与 SKILL.md 中不要把dist/、build/、generated/、.next/、__pycache__/当作约定来记录的 Gotchas 一致见 SKILL.md保证技术栈结论只来自源码与配置文件而非构建产物。TODO 扫描排除测试目录search_todos()在统计TODO/FIXME/HACK时会排除test、tests、__tests__、spec、fixtures等目录因为测试中的 TODO 是覆盖缺口不是生产技术债见 SKILL.md。Git 信息辅助判定is_git_repo()与get_git_churn()输出最近提交与 90 天高变更文件CHURN_LIMIT 20用于在 CONCERNS.md 中标记脆弱区域。十、检测结果落地STACK.md 模板与证据链Stack Detection 的终点不是知道技术栈而是把结论写进docs/codebase/STACK.md。Phase 3 的第一步就是填充 STACK.md 模板其必需板块与本文检测维度的对应关系如下STACK.md 板块数据来源Stack Detection 方法Runtime Summary主语言、运行时版本、包管理器、模块/构建系统第二节生态判定 第三节日运行时版本检测Production Frameworks and Dependencies依赖、版本、角色、证据第四、五节框架检测只列高影响生产依赖Development Toolchainlint/format/test/build 工具依赖中devDependencies部分 scan.py 的 LINTING AND FORMATTING CONFIG 区块Key Commandsinstall/build/test/lint 命令package.json的scripts、Makefile、pyproject.toml脚本Environment and Config配置来源、必需环境变量.env.example等模板 scan.py 的 ENVIRONMENT VARIABLE TEMPLATES 区块Evidence证据文件路径列表本次检测实际读过的 manifest / 运行时配置 / CI 文件路径每个板块都要求填 Evidence 列具体文件路径这正是每个结论都可追溯到源文件的输出契约的体现。填写 STACK.md 时的调查问题清单可参考 inquiry-checkpoints.md 中 STACK.md 一节的六个问题主语言与精确版本、包管理器、核心框架、生产依赖 vs 开发依赖、Docker 基础镜像、关键脚本。十一、实战避坑判定优先级与反模式综合参考文档与 SKILL.md 的 Gotchas / Anti-Patterns技术栈判定时应遵循以下纪律先自动化扫描再人工阅读Phase 1 先运行 scan.py 拿到全部信号再在 Phase 2 用本文方法定向确认避免凭经验猜。多信号冲突时回到 manifestREADME 常常描述的是预期架构而非当前现状判定结论必须以实际文件结构为准见 SKILL.md。不要凭变量名猜依赖看到dbUrl就推断数据库是错的应到 manifest 中确认是否存在pg、mysql2、mongoose、prisma、sqlalchemy等依赖见 SKILL.md。devDependencies 不等于生产栈linter、格式化器、测试框架属于开发工具链应单独记录不能混入生产框架列表见 SKILL.md。未知即标[TODO]意图即标[ASK USER]无法从代码确认的内容不得臆测需要团队意图才能定夺的内容标记为待确认问题这是技能输出契约的硬性要求见 SKILL.md。结语Stack Detection 参考文档看似只是一组表格实则是先判生态、再定版本、后识框架、复查形态这一可执行检测链路的浓缩。将它与 scan.py 的自动扫描、STACK.md 模板的证据链要求组合使用就能在技术栈模糊的仓库中稳定地产出可追溯、可验证的 STACK 结论为后续 STRUCTURE、ARCHITECTURE 等六份文档的填写打下可靠基础。实际使用中建议把本文的六类检测表当作查表手册把 scan.py 的输出当作事实输入把 STACK.md 的 Evidence 列当作验收标准三者闭环即可覆盖绝大多数代码库的上手场景。【免费下载链接】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），仅供参考 技术栈识别指南：awesome-copilot 中 acquire-codebase-knowledge 的 Stack Detection 参考手册
技术栈识别指南awesome-copilot 中 acquire-codebase-knowledge 的 Stack Detection 参考手册【免费下载链接】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本文是围绕 awesome-copilot 仓库内acquire-codebase-knowledge技能Agent Skill中 Stack Detection 参考文档展开的深度指南。该参考文档服务于技能工作流的 Phase 2 调查阶段当目标仓库的技术栈模糊不清——例如同时存在多个 manifest 文件、出现陌生文件扩展名、或者找不到明显的package.json/go.mod时Agent 需要依据本文提供的方法完成技术栈判定。读完本文你将掌握一套清单文件 → 生态系统 → 运行时版本 → 框架 → 仓库形态的递进式检测方法论并能与技能自带的 scan.py 扫描器配合把检测结果落成带证据链的 STACK.md 文档。一、Stack Detection 在技能工作流中的定位acquire-codebase-knowledge技能用于在用户要求梳理代码库 / 记录架构 / 上手现有仓库时产出七份docs/codebase/文档STACK.md、STRUCTURE.md、ARCHITECTURE.md、CONVENTIONS.md、INTEGRATIONS.md、TESTING.md、CONCERNS.md。其四阶段工作流定义在 SKILL.md 中- [ ] Phase 1: Run scan, read intent documents - [ ] Phase 2: Investigate each documentation area - [ ] Phase 3: Populate all seven docs in docs/codebase/ - [ ] Phase 4: Validate docs, present findings, resolve all [ASK USER] itemsStack Detection 参考文档正是为 Phase 2 准备的按需加载资源。SKILL.md 明确写道If the stack is ambiguous (multiple manifest files, unfamiliar file types, nopackage.json), loadreferences/stack-detection.md.见 SKILL.md。也就是说这份参考文档不是默认加载项而是在初次扫描后判定技术栈存在歧义时才被读取的定向工具。它的存在价值在于避免 Agent 在多重信号并存时盲目猜测技术栈而是用系统化的信号优先级给出可追溯的结论。参考文档开篇即给出加载条件值得先记住这三类典型歧义场景歧义场景示例信号多个 manifest 并存同时存在package.json与go.mod、requirements.txt与Cargo.toml陌生文件扩展名无法凭扩展名判断语言归属如.ex、.nimble、.cabal缺少常见清单文件既没有package.json也没有go.mod但存在Dockerfile或源码目录二、Manifest 文件 → 生态系统映射技术栈判定的第一步是找到仓库中的依赖清单文件manifest file。不同的清单文件直接对应不同的语言生态系统也决定了后续读取哪些关键字段。参考文档给出的映射表如下FileEcosystemKey fields to readpackage.jsonNode.js / JavaScript / TypeScriptdependencies,devDependencies,scripts,main,type,enginesgo.modGoModule path, Go version,requireblockrequirements.txtPython (pip)Package list with pinned versionsPipfilePython (pipenv)[packages],[dev-packages],[requires]python versionpyproject.tomlPython (poetry / uv / hatch)[tool.poetry.dependencies],[project],[build-system]setup.py/setup.cfgPython (setuptools, legacy)install_requires,python_requiresCargo.tomlRust[dependencies],[[bin]],[lib]pom.xmlJava / Kotlin (Maven)dependencies,artifactId,groupId,java.versionbuild.gradle/build.gradle.ktsJava / Kotlin (Gradle)dependencies {},sourceCompatibilitycomposer.jsonPHPrequire,require-devGemfileRubygemdeclarations,rubyversion constraintmix.exsElixirdeps/0,elixir: ~ X.Ypubspec.yamlDart / Flutterdependencies,dev_dependencies,environment.sdk*.csproj.NET / C#PackageReference,TargetFramework*.sln.NET solutionReferences multiple.csprojprojectsdeno.json/deno.jsoncDeno (TypeScript runtime)imports,tasksbun.lockbBun (JavaScript runtime)Binary lockfile — checkpackage.jsonfor deps表内要点解读关键字段决定读取方向同一生态内不同字段的语义完全不同。以package.json为例dependencies是生产依赖、devDependencies是开发工具链、scripts暴露常用命令、type决定 CommonJS/ESM 模块语义、engines声明运行时版本约束。读取时应有先后顺序先判生态、再读生产依赖、最后看脚本与引擎约束。.sln是聚合信号而非语言信号解决方案文件本身不含代码它引用多个.csproj项目因此当检测到.sln时应继续下钻到各.csproj读取TargetFramework与PackageReference。二进制 lockfile 的陷阱bun.lockb是 Bun 的二进制锁文件无法直接解析内容正确做法是回到package.json读取依赖清单参考文档明确标注 Binary lockfile — checkpackage.jsonfor deps。与 scan.py 的对应实现参考文档的这张表是人工阅读层面的指引而技能自带的 scan.py 已经把这套逻辑自动化了。在 scan.py 中MANIFESTS常量列出了扫描器会识别的全部清单文件其覆盖面远超上表还包含package-lock.json、yarn.lock、pnpm-lock.yaml、poetry.lock、pdm.lock、uv.lock、go.sum、Cargo.lock、Gemfile.lock、settings.gradle、global.json、Package.swiftSwift、build.sbtScala、*.cabal/stack.yamlHaskell、dune-project/opamOCaml、*.nimbleNim、shard.ymlCrystal、DESCRIPTION/renv.lockR、Project.tomlJulia以及CMakeLists.txt、Makefile、BUILD/WORKSPACEBazel、justfile、Taskfile.yml、tox.ini、Vagrantfile等构建系统文件。扫描器在main()中会输出STACK DETECTION (manifest files)区块见 scan.py对每个命中的 manifest 读取前 80 行预览MANIFEST_PREVIEW_LINES 80见 scan.py并特殊处理bun.lockb——直接输出[Binary lockfile — see package.json for dependency details.]提示与参考文档的处理建议完全一致。若根目录没有命中的 manifest扫描器会输出 No recognized manifest files found in project root.此时就应触发 Stack Detection 的后续手段如 Dockerfile 判定。三、语言运行时版本检测确定生态之后下一步是确认具体的运行时版本。版本信息往往不写在单一位置参考文档给出的查找位置如下LanguageWhere to find the versionNode.js.nvmrc,.node-version,engines.nodeinpackage.json, DockerFROM node:XPython.python-version,pyproject.toml [requires-python], DockerFROM python:XGoFirst line ofgo.mod(go 1.21)Javajava.versioninpom.xml,sourceCompatibilityinbuild.gradle, DockerFROM eclipse-temurin:XRuby.ruby-version,Gemfileruby X.Y.ZRustrust-toolchain.toml,rust-toolchainfile.NETTargetFrameworkin.csproj(e.g.,net8.0)使用要点多信号交叉验证同一语言的版本可能同时出现在多个文件中例如 Node.js 既有.nvmrc又有engines.node当多信号不一致时应以约束更强、更贴近运行时构建的那一个为准并在 STACK.md 的 Evidence 列中同时列出多个来源路径方便读者自行判断。版本字段的精确位置Go 的版本固定写在go.mod第一行go 1.21格式Java 的 Maven 项目看java.version属性、Gradle 项目看sourceCompatibility.NET 则看.csproj的TargetFramework如net8.0表示 .NET 8。Docker 镜像作为兜底当语言级版本文件全部缺失时Dockerfile 的FROM行是可靠的运行时版本来源详见第七节。四、框架检测Node.js / TypeScriptmanifest 只能回答语言生态回答不了项目用了什么框架。框架判定要落到package.json的依赖名上。参考文档给出的 Node.js / TypeScript 框架映射如下Dependency inpackage.jsonFrameworkexpressExpress.js (minimal HTTP server)fastifyFastify (high-performance HTTP server)nextNext.js (SSR/SSG React — check forpages/orapp/directory)nuxtNuxt.js (SSR/SSG Vue)nestjs/coreNestJS (opinionated Node.js framework with DI)koaKoa (middleware-focused, no built-in router)hapi/hapiHapitrpc/servertRPC (type-safe API without REST/GraphQL schemas)routing-controllersrouting-controllers (decorator-based Express wrapper)typeormTypeORM (SQL ORM with decorators)prismaPrisma (type-safe ORM, checkprisma/schema.prisma)mongooseMongoose (MongoDB ODM)sequelizeSequelize (SQL ORM)drizzle-ormDrizzle (lightweight SQL ORM)reactwithoutnextVanilla React SPA (check forreact-router-dom)vuewithoutnuxtVanilla Vue SPA使用要点主依赖 排除法react或vue单独出现时并不能立即判定为 SPA 应用——必须先排除next/nuxt的存在。参考文档特意用 without next / without nuxt 来强调这一排除逻辑防止把 SSR 框架误判为纯 SPA。框架背后的目录信号判定next之后还需确认目录结构是pages/Pages Router还是app/App Router判定prisma后要检查prisma/schema.prisma是否存在。也就是说依赖名只负责启动猜测目录结构负责确认结论。用途细分HTTP 服务框架Express / Fastify / Koa / Hapi与数据层框架TypeORM / Prisma / Mongoose / Sequelize / Drizzle是两类不同维度的依赖一个项目中可能同时存在应分别记录而不是互相替代。五、框架检测PythonPython 生态的框架判定遵循同样的思路参考文档给出的映射如下PackageFrameworkfastapiFastAPI (async REST, auto OpenAPI docs)flaskFlask (minimal WSGI web framework)djangoDjango (batteries-included, checksettings.py)starletteStarlette (ASGI, often used as FastAPI base)alembicAlembic (SQLAlchemy migration tool)sqlalchemySQLAlchemy (SQL ORM; check foralembicmigrations)pydanticPydantic (data validation; core to FastAPI)celeryCelery (distributed task queue)aiohttpaiohttp (async HTTP client and server)使用要点依赖之间的隐含关系starlette常作为 FastAPI 的底层 ASGI 框架出现、pydantic是 FastAPI 的数据校验核心、sqlalchemy通常与alembic迁移工具成对出现。判定出某个核心框架后可以顺藤摸瓜确认周边配套依赖形成完整的框架图谱。框架判定 ≠ 功能模块判定celery是分布式任务队列而非 Web 框架它标记的是存在异步后台任务这一事实应同时反映到 INTEGRATIONS.md 或 ARCHITECTURE.md 的相关描述中而不只是在 STACK.md 里列一行依赖。从源码看判定依据scan.py 的SOURCE_EXTS见 scan.py与ENTRY_CANDIDATES见 scan.py为 Python 项目准备了main.py、app.py、server.py、run.py、cli.py、src/main.py等入口候选扫描器会把这些候选输出到 ENTRY POINTS 区块供 Phase 2 确认框架的实际入口使用。六、Monorepo 检测当仓库中存在多个子项目时单一生态判定会失效。参考文档给出的 Monorepo 检测信号按优先级排列如下pnpm-workspace.yaml— pnpm workspaceslerna.json— Lerna monoreponx.json— Nx monorepo (also checkworkspace.json)turbo.json— Turboreporush.json— Rush (Microsoft monorepo manager)moon.yml— Moonpackage.jsonwithworkspaces: [...]— npm/yarn workspacesPresence ofpackages/,apps/,libs/, orservices/directories with their ownpackage.json检测到 Monorepo 后的处理原则每个 workspace 可能拥有独立的依赖和约定应逐个在STACK.md中分别映射子包并在STRUCTURE.md中记录 Monorepo 结构。与 scan.py 的对应实现这个信号列表与扫描器的实现一一对应。scan.py 定义了MONOREPO_FILES [pnpm-workspace.yaml, lerna.json, nx.json, rush.json, turbo.json, moon.yml] MONOREPO_DIRS [packages, apps, libs, services, modules]detect_monorepo()函数见 scan.py依次检测Monorepo 工具文件是否存在、packages/等子包目录是否存在、package.json中是否含workspaces字段并将结果输出为 MONOREPO SIGNALS 区块。注意扫描器还额外支持modules目录可作为目录信号的补充。提示package.json的workspaces字段检测在扫描器中是通过字符串匹配workspaces完成的说明该字段只要出现即视为 Monorepo 信号而真正的子包边界仍需人工确认各子目录下是否有独立的package.json。七、TypeScript 路径别名检测TS/JS 项目中一个常见的结构陷阱是路径别名tsconfig.json中的paths配置会让/foo这类非相对路径不直接对应文件系统。参考文档给出的示例// tsconfig.json example paths: { /*: [./src/*], components/*: [./src/components/*], utils/*: [./src/utils/*] }处理原则import { foo } from /utils/bar实际解析到src/utils/bar因此在文档中应记录为src/utils/bar而不是/utils/bar。为什么必须做别名映射从文档准确性角度看把别名原样写进 STRUCTURE.md 会让读者找不到对应文件破坏每个结论都可追溯到具体文件的输出契约见 SKILL.md。从技能设计看这一规则也被写进了 SKILL.md 的 Gotchas 清单tsconfig.jsonpathsconfig means imports like/foodont map directly to the filesystem. Map aliases to real paths before documenting structure.见 SKILL.md。scan.py 也会在 LINT 配置检测中把tsconfig.json/tsconfig.base.json/tsconfig.build.json一并列出见 scan.py提醒 Phase 2 阶段去检查这些配置文件。八、Docker 基础镜像 → 运行时当仓库中没有任何 manifest 文件却存在Dockerfile时FROM行就是判定运行时的最后手段。参考文档给出的映射FROM line patternRuntimeFROM node:XNode.js XFROM python:XPython XFROM golang:XGo XFROM eclipse-temurin:XJava X (Eclipse Temurin JDK)FROM mcr.microsoft.com/dotnet/aspnet:X.NET XFROM ruby:XRuby XFROM rust:XRust XFROM alpine(alone)Check whats installed viaRUN apk add使用要点多阶段构建要逐层看现代 Dockerfile 常用多阶段构建builder 阶段与 runtime 阶段基础镜像不同。判定运行时应以最终运行阶段通常是FROM mcr.microsoft.com/dotnet/aspnet、FROM node:alpine这类精简运行时镜像的FROM行为准构建阶段如golang:1.22编译 Go只说明编译工具链。alpine单独出现时不能下结论Alpine 是通用极简 Linux 发行版本身不绑定任何语言必须继续阅读后续RUN apk add package命令安装了什么包如nodejs、python3、openjdk17才能推断运行时。与 scan.py 的配合扫描器的CONTAINER_FILES见 scan.py会检测Dockerfile、Dockerfile.*、docker-compose.yml/.yaml、.dockerignore、k8s目录、kustomization.yaml、Chart.yamlHelm、Vagrantfile、podman-compose.yml输出为 CONTAINERS ORCHESTRATION 区块直接列出仓库中有哪些容器化与编排信号。若扫描结果为空且无 manifest则可按本节方法查看是否存在Dockerfile。九、scan.py 自动扫描让 Stack Detection 可执行以上所有检测手段在acquire-codebase-knowledge技能中统一由 scan.py 落地为可重复执行的命令。运行方式需 Python 3.8 与 git跨平台# 在目标项目根目录运行输出到控制台 python3 /absolute/path/to/skills/acquire-codebase-knowledge/scripts/scan.py # 或输出到指定文件供后续调查引用 python3 $SKILL_ROOT/scripts/scan.py --output docs/codebase/.codebase-scan.txt扫描器输出与本文各节的对应关系从 scan.py 的main()流程看输出区块与本文内容一一对应输出区块对应检测维度相关实现DIRECTORY TREE目录结构初判深度 3、上限 200 项get_directory_tree()scan.pySTACK DETECTION (manifest files)本文第二节的 manifest → 生态映射find_manifest_files()scan.pyENTRY POINTS入口点候选src/index.ts、cmd/main.go、app.py等find_entry_points()scan.pyMONOREPO SIGNALS本文第六节的 Monorepo 检测detect_monorepo()scan.pyCI/CD PIPELINESGitHub Actions、GitLab CI、Jenkins 等 10 类平台detect_ci_cd_pipelines()scan.pyCONTAINERS ORCHESTRATIONDocker / Compose / K8s 等容器化信号detect_containers()scan.pyCODE METRICS语言文件数、代码行数、最大文件复杂度信号collect_code_metrics()scan.py扫描器的关键设计排除规则保护结论真实性EXCLUDE_DIRS见 scan.py包含node_modules、.git、dist、build、out、.next、.nuxt、__pycache__、venv、target、vendor、coverage、generated等目录——这与 SKILL.md 中不要把dist/、build/、generated/、.next/、__pycache__/当作约定来记录的 Gotchas 一致见 SKILL.md保证技术栈结论只来自源码与配置文件而非构建产物。TODO 扫描排除测试目录search_todos()在统计TODO/FIXME/HACK时会排除test、tests、__tests__、spec、fixtures等目录因为测试中的 TODO 是覆盖缺口不是生产技术债见 SKILL.md。Git 信息辅助判定is_git_repo()与get_git_churn()输出最近提交与 90 天高变更文件CHURN_LIMIT 20用于在 CONCERNS.md 中标记脆弱区域。十、检测结果落地STACK.md 模板与证据链Stack Detection 的终点不是知道技术栈而是把结论写进docs/codebase/STACK.md。Phase 3 的第一步就是填充 STACK.md 模板其必需板块与本文检测维度的对应关系如下STACK.md 板块数据来源Stack Detection 方法Runtime Summary主语言、运行时版本、包管理器、模块/构建系统第二节生态判定 第三节日运行时版本检测Production Frameworks and Dependencies依赖、版本、角色、证据第四、五节框架检测只列高影响生产依赖Development Toolchainlint/format/test/build 工具依赖中devDependencies部分 scan.py 的 LINTING AND FORMATTING CONFIG 区块Key Commandsinstall/build/test/lint 命令package.json的scripts、Makefile、pyproject.toml脚本Environment and Config配置来源、必需环境变量.env.example等模板 scan.py 的 ENVIRONMENT VARIABLE TEMPLATES 区块Evidence证据文件路径列表本次检测实际读过的 manifest / 运行时配置 / CI 文件路径每个板块都要求填 Evidence 列具体文件路径这正是每个结论都可追溯到源文件的输出契约的体现。填写 STACK.md 时的调查问题清单可参考 inquiry-checkpoints.md 中 STACK.md 一节的六个问题主语言与精确版本、包管理器、核心框架、生产依赖 vs 开发依赖、Docker 基础镜像、关键脚本。十一、实战避坑判定优先级与反模式综合参考文档与 SKILL.md 的 Gotchas / Anti-Patterns技术栈判定时应遵循以下纪律先自动化扫描再人工阅读Phase 1 先运行 scan.py 拿到全部信号再在 Phase 2 用本文方法定向确认避免凭经验猜。多信号冲突时回到 manifestREADME 常常描述的是预期架构而非当前现状判定结论必须以实际文件结构为准见 SKILL.md。不要凭变量名猜依赖看到dbUrl就推断数据库是错的应到 manifest 中确认是否存在pg、mysql2、mongoose、prisma、sqlalchemy等依赖见 SKILL.md。devDependencies 不等于生产栈linter、格式化器、测试框架属于开发工具链应单独记录不能混入生产框架列表见 SKILL.md。未知即标[TODO]意图即标[ASK USER]无法从代码确认的内容不得臆测需要团队意图才能定夺的内容标记为待确认问题这是技能输出契约的硬性要求见 SKILL.md。结语Stack Detection 参考文档看似只是一组表格实则是先判生态、再定版本、后识框架、复查形态这一可执行检测链路的浓缩。将它与 scan.py 的自动扫描、STACK.md 模板的证据链要求组合使用就能在技术栈模糊的仓库中稳定地产出可追溯、可验证的 STACK 结论为后续 STRUCTURE、ARCHITECTURE 等六份文档的填写打下可靠基础。实际使用中建议把本文的六类检测表当作查表手册把 scan.py 的输出当作事实输入把 STACK.md 的 Evidence 列当作验收标准三者闭环即可覆盖绝大多数代码库的上手场景。【免费下载链接】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），仅供参考