@stofone/dsh-agent-roster 0.13.0 → 1.0.0

package/lib/clone.js

@@ -0,0 +1,318 @@
+/**
+ * 把一个远端「档案空间」拉成一份本地副本。
+ *
+ * 为什么不能只拉 `dist/`：编译产物是一份自包含的快照，能读、不能改——
+ * 你改它，改的是快照，不是仓库里的任何一个源文件。要让"编辑"和源文件对得上，
+ * 拉下来的目录结构必须和仓库里的**同形**：`roles/<role>/AGENT.md`、
+ * `rosters/<id>/roster.yaml`、`dist/<id>-<ver>.json`，一条路径都不许改。
+ *
+ * 三种来源都收：
+ * - `space.yaml` 在（layout: monorepo）：按目录树逐文件拉，收到 `dist/`；
+ * - `space.yaml` 在（layout: flat）：只拉 `<id>/roster.yaml`；
+ * - `space.yaml` 不在（老仓库）：按 flat 处理，并在本地副本上补一份带 `origin` 的 space.yaml。
+ *
+ * @module dsh-agent-roster/clone
+ */
+
+import fs from "node:fs";
+import nodePath from "node:path";
+
+import { parseDocumentText } from "./parse.js";
+import { SPACE_FILE_NAMES, SPACE_KIND, validateSpace } from "./space.js";
+
+const RAW = "https://raw.githubusercontent.com";
+
+/** 拉取并发度：单次 clone 的文件数在几十份量级，6 路够用且不冒犯对方。 */
+export const CLONE_CONCURRENCY = 6;
+
+/** 目录里的相对路径只允许这些形态：拼 URL 前先钉死，免得把 `..` 带进写盘。 */
+const SAFE_RELATIVE = /^(?:\.[A-Za-z0-9._-]+|[A-Za-z0-9._-]+)(?:\/[A-Za-z0-9._-]+)*$/;
+
+function joinUrl(base, relative) {
+  const encoded = relative
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+  return `${base}${encoded}`;
+}
+
+async function fetchText(url, fetchImpl) {
+  const response = await fetchImpl(url, { headers: { accept: "application/json, text/plain, */*" } });
+  if (!response.ok) return { ok: false, status: response.status };
+  return { ok: true, text: await response.text() };
+}
+
+/** 角色名取自 `name@1.2.3` 这种引用；取不到就不猜。 */
+function roleNameOf(reference) {
+  if (typeof reference !== "string") return null;
+  const at = reference.lastIndexOf("@");
+  return at > 0 ? reference.slice(0, at) : reference;
+}
+
+/**
+ * 从一份 roster 文档里收集它引用的角色名（成员 + 队长）。
+ *
+ * @param {object} roster
+ * @returns {string[]}
+ */
+export function rolesOfRoster(roster) {
+  const names = new Set();
+  for (const member of Array.isArray(roster?.members) ? roster.members : []) {
+    const name = roleNameOf(member?.role);
+    if (name) names.add(name);
+  }
+  const captain = roster?.captain;
+  if (captain && typeof captain === "object") {
+    const name = roleNameOf(captain.role);
+    if (name) names.add(name);
+  }
+  return [...names].sort();
+}
+
+/**
+ * 拉一个空间到 `<rootDir>/<spaceId>/`。
+ *
+ * @param {{
+ *   rootDir: string,
+ *   spaceId: string,
+ *   repo: string,
+ *   ref?: string,
+ *   path?: string,
+ *   fetchImpl: (url: string, init?: object) => Promise<object>,
+ *   concurrency?: number,
+ * }} input
+ * @returns {Promise<{ok: boolean, dir: string, layout: string, written: string[], skipped: string[], diagnostics: object[]}>}
+ */
+export async function cloneSpace(input) {
+  const ref = input.ref ?? "main";
+  const originPath = input.path ?? "";
+  const base = `${RAW}/${input.repo}/${encodeURIComponent(ref)}/${originPath === "" ? "" : `${originPath}/`}`;
+  const fetchImpl = input.fetchImpl;
+  const concurrency = Math.max(1, Math.min(16, input.concurrency ?? CLONE_CONCURRENCY));
+  const diagnostics = [];
+  const written = [];
+  const skipped = [];
+
+  const read = async (relative) => {
+    try {
+      return await fetchText(joinUrl(base, relative), fetchImpl);
+    } catch (error) {
+      diagnostics.push({ severity: "error", code: "clone-fetch-failed", path: relative, file: relative, reason: `拉取失败：${String(error?.message ?? error)}` });
+      return { ok: false, status: 0 };
+    }
+  };
+
+  // 1. 读空间封面；没有就按 flat 老仓库处理。
+  let spaceFile = null;
+  let raw = null;
+  for (const name of SPACE_FILE_NAMES) {
+    const got = await read(name);
+    if (got.ok) {
+      spaceFile = name;
+      raw = got.text;
+      break;
+    }
+    if (got.status !== 404 && got.status !== undefined) {
+      diagnostics.push({ severity: "warn", code: "clone-space-unreadable", path: name, file: name, reason: `读取 ${name} 返回 ${got.status}。` });
+    }
+  }
+
+  let space = null;
+  let layout = "flat";
+  let rosterIds = [];
+  if (spaceFile !== null) {
+    const parsed = parseDocumentText(raw, { file: spaceFile, format: spaceFile.endsWith(".json") ? "json" : "yaml" });
+    if (!parsed.ok) {
+      return { ok: false, dir: nodePath.join(input.rootDir, input.spaceId), layout, written, skipped, diagnostics: [...diagnostics, ...parsed.diagnostics] };
+    }
+    const validated = validateSpace(parsed.value, { file: spaceFile, expectedId: null });
+    if (!validated.ok) {
+      return { ok: false, dir: nodePath.join(input.rootDir, input.spaceId), layout, written, skipped, diagnostics: [...diagnostics, ...validated.diagnostics] };
+    }
+    space = validated.space;
+    layout = space.layout;
+    rosterIds = space.rosters.map((item) => item.id);
+  } else {
+    // 没有封面：调用方必须给 ids（来自 registry 索引），否则无从下手。
+    rosterIds = Array.isArray(input.rosterIds) ? [...input.rosterIds] : [];
+    if (rosterIds.length === 0) {
+      diagnostics.push({
+        severity: "error",
+        code: "clone-no-space",
+        path: "",
+        file: null,
+        reason: `${input.repo}@${ref}${originPath === "" ? "" : `/${originPath}`} 没有 space.yaml，调用方也没有给档案 id 列表。`,
+      });
+      return { ok: false, dir: nodePath.join(input.rootDir, input.spaceId), layout, written, skipped, diagnostics };
+    }
+  }
+
+  const dir = nodePath.join(input.rootDir, input.spaceId);
+  const files = new Map();
+
+  // 2. 档案本体（外加能力要求这种"同目录兄弟文件"）。
+  for (const id of rosterIds) {
+    const relative = layout === "monorepo" ? `rosters/${id}/roster.yaml` : `${id}/roster.yaml`;
+    const got = await read(relative);
+    if (!got.ok) {
+      skipped.push(relative);
+      diagnostics.push({
+        severity: "warn",
+        code: "clone-roster-missing",
+        path: relative,
+        file: relative,
+        reason: `${id} 在 ${relative} 处读不到（${got.status}）；本地副本会少这一份。`,
+      });
+      continue;
+    }
+    files.set(relative, got.text);
+    if (layout === "monorepo") {
+      const capabilities = await read(`rosters/${id}/capabilities.yaml`);
+      if (capabilities.ok) files.set(`rosters/${id}/capabilities.yaml`, capabilities.text);
+    }
+  }
+
+  // 3. monorepo：把被引用的角色连同片段一起拉下来，否则本地编译不出人设。
+  if (layout === "monorepo") {
+    const roles = new Set(space?.roles ?? []);
+    for (const [relative, text] of [...files]) {
+      if (!relative.endsWith("roster.yaml")) continue;
+      const parsed = parseDocumentText(text, { file: relative, format: "yaml" });
+      if (!parsed.ok) continue;
+      for (const name of rolesOfRoster(parsed.value)) roles.add(name);
+    }
+    for (const name of [...roles].sort()) {
+      const agentPath = `roles/${name}/AGENT.md`;
+      const got = await read(agentPath);
+      if (!got.ok) {
+        if (!skipped.includes(agentPath)) {
+          skipped.push(agentPath);
+          diagnostics.push({
+            severity: "warn",
+            code: "clone-role-missing",
+            path: agentPath,
+            file: agentPath,
+            reason: `角色 ${name} 读不到（${got.status}）；本地编译会缺这一份人设。`,
+          });
+        }
+        continue;
+      }
+      files.set(agentPath, got.text);
+      // 片段路径写在 frontmatter 里，只能读完才知道；一次多一跳，不猜。
+      for (const part of partPathsOf(got.text)) {
+        const partPath = part.startsWith("roles/") ? part : `roles/${name}/${part}`;
+        const piece = await read(partPath);
+        if (piece.ok) files.set(partPath, piece.text);
+        else skipped.push(partPath);
+      }
+    }
+  }
+
+  // 4. 落盘：先写文件，最后写空间封面（封面存在即代表这次 clone 完整）。
+  try {
+    for (const [relative, text] of files) {
+      if (!SAFE_RELATIVE.test(relative)) {
+        diagnostics.push({ severity: "error", code: "clone-unsafe-path", path: relative, file: relative, reason: "拒绝写入：路径不是安全的相对路径。" });
+        continue;
+      }
+      const target = nodePath.join(dir, ...relative.split("/"));
+      fs.mkdirSync(nodePath.dirname(target), { recursive: true });
+      fs.writeFileSync(target, text, "utf8");
+      written.push(relative);
+    }
+    const cover = spaceCover({
+      space,
+      spaceId: input.spaceId,
+      layout,
+      rosterIds,
+      origin: { repo: input.repo, ref, path: originPath },
+    });
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(nodePath.join(dir, "space.yaml"), cover, "utf8");
+    written.push("space.yaml");
+  } catch (error) {
+    diagnostics.push({ severity: "error", code: "clone-write-failed", path: "", file: null, reason: `写盘失败：${String(error?.message ?? error)}` });
+    return { ok: false, dir, layout, written, skipped, diagnostics };
+  }
+
+  return {
+    ok: diagnostics.every((item) => item.severity !== "error"),
+    dir,
+    layout,
+    written,
+    skipped,
+    diagnostics,
+  };
+}
+
+/**
+ * 从 AGENT.md 的 frontmatter 里取片段路径；解析不了就返回空数组（不猜）。
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+function partPathsOf(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (match === null) return [];
+  const lines = match[1].split(/\r?\n/);
+  const parts = [];
+  let inParts = false;
+  for (const line of lines) {
+    if (/^prompt:\s*$/.test(line)) continue;
+    if (/^\s+parts:\s*$/.test(line)) {
+      inParts = true;
+      continue;
+    }
+    if (inParts) {
+      const item = line.match(/^\s*-\s*(\S+)\s*$/);
+      if (item) {
+        parts.push(item[1].replace(/^["']|["']$/g, ""));
+        continue;
+      }
+      if (/^\s{0,2}\S/.test(line)) inParts = false;
+    }
+  }
+  return parts;
+}
+
+/**
+ * 生成本地副本的 `space.yaml`：远端的那份 + `origin`。
+ *
+ * @param {{space: object|null, spaceId: string, layout: string, rosterIds: string[], origin: {repo: string, ref: string, path: string}}} input
+ * @returns {string}
+ */
+export function spaceCover(input) {
+  const title = input.space?.title ?? input.spaceId;
+  const description = input.space?.description ?? "";
+  const license = input.space?.license ?? "";
+  const homepage = input.space?.homepage ?? "";
+  const maintainers = input.space?.maintainers ?? [];
+  const roles = input.space?.roles ?? [];
+  const lines = ["kind: " + SPACE_KIND, `space: ${input.spaceId}`, `title: ${yamlScalar(title)}`];
+  if (description !== "") lines.push(`description: ${yamlScalar(description)}`);
+  if (license !== "") lines.push(`license: ${yamlScalar(license)}`);
+  if (homepage !== "") lines.push(`homepage: ${yamlScalar(homepage)}`);
+  if (maintainers.length > 0) {
+    lines.push("maintainers:");
+    for (const who of maintainers) lines.push(`  - ${yamlScalar(who)}`);
+  }
+  lines.push(`layout: ${input.layout}`);
+  lines.push("origin:");
+  lines.push(`  repo: ${yamlScalar(input.origin.repo)}`);
+  lines.push(`  ref: ${yamlScalar(input.origin.ref)}`);
+  if (input.origin.path !== "") lines.push(`  path: ${yamlScalar(input.origin.path)}`);
+  if (roles.length > 0) {
+    lines.push("roles:");
+    for (const name of roles) lines.push(`  - ${yamlScalar(name)}`);
+  }
+  lines.push("rosters:");
+  for (const id of input.rosterIds) lines.push(`  - id: ${id}`);
+  return `${lines.join("\n")}\n`;
+}
+
+/** YAML 标量：需要引号就加双引号并转义，不需要就原样写。 */
+function yamlScalar(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9\u4e00-\u9fa5][^:{}[\],&*#?|\-<>=!%@`"']*$/.test(text) && text.trim() === text) return text;
+  return JSON.stringify(text);
+}

