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

package/lib/http.js

@@ -0,0 +1,122 @@
+/**
+ * 路由层的小工具：认证闸门、方法校验、有界 JSON 体、统一响应。
+ *
+ * 面板的写操作（保存/删除/导入档案）走 HTTP，所以这一层是安全边界：
+ * 每个写请求先过宿主的 connection.requestRejection（Host/Origin 围栏 + 浏览器登录凭据），
+ * 再校验方法与媒体类型，再限制正文大小。任何一步失败都直接返回，不进入业务代码。
+ *
+ * @module dsh-agent-roster/http
+ */
+
+/** 写请求正文上限：一份档案含 32 个成员的人设在 256 KiB 内足够，超过视为异常。 */
+export const MAX_BODY_BYTES = 256 * 1024;
+
+/**
+ * 发送 JSON 响应。
+ *
+ * @param {import("node:http").ServerResponse} res
+ * @param {number} status
+ * @param {unknown} payload
+ * @returns {void}
+ */
+export function sendJson(res, status, payload) {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json; charset=utf-8");
+  res.setHeader("cache-control", "no-store");
+  res.end(JSON.stringify(payload));
+}
+
+/**
+ * 发送错误响应：机器可读的 code + 可选诊断数组。
+ *
+ * @param {import("node:http").ServerResponse} res
+ * @param {number} status
+ * @param {string} code
+ * @param {object[]} [diagnostics]
+ * @returns {void}
+ */
+export function sendError(res, status, code, diagnostics = []) {
+  sendJson(res, status, { ok: false, error: { code }, diagnostics });
+}
+
+/**
+ * 405，并如实声明本路由支持的方法。
+ *
+ * @param {import("node:http").ServerResponse} res
+ * @param {string} allow
+ * @returns {void}
+ */
+export function sendMethodNotAllowed(res, allow) {
+  res.statusCode = 405;
+  res.setHeader("allow", allow);
+  res.end();
+}
+
+/**
+ * 造一个认证闸门：返回 true 表示请求已被拒绝并写完响应。
+ *
+ * connection 缺失（极简组合没有装 connection）时放行——此时 webServer 本身已经只监听
+ * 本机回环地址，写操作仍有方法/路径/大小/校验四道闸。
+ *
+ * @param {object} ctx 宿主上下文
+ * @returns {(req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse) => boolean}
+ */
+export function createAuthGate(ctx) {
+  const connection = Reflect.get(ctx, "connection");
+  return (req, res) => {
+    if (connection === undefined || typeof connection.requestRejection !== "function") return false;
+    const rejection = connection.requestRejection(req);
+    if (rejection === undefined) return false;
+    res.statusCode = rejection;
+    res.end();
+    return true;
+  };
+}
+
+/**
+ * 读取有界 JSON 正文。
+ *
+ * @param {import("node:http").IncomingMessage} req
+ * @returns {Promise<{ ok: true, value: unknown } | { ok: false, status: number, code: string }>}
+ */
+export async function readJsonBody(req) {
+  const mediaType = String(req.headers["content-type"] ?? "").split(";")[0].trim().toLowerCase();
+  if (mediaType !== "application/json") return { ok: false, status: 415, code: "unsupported-media-type" };
+
+  const declared = Number(req.headers["content-length"] ?? Number.NaN);
+  if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+    req.resume();
+    return { ok: false, status: 413, code: "body-too-large" };
+  }
+
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of req) {
+    total += chunk.length;
+    if (total > MAX_BODY_BYTES) {
+      return { ok: false, status: 413, code: "body-too-large" };
+    }
+    chunks.push(chunk);
+  }
+  if (total === 0) return { ok: false, status: 400, code: "empty-body" };
+
+  try {
+    return { ok: true, value: JSON.parse(Buffer.concat(chunks).toString("utf8")) };
+  } catch {
+    return { ok: false, status: 400, code: "invalid-json" };
+  }
+}
+
+/**
+ * 断言请求方法，否则写 405 并返回 false。
+ *
+ * @param {import("node:http").IncomingMessage} req
+ * @param {import("node:http").ServerResponse} res
+ * @param {string} method
+ * @returns {boolean}
+ */
+export function requireMethod(req, res, method) {
+  if (req.method === method) return true;
+  sendMethodNotAllowed(res, method);
+  return false;
+}

