@stofone/dsh-agent-roster 0.13.0 → 1.0.0

package/CHANGELOG.md

@@ -4,6 +4,57 @@
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-11-03
+
+### A space is the thing a repository holds
+
+Until now a pulled roster was a flattened copy: whatever the source repository looked like, it arrived as
+`<id>/roster.yaml` and the editor had no idea which file upstream it corresponded to. That is fine for "I
+only need this one", and wrong for every monorepo — which is what this project's own libraries have been
+since 0.10.0.
+
+`space.yaml` (`kind: dsh-agent-roster/space@1`) is the level that was missing. It declares what a
+directory in a repository *is*: which rosters it holds, whether the layout is `flat` (`<id>/roster.yaml`)
+or `monorepo` (`roles/` + `rosters/` + `dist/`), and — only on local copies — where it came from
+(`origin: {repo, ref, path}`). Layout is now part of the format instead of something the puller guesses.
+Clone a space and the local tree is the repository's tree: edit `rosters/<id>/roster.yaml` and you are
+editing the file upstream.
+
+### Changed (breaking)
+
+- `organization.yaml` is replaced by `space.yaml`. The old file, its `kind`
+  (`dsh-agent-roster-organization/v1`), its schema and its diagnostics codes (`organization-*`) are gone;
+  the equivalents are `space.yaml`, `dsh-agent-roster/space@1` and `space-*`. Migration: rename the file,
+  change `kind`, rename the `organization:` key to `space:`, and add `layout: flat|monorepo`.
+- A space file inside a repository may not declare `origin`; the validator rejects it. `origin` describes
+  a local copy, and a repository claiming a source is a second copy of the truth.
+
+### Added
+
+- `lib/space.js` + `schema/space.v1.schema.json`: declaration, cross-check (missing = error, undeclared =
+  warn, archived = info) and strict validation, with `layout` and `origin`.
+- `lib/clone.js` and `dsh-agent-roster clone --repo <owner/repo> [--path] [--ref] [--space]`: pull a whole
+  space with its layout intact — rosters, the roles they reference, and each role's `parts/`. The written
+  `space.yaml` is the source's cover plus `origin`.
+- `POST /plugins/dsh-agent-roster/install-space` and a "Pull whole space" button on every source group in
+  the Library tab; pulled files land in `<library>/<space>/` with the repository's paths.
+- The Library tab marks rosters that are already installed locally, so "everything is pulled" and "what
+  do I actually have" stop looking the same.
+- `examples/`, `examples-orchestration/` and `orgs/agent-roster-collective/` each ship a `space.yaml`.
+
+
+## [0.13.1] - 2026-11-03
+
+### The local rosters are the front page
+
+0.13.0 opened on the library tab. That got the metaphor right and the priority wrong: the rosters you
+already manage are what you come back to every day, and they were one tab away. The panel now lands on
+**Rosters** — local, searchable, with its tag pool — and the library marketplace is the second tab.
+
+- Tab order is `Rosters, Library, Teams, Sources, Health`; the default tab is `rosters` again.
+- Nothing moved between the two: both read the same snapshot, both filter by tag, and the tag pools stay
+  independent (local-only vs everything in view) so neither one silently changes the other's counts.
+
 ## [0.13.0] - 2026-11-03
 
 ### A tab that behaves like a marketplace, not a filter on a list
@@ -615,6 +666,8 @@ point is now one search field above the tabs.
   且所有返回值先过 `lib/json.js#lossless`。
 
 [Unreleased]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.12.0...main
+[0.13.1]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.13.0...v0.13.1
+[1.0.0]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.13.1...v1.0.0
 [0.13.0]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.11.1...v0.12.0
 [0.11.1]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.11.0...v0.11.1

package/README.md

