【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载本篇以 kind-moles-dance.md 这份变更记录Fixed 类型关联 PR #3762为核心解析 GSD-CoreGit. Ship. Done - Core中Agent 安装状态检测的完整机制修复前resolveAgentsDir()只检查全局~/.claude/agents导致--local仓库本地安装被误判为未安装修复后如何通过四级目录解析算法与gsd-file-manifest.json清单背书让init.new-project正确报告agents_installed: true。读完后你能掌握 agents 目录的解析优先级、仓库本地安装的校验条件以及agents_installed结果结构如何参与初始化工作流的门禁判断。1. 变更记录描述的问题--local 安装下的误报这份 changeset 的完整内容只有三行事实Repo-local Claude agents now detected on --local installs—resolveAgentsDir()was checking only~/.claude/agents, soinit.new-projectreportedagents_installed: falseandinit-complexskipped initialization despite a valid repo-local install.把这段话拆成技术链路就是四个要点安装形态用户以--local方式安装GSD 的 agent 文件被写入仓库内repo-local而不是用户主目录下的全局配置目录缺陷根源当时的目录解析函数只硬编码检查~/.claude/agents完全忽略项目内的本地安装故障表现init.new-project的报告中输出agents_installed: false——尽管本地安装完全有效下游连锁反应init-complex工作流依据这个 false 值跳过了初始化步骤即检测误报直接导致流程误跳。这类问题的典型危害在于它不会抛错、不会崩溃而是以一份看似合理的健康检查报告形式静默误导后续工作流。在 src/init.cts 中可以看到agents_installed字段被原样写入 init 结果并交给工作流消费约 L354result[agents_installed] agentStatus.agents_installed;说明这个布尔值确实是初始化决策的一等输入。修复的意义因此不只是报告更准而是恢复了检测—判断—执行这条链路的前置条件。2. 修复后的核心实现getAgentsDir() 的四级解析算法修复落在 src/agent-install-check.cts 模块该文件头部注释说明其由 ADR-857 的 T0 #1268 阶段从 core 模块迁出现独立拥有getAgentsDir()与checkAgentsInstalled()两个核心函数。当前实现的目录解析优先级如下与源码注释L118-L143完全对应优先级条件解析结果1环境变量GSD_AGENTS_DIR非空直接返回该值显式覆盖适用于任意 runtime2runtime 为claude__dirname相对路径安装根/agents/gsd-core/ 的兄弟目录除非路径中含node_modules段则改走全局目录3非 claude runtime 且项目内有清单背书的本地安装projectRoot/localConfigDir/agents4其余非 claude runtimegetGlobalConfigDir(runtime)/agents即各 runtime 的全局配置目录其中 runtime 名称本身也有回退链显式参数 → 环境变量GSD_RUNTIME→ 默认claudeL148。2.1 claude runtime 的 node_modules 守卫claude 分支中最微妙的是对 npm 全局安装的词法守卫L149-L160if (resolved claude) { const installRelative path.join(__dirname, .., .., .., agents); // #3203: a lexical guard, not an install-shape test. if (installRelative.split(path.sep).includes(node_modules)) { return path.join(getGlobalConfigDir(claude), agents); } return installRelative; }源码注释解释得很直白gsd-tools.cjs在任何安装形态下都位于gsd-core/bin/内../../..相对路径在仓库内运行或安装到 runtime 配置目录两种形态下指向的正是用户的 agents 目录但在 npm 全局安装形态下gsd-core/ 位于包内部包自带一份agents/捆绑副本——若不加守卫安装检查就会用包自己验证包自己agents_installed永远不可能为 false。守卫本身是一个词法判断而非安装形态探测只要解析出的路径携带一段精确的node_modules目录名就改走getGlobalConfigDir(claude)/agents该函数同时尊重CLAUDE_CONFIG_DIR环境变量对应 issue #3203。注释还特意说明这是一个刻意的保守设计任何恰好叫 node_modules 的目录也会触发同样的重定向而GSD_AGENTS_DIR非空时覆盖前两者。2.2 仓库本地安装的发现逻辑本次修复的直接落点非 claude runtime 分支携带projectRoot时进入仓库本地安装的发现逻辑L161-L186const localConfigDirName getDirName(resolved); const localConfigDir localConfigDirName NO_LOCAL_CONFIG_DIR_SENTINEL ? undefined : runtimeConfig?.hostBehaviors?.localTargetIsProjectRoot ? projectRoot : path.join(projectRoot, localConfigDirName); ... const localAgentsDir path.join(localConfigDir, agents); const manifestPath path.join(localConfigDir, gsd-file-manifest.json); try { if (fs.lstatSync(localAgentsDir).isDirectory() fs.lstatSync(manifestPath).isFile()) { return localAgentsDir; } } catch { // Local discovery is best-effort; any probe failure preserves global fallback. }这段代码体现了修复后的三条关键设计决策a本地目录位置由 capability 注册表驱动。getDirName()来自 src/runtime-name-policy.ctslocalTargetIsProjectRoot行为标志来自 src/capability-registry.cts 中各 runtime 的hostBehaviors配置——本地安装的目标目录不是硬编码的而是每个 runtime 声明的。若该 runtime 根本没有本地配置目录哨兵值NO_LOCAL_CONFIG_DIR_SENTINEL则直接落到全局回退。bmanifest 背书防止误判。仅当本地agents/是真实目录、且同级的gsd-file-manifest.json是真实文件时才认定这是一个 GSD 的本地安装。gsd-file-manifest.json是安装引擎写入的文件清单可参见 docs/installer-migrations.md 对清单机制的描述它的存在是GSD 亲手装过这里的证据。源码注释点明了动机Requiring the GSD manifest prevents runtime-native project agents from shadowing a working global GSD install——很多 runtime 原生支持项目内放置 agent 文件如果只看目录是否存在一个与 GSD 无关的项目 agent 目录就会遮蔽掉正常工作的全局 GSD 安装。c符号链接一律忽略探测失败静默回退。两处都用lstatSync而非statSync符号链接形式的agents/目录或清单文件不会被认定为有效安装注释原文Symlinked local agent directories are ignored。try/catch保证任何探测异常目录不存在、无权限等都让本地发现尽力而为地失败保持全局目录回退。3. checkAgentsInstalled()结果结构与完整性校验解析出目录后checkAgentsInstalled() 执行三步判定第一步目录存在性。若 agents 目录不存在直接返回agents_installed: false且missing_agents等于全部期望 agent期望名单来自 src/model-profiles.cts 的MODEL_PROFILES键集。第二步逐个 agent 文件探测。每个期望 agent 按 runtime 的文件名变体探测agentFileExists()变体路径形态适用 runtime基础agentsDir/name.md通用CopilotagentsDir/name.agent.md通用任一存在即命中CodexagentsDir/name.toml通用任一存在即命中KimiagentsDir/subagents/name.yaml且subagents/name.md必须同时存在仅 kimi第三步manifest 完整性校验。若 agents 目录的父目录存在gsd-file-manifest.json则对每个被清单跟踪的 agent验证清单中agents/agentName.ext键对应的每个文件都在盘上L221-L261。这捕获部分安装状态——例如.md在而.toml不在——并放入incomplete_agents列表。清单读取复用安装迁移模块的readInstallManifest()惰性 require见 src/installer-migrations.cts源码注释强调这是为了不做第四份私有副本。若目录无清单该步为空操作对 claude/捆绑形态优雅降级。最终结果结构为interface AgentsInstalledResult { agents_installed: boolean; // installed.length 0 missing.length 0 incomplete.length 0 missing_agents: string[]; installed_agents: string[]; incomplete_agents: string[]; agents_dir: string; agent_runtime: string; }注意agents_installed的合取条件只要有一个 agent 缺失或有一个不完整结果就是 false。这正是 changeset 中detected二字的实质——本地安装不仅要被看到目录还要通过完整性校验后才能被检测到。该结构同时被 src/health-diagnostic-rules/agent-install.cts健康诊断规则和 src/verify.cts 等消费相关行为有 tests/agent-install-check.test.cjs 与 tests/agent-install-validation.test.cjs 两套测试锚定。4. 同模块的延伸能力从存在性到姿态检查修复所在的模块还承载了两类更深的只读检查理解它们有助于把握检测在 GSD-Core 中的完整含义checkCodexModelPosture()仅当 runtime 为codex时工作扫描.tomlagent 文件报告两类违规——anthropic_flavored_modelmodel 字段被钉到 Anthropic 风格模型与orphaned_reasoning_effort有model_reasoning_effort却没有 model 钉值。所有 reason 使用冻结枚举POSTURE_REASON调用方与测试断言的是枚举值而非文案。checkCodexSandboxPosture()对照捆绑的agents/*.md规范源中tools:契约推导出的sandbox_mode期望值检查已安装.toml的sandbox_mode是否漂移。推导函数deriveCodexSandboxMode来自 src/codex-agent-toml.cts——该共享叶子模块同时被安装发射器与姿态检查引用源码注释明确这是为了防止两条沙箱供给路径静默分歧。两个函数都刻意设计为只检测、不修复且在非 codex runtime 上先行短路不解析目录、不触碰任何文件——这与 changeset 所修复的检测面是同一设计哲学的延伸检测必须是廉价的、无副作用的、fail-closed 的。5. 实操视角如何验证本地安装被正确识别结合上述实现在仓库只读的前提下可以这样排查本地安装是否被检测到确认本地安装形态检查项目内 runtime 配置目录下是否存在agents/子目录以及同级的gsd-file-manifest.json文件。两者缺一getAgentsDir()就会落到全局目录回退本地安装不被识别——这与 changeset 修复前的症状同构目录在但解析器看不见它。检查符号链接若agents/是符号链接会被lstatSync判断显式忽略本地目录必须是真实目录。核对 agent 文件变体不同 runtime 要求不同的文件名.md/.agent.md/.toml/ kimi 的subagents/name.{yaml,md}成对清单中跟踪到的文件若部分缺失会进入incomplete_agents同样使agents_installed为 false。显式覆盖设置GSD_AGENTS_DIR环境变量可强制指定 agents 目录优先级高于一切自动解析适合验证环境或非常规安装布局。运行时指定GSD_RUNTIME环境变量决定 runtime 回退值不设置时按claude处理此时走的是安装相对路径而非全局~/.claude/agents。6. 小结这份变更记录修复了什么、边界在哪里回到 changeset 本身可以把修复概括为一次检测面的能力对齐修复前目录解析器只有全局一个视角仅~/.claude/agents--local安装对检测器不可见agents_installed: false被写入 init 报告init-complex据此跳过初始化修复后解析器具备了完整的安装形态感知——claude 的安装相对路径含 npm 全局形态的 node_modules 守卫、manifest 背书的仓库本地目录发现含符号链接忽略与失败回退、以及各 runtime 的全局配置目录回退边界本地安装必须同时满足真实目录 真实清单文件才生效探测失败永远静默回退全局不做任何修复动作agents_installed的最终判定还叠加了逐 agent 的文件变体检查与清单完整性检查。这份改动虽小changeset 仅数行却精确展示了 GSD-Core 检测类代码的通用模式解析getAgentsDir与判定checkAgentsInstalled分离、探测尽力而为且 fail-safe、枚举值冻结以供测试断言、清单文件作为所有权证据防止误认。理解这条链路也就理解了init、verify、健康诊断三个面为何能共享同一份安装事实而不各说各话。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐PHPStan 错误标识符详解booleanOr.leftAlwaysFalse —— || 左侧恒为 false的检测原理与修复实践PHPStan 错误标识符详解booleanOr.leftAlwaysFalse —— || 左侧恒为 false的检测原理与修复实践 booleanOr开发工具代码质量静态分析PHPStan 错误标识符解析greaterOrEqual.alwaysFalse—— 比较恒为 false 的检测原理与修复指南PHPStan 错误标识符解析greaterOrEqual.alwaysFalse—— 比较恒为 false 的检测原理与修复指南 greaterOrEq开发工具代码质量静态分析PHPStan 错误标识符 doWhile.alwaysFalse 全解do-while 条件恒为 false 的检测原理与修复实践PHPStan 错误标识符 doWhile.alwaysFalse 全解do while 条件恒为 false 的检测原理与修复实践 导读 doWhile.a开发工具代码质量静态分析上一篇ChatRTX模型管理深度解析从下载到部署的完整流程指南下一篇welle.io源码深潜OFDM定时同步、粗频偏校正与相位参考跟踪的实现原理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考