package/lib/json.js

@@ -0,0 +1,89 @@
+/**
+ * 工具输出的「无损 JSON」清洗。
+ *
+ * DSH 运行时会把工具返回值再序列化一遍，并且要求**往返无损**：`undefined` 属性的键
+ * 在 `JSON.stringify` 时会被丢掉，回来就对不上号，于是整次调用被判为
+ * `value is not lossless JSON` 而失败。这个坑在一次真机验证里踩到过——工具本身没错，
+ * 错在返回值里带着 `undefined`。
+ *
+ * 所以约定：**工具返回值里不允许出现 `undefined`**。缺失一律用 `null` 表达
+ * （`null` 能被 JSON 如实往返），或者干脆不带这个键。
+ *
+ * @module dsh-agent-roster/json
+ */
+
+/**
+ * 递归清洗：对象丢掉值为 `undefined` 的键，数组里的 `undefined` 变成 `null`。
+ *
+ * 只处理 JSON 能表达的结构（对象、数组、原始值）；遇到 `Date`/`Map` 之类不常见的值
+ * 原样放行，它们的序列化责任不在本函数。
+ *
+ * @template T
+ * @param {T} value
+ * @returns {T} 结构相同、但可无损往返 JSON 的值
+ */
+export function lossless(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => (item === undefined ? null : lossless(item)));
+  }
+  if (value !== null && typeof value === "object") {
+    // 保留原型会给 JSON 往返制造意外（比如 Date 会变成字符串），只按普通对象处理纯数据结构。
+    if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+      return value;
+    }
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+      if (item === undefined) continue;
+      out[key] = lossless(item);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * 校验一个值能否无损往返 JSON——测试与调试用。
+ *
+ * @param {unknown} value
+ * @returns {{ ok: boolean, reason?: string }}
+ */
+export function isLossless(value) {
+  let text;
+  try {
+    text = JSON.stringify(value);
+  } catch (error) {
+    return { ok: false, reason: `无法序列化：${error.message}` };
+  }
+  if (text === undefined) return { ok: false, reason: "顶层值不可序列化（undefined/function/symbol）" };
+  const back = JSON.parse(text);
+  try {
+    assertDeepEqual(value, back);
+  } catch (error) {
+    return { ok: false, reason: error.message };
+  }
+  return { ok: true };
+}
+
+/** 找第一处结构差异，报出路径，比整段 diff 更容易定位。 */
+function assertDeepEqual(left, right, at = "$") {
+  if (left === right) return;
+  if (typeof left !== typeof right || left === null || right === null || typeof left !== "object") {
+    throw new Error(`${at}: ${describe(left)} ≠ ${describe(right)}`);
+  }
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  if (leftKeys.length !== rightKeys.length) {
+    const missing = leftKeys.filter((key) => !rightKeys.includes(key));
+    throw new Error(`${at}: 键集合不同${missing.length > 0 ? `，丢掉了 ${missing.join(", ")}` : ""}`);
+  }
+  for (const key of leftKeys) {
+    assertDeepEqual(left[key], right[key], Array.isArray(left) ? `${at}[${key}]` : `${at}.${key}`);
+  }
+}
+
+function describe(value) {
+  if (value === undefined) return "undefined";
+  if (value === null) return "null";
+  if (typeof value === "object") return Array.isArray(value) ? "array" : "object";
+  return JSON.stringify(value);
+}

package/lib/library.js

