@stofone/dsh-agent-roster 0.9.1 → 0.10.0

package/lib/format-v2.js

@@ -0,0 +1,196 @@
+/**
+ * v2 格式常量：角色（role） / 组装（roster@2） / 编译产物（compiled）。
+ *
+ * 与 `format.js` 的关系：v1（`dsh-agent-roster/v1`）冻结，不再长新字段；
+ * v2 是同一项目的下一个格式版本，两者共用 id / provider / model / semver 这些底层模式，
+ * 但**不共用文档白名单**——v1 的字段以成员为中心，v2 的字段以「角色 + 引用 + 编排」为中心。
+ *
+ * 这里只有数据，没有逻辑；改这里等于改格式，必须同步 bump 对应的 `@N` 与三个 schema 文件。
+ *
+ * @module dsh-agent-roster/format-v2
+ */
+
+import { PATTERNS } from "./format.js";
+
+const { id, semver, provider, model, tag, skill } = PATTERNS;
+
+/**
+ * 维护者句柄：这是「人/账号」，不是档案 id。
+ *
+ * 所以它允许大写与点（`STofone`、`first.last`），也允许长度 1——把人的 GitHub 账号
+ * 强行塞进档案 id 的小写短横线规则里，只会让迁移去篡改真实姓名。
+ */
+const handle = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+/** 角色文档（`roles/<任意目录>/AGENT.md` 的 frontmatter）。 */
+export const ROLE_KIND = "dsh-agent-roster/role@1";
+
+/** 组装文档（`rosters/<id>/roster.yaml`）。 */
+export const ROSTER2_KIND = "dsh-agent-roster/roster@2";
+
+/** 编译产物（`dist/<id>-<version>.json`，以及在内存里生成的 review 视图）。 */
+export const COMPILED_KIND = "dsh-agent-roster/compiled@1";
+/** 施工图：把编排摊成可执行的卡片清单，由队长会话去调用，插件自己不调。 */
+export const PLAN_KIND = "dsh-agent-roster/plan@1";
+
+/** 锁文件（`.agent-roster/lock.yaml`）。 */
+export const LOCK_KIND = "dsh-agent-roster/lock@1";
+
+/** 角色文件名（只有一个，不再按扩展名探测三种）。 */
+export const ROLE_FILE_NAME = "AGENT.md";
+
+/** 角色目录里允许出现的子目录：片段与示例。 */
+export const ROLE_PARTS_DIR = "parts";
+
+/** 组装文档文件名（与 v1 一致，靠 kind 区分版本）。 */
+export const ROSTER2_FILE_NAMES = ["roster.yaml", "roster.yml", "roster.json"];
+
+/** 上限。与 v1 的 `LIMITS` 分开：这些数字属于 v2 的语义，不是 v1 的放宽版。 */
+export const LIMITS2 = {
+  roleNameChars: 64,
+  roleChars: 120,
+  titleChars: 120,
+  descriptionChars: 500,
+  notesChars: 500,
+  tagsPerRole: 16,
+  maintainers: 16,
+  skillsPerRole: 16,
+  /** 一个角色正文（AGENT.md 的 markdown 部分）的上限。 */
+  bodyChars: 8000,
+  /** 一个片段的字符上限。 */
+  partChars: 6000,
+  /** 一个角色最多拆成几个片段。 */
+  parts: 16,
+  /** 拼装后 executionPrompt 的硬上限——这是运行时字段的上限，不是建议值。 */
+  promptChars: 12_000,
+  /** roster 层可以追加的字符上限。 */
+  appendChars: 6000,
+  members: 32,
+  stages: 12,
+  gates: 12,
+  /** 一条验收判据的字符上限（它是句子，不是引用）。 */
+  gateCriterionChars: 160,
+  /** 一个门最多带几条可执行判据，以及一条命令的长度上限。 */
+  gateVerifyCommands: 8,
+  gateVerifyCommandChars: 500,
+  maxRounds: 5,
+  /** 一次编译最多解析多少个角色文件（防把仓库根当角色库扫）。 */
+  roleFiles: 512,
+};
+
+/** 角色 frontmatter 允许的键（未知键一律拒绝）。 */
+export const ROLE_FIELDS = [
+  "$schema",
+  "kind",
+  "name",
+  "version",
+  "role",
+  "title",
+  "description",
+  "tags",
+  "maintainers",
+  "license",
+  "route",
+  "tools",
+  "prompt",
+  "skills",
+  "examples",
+  "requires",
+  "onMissing",
+  "notes",
+];
+
+/** 角色必填键。`prompt` 可省略（表示正文即全部）。 */
+export const ROLE_REQUIRED = ["kind", "name", "version", "role"];
+
+/** `route` 允许的键：与 v1 的 direct 路由字段一一对应，只是嵌套了一层。 */
+export const ROUTE_FIELDS = ["provider", "model", "reasoningEffort"];
+
+/** `tools` 允许的键。`policy` 是 direct，`scope` 是 declaration。 */
+export const TOOLS_FIELDS = ["policy", "scope"];
+
+/** `tools.scope` 允许的键。 */
+export const TOOL_SCOPE_FIELDS = ["allow", "deny"];
+
+/** `prompt` 允许的键。`parts` 是有序片段，`budget` 是字符预算。 */
+export const PROMPT_FIELDS = ["parts", "budget"];
+
+/** `requires` 允许的键：只收有证据源的两类。 */
+export const REQUIRES_FIELDS = ["skills", "toolPolicies"];
+
+/** `onMissing` 的枚举。 */
+export const ON_MISSING = ["refuse", "degraded"];
+export const DEFAULT_ON_MISSING = "refuse";
+
+/** 组装文档允许的顶层键。 */
+export const ROSTER2_FIELDS = [
+  "$schema",
+  "kind",
+  "id",
+  "version",
+  "title",
+  "description",
+  "license",
+  "maintainers",
+  "tags",
+  "defaults",
+  "targets",
+  "members",
+  "captain",
+  "orchestration",
+  "requires",
+  "onMissing",
+  "notes",
+];
+
+/** 组装文档必填键。 */
+export const ROSTER2_REQUIRED = ["kind", "id", "version", "members"];
+
+/** `defaults` 允许的键：只放能被成员继承的**桥接字段**。 */
+export const DEFAULTS2_FIELDS = ["route", "tools"];
+
+/** 一个成员引用允许的键。 */
+export const MEMBER2_FIELDS = ["as", "role", "route", "tools", "prompt", "requires", "notes"];
+
+/** 成员 `prompt` 允许的键：只能 prepend / append，不能替换角色片段。 */
+export const MEMBER_PROMPT_FIELDS = ["prepend", "append"];
+
+/** 队长段允许的键。 */
+export const CAPTAIN2_FIELDS = ["role", "route", "persona", "notes"];
+
+/** 编排段允许的键。 */
+export const ORCHESTRATION_FIELDS = ["shape", "stages", "gates"];
+
+/** 一个阶段允许的键。 */
+export const STAGE_FIELDS = ["id", "parallel", "join", "on", "role", "maxRounds", "serial"];
+
+/** 一个门允许的键。 */
+/**
+ * 门的字段。
+ *
+ * `after` 是「等哪些阶段结束」——机器可校验（必须是存在的 stage）。
+ * `requires` 是「验收判据」——是给人读的句子，编译器只做长度与条数上限，不假装能验它。
+ * `by` 是「谁来判」，必须是这个组装里的成员名。
+ */
+export const GATE_FIELDS = ["id", "after", "requires", "verify", "by"];
+
+/** 门的一条可执行判据：跑什么、期望退出码是什么。 */
+export const VERIFY_FIELDS = ["command", "expectExit"];
+
+/** 编排形态。只有一种被实现；其余留给未来而不是写一个假开关。 */
+export const ORCHESTRATION_SHAPES = ["gate-pipeline"];
+
+/** 编译目标：决定字段落到哪个面。 */
+export const TARGETS = [
+  "agent-teams/members",
+  "agent-teams/orchestration",
+  "profile/agent-preset",
+];
+
+/** 角色引用：`name@1.2.3`。 */
+export const ROLE_REF = new RegExp(`^(${id.source.slice(1, -1)})@(${semver.source.slice(1, -1)})$`);
+
+/** 拼装分隔符——写进格式，不留在代码里。 */
+export const PROMPT_SEPARATOR = "\n\n";
+
+export const PATTERNS2 = { id, semver, provider, model, tag, skill, handle, roleRef: ROLE_REF };