@@ -187,13 +187,14 @@ Behaviour: under `onMissing: refuse` (default) `roster_create` emits **no** `age
 
 The sibling file has its own JSON Schema: [`schema/capabilities.v1.schema.json`](./schema/capabilities.v1.schema.json), kept aligned with `lib/capabilities.js` by `test/capabilities.test.js`.
 
-## Library organization (`organization.yaml`)
+## Spaces (`space.yaml`)
 
 A roster answers *who the members are*; it cannot answer **which rosters belong together, which one is production and which is retired**. When a library holds twenty archives from different sources, the directory listing stops being an index. An optional file at the **library root** declares that, and nothing else:
 
 ```yaml
-kind: dsh-agent-roster-organization/v1
-organization: agent-roster-collective   # must equal the directory name
+kind: dsh-agent-roster/space@1
+space: agent-roster-collective   # must equal the directory name
+layout: monorepo                 # flat = <id>/roster.yaml; monorepo = roles/ + rosters/ + dist/
 title: 团队档案合集
 maintainers: [STofone]
 rosters:
@@ -207,13 +208,13 @@ The declaration is mechanically checked against disk, and the three outcomes are
 
 | Situation | Code | Severity | Why |
 |---|---|---|---|
-| declared, directory missing | `organization-roster-missing` | **error** | the organization page is lying — worse than no page |
-| directory present, not declared | `organization-roster-undeclared` | warn | someone added a roster around the index; it still loads |
-| declared `archived`, directory still there | `organization-roster-archived` | info | archiving is a statement, not a delete |
+| declared, directory missing | `space-roster-missing` | **error** | the organization page is lying — worse than no page |
+| directory present, not declared | `space-roster-undeclared` | warn | someone added a roster around the index; it still loads |
+| declared `archived`, directory still there | `space-roster-archived` | info | archiving is a statement, not a delete |
 
-`organization` must equal the directory name, exactly like `roster` does: position is identity, and two ids for one library would make every diagnostic ambiguous. Unknown keys are rejected — a field nobody can check is another way to look green.
+`space` must equal the directory name, exactly like `roster` does: position is identity, and two ids for one library would make every diagnostic ambiguous. Unknown keys are rejected — a field nobody can check is another way to look green.
 
-This file creates nothing. It does not write `team.json`, does not create members, and never reaches `agent_teams_add_member`. Its JSON Schema is [`schema/organization.v1.schema.json`](./schema/organization.v1.schema.json), kept aligned with `lib/organization.js` by `test/organization.test.js`.
+This file creates nothing. It does not write `team.json`, does not create members, and never reaches `agent_teams_add_member`. Its JSON Schema is [`schema/space.v1.schema.json`](./schema/space.v1.schema.json), kept aligned with `lib/organization.js` by `test/space.test.js`.
 
 **A worked example ships in this repository:** [`orgs/agent-roster-collective/`](./orgs/agent-roster-collective/) holds 21 rosters (63 members) covering API review, incident response, data quality, database migration, localization, security audit, performance, frontend, docs, release, support triage, recruiting, market research, finance reconciliation, contract review, content ops, regression testing, model evaluation, SRE on-call, literature review and product discovery. Every roster is a three-person team with a captain, and each was written for this repository (no upstream text is copied). Validate it with:
 
@@ -308,8 +309,9 @@ turns into decoration.
 
 ## The library tab: find by capability, not by source
 
-The panel opens on **Library**, which is meant to read like a plugin marketplace: one search field, one row
-of tags, and one list that spans this machine and every subscribed source.
+The panel opens on **Rosters** — the local ones: what you work with every day, its tags and members, ready
+to filter or edit. The second tab is the **Library**, meant to read like a plugin marketplace: one search
+field, one row of tags, and one list that spans this machine and every subscribed source.
 
 ```
 要找什么能力？例：数据质量、发版、代码评审
@@ -509,7 +511,7 @@ 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
 examples-orchestration/  a v2 library with orchestration, gates and a construction plan
-orgs/             a worked example library with its own organization.yaml (21 rosters)
+orgs/             a worked example library with its own space.yaml (21 rosters)
 test/             unit tests
 ```
 
@@ -517,7 +519,7 @@ test/             unit tests
 
 Verified on this machine:
 
