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

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# @stofone/dsh-agent-roster 的 Host 行。
+#
+# config 会被整体替换（不会深合并）：覆盖本行时请把需要的字段全部重述一遍。
+# 所有字段都有默认值，留空即可用「项目内 .dsh/agent-rosters/」与「用户级
+# <dshHome>/agent-rosters/」两个目录。
+- insert:
+    - id: agent-roster
+      name: '@stofone/dsh-agent-roster'
+      config: {}

package/examples/core-review/roster.yaml

@@ -0,0 +1,82 @@
+# 示例档案：一个三人的代码审查小组。
+#
+# 目录约定：档案库根目录下，每份档案一个目录，目录名必须等于 roster 字段。
+# 本文件位于 <根>/core-review/roster.yaml，所以 roster 必须是 core-review。
+kind: dsh-agent-roster/v1
+roster: core-review
+version: 1.0.0
+title: 代码审查小组
+description: 一名队长加两名审查者：一人盯正确性，一人盯可维护性与边界条件。
+license: MIT
+maintainers:
+  - STofone
+tags:
+  - review
+  - example
+
+# defaults 是成员的省缺值：成员自己没写的字段才继承；写了就覆盖。
+# provider/model 是"运行时真值"，会原样交给 dsh-agent-teams 建员；
+# toolPolicy 需要部署方声明过对应 id，否则只是声明、运行时不会生效（验证器会提醒）。
+defaults:
+  provider: deepseek
+  model: deepseek-v4.1-flash
+  reasoningEffort: high
+  toolPolicy: read-only
+
+members:
+  - name: lead
+    role: 队长
+    title: 编排与取舍
+    description: 编排这次审查、拆任务、合并结论；不写具体代码
+    aliases:
+      - coordinator
+    skills:
+      - frontend-skill
+    examples:
+      - 这次改动影响面有多大，分给谁看
+      - 两人结论冲突，你判断谁对
+    systemPrompt: |
+      你负责这次审查的编排：先划定改动影响面，再把任务分给两名审查者，最后合并结论。
+      只在两种情况下自己下结论：两人结论冲突且证据不足，或风险高到必须先止损。
+      报告要能直接贴进 PR：结论在前，证据在后，不确定的地方明确写"未验证"。
+    tags:
+      - orchestration
+    notes: 队长的工具边界通常比审查者宽（要能派活），这里刻意收窄成只读，作为示例。
+
+  - name: correctness
+    role: 正确性审查
+    title: 找会出错的地方
+    description: 只找"什么输入下会做错事"，每条结论给可复现的触发条件
+    systemPrompt: |
+      你只关心"这段代码在什么输入下会做错事"：边界值、空值、并发、错误路径、类型退化。
+      每条结论必须给出可复现的触发条件；给不出就标注为"怀疑，未验证"。
+      不要评论风格，那是另一个人的事。
+    tags:
+      - correctness
+    toolScope:
+      allow:
+        - read
+        - grep
+        - glob
+
+  - name: maintainer
+    role: 可维护性审查
+    title: 看六个月后谁来改
+    description: 看命名、重复、耦合、测试与错误信息；只给最小修改方向
+    systemPrompt: |
+      你关心的是"半年后接手的人能不能安全改动"：命名、重复、隐含耦合、缺测试、错误信息质量。
+      对每处问题给出最小修改方向，不要重写整个模块。
+      风格问题只在它影响可读性判断时提，且最多三条。
+    tags:
+      - maintainability
+
+# 队长段：队长＝创建团队的那个会话，不是成员。这里只记录它应该是什么样，
+# 真要生效得改 profile 的 agent-default-model 与 agent preset 的 persona。
+captain:
+  name: lead
+  description: 主会话即队长，负责拆活与验收
+  provider: deepseek
+  model: deepseek-v4.1-flash
+  reasoningEffort: high
+  personaPrefix: |
+    派活前先复述目标与验收标准；汇报时先结论后证据。