@@ -0,0 +1,161 @@
+/**
+ * 档案库快照：把"文件系统里的档案"折叠成面板与只读路由能直接渲染的 JSON。
+ *
+ * 这一层是纯数据投影：不碰 ctx 的生命周期、不注册任何东西，只做三件可以单测的事——
+ * 展开工作区 × 档案库目录、给每份档案配上它自己的诊断、跨库同名时点名冲突。
+ * 放在 lib/ 而不是 index.js，是为了让测试不必拉起宿主（index.js 会 import dsh-tools）。
+ *
+ * @module dsh-agent-roster/library
+ */
+import { displayDshHome, isGlobalDirSpec, resolveDshHome, resolveDirSpec } from "./home.js";
+import { scanRosterLibrary } from "./registry.js";
+
+/**
+ * 采集档案库快照。
+ *
+ * 默认**不按工作区展开**：档案库是全局的，默认根目录是 `<DSH_HOME>/agent-roster`。
+ * 只有显式配置成相对路径（如 `examples`）的目录才按工作区展开——那是给"仓库内示例库"
+ * 这类用法留的口子。拿不到工作区注册表时退回进程工作目录并如实标注 `fallbackWorkspace`。
+ *
+ * 多目录是并列的"库"，不合并：每座库单独出统计，同名档案（id 相同）在跨库时会被点名——
+ * 两份同 id 的档案并存意味着"改了 A 生效的是 B"，这必须让用户看见。
+ *
+ * @param {{ get?: (key: string) => unknown }} ctx 只用到工作区注册表这一项能力
+ * @param {object} config 插件配置
+ * @param {{ name: string, version: string }} meta 插件自身元信息
+ * @returns {object}
+ */
+export function collectLibrary(ctx, config, meta) {
+  const workspaces = listWorkspaces(ctx);
+
+  const dirSpecs = Array.isArray(config.rosterDirs) && config.rosterDirs.length > 0 ? config.rosterDirs : [""];
+
+  const reports = [];
+  for (const dirSpec of dirSpecs) {
+    const targets = isGlobalDirSpec(dirSpec)
+      ? [{ scope: "global", workspace: "", workspacePath: "", fallbackWorkspace: false }]
+      : workspaces.map((workspace) => ({
+          scope: "workspace",
+          workspace: workspace.title,
+          workspacePath: workspace.path,
+          fallbackWorkspace: workspace.fallback === true,
+        }));
+    for (const target of targets) {
+      const rootDir = resolveDirSpec(dirSpec, target.workspacePath || process.cwd());
+      const scan = scanRosterLibrary({
+        rootDir,
+        knownToolPolicies: config.knownToolPolicies ?? null,
+      });
+      reports.push({
+        ...target,
+        dirSpec,
+        rootDir,
+        missing: scan.missing === true,
+        stats: scan.stats,
+        rosters: scan.rosters.map((roster) => serializeRoster(roster, scan.diagnostics)),
+        diagnostics: scan.diagnostics,
+      });
+    }
+  }
+
+  markDuplicateIds(reports);
+
+  return {
+    plugin: meta.name,
+    version: meta.version,
+    rosterDirs: dirSpecs,
+    dshHome: displayDshHome(resolveDshHome(undefined)),
+    agentTeamsStateDir: config.agentTeamsStateDir,
+    workspaces: reports,
+  };
+}
+
+/**
+ * 枚举宿主已知的工作区；拿不到注册表时退回进程工作目录并如实标注 `fallback`。
+ *
+ * @param {{ get?: (key: string) => unknown }} ctx
+ * @returns {{ title: string, path: string, fallback?: boolean }[]}
+ */
+export function listWorkspaces(ctx) {
+  const registry = ctx.get?.("workspaceRegistry") ?? ctx.get?.("workspace") ?? undefined;
+  return registry !== undefined && typeof registry.list === "function"
+    ? registry.list().map((workspace) => ({ title: workspace.title ?? "", path: workspace.path }))
+    : [{ title: "", path: process.cwd(), fallback: true }];
+}
+
+/**
+ * 同一工作区里跨库重复的档案 id：在后来者上追加一条警告，列出先前那份文件。
+ *
+ * 只警告、不删档：用户的文件不该被插件悄悄忽略；面板与工具都会显示这条冲突。
+ *
+ * @param {object[]} reports
+ * @returns {void}
+ */
+export function markDuplicateIds(reports) {
+  const seen = new Map();
+  for (const report of reports) {
+    for (const roster of report.rosters) {
+      const key = `${report.workspacePath}::${roster.id}`;
+      const previous = seen.get(key);
+      if (previous !== undefined) {
+        const diagnostic = {
+          severity: "warn",
+          code: "duplicate-roster-id",
+          path: "",
+          file: roster.file,
+          reason:
+            `档案 id "${roster.id}" 与 ${previous} 重复。两份同 id 档案并存时，` +
+            "工具按配置顺序取先出现的那份，改另一份不会生效；请删除或改名其中一份。",
+        };
+        report.diagnostics = [...report.diagnostics, diagnostic];
+        roster.diagnostics = [...roster.diagnostics, diagnostic];
+      } else {
+        seen.set(key, `${report.rootDir}/${roster.file}`);
+      }
+    }
+  }
+}
+
+/**
+ * 面板用的档案投影：字段名保持档案里的 camelCase，减少一次翻译。
+ *
+ * 人设正文不外发（可能上千字），只给长度；与这份档案同目录的诊断会被带上，
+ * 让面板在卡片上就能标出"这份有问题"，而不用把整张诊断表翻一遍。
+ *
+ * @param {object} roster 已通过校验的档案
+ * @param {object[]} [scanDiagnostics] 整座库的诊断
+ * @returns {object}
+ */
+export function serializeRoster(roster, scanDiagnostics = []) {
+  const dir = roster.file.includes("/") ? roster.file.slice(0, roster.file.indexOf("/")) : "";
+  const diagnostics = scanDiagnostics.filter(
+    (item) => item?.file != null && (item.file === roster.file || String(item.file).startsWith(`${dir}/`)),
+  );
+  return {
+    id: roster.id,
+    version: roster.version,
+    title: roster.title,
+    description: roster.description,
+    file: roster.file,
+    tags: roster.tags,
+    maintainers: roster.maintainers,
+    defaults: roster.defaults,
+    diagnostics,
+    members: roster.members.map((member) => ({
+      name: member.name,
+      role: member.role,
+      title: member.title,
+      provider: member.provider ?? null,
+      model: member.model ?? null,
+      reasoningEffort: member.reasoningEffort ?? null,
+      toolPolicy: member.toolPolicy ?? null,
+      toolScope: member.toolScope ?? null,
+      fallback: member.fallback ?? null,
+      maxTokens: member.maxTokens ?? null,
+      inherited: member.inherited ?? [],
+      tags: member.tags,
+      notes: member.notes,
+      systemPromptChars: member.systemPrompt.length,
+    })),
+  };
+}