-- `npm test` — 308/308 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` — 313/313 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

@@ -183,13 +183,14 @@ notes: 建队前先确认成员会话可用。
 
 兄弟文件有自己的 JSON Schema：[`schema/capabilities.v1.schema.json`](./schema/capabilities.v1.schema.json)，由 `test/capabilities.test.js` 钉住与 `lib/capabilities.js` 一致。
 
-## 档案库组织（`organization.yaml`）
+## 档案空间（`space.yaml`）
 
 档案回答的是**成员是谁**，回答不了**哪几份档案属于同一套、哪份是生产、哪份已退役**。一座库放二十份来自不同来源的档案时，目录列表就不再是索引。库**根目录**上一个可选文件只声明这件事：
 
 ```yaml
-kind: dsh-agent-roster-organization/v1
-organization: agent-roster-collective   # 必须等于目录名
+kind: dsh-agent-roster/space@1
+space: agent-roster-collective   # 必须等于目录名
+layout: monorepo                 # flat = <id>/roster.yaml；monorepo = roles/ + rosters/ + dist/
 title: 团队档案合集
 maintainers: [STofone]
 rosters:
@@ -203,13 +204,26 @@ rosters:
 
 | 情况 | 代码 | 严重度 | 理由 |
 |---|---|---|---|
-| 声明了，目录不在 | `organization-roster-missing` | **error** | 组织页在撒谎，比没有组织页更糟 |
-| 目录在，没登记 | `organization-roster-undeclared` | warn | 有人绕过索引加了档案，但它仍会被加载 |
-| 声明 `archived`，目录还在 | `organization-roster-archived` | info | 归档是声明，不是删除 |
+| 声明了，目录不在 | `space-roster-missing` | **error** | 组织页在撒谎，比没有组织页更糟 |
+| 目录在，没登记 | `space-roster-undeclared` | warn | 有人绕过索引加了档案，但它仍会被加载 |
+| 声明 `archived`，目录还在 | `space-roster-archived` | info | 归档是声明，不是删除 |
 
-`organization` 必须等于目录名，和 `roster` 同一条规则：位置即身份，一座库两个 id 会让所有诊断都变得没法定位。未知键一律拒收——没人核得了的字段，只是换一种方式发绿。
+`space` 必须等于目录名，和 `roster` 同一条规则：位置即身份，一座库两个 id 会让所有诊断都变得没法定位。未知键一律拒收——没人核得了的字段，只是换一种方式发绿。
 
-这份文件什么都不创建：不写 `team.json`、不建成员，也永远不会进入 `agent_teams_add_member` 参数。它的 JSON Schema 在 [`schema/organization.v1.schema.json`](./schema/organization.v1.schema.json)，由 `test/organization.test.js` 钉住与 `lib/organization.js` 一致。
+这份文件什么都不创建：不写 `team.json`、不建成员，也永远不会进入 `agent_teams_add_member` 参数。
+
+**它同时固定了布局。** `layout: flat` 是 `<id>/roster.yaml`（v1 时代的一仓多档案）；`layout: monorepo` 是 `roles/<role>/AGENT.md` + `rosters/<id>/roster.yaml` + `dist/`。布局进了格式，编辑器才知道该改哪个文件——不再是"拉下来摊平、改的和源文件没关系"。
+
+**本地副本靠 `origin` 认祖归宗。** 从远端拉下来的空间会在 `space.yaml` 里多一段 `origin: {repo, ref, path}`，其余字段原样保留；仓库里的空间文件**不许**写 `origin`（源就是这个仓库本身，再写一遍就是第二真源），校验器会拒收。
+
+拉一整座空间、并且保留原布局（拉完就能改，改的就是源仓库里那个文件）：
+
+```bash
+dsh-agent-roster clone --repo dsh-agent-roster/agent-teams --space agent-teams
+```
+
+面板「档案库」里每组来源都有一个「拉取整个空间」按钮，等价于这条命令；单份档案的「拉取」仍然只摊平那一份（适合"我只要这一份、不打算往回改"）。
+它的 JSON Schema 在 [`schema/space.v1.schema.json`](./schema/space.v1.schema.json)，由 `test/space.test.js` 钉住与 `lib/space.js` 一致。
 
 **仓内带了一个可跑的示例**：[`orgs/agent-roster-collective/`](./orgs/agent-roster-collective/) 里有 21 份档案（63 名成员），覆盖接口评审、事故响应、数据质量、数据库迁移、本地化、安全审计、性能、前端、文档、发布、客服分诊、招聘、市场研究、财务对账、合同审阅、内容运营、回归测试、模型评测、SRE 值守、文献综述与产品发现。每份都是"队长 + 两名专家"的三人组，全部为本项目自撰（未复制任何上游文本）。校验方式：
 