package/examples/research/roster.yaml

@@ -0,0 +1,42 @@
+# 示例档案：外部调研小组。
+#
+# 与 core-review 刻意不同：这份档案让成员分别用不同模型，并给"复核者"更弱的工具边界。
+kind: dsh-agent-roster/v1
+roster: research
+version: 0.1.0
+title: 外部调研小组
+description: 一手资料收集 + 交叉复核；复核者的结论必须能被另一条独立来源支撑。
+tags:
+  - research
+  - example
+
+defaults:
+  provider: deepseek
+  model: deepseek-v4.1-pro
+  reasoningEffort: medium
+
+members:
+  - name: scout
+    role: 一手资料
+    title: 找原始出处
+    systemPrompt: |
+      你负责找一手资料：官方文档、源码、发布说明、原始数据。二手转述只能用来说明"存在争议"。
+      每条事实必须附可点击链接与日期；找不到就写"没找到"，不要用常识补。
+    tags:
+      - sourcing
+
+  - name: verifier
+    role: 交叉复核
+    title: 独立复现结论
+    systemPrompt: |
+      你只做一件事：拿另一条独立来源验证别人的结论。你有意不共享 scout 的上下文，避免同源偏差。
+      结论分三档：已复现 / 部分一致 / 无法复现。无法复现时必须写清缺哪条关键证据。
+    model: deepseek-v4.1-flash
+    reasoningEffort: high
+    tags:
+      - verification
+    toolScope:
+      allow:
+        - read
+        - grep
+    notes: 刻意用更小的模型做复核，成本低且能暴露"结论依赖模型能力"的问题。

package/icon.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Agent Roster">
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="#1d4ed8"/>
+  <g fill="#ffffff">
+    <rect x="14" y="16" width="24" height="5" rx="2.5"/>
+    <rect x="14" y="27" width="32" height="5" rx="2.5" opacity="0.9"/>
+    <rect x="14" y="38" width="20" height="5" rx="2.5" opacity="0.75"/>
+  </g>
+  <g fill="none" stroke="#ffffff" stroke-width="3.2" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M40 47.5l4.6 4.5L54 42.5"/>
+  </g>
+</svg>

package/index/registry.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "../schema/registry.v1.schema.json",
+  "kind": "dsh-agent-roster-registry/v1",
+  "version": 1,
+  "generatedAt": "2026-10-30T00:00:00.000Z",
+  "generator": "STofone/dsh-agent-roster (hand-maintained; verified by .github/workflows/registry.yml)",
+  "source": "https://github.com/STofone/dsh-agent-roster",
+  "collections": [
+    {
+      "id": "agent-roster-examples",
+      "title": "官方起步档案集",
+      "description": "评审与调研两套起步档案，用来验证格式、桥接与核对链路；也可以直接复制成自己的档案。",
+      "repo": "github:STofone/dsh-agent-roster",
+      "ref": "main",
+      "path": "examples",
+      "rosters": ["core-review", "research"],
+      "tags": ["starter", "review", "research"],
+      "license": "MIT",
+      "maintainers": ["STofone"],
+      "homepage": "https://github.com/STofone/dsh-agent-roster#examples"
+    }
+  ]
+}

package/index.js