package/lib/frontmatter.js

@@ -0,0 +1,113 @@
+/**
+ * Markdown + YAML frontmatter 解析：把一份 `AGENT.md` 拆成「参数」（frontmatter）与「人设」（正文）。
+ *
+ * 为什么不用一种方言装两种内容：散文需要高亮、diff、lint；参数需要机器校验。
+ * 混在一个 YAML 块标量里，缩进错一格内容就静默变形（v1 的真实痛点，见 issue #3）。
+ *
+ * 解析只回答「这段文本能否拆成两块」，语义校验交给 `role.js`；失败一律转诊断，不抛异常。
+ *
+ * @module dsh-agent-roster/frontmatter
+ */
+import { diagnostic } from "./parse.js";
+
+const FENCE = /^---[ \t]*$/;
+
+/**
+ * 拆分 frontmatter 与正文。
+ *
+ * 规则（写死在这里，作为格式的一部分）：
+ * 1. 第一行必须是 `---`（允许前面有空行与 BOM，但只有这一种围栏）；
+ * 2. 结束围栏是**独占一行**的 `---`；
+ * 3. 正文只去掉开头连续的空白行，其余原样保留（不做 dedent、不改缩进）。
+ *
+ * @param {string} text 文件全文
+ * @param {{ file?: string }} [options]
+ * @returns {{ ok: boolean, frontmatter: string | null, body: string, diagnostics: object[] }}
+ */
+export function splitFrontmatter(text, options = {}) {
+  const file = String(options.file ?? "");
+  const source = String(text ?? "").replace(/^\uFEFF/, "");
+  const diagnostics = [];
+
+  if (source.trim() === "") {
+    diagnostics.push(diagnostic("error", "empty-document", "", "文档为空", file));
+    return { ok: false, frontmatter: null, body: "", diagnostics };
+  }
+
+  const lines = source.split("\n");
+  let index = 0;
+  while (index < lines.length && lines[index].trim() === "") index += 1;
+
+  if (index >= lines.length || !FENCE.test(lines[index])) {
+    diagnostics.push(
+      diagnostic(
+        "error",
+        "missing-frontmatter",
+        "",
+        "AGENT.md 必须以独占一行的 --- 开头，紧接着 YAML frontmatter；正文放在第二个 --- 之后",
+        file,
+      ),
+    );
+    return { ok: false, frontmatter: null, body: "", diagnostics };
+  }
+
+  const start = index + 1;
+  let end = -1;
+  for (let cursor = start; cursor < lines.length; cursor += 1) {
+    if (FENCE.test(lines[cursor])) {
+      end = cursor;
+      break;
+    }
+  }
+
+  if (end === -1) {
+    diagnostics.push(
+      diagnostic("error", "unterminated-frontmatter", "", "frontmatter 没有结束围栏（缺少独占一行的 ---）", file),
+    );
+    return { ok: false, frontmatter: null, body: "", diagnostics };
+  }
+
+  const frontmatter = lines.slice(start, end).join("\n");
+  if (frontmatter.trim() === "") {
+    diagnostics.push(diagnostic("error", "empty-frontmatter", "", "frontmatter 为空：至少要有 kind / name / version / role", file));
+    return { ok: false, frontmatter: null, body: "", diagnostics };
+  }
+
+  let bodyStart = end + 1;
+  while (bodyStart < lines.length && lines[bodyStart].trim() === "") bodyStart += 1;
+  const body = lines.slice(bodyStart).join("\n").replace(/\s+$/, "");
+
+  if (body === "") {
+    diagnostics.push(
+      diagnostic("error", "empty-body", "body", "正文为空：人设写在第二个 --- 之后；空人设不会被当成“用默认值”", file),
+    );
+    return { ok: false, frontmatter, body: "", diagnostics };
+  }
+
+  return { ok: true, frontmatter, body, diagnostics };
+}
+
+/**
+ * 把正文与片段按格式规定的语义拼成最终 executionPrompt。
+ *
+ * 拼装规则是格式的一部分：`join("\n\n", [body, ...parts])`。
+ * 除了 roster 层允许的 prepend / append，没有第二个改变顺序或分隔符的入口。
+ *
+ * @param {string} body 角色正文
+ * @param {string[]} parts 片段正文（按 frontmatter 里的顺序）
+ * @param {{ prepend?: string, append?: string }} [extra] roster 层追加
+ * @returns {{ text: string, parts: string[] }}
+ */
+export function assemblePrompt(body, parts, extra = {}) {
+  const blocks = [];
+  if (typeof extra.prepend === "string" && extra.prepend !== "") blocks.push(extra.prepend);
+  if (body !== "") blocks.push(body);
+  for (const part of parts ?? []) if (typeof part === "string" && part !== "") blocks.push(part);
+  if (typeof extra.append === "string" && extra.append !== "") blocks.push(extra.append);
+  return { text: blocks.join("\n\n"), parts: blocks.map((block) => block.length) };
+}
+
+/** 字符数（人设预算按字符计，不按字节，也不猜 token）。 */
+export function charLength(text) {
+  return [...String(text ?? "")].length;
+}

package/lib/migrate.js

@@ -0,0 +1,326 @@
+/**
+ * v1 档案 → v2（角色 / 组装 / 编译）的原地迁移。
+ *
+ * 迁移只做形状改写，不做语义发明：
+ *
+ * - 成员原来内嵌的 `systemPrompt` 变成 `roles/<roster>-<member>/AGENT.md` 的正文；
+ * - 原来写在成员上的路由与工具策略搬进角色 frontmatter；
+ * - 组装只留引用（`role: <roster>-<member>@1.0.0`），成员名、标题、描述保持原样；
+ * - 队长从「成员之外的一个字段」变成真正的角色文件，`captain.role` 指向它；
+ * - 能力要求（`capabilities.yaml`）跟着档案走，内容不动。
+ *
+ * 角色名带档案 id 前缀，是因为 v2 要求**同一座库里角色名唯一**，而仓库里的 21 套业务档案
+ * 全都叫 `lead`；不加前缀就无法共存，加了前缀至少能追溯「这份人设属于谁」。
+ *
+ * @module dsh-agent-roster/migrate
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import nodePath from "node:path";
+
+import { CAPABILITIES_FILE_NAMES, validateCapabilities } from "./capabilities.js";
+import { compileRoster, scanRoles } from "./compile2.js";
+import { MEMBER_FILE_NAMES } from "./format.js";
+import { parseDocumentText } from "./parse.js";
+import { compilePlan } from "./plan.js";
+import { loadRosterAt } from "./registry.js";
+
+export const ROLES_DIR = "roles";
+export const ROSTERS_DIR = "rosters";
+export const DIST_DIR = "dist";
+
+const ROLE_VERSION = "1.0.0";
+const EMPTY_PERSONA = "（迁移时原档案没有写人设正文；请补上这个角色的职责与边界。）";
+
+/** 把值写成 YAML（块风格）。字符串一律 JSON 转义，避免冒号、井号被误读。 */
+export function emitYaml(value, indent = 0) {
+  const pad = " ".repeat(indent);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    return value
+      .map((item) => {
+        if (item !== null && typeof item === "object") {
+          const nested = emitYaml(item, indent + 2);
+          // `- key: v` 的形式更像人写的 YAML：第一行跟在短横线后，其余按缩进续行。
+          const [first, ...rest] = nested.split("\n");
+          return [`${pad}- ${first.trimStart()}`, ...rest].join("\n");
+        }
+        return `${pad}- ${inline(item)}`;
+      })
+      .join("\n");
+  }
+  if (value !== null && typeof value === "object") {
+    if (Object.keys(value).length === 0) return "{}";
+    const lines = [];
+    for (const [key, item] of Object.entries(value)) {
+      if (item === undefined) continue;
+      if (Array.isArray(item)) {
+        lines.push(item.length === 0 ? `${pad}${key}: []` : `${pad}${key}:\n${emitYaml(item, indent + 2)}`);
+      } else if (item !== null && typeof item === "object") {
+        const body = emitYaml(item, indent + 2);
+        lines.push(Object.keys(item).length === 0 ? `${pad}${key}: {}` : `${pad}${key}:\n${body}`);
+      } else {
+        lines.push(`${pad}${key}: ${inline(item)}`);
+      }
+    }
+    return lines.join("\n");
+  }
+  return `${pad}${inline(value)}`;
+}
+
+function inline(value) {
+  if (value === null) return "null";
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return `[${value.map(inline).join(", ")}]`;
+  if (value !== null && typeof value === "object") return JSON.stringify(value);
+  return JSON.stringify(String(value));
+}
+
+/** 角色文件的内容：frontmatter + 空行 + 正文。 */
+export function roleDocument(role, body) {
+  const text = String(body ?? "").trim().length > 0 ? String(body).trimEnd() : EMPTY_PERSONA;
+  return `---\n${emitYaml(role)}\n---\n\n${text}\n`;
+}
+
+function routeOf(source) {
+  if (source === null || source === undefined) return null;
+  const route = {};
+  if (source.provider) route.provider = source.provider;
+  if (source.model) route.model = source.model;
+  if (source.reasoningEffort) route.reasoningEffort = source.reasoningEffort;
+  return Object.keys(route).length > 0 ? route : null;
+}
+
+function listOf(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.length > 0) : [];
+}
+
+/**
+ * 把一份 v1 档案转成 v2 的两类文件（角色文件 + 组装）。
+ * 编译产物在写盘之后由 `compileRoster` 生成，这里不重复拼装。
+ */
+export function convertRoster(roster, { capabilities = null } = {}) {
+  // v1 的 id 字段叫 `roster`；校验后的对象会补一个 `id`，但单测里可能直接传原文。
+  const rosterId = roster.id ?? roster.roster;
+  const version = roster.version ?? "1.0.0";
+  const files = [];
+  const members = [];
+  const roleNames = [];
+  const skills = new Set();
+  const policies = new Set();
+
+  for (const member of roster.members ?? []) {
+    const roleName = `${rosterId}-${member.name}`;
+    roleNames.push(roleName);
+    const memberSkills = listOf(member.skills);
+    const policy = member.toolPolicy ?? roster.defaults?.toolPolicy ?? null;
+    for (const skill of memberSkills) skills.add(skill);
+    if (policy) policies.add(policy);
+    const role = {
+      kind: "dsh-agent-roster/role@1",
+      name: roleName,
+      version: ROLE_VERSION,
+      role: member.role ?? member.name,
+    };
+    if (member.title) role.title = member.title;
+    if (member.description) role.description = member.description;
+    if (listOf(member.tags).length > 0) role.tags = listOf(member.tags);
+    const route = routeOf(member);
+    if (route) role.route = route;
+    if (member.toolPolicy) role.tools = { policy: member.toolPolicy };
+    if (memberSkills.length > 0) role.requires = { skills: memberSkills };
+    files.push({ path: nodePath.join(ROLES_DIR, roleName, "AGENT.md"), text: roleDocument(role, member.systemPrompt) });
+    members.push({ as: member.name, role: `${roleName}@${ROLE_VERSION}` });
+  }
+
+  let captain = null;
+  if (roster.captain) {
+    // v1 里队长常常与某个成员同名（`lead` 既是成员又是 captain）；两者人设不同，
+    // 所以重名时给队长加后缀，而不是悄悄合并成同一个角色。
+    const base = `${rosterId}-${roster.captain.name ?? "captain"}`;
+    const captainName = roleNames.includes(base) ? `${base}-captain` : base;
+    roleNames.push(captainName);
+    const role = {
+      kind: "dsh-agent-roster/role@1",
+      name: captainName,
+      version: ROLE_VERSION,
+      role: roster.captain.role ?? "队长",
+    };
+    if (roster.captain.description) role.description = roster.captain.description;
+    const route = routeOf(roster.captain);
+    if (route) role.route = route;
+    files.push({
+      path: nodePath.join(ROLES_DIR, captainName, "AGENT.md"),
+      text: roleDocument(role, roster.captain.personaPrefix ?? roster.captain.description ?? ""),
+    });
+    captain = { role: `${captainName}@${ROLE_VERSION}` };
+    const captainRoute = routeOf(roster.captain);
+    if (captainRoute) captain.route = captainRoute;
+  }
+
+  for (const item of capabilities?.requires?.skills ?? []) skills.add(typeof item === "string" ? item : item.name);
+  for (const item of capabilities?.requires?.toolPolicies ?? []) policies.add(typeof item === "string" ? item : item.name);
+
+  const defaults = {};
+  const defaultRoute = routeOf(roster.defaults ?? null);
+  if (defaultRoute) defaults.route = defaultRoute;
+  if (roster.defaults?.toolPolicy) defaults.tools = { policy: roster.defaults.toolPolicy };
+
+  const targets = ["agent-teams/members"];
+  if (captain !== null) targets.push("profile/agent-preset");
+
+  const roster2 = { kind: "dsh-agent-roster/roster@2", id: rosterId, version };
+  if (roster.title) roster2.title = roster.title;
+  if (roster.description) roster2.description = roster.description;
+  if (roster.license) roster2.license = roster.license;
+  if (listOf(roster.maintainers).length > 0) roster2.maintainers = listOf(roster.maintainers);
+  if (listOf(roster.tags).length > 0) roster2.tags = listOf(roster.tags);
+  if (Object.keys(defaults).length > 0) roster2.defaults = defaults;
+  roster2.targets = targets;
+  roster2.members = members;
+  if (captain !== null) roster2.captain = captain;
+  if (skills.size > 0 || policies.size > 0) {
+    roster2.requires = {};
+    if (skills.size > 0) roster2.requires.skills = [...skills];
+    if (policies.size > 0) roster2.requires.toolPolicies = [...policies];
+  }
+  if (capabilities?.onMissing) roster2.onMissing = capabilities.onMissing;
+
+  files.push({ path: nodePath.join(ROSTERS_DIR, rosterId, "roster.yaml"), text: `${emitYaml(roster2)}\n` });
+  return { roster: roster2, files, members, roleNames, memberCount: members.length, hasCaptain: captain !== null };
+}
+
+function loadCapabilitiesOf(dir) {
+  for (const name of CAPABILITIES_FILE_NAMES) {
+    const file = nodePath.join(dir, name);
+    if (!existsSync(file)) continue;
+    const parsed = parseDocumentText(readFileSync(file, "utf8"), name);
+    if (!parsed.ok) return null;
+    const outcome = validateCapabilities(parsed.value, { file: name, expectedId: null });
+    return outcome.ok ? outcome.capabilities : null;
+  }
+  return null;
+}
+
+/**
+ * 迁移一座 v1 档案库。
+ *
+ * 不写盘时只返回计划；`write: true` 才落盘、编译、写出 `dist/`，并在最后删掉旧的 `<id>/` 目录。
+ */
+export function migrateLibrary(rootDir, { write = false, knownToolPolicies = null, source = {} } = {}) {
+  const report = { rootDir, write, entries: [], diagnostics: [], written: [], removed: [], compiled: [] };
+  let children = [];
+  try {
+    children = readdirSync(rootDir, { withFileTypes: true });
+  } catch (error) {
+    report.diagnostics.push({ severity: "error", code: "unreadable-dir", path: "", file: null, reason: `档案库不可读：${error?.message ?? error}` });
+    return report;
+  }
+
+  const seenRoles = new Map();
+  for (const child of children) {
+    if (!child.isDirectory() || child.isSymbolicLink()) continue;
+    if (child.name.startsWith(".") || child.name === ROLES_DIR || child.name === ROSTERS_DIR || child.name === DIST_DIR) continue;
+    const dir = nodePath.join(rootDir, child.name);
+    // v1 的档案文件名可以是 yaml / yml / json——迁移只认内容，不认扩展名。
+    if (!MEMBER_FILE_NAMES.some((name) => existsSync(nodePath.join(dir, name)))) continue;
+    const loaded = loadRosterAt(dir, { knownToolPolicies });
+    if (!loaded.ok) {
+      report.diagnostics.push({
+        severity: "warn",
+        code: "migrate-skipped",
+        path: "",
+        file: `${child.name}/roster.yaml`,
+        reason: `跳过：${loaded.diagnostics.map((item) => item.reason).join("；") || "读不出档案"}`,
+      });
+      continue;
+    }
+    const capabilities = loadCapabilitiesOf(dir);
+    const converted = convertRoster(loaded.roster, { capabilities });
+    for (const roleName of converted.roleNames) {
+      if (seenRoles.has(roleName)) {
+        report.diagnostics.push({
+          severity: "error",
+          code: "duplicate-role",
+          path: "",
+          file: `${child.name}/roster.yaml`,
+          reason: `角色名 "${roleName}" 与 ${seenRoles.get(roleName)} 重复；v2 要求同库唯一`,
+        });
+      }
+      seenRoles.set(roleName, child.name);
+    }
+    report.entries.push({
+      id: loaded.roster.id,
+      version: loaded.roster.version,
+      from: `${child.name}/roster.yaml`,
+      files: converted.files,
+      memberCount: converted.memberCount,
+      hasCaptain: converted.hasCaptain,
+      capabilities: capabilities !== null,
+    });
+  }
+
+  if (!write) return report;
+
+  for (const entry of report.entries) {
+    for (const file of entry.files) {
+      const target = nodePath.join(rootDir, file.path);
+      mkdirSync(nodePath.dirname(target), { recursive: true });
+      writeFileSync(target, file.text, "utf8");
+      report.written.push(file.path);
+    }
+    for (const name of CAPABILITIES_FILE_NAMES) {
+      const source = nodePath.join(rootDir, entry.id, name);
+      if (!existsSync(source)) continue;
+      const relative = nodePath.join(ROSTERS_DIR, entry.id, name);
+      const target = nodePath.join(rootDir, relative);
+      mkdirSync(nodePath.dirname(target), { recursive: true });
+      writeFileSync(target, readFileSync(source, "utf8"), "utf8");
+      report.written.push(relative);
+      break;
+    }
+  }
+
+  const scanned = scanRoles(nodePath.join(rootDir, ROLES_DIR), { knownToolPolicies });
+  report.diagnostics.push(...scanned.diagnostics);
+  for (const entry of report.entries) {
+    const compiled = compileRoster({
+      rosterDir: nodePath.join(rootDir, ROSTERS_DIR, entry.id),
+      roles: scanned.roles,
+      expectedId: entry.id,
+      knownToolPolicies,
+      source: {},
+    });
+    if (!compiled.ok) {
+      report.diagnostics.push({
+        severity: "error",
+        code: "migrate-compile-failed",
+        path: "",
+        file: `${ROSTERS_DIR}/${entry.id}/roster.yaml`,
+        reason: compiled.diagnostics.map((item) => item.reason).join("；"),
+      });
+      continue;
+    }
+    const name = `${compiled.compiled.source.roster}-${compiled.compiled.source.version}`;
+    const planResult = compilePlan(compiled.compiled);
+    const outputs = [{ path: nodePath.join(DIST_DIR, `${name}.json`), text: `${JSON.stringify(compiled.compiled, null, 2)}\n` }];
+    if (planResult.plan !== null) {
+      outputs.push({ path: nodePath.join(DIST_DIR, `${name}.tasks.json`), text: `${JSON.stringify(planResult.plan, null, 2)}\n` });
+    }
+    for (const output of outputs) {
+      const target = nodePath.join(rootDir, output.path);
+      mkdirSync(nodePath.dirname(target), { recursive: true });
+      writeFileSync(target, output.text, "utf8");
+      report.written.push(output.path);
+    }
+    report.compiled.push({ id: entry.id, members: compiled.compiled.members.length, plan: planResult.plan !== null });
+  }
+
+  for (const entry of report.entries) {
+    const legacy = nodePath.join(rootDir, entry.id);
+    if (!existsSync(legacy) || !statSync(legacy).isDirectory()) continue;
+    // 只删「迁移前的那份目录」：v2 布局里档案在 rosters/ 下，root 上不该再有同名目录。
+    rmSync(legacy, { recursive: true, force: true });
+    report.removed.push(entry.id);
+  }
+  return report;
+}