@stofone/dsh-agent-roster 0.13.1 → 1.1.0

package/CHANGELOG.md

@@ -4,6 +4,62 @@
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-11-03
+
+### The library reads as spaces, not groups
+
+1.0.0 made the space a real level in the format. The panel still showed collections as small labels, so the
+level existed in the files and not on screen. Each group header is now the space itself: its id sits in the
+same column as the roster ids (the register keeps one spine), the right side states two facts you can check
+on the spot — how many rosters it holds, how many are already here — and one button pulls the whole space.
+
+Rows also stopped lying about state. A roster that is already on this machine says so, and its action
+becomes **Open** instead of **Pull**: the panel no longer offers to fetch something you already have. The
+local group drops the per-row "local" label, because the group header already says it.
+
+On a narrow panel the space header folds into two lines (id + action, then title + facts) instead of
+squeezing a long space name into a vertical stack one character wide.
+
+
+## [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
@@ -628,6 +684,8 @@ point is now one search field above the tabs.
 
 [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
+[1.1.0]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v1.0.0...v1.1.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:
 
@@ -325,6 +326,11 @@ response, the tag strip summarises every tag in view with its count (multiple ta
 segmented control switches between **by source** (this machine, then one group per collection) and **flat**
 (one list, source named per row). Tag filtering is view state only; it never writes back to a file.
 
+By source, each group's head **is the space**: its id sits in the same column as the roster ids, the
+right side states two facts you can check on the spot — how many rosters it holds, how many are already
+here — and carries one button that pulls the whole space. A roster that is already here says so in its row
+and its button reads **Open**: the panel never asks you to pull something you already have.
+
 Multiple words are AND, not OR: `data kubernetes` returns nothing rather than every roster that merely
 mentions "data". Ranking is a pure function in `lib/search.js`, so it is unit-tested rather than eyeballed.
 
@@ -510,7 +516,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
 ```
 
@@ -518,7 +524,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 值守、文献综述与产品发现。每份都是"队长 + 两名专家"的三人组，全部为本项目自撰（未复制任何上游文本）。校验方式：
 
@@ -309,6 +323,10 @@ node bin/cli.mjs compile --roster examples-orchestration/rosters/core-review \
 多选是「且」；右侧可以在**按来源**（本机 + 每个 collection 各一组）与**平铺**（一份清单，来源写在行内）
 之间切换。标签筛选只影响视图，不写回文件。
 
+按来源时，每一组的头就是**空间**本身：等宽的空间 id 落在与档案 id 同一列，右侧写两件当场能核对的事实
+——「几份 · 已装几份」——并带一个「拉取整个空间」按钮。已经在本机的那份，行内写「已在本机」，
+按钮变成「打开」：面板不会让你去拉一份自己已经有的档案。窄屏上这个头折成两行，空间名不会被挤成竖排。
+
 多个词是「且」不是「或」：`data kubernetes` 一条都不返，而不是把所有提到 data 的档案都堆上来。
 排序是 `lib/search.js` 里的纯函数，所以它被单测钉住，而不是靠肉眼看着顺。
 
@@ -487,7 +505,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) => {
@@ -1365,14 +1373,19 @@ window.__ModuleLoader__.load({
             map.set(key, {
               key,
               scope: entry.scope,
-              title: entry.scope === "local" ? t("catalog.local") : entry.collectionTitle ?? entry.collectionId ?? "",
+              id: entry.scope === "local" ? t("catalog.local") : entry.collectionId ?? "",
+              title: entry.scope === "local" ? "" : entry.collectionTitle ?? "",
               entries: [],
             });
           }
           map.get(key).entries.push(entry);
         }
-        return [...map.values()];
-      }, [filtered, mode]);
+        // 空间头上只放两件能当场核对的事实：有几份、其中几份本机已经有。
+        return [...map.values()].map((group) => ({
+          ...group,
+          installed: group.entries.filter((entry) => installed.has(entry.rosterId)).length,
+        }));
+      }, [filtered, mode, installed, t]);
 
       function toggleTag(tag) {
         setSelected((current) => {
@@ -1410,13 +1423,17 @@ window.__ModuleLoader__.load({
               "div",
               { className: "rstr-row-stats" },
               h("span", { className: "rstr-stat" }, t("catalog.members", { count: String(entry.members ?? 0) })),
-              h(
-                "span",
-                { className: "rstr-stat" },
-                entry.scope === "local"
-                  ? t("catalog.local")
-                  : t("catalog.remoteFrom", { collection: entry.collectionTitle ?? entry.collectionId ?? "" }),
-              ),
+              entry.scope === "remote" && installed.has(entry.rosterId)
+                ? h("span", { className: "rstr-row-here" }, t("catalog.here"))
+                : null,
+              // 本机组里每行再写一次「本机」是废话：所在的分组头已经说了。
+              entry.scope === "local"
+                ? null
+                : h(
+                    "span",
+                    { className: "rstr-stat" },
+                    t("catalog.remoteFrom", { collection: entry.collectionTitle ?? entry.collectionId ?? "" }),
+                  ),
             ),
             h(
               "div",
@@ -1428,7 +1445,8 @@ window.__ModuleLoader__.load({
                   className: "rstr-btn rstr-btn-sm",
                   disabled: busy,
                   onClick: async () => {
-                    if (entry.scope === "local") {
+                    // 已经在本机的那份，按钮就该是「打开」——不能让人去拉一份自己已经有的。
+                    if (entry.scope === "local" || installed.has(entry.rosterId)) {
                       onOpen(entry.rosterId);
                       return;
                     }
@@ -1441,7 +1459,7 @@ window.__ModuleLoader__.load({
                     }
                   },
                 },
-                entry.scope === "local" ? t("catalog.open") : t("catalog.pull"),
+                entry.scope === "local" || installed.has(entry.rosterId) ? t("catalog.open") : t("catalog.pull"),
               ),
             ),
           ),
@@ -1538,14 +1556,42 @@ window.__ModuleLoader__.load({
           : groups.map((group) =>
               h(
                 "div",
-                { key: group.key, className: "rstr-group" },
-                mode === "flat" || group.title === ""
+                { key: group.key, className: "rstr-space" },
+                mode === "flat"
                   ? null
                   : h(
                       "div",
-                      { className: "rstr-group-head" },
-                      h("span", { className: "rstr-group-title" }, group.title),
-                      h("span", { className: "rstr-group-count" }, String(group.entries.length)),
+                      { className: "rstr-space-head" },
+                      h("code", { className: "rstr-space-id", title: group.id }, group.id),
+                      h("span", { className: "rstr-space-title" }, group.title),
+                      h(
+                        "span",
+                        { className: "rstr-space-facts" },
+                        t("catalog.facts", {
+                          count: String(group.entries.length),
+                          installed: String(group.installed),
+                        }),
+                      ),
+                      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),
               ),
@@ -1654,7 +1700,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 +1716,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(
@@ -1766,6 +1812,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"));
+            }
+          },
         });
       }
 
@@ -2682,13 +2750,37 @@ window.__ModuleLoader__.load({
 }
 .rstr-catalog .rstr-search { max-width: 560px; }
 
-.rstr-group { display: flex; flex-direction: column; min-width: 0; }
+.rstr-space { display: flex; flex-direction: column; min-width: 0; }
+.rstr-space + .rstr-space { margin-top: 24px; }
+.rstr-space-head {
+  display: grid;
+  grid-template-columns: minmax(110px, 176px) minmax(0, 1fr) auto auto;
+  align-items: baseline;
+  gap: 8px 16px;
+  padding: 16px 8px 6px 0;
+  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  min-width: 0;
+}
+.rstr-space-id {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--dsw-alias-label-primary);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.rstr-space-title { font-size: 13px; color: var(--dsw-alias-label-secondary); min-width: 0; }
+.rstr-space-facts {
+  font-size: 11px;
+  color: var(--dsw-alias-label-tertiary);
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+.rstr-row-here { font-size: 11px; color: var(--dsw-alias-label-tertiary); }
 
-.rstr-group-head { display: flex; align-items: baseline; gap: 8px; padding: 10px 0 4px; border-bottom: 1px solid var(--dsw-alias-border-l2); }
 
-.rstr-group-title { font-size: 12px; font-weight: 600; letter-spacing: 0.02em; color: var(--dsw-alias-label-secondary); }
 
-.rstr-group-count { font-size: 11px; color: var(--dsw-alias-label-tertiary); font-variant-numeric: tabular-nums; }
 
 .rstr-results { display: flex; flex-direction: column; min-width: 0; padding: 0 28px 28px; border-top: 1px solid var(--dsw-alias-border-l2); }
 
@@ -3027,6 +3119,16 @@ window.__ModuleLoader__.load({
   .rstr-tag { border-left: none; border-bottom: 2px solid transparent; border-radius: 0; white-space: nowrap; }
   .rstr-tag-on { border-left: none; border-bottom-color: var(--dsw-alias-state-business-primary); background: transparent; }
   .rstr-tag-clear { margin-top: 0; flex: 0 0 auto; }
+  /* 空间头：窄屏由一列 id/标题/事实/按钮的四列网格折成两行 */
+  .rstr-space-head {
+    grid-template-columns: minmax(0, 1fr) auto;
+    row-gap: 2px;
+    padding-top: 14px;
+  }
+  .rstr-space-id { grid-area: 1 / 1; }
+  .rstr-space-head > .rstr-btn { grid-area: 1 / 2; }
+  .rstr-space-title { grid-area: 2 / 1; }
+  .rstr-space-facts { grid-area: 2 / 2; text-align: right; }
   .rstr-row-body { grid-template-columns: minmax(0, 1fr) auto; }
   .rstr-row-id { grid-column: 1; }
   .rstr-row-text { grid-column: 1; }

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