@@ -294,7 +308,8 @@ node bin/cli.mjs compile --roster examples-orchestration/rosters/core-review \
 
 ## 档案库：按能力找，而不是按来源翻
 
-面板的第一个页签是**档案库**，定位接近一个插件市场：一个搜索框、一排标签、一份横跨本机与所有订阅来源的清单。
+面板的**首屏是本机档案**（第一个页签）：你每天打交道的那些档案、它们的标签与成员，进来就能看见、能筛选、能改。
+第二个页签是**档案库**，定位接近一个插件市场：一个搜索框、一排标签、一份横跨本机与所有订阅来源的清单。
 
 ```
 要找什么能力？例：数据质量、发版、代码评审
@@ -373,8 +388,8 @@ node bin/cli.mjs compile --roster examples-orchestration/rosters/core-review \
 
 | 页签 | 能做什么 |
 |---|---|
+| 档案 | 浏览每个工作区 × 每座档案库，展开成员；**新建 / 编辑 / 复制 / 删除 / 导入 / 导出**档案。编辑器有表单与源码两种模式（源码就是文件原文）；写之前由宿主校验，覆盖已有文件会留一份 `.bak`；顶上有搜索框与标签池 |
 | 档案库 | 按能力找档案：搜索（横跨本机与订阅来源，命中给出处）、标签筛选、按来源聚合或平铺，行内直接打开或拉取 |
-| 档案 | 浏览每个工作区 × 每座档案库，展开成员；**新建 / 编辑 / 复制 / 删除 / 导入 / 导出**档案。编辑器有表单与源码两种模式（源码就是文件原文）；写之前由宿主校验，覆盖已有文件会留一份 `.bak` |
 | 团队 | 读一个配置好的状态目录（默认 `.agent-teams`），列出运行时真正建出来的每个团队：档案、成员档案与模型路由、每个持久化成员是否真的与其档案一致，以及该团队的任务 |
 | 档案源 | 列出订阅的公共 registry 目录，每个 collection 一个「拉取到本机」按钮；可展开先看里面有哪些档案 |
 | 体检 | 把「配置有没有指错」集中一处：目录解析到了哪、状态目录在不在、有多少声明未被确认，以及该改哪个设置 |
@@ -486,7 +501,7 @@ test/             单测
 
 本机已验证：
 
-- `npm test` —— 308/308 通过（格式、解析、校验、扫描、路径、桥接、核对四桶、摘要与溯源、档案差异、能力要求与能力闸门、档案库组织、索引 schema、无损 JSON、写入计划与执行、六条路由、快照与提示、两本词典一致、工具契约、客户端加载器契约、包清单、配置视图、样式 token 约束、声明层字段与队长段、schema 与常量对齐、v2 角色/组装/编译三层及其 schema 对齐、v1→v2 迁移、执行回执并入施工图）。
+- `npm test` —— 313/313 通过（格式、解析、校验、扫描、路径、桥接、核对四桶、摘要与溯源、档案差异、能力要求与能力闸门、档案库组织、索引 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

@@ -15,10 +15,12 @@
  *   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 { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import nodePath from "node:path";
 
 import { resolveDirSpec } from "../lib/home.js";
+import { globalRosterRoot } from "../lib/home.js";
+import { cloneSpace } from "../lib/clone.js";
 import { scanRosterLibrary } from "../lib/registry.js";
 import { renderRosterList } from "../lib/render.js";
 import { REGISTRY_KIND } from "../lib/format.js";
@@ -40,6 +42,8 @@ const USAGE = `用法：
   dsh-agent-roster compile --roster <目录>            把 v2 组装编译成自包含产物（不写盘）
   dsh-agent-roster migrate --dir <目录> [--from <子目录>] [--repo <owner/repo>] [--write]
                                                       把 v1 档案原地迁成 v2（roles/ + rosters/ + dist/）