@@ -0,0 +1,298 @@
+/**
+ * @stofone/dsh-agent-roster —— 多 Agent 团队的静态成员档案层。
+ *
+ * 定位：**定义与校验 + 桥接参数生成 + 可管理它的面板**。本插件不运行团队、不调度任务、
+ * 不替代任何团队运行时，也不写别人的状态。它做的事是：
+ *
+ * 1. 把成员档案（谁、能做什么、用什么模型、受什么工具约束）固化成可校验、可版本化的静态文件；
+ * 2. 校验失败时 fail-loud：带文件路径与字段路径报错，不静默降级；
+ * 3. 在 dsh-agent-teams 创建成员时，把档案翻译成建员参数，并如实标注每个字段的归宿
+ *    （运行时接收 / 仅声明 / 需落部署配置），事后再拿 team.json 的实际值核对；
+ * 4. 给用户一个能看到、能编辑、能新建/导入/删除档案，并能查看/核对团队的面板。
+ *
+ * @module dsh-agent-roster
+ */
+import { readFileSync } from "node:fs";
+
+import z from "@deepseek-ai/schemastery";
+
+import { configView } from "./lib/config-view.js";
+import { collectLibrary } from "./lib/library.js";
+import { parseDocumentText } from "./lib/parse.js";
+import { validateRoster } from "./lib/validate.js";
+import { sendError, sendJson, createAuthGate, readJsonBody, requireMethod } from "./lib/http.js";
+import { buildPanelSnapshot, installCollection, loadRemotePanel, resolveRoots } from "./lib/service.js";
+import { fetchCollection } from "./lib/remote.js";
+import { registerRosterTools } from "./lib/tools.js";
+import { deleteRosterDocument, readRosterDocument, writeRosterDocument } from "./lib/write.js";
+
+const pkg = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8"));
+
+/** Cordis 插件名（出现在宿主日志与设置页）。 */
+export const name = "agent-roster";
+
+/** 只依赖工具注册表；档案库与团队状态都是普通文件，不依赖别的插件。 */
+export const inject = ["tools"];
+
+/**
+ * 插件配置。
+ *
+ * 全部声明为 volatile：在设置页改完立即生效，不需要重启宿主——
+ * 这些值只是"去哪读文件、界面说什么语言"，没有需要重建的生命周期资源。
+ */
+export const Config = z.object({
+  rosterDirs: z
+    .array(z.string())
+    .default([])
+    .description(
+      "档案库目录。留空 = 全局默认目录 $DSH_HOME/agent-roster（默认 ~/.dsh/agent-roster，" +
+        "docker 下就是被挂载的数据卷），与工作区无关。填绝对路径或 ~ 开头路径同样是全局的；" +
+        "只有填相对路径（如 examples）才按工作区解析。第一项是四个工具默认读取的档案库。",
+    )
+    .volatile(),
+  knownToolPolicies: z
+    .array(z.string())
+    .default([])
+    .description("部署已声明的 toolPolicy id 列表：填了就能在校验期发现档案里写错的策略 id。留空表示不做交叉校验。")
+    .volatile(),
+  agentTeamsStateDir: z
+    .string()
+    .default(".agent-teams")
+    .description("dsh-agent-teams 的状态目录（只读，用于核对成员实际字段）。相对路径以工作区为基准。")
+    .volatile(),
+  language: z
+    .union([z.const("auto"), z.const("zh"), z.const("en")])
+    .default("auto")
+    .description("面板与设置项的语言：auto 跟随 DSH 当前语言，zh/en 固定中文或英文。")
+    .volatile(),
+  indexes: z
+    .array(z.string())
+    .default([])
+    .description(
+      "公共档案源（registry）列表，可填 https URL 或 npm:pkg。留空 = 只用官方源 " +
+        "STofone/dsh-agent-roster 的 index/registry.json。拉取按 TTL 缓存（默认一小时一次），" +
+        "网络失败时沿用上次缓存，不会把“没拉到”当成“没有档案”。",
+    )
+    .volatile(),
+  region: z
+    .union([z.const("auto"), z.const("global"), z.const("china")])
+    .default("auto")
+    .description("下载区：china 用腾讯 npm 镜像读 npm 形式的目录包；auto 等同 global（不自动探测，避免额外的出网请求）。")
+    .volatile(),
+});
+
+/**
+ * 挂载插件。
+ *
+ * @param {import("@deepseek-ai/cordis").Context} ctx
+ * @param {object} config
+ * @returns {void}
+ */
+export function apply(ctx, config) {
+  // volatile 字段在运行时是引用对象，必须走视图按当前值读，见 lib/config-view.js。
+  const settings = configView(config);
+
+  registerRosterTools(ctx, settings, { version: pkg.version });
+  ctx.logger?.info?.(`dsh-agent-roster ${pkg.version}: registered 4 tools`);
+
+  // 面板路由：读快照 / 读单份档案原文 / 保存 / 删除 / 导入。
+  // 没有 webServer 也不影响工具可用性。
+  ctx.inject(["webServer", "connection"], (webCtx) => {
+    const guard = createAuthGate(webCtx);
+    const register = (path, handler, label) =>
+      webCtx.effect(() => webCtx.webServer.register({ kind: "exact", path, handler }), `dsh-agent-roster: ${label}`);
+
+    register(
+      "/plugins/dsh-agent-roster/library",
+      async (req, res) => {
+        if (guard(req, res)) return;
+        if (!requireMethod(req, res, "GET")) return;
+        const snapshot = buildPanelSnapshot(ctx, settings, { name: pkg.name, version: pkg.version });
+        const query = new URL(req.url ?? "/", "http://localhost").searchParams;
+        // 远程源是“附属信息”：拉不到也不能让本地档案库的响应失败，所以失败只体现在 remote.diagnostics 里。
+        const remote = await loadRemotePanel(settings, { refresh: query.get("refresh") === "1" });
+        sendJson(res, 200, { ...snapshot, remote });
+      },
+      "library route",
+    );
+
+    register(
+      "/plugins/dsh-agent-roster/collection",
+      async (req, res) => {
+        if (guard(req, res)) return;
+        if (!requireMethod(req, res, "GET")) return;
+        const query = new URL(req.url ?? "/", "http://localhost").searchParams;
+        const id = query.get("id") ?? "";
+        const source = query.get("source") ?? "";
+        const remote = await loadRemotePanel(settings, { refresh: query.get("refresh") === "1" });
+        const collection = remote.collections.find(
+          (item) => item.id === id && (source === "" || item.origin?.source === source),
+        );
+        if (collection === undefined) {
+          sendJson(res, 404, { ok: false, error: { code: "collection-not-found" }, known: remote.collections.map((item) => item.id) });
+          return;
+        }
+        const fetched = await fetchCollection(collection);
+        sendJson(res, 200, {
+          ok: fetched.diagnostics.every((item) => item.severity !== "error"),
+          collection: {
+            id: collection.id,
+            title: collection.title,
+            description: collection.description,
+            repo: collection.repo,
+            ref: collection.ref,
+            path: collection.path,
+            rosters: collection.rosters,
+            license: collection.license,
+            homepage: collection.homepage,
+            origin: collection.origin,
+          },
+          rosters: fetched.rosters,
+          diagnostics: fetched.diagnostics,
+        });
+      },
+      "collection route",
+    );
+
+    register(
+      "/plugins/dsh-agent-roster/locale",
+      async (req, res) => {
+        if (guard(req, res)) return;
+        if (!requireMethod(req, res, "GET")) return;
+        const query = new URL(req.url ?? "/", "http://localhost").searchParams;
+        const lang = query.get("lang") === "zh" ? "zh" : "en";
+        try {
+          const text = readFileSync(new URL(`./locale/${lang}.json`, import.meta.url), "utf8");
+          res.writeHead(200, {
+            "content-type": "application/json; charset=utf-8",
+            "cache-control": "no-store",
+          });
+          res.end(text);
+        } catch {
+          sendError(res, 500, "locale-unavailable");
+        }
+      },
+      "locale route",
+    );
+
+    register(
+      "/plugins/dsh-agent-roster/document",
+      async (req, res) => {
+        if (guard(req, res)) return;
+        if (!requireMethod(req, res, "GET")) return;
+        const query = new URL(req.url ?? "/", "http://localhost").searchParams;
+        const result = readRosterDocument({
+          roots: resolveRoots(ctx, settings),
+          rootDir: query.get("rootDir") ?? "",
+          id: query.get("id") ?? "",
+        });
+        if (!result.ok) {
+          sendError(res, result.code === "not-found" ? 404 : 400, result.code);
+          return;
+        }
+        // 编辑表单需要人设原文：解析一份给编辑器用，解析失败也不挡"看源码"这条路。
+        const parsed = parseDocumentText(result.text, { file: result.file, format: result.format });
+        const validated = parsed.ok ? validateRoster(parsed.value, { file: result.file }) : null;
+        sendJson(res, 200, {
+          ok: true,
+          file: result.file,
+          format: result.format,
+          text: result.text,
+          roster: validated?.ok ? validated.roster : null,
+        });
+      },
+      "document route",
+    );
+
+    register(
+      "/plugins/dsh-agent-roster/install",
+      async (req, res) => {
+        if (guard(req, res)) return;
+        if (!requireMethod(req, res, "POST")) return;
+        const body = await readJsonBody(req);
+        if (!body.ok) {
+          sendError(res, body.status, body.code);
+          return;
+        }
+        const input = body.value !== null && typeof body.value === "object" ? body.value : {};
+        if (typeof input.collection !== "string" || input.collection === "") {
+          sendError(res, 400, "missing-collection");
+          return;
+        }
+        const result = await installCollection(settings, {
+          collectionId: input.collection,
+          source: typeof input.source === "string" && input.source !== "" ? input.source : undefined,
+          overwrite: input.overwrite === true,
+        });
+        if (result.ok !== true && result.code !== undefined) {
+          sendJson(res, result.code === "collection-not-found" ? 404 : 400, {
+            ok: false,
+            error: { code: result.code },
+            known: result.known ?? [],
+            diagnostics: result.diagnostics ?? [],
+          });
+          return;
+        }
+        sendJson(res, 200, result);
+      },
+      "install route",
+    );
+
+    register(
+      "/plugins/dsh-agent-roster/rosters",
+      async (req, res) => {
+        if (guard(req, res)) return;
+        if (!requireMethod(req, res, "POST")) return;
+        const body = await readJsonBody(req);
+        if (!body.ok) {
+          sendError(res, body.status, body.code);
+          return;
+        }
+        const input = body.value !== null && typeof body.value === "object" ? body.value : {};
+        const roots = resolveRoots(ctx, settings);
+
+        if (input.action === "delete") {
+          const result = deleteRosterDocument({ roots, rootDir: input.rootDir, id: input.id });
+          if (!result.ok) {
+            sendError(res, result.code === "not-found" ? 404 : 400, result.code);
+            return;
+          }
+          sendJson(res, 200, { ok: true, removed: result.removed });
+          return;
+        }
+
+        if (input.action !== "save" && input.action !== "import") {
+          sendError(res, 400, "unknown-action");
+          return;
+        }
+
+        const result = writeRosterDocument({
+          roots,
+          rootDir: input.rootDir,
+          text: input.text,
+          format: input.format,
+          // import 语义上就是"往库里放一份"，默认允许覆盖同名档案；save 必须由用户确认。
+          overwrite: input.action === "import" ? input.overwrite !== false : input.overwrite === true,
+          knownToolPolicies: settings.knownToolPolicies,
+        });
+        if (!result.ok) {
+          const status =
+            result.code === "exists" || result.code === "format-conflict" ? 409 : result.code === "unknown-root" ? 403 : 422;
+          sendJson(res, status, {
+            ok: false,
+            error: { code: result.code },
+            existing: result.existing ?? null,
+            diagnostics: result.diagnostics ?? [],
+          });
+          return;
+        }
+        sendJson(res, 200, result);
+      },
+      "rosters route",
+    );
+  });
+}
+
+// 面板快照逻辑在 lib/library.js 与 lib/service.js：纯数据投影，可脱离宿主单测。
+export { collectLibrary, markDuplicateIds, serializeRoster } from "./lib/library.js";
+export { buildPanelSnapshot } from "./lib/service.js";