package/lib/parse.js

@@ -0,0 +1,148 @@
+/**
+ * 档案文档解析：YAML 为主、JSON 兼容，纯函数、不碰文件系统。
+ *
+ * 解析阶段只回答「这段文本能否变成一棵对象树」，语义校验交给 `validate.js`。
+ * 所有失败都转成诊断对象，不做抛异常式的静默降级。
+ *
+ * @module dsh-agent-roster/parse
+ */
+import { parseAllDocuments } from "yaml";
+import { MAX_DOCUMENT_BYTES } from "./format.js";
+
+/** 造一条诊断。path 用点号 + 下标表达，例如 `members[2].model`。 */
+export function diagnostic(severity, code, path, reason, file = "") {
+  return { severity, code, path, reason, file };
+}
+
+/** 文本的字节数（按 UTF-8 计，而不是字符数）。 */
+export function byteLength(text) {
+  return Buffer.byteLength(String(text ?? ""), "utf8");
+}
+
+/** 由文件名猜格式；认不出的按 YAML 处理（YAML 是 JSON 的超集）。 */
+export function formatOf(file) {
+  return /\.json$/i.test(String(file ?? "")) ? "json" : "yaml";
+}
+
+/**
+ * 解析一份档案 / 索引文档。
+ *
+ * @param {string} text 文档全文
+ * @param {{ file?: string, format?: "yaml" | "json" }} [options]
+ * @returns {{ ok: boolean, value: unknown, format: string, diagnostics: object[] }}
+ */
+export function parseDocumentText(text, options = {}) {
+  const file = String(options.file ?? "");
+  const format = options.format ?? formatOf(file);
+  const diagnostics = [];
+
+  const source = String(text ?? "");
+  const bytes = byteLength(source);
+  if (bytes > MAX_DOCUMENT_BYTES) {
+    diagnostics.push(
+      diagnostic(
+        "error",
+        "document-too-large",
+        "",
+        `文档 ${bytes} 字节，超过上限 ${MAX_DOCUMENT_BYTES} 字节`,
+        file,
+      ),
+    );
+    return { ok: false, value: undefined, format, diagnostics };
+  }
+  if (source.trim() === "") {
+    diagnostics.push(diagnostic("error", "empty-document", "", "文档为空", file));
+    return { ok: false, value: undefined, format, diagnostics };
+  }
+
+  if (format === "json") return parseJson(source, file);
+
+  let documents;
+  try {
+    documents = parseAllDocuments(source, { uniqueKeys: true, prettyErrors: false });
+  } catch (error) {
+    diagnostics.push(diagnostic("error", "yaml-syntax", "", messageOf(error), file));
+    return { ok: false, value: undefined, format, diagnostics };
+  }
+
+  const failed = documents.filter((doc) => doc.errors.length > 0);
+  if (failed.length > 0) {
+    for (const doc of failed) {
+      for (const error of doc.errors) {
+        diagnostics.push(
+          diagnostic(
+            "error",
+            "yaml-syntax",
+            linePath(error),
+            String(error.message ?? "").split("\n")[0],
+            file,
+          ),
+        );
+      }
+    }
+    return { ok: false, value: undefined, format, diagnostics };
+  }
+  if (documents.length !== 1) {
+    diagnostics.push(
+      diagnostic(
+        "error",
+        "multi-document",
+        "",
+        `一份档案文件只允许一个 YAML 文档，实际 ${documents.length} 个`,
+        file,
+      ),
+    );
+    return { ok: false, value: undefined, format, diagnostics };
+  }
+
+  let value;
+  try {
+    value = documents[0].toJS({ maxAliasCount: 100 });
+  } catch (error) {
+    diagnostics.push(diagnostic("error", "yaml-value", "", messageOf(error), file));
+    return { ok: false, value: undefined, format, diagnostics };
+  }
+
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    diagnostics.push(
+      diagnostic("error", "document-not-mapping", "", "文档顶层必须是映射（对象）", file),
+    );
+    return { ok: false, value: undefined, format, diagnostics };
+  }
+  return { ok: true, value, format, diagnostics };
+}
+
+function parseJson(source, file) {
+  try {
+    const value = JSON.parse(source);
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      return {
+        ok: false,
+        value: undefined,
+        format: "json",
+        diagnostics: [
+          diagnostic("error", "document-not-mapping", "", "文档顶层必须是对象", file),
+        ],
+      };
+    }
+    return { ok: true, value, format: "json", diagnostics: [] };
+  } catch (error) {
+    return {
+      ok: false,
+      value: undefined,
+      format: "json",
+      diagnostics: [diagnostic("error", "json-syntax", "", messageOf(error), file)],
+    };
+  }
+}
+
+function messageOf(error) {
+  return String(error?.message ?? error ?? "解析失败").split("\n")[0];
+}
+
+/** 把 yaml 的语法错误位置折成 `line:col` 形式的 path，便于定位。 */
+function linePath(error) {
+  const line = error?.linePos?.[0]?.line;
+  const col = error?.linePos?.[0]?.col;
+  return Number.isFinite(line) ? `line:${line}${Number.isFinite(col) ? `:${col}` : ""}` : "";
+}