+  dsh-agent-roster clone --repo <owner/repo> [--ref <分支>] [--path <子目录>] [--space <id>] [--dir <目录>]
+                                                      把一个远端空间按原布局拉成本地副本（可编辑）
   dsh-agent-roster --version         输出版本号
 
 选项：
@@ -50,7 +54,10 @@ const USAGE = `用法：
   --write                   sync 把重算结果写回文件
   --roster <path>           v2 组装目录（compile 用）
   --from <path>             v1 档案所在目录（migrate 用；缺省与 --dir 相同，用于仓库根 + rosters/ 布局）
-  --repo <owner/repo>       写进 dist 产物的仓库坐标（migrate 用；缺省取本仓 remote）
+  --repo <owner/repo>       写进 dist 产物的仓库坐标（migrate 用）；clone 的源仓库
+  --ref <branch|tag>        clone 的分支/tag（缺省 main）
+  --path <subdir>           clone 的仓库内子目录（缺省仓库根）
+  --space <id>              clone 落到本地后的空间 id（缺省取仓库名）
   --run <path>              执行回执（compile 用；把上一轮失败并入重试卡）
   --roles <path>            角色库目录（compile 用；缺省按 rosters/<id> 推同级的 roles/）
   --json                    以 JSON 输出（validate / list / compile 都支持）
@@ -73,6 +80,9 @@ function parseArgs(argv) {
     roles: null,
     run: null,
     from: null,
+    ref: null,
+    path: null,
+    space: null,
     repo: null,
   };
   for (let index = 0; index < argv.length; index += 1) {
@@ -112,6 +122,21 @@ function parseArgs(argv) {
       if (value === undefined) throw new UsageError("--run 需要一个路径");
       options.run = value;
       index += 1;
+    } else if (arg === "--ref") {
+      const value = argv[index + 1];
+      if (value === undefined) throw new UsageError("--ref 需要一个分支名");
+      options.ref = value;
+      index += 1;
+    } else if (arg === "--path") {
+      const value = argv[index + 1];
+      if (value === undefined) throw new UsageError("--path 需要一个相对目录");
+      options.path = value;
+      index += 1;
+    } else if (arg === "--space") {
+      const value = argv[index + 1];
+      if (value === undefined) throw new UsageError("--space 需要一个 id");
+      options.space = value;
+      index += 1;
     } else if (arg === "--roles") {
       const value = argv[index + 1];
       if (value === undefined) throw new UsageError("--roles 需要一个路径");
@@ -159,6 +184,7 @@ async function main(argv) {
     return 0;
   }
   if (options.command === "compile") return runCompile(options);
+  if (options.command === "clone") return runClone(options);
   if (options.command === "migrate") return runMigrate(options);
   if (options.command === "registry") {
     if (options.file === null) {
@@ -195,8 +221,8 @@ async function main(argv) {
             rootDir: report.rootDir,
             missing: report.scan.missing,
             stats: report.scan.stats,
-            organization: report.scan.organization,
-            organizationCheck: report.scan.organizationCheck,
+            space: report.scan.space,
+            spaceCheck: report.scan.spaceCheck,
             rosters: report.scan.rosters.map((roster) => ({ id: roster.id, file: roster.file })),
             diagnostics: report.scan.diagnostics,
           })),
@@ -212,11 +238,11 @@ async function main(argv) {
         process.stdout.write(`${renderRosterList(report.scan)}\n`);
       } else {
         const { stats } = report.scan;
-        const organization = report.scan.organization ?? null;
-        if (organization !== null) {
-          const check = report.scan.organizationCheck;
+        const space = report.scan.space ?? null;
+        if (space !== null) {
+          const check = report.scan.spaceCheck;
           process.stdout.write(
-            `  组织 ${organization.id}  ${organization.title}（登记 ${check.declared} · 在库 ${check.present} · ` +
+            `  空间 ${space.id}  ${space.title}（登记 ${check.declared} · 在库 ${check.present} · ` +
               `缺 ${check.missing.length} · 未登记 ${check.undeclared.length}）\n`,
           );
         }
@@ -593,3 +619,56 @@ function runMigrate(options) {
   }
   return rc;
 }
+
+/**
+ * `clone`：把一个远端空间按原布局拉成本地副本。
+ *
+ * 落点默认是全局档案库根（`$DSH_HOME/agent-roster`），可以用 `--dir` 指到别处。
+ * 目录里有同名空间时**不覆盖**——覆盖别人正在用的副本不该是顺手发生的事；
+ * 要重来做 `rm -rf` 或换个 `--space` 名字。
+ *
+ * @param {object} options
+ * @returns {Promise<number>}
+ */
+async function runClone(options) {
+  if (options.repo === null) {
+    process.stderr.write(`clone 需要 --repo <owner/repo>\n\n${USAGE}`);
+    return 2;
+  }
+  const rootDir = options.dirs.length > 0 ? nodePath.resolve(options.dirs[0]) : globalRosterRoot();
+  const spaceId = options.space ?? options.repo.split("/")[1];
+  const target = nodePath.join(rootDir, spaceId);
+  if (existsSync(target) && options.write !== true) {
+    process.stderr.write(
+      `目标已存在：${target}\n` +
+        "不覆盖已有副本（那可能正被使用）。要重来请先删掉它，或用 --space 换个名字。\n" +
+        "确认要就地重写就加 --write（只重写本次拉到的文件）。\n",
+    );
+    return 1;
+  }
+
+  const result = await cloneSpace({
+    rootDir,
+    spaceId,
+    repo: options.repo,
+    ref: options.ref ?? "main",
+    path: options.path ?? "",
+    fetchImpl: fetch,
+  });
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify({ plugin: pkg.name, version: pkg.version, rootDir, ...result }, null, 2)}\n`);
+  } else {
+    const where = options.path === null ? "" : `/${options.path}`;
+    process.stdout.write(
+      `空间 ${spaceId}  <-  ${options.repo}@${options.ref ?? "main"}${where}  布局 ${result.layout}  ` +
+        `写入 ${result.written.length} 个文件${result.skipped.length > 0 ? ` · 跳过 ${result.skipped.length}` : ""}\n`,
+    );
+    process.stdout.write(`  落点 ${result.dir}\n`);
+    for (const item of result.diagnostics) process.stdout.write(`${formatDiagnostic(item)}\n`);
+    if (result.written.length > 0) {
+      process.stdout.write(`  文件 ${result.written.slice(0, 8).join(" · ")}${result.written.length > 8 ? " …" : ""}\n`);
+    }
+  }
+  return result.ok ? 0 : 1;
+}

package/client.js

@@ -32,6 +32,7 @@ window.__ModuleLoader__.load({
     const DOCUMENT_ROUTE = "/plugins/dsh-agent-roster/document";
     const ROSTERS_ROUTE = "/plugins/dsh-agent-roster/rosters";
     const INSTALL_ROUTE = "/plugins/dsh-agent-roster/install";
+    const INSTALL_SPACE_ROUTE = "/plugins/dsh-agent-roster/install-space";
     const COLLECTION_ROUTE = "/plugins/dsh-agent-roster/collection";
     const APPLY_ROUTE = "/plugins/dsh-agent-roster/apply";
     const SEARCH_ROUTE = "/plugins/dsh-agent-roster/search";
@@ -1285,7 +1286,7 @@ window.__ModuleLoader__.load({
      * 查询走后端排序（`/search`）：前端再写一套打分，两处迟早给出不同顺序。
      * 标签筛选是「且」，与档案页签的标签池同一语义。
      */
-    function CatalogTab({ onOpen, onPull }) {
+    function CatalogTab({ onOpen, onPull, onPullSpace }) {
       useTranslation();
       const [mode, setMode] = useState("source");
       const [query, setQuery] = useState("");
@@ -1348,6 +1349,13 @@ window.__ModuleLoader__.load({
         return [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
       }, [catalog.entries]);
 
+      // 哪些远端档案本机已经有了：按 id 对齐（同一个空间里 id 唯一）。
+      const installed = useMemo(() => {
+        const set = new Set();
+        for (const entry of catalog.entries) if (entry.scope === "local") set.add(entry.rosterId);
+        return set;
+      }, [catalog.entries]);
+
       const entries = hits !== null && hits.status === "ready" ? hits.matches : catalog.entries;
       const filtered = useMemo(() => {
         return entries.filter((entry) => {
@@ -1410,6 +1418,9 @@ window.__ModuleLoader__.load({
               "div",
               { className: "rstr-row-stats" },
               h("span", { className: "rstr-stat" }, t("catalog.members", { count: String(entry.members ?? 0) })),
+              entry.scope === "remote" && installed.has(entry.rosterId)
+                ? h(Badge, { tone: "ok" }, t("catalog.installed"))
+                : null,
               h(
                 "span",
                 { className: "rstr-stat" },
@@ -1546,6 +1557,26 @@ window.__ModuleLoader__.load({
                       { className: "rstr-group-head" },
                       h("span", { className: "rstr-group-title" }, group.title),
                       h("span", { className: "rstr-group-count" }, String(group.entries.length)),
+                      group.scope === "remote" && typeof onPullSpace === "function"
+                        ? h(
+                            "button",
+                            {
+                              type: "button",
+                              className: "rstr-btn rstr-btn-sm rstr-btn-ghost",
+                              disabled: pulling === `space:${group.key}`,
+                              onClick: async () => {
+                                setPulling(`space:${group.key}`);
+                                try {
+                                  await onPullSpace(group.key.slice(2));
+                                  setNonce((value) => value + 1);
+                                } finally {
+                                  setPulling("");
+                                }
+                              },
+                            },
+                            t("catalog.pullSpace"),
+                          )
+                        : null,
                     ),
                 group.entries.map(row),
               ),
@@ -1556,7 +1587,7 @@ window.__ModuleLoader__.load({
     function Panel() {
       useTranslation();
       const library = useLibrary();
-      const [tab, setTab] = useState("catalog");
+      const [tab, setTab] = useState("rosters");
       const [query, setQuery] = useState("");
       const [selectedTags, setSelectedTags] = useState(() => new Set());
       const [settingsOpen, setSettingsOpen] = useState(false);
@@ -1654,7 +1685,7 @@ window.__ModuleLoader__.load({
         }
       }
 
-      const organization = (snapshot?.workspaces ?? []).map((workspace) => workspace.organization).find((item) => item && item.id)?.id ?? "";
+      const space = (snapshot?.workspaces ?? []).map((workspace) => workspace.space).find((item) => item && item.id)?.id ?? "";
 
       const header = h(
         "header",
@@ -1670,7 +1701,7 @@ window.__ModuleLoader__.load({
             h("span", null, h("b", null, String(snapshot?.summary?.rosters ?? 0)), " ", t("panel.metaRosters")),
             h("span", null, h("b", null, String(snapshot?.summary?.members ?? 0)), " ", t("panel.metaMembers")),
             h("span", null, h("b", null, String(snapshot?.summary?.teams ?? 0)), " ", t("panel.metaTeams")),
-            organization === "" ? null : h("span", null, t("panel.metaOrganization", { name: organization })),
+            space === "" ? null : h("span", null, t("panel.metaSpace", { name: space })),
           ),
         ),
         h(
@@ -1713,8 +1744,8 @@ window.__ModuleLoader__.load({
         "div",
         { className: "rstr-tabs", role: "tablist" },
         [
-          ["catalog", t("panel.tabsCatalog"), null],
           ["rosters", t("panel.tabsRosters"), rosters.length],
+          ["catalog", t("panel.tabsCatalog"), null],
           ["teams", t("panel.tabsTeams"), teams.length],
           ["sources", t("panel.tabsSources"), snapshot?.remote?.collections?.length ?? 0],
           // 只有真正要用户处理的问题才计数：info 只是说明，不该在页签上挂数字。
@@ -1766,6 +1797,28 @@ window.__ModuleLoader__.load({
               setToast(t("misc.failed"));
             }
           },
+          onPullSpace: async (collectionId) => {
+            try {
+              const result = await readJson(INSTALL_SPACE_ROUTE, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ collection: collectionId }),
+              });
+              if (!result.ok || result.body === null) {
+                setToast(`${t("misc.failed")} (${String(result.status)})`);
+                return;
+              }
+              const body = result.body;
+              const summary = t("catalog.pulledSpace", {
+                files: String((body.written ?? []).length),
+                skipped: String((body.skipped ?? []).length),
+              });
+              setToast(summary);
+              library.reload();
+            } catch {
+              setToast(t("misc.failed"));
+            }
+          },
         });
       }
 

package/docs/roster-v2.md

@@ -209,7 +209,7 @@ gates:
 | 层 | 文件 | 回答的问题 |
 |---|---|---|
 | 能力 | `capabilities.yaml` | 这份档案要求部署提供什么（有证据源） |
-| 组织 | `organization.yaml` | 这座库收了哪些档案、哪些已归档 |
+| 空间 | `space.yaml` | 这座库收了哪些档案、什么布局（flat / monorepo）、本地副本从哪来 |
 | 角色/组装 | `AGENT.md` + `roster.yaml` | 谁是谁、怎么拼、编排放哪 |
 
 三者正交：`requires` 说"必须有"，`capabilities.yaml` 说"这份组装必须有"，`organization.yaml` 说"这座库有哪些"。

package/examples/space.yaml

@@ -0,0 +1,11 @@
+kind: dsh-agent-roster/space@1
+space: examples
+title: 示例档案（v2 三层）
+description: 两份从 v1 迁过来的档案，用来演示角色/组装/编译与施工图。
+license: MIT
+maintainers:
+  - STofone
+layout: monorepo
+rosters:
+  - id: core-review
+  - id: research

package/examples-orchestration/space.yaml

@@ -0,0 +1,10 @@
+kind: dsh-agent-roster/space@1
+space: examples-orchestration
+title: 编排示例
+description: 一份手写的 v2 档案：阶段、质量门与可执行判据都在这里。
+license: MIT
+maintainers:
+  - STofone
+layout: monorepo
+rosters:
+  - id: core-review

package/index.js

@@ -24,7 +24,7 @@ import { ROSTER2_KIND } from "./lib/format-v2.js";
 import { validateRoster } from "./lib/validate.js";
 import { validateRoster2 } from "./lib/roster2.js";
 import { sendError, sendJson, createAuthGate, readJsonBody, requireMethod } from "./lib/http.js";
-import { buildPanelSnapshot, installCollection, loadRemotePanel, resolveRoots } from "./lib/service.js";
+import { buildPanelSnapshot, installCollection, installSpace, loadRemotePanel, resolveRoots } from "./lib/service.js";
 import { createTtlCache, fetchCollection } from "./lib/remote.js";
 import { searchRosters } from "./lib/search.js";
 import { registerRosterTools } from "./lib/tools.js";
@@ -382,6 +382,35 @@ export function apply(ctx, config) {
       "install route",
     );
 
+    register(
+      "/plugins/dsh-agent-roster/install-space",
+      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 installSpace(settings, {
+          collectionId: input.collection,
+          source: typeof input.source === "string" && input.source !== "" ? input.source : undefined,
+          spaceId: typeof input.space === "string" && input.space !== "" ? input.space : undefined,
+        });
+        if (result.code === "collection-not-found") {
+          sendJson(res, 404, { ok: false, error: { code: result.code }, known: result.known ?? [], diagnostics: result.diagnostics ?? [] });
+          return;
+        }
+        sendJson(res, 200, result);
+      },
+      "install-space route",
+    );
+
     register(
       "/plugins/dsh-agent-roster/apply",
       async (req, res) => {