@stofone/dsh-agent-roster 0.10.1 → 0.10.3

package/CHANGELOG.md

@@ -4,6 +4,40 @@
 
 ## [Unreleased]
 
+## [0.10.3] - 2026-11-03
+
+### Added
+
+- `migrate --from <dir>` and `--repo <owner/repo>`: a repository that publishes a collection keeps its
+  v1 rosters in `rosters/<id>/`, so the library root and the old files are not the same directory. The
+  migration now rewrites that file in place, adds `roles/` and `dist/` at the root, removes the stale
+  `roster.json`/`roster.yml` beside it (two spellings of one roster are two sources of truth), and does
+  **not** delete `rosters/<id>/` — that is where the new assembly lives.
+- A collection's `path` may be empty, meaning the repository root *is* the library. The three example
+  repositories (`agent-teams`, `metagpt-company`, `openmanus`) now use that shape: `roles/`, `rosters/`,
+  `dist/` at the root, `files` pointing at the compiled artifact.
+
+### Fixed
+
+- The `agent-teams`, `metagpt-company` and `openmanus` collections were still published as v1, so their
+  `roster.yaml` was fetched while a v2 world had already moved on; every entry now names its artifact.
+
+## [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
@@ -456,7 +490,11 @@
 - 工具返回值含 `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.3...main
+[0.10.3]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.10.2...v0.10.3
+[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

@@ -276,6 +276,18 @@ Migration keeps personas verbatim: a member's `systemPrompt` becomes the body of
 loose field and becomes a role file of its own — `<roster>-<captain>-captain` when its name collides
 with a member, because those are two different personas and silently merging them would lose one.
 
+If the v1 rosters live in a subdirectory (the usual case for a repository that publishes a
+collection), point the migration at the library root and tell it where the old files are:
+
+```bash
+node bin/cli.mjs migrate --dir . --from rosters --repo owner/repo --write
+```
+
+That layout rewrites `rosters/<id>/roster.yaml` in place, adds `roles/` and `dist/` at the repository
+root, and drops the stale `roster.json`/`roster.yml` next to it — two spellings of one roster are two
+sources of truth. The collection then uses `path: ""` (the repository root *is* the library) and a
+`files` map pointing at `dist/`, because an assembly only references roles and cannot be pulled alone.
+
 Role names carry the roster id prefix because v2 requires role names to be **unique per library**,
 and a library whose 21 rosters all call their captain `lead` cannot have 21 files with the same name.
 
@@ -383,6 +395,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`,
@@ -464,7 +480,7 @@ test/             unit tests
 
 Verified on this machine:
 
-- `npm test` — 286/286 passing (format, parse, validate, registry, paths, bridge, verify buckets, digests and provenance, roster diff, capability requirements and the capability gate, library organization, registry schema, lossless JSON, write plan/apply, all routes, panel snapshot and hints, dictionary consistency, tool contracts, client loader contract, library snapshot, config view, package manifest, declared fields and captain block, schema/constant alignment, the v2 role/roster/compiled layers and their schema alignment, v1→v2 migration, run records feeding the plan, remote registry and one-click install).
+- `npm test` — 293/293 passing (format, parse, validate, registry, paths, bridge, verify buckets, digests and provenance, roster diff, capability requirements and the capability gate, library organization, registry schema, lossless JSON, write plan/apply, all routes, panel snapshot and hints, dictionary consistency, tool contracts, client loader contract, library snapshot, config view, package manifest, declared fields and captain block, schema/constant alignment, the v2 role/roster/compiled layers and their schema alignment, v1→v2 migration, run records feeding the plan, remote registry and one-click install).
 - `npm run smoke` — `apply()` registers all six tools through a real `defineTool` from a DSH bundle; `roster_list` / `roster_show` / `roster_create` / `roster_verify` / `roster_diff` execute, every output survives `lossless` checks, `path` overrides are honored, effect disposal runs cleanly. The same command then loads `client.js` against a stubbed module table and asserts the three slot registrations, style injection and effect disposal.
 - CLI: `validate --dir examples` returns exit 0 over both example libraries.
 - Installed into a real profile with the plugin manager (`plugin_manager install_bundle` against this directory → `link:` dependency + bundle entry); the profile re-reads the linked files on restart.

