@stofone/dsh-agent-roster 0.0.0-stage → 0.5.1

package/lib/bridge.js

@@ -0,0 +1,233 @@
+/**
+ * 桥接层：把静态档案翻译成 dsh-agent-teams 可以执行的调用参数，并如实标注每个字段的归宿。
+ *
+ * 这一层刻意**只做翻译与核对，不做调用**：真正的成员创建仍由队长模型发起
+ * `agent_teams_add_member`。原因是档案层不知道团队此刻处于什么阶段（暂存/运行/已归档），
+ * 也不应该替运行时决定"现在创建一个成员"。工具只输出参数，模型原样传入，运行时决定成败。
+ *
+ * 三个诚实状态必须被区分，否则档案会给人"能力已被运行时保证"的错觉：
+ *
+ * - `applied`：运行时状态里的值与档案一致（读取的是 team.json，不是我们的请求）；
+ * - `overridden` / `omitted`：运行时最终采用了别的值，或根本没带这个字段；
+ * - `not-carried`：agent-teams 没有对应承载（toolScope、maxTokens 等），档案只是声明。
+ *
+ * @module dsh-agent-roster/bridge
+ */
+import { FIELD_BINDING } from "./format.js";
+
+/** 成员字段 → 调用参数名 / 运行时状态键。 */
+const CARRIED_FIELDS = [
+  { field: "name", param: "name", stateKey: "name" },
+  { field: "role", param: "role", stateKey: "role" },
+  { field: "systemPrompt", param: "executionPrompt", stateKey: "executionPrompt" },
+  { field: "provider", param: "provider", stateKey: "provider" },
+  { field: "model", param: "model", stateKey: "model" },
+  { field: "reasoningEffort", param: "reasoning_effort", stateKey: "reasoningEffort" },
+  { field: "toolPolicy", param: "tool_policy", stateKey: "toolPolicy" },
+];
+
+/** 桥接状态的中文标签，工具输出与 UI 共用。 */
+export const BINDING_STATUS = {
+  pending: "已生成参数，运行时尚未回执",
+  applied: "运行时取值与档案一致",
+  overridden: "运行时实际取值与档案不同",
+  omitted: "运行时未携带该字段",
+  unconfirmed: "缺少运行时状态，无法核对",
+  "not-carried": "agent-teams 无承载，仅声明",
+  "config-required": "需要落到部署配置才生效",
+};
+
+/**
+ * 为一份档案里的一个成员生成桥接结果。
+ *
+ * 字段值缺失时一律写 `null` 而不是 `undefined`：工具返回值要能无损往返 JSON，
+ * 带 `undefined` 的键会被序列化丢掉，运行时因此判整次调用失败。
+ *
+ * @param {object} roster 已校验的档案
+ * @param {object} member 已校验的成员
+ * @returns {{ args: object, planMember: object, binding: object }}
+ */
+export function buildMemberBinding(roster, member) {
+  const args = { name: member.name, role: member.role, executionPrompt: member.systemPrompt };
+  if (member.provider !== undefined) args.provider = member.provider;
+  if (member.model !== undefined) args.model = member.model;
+  if (member.reasoningEffort !== undefined) args.reasoning_effort = member.reasoningEffort;
+  if (member.toolPolicy !== undefined) args.tool_policy = member.toolPolicy;
+
+  const planMember = { name: member.name, role: member.role };
+  if (member.provider !== undefined) planMember.provider = member.provider;
+  if (member.model !== undefined) planMember.model = member.model;
+  if (member.reasoningEffort !== undefined) planMember.reasoning_effort = member.reasoningEffort;
+  if (member.toolPolicy !== undefined) planMember.tool_policy = member.toolPolicy;
+
+  const binding = {
+    rosterId: roster.id,
+    rosterVersion: roster.version,
+    member: member.name,
+    origin: provenanceOf(roster, member),
+    fields: [],
+  };
+
+  for (const { field, param, stateKey } of CARRIED_FIELDS) {
+    const carried = args[param] !== undefined;
+    const source = member.inherited?.includes(field) ? "defaults" : "member";
+    if (!carried && field !== "name" && field !== "role" && field !== "systemPrompt") {
+      binding.fields.push({
+        field,
+        param,
+        stateKey,
+        source,
+        status: "omitted",
+        requested: null,
+        actual: null,
+        note: "档案未指定，运行时将沿用队长默认",
+      });
+      continue;
+    }
+    if (!carried) {
+      // name/role/executionPrompt 永远有值，走到这里说明数据损坏，明确报出来而不是静默跳过。
+      binding.fields.push({
+        field,
+        param,
+        stateKey,
+        source,
+        status: "omitted",
+        requested: null,
+        actual: null,
+        note: "档案缺少该必填字段",
+      });
+      continue;
+    }
+    binding.fields.push({
+      field,
+      param,
+      stateKey,
+      source,
+      status: "pending",
+      requested: args[param],
+      actual: null,
+      note: "",
+    });
+  }
+
+  for (const [field, kind] of Object.entries(FIELD_BINDING)) {
+    if (kind === "direct") continue;
+    const value = member[field];
+    if (value === undefined) continue;
+    if (Array.isArray(value) && value.length === 0) continue;
+    if (typeof value === "string" && value === "") continue;
+    binding.fields.push({
+      field,
+      param: null,
+      stateKey: null,
+      source: member.inherited?.includes(field) ? "defaults" : "member",
+      status: kind === "config" ? "config-required" : "not-carried",
+      requested: value,
+      actual: null,
+      note:
+        kind === "config"
+          ? field === "fallback"
+            ? "备用路由需写进成员创建后的部署配置（本插件不代写配置）"
+            : "该字段需落到部署配置才会生效"
+          : "agent-teams 成员无此承载，档案仅作能力声明与校验依据",
+    });
+  }
+
+  return { args, planMember, binding };
+}
+
+/**
+ * 用一份真实的团队状态（team.json 的 members[]）核对该成员的桥接结果。
+ *
+ * 比对的是运行时**持久化的实际值**，不是我们发出去的请求参数——这是"验证"与"自我报告"的分界。
+ *
+ * @param {object} binding `buildMemberBinding` 产出的 binding
+ * @param {object | null} teamMember team.json 里同名的成员记录
+ * @returns {object} 同一个 binding（就地更新），便于链式使用
+ */
+export function reconcileBinding(binding, teamMember) {
+  const found = teamMember ?? null;
+  for (const entry of binding.fields) {
+    if (entry.param === null) continue;
+    if (found === null) {
+      entry.status = "unconfirmed";
+      entry.note = "团队状态里没有同名成员";
+      continue;
+    }
+    const actual = found[entry.stateKey];
+    entry.actual = actual ?? null;
+    if (actual === undefined || actual === null || actual === "") {
+      entry.status = "omitted";
+      entry.note = "运行时没有记录该字段";
+      continue;
+    }
+    entry.status = valueMatches(entry.field, entry.requested, actual) ? "applied" : "overridden";
+    entry.note = entry.status === "applied" ? "" : "运行时采用了不同的值";
+  }
+  return binding;
+}
+
+/**
+ * 生成绑定摘要：按状态统计，供工具输出和索引里的 `binding` 段使用。
+ *
+ * @param {object} binding
+ * @returns {{ counts: Record<string, number>, carried: number, applied: number, degraded: number }}
+ */
+export function summarizeBinding(binding) {
+  const counts = {};
+  for (const entry of binding.fields) {
+    counts[entry.status] = (counts[entry.status] ?? 0) + 1;
+  }
+  const carried = binding.fields.filter((entry) => entry.param !== null).length;
+  const applied = counts.applied ?? 0;
+  const degraded = (counts.overridden ?? 0) + (counts.omitted ?? 0) + (counts.unconfirmed ?? 0);
+  return { counts, carried, applied, degraded };
+}
+
+/** 人读的一行：`model          已应用  deepseek/deepseek-v4.1-flash（来源：member）`。 */
+export function describeField(entry) {
+  const label = entry.field.padEnd(15, " ");
+  const source = entry.source === "defaults" ? "继承 defaults" : "成员自带";
+  const value = entry.actual !== null ? entry.actual : entry.requested;
+  const rendered =
+    entry.field === "systemPrompt"
+      ? `${String(value ?? "").length} 字符`
+      : value === null || value === undefined
+        ? "—"
+        : typeof value === "string"
+          ? value
+          : JSON.stringify(value);
+  const note = entry.note === "" ? "" : `（${entry.note}）`;
+  return `${label}${BINDING_STATUS[entry.status] ?? entry.status}  ${rendered}  · ${source}${note}`;
+}
+
+/**
+ * 团队状态是否与档案一致：只统计"被运行时承载"的字段。
+ *
+ * 存在 overridden / omitted / unconfirmed 时返回 false——降级必须被看见。
+ */
+export function isBindingFaithful(binding) {
+  const summary = summarizeBinding(binding);
+  return (summary.counts.overridden ?? 0) === 0 && (summary.counts.unconfirmed ?? 0) === 0;
+}
+
+/** `roster:<id>@<version>`——出现在输出、提交信息与绑定记录里的出处标识。 */
+export function provenanceOf(roster, member) {
+  const suffix = member.inherited?.length ? `+${member.inherited.join(",")}` : "";
+  return `roster:${roster.id}@${roster.version}${suffix}`;
+}
+
+/**
+ * 比较字段值。`reasoningEffort` 容许运行时把 "default" 解析成具体档位，
+ * 其余字段要求严格相等：档案说用什么模型，运行时就得记录那个模型。
+ */
+function valueMatches(field, requested, actual) {
+  if (requested === undefined || requested === null) return false;
+  if (field === "systemPrompt") return String(requested).trim() === String(actual).trim();
+  if (field === "reasoningEffort") {
+    if (requested === actual) return true;
+    // "default" 表示"由目标模型决定"，运行时落成任何具体档位都算忠实执行。
+    return requested === "default" || actual === "default";
+  }
+  return String(requested) === String(actual);
+}

package/lib/config-view.js

@@ -0,0 +1,76 @@
+/**
+ * 配置读取视图：把插件配置读成"每次访问都取当前值"的形态。
+ *
+ * 声明为 `volatile` 的字段在运行时拿到的**不是快照值**，而是一个引用对象（`.get()`）：
+ * 宿主用它承载"改设置立即生效"。所以这里不能读一次就存下来——否则用户改了档案库
+ * 目录却要重启宿主，那正是 volatile 想避免的事。
+ *
+ * 三种输入都要能接：引用对象（volatile）、普通值（非 volatile）、缺省（未配置）。
+ *
+ * @module dsh-agent-roster/config-view
+ */
+
+/**
+ * 读一个配置单元：引用对象取值、普通值原样、缺省用兜底。
+ *
+ * @template T
+ * @param {unknown} cell 配置字段
+ * @param {T} fallback 缺省值
+ * @returns {T}
+ */
+function read(cell, fallback) {
+  if (cell === undefined || cell === null) return fallback;
+  if (typeof cell === "object" && typeof cell.get === "function") {
+    const value = cell.get();
+    return value === undefined || value === null ? fallback : value;
+  }
+  if (Array.isArray(cell) && cell.length === 0) return fallback;
+  return cell;
+}
+
+/**
+ * 把 Config 解析结果包成带 getter 的视图。
+ *
+ * 只转发插件真正使用的字段；其余一律不透传，避免下游误把引用对象当数据用。
+ *
+ * @param {object} config `apply(ctx, config)` 收到的配置
+ * @returns {{
+ *   rosterDirs: string[],
+ *   knownToolPolicies: string[],
+ *   agentTeamsStateDir: string,
+ *   indexes: unknown,
+ *   region: string,
+ * }}
+ */
+export function configView(config) {
+  const source = config ?? {};
+  return {
+    get rosterDirs() {
+      // 缺省 = 空串 = 机器级全局库（$DSH_HOME/agent-roster），与 0.3.0 起的默认一致。
+      const dirs = read(source.rosterDirs, [""]);
+      return Array.isArray(dirs) ? dirs : [""];
+    },
+    get knownToolPolicies() {
+      const policies = read(source.knownToolPolicies, []);
+      return Array.isArray(policies) ? policies : [];
+    },
+    get agentTeamsStateDir() {
+      const dir = read(source.agentTeamsStateDir, ".agent-teams");
+      return typeof dir === "string" && dir !== "" ? dir : ".agent-teams";
+    },
+    /**
+     * 索引源。三种取值都必须原样保留：
+     * `undefined`/空数组 = 官方源；显式 `false` = 完全关掉远端；数组 = 自定义源。
+     */
+    get indexes() {
+      if (typeof source.indexes === "object" && source.indexes !== null && typeof source.indexes.get === "function") {
+        return source.indexes.get();
+      }
+      return source.indexes;
+    },
+    get region() {
+      const region = read(source.region, "auto");
+      return typeof region === "string" && region !== "" ? region : "auto";
+    },
+  };
+}

package/lib/format.js

@@ -0,0 +1,223 @@
+/**
+ * 档案与索引的格式常量：标识、上限、模式、字段白名单与绑定类别。
+ *
+ * 这个模块只有数据、没有逻辑，被校验器、桥接层、UI 共同引用；
+ * 改这里等于改格式，必须同步 bump {@link ROSTER_KIND} 或索引格式。
+ *
+ * @module dsh-agent-roster/format
+ */
+
+/** 档案文档格式标识（出现在每份 roster.yaml 的 kind 字段）。 */
+export const ROSTER_KIND = "dsh-agent-roster/v1";
+
+/** 索引文档格式标识（由 scan CLI / GitHub Action 产出）。 */
+export const INDEX_KIND = "dsh-agent-roster-index/v1";
+
+/**
+ * 公共档案库目录（registry）的格式标识。
+ *
+ * 与 {@link INDEX_KIND} 的区别：index 是“一个档案库扫描后的清单”（roster 指针），
+ * registry 是“许多档案库的登记簿”（collection 指针）——后者才是订阅/共享的入口。
+ */
+export const REGISTRY_KIND = "dsh-agent-roster-registry/v1";
+
+/** 单份档案文档的字节上限，超过直接拒绝，避免把仓库当数据库用。 */
+export const MAX_DOCUMENT_BYTES = 256 * 1024;
+
+/** 结构与长度上限。 */
+export const LIMITS = {
+  members: 32,
+  systemPromptChars: 8000,
+  titleChars: 120,
+  descriptionChars: 500,
+  roleChars: 120,
+  idChars: 64,
+  tagChars: 32,
+  tagsPerEntry: 16,
+  notesChars: 500,
+  reasonChars: 400,
+  aliasesPerMember: 8,
+  skillsPerMember: 16,
+  examplesPerMember: 5,
+  exampleChars: 200,
+  captainChars: 4000,
+  collections: 500,
+  rostersPerCollection: 200,
+};
+
+/** 形态模式。 */
+export const PATTERNS = {
+  /** roster id 与成员 name 共用：kebab-case，2~64 字符。 */
+  id: /^[a-z0-9][a-z0-9-]{1,63}$/,
+  /** LLM provider 路由名。 */
+  provider: /^[a-z0-9][a-z0-9._-]{0,63}$/,
+  /** 模型 id：允许厂商前缀与版本号里的点、斜杠、冒号。 */
+  model: /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,119}$/,
+  /** 工具名（命名空间分隔符，精确匹配）。 */
+  toolName: /^[A-Za-z0-9_][A-Za-z0-9_.:-]{0,127}$/,
+  /** 工具匹配模式：精确名，或末尾带一个 `*` 的前缀通配（如 `git:*`、`files*`）。 */
+  toolPattern: /^[A-Za-z0-9_][A-Za-z0-9_.:-]{0,126}\*?$/,
+  /** 精确 SemVer。 */
+  semver: /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/,
+  /** 40 位小写 commit SHA（索引指针只接受这种精确形态）。 */
+  commit: /^[0-9a-f]{40}$/,
+  /** 标签令牌。 */
+  tag: /^[a-z0-9][a-z0-9-]{0,31}$/,
+  /** 技能名：与 DSH 技能目录同名，允许点与下划线（如 `frontend-skill`、`eastmoney-quant`）。 */
+  skill: /^[a-z0-9][a-z0-9._-]{0,63}$/,
+  /** 仓库坐标：`github:owner/repo` 或 `owner/repo`（只允许 GitHub 与普通字符）。 */
+  repo: /^(?:github:)?[A-Za-z0-9][A-Za-z0-9_.-]{0,38}\/[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/,
+  /** git ref：分支、标签或 40 位 commit（不接受 `..` 之类会让 URL 跑出仓库的写法）。 */
+  ref: /^(?:[A-Za-z0-9][A-Za-z0-9._-]{0,127}|[0-9a-f]{40})$/,
+  /** 仓库内相对目录：不允许绝对路径、`..` 与反斜杠。 */
+  relPath: /^(?:\/)?(?:[A-Za-z0-9._-]+\/)*[A-Za-z0-9._-]*$/,
+  /** npm 包名（含 scoped）。 */
+  npmName: /^(?:@[a-z0-9][a-z0-9._-]{0,63}\/)?[a-z0-9][a-z0-9._-]{0,99}$/,
+};
+
+/** reasoningEffort 的封闭枚举；未知值一律拒绝，不做静默降级。 */
+export const REASONING_EFFORTS = ["low", "medium", "high", "default"];
+
+/**
+ * 成员字段 → 桥接生效方式。
+ *
+ * - `direct`：原样进入 agent-teams 的工具参数；
+ * - `config`：运行时没有对应工具参数，只能生成配置片段，属「待 owner 落配置」；
+ * - `declaration`：运行时无承载，仅作文档与校验依据，必须标注未生效。
+ */
+export const FIELD_BINDING = {
+  name: "direct",
+  role: "direct",
+  systemPrompt: "direct",
+  provider: "direct",
+  model: "direct",
+  reasoningEffort: "direct",
+  toolPolicy: "direct",
+  fallback: "config",
+  toolScope: "declaration",
+  maxTokens: "declaration",
+  title: "declaration",
+  tags: "declaration",
+  notes: "declaration",
+  description: "declaration",
+  aliases: "declaration",
+  skills: "declaration",
+  examples: "declaration",
+};
+
+/** 成员允许的字段（未知键一律拒绝，防止拼写错误静默失效）。 */
+export const MEMBER_FIELDS = Object.keys(FIELD_BINDING);
+
+/** 一个档案目录里按顺序探测的档案文件名：<root>/<roster-id>/roster.{yaml,yml,json}。 */
+export const MEMBER_FILE_NAMES = ["roster.yaml", "roster.yml", "roster.json"];
+
+/** 团队级默认值允许的字段：只放真正参与桥接的成员字段。 */
+export const DEFAULTS_FIELDS = [
+  "provider",
+  "model",
+  "reasoningEffort",
+  "toolPolicy",
+  "toolScope",
+  "fallback",
+];
+
+/** 档案文档允许的顶层字段。 */
+export const ROSTER_FIELDS = [
+  "$schema",
+  "kind",
+  "roster",
+  "version",
+  "title",
+  "description",
+  "license",
+  "maintainers",
+  "tags",
+  "defaults",
+  "members",
+  "captain",
+];
+
+/**
+ * 队长段允许的字段。
+ *
+ * 队长就是创建团队的那个会话本身，agent-teams 没有 `captain` 成员行，
+ * 也没有任何工具参数能改写它的路由，所以这里全是「声明 + 落地提示」：
+ * 真正生效要改 profile 的 `agent-default-model` 与 agent preset 的 persona。
+ */
+export const CAPTAIN_FIELDS = [
+  "name",
+  "description",
+  "systemPrompt",
+  "personaPrefix",
+  "provider",
+  "model",
+  "reasoningEffort",
+];
+
+/** 队长字段 → 生效方式（与 FIELD_BINDING 同语义）。 */
+export const CAPTAIN_BINDING = {
+  name: "declaration",
+  description: "declaration",
+  systemPrompt: "declaration",
+  personaPrefix: "config",
+  provider: "config",
+  model: "config",
+  reasoningEffort: "config",
+};
+
+/** 索引文档允许的顶层字段。 */
+export const INDEX_FIELDS = [
+  "$schema",
+  "format",
+  "generatedAt",
+  "generator",
+  "source",
+  "rosters",
+];
+
+/** registry 文档允许的顶层字段。 */
+export const REGISTRY_FIELDS = [
+  "$schema",
+  "kind",
+  "version",
+  "generatedAt",
+  "generator",
+  "source",
+  "collections",
+];
+
+/**
+ * registry 里一条 collection 允许的字段。
+ *
+ * `repo` + `ref` + `path` 决定去哪个仓库的哪个目录取档案；
+ * `rosters` 是目录里真的有哪几份（索引不撒谎，客户端据此逐份拉取并自行校验）。
+ */
+export const COLLECTION_FIELDS = [
+  "id",
+  "title",
+  "description",
+  "repo",
+  "ref",
+  "path",
+  "rosters",
+  "tags",
+  "license",
+  "maintainers",
+  "homepage",
+];
+
+/**
+ * 档案字段 → dsh-agent-teams 成员参数名。
+ *
+ * 只有 direct 字段出现在这里；config/declaration 字段没有运行时参数，
+ * 由 `bridge.js` 的 binding 报告如实标注。
+ */
+export const AGENT_TEAMS_FIELD = {
+  name: "name",
+  role: "role",
+  systemPrompt: "executionPrompt",
+  provider: "provider",
+  model: "model",
+  reasoningEffort: "reasoning_effort",
+  toolPolicy: "tool_policy",
+};

package/lib/home.js

@@ -0,0 +1,108 @@
+/**
+ * DSH 数据目录（harness home）与全局档案库的解析。
+ *
+ * 档案库默认**不跟着工作区走**：一座机器一份，放在 DSH 的数据目录下
+ * （`$DSH_HOME/agent-roster`，默认 `~/.dsh/agent-roster`）。docker 部署时
+ * `$DSH_HOME` 通常就是被挂载的那个卷，因此档案天然落在持久化位置。
+ *
+ * 这里的解析规则与宿主 `@deepseek-ai/dsh-home-paths` 保持一致（配置 > $DSH_HOME > `~/.dsh`），
+ * 但不 import 宿主包：插件要能在没有宿主的单测和 CLI 里独立跑。
+ *
+ * @module dsh-agent-roster/home
+ */
+import os from "node:os";
+import nodePath from "node:path";
+
+/** 默认数据目录名（与宿主一致）。 */
+export const DSH_HOME_DIR_NAME = ".dsh";
+
+/** 覆盖数据目录的环境变量（与宿主一致）。 */
+export const DSH_HOME_ENV = "DSH_HOME";
+
+/** 全局档案库在数据目录下的目录名。 */
+export const GLOBAL_ROSTER_DIR_NAME = "agent-roster";
+
+/**
+ * 展开 `~`、`~/`、`~\` 前缀。
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+export function expandHomePath(value) {
+  if (typeof value !== "string") return value;
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/") || value.startsWith("~\\")) return nodePath.join(os.homedir(), value.slice(2));
+  return value;
+}
+
+/**
+ * 解析 DSH 数据目录：显式配置 > `$DSH_HOME` > `~/.dsh`。
+ *
+ * @param {string | undefined} configured 显式覆盖（通常是插件配置里的绝对路径）
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string} 绝对路径
+ */
+export function resolveDshHome(configured, env = process.env) {
+  const explicit = typeof configured === "string" ? configured.trim() : "";
+  if (explicit !== "") return nodePath.resolve(expandHomePath(explicit));
+  const fromEnv = typeof env?.[DSH_HOME_ENV] === "string" ? env[DSH_HOME_ENV].trim() : "";
+  if (fromEnv !== "") return nodePath.resolve(expandHomePath(fromEnv));
+  return nodePath.join(os.homedir(), DSH_HOME_DIR_NAME);
+}
+
+/**
+ * 全局档案库默认根目录：`<DSH_HOME>/agent-roster`。
+ *
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string}
+ */
+export function globalRosterRoot(env = process.env) {
+  return nodePath.join(resolveDshHome(undefined, env), GLOBAL_ROSTER_DIR_NAME);
+}
+
+/**
+ * 配置项是不是"与工作区无关"的全局目录。
+ *
+ * 空串 = 内置全局目录；`~` 开头的路径与绝对路径也都是全局的。
+ * 只有相对路径（如 `rosters`、`examples`）才按工作区解析——那是给"仓库内示例库"
+ * 这类有意为之的用法留的口子，不是默认行为。
+ *
+ * @param {string | undefined} spec
+ * @returns {boolean}
+ */
+export function isGlobalDirSpec(spec) {
+  if (typeof spec !== "string") return true;
+  const trimmed = spec.trim();
+  if (trimmed === "") return true;
+  return trimmed === "~" || trimmed.startsWith("~/") || trimmed.startsWith("~\\") || nodePath.isAbsolute(trimmed);
+}
+
+/**
+ * 把一个目录配置解析成绝对路径。
+ *
+ * @param {string | undefined} spec 目录配置（空串 = 内置全局目录）
+ * @param {string} [workspacePath] 相对路径的基准工作区
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string}
+ */
+export function resolveDirSpec(spec, workspacePath = process.cwd(), env = process.env) {
+  const trimmed = typeof spec === "string" ? spec.trim() : "";
+  if (trimmed === "") return globalRosterRoot(env);
+  if (trimmed === "~") return os.homedir();
+  if (trimmed.startsWith("~/") || trimmed.startsWith("~\\")) return nodePath.resolve(expandHomePath(trimmed));
+  if (nodePath.isAbsolute(trimmed)) return nodePath.resolve(trimmed);
+  return nodePath.resolve(workspacePath, trimmed);
+}
+
+/**
+ * 给用户展示的数据目录写法（不暴露机器绝对路径）。
+ *
+ * @param {string} home
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string}
+ */
+export function displayDshHome(home, env = process.env) {
+  const fromEnv = typeof env?.[DSH_HOME_ENV] === "string" ? env[DSH_HOME_ENV].trim() : "";
+  if (fromEnv !== "") return "$DSH_HOME";
+  return `~/${DSH_HOME_DIR_NAME}`;
+}