Back to Details

gsd-surface

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<objective> Manage the runtime skill surface without reinstall. Reads/writes `~/.claude/.gsd-surface.json` (sibling to `~/.claude/.gsd-profile`) and re-stages the active skills directory in place. Skill dirs live at `~/.claude/skills/gsd-*/`.
Sub-commands: list · status · profile · disable · enable · reset </objective>
<objective> 无需重新安装即可管理运行时技能表面。读取/写入`~/.claude/.gsd-surface.json` （与`~/.claude/.gsd-profile`同级），并原地重新部署活动技能目录。 技能目录位于`~/.claude/skills/gsd-*/`。
子命令：list · status · profile · disable · enable · reset </objective>

Sub-command routing

子命令路由

Parse the first token of $ARGUMENTS:
TokenAction
list
Show enabled + disabled clusters and skills
status
Alias for 
list
plus token cost summary
profile <name>
Write 
baseProfile
and re-stage
profile <n1>,<n2>
Composed profiles (comma-separated, no spaces)
disable <cluster>
Add cluster to 
disabledClusters
, re-stage
enable <cluster>
Remove cluster from 
disabledClusters
, re-stage
reset
Delete 
.gsd-surface.json
, return to install-time profile
(none)Treat as 
list
解析$ARGUMENTS的第一个令牌：
令牌操作
list
显示已启用和已禁用的集群及技能
status
list
的别名，额外显示令牌成本汇总
profile <name>
写入
baseProfile
并重新部署
profile <n1>,<n2>
组合配置文件（逗号分隔，无空格）
disable <cluster>
将集群添加到
disabledClusters
，重新部署
enable <cluster>
将集群从
disabledClusters
移除，重新部署
reset
删除
.gsd-surface.json
，恢复为安装时配置文件
(无)视为
list
命令

list / status

list / status

Load the capability registry and call 
listSurface(runtimeConfigDir, manifest, CLUSTERS, registry)
from the engine module at 
${runtimeConfigDir}/gsd-core/bin/lib/surface.cjs
. The registry is loaded via:
js
const registry = require(runtimeConfigDir + '/gsd-core/bin/lib/capability-registry.cjs');
Display:
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%)
For 
status
also append:
Base profile:   standard  (from .gsd-surface.json)
Install profile: standard  (from .gsd-profile)
加载能力注册表，并从引擎模块
${runtimeConfigDir}/gsd-core/bin/lib/surface.cjs
调用
listSurface(runtimeConfigDir, manifest, CLUSTERS, registry)
。注册表通过以下方式加载：
js
const registry = require(runtimeConfigDir + '/gsd-core/bin/lib/capability-registry.cjs');
显示内容：
已启用（N个技能，约T令牌）：
  core_loop:   new-project  discuss-phase  plan-phase  execute-phase  help  update
  audit_review: …
  …

已禁用：
  utility:  health  stats  settings  …

令牌成本：约T（200k上下文@1%时预算上限约500令牌）
对于
status
命令，还需追加：
基础配置文件:   standard  (来自 .gsd-surface.json)
安装配置文件: standard  (来自 .gsd-profile)

profile <name>

profile <name>

  1. Read current surface: 
    readSurface(runtimeConfigDir)
    → if null, seed from 
    readActiveProfile(runtimeConfigDir)
    .
  2. Set 
    surfaceState.baseProfile = name
    .
  3. writeSurface(runtimeConfigDir, surfaceState)
    .
  4. Resolve and re-apply:
    js
    const registry = require(runtimeConfigDir + '/gsd-core/bin/lib/capability-registry.cjs');
const layout = resolveRuntimeArtifactLayout(runtime, runtimeConfigDir, scope);
applySurface(runtimeConfigDir, layout, manifest, CLUSTERS, registry);
  5. Confirm: "Surface updated to profile 
    <name>
    . N skills enabled."
  1. 读取当前表面状态：
    readSurface(runtimeConfigDir)
    → 如果为null，从
    readActiveProfile(runtimeConfigDir)
    初始化。
  2. 设置
    surfaceState.baseProfile = name
    。
  3. 执行
    writeSurface(runtimeConfigDir, surfaceState)
    。
  4. 解析并重新应用：
    js
    const registry = require(runtimeConfigDir + '/gsd-core/bin/lib/capability-registry.cjs');
const layout = resolveRuntimeArtifactLayout(runtime, runtimeConfigDir, scope);
applySurface(runtimeConfigDir, layout, manifest, CLUSTERS, registry);
  5. 确认提示："已将表面更新为配置文件
    <name>
    。已启用N个技能。"

disable <cluster>

disable <cluster>

Valid cluster names: 
core_loop
, 
audit_review
, 
milestone
, 
research_ideate
, 
workspace_state
, 
docs
, 
ui
, 
ai_eval
, 
ns_meta
, 
utility
.
  1. Validate cluster name against 
    Object.keys(CLUSTERS)
    .
  2. Read or initialize surface state.
  3. Add cluster to 
    surfaceState.disabledClusters
    (deduplicate).
  4. writeSurface
    → resolve layout → 
    applySurface
    :
    js
    const registry = require(runtimeConfigDir + '/gsd-core/bin/lib/capability-registry.cjs');
const layout = resolveRuntimeArtifactLayout(runtime, runtimeConfigDir, scope);
applySurface(runtimeConfigDir, layout, manifest, CLUSTERS, registry);
  5. Confirm: "Disabled cluster 
    <cluster>
    . N skills removed from surface."
有效集群名称：
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. 执行
    writeSurface
    → 解析布局 → 
    applySurface
    ：
    js
    const registry = require(runtimeConfigDir + '/gsd-core/bin/lib/capability-registry.cjs');
const layout = resolveRuntimeArtifactLayout(runtime, runtimeConfigDir, scope);
applySurface(runtimeConfigDir, layout, manifest, CLUSTERS, registry);
  5. 确认提示："已禁用集群
    <cluster>
    。已从表面移除N个技能。"

enable <cluster>

enable <cluster>

  1. Read surface state; if null, nothing to enable — print "No surface delta active."
  2. Remove cluster from 
    surfaceState.disabledClusters
    .
  3. writeSurface
    → resolve layout → 
    applySurface
    :
    js
    const registry = require(runtimeConfigDir + '/gsd-core/bin/lib/capability-registry.cjs');
const layout = resolveRuntimeArtifactLayout(runtime, runtimeConfigDir, scope);
applySurface(runtimeConfigDir, layout, manifest, CLUSTERS, registry);
  4. Confirm: "Enabled cluster 
    <cluster>
    . N skills added back to surface."
  1. 读取表面状态；如果为null，无可用启用项 — 输出"无活动表面增量。"
  2. 将集群从
    surfaceState.disabledClusters
    中移除。
  3. 执行
    writeSurface
    → 解析布局 → 
    applySurface
    ：
    js
    const registry = require(runtimeConfigDir + '/gsd-core/bin/lib/capability-registry.cjs');
const layout = resolveRuntimeArtifactLayout(runtime, runtimeConfigDir, scope);
applySurface(runtimeConfigDir, layout, manifest, CLUSTERS, registry);
  4. 确认提示："已启用集群
    <cluster>
    。已将N个技能重新添加到表面。"

reset

reset

  1. Check if 
    .gsd-surface.json
    exists.
  2. Delete it.
  3. Re-apply using only 
    readActiveProfile(runtimeConfigDir)
    (install-time profile).
  4. Confirm: "Surface reset to install-time profile 
    <name>
    ."
  1. 检查
    .gsd-surface.json
    是否存在。
  2. 删除该文件。
  3. 仅使用
    readActiveProfile(runtimeConfigDir)
    （安装时配置文件）重新应用。
  4. 确认提示："已将表面重置为安装时配置文件
    <name>
    。"

runtimeConfigDir resolution

runtimeConfigDir解析

The 
runtimeConfigDir
for 
applySurface
is the base Claude config directory (
~/.claude
), NOT the skills sub-directory (
~/.claude/skills
).
This matches 
installRuntimeArtifacts
and 
uninstallRuntimeArtifacts
, which also receive 
~/.claude
as 
configDir
. The skill dirs themselves live at 
~/.claude/skills/gsd-*/
because the 
claude global
layout has 
destSubpath = 'skills'
— they are derived from 
configDir
, not the root for it.
bash
undefined
applySurface
使用的
runtimeConfigDir
是Claude基础配置目录 (
~/.claude
)，而非技能子目录(
~/.claude/skills
)。
这与
installRuntimeArtifacts
和
uninstallRuntimeArtifacts
的逻辑一致，它们同样将
~/.claude
作为
configDir
传入。技能目录本身位于 
~/.claude/skills/gsd-*/
，因为
claude global
布局的
destSubpath = 'skills'
— 它们由
configDir
派生而来，而非其根目录。
bash
undefined

Claude Code — global install

Claude Code — 全局安装

RUNTIME_CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}" SCOPE="global"
RUNTIME_CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}" SCOPE="global"

Artifact destinations are derived from runtime layout

工件目标路径通过运行时布局解析

via resolveRuntimeArtifactLayout(runtime, RUNTIME_CONFIG_DIR, SCOPE)

调用resolveRuntimeArtifactLayout(runtime, RUNTIME_CONFIG_DIR, SCOPE)

then applySurface(RUNTIME_CONFIG_DIR, layout, manifest, CLUSTERS)

然后执行applySurface(RUNTIME_CONFIG_DIR, layout, manifest, CLUSTERS)


Surface state is stored at `${RUNTIME_CONFIG_DIR}/.gsd-surface.json`
(i.e. `~/.claude/.gsd-surface.json`).

All paths can be overridden by reading the `CLAUDE_CONFIG_DIR` env var if set.

---

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

所有路径均可通过读取已设置的`CLAUDE_CONFIG_DIR`环境变量进行覆盖。

---

Error handling

错误处理

  • Unknown cluster name → list valid cluster names, exit without writing.
  • Unknown profile name → list known profiles (
    core
    , 
    standard
    , 
    full
    ), exit.
  • Missing 
    surface.cjs
    → prompt: "Run 
    npm i -g @opengsd/gsd-core
    to reinstall GSD."
<execution_context> Surface state file: 
~/.claude/.gsd-surface.json
Install profile marker: 
~/.claude/.gsd-profile
Skill dirs: 
~/.claude/skills/gsd-*/
Engine module: 
~/.claude/gsd-core/bin/lib/surface.cjs
Cluster definitions: 
~/.claude/gsd-core/bin/lib/clusters.cjs
</execution_context>
  • 未知集群名称 → 列出有效集群名称，不执行写入直接退出。
  • 未知配置文件名称 → 列出已知配置文件（
    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>