package/lib/library.js

@@ -59,10 +59,10 @@ export function collectLibrary(ctx, config, meta) {
         stats: scan.stats,
         rosters: scan.rosters.map((roster) => serializeRoster(roster, scan.diagnostics)),
         // 面板抬头要显示"这份库属于哪个组织"，只给 id 与标题，不带成员细节。
-        organization:
-          scan.organization === null || scan.organization === undefined
+        space:
+          scan.space === null || scan.space === undefined
             ? null
-            : { id: scan.organization.organization, title: scan.organization.title ?? "" },
+            : { id: scan.space.id, title: scan.space.title ?? "" },
         diagnostics: scan.diagnostics,
       });
     }

package/lib/registry.js

@@ -29,11 +29,11 @@ import { compileRosterAt, rosterViewOf, scanRoles } from "./compile2.js";
 import { sha256Hex } from "./digest.js";
 import { MEMBER_FILE_NAMES } from "./format.js";
 import {
-  ORGANIZATION_FILE_NAMES,
-  checkOrganization,
-  organizationDiagnostics,
-  validateOrganization,
-} from "./organization.js";
+  SPACE_FILE_NAMES,
+  checkSpace,
+  spaceDiagnostics,
+  validateSpace,
+} from "./space.js";
 import { parseDocumentText } from "./parse.js";
 import { validateRoster } from "./validate.js";
 
@@ -82,9 +82,9 @@ export function scanRosterLibrary({ rootDir, knownToolPolicies = null }) {
   const capabilities = {};
   /** 档案 id → 能力要求的文件名（诊断要指到具体那份文件）。 */
   const capabilityFiles = {};
-  /** 组织档案（organization.yaml）与它的交叉核对结果。 */
-  let organization = null;
-  let organizationFile = null;
+  /** 组织档案（space.yaml）与它的交叉核对结果。 */
+  let space = null;
+  let spaceFile = null;
   const stats = {
     total: 0,
     ok: 0,
@@ -123,8 +123,8 @@ export function scanRosterLibrary({ rootDir, knownToolPolicies = null }) {
       if (child.name.startsWith(".") || SKIP_DIRS.has(child.name) || child.isSymbolicLink()) continue;
 
       if (!child.isDirectory()) {
-        // 库根上的 organization.yaml 是合法的：它是这座库的目录页，不是散落的档案。
-        if (ORGANIZATION_FILE_NAMES.includes(child.name)) continue;
+        // 库根上的 space.yaml 是合法的：它是这座库的目录页，不是散落的档案。
+        if (SPACE_FILE_NAMES.includes(child.name)) continue;
         // 散落的 *.yaml 曾经是另一种布局；现在只认目录，必须明确告知而不是忽略。
         diagnostics.push({
           severity: "warn",
@@ -191,15 +191,15 @@ export function scanRosterLibrary({ rootDir, knownToolPolicies = null }) {
   }
 
   // 组织档案在目录扫完之后读：它的交叉核对需要知道磁盘上到底有哪些档案。
-  const wantedOrganization = loadOrganization(rootDir, nodePath.basename(rootDir));
-  organization = wantedOrganization.organization;
-  organizationFile = wantedOrganization.file;
-  diagnostics.push(...wantedOrganization.diagnostics);
-  const organizationCheck = checkOrganization(
-    organization,
+  const wantedSpace = loadSpace(rootDir, nodePath.basename(rootDir));
+  space = wantedSpace.space;
+  spaceFile = wantedSpace.file;
+  diagnostics.push(...wantedSpace.diagnostics);
+  const spaceCheck = checkSpace(
+    space,
     rosters.map((item) => item.id),
   );
-  diagnostics.push(...organizationDiagnostics(organization, organizationCheck, organizationFile ?? ORGANIZATION_FILE_NAMES[0]));
+  diagnostics.push(...spaceDiagnostics(space, spaceCheck, spaceFile ?? SPACE_FILE_NAMES[0]));
 
   if (stats.total > 0 && rosters.length === 0) {
     diagnostics.push({
@@ -248,9 +248,9 @@ export function scanRosterLibrary({ rootDir, knownToolPolicies = null }) {
     rosters,
     capabilities,
     capabilityFiles,
-    organization,
-    organizationFile,
-    organizationCheck,
+    space,
+    spaceFile,
+    spaceCheck,
     stats,
     diagnostics,
   };
@@ -368,22 +368,22 @@ function loadDocument(found, expectedId, { knownToolPolicies }, rawText = null)
  * @param {string} dirName 目录名（同时也是期望的 `roster` 字段）
  * @returns {{ capabilities: object | null, file: string | null, diagnostics: object[] }}
  */
-export function loadOrganization(rootDir, dirName) {
+export function loadSpace(rootDir, dirName) {
   let names;
   try {
     names = readdirSync(rootDir);
   } catch {
-    return { organization: null, file: null, diagnostics: [] };
+    return { space: null, file: null, diagnostics: [] };
   }
-  const present = ORGANIZATION_FILE_NAMES.filter((name) => names.includes(name));
-  if (present.length === 0) return { organization: null, file: null, diagnostics: [] };
+  const present = SPACE_FILE_NAMES.filter((name) => names.includes(name));
+  if (present.length === 0) return { space: null, file: null, diagnostics: [] };
 
   const diagnostics = [];
   const relative = present[0];
   if (present.length > 1) {
     diagnostics.push({
       severity: "warn",
-      code: "multiple-organization-files",
+      code: "multiple-space-files",
       path: "",
       file: relative,
       reason:
@@ -403,17 +403,17 @@ export function loadOrganization(rootDir, dirName) {
       file: relative,
       reason: `文件不可读：${messageOf(error)}`,
     });
-    return { organization: null, file: relative, diagnostics };
+    return { space: null, file: relative, diagnostics };
   }
 
   const format = relative.endsWith(".json") ? "json" : "yaml";
   const parsed = parseDocumentText(raw, { file: relative, format });
-  if (!parsed.ok) return { organization: null, file: relative, diagnostics: [...diagnostics, ...parsed.diagnostics] };
+  if (!parsed.ok) return { space: null, file: relative, diagnostics: [...diagnostics, ...parsed.diagnostics] };
 
-  const validated = validateOrganization(parsed.value, { file: relative, expectedId: dirName });
+  const validated = validateSpace(parsed.value, { file: relative, expectedId: dirName, allowOrigin: true });
   diagnostics.push(...validated.diagnostics);
-  if (!validated.ok) return { organization: null, file: relative, diagnostics };
-  return { organization: validated.organization, file: relative, diagnostics };
+  if (!validated.ok) return { space: null, file: relative, diagnostics };
+  return { space: validated.space, file: relative, diagnostics };
 }
 
 export function loadCapabilities(dirPath, dirName) {

package/lib/render.js

@@ -89,11 +89,11 @@ export function renderRosterList(scan) {
   const { entries, stats, rootDir } = scan;
   const lines = [];
   lines.push(`档案库  ${rootDir}`);
-  const organization = scan.organization ?? null;
-  if (organization !== null) {
-    const check = scan.organizationCheck ?? { declared: 0, present: 0, missing: [], undeclared: [], archived: [] };
-    lines.push(`组织    ${organization.id}  ${organization.title}`);
-    if (organization.description !== "") lines.push(`        ${organization.description}`);
+  const space = scan.space ?? null;
+  if (space !== null) {
+    const check = scan.spaceCheck ?? { declared: 0, present: 0, missing: [], undeclared: [], archived: [] };
+    lines.push(`空间    ${space.id}  ${space.title}`);
+    if (space.description !== "") lines.push(`        ${space.description}`);
     const parts = [
       `登记 ${check.declared}`,
       `在库 ${check.present}`,
@@ -101,7 +101,7 @@ export function renderRosterList(scan) {
       `未登记 ${check.undeclared.length}`,
     ];
     if (check.archived.length > 0) parts.push(`已归档 ${check.archived.length}`);
-    if (organization.maintainers.length > 0) parts.push(`维护者 ${organization.maintainers.join(", ")}`);
+    if (space.maintainers.length > 0) parts.push(`维护者 ${space.maintainers.join(", ")}`);
     lines.push(`        ${parts.join(" · ")}`);
   }
   if (entries.length === 0) {

package/lib/service.js

@@ -14,6 +14,7 @@ import nodePath from "node:path";
 
 import { globalRosterRoot } from "./home.js";
 import { readDeployedCaptains, verifyCaptain } from "./captain.js";
+import { cloneSpace } from "./clone.js";
 import { collectLibrary, listWorkspaces } from "./library.js";
 import { CACHE_DIR_NAME, fetchCollection, loadRegistryIndex } from "./remote.js";
 import { rosterDocumentText } from "./serialize.js";
@@ -428,6 +429,52 @@ export async function installCollection(config, options) {
   };
 }
 
+/**
+ * 把一个远端 collection 对应的**整个空间**拉成本地副本。
+ *
+ * 与 `installCollection` 的区别不是"多拉几份"，而是**布局**：
+ * 拉下来的目录和仓库同形（`roles/` + `rosters/` + `dist/`），
+ * 所以本地编辑的就是源仓库里的那个文件；`installCollection` 只摊平单份档案，
+ * 适合"我只要这一份、不打算往回改"的场景。
+ *
+ * @param {object} config
+ * @param {{ collectionId: string, source?: string, spaceId?: string, overwrite?: boolean, fetchImpl?: typeof fetch, cacheDir?: string }} options
+ * @returns {Promise<object>}
+ */
+export async function installSpace(config, options) {
+  const panel = await loadRemotePanel(config, { fetchImpl: options.fetchImpl, cacheDir: options.cacheDir });
+  const collection = panel.collections.find(
+    (item) => item.id === options.collectionId && (options.source === undefined || item.origin?.source === options.source),
+  );
+  if (collection === undefined) {
+    return {
+      ok: false,
+      code: "collection-not-found",
+      known: panel.collections.map((item) => item.id),
+      diagnostics: panel.diagnostics,
+    };
+  }
+  const roots = listLibraryRoots({ rosterDirs: config.rosterDirs ?? [], workspaces: [] });
+  const root = roots[0] ?? null;
+  if (root === null) return { ok: false, code: "no-library-root", diagnostics: panel.diagnostics };
+
+  const spaceId = options.spaceId ?? collection.id;
+  const cloned = await cloneSpace({
+    rootDir: root.rootDir,
+    spaceId,
+    repo: collection.repo,
+    ref: collection.ref,
+    path: collection.path,
+    rosterIds: collection.rosters,
+    fetchImpl: options.fetchImpl ?? fetch,
+  });
+  return {
+    ...cloned,
+    collection: { id: collection.id, title: collection.title, repo: collection.repo, ref: collection.ref, path: collection.path },
+    rootDir: root.rootDir,
+  };
+}
+
 /**
  * 远程档案源（公共 registry）的投影。
  *