package/README.zh.md

@@ -269,6 +269,16 @@ node bin/cli.mjs migrate --dir examples --write    # 原地重写：roles/ + ros
 
 迁移逐字保留人设：成员的 `systemPrompt` 原文成为 `roles/<档案>-<成员>/AGENT.md` 的正文，成员本身变成引用。队长不再是一个散字段，而是自己的角色文件——与成员同名时得到 `-captain` 后缀，因为那是两份人设，悄悄合并会丢掉一份。
 
+如果 v1 的档案在子目录里（把仓库当 collection 发布的常见形态），把 `--dir` 指到库根、用 `--from` 指旧目录：
+
+```bash
+node bin/cli.mjs migrate --dir . --from rosters --repo owner/repo --write
+```
+
+这种布局会就地重写 `rosters/<id>/roster.yaml`，在仓库根上补 `roles/` 与 `dist/`，并删掉并排的旧
+`roster.json`/`roster.yml`——同一份档案两种写法就是两个真源。之后 collection 用 `path: ""`（仓库根就是库），
+再用 `files` 指向 `dist/`：组装只引用角色，单独拉一个文件拉不到角色目录。
+
 角色名带档案 id 前缀，是因为 v2 要求同库角色名唯一：一座库里 21 套组装都叫自己的队长 `lead`，不可能有 21 个同名文件。
 
 ### 把失败的一轮喂回施工图
@@ -364,6 +374,9 @@ node bin/cli.mjs compile --roster examples-orchestration/rosters/core-review \
   冲突要你自己决定：要么在编辑器里合并，要么再点一次「拉取到本机」并在请求里带 `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` 会校验索引与仓库真实文件是否对得上。
 
@@ -441,7 +454,7 @@ test/             单测
 
 本机已验证：
 
-- `npm test` —— 286/286 通过（格式、解析、校验、扫描、路径、桥接、核对四桶、摘要与溯源、档案差异、能力要求与能力闸门、档案库组织、索引 schema、无损 JSON、写入计划与执行、六条路由、快照与提示、两本词典一致、工具契约、客户端加载器契约、包清单、配置视图、样式 token 约束、声明层字段与队长段、schema 与常量对齐、v2 角色/组装/编译三层及其 schema 对齐、v1→v2 迁移、执行回执并入施工图）。
+- `npm test` —— 293/293 通过（格式、解析、校验、扫描、路径、桥接、核对四桶、摘要与溯源、档案差异、能力要求与能力闸门、档案库组织、索引 schema、无损 JSON、写入计划与执行、六条路由、快照与提示、两本词典一致、工具契约、客户端加载器契约、包清单、配置视图、样式 token 约束、声明层字段与队长段、schema 与常量对齐、v2 角色/组装/编译三层及其 schema 对齐、v1→v2 迁移、执行回执并入施工图）。
 - `npm run smoke` —— 用真实 DSH bundle 的 `defineTool` 注册六个工具，逐个调用：输出全部通过无损校验、`path` 覆盖生效、释放干净；同一条命令随后用桩模块表加载 `client.js`，断言三处槽位注册、样式只注入一次、effect 可回收。
 - CLI：`validate --dir examples` 对两座示例库退出码 0。
 - 用插件管理器真的装进了本机 profile（`plugin_manager install_bundle` 指向本仓库 → `link:` 依赖 + bundle 条目），重启后按链接读取本仓库文件。

package/bin/cli.mjs

@@ -13,6 +13,7 @@
  *   dsh-agent-roster registry sync     --file index/registry.json [--write]
  *   dsh-agent-roster compile --roster rosters/money-lab [--roles roles] [--run run.json] [--write] [--json]
  *   dsh-agent-roster migrate --dir examples [--write] [--json]
+ *   dsh-agent-roster migrate --dir . --from rosters --repo owner/repo --write
  */
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import nodePath from "node:path";
@@ -26,6 +27,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"));
 
@@ -36,7 +38,8 @@ const USAGE = `用法：
   dsh-agent-roster registry fetch --file <路径>      逐条确认 collection 真的能取到
   dsh-agent-roster registry sync --file <路径>       按仓库实际内容重算 roster 列表
   dsh-agent-roster compile --roster <目录>            把 v2 组装编译成自包含产物（不写盘）
-  dsh-agent-roster migrate --dir <目录>               把 v1 档案原地迁成 v2（roles/ + rosters/ + dist/）
+  dsh-agent-roster migrate --dir <目录> [--from <子目录>] [--repo <owner/repo>] [--write]
+                                                      把 v1 档案原地迁成 v2（roles/ + rosters/ + dist/）
   dsh-agent-roster --version         输出版本号
 
 选项：
@@ -46,6 +49,8 @@ const USAGE = `用法：
   --local-only              fetch 只验本仓库登记的 collection（CI 里用，不依赖外网）
   --write                   sync 把重算结果写回文件
   --roster <path>           v2 组装目录（compile 用）
+  --from <path>             v1 档案所在目录（migrate 用；缺省与 --dir 相同，用于仓库根 + rosters/ 布局）
+  --repo <owner/repo>       写进 dist 产物的仓库坐标（migrate 用；缺省取本仓 remote）
   --run <path>              执行回执（compile 用；把上一轮失败并入重试卡）
   --roles <path>            角色库目录（compile 用；缺省按 rosters/<id> 推同级的 roles/）
   --json                    以 JSON 输出（validate / list / compile 都支持）
@@ -67,6 +72,8 @@ function parseArgs(argv) {
     roster: null,
     roles: null,
     run: null,
+    from: null,
+    repo: null,
   };
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
@@ -90,6 +97,16 @@ function parseArgs(argv) {
       if (value === undefined) throw new UsageError("--roster 需要一个路径");
       options.roster = value;
       index += 1;
+    } else if (arg === "--from") {
+      const value = argv[index + 1];
+      if (value === undefined) throw new UsageError("--from 需要一个路径");
+      options.from = value;
+      index += 1;
+    } else if (arg === "--repo") {
+      const value = argv[index + 1];
+      if (value === undefined) throw new UsageError("--repo 需要 owner/name");
+      options.repo = value;
+      index += 1;
     } else if (arg === "--run") {
       const value = argv[index + 1];
       if (value === undefined) throw new UsageError("--run 需要一个路径");
@@ -442,6 +459,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`);
@@ -508,7 +536,13 @@ function runMigrate(options) {
   const reports = [];
   for (const dir of dirs) {
     const rootDir = resolveDirSpec(dir, process.cwd());
-    const report = migrateLibrary(rootDir, { write: options.write, knownToolPolicies, source: { repo: ownRepo(), ref: "main" } });
+    const fromDir = options.from === null ? rootDir : resolveDirSpec(options.from, process.cwd());
+    const report = migrateLibrary(rootDir, {
+      write: options.write,
+      knownToolPolicies,
+      source: { repo: options.repo ?? ownRepo(), ref: "main" },
+      fromDir,
+    });
     reports.push({ dir, rootDir, report });
     if (report.diagnostics.some((item) => item.severity === "error")) rc = 1;
     if (options.json) continue;

package/docs/roster-v2.md

@@ -197,6 +197,8 @@ gates:
 ## 8. 迁移
 
 - `roster migrate --dir <库> [--write]` 读 v1 档案，把 `systemPrompt` 拆成角色（`roles/<member>/AGENT.md`）+ 组装（成员改为引用），原地重写并生成 `dist/`。默认只出计划，`--write` 才落盘——这是唯一会删旧目录的命令。
+- `roster migrate --dir <库根> --from <旧目录> [--repo <owner/repo>] [--write]`：v1 档案放在子目录（`rosters/<id>/roster.yaml`，即"仓库本身就是库、只是档案隔了一层"）时用这条。它就地重写 `rosters/<id>/roster.yaml`、在库根补 `roles/` 与 `dist/`、删掉并排的 `roster.json`/`roster.yml`（同义文件=第二真源），**不删** `rosters/<id>/` —— 那个目录就是新档案的落脚处。`--repo` 写进产物的 `source.repo`，避免发布仓的产物署错名。
+- **collection 的 `path` 可以是空字符串**，表示仓库根就是库：`roles/`、`rosters/`、`dist/` 直接躺在根上。配合 `files` 映射指向 `dist/<id>-<ver>.json`。
 - **角色名带档案 id 前缀**（`core-review-reviewer`）：v2 要求同库角色名唯一，而真实档案库里几十套组装都可能叫 `lead`。队长与成员同名时，队长得到 `-captain` 后缀，不与人设合并。
 - `maintainers` 用 `handle` 模式（允许大写与点），不复用档案 id 的小写短横线规则——维护者是账号，不是标识符。
 - v1 冻结：新字段只进 v2，不再回填 v1。
@@ -212,9 +214,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-03T06:14:00.000Z",
   "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",
@@ -78,7 +105,7 @@
       "description": "把 wshobson/agents 的 agent-teams 插件（4.2 万星，MIT）迁成档案：队长、实现者、审查者、调试者，保留上游工具边界。",
       "repo": "github:dsh-agent-roster/agent-teams",
       "ref": "main",
-      "path": "rosters",
+      "path": "",
       "rosters": [
         "agent-teams"
       ],
@@ -92,7 +119,10 @@
       "maintainers": [
         "STofone"
       ],
-      "homepage": "https://github.com/dsh-agent-roster/agent-teams"
+      "homepage": "https://github.com/dsh-agent-roster/agent-teams",
+      "files": {
+        "agent-teams": "dist/agent-teams-1.0.0.json"
+      }
     },
     {
       "id": "metagpt-company",
@@ -100,7 +130,7 @@
       "description": "MetaGPT（5 万星+，MIT）的软件公司角色：产品经理、架构师、项目经理、工程师，字段取自上游 Role 的 profile/goal/constraints。",
       "repo": "github:dsh-agent-roster/metagpt-company",
       "ref": "main",
-      "path": "rosters",
+      "path": "",
       "rosters": [
         "metagpt-company"
       ],
@@ -113,7 +143,10 @@
       "maintainers": [
         "STofone"
       ],
-      "homepage": "https://github.com/dsh-agent-roster/metagpt-company"
+      "homepage": "https://github.com/dsh-agent-roster/metagpt-company",
+      "files": {
+        "metagpt-company": "dist/metagpt-company-1.0.0.json"
+      }
     },
     {
       "id": "openmanus",
@@ -121,7 +154,7 @@
       "description": "OpenManus（5.8 万星，MIT）的三个代理提示词：规划、编码、浏览器，systemPrompt 保留上游原文。",
       "repo": "github:dsh-agent-roster/openmanus",
       "ref": "main",
-      "path": "rosters",
+      "path": "",
       "rosters": [
         "openmanus"
       ],
@@ -135,7 +168,10 @@
       "maintainers": [
         "STofone"
       ],
-      "homepage": "https://github.com/dsh-agent-roster/openmanus"
+      "homepage": "https://github.com/dsh-agent-roster/openmanus",
+      "files": {
+        "openmanus": "dist/openmanus-1.0.0.json"
+      }
     }
   ]
 }

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/migrate.js

@@ -206,11 +206,11 @@ function loadCapabilitiesOf(dir) {
  *
  * 不写盘时只返回计划；`write: true` 才落盘、编译、写出 `dist/`，并在最后删掉旧的 `<id>/` 目录。
  */
-export function migrateLibrary(rootDir, { write = false, knownToolPolicies = null, source = {} } = {}) {
+export function migrateLibrary(rootDir, { write = false, knownToolPolicies = null, source = {}, fromDir = rootDir } = {}) {
   const report = { rootDir, write, entries: [], diagnostics: [], written: [], removed: [], compiled: [] };
   let children = [];
   try {
-    children = readdirSync(rootDir, { withFileTypes: true });
+    children = readdirSync(fromDir, { withFileTypes: true });
   } catch (error) {
     report.diagnostics.push({ severity: "error", code: "unreadable-dir", path: "", file: null, reason: `档案库不可读：${error?.message ?? error}` });
     return report;
@@ -220,7 +220,7 @@ export function migrateLibrary(rootDir, { write = false, knownToolPolicies = nul
   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);
+    const dir = nodePath.join(fromDir, child.name);
     // v1 的档案文件名可以是 yaml / yml / json——迁移只认内容，不认扩展名。
     if (!MEMBER_FILE_NAMES.some((name) => existsSync(nodePath.join(dir, name)))) continue;
     const loaded = loadRosterAt(dir, { knownToolPolicies });
@@ -269,7 +269,7 @@ export function migrateLibrary(rootDir, { write = false, knownToolPolicies = nul
       report.written.push(file.path);
     }
     for (const name of CAPABILITIES_FILE_NAMES) {
-      const source = nodePath.join(rootDir, entry.id, name);
+      const source = nodePath.join(fromDir, entry.id, name);
       if (!existsSync(source)) continue;
       const relative = nodePath.join(ROSTERS_DIR, entry.id, name);
       const target = nodePath.join(rootDir, relative);
@@ -278,6 +278,13 @@ export function migrateLibrary(rootDir, { write = false, knownToolPolicies = nul
       report.written.push(relative);
       break;
     }
+    // 就地迁移时旧的 roster.json / roster.yml 会和新的 roster.yaml 并排躺着：
+    // 两份同义文件就是两个真源，删掉非 .yaml 的旧件。
+    for (const name of MEMBER_FILE_NAMES) {
+      if (name === "roster.yaml") continue;
+      const stale = nodePath.join(rootDir, ROSTERS_DIR, entry.id, name);
+      if (existsSync(stale)) rmSync(stale, { force: true });
+    }
   }
 
   const scanned = scanRoles(nodePath.join(rootDir, ROLES_DIR), { knownToolPolicies });
@@ -316,7 +323,9 @@ export function migrateLibrary(rootDir, { write = false, knownToolPolicies = nul
   }
 
   for (const entry of report.entries) {
-    const legacy = nodePath.join(rootDir, entry.id);
+    const legacy = nodePath.join(fromDir, entry.id);
+    // 仓库根 + rosters/ 的布局里，v1 的 rosters/<id>/ 正是 v2 新档案落脚处 —— 不能删。
+    if (nodePath.resolve(legacy) === nodePath.resolve(nodePath.join(rootDir, ROSTERS_DIR, entry.id))) continue;
     if (!existsSync(legacy) || !statSync(legacy).isDirectory()) continue;
     // 只删「迁移前的那份目录」：v2 布局里档案在 rosters/ 下，root 上不该再有同名目录。
     rmSync(legacy, { recursive: true, force: true });

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,
@@ -466,8 +468,9 @@ export function validateRegistry(value, meta = {}) {
       bad = true;
     }
     const path = entry.path === undefined ? "rosters" : String(entry.path);
-    if (!PATTERNS.relPath.test(path)) {
-      diagnostics.push(diagnostic("error", "collection-path", `${where}.path 必须是仓库内相对目录`, file));
+    // 空 path 表示「仓库根就是这座库」：v2 的 roles/ + rosters/ + dist/ 直接躺在仓库根上。
+    if (path !== "" && !PATTERNS.relPath.test(path)) {
+      diagnostics.push(diagnostic("error", "collection-path", `${where}.path 必须是仓库内相对目录（空字符串表示仓库根）`, file));
       bad = true;
     }
 
@@ -486,6 +489,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 +517,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 +549,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 +570,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 +616,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.1",
+  "version": "0.10.3",
   "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}$",
@@ -46,13 +71,15 @@
             "type": "string",
             "pattern": "^(?:/)?(?:[A-Za-z0-9._-]+/)*[A-Za-z0-9._-]*$",
             "default": "rosters",
-            "description": "仓库内存放档案的目录。"
+            "description": "仓库内存放档案的目录；空字符串表示仓库根（v2 布局的 roles/ + rosters/ + dist/ 就在根上）。"
           },
           "rosters": {
             "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": "仓库内相对路径，不含 ..、不以 / 开头。"
     }
   }
 }