gsd-core 多运行时兼容修复：/gsd:init 按运行时解析 agents 目录的深度解析

【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载导读本文围绕 gsd-coreGit. Ship. Done - Core仓库中.changeset/archived/384-agents-dir-runtime-aware.md所记录的修复展开/gsd:init命令在 OpenCode 等非 Claude 运行时上不再误报agents 缺失其根因是getAgentsDir()原先总是检查 Claude 专属路径如今改为按当前运行时的全局配置目录解析同时 init 诊断结果中新增了agent_runtime与agents_dir两个字段。读完本文你将掌握 gsd-core 中 agents 目录的完整解析优先级、init 诊断字段的语义以及如何用源码与测试验证该行为。修复背景为什么 OpenCode 会误报 agents 缺失gsd-core 是一套与运行时runtime深度绑定的 AI 工作流核心库它的 agent 文件如gsd-executor、gsd-planner等需要落在当前 AI 宿主工具Claude Code、OpenCode、Cursor、Codex、Kimi、Cline 等能够读取的目录中。/gsd:init启动时会做一次agent 安装检查确认这些 agent 是否就位并给出诊断。修复之前该检查存在一个单运行时假设getAgentsDir()无论当前跑在哪个运行时上都优先返回 Claude 的路径__dirname相对的agents/兄弟目录或~/.claude/agents。于是当用户通过 OpenCode 运行/gsd:init时检查会去 Claude 的目录里找 agent——找不到就报告agents 缺失即记录中所述/gsd:initno longer reports agents as missing on OpenCode and other non-Claude runtimes所修复的误报。该问题的官方 changelog 记录位于 .changeset/archived/384-agents-dir-runtime-aware.mdtype: FixedPR #617本文的源码证据均来自当前仓库。getAgentsDir() 的运行时感知解析从单一路径到四级优先级核心修复落在src/agent-install-check.cts的getAgentsDir(runtime?, projectRoot?)函数。它现在按如下优先级解析 agents 目录源码实现优先级场景解析结果1GSD_AGENTS_DIR环境变量已设置直接返回该值任何运行时均生效的显式覆盖2claude运行时__dirname向上的agents/兄弟目录若该路径含node_modules段npm 全局安装则回退到getGlobalConfigDir(claude)/agents尊重CLAUDE_CONFIG_DIR3非 Claude 运行时 项目根若项目本地配置目录存在agents/子目录且存在gsd-file-manifest.json即 manifest 背书的本地产安装返回该本地目录否则落入第 4 级4非 Claude 运行时默认getGlobalConfigDir(runtime)/agents即按运行时查全局配置目录两个关键设计值得展开GSD_AGENTS_DIR 显式覆盖。环境变量优先于一切运行时推断这是排查问题时的第一手段。设置GSD_AGENTS_DIR/path/to/agents即可让 init 检查、verify 检查以及resolveAgentHint全部指向指定目录。npm 全局安装的 node_modules 词法守卫。对 claude 运行时源码通过installRelative.split(path.sep).includes(node_modules)判断当前是否为 npm 全局安装此时gsd-core位于包内、包自带的agents/会被用于自校验导致agents_installed永远不可能为 false从而重定向到全局配置目录注释与实现。非 Claude 运行时的本地安装探测第 3 级逻辑值得单独说明源码它先从capability-registry读取该运行时的hostBehaviors.localTargetIsProjectRoot决定本地配置目录是项目根本身还是projectRoot/localConfigDirName随后要求agents/目录与gsd-file-manifest.json同时存在才认定为本地安装。这一manifest 背书约束的目的是防止运行时原生的项目级 agents 目录遮蔽一个正常的全局 GSD 安装。若探测失败如权限异常则静默回退到全局配置目录属于 best-effort 设计。全局配置目录的解析getGlobalConfigDir第 4 级依赖src/runtime-homes.cts的getGlobalConfigDir(runtime)实现其解析链为已退役的运行时 id 一律拒绝解析assertNotRetiredRuntimeexplicitDir参数经~展开后直接返回grok走硬编码分支GROK_AGENTS_HOME或~/.agents其余运行时查capability-registry中该运行时注册的configHome描述符resolveDescriptorWithOptions并遵循对应环境变量覆盖未知运行时回退到CLAUDE_CONFIG_DIR或~/.claude。也就是说OpenCode、Cursor、Cline 等运行时的 agents 目录由各自在 registry 中的configHome描述决定而不是被硬编码到 Claude 路径——这正是运行时感知修复的核心。init 诊断字段agent_runtime 与 agents_dir 的引入修复的第二个部分是/gsd:init的诊断输出。src/init.cts的withProjectRoot()在输出结果中注入实现const activeRuntime resolveReportedRuntime(cwd); const agentStatus checkAgentsInstalled(activeRuntime, cwd); result[agents_installed] agentStatus.agents_installed; result[missing_agents] agentStatus.missing_agents; result[agents_dir] agentStatus.agents_dir; result[agent_runtime] agentStatus.agent_runtime;其中agent_runtime与agents_dir正是本次修复新增的诊断字段让用户在报告输出中能直接看到检查基于哪个运行时、指向哪个目录。agent_runtime 的宿主检测阶梯agent_runtime不再写死claude而是通过src/host-runtime-detection.cts的resolveReportedRuntime(projectDir)解析实现。其优先级阶梯为显式来源GSD_RUNTIME环境变量或项目.planning/config.json的runtime字段由resolveExplicitRuntime解析安装标记按安装写入的.gsd-runtime标记#4717 引入用于多运行时机器上避免主机嗅探误报宿主检测detectHostRuntime()通过进程环境信号推断——CODEX_SANDBOX/CODEX_SANDBOX_NETWORK_DISABLED任一非空值或显式CODEX_HOME下存在config.toml则判定为codex兜底默认claude。detectHostRuntime有三个明确约束绝不写盘#2297防止污染共享默认配置、绝不 spawn 子进程无超时问题、任何异常降级为未检测到。注意resolveReportedRuntime是独立于resolveRuntime的阶梯——后者保持旧行为不变ADR-2313 范围边界这是刻意为之的隔离设计。agents_dir 的完整结果结构checkAgentsInstalled()返回的完整结构接口定义为interface AgentsInstalledResult { agents_installed: boolean; missing_agents: string[]; installed_agents: string[]; incomplete_agents: string[]; agents_dir: string; agent_runtime: string; }判定逻辑为agents_installed当且仅当至少装了一个、missing_agents与incomplete_agents均为空。完整性检查基于gsd-file-manifest.json若 manifest 记录了某 agent 的agents/name.ext条目但磁盘上缺少对应文件例如.md在而.toml缺失该 agent 会被标记为incomplete实现。当 agents 目录本身不存在时直接返回agents_installed: false且missing_agents为全部预期 agent实现诊断信息中的agents_dir让用户一眼看到检查的是哪个路径。从 verify 到健康诊断W010 规则如何消费这些字段agent_runtime/agents_dir不止被 init 输出。src/verify.cts在验证时同样执行checkAgentsInstalled并将agents_dir纳入结果verify.cts 调用点。src/health-diagnostic-rules/agent-install.cts的 W010 规则则消费agents_dir生成可读警告规则实现典型消息如No GSD agents found in agents_dir — Task(subagent_typegsd-*) will fall back to general-purpose提示用户执行npx gsd-corelatest重新安装。此外resolveAgentHint()在解析计划中的agent_hint专业 agent 时会同时探测getAgentsDir()的结果与全局配置 agents 目录实现并拒绝包含路径分隔符或..的输入以防路径穿越——这些下游消费点都受益于本次按运行时解析的修复。测试验证行为如何被锁定修复行为在测试中有完整锁定主要位于tests/agent-install-check.test.cjs与tests/host-runtime-detection.test.cjs非 Claude 运行时解析getAgentsDir(cursor)必须等于getGlobalConfigDir(cursor)/agents测试manifest 背书的本地安装codex/cline 运行时在存在 manifest 时优先返回项目本地agents/测试结果字段完整性断言返回结果包含agent_runtime: cursor与agents_dir测试宿主检测阶梯CODEX_SANDBOX检测 codex 会话、CODEX_HOMEconfig.toml检测 codex 根、会话信号优先于 config-home、默认~/.codex永不探测、检测绝不写盘等测试报告运行时优先级GSD_RUNTIME胜过 config、config 胜过宿主检测、安装标记胜过宿主检测、无信号回退 claude 等测试。这些测试共同保证了同一份代码在 Claude 与 OpenCode 等运行时下得到各自正确的 agents 目录且诊断字段可被机器断言。实际使用与排查指引结合仓库源码实践中的排查建议如下查看 init 诊断运行/gsd:init重点看agent_runtime确认基于哪个运行时检查与agents_dir确认检查哪个目录若agent_runtime不是预期运行时优先检查GSD_RUNTIME环境变量与项目.planning/config.json的runtime字段。显式指定目录设置GSD_AGENTS_DIR可绕过一切运行时推断适合自定义 agent 布局。区分本地安装与全局安装本地安装要求agents/与gsd-file-manifest.json共存仅存在agents/而没有 manifest 时检查会回退到全局配置目录。完整性告警若incomplete_agents非空说明 manifest 跟踪的生成文件缺失重新运行安装器即可补齐。本修复的本质是消除了运行时路径假设这一隐含单点将 agents 目录解析从硬编码 Claude 路径升级为按运行时 项目根 环境变量四级判定并为诊断输出补齐agent_runtime/agents_dir两个可观测字段。仓库中 src/agent-install-check.cts、src/host-runtime-detection.cts、src/runtime-homes.cts 与对应测试共同构成对该行为的完整契约。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐GSD 将 Antigravity 建模为一等运行时/gsd:update 运行时解析修复Bug 3608深入解析GSD 将 Antigravity 建模为一等运行时 /gsd:update 运行时解析修复Bug 3608深入解析 导读 本文围绕 GSDGet Shgsd-core 修复 global: 技能路径解析runtime-homes 模块与多运行时 skills 目录的规范化映射gsd core 修复 global: 技能路径解析runtime homes 模块与多运行时 skills 目录的规范化映射 导读 本文以 gsd core.NET 运行时 Mono 的 Bitcode 兼容执行llvmonly 模式深度解析.NET 运行时 Mono 的 Bitcode 兼容执行llvmonly 模式深度解析 导读 本文基于 docs/design/mono/web/bitcod语言运行时标准库JIT编译编译器上一篇深度解析如何构建高效的自托管游戏串流服务器Sunshine下一篇告别付费限制5分钟解锁Wand所有高级功能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考