@stofone/dsh-agent-roster 0.10.0 → 0.10.2

package/CHANGELOG.md

@@ -4,6 +4,33 @@
 
 ## [Unreleased]
 
+## [0.10.2] - 2026-11-03
+
+### Fixed
+
+- **Every v2 collection was unfetchable (HTTP 404).** The index assumed the v1 flat layout
+  (`<path>/<id>/roster.yaml`), which stopped existing the moment rosters moved to `rosters/<id>/`.
+  A collection may now pin one relative path per roster in an optional `files` map;
+  `registry sync` fills it in and points v2 rosters at the self-contained `dist/<id>-<ver>.json`
+  (an assembly alone cannot be pulled — its members are role references).
+- Pulling a compiled artifact flattens it into an inline v1 document (personas are the assembled
+  prompt, which is what would actually be sent); run `migrate` afterwards if you want the role split
+  on your machine. A bare `roster@2` is reported as `collection-roster-needs-roles` instead of being
+  fetched as if it were one file.
+- `flattenCompiledToRoster` no longer emits empty `title`/`description` strings — v1 rejects those,
+  so a flattened artifact used to fail its own validation.
+
+## [0.10.1] - 2026-11-03
+
+### Docs
+
+- The Chinese README said `migrate` was "not implemented", listed one example library where there are
+  two, and had a file tree from before `roles/`, `roster.v2` and `compiled.v1` existed — docs that
+  describe last week's format read as current, which is worse than no docs.
+- Both READMEs now carry the same two sections: one-command v1→v2 migration (including why role names
+  are prefixed and why a colliding captain gets `-captain`), and feeding a failed round back into the
+  plan with `compile --run`.
+
 ## [0.10.0] - 2026-11-03
 
 ### Roles, rosters and compiled artifacts (v2)
@@ -445,7 +472,10 @@
 - 工具返回值含 `undefined` 键，运行时按 `value is not lossless JSON` 整次拒绝；缺失值统一写 `null`，
   且所有返回值先过 `lib/json.js#lossless`。
 
-[Unreleased]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.9.2...main
+[Unreleased]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.10.2...main
+[0.10.2]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.10.1...v0.10.2
+[0.10.1]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.10.0...v0.10.1
+[0.10.0]: https://github.com/dsh-agent-roster/dsh-agent-roster/releases/tag/v0.10.0
 [0.9.2]: https://github.com/dsh-agent-roster/dsh-agent-roster/releases/tag/v0.9.2
 [0.9.1]: https://github.com/dsh-agent-roster/dsh-agent-roster/releases/tag/v0.9.1
 [0.9.0]: https://github.com/dsh-agent-roster/dsh-agent-roster/releases/tag/v0.9.0

package/README.md

@@ -383,6 +383,10 @@ repository's `index/registry.json`, and anyone who subscribes can see them in th
 - **Pulling**: writes are idempotent and report one of `created`, `updated` (explicit overwrite), `unchanged`
   (same content, nothing written) or `conflict` (the local copy differs and is **not** overwritten by default).
   Conflicts are yours to resolve: merge in the editor, or pull again with `overwrite` in the request body.
+- **Where each roster lives**: a collection's `rosters[]` is just the list of ids; the optional
+  `files` map says where each one is (`{"core-review": "dist/core-review-1.0.0.json"}`). It is optional —
+  without it the fetcher assumes the v1 layout `<id>/roster.yaml` — but a v2 library needs it, because an
+  assembly only references roles and cannot be pulled on its own. `registry sync` writes this map for you.
 - **The index has a schema**: [`schema/registry.v1.schema.json`](./schema/registry.v1.schema.json) mirrors the
   runtime validator, so an editor flags a typo before CI does.
 - **Publishing your own**: add an entry to `collections` in `index/registry.json` (`id`, `repo: github:owner/repo`,
@@ -450,7 +454,8 @@ lib/              format, parse, validate, registry, bridge, verify, render, lib
                   config-view, json, http, write, service, teams-state, tools
 client.js         client plugin: sidebar entry, main panel (rosters/teams/health), settings section
 locale/           panel + listing dictionaries (en/zh)
-schema/           roster / capabilities / organization / registry v1 schemas (editor completion; kept aligned by tests)
+schema/           roster v1 / role v1 / roster v2 / compiled v1 / capabilities / organization / registry
+                  schemas (editor completion; kept aligned by tests)
 bin/cli.mjs       validate/list/compile/migrate/registry for CI
 scripts/          host-smoke.mjs, client-smoke.mjs, check-locale.mjs (dev only, not shipped)
 examples/         a v2 library migrated from the v1 archives

package/README.zh.md

@@ -82,7 +82,7 @@ captain:                     # 可选：记录队长（＝创建团队的那个
 
 JSON 也可以（`roster.json`）。同一目录下按 `roster.yaml` → `roster.yml` → `roster.json` 顺序探测，**只认一份**；出现第二份会报诊断，绝不静默挑一份。
 
-本包自带两份示例档案库（[`examples/`](./examples)）。`rosterDirs` 默认留空，也就是上面那座全局库；
+本包自带两份示例档案库：[`examples/`](./examples)（v2，由本仓历史档案迁移而来）与 [`examples-orchestration/`](./examples-orchestration)（v2，手写，用来演示门与施工图）。`rosterDirs` 默认留空，也就是上面那座全局库；
 新装时它是空的，所以面板一开始显示「0 份档案」——在面板里新建一份即可（目录会自动创建）。想先看示例库：
 
 ```bash
@@ -227,7 +227,7 @@ rosters/<id>/roster.yaml      组装：成员是引用，队长独立成段
 dist/<id>-<ver>.json          编译产物：自包含、可哈希，消费者只看它
 ```
 
-判别键决定版本——`dsh-agent-roster/role@1`、`dsh-agent-roster/roster@2`、`dsh-agent-roster/compiled@1`。同一目录不允许两种格式共存：v1 冻结，`roster migrate`（尚未实现）负责原地重写。
+判别键决定版本——`dsh-agent-roster/role@1`、`dsh-agent-roster/roster@2`、`dsh-agent-roster/compiled@1`。同一目录不允许两种格式共存：v1 冻结，`migrate` 负责原地重写。
 
 拼装写进格式，而不是藏在代码里：
 
@@ -260,6 +260,28 @@ node bin/cli.mjs compile --roster examples-orchestration/rosters/core-review --j
 
 `orchestration` 是格式的一部分，但编译时标 `status: "declaration"`：阶段与门会被校验（门的 `after` 必须指向真实阶段，`by` 必须指向真实成员），但没有任何东西执行它。能声明不等于已被证明会运行，所以产物在 `declarations[]` 里逐条说明谁属于哪一类。完整契约——字段归宿、拼装语义、身份与唯一性、迁移规则——见 [`docs/roster-v2.md`](./docs/roster-v2.md)；schema 见 [`schema/role.v1.schema.json`](./schema/role.v1.schema.json)、[`schema/roster.v2.schema.json`](./schema/roster.v2.schema.json)、[`schema/compiled.v1.schema.json`](./schema/compiled.v1.schema.json)。
 
+### 从 v1 到 v2，一条命令
+
+```bash
+node bin/cli.mjs migrate --dir examples            # 只出计划：要写哪些文件、能不能编译
+node bin/cli.mjs migrate --dir examples --write    # 原地重写：roles/ + rosters/ + dist/，删掉旧目录
+```
+
+迁移逐字保留人设：成员的 `systemPrompt` 原文成为 `roles/<档案>-<成员>/AGENT.md` 的正文，成员本身变成引用。队长不再是一个散字段，而是自己的角色文件——与成员同名时得到 `-captain` 后缀，因为那是两份人设，悄悄合并会丢掉一份。
+
+角色名带档案 id 前缀，是因为 v2 要求同库角色名唯一：一座库里 21 套组装都叫自己的队长 `lead`，不可能有 21 个同名文件。
+
+### 把失败的一轮喂回施工图
+
+`compile --run <文件>` 读执行回执（`run@1`），把上一轮的失败并进重试卡的 description：
+
+```bash
+node bin/cli.mjs compile --roster examples-orchestration/rosters/core-review \
+  --run examples-orchestration/dist/core-review-1.0.0.run.json
+```
+
+回执由执行施工图的队长会话写，不由插件写：任务 id 属于团队，插件从不写团队状态。插件负责的是合并——只活在红卡上的失败，下一次编译就消失了，门也就变成了装饰。
+
 ## 工具
 
 | 工具 | 作用 |
@@ -342,6 +364,9 @@ node bin/cli.mjs compile --roster examples-orchestration/rosters/core-review --j
   冲突要你自己决定：要么在编辑器里合并，要么再点一次「拉取到本机」并在请求里带 `overwrite`。
 - **索引本身也有 schema**：[`schema/registry.v1.schema.json`](./schema/registry.v1.schema.json) 与运行时校验器对齐，
   拼错字段在编辑器里就会提示，不必等 CI。
+- **每份档案住在哪**：collection 的 `rosters[]` 只是 id 名单，实际位置由可选的 `files` 映射给出
+  （如 `{"core-review": "dist/core-review-1.0.0.json"}`）。不写就按 v1 布局 `<id>/roster.yaml` 猜——v2 的库必须写，
+  因为组装本身只引用角色，单独拉一个文件拉不到角色目录。`registry sync` 会替你填。
 - **登记自己的档案**：在 `index/registry.json` 的 `collections` 里加一条（`id`、`repo: github:owner/repo`、
   `ref`、`path`、`rosters[]`），提交 PR 即可；`.github/workflows/registry.yml` 会校验索引与仓库真实文件是否对得上。
 
@@ -405,11 +430,13 @@ lib/              format / parse / validate / registry / bridge / verify / rende
                   config-view / json / http / write / service / teams-state / tools
 client.js         客户端半边：左侧栏图标 + 主面板（档案/团队/体检）+ 设置页小节
 locale/           面板与列表词典（en/zh）
-schema/           roster / capabilities / organization / registry v1 schema（编辑器补全用，与校验器由测试对齐）
-bin/cli.mjs       validate / list / version，给 CI 用
+schema/           roster v1 / role v1 / roster v2 / compiled v1 / capabilities / organization / registry
+                  schema（编辑器补全用，与校验器由测试对齐）
+bin/cli.mjs       validate / list / compile / migrate / registry，给 CI 用
 scripts/          host-smoke.mjs、client-smoke.mjs、check-locale.mjs（开发用，不随包发布）
-examples/         两座示例档案库
-orgs/             带 organization.yaml 的示例库（21 套档案）
+examples/         由历史 v1 档案迁移来的 v2 库（roles/ + rosters/ + dist/）
+examples-orchestration/  手写的 v2 库：编排、门与施工图
+orgs/             带 organization.yaml 的示例库（21 套 v2 档案）
 test/             单测
 ```
 

package/bin/cli.mjs

@@ -26,6 +26,7 @@ import { compileRosterAt } from "../lib/compile2.js";
 import { migrateLibrary } from "../lib/migrate.js";
 import { compilePlan } from "../lib/plan.js";
 import { mergeRunIntoPlan, validateRun } from "../lib/run.js";
+import { DIST_DIR } from "../lib/migrate.js";
 
 const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 
@@ -442,6 +443,17 @@ async function runRegistry(options) {
         entry.rosters = ids;
         changed = true;
       }
+      const files = {};
+      for (const roster of scanned.rosters.slice().sort((a, b) => a.id.localeCompare(b.id))) {
+        files[roster.id] =
+          roster.format === "v2"
+            ? `${DIST_DIR}/${roster.id}-${roster.version}.json`
+            : `${roster.id}/${roster.file ?? "roster.yaml"}`;
+      }
+      if (JSON.stringify(files) !== JSON.stringify(entry.files ?? {})) {
+        entry.files = files;
+        changed = true;
+      }
     }
     if (options.write) {
       writeFileSync(file, `${JSON.stringify(document, null, 2)}\n`);

package/docs/roster-v2.md

@@ -212,9 +212,14 @@ gates:
 
 三者正交：`requires` 说"必须有"，`capabilities.yaml` 说"这份组装必须有"，`organization.yaml` 说"这座库有哪些"。
 
+远端的 registry 索引也是同理：登记的 `rosters[]` 只是 id 名单，实际位置由 `files` 映射给出。
+v1 的库可以省略（回退成 `<id>/roster.yaml`）；v2 的库必须写，**指向 `dist/` 的编译产物**——
+组装文件本身只引用角色，单独拉一个 `roster.yaml` 拉不到角色目录，那不是"没实现"，是"拉下来也不完整"。
+拉到编译产物后，客户端把它摊成一份内联 v1 文档（人设就是拼装结果），要角色分层就在本地跑 `migrate`。
+
 ## 10. 未决与下一步
 
 1. **施工图 ↔ 团队真实卡 id 的映射**：`run@1` 已经能读、能合并（`compile --run` 会把上一轮失败写进重试卡），但「施工图内部 id ↔ 团队真实 task id」的映射表还没落成文件——目前靠执行者按 id 命名建卡。
-2. `dist` 的发布与 `registry` 只登记产物（现在 registry 登记的是档案路径）。
+2. `dist` 的发布流程（索引已能逐份指向 `dist/<id>-<ver>.json`，但"从 dist 反推角色版本、做跨库一致性检查"还没做）。
 3. `profile/agent-preset` 目标：把队长与成员的 preset 片段生成出来，仍然只产参不写入。
 4. 编辑器支持：三个 schema 已就位，LSP 级校验待做。

package/index/registry.json

@@ -2,7 +2,7 @@
   "$schema": "../schema/registry.v1.schema.json",
   "kind": "dsh-agent-roster-registry/v1",
   "version": 1,
-  "generatedAt": "2026-11-02T17:00:43.713Z",
+  "generatedAt": "2026-11-03T05:50:01.540Z",
   "generator": "dsh-agent-roster/dsh-agent-roster (hand-maintained; verified by .github/workflows/registry.yml)",
   "source": "https://github.com/dsh-agent-roster/dsh-agent-roster",
   "collections": [
@@ -26,7 +26,11 @@
       "maintainers": [
         "STofone"
       ],
-      "homepage": "https://github.com/dsh-agent-roster/dsh-agent-roster#examples"
+      "homepage": "https://github.com/dsh-agent-roster/dsh-agent-roster#examples",
+      "files": {
+        "core-review": "dist/core-review-1.0.0.json",
+        "research": "dist/research-0.1.0.json"
+      }
     },
     {
       "id": "agent-roster-collective",
@@ -70,7 +74,30 @@
       "maintainers": [
         "STofone"
       ],
-      "homepage": "https://github.com/dsh-agent-roster/dsh-agent-roster/tree/main/orgs/agent-roster-collective"
+      "homepage": "https://github.com/dsh-agent-roster/dsh-agent-roster/tree/main/orgs/agent-roster-collective",
+      "files": {
+        "api-design": "dist/api-design-1.0.0.json",
+        "content-ops": "dist/content-ops-1.0.0.json",
+        "contract-review": "dist/contract-review-1.0.0.json",
+        "data-quality": "dist/data-quality-1.0.0.json",
+        "db-migration": "dist/db-migration-1.0.0.json",
+        "docs-writer": "dist/docs-writer-1.0.0.json",
+        "finance-recon": "dist/finance-recon-1.0.0.json",
+        "frontend-ui": "dist/frontend-ui-1.0.0.json",
+        "i18n-l10n": "dist/i18n-l10n-1.0.0.json",
+        "incident-response": "dist/incident-response-1.0.0.json",
+        "literature-review": "dist/literature-review-1.0.0.json",
+        "market-research": "dist/market-research-1.0.0.json",
+        "ml-eval": "dist/ml-eval-1.0.0.json",
+        "performance": "dist/performance-1.0.0.json",
+        "product-discovery": "dist/product-discovery-1.0.0.json",
+        "qa-regression": "dist/qa-regression-1.0.0.json",
+        "recruiting": "dist/recruiting-1.0.0.json",
+        "release-manager": "dist/release-manager-1.0.0.json",
+        "security-audit": "dist/security-audit-1.0.0.json",
+        "sre-oncall": "dist/sre-oncall-1.0.0.json",
+        "support-triage": "dist/support-triage-1.0.0.json"
+      }
     },
     {
       "id": "agent-teams",

package/lib/compile2.js

@@ -21,6 +21,7 @@ import {
   ROLE_PARTS_DIR,
   ROSTER2_FILE_NAMES,
 } from "./format-v2.js";
+import { ROSTER_KIND } from "./format.js";
 import { diagnostic, parseDocumentText } from "./parse.js";
 import { loadRoleAt, safeResolve } from "./role.js";
 import { validateRoster2 } from "./roster2.js";
@@ -520,3 +521,110 @@ export function rosterViewOf(compiled, roster2, options = {}) {
     orchestration: compiled.orchestration ?? null,
   };
 }
+
+/**
+ * 校验一份编译产物。
+ *
+ * 这是「消费者只看产物」的入口：远端订阅拿到的就是它，所以这里只认产物该有的形状，
+ * 不回头读角色文件——拉一份档案不该变成拉一个仓库。
+ *
+ * @param {unknown} value
+ * @param {{ file?: string | null }} [options]
+ * @returns {{ ok: boolean, compiled: object | null, diagnostics: object[] }}
+ */
+export function validateCompiled(value, { file = null } = {}) {
+  const diagnostics = [];
+  const at = (relative) => (file === null ? relative : `${file} · ${relative}`);
+  const fail = () => ({ ok: false, compiled: null, diagnostics });
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    diagnostics.push({ severity: "error", code: "compiled-not-object", reason: "编译产物必须是一个对象", file });
+    return fail();
+  }
+  if (value.kind !== COMPILED_KIND) {
+    diagnostics.push({
+      severity: "error",
+      code: "compiled-kind",
+      reason: `判别键必须是 ${COMPILED_KIND}，实际是 ${JSON.stringify(value.kind ?? null)}`,
+      file,
+    });
+  }
+  const source = value.source;
+  if (source === null || typeof source !== "object") {
+    diagnostics.push({ severity: "error", code: "compiled-source", reason: "缺少 source", file });
+  } else {
+    for (const key of ["roster", "version"]) {
+      if (typeof source[key] !== "string" || source[key] === "") {
+        diagnostics.push({
+          severity: "error",
+          code: "compiled-source",
+          reason: `source.${key} 必须是非空字符串`,
+          file: at("source"),
+        });
+      }
+    }
+  }
+  const members = value.members;
+  if (!Array.isArray(members) || members.length === 0) {
+    diagnostics.push({ severity: "error", code: "compiled-members", reason: "members 必须是非空数组", file });
+  } else {
+    for (const [index, member] of members.entries()) {
+      const where = at(`members[${String(index)}]`);
+      if (member === null || typeof member !== "object") {
+        diagnostics.push({ severity: "error", code: "compiled-member", reason: "成员必须是对象", file: where });
+        continue;
+      }
+      if (typeof member.name !== "string" || member.name === "") {
+        diagnostics.push({ severity: "error", code: "compiled-member", reason: "成员缺少 name", file: where });
+      }
+      if (typeof member.executionPrompt !== "string" || member.executionPrompt.trim() === "") {
+        diagnostics.push({ severity: "error", code: "compiled-member", reason: "成员缺少 executionPrompt", file: where });
+      }
+    }
+  }
+  const ok = diagnostics.every((item) => item.severity !== "error");
+  return { ok, compiled: ok ? value : null, diagnostics };
+}
+
+/**
+ * 把编译产物摊回一份 v1 档案文档。
+ *
+ * 远端订阅只拿得到产物：产物里的人设已经是最终拼装结果，所以导入本地时写成 v1 内联档案，
+ * 不假装自己带着角色目录。想要角色分层，导入后跑一次 `migrate` 重写即可。
+ *
+ * @param {object} compiled
+ * @returns {object}
+ */
+export function flattenCompiledToRoster(compiled) {
+  const source = compiled.source ?? {};
+  const members = (compiled.members ?? []).map((member) => {
+    const flat = {
+      name: member.name,
+      role: member.role ?? "",
+      systemPrompt: member.executionPrompt,
+    };
+    if (member.title) flat.title = member.title;
+    if (member.description) flat.description = member.description;
+    if (member.provider) flat.provider = member.provider;
+    if (member.model) flat.model = member.model;
+    if (member.reasoningEffort) flat.reasoningEffort = member.reasoningEffort;
+    if (member.toolPolicy) flat.toolPolicy = member.toolPolicy;
+    return flat;
+  });
+  const roster = {
+    kind: ROSTER_KIND,
+    roster: source.roster,
+    version: source.version,
+    members,
+  };
+  if (source.title) roster.title = source.title;
+  if (source.description) roster.description = source.description;
+  if (compiled.captain) {
+    const captain = { name: String(compiled.captain.role ?? "").replace(/@[^@]*$/, "") };
+    if (compiled.captain.provider) captain.provider = compiled.captain.provider;
+    if (compiled.captain.model) captain.model = compiled.captain.model;
+    if (compiled.captain.reasoningEffort) captain.reasoningEffort = compiled.captain.reasoningEffort;
+    if (compiled.captain.persona) captain.personaPrefix = compiled.captain.persona;
+    roster.captain = captain;
+  }
+  return roster;
+}

package/lib/format.js

@@ -199,6 +199,7 @@ export const COLLECTION_FIELDS = [
   "ref",
   "path",
   "rosters",
+  "files",
   "tags",
   "license",
   "maintainers",

package/lib/remote.js

@@ -23,6 +23,8 @@ import fs from "node:fs";
 import nodePath from "node:path";
 import { gunzipSync } from "node:zlib";
 
+import { flattenCompiledToRoster, validateCompiled } from "./compile2.js";
+import { COMPILED_KIND, ROSTER2_KIND } from "./format-v2.js";
 import {
   COLLECTION_FIELDS,
   LIMITS,
@@ -486,6 +488,25 @@ export function validateRegistry(value, meta = {}) {
     }
     if (bad) return;
 
+    const files = {};
+    if (entry.files !== undefined) {
+      if (entry.files === null || typeof entry.files !== "object" || Array.isArray(entry.files)) {
+        diagnostics.push(diagnostic("warn", "collection-files", `${where}.files 必须是「档案 id → 仓库内相对路径」的对象`, file));
+      } else {
+        for (const [key, value] of Object.entries(entry.files)) {
+          if (!rosters.includes(key)) {
+            diagnostics.push(diagnostic("warn", "collection-files-unknown", `${where}.files 里的 ${key} 不在 rosters 名单里，已忽略`, file));
+            continue;
+          }
+          if (typeof value !== "string" || value.trim() === "" || !PATTERNS.relPath.test(value) || value.split("/").includes("..")) {
+            diagnostics.push(diagnostic("warn", "collection-files-path", `${where}.files.${key} 必须是仓库内相对路径`, file));
+            continue;
+          }
+          files[key] = value.trim();
+        }
+      }
+    }
+
     seen.add(id);
     collections.push({
       id,
@@ -495,6 +516,7 @@ export function validateRegistry(value, meta = {}) {
       ref,
       path: path.replace(/^\/+|\/+$/g, ""),
       rosters,
+      files,
       tags: Array.isArray(entry.tags) ? entry.tags.filter((tag) => typeof tag === "string") : [],
       license: typeof entry.license === "string" ? entry.license : "",
       maintainers: Array.isArray(entry.maintainers) ? entry.maintainers.filter((item) => typeof item === "string") : [],
@@ -526,8 +548,10 @@ export async function fetchCollection(collection, options = {}) {
   for (const rosterId of wanted) {
     let loaded = null;
     let lastError = "";
-    for (const fileName of ["roster.yaml", "roster.yml", "roster.json"]) {
-      const url = collectionFileUrl(collection, rosterId, fileName);
+    const listedPath = collection.files?.[rosterId] ?? null;
+    const candidateNames = listedPath === null ? ["roster.yaml", "roster.yml", "roster.json"] : [null];
+    for (const fileName of candidateNames) {
+      const url = listedPath === null ? collectionFileUrl(collection, rosterId, fileName) : collectionFileUrl(collection, rosterId, "");
       try {
         const response = await fetchImpl(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
         if (!response.ok) {
@@ -545,15 +569,37 @@ export async function fetchCollection(collection, options = {}) {
       continue;
     }
     const parsed = parseDocumentText(loaded.text, { file: loaded.url });
-    const checked = parsed.ok
-      ? validateRoster(parsed.value, { file: loaded.url, expectedId: rosterId })
-      : { ok: false, diagnostics: parsed.diagnostics };
+    if (parsed.ok && parsed.value !== null && typeof parsed.value === "object" && parsed.value.kind === ROSTER2_KIND) {
+      diagnostics.push(
+        diagnostic(
+          "warn",
+          "collection-roster-needs-roles",
+          `${collection.id}/${rosterId} 是 v2 组装，成员是角色引用，单个文件拉不到角色目录；索引应指向 dist/ 里的编译产物`,
+        ),
+      );
+      continue;
+    }
+    let checked;
+    if (parsed.ok && parsed.value !== null && typeof parsed.value === "object" && parsed.value.kind === COMPILED_KIND) {
+      const compiled = validateCompiled(parsed.value, { file: loaded.url });
+      if (!compiled.ok) {
+        diagnostics.push(...compiled.diagnostics);
+        continue;
+      }
+      checked = validateRoster(flattenCompiledToRoster(compiled.compiled), { file: loaded.url, expectedId: rosterId });
+      checked = { ...checked, format: "compiled" };
+    } else {
+      checked = parsed.ok
+        ? validateRoster(parsed.value, { file: loaded.url, expectedId: rosterId })
+        : { ok: false, diagnostics: parsed.diagnostics };
+    }
     if (!checked.ok) {
       diagnostics.push(...checked.diagnostics);
       continue;
     }
     rosters.push({
       ...checked.roster,
+      ...(checked.format === undefined ? {} : { format: checked.format }),
       origin: {
         kind: "remote",
         collection: collection.id,
@@ -569,10 +615,12 @@ export async function fetchCollection(collection, options = {}) {
   return { collection, rosters, diagnostics };
 }
 
-/** 拼一份档案的 raw 地址。 */
+/** 拼一份档案的 raw 地址（relativePath 由索引给出，或回退到 v1 的 `<id>/roster.<ext>`）。 */
 export function collectionFileUrl(collection, rosterId, fileName) {
   const repo = collection.repo.replace(/^github:/, "");
-  return `${GITHUB_RAW}/${repo}/${encodeURIComponent(collection.ref)}/${collection.path}/${rosterId}/${fileName}`;
+  const relative = collection.files?.[rosterId] ?? `${rosterId}/${fileName}`;
+  const base = collection.path === "" ? "" : `${collection.path}/`;
+  return `${GITHUB_RAW}/${repo}/${encodeURIComponent(collection.ref)}/${base}${relative}`;
 }
 
 /** 一次读多个源（串行：GitHub 未认证配额经不起并发烧）。 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stofone/dsh-agent-roster",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "多 Agent 团队的静态成员档案定义与校验层：档案库在面板里看得见、改得动，团队成员的人设、模型与工具边界固化成可校验、可版本化的文件，并在 dsh-agent-teams 创建成员时把档案桥接给运行时。",
   "type": "module",
   "main": "index.js",

package/schema/registry.v1.schema.json

@@ -5,32 +5,57 @@
   "description": "公共档案索引：登记若干 collection（仓库 + 目录 + 确有哪几份档案），供订阅与一键安装。权威校验实现是 lib/remote.js#validateRegistry；本文件供编辑器与外部工具提示，两者由 test/registry-schema.test.js 对齐。注意：运行时对未知字段只告警不判错，这里写成 additionalProperties:false 是为了让编辑器早点指出拼写错误。",
   "type": "object",
   "additionalProperties": false,
-  "required": ["kind", "collections"],
+  "required": [
+    "kind",
+    "collections"
+  ],
   "properties": {
     "$schema": {
       "type": "string",
       "description": "编辑器用的 schema 地址，插件不读它。"
     },
-    "kind": { "const": "dsh-agent-roster-registry/v1" },
-    "version": { "type": "integer", "minimum": 1 },
+    "kind": {
+      "const": "dsh-agent-roster-registry/v1"
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1
+    },
     "generatedAt": {
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$",
       "description": "上一次校验通过的时间，由 CI 或维护者盖章。"
     },
-    "generator": { "type": "string", "maxLength": 200 },
-    "source": { "type": "string", "maxLength": 200 },
+    "generator": {
+      "type": "string",
+      "maxLength": 200
+    },
+    "source": {
+      "type": "string",
+      "maxLength": 200
+    },
     "collections": {
       "type": "array",
       "maxItems": 500,
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["id", "repo"],
+        "required": [
+          "id",
+          "repo"
+        ],
         "properties": {
-          "id": { "$ref": "#/$defs/id" },
-          "title": { "type": "string", "maxLength": 120 },
-          "description": { "type": "string", "maxLength": 500 },
+          "id": {
+            "$ref": "#/$defs/id"
+          },
+          "title": {
+            "type": "string",
+            "maxLength": 120
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 500
+          },
           "repo": {
             "type": "string",
             "pattern": "^(?:github:)?[A-Za-z0-9][A-Za-z0-9_.-]{0,38}/[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$",
@@ -52,7 +77,9 @@
             "type": "array",
             "maxItems": 200,
             "description": "目录里确实存在的档案 id。索引不撒谎：不存在的 id 会被 registry sync 剔除。",
-            "items": { "$ref": "#/$defs/id" }
+            "items": {
+              "$ref": "#/$defs/id"
+            }
           },
           "tags": {
             "type": "array",
@@ -62,13 +89,34 @@
               "pattern": "^[a-z0-9][a-z0-9-]{0,31}$"
             }
           },
-          "license": { "type": "string", "maxLength": 120 },
+          "license": {
+            "type": "string",
+            "maxLength": 120
+          },
           "maintainers": {
             "type": "array",
             "maxItems": 16,
-            "items": { "type": "string", "minLength": 1, "maxLength": 120 }
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 120
+            }
           },
-          "homepage": { "type": "string", "maxLength": 200, "pattern": "^https?://\\S+$" }
+          "homepage": {
+            "type": "string",
+            "maxLength": 200,
+            "pattern": "^https?://\\S+$"
+          },
+          "files": {
+            "type": "object",
+            "description": "档案 id → 仓库内相对路径。v2 档案指向 dist/ 的编译产物（自包含），v1 可省略。",
+            "propertyNames": {
+              "$ref": "#/$defs/id"
+            },
+            "additionalProperties": {
+              "$ref": "#/$defs/relPath"
+            }
+          }
         }
       }
     }
@@ -78,6 +126,13 @@
       "type": "string",
       "pattern": "^[a-z0-9][a-z0-9-]{1,63}$",
       "description": "kebab-case 标识，与档案目录名同规则。"
+    },
+    "relPath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200,
+      "pattern": "^(?:[A-Za-z0-9._-]+/)*[A-Za-z0-9._-]+$",
+      "description": "仓库内相对路径，不含 ..、不以 / 开头。"
     }
   }
 }