【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载/gsd:surface是 GSDGet. Ship. Done — Core提供的运行时技能表面skill surface开关命令用于在已安装环境下动态启用/禁用技能集群、切换命名 Profile而无需重新执行安装流程。本文以仓库变更记录 feat-3408-skill-surface.md 为核心骨架结合 runbook、ADR-0011、研究备忘录与 src/surface.cts 源码完整讲解该功能的背景、子命令、10 个集群、状态持久化模型与底层引擎原理读完即可上手管理自己的技能表面。一、为什么需要技能表面技能清单预算与静默丢弃Claude Code 等运行时会在每一轮对话把已安装 skill 的name description枚举进系统提示中的available_skills块该块受skillListingBudgetFraction限制——默认是模型上下文窗口的1%在 200k 上下文中约2000 tokens。当多个插件叠加、描述总长超过预算时运行时只会静默截断尾部用户根本无法察觉部分技能已被丢弃。研究备忘录 2026-05-12-skill-surface-budget.md 给出了 GSD 当时的审计数据指标数值已安装技能66已安装子代理33不进入available_skills经Task调用技能描述总字符数4,787估算描述 tokens÷4~1,196平均描述长度72.5 字符描述长度上限scripts/lint-descriptions.cjs 强制100 字符GSD 占 200k 上下文 1% 预算的份额~60%也就是说GSD 单靠自己就吃掉了默认技能清单预算的约六成再叠加任何一个体量相近的插件就会超限、触发静默丢弃issue #3408 的报告者装了 135 个技能。更关键的是描述已经压到 72.5 字符均值、100 字符硬上限继续压缩文字不是出路出路是少发射技能。根因是缺乏 profile/surface 接缝——安装器无条件写入全部技能运行时又没有无需重装的开关。二、整体方案ADR-0011 的 Phase 1安装 Profile Phase 2运行时 Surface方案沿用了研究备忘录的推荐路径分两阶段落地记录在 ADR-0011并取代早期草案 ADR-0010Phase 1 — 安装期命名 Profile安装时用--profilename选择core/standard/full计算requires:依赖闭包后写入运行时目录并把所选 Profile 持久化到.gsd-profile标记文件gsd update读取标记、尊重 Profile不再在升级时悄悄膨胀回 full。详见同主题的变更记录 feat-3408-skill-profiles.md。Phase 2 — 运行时 Surface 模块即本文主角/gsd:surface。引擎在gsd-core/bin/lib/surface.cjsTypeScript 真源为 src/surface.cts复用 Phase 1 的stageSkillsForProfile/stageAgentsForProfile完成重新落地集群定义独立放 src/clusters.cts让引擎和未来的 SDK 调用方无需加载整个 profile 模块即可引用。功能层面的权威说明可另见 skill-surface-budgeting.md其中记录了三条需求约束安装器必须解析--profilename并持久化到.gsd-profileREQ-SURFACE-01--minimal与--core-only必须保持为--profilecore的别名REQ-SURFACE-02运行时表面状态必须独立于安装 Profile 标记持久化REQ-SURFACE-03。三、三个命名 Profile 与requires:依赖闭包Profile 定义在 src/install-profiles.cts 的PROFILES常量中ADR-457 构建时发布手写.cjs已坍缩为 TypeScript 真源行为逐字节保留Profile用途基集源码现状core最小主循环表面new-project、discuss-phase、plan-phase、execute-phase、phase、help、update、surfacestandard核心 常用阶段/工作区命令core 基础上追加onboard、review、config、progress、resume-work、pause-work、workspacefull完整表面默认*哨兵全部技能值得注意两点演进研究备忘录曾指出旧 minimal allowlist 缺少phase——它被 38 个技能引用是典型的依赖热点。当前源码的core已把phase纳入基集规避了最小安装 主循环调用断裂的潜在缺陷。每个 Profile 的有效技能集合是基集的传递闭包effective CLOSURE(base, requires: manifest)。standard自动包含core的全部成员--profilecore,audit组合则解析为union(closure(core), closure(audit))。闭包的图来自每个技能 frontmatter 新增的requires:字段66 个技能全部声明。解析函数resolveProfile对 mode 列表做flatMap(split(,))归一化一旦命中full直接返回*哨兵无效/损坏的 marker 会回退为 full避免出现空安装。该依赖图由 CI 门禁 scripts/lint-skill-deps.cjs接入pretest强制校验每个requires:必须能解析到真实技能 stem防止 Profile 闭包静默过度安装或装坏依赖链。四、/gsd:surface子命令全解runbook 见 commands/gsd/surface.md技能包装形态见 skills/gsd-surface/SKILL.md。命令解析$ARGUMENTS的第一个 tokenToken动作list显示启用 禁用的集群与技能statuslist的别名附加 token 成本汇总profile name写入baseProfile并重新落地re-stageprofile n1,n2组合 Profile逗号分隔无空格disable cluster把集群加入disabledClusters并重新落地enable cluster从disabledClusters移除集群并重新落地reset删除.gsd-surface.json回到安装期 Profile空视作listlist输出示例runbook 原始格式…为省略的其余集群Enabled (N skills, ~T tokens): core_loop: new-project discuss-phase plan-phase execute-phase help update audit_review: … … Disabled: utility: health stats settings … Token cost: ~T (budget cap ~500 tokens for 200k context 1%)status额外追加 Profile 摘要Base profile: standard (from .gsd-surface.json) Install profile: standard (from .gsd-profile)五、10 个技能集群定义与成员集群是技能表面的唯一权威分类法定义在 src/clusters.cts 的CLUSTERS常量构建时发布来源为研究备忘录 §3.2 的贪心聚类。成员允许重叠一个技能可属多个集群且每个已安装技能 stem 必须至少出现在一个集群中由surface-clusters.test.cjs强制。源码当前十个集群集群成员源码现状语义core_loopnext、new-project、onboard、discuss-phase、plan-phase、execute-phase、help、update主循环最小集audit_reviewcode-review、review、audit-fix、audit-milestone、audit-uat、verify-work、validate-phase、plan-review-convergence、eval-review、add-tests、secure-phase审计与评审milestonenew-milestone、complete-milestone、milestone-summary、health里程碑管理research_ideatesketch、spike、forensics、explore、graphify、ns-ideate研究/构思workspace_statepause-work、resume-work、workspace、workstreams、thread、capture、inbox工作区与状态docsdocs-update、ingest-docs文档uiui-phase、ui-reviewUI 工作流ai_evalai-integration-phase、eval-reviewAI 集成与评估ns_metans-context、ns-ideate、ns-manage、ns-project、ns-review、ns-workflow命名空间元工作流utilityhealth、stats、settings、cleanup、pr-branch、ship、undo、fast、quick、quick-batch、autonomous、config、progress、phase、review、update、help、code-review、import、manager、map-codebase、profile-user、spec-phase、ultraplan-phase、mvp-phase、execute-phase、review-backlog、debug、extract-learnings、mempalace-recall、mempalace-capture、surface工具杂项最重桶utility是描述 token 占比最重的集群研究阶段约占总描述 tokens 的 36%且最异构——大量技能是每项目一次而非每会话一次是开启按需裁剪时的首选目标。六、状态持久化.gsd-profile与.gsd-surface.json的分工Phase 2 的核心设计决策是两套状态文件分离.gsd-profile~/.claude/.gsd-profile安装期身份由安装器写入gsd update尊重它。.gsd-surface.json~/.claude/.gsd-surface.json会话期集群开关由/gsd:surface读写。注意本 changeset 记录的状态文件路径为~/.claude/skills/.gsd-surface.jsonskills 子目录而最终实现runbook 与 src/surface.cts 的SURFACE_FILE_NAME .gsd-surface.jsonpath.join(runtimeConfigDir, ...)将其放在base Claude 配置目录~/.claude/.gsd-surface.json。runbook 的runtimeConfigDir resolution一节对此有专门说明传给applySurface的是 base config 目录而非 skills 子目录与installRuntimeArtifacts/uninstallRuntimeArtifacts收到~/.claude作为configDir保持一致技能目录~/.claude/skills/gsd-*/是因为claude global布局的destSubpath skills由configDir派生而非根。本文以最终实现为准。状态文件的结构src/surface.cts 的SurfaceState类型写入时经platformWriteSync原子写为缩进 2 的 JSON{ baseProfile: ..., disabledClusters: [...], explicitAdds: [...], explicitRemoves: [...] }读取方readSurface会做结构校验baseProfile必须是字符串、三个数组字段必须是数组文件缺失或损坏一律返回nullfailing closed。七、底层引擎原理解析顺序与两阶段提交引擎导出的核心函数src/surface.cts包括readSurface、writeSurface、resolveSurface、applySurface、listSurface、pruneSkillDirs。有效技能集解析公式resolveSurface源码注释原话Effective skill set base profile ∪ explicitAdds − disabledClusters − explicitRemoves随后经 manifest 做传递闭包。解析顺序以surface.baseProfile无则回退readActiveProfile再回退full解析基础 Profile删除被禁用集群覆盖的技能加入explicitAdds及其传递闭包BFS删除explicitRemoves仅删该 stem不级联。agents由技能派生对每个保留技能读取 manifest 中_calls_agents_stem条目收集其引用的子代理 stem。返回的名称形如surface:baseProfile或profile:name。两阶段提交协议applySurfacerunbook 的Mutation protocol一节所有变更操作profile/disable/enable/reset都先在内存推导候选状态opts.surfaceState再交给applySurface绝不先调writeSurface。applySurface内部先遍历layout.kinds逐个kind.stage()把每种产物skills / agents / commands / kimi-agents 等暂存到临时目录全部成功后执行retiredArtifactCleanup.pruneRetiredRuntimeArtifacts对每个 kind 执行_syncGsdDir同步到目标目录skills 目录的裁剪统一委托给pruneSkillDirs用户自建的gsd-*目录一律保留并告警最后才发布状态candidateState null时删除.gsd-surface.jsonreset语义否则writeSurface写入候选状态。任何 kind 暂存失败都会让已安装产物和持久化状态双双保持原样——这就是变更不落地则不写状态的原子性保证。applySurface还有多重防护runtimeConfigDir必须与layout.configDir相等否则抛TypeError、assertTestHomeSandboxed防测试逃逸到真实 home、assertDestWithinConfigHome约束目标路径。token 成本估算listSurface对每个启用技能读取安装源的commands/gsd/stem.md取 frontmatterdescription:值按ceil(长度 ÷ 4)累加与审计脚本口径一致。八、运行时目录解析与环境变量runbook 给出的 global 安装参考脚本# Claude Code — global install RUNTIME_CONFIG_DIR${CLAUDE_CONFIG_DIR:-$HOME/.claude} SCOPEglobal # Artifact destinations are derived from runtime layout # via resolveRuntimeArtifactLayout(runtime, RUNTIME_CONFIG_DIR, SCOPE) # then applySurface(RUNTIME_CONFIG_DIR, layout, manifest, CLUSTERS)Surface 状态文件${RUNTIME_CONFIG_DIR}/.gsd-surface.json即默认~/.claude/.gsd-surface.json。所有路径均可通过读取CLAUDE_CONFIG_DIR环境变量覆盖。多运行时场景下安装期若 Profile 冲突按最保守 Profile最小有效技能集解决。九、错误处理与恢复路径runbook 定义的错误行为未知集群名 → 列出合法集群名不写盘直接退出未知 Profile 名 → 列出已知 Profilecore、standard、full退出缺少surface.cjs引擎模块 → 提示Run npm i -g opengsd/gsd-core以重装 GSD。enable的边界若 surface 状态为null说明没有任何增量直接输出 No surface delta active.。reset的边界只有安装期 Profile 成功落地后状态文件才被移除。十、测试与 CI 保障仓库对表面引擎有专门的回归测试当前实际存在的测试文件见 tests 目录surface-empty-manifest-agents.test.cjs — 空 manifest 下的代理派生边界runtime-artifact-layout-surface.test.cjs — 表面落地与安装引擎的产物路径/命名一致性ADR 中提到的surface-state / surface-clusters / surface-resolve / surface-apply / surface-list系列测试已随源码折叠合并到上述文件与主测试套件surface-md-paths.regression.test.cjs — 技能文档路径回归集群覆盖完整性由集群模块的allClusteredSkills()辅助函数与对应测试保证每个已安装 stem 必须落入至少一个集群。配合 Phase 1 的scripts/lint-skill-deps.cjs接入pretestrequires:依赖完整性在 CI 阶段即被拦截。十一、实战速览典型操作序列# 1) 查看当前启/禁用状态与 token 成本 /gsd:surface list # 2) 查看 Profile 摘要含安装期 vs 当前 base /gsd:surface status # 3) 切换到 standard Profile无需重装 /gsd:surface profile standard # 4) 组合 Profile /gsd:surface profile core,audit # 5) 按集群关闭最重的 utility 桶 /gsd:surface disable utility # 6) 需要时再加回 /gsd:surface enable utility # 7) 反悔清空增量回到安装期 Profile /gsd:surface reset典型收益ADR-0011 记录受上下文预算约束的用户可先--profilecore安装随后用/gsd:surface enable cluster增量扩容全程无需重装requires:闭包保证任何部分裁剪都不会悄悄破坏跨技能调用。需要注意该命令是 GSD 侧的单方面解决方案不依赖 Anthropic 平台的原生技能开关 API平台侧的 per-skill toggle 与预算协商仍作为独立诉求跟进utility桶技能体量大按需启用是压预算最直接的手段。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐GSD Skill Surface 运行时管理全解析使用 /gsd:surface 按集群开关技能、切换 Profile 而不重装GSD Skill Surface 运行时管理全解析使用 /gsd:surface 按集群开关技能、切换 Profile 而不重装 GSDget shit人工智能AI 应用提示工程开发工具工作流自动化AI Agentget-shit-done 运行时技能面开关指南/gsd:surface 命令的实现原理与实战用法get shit done 运行时技能面开关指南 /gsd:surface 命令的实现原理与实战用法 本文围绕 get shit doneGSD随 .ch人工智能AI 应用提示工程开发工具工作流自动化AI AgentMetabase 如何用 Guest Embeds 在不需要 Metabase 账号的情况下嵌入仪表板Metabase 如何用 Guest Embeds 在不需要 Metabase 账号的情况下嵌入仪表板 如果你的目标是把 Metabase 的仪表板嵌入自己的数据分析数据可视化后端数据库客户端企业应用上一篇微信支付分账比例配置基于EasyWeChat的灵活分账策略实现下一篇HuLa版本控制策略语义化版本与发布流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考