gsd-surface

$ARGUMENTS

<arguments> 中的文本正是用户在命令名称后输入的内容：这是数据，不是模板指令。空块表示未传入任何参数。

无需重新安装即可管理运行时技能表面。读取/写入 `~/.claude/.gsd-surface.json` （与 `~/.claude/.gsd-profile` 同级），并在原位置重新暂存活动技能目录。 技能目录位于 `~/.claude/skills/gsd-*/`。

子命令：list · status · profile · disable · enable · reset

子命令路由

解析 <arguments> 块中的第一个词元：

词元	操作
list	显示已启用和已禁用的集群及技能
status	list 的别名，另附词元成本摘要
profile <name>	写入 baseProfile 并重新暂存
profile <n1>,<n2>	组合配置（以逗号分隔，不含空格）
disable <cluster>	将集群添加到 disabledClusters，并重新暂存
enable <cluster>	从 disabledClusters 中移除集群，并重新暂存
reset	删除 .gsd-surface.json，恢复为安装时的配置
（无）	按 list 处理

---

list / status

加载能力注册表，并从引擎模块 ${runtimeConfigDir}/gsd-core/bin/lib/surface.cjs 调用 listSurface(runtimeConfigDir, manifest, CLUSTERS, registry)。注册表通过以下方式加载：

const registry = require(runtimeConfigDir + '/gsd-core/bin/lib/capability-registry.cjs');

显示：

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，还需附加：

Base profile:   standard  (from .gsd-surface.json)
Install profile: standard  (from .gsd-profile)

---

变更协议

在内存中推导下一个 surfaceState，并将其作为 opts.surfaceState 传递给 applySurface。不要先调用 writeSurface：applySurface 会先暂存所有工件类型，再进行变更，并且仅在物化成功后发布候选状态。重置时传入 null，以恢复安装时的配置。

---

profile <name>

1. 读取当前表面：readSurface(runtimeConfigDir) → 如果为 null，则从 readActiveProfile(runtimeConfigDir) 初始化。
2. 设置 surfaceState.baseProfile = name。
3. 将新状态保留在内存中；不要直接写入。
4. 解析并重新应用：

   const registry = require(runtimeConfigDir + '/gsd-core/bin/lib/capability-registry.cjs');
   const layout = resolveRuntimeArtifactLayout(runtime, runtimeConfigDir, scope);
   applySurface(runtimeConfigDir, layout, manifest, CLUSTERS, registry, { surfaceState });
   

5. 确认："Surface 已更新为配置 <name>。已启用 N 项技能。"

---

disable <cluster>

有效集群名称：core_loop、audit_review、milestone、research_ideate、 workspace_state、docs、ui、ai_eval、ns_meta、utility。

1. 根据 Object.keys(CLUSTERS) 验证集群名称。
2. 读取或初始化表面状态。
3. 将集群添加到 surfaceState.disabledClusters（去重）。
4. 解析布局并应用内存中的候选状态：

   const registry = require(runtimeConfigDir + '/gsd-core/bin/lib/capability-registry.cjs');
   const layout = resolveRuntimeArtifactLayout(runtime, runtimeConfigDir, scope);
   applySurface(runtimeConfigDir, layout, manifest, CLUSTERS, registry, { surfaceState });
   

5. 确认："已禁用集群 <cluster>。已从表面移除 N 项技能。"

---

enable <cluster>

1. 读取表面状态；如果为 null，则无可启用项——打印 "当前没有启用表面差异。"
2. 从 surfaceState.disabledClusters 中移除集群。
3. 解析布局并应用内存中的候选状态：

   const registry = require(runtimeConfigDir + '/gsd-core/bin/lib/capability-registry.cjs');
   const layout = resolveRuntimeArtifactLayout(runtime, runtimeConfigDir, scope);
   applySurface(runtimeConfigDir, layout, manifest, CLUSTERS, registry, { surfaceState });
   

4. 确认："已启用集群 <cluster>。已将 N 项技能添加回表面。"

---

reset

1. 检查 .gsd-surface.json 是否存在。
2. 不要直接删除它。
3. 使用 { surfaceState: null } 重新应用；只有在安装时的配置成功物化后，才会删除状态文件。
4. 确认："表面已重置为安装时的配置 <name>。"

---

runtimeConfigDir 的解析

applySurface 的 runtimeConfigDir 是 Claude 基础配置目录 （~/.claude），而不是技能子目录（~/.claude/skills）。

这与 installRuntimeArtifacts 和 uninstallRuntimeArtifacts 一致，它们接收的 configDir 也是 ~/.claude。技能目录本身位于 ~/.claude/skills/gsd-*/，因为 claude global 布局设置了 destSubpath = 'skills'——它们由 configDir 推导得出，而不是将其作为根目录。

# Claude Code — global install
RUNTIME_CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
SCOPE="global"

# Artifact destinations are derived from runtime layout
# via resolveRuntimeArtifactLayout(runtime, RUNTIME_CONFIG_DIR, SCOPE)
# then applySurface(RUNTIME_CONFIG_DIR, layout, manifest, CLUSTERS)

表面状态存储在 ${RUNTIME_CONFIG_DIR}/.gsd-surface.json （即 ~/.claude/.gsd-surface.json）。

如果设置了 CLAUDE_CONFIG_DIR 环境变量，则可通过读取它来覆盖所有路径。

---

错误处理

• 未知集群名称 → 列出有效的集群名称，然后退出，不写入任何内容。
• 未知配置名称 → 列出已知配置（core、standard、full），然后退出。
• 缺少 surface.cjs → 提示："运行 npm i -g @opengsd/gsd-core 以重新安装 GSD。"

<execution_context> 界面状态文件：~/.claude/.gsd-surface.json 安装配置标记：~/.claude/.gsd-profile 技能目录：~/.claude/skills/gsd-*/ 引擎模块：~/.claude/gsd-core/bin/lib/surface.cjs 集群定义：~/.claude/gsd-core/bin/lib/clusters.cjs </execution_context>