Merge branch 'chore/grants-table-overflow'

GrantDto 增加 principalOpenId(USER 主体的 feishuOpenId),GROUP 行两列显示 —;
搜索过滤同步覆盖 openId。

.gitea/workflows/checker-check.yml

@@ -1,12 +1,12 @@
 name: checker check
 
 # Builds and lints the Rust implementation crates under crates/ (the rule-based
-# checker that "stands in Lean's position" at product runtime).
+# lesson checker).
 #
-# Like spec-check, this is an INTERNAL gate on the implementation's own health
-# (does it build, pass its tests, satisfy clippy + rustfmt?). It is NOT a
-# spec-to-implementation conformance gate — implementations align to the Lean
-# contract by human review, not by CI. See the repo README.
+# This is an INTERNAL gate on the implementation's own health
+# (does it build, pass its tests, satisfy clippy + rustfmt?). There is no
+# decision-to-implementation conformance gate — implementations align to the
+# ADRs by human review, not by CI. See the repo README.
 
 on:
   push:

.gitea/workflows/deploy-admin.yml

@@ -0,0 +1,126 @@
+name: deploy admin (hub fleet)
+
+# Rolls Hub releases that include the org-admin SPA (`admin-web` → registerStaticSpa)
+# onto the managed Alpha host. Two fleets share one machine and are separated by
+# the middle DNS label of each Silo's public URL:
+#
+#   dev  → https://<slug>.educraft-dev.paradigm-edu.net   (every push + PR)
+#   prod → https://<slug>.educraft.paradigm-edu.net       (main + tags)
+#
+# Example prod tenant:
+#   https://para-26071100.educraft.paradigm-edu.net/auth/feishu/para-26071100
+#
+# Required Gitea secret:
+#   DEPLOY_SSH_KEY  — private key for root@39.107.254.4
+#
+# Optional secrets / vars (defaults match NEW_SILO_RUNBOOK):
+#   DEPLOY_HOST, DEPLOY_USER, DEPLOY_SSH_PORT, DEPLOY_BASE
+#   vars.ALLOW_EMPTY_FLEET=1  — green when the fleet has no silos yet
+
+on:
+  push:
+    paths:
+      - "hub/**"
+      - ".gitea/workflows/deploy-admin.yml"
+  pull_request:
+    paths:
+      - "hub/**"
+      - ".gitea/workflows/deploy-admin.yml"
+  workflow_dispatch:
+    inputs:
+      fleet:
+        description: "Which fleet to deploy (dev | prod | both)"
+        required: true
+        default: both
+      allow_empty_fleet:
+        description: "Succeed if no silo matches (1/0)"
+        required: false
+        default: "0"
+
+concurrency:
+  group: deploy-admin-host
+  cancel-in-progress: false
+
+jobs:
+  deploy-dev:
+    name: deploy fleet dev (educraft-dev)
+    runs-on: ubuntu-latest
+    if: >
+      github.event_name == 'pull_request' ||
+      (github.event_name == 'push' && !startsWith(github.ref, 'refs/tags/')) ||
+      (github.event_name == 'workflow_dispatch' &&
+        (github.event.inputs.fleet == 'dev' || github.event.inputs.fleet == 'both'))
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install rsync + ssh
+        run: sudo apt-get update && sudo apt-get install -y rsync openssh-client
+
+      - name: Deploy Hub + admin SPA to educraft-dev fleet
+        env:
+          CPH_FLEET: dev
+          PLATFORM_DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
+          PLATFORM_DEPLOY_USER: ${{ secrets.DEPLOY_USER }}
+          PLATFORM_DEPLOY_PORT: ${{ secrets.DEPLOY_SSH_PORT }}
+          PLATFORM_DEPLOY_BASE: ${{ secrets.DEPLOY_BASE }}
+          PLATFORM_DEPLOY_RELEASE: ${{ github.sha }}
+          ALLOW_EMPTY_FLEET: ${{ github.event.inputs.allow_empty_fleet || vars.ALLOW_EMPTY_FLEET || '0' }}
+          DEPLOY_SSH_KEY_BODY: ${{ secrets.DEPLOY_SSH_KEY }}
+        run: |
+          set -euo pipefail
+          if [ -z "${DEPLOY_SSH_KEY_BODY:-}" ]; then
+            echo "missing secret DEPLOY_SSH_KEY" >&2
+            exit 1
+          fi
+          key="$(mktemp)"
+          trap 'rm -f "$key"' EXIT
+          printf '%s\n' "$DEPLOY_SSH_KEY_BODY" >"$key"
+          chmod 600 "$key"
+          export PLATFORM_DEPLOY_SSH_KEY="$key"
+          # Apply managed-host defaults when secrets are unset.
+          export PLATFORM_DEPLOY_HOST="${PLATFORM_DEPLOY_HOST:-39.107.254.4}"
+          export PLATFORM_DEPLOY_USER="${PLATFORM_DEPLOY_USER:-root}"
+          export PLATFORM_DEPLOY_PORT="${PLATFORM_DEPLOY_PORT:-22}"
+          export PLATFORM_DEPLOY_BASE="${PLATFORM_DEPLOY_BASE:-/srv/curriculum-project-hub}"
+          bash hub/deploy/deploy_fleet_release.sh
+
+  deploy-prod:
+    name: deploy fleet prod (educraft)
+    runs-on: ubuntu-latest
+    if: >
+      (github.event_name == 'push' && github.ref == 'refs/heads/main') ||
+      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')) ||
+      (github.event_name == 'workflow_dispatch' &&
+        (github.event.inputs.fleet == 'prod' || github.event.inputs.fleet == 'both'))
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install rsync + ssh
+        run: sudo apt-get update && sudo apt-get install -y rsync openssh-client
+
+      - name: Deploy Hub + admin SPA to educraft fleet
+        env:
+          CPH_FLEET: prod
+          PLATFORM_DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
+          PLATFORM_DEPLOY_USER: ${{ secrets.DEPLOY_USER }}
+          PLATFORM_DEPLOY_PORT: ${{ secrets.DEPLOY_SSH_PORT }}
+          PLATFORM_DEPLOY_BASE: ${{ secrets.DEPLOY_BASE }}
+          PLATFORM_DEPLOY_RELEASE: ${{ github.sha }}
+          ALLOW_EMPTY_FLEET: ${{ github.event.inputs.allow_empty_fleet || vars.ALLOW_EMPTY_FLEET || '0' }}
+          DEPLOY_SSH_KEY_BODY: ${{ secrets.DEPLOY_SSH_KEY }}
+        run: |
+          set -euo pipefail
+          if [ -z "${DEPLOY_SSH_KEY_BODY:-}" ]; then
+            echo "missing secret DEPLOY_SSH_KEY" >&2
+            exit 1
+          fi
+          key="$(mktemp)"
+          trap 'rm -f "$key"' EXIT
+          printf '%s\n' "$DEPLOY_SSH_KEY_BODY" >"$key"
+          chmod 600 "$key"
+          export PLATFORM_DEPLOY_SSH_KEY="$key"
+          export PLATFORM_DEPLOY_HOST="${PLATFORM_DEPLOY_HOST:-39.107.254.4}"
+          export PLATFORM_DEPLOY_USER="${PLATFORM_DEPLOY_USER:-root}"
+          export PLATFORM_DEPLOY_PORT="${PLATFORM_DEPLOY_PORT:-22}"
+          export PLATFORM_DEPLOY_BASE="${PLATFORM_DEPLOY_BASE:-/srv/curriculum-project-hub}"
+          bash hub/deploy/deploy_fleet_release.sh

.gitea/workflows/hub-check.yml

@@ -1,8 +1,8 @@
 name: hub check
 
 # Builds, type-checks, and tests the Hub TS package under hub/.
-# The Hub is the Feishu-group collaboration + agent runtime half
-# (spec/System implementation). This is an INTERNAL gate on the Hub's own
+# The Hub is the Feishu-group collaboration + agent runtime half.
+# This is an INTERNAL gate on the Hub's own
 # health, like checker-check is for the Rust half.
 
 on:

.gitea/workflows/spec-check.yml

@@ -1,20 +0,0 @@
-name: spec check
-
-# Builds the Lean semantic master spec under spec/.
-# This is an INTERNAL well-formedness gate (does the contract type-check?),
-# NOT a spec-to-implementation conformance gate — implementations align to the
-# contract by human review, not by CI. See repo README.
-
-on:
-  push:
-  pull_request:
-  workflow_dispatch:
-
-jobs:
-  spec-check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-      - uses: leanprover/lean-action@v1
-        with:
-          lake-package-directory: spec

.gitignore

@@ -1,7 +1,3 @@
-# Lean / Lake build artifacts (spec/ has its own .gitignore too)
-.lake/
-**/.lake/
-
 # Rust / Cargo build artifacts (repo-wide cargo workspace at root)
 /target
 **/*.pdf
@@ -11,6 +7,9 @@
 # regenerable, not for VCS. The embedded engine mounts cph-render directly.
 render/vendor/local-packages/
 
+# Environment
+.env
+
 # Node (hub/ TS workspace and any future JS package)
 node_modules/
 

.scratch/saas-production-readiness/issues/05-define-abuse-capacity-controls.md

@@ -29,7 +29,7 @@ workload brakes.
 
 The full current-state inventory, accepted behavior, and release evidence are
 recorded in [Initial abuse and capacity controls](../assets/initial-abuse-capacity-controls.md),
-with the durable decision in ADR-0022 and `Spec.System.Capacity`. Numerical
+with the durable decision in ADR-0022. Numerical
 ceilings remain open until production-like calibration.
 
 The implementation frontier is:

.scratch/saas-production-readiness/issues/08-prove-production-release-gate.md

@@ -7,6 +7,6 @@ Blocked by: 01, 02, 03, 04, 05, 06, 07, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18,
 ## Question
 
 After the readiness investigations and resulting fixes are resolved, can one
-repeatable release procedure prove build/test/spec health, deploy a clean
+repeatable release procedure prove build/test health, deploy a clean
 production-like environment, exercise critical tenant and agent journeys,
 verify observability and recovery, and either roll forward or roll back safely?

.scratch/saas-production-readiness/issues/27-reconcile-audit-history-contract.md

@@ -8,7 +8,7 @@ Blocked by: 04
 
 Separate or unify run-bound audit entries, pre-run security/permission events,
 structured messages, and operational recovery events without weakening
-`Spec.System.Audit`'s pinned AuditEntry-to-run relation. Decide durability,
+the pinned AuditEntry-to-run relation. Decide durability,
 failure, retention, and query semantics; then enforce referential integrity and
 observable/recoverable writes instead of silently swallowing lost evidence.
 Do not merge these customer Project/Run records with ADR-0023's already-decided

.scratch/saas-production-readiness/issues/42-decide-platform-admin-identity-audit.md

@@ -40,9 +40,7 @@ an off-host recovery key, an incident and reason, and issues only an expiring
 Emergency Platform Grant.
 
 The complete accepted decision and implementation divergences are in
-[ADR-0023](../../../docs/adr/0023-platform-administrator-identity-and-audit.md).
-The pinned semantic invariants are in
-[`Spec.System.PlatformAdministration`](../../../spec/Spec/System/PlatformAdministration.lean),
+[ADR-0023](../../../docs/adr/0023-platform-administrator-identity-and-audit.md),
 and the canonical terms are in [`CONTEXT.md`](../../../CONTEXT.md).
 
 Exact numeric session/invitation/step-up limits and browser mechanics remain

AGENTS.md

@@ -1,35 +1,35 @@
 # AGENTS.md —— agent 操作手册(全 repo)
 
-本 repo 是 monorepo。先读根 `README.md` 的"宪法"5 条,那是一切工作的前提。本文件是给在这里干活的 coding agent 的纪律。
+本 repo 是 monorepo。先读根 `README.md` 的"宪法"4 条,那是一切工作的前提。本文件是给在这里干活的 coding agent 的纪律。
 
 ## 这个 repo 是什么
 
-- `spec/` 是一份**人机共识的契约**(Lean 语义母本),是产品语义的上游参照。
-- 其余部件(将来的 `spec/` 外文件夹)是**向 `spec/` 对齐的实现**。
+- `docs/adr/` 是系统级决策的唯一权威来源;`CONTEXT.md` 是平台语言词汇表;代码注释把关键不变量锚到 ADR 编号,可 grep。
 - `hub/` 的平台层按 SaaS 形态演进:`Organization` 是 tenant root;`Project`/`Team`
-  必须归属 org,TEAM→PROJECT 授权不得跨 org(见 ADR-0020 / `Spec.System.Organization`)。
+  必须归属 org,TEAM→PROJECT 授权不得跨 org(见 ADR-0020)。
 - org 后台 project explorer 里 `Folder` 是透明组织节点,不是权限资源;project 仍是权限边界。
-  普通老师可在飞书群自助建 project 但受 org policy 控制(见 ADR-0021 /
-  `Spec.System.ProjectWorkspace`)。
+  普通老师可在飞书群自助建 project 但受 org policy 控制(见 ADR-0021)。
 - 每个 org 自选 BYOK 或平台托管 model provider connection;平台托管也必须是该 org
-  独享的 key/base URL,不得让无关 org 共用 process-global provider key(见 ADR-0021 /
-  `Spec.System.Organization`)。
+  独享的 key/base URL,不得让无关 org 共用 process-global provider key(见 ADR-0021)。
 - Feishu/provider secret 使用本地版本化 master-key keyring 的信封加密;生产由 systemd
   credential 注入,运行时只允许显式 org/project scope 的 fail-closed resolver,不得回退
   process-global credential;Agent child 只接收 run-scoped loopback proxy capability,
-  不接收 org provider credential(见 ADR-0024 / `Spec.System.Organization`)。
+  不接收 org provider credential(见 ADR-0024)。
 - 生产容量按不可突破的 platform ceiling 与 org 可下调 policy 分层;有效限制取两者较低值。
-  Agent admission 必须持久、有界、跨 org 公平且显式背压(见 ADR-0022 /
-  `Spec.System.Capacity`)。
+  Agent admission 必须持久、有界、跨 org 公平且显式背压(见 ADR-0022)。
 - 平台管理员只通过独立的 platform-owned 飞书应用与可撤销 Platform Session 认证,不复用
   客户 `User`/org membership;平台写操作与 append-only audit 同事务,break-glass 只走
-  双因子的离线恢复流程(见 ADR-0023 / `Spec.System.PlatformAdministration`)。
+  双因子的离线恢复流程(见 ADR-0023)。
 - 受控 alpha 暂采用一 Organization 一具名 systemd Silo:独立 database role/database、
   service identity、workspace、keyring 与 Feishu/provider connection；进程必须由
   `HUB_SILO_ORGANIZATION_ID` fail-closed 绑定唯一 org，平台后台不开放。共享 SaaS
   控制面与 Docker adapter 后置(见 ADR-0025)。
 - Agent role 与 skill 是 Organization-scoped 动态运行配置：role 组合 model、system prompt、
   tools 与已安装 skill；skill 版本进入 content-addressed 持久存储，run 只读加载所选快照。
+  每个 Organization 必须且只能有一个启用中的默认 role；新建群绑定从该默认值初始化，之后
+  `ProjectGroupBinding` 持久化群内当前 role，run 在接纳时冻结该 role。飞书公开 slash 协议只含
+  `/project`、`/usage`、`/help`；role、会话、目录操作走 `/project` 卡片，Claude 原生
+  `/compact` 只能由卡片动作以未经包装的精确 prompt 转发。
   `settingSources: []` 继续禁用项目/用户配置加载，不得把任意 workspace `.claude` 配置变成
   运行时能力(见 ADR-0018)。
 - 项目发现由 `ProjectDiscovery` 模块统一承载：PostgreSQL `pg_trgm` 搜索派生文档、项目编号
@@ -40,12 +40,12 @@
 
 ## 纪律
 
-1. **不得用预训练先验脑补本领域。** 这个领域很新,你没有相关先验。契约里 prose doc 注释是语义的唯一权威来源;契约没写的,就是没定的。
+1. **不得用预训练先验脑补本领域。** 这个领域很新,你没有相关先验。ADR 与 `CONTEXT.md` 是语义的唯一权威来源;没写的,就是没定的。
 
-2. **凡契约未写明者,不得假设。** 遇到标了 `OPEN` 的地方,或契约根本没覆盖的地方,**显式 surface 出来**让开发者决定,绝不擅自替它选一个解。
+2. **凡 ADR 未写明者,不得假设。** 遇到没覆盖的地方,**显式 surface 出来**让开发者决定,绝不擅自替它选一个解。
 
-3. **改 `spec/` 必须保持其 `lake build` 通过。** 在 `spec/` 目录下跑 `lake build`。新增声明必须带 `/-- … -/` doc 注释和恰当标签(`PINNED` / `OPEN` / `ADR-NNNN`)。规范见 `spec/README.md`。不准用 `sorry` 把 build 糊绿。
+3. **新语义决策进 ADR。** 跨部件的语义分歧点按编号顺延新增 `docs/adr/NNNN-*.md`;代码里的关键不变量用注释锚到 ADR 编号,保持可 grep。已有 ADR 正文不改写历史——推翻旧决策就写新 ADR 标记 supersede。
 
-4. **实现向契约对齐;偏离必须 surface。** 没有 CI gate 替你把关 spec↔实现的一致性(见宪法第 2 条)——这道对齐靠 review 和你巡逻 diff。发现实现与契约不一致时,报告它,不要默默让其中一边将就另一边。
+4. **实现向 ADR 对齐;偏离必须 surface。** 没有 CI gate 替你把关 ADR↔实现的一致性(见宪法第 2 条)——这道对齐靠 review 和你巡逻 diff。发现实现与决策不一致时,报告它,不要默默让其中一边将就另一边。
 
 5. **写操作谨慎。** 线上操作、git 写操作前与开发者确认(这是开发者的全局偏好)。

CLAUDE.md

@@ -1,25 +1,23 @@
 # CLAUDE.md —— agent 操作手册(全 repo)
 
-本 repo 是 monorepo。先读根 `README.md` 的"宪法"5 条,那是一切工作的前提。本文件是给在这里干活的 coding agent 的纪律。
+本 repo 是 monorepo。先读根 `README.md` 的"宪法"4 条,那是一切工作的前提。本文件是给在这里干活的 coding agent 的纪律。
 
 ## 这个 repo 是什么
 
-- `spec/` 是一份**人机共识的契约**(Lean 语义母本),是产品语义的上游参照。
-- 其余部件(将来的 `spec/` 外文件夹)是**向 `spec/` 对齐的实现**。
+- `docs/adr/` 是系统级决策的唯一权威来源;`CONTEXT.md` 是平台语言词汇表;代码注释把关键不变量锚到 ADR 编号,可 grep。
 - `hub/` 的平台层按 SaaS 形态演进:`Organization` 是 tenant root;`Project`/`Team`
-  必须归属 org,TEAM→PROJECT 授权不得跨 org(见 ADR-0020 / `Spec.System.Organization`)。
+  必须归属 org,TEAM→PROJECT 授权不得跨 org(见 ADR-0020)。
 - org 后台 project explorer 里 `Folder` 是透明组织节点,不是权限资源;project 仍是权限边界。
-  普通老师可在飞书群自助建 project 但受 org policy 控制(见 ADR-0021 /
-  `Spec.System.ProjectWorkspace`)。
+  普通老师可在飞书群自助建 project 但受 org policy 控制(见 ADR-0021)。
 
 ## 纪律
 
-1. **不得用预训练先验脑补本领域。** 这个领域很新,你没有相关先验。契约里 prose doc 注释是语义的唯一权威来源;契约没写的,就是没定的。
+1. **不得用预训练先验脑补本领域。** 这个领域很新,你没有相关先验。ADR 与 `CONTEXT.md` 是语义的唯一权威来源;没写的,就是没定的。
 
-2. **凡契约未写明者,不得假设。** 遇到标了 `OPEN` 的地方,或契约根本没覆盖的地方,**显式 surface 出来**让开发者决定,绝不擅自替它选一个解。
+2. **凡 ADR 未写明者,不得假设。** 遇到没覆盖的地方,**显式 surface 出来**让开发者决定,绝不擅自替它选一个解。
 
-3. **改 `spec/` 必须保持其 `lake build` 通过。** 在 `spec/` 目录下跑 `lake build`。新增声明必须带 `/-- … -/` doc 注释和恰当标签(`PINNED` / `OPEN` / `ADR-NNNN`)。规范见 `spec/README.md`。不准用 `sorry` 把 build 糊绿。
+3. **新语义决策进 ADR。** 跨部件的语义分歧点按编号顺延新增 `docs/adr/NNNN-*.md`;代码里的关键不变量用注释锚到 ADR 编号,保持可 grep。已有 ADR 正文不改写历史——推翻旧决策就写新 ADR 标记 supersede。
 
-4. **实现向契约对齐;偏离必须 surface。** 没有 CI gate 替你把关 spec↔实现的一致性(见宪法第 2 条)——这道对齐靠 review 和你巡逻 diff。发现实现与契约不一致时,报告它,不要默默让其中一边将就另一边。
+4. **实现向 ADR 对齐;偏离必须 surface。** 没有 CI gate 替你把关 ADR↔实现的一致性(见宪法第 2 条)——这道对齐靠 review 和你巡逻 diff。发现实现与决策不一致时,报告它,不要默默让其中一边将就另一边。
 
 5. **写操作谨慎。** 线上操作、git 写操作前与开发者确认(这是开发者的全局偏好)。

CONTEXT.md

@@ -99,3 +99,7 @@ _Avoid_: Cost budget, unlimited run
 **Emergency Workload Brake**:
 An audited Platform Administrator control that prevents new agent work for one Organization or the whole platform and may explicitly stop active work during an incident.
 _Avoid_: Organization deletion, service restart
+
+**Member Group**:
+A global, unlimited-depth, nestable authorization principal managed by the website administrator; a file-library grant on a group applies to that group and its whole descendant subtree, and a user's effective permission collects every group they belong to plus those groups' ancestors (ADR-0028). It stores no folder/project permission itself — only the user→group membership. Global: not owned by any Organization.
+_Avoid_: Team (the org-scoped flat grouping), Feishu department

README.md

@@ -2,7 +2,7 @@
 
 教研生产的数字化解决方案。核心思路:课程像 DAW / 剪辑软件那样有一个**结构化的工程文件**;coding agent 协助编辑它;一个 rule-based checker(类编译器)校验其合法性并给出 helpful fix hint。目标是把教研从一次性的文档,沉淀成**可累积、可校验、可复用的资产**。
 
-这是一个 **monorepo**。它的组织方式本身就表达了一条原则:**`spec/` 是上游的语义母本,其余部件是向它对齐的实现。**
+这是一个 **monorepo**。它的组织方式本身就表达了一条原则:**`docs/adr/` 是系统级决策的唯一权威来源,代码注释把关键不变量锚到 ADR 编号,可 grep。**
 
 ## 安装 `cph` 命令行
 
@@ -33,47 +33,40 @@ cph completions zsh > ~/.zfunc/_cph        # 或 bash/fish/powershell/elvish
 ```
 README.md          ← 本文件:总览 + 宪法(下面 5 条)
 CLAUDE.md          ← 全局 agent 操作手册(管整个 repo)
-docs/adr/          ← 系统级架构决策记录(跨部件,被 spec 契约引用)
-spec/              ← Lean 语义母本(自包含的 Lean 工程)。见 spec/README.md
+docs/adr/          ← 系统级架构决策记录(跨部件,决策的唯一权威来源)
+CONTEXT.md         ← 平台语言词汇表(术语与禁用说法)
 Cargo.toml         ← 仓库级 cargo workspace(实现部件共用,便于跨部件复用 crate)
-crates/            ← 实现:rule-based checker(向 spec 对齐)。见 crates/README.md
+crates/            ← 实现:rule-based checker(语义由 ADR 锚定)。见 crates/README.md
   cph-diag / cph-model / cph-schema / cph-typst   ← 可复用基础(模型/校验/typst 引擎)
   cph-check / cph-cli                             ← checker 本体 + `cph` 命令行
-render/            ← typst 渲染包 cph-render(母本的渲染后端之一,ADR-0005)
+render/            ← typst 渲染包 cph-render(checker 的渲染后端,ADR-0005)
 examples/          ← 样例工程文件(如 TH-141),流水线的真实输入
 hub/              ← SaaS Hub:飞书协作、org 管理、agent runtime 与生产部署
-(exporter/ …)     ← 将来的其他部件,平级于 spec/
+(exporter/ …)     ← 将来的其他部件,平级于 crates/
 ```
 
-`spec/` 与实现部件**物理分离、平级共存**:谁是上游、谁向谁对齐,一眼可见。
 实现部件共用一个仓库根的 cargo workspace,使基础 crate(模型、typst 引擎)能被
 未来部件(如 exporter)复用,而非各自重造。
 
 ## 宪法
 
-这 5 条是 `spec/` 这份语义母本的定位与约束,是本仓库一切工作的前提。
+这 4 条是本仓库的协作约定,是一切工作的前提。
 
-1. **角色 —— Lean 是研发侧的上游参照。**
-   `spec/` 用 Lean 编写,是开发者(领域专家)与 coding agent **共用**的 spec 工具,用来沉淀产品各部件的**语义**。它**不进入产品运行时**——产品里"站在 Lean 这个位置"的那个 checker 用什么技术实现,尚未决定;但那个东西的语义,先在 `spec/` 里固定下来。
+1. **角色 —— ADR 是决策真相。**
+   跨部件的语义决策只记录在 `docs/adr/`,一份决策一份 ADR,编号顺延、正文不改写历史。代码里的关键不变量用注释锚到 ADR 编号,保持可 grep。没有第二份权威文档。
 
-2. **对齐机制 —— Lean 只做上游参照。**
-   不做 extract / codegen,不派生 conformance test,CI 里**没有** spec→实现的 gate。实现对齐 spec,由"开发者 review + agent 巡逻 diff"这个人肉环节承载。
-   (CI 里的 `spec check` 只验 spec **自身**能否 type-check,即契约内部良构,不是 spec↔实现的对齐检查。)
+2. **对齐机制 —— 人肉承载,无机器兜底。**
+   CI 只验各部件自身良构(build / test / clippy),**没有**决策↔实现的一致性 gate。实现对齐 ADR,由"开发者 review + agent 巡逻 diff"这个人肉环节承载。发现漂移,报告它,不要默默让其中一边将就另一边。
 
-3. **资产性 —— 由 review 纪律承载,无机器兜底。**
-   这份仓库给你的是"精确、自洽、机器验内部良构的语义共识",**不是**"实现正确性保证"。spec 与实现之间那道缝,是我们自愿用人来守的——清醒地守,它就是资产;放任实现漂移而不回头同步,它就退化成最贵的过期文档。
+3. **形态 —— 自包含。**
+   凡 ADR 未明文规定的,开发者与 agent 双方都不该假设;遇到没覆盖的地方,**显式 surface** 出来让开发者决定。
 
-4. **形态 —— 它是人机共识的契约。**
-   契约必须**自包含**:凡契约未明文规定的,开发者与 agent 双方都不该假设。这比"文档"严格——type checker 会逼这份契约在结构上无洞。
-
-5. **深度判据 —— 只收录分歧点。**
-   一条语义该不该写进 Lean,取决于一句话:**"不写明,开发者与 agent 会不会各自做出不同假设?"** 会 → 进契约;显然的东西 / 纯 plumbing / 普通 CRUD 字段 → 不进(写进去只稀释信噪比、增加维护面)。
-   深度上限不是 Lean 的表达力,而是**你愿意在每次实现变更时手动回头同步的量**——写得比你能维护的更深,多出来的部分会率先过期、反过来误导实现。
+4. **深度判据 —— 只收录分歧点。**
+   一条语义该不该写进 ADR,取决于一句话:**"不写明,开发者与 agent 会不会各自做出不同假设?"** 会 → 进 ADR;显然的东西 / 纯 plumbing / 普通 CRUD 字段 → 不进(写进去只稀释信噪比、增加维护面)。
+   深度上限是**你愿意在每次实现变更时手动回头同步的量**——写得比你能维护的更深,多出来的部分会率先过期、反过来误导实现。
 
 ## CI
 
-`.gitea/workflows/spec-check.yml` 在每次 push / PR 时于 `spec/` 下跑 `lake build`,确保契约始终 type-check 通过(从第一天起就是"绿"的)。这是良构 gate,见宪法第 2 条。
-
 Rust checker 的本地与 CI 工具链由根 `rust-toolchain.toml` 固定;`.gitea/workflows/checker-check.yml`
 必须安装同一精确版本并执行 `cargo fmt --all --check`、Clippy `-D warnings` 与 workspace
 全测试。升级 Rust 时这两处必须在同一提交更新并通过完整 checker gate。

crates/README.md

@@ -1,7 +1,8 @@
 # crates/
 
-These crates implement the rule-based lesson checker that aligns to the
-semantic master in `spec/`: it reads an engineering-file (one lesson, ADR-0005)
+These crates implement the rule-based lesson checker whose semantics are
+pinned by the ADRs in `docs/adr/`: it reads an engineering-file (one lesson,
+ADR-0005)
 laid out per ADR-0008 (declarative `manifest.toml` + per-element
 `element.toml`), validates structure and content, and emits diagnostics.
 `cph-diag` (the shared diagnostic vocabulary), `cph-model` (the ADR-0008 loader),

crates/cph-check/src/lib.rs

@@ -19,13 +19,11 @@ const DEFAULT_TARGET: &str = "student";
 
 /// Severity of the render-coverage ("element ignored under a target") diagnostic.
 ///
-/// **PINNED to `warning` by the contract.** Mirrors the Lean master's
-/// `Spec.Courseware.renderIgnoredSeverity : Severity := .warning`
-/// (`spec/Spec/Courseware/Check/Diagnostic.lean`), itself citing ADR-0005: when a
+/// **PINNED to `warning` by ADR-0005:** when a
 /// `(kind, target)` pair has no render rule the checker reports that the element
 /// is ignored under that target and **does not block the export**. Naming the
-/// severity as a const makes "it is a warning, not an error" a greppable,
-/// alignable fact rather than an inline literal.
+/// severity as a const makes "it is a warning, not an error" a greppable
+/// fact rather than an inline literal.
 const RENDER_IGNORED_SEVERITY: Severity = Severity::Warning;
 
 /// The result of running [`check`] (or the check phases of [`build`]).
@@ -57,12 +55,12 @@ impl CheckReport {
 
     /// Whether any collected diagnostic is `Error`-severity.
     ///
-    /// **Legality decision (spec alignment).** `!has_errors()` is the
-    /// implementation of `Spec.Courseware.Legal` (`spec/Spec/Courseware/Check/Diagnostic.lean`):
-    /// a lesson is *legal* iff its diagnostics contain no error-level diagnostic
-    /// (warnings are non-blocking — see `Severity` / ADR-0010). There is no CI
-    /// gate enforcing this alignment (repo constitution); it is kept greppable
-    /// here so a reviewer can tie the orchestrator's gate to the Lean master.
+    /// **Legality decision (ADR-0010).** `!has_errors()` decides lesson
+    /// legality: a lesson is *legal* iff its diagnostics contain no error-level
+    /// diagnostic (warnings are non-blocking — see `Severity`). There is no CI
+    /// gate enforcing ADR↔implementation alignment (repo constitution); it is
+    /// kept greppable here so a reviewer can tie the orchestrator's gate to
+    /// the ADR.
     pub fn has_errors(&self) -> bool {
         self.diagnostics
             .iter()

crates/cph-diag/src/lib.rs

@@ -2,7 +2,7 @@
 //!
 //! Every other crate in the workspace depends on these types to report
 //! problems. The vocabulary is intentionally small and stable: a [`Severity`]
-//! (mirroring the Lean master), a closed set of machine-stable [`DiagCode`]s, an
+//! (two-valued, ADR-0010), a closed set of machine-stable [`DiagCode`]s, an
 //! optional [`SourceSpan`] pointing back at the offending source, and a
 //! [`Diagnostic`] tying them together with a human message and a fix hint.
 //!
@@ -17,32 +17,27 @@ use serde::Serialize;
 
 /// Severity of a diagnostic.
 ///
-/// **Mirrors `Spec.Courseware.Diagnostic.Severity`** in the Lean semantic
-/// master (`spec/Spec/Courseware/Check/Diagnostic.lean`), whose definition is
-/// exactly:
+/// **Pinned by ADR-0005 / ADR-0010: exactly two values.**
 ///
 /// ```text
-/// inductive Severity where
-///   | warning
-///   | error
+/// warning | error
 /// ```
 ///
-/// This two-valued shape is a **contract decision**, not an accident: the Lean
-/// module pins `Severity` to exactly `warning | error` and states the finer
-/// levels (`info` / `hint` / `note`) are deliberately undecided. We therefore
+/// This two-valued shape is a **contract decision**, not an accident: the
+/// finer levels (`info` / `hint` / `note`) are deliberately undecided, so we
 /// do **not** add an info/note level here. `error` blocks (the artifact is
 /// invalid); `warning` does not block (the artifact still exports, but with
 /// loss / an ignored element — e.g. ADR-0005's "missing render ⇒ warning").
 ///
-/// There is no CI gate enforcing this alignment (see the repo constitution);
-/// it is maintained by review, which is why this correspondence is documented
-/// here rather than only in the spec.
+/// There is no CI gate enforcing ADR↔implementation alignment (see the repo
+/// constitution); it is maintained by review, which is why the decision is
+/// documented here rather than only in the ADR.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
 pub enum Severity {
     /// Non-blocking: the artifact still exports, but is lossy / has an ignored
-    /// element. Mirrors Lean `Severity.warning`.
+    /// element. ADR-0010 `warning`.
     Warning,
-    /// Blocking: the artifact is invalid. Mirrors Lean `Severity.error`.
+    /// Blocking: the artifact is invalid. ADR-0010 `error`.
     Error,
 }
 

crates/cph-model/src/lib.rs

@@ -3,9 +3,7 @@
 //! This crate is the **loader**, not the full checker. It reads
 //! `<root>/manifest.toml` (project / info / ordered `[[parts]]` / declared
 //! `[targets.*]`) and each part's `<root>/<path>/element.toml`, and produces an
-//! ordered [`Lesson`] — mirroring the Lean master's `Lesson = List (Element P)`
-//! (`spec/Spec/Courseware/Model/Lesson.lean`), where the order of `parts` carries
-//! teaching semantics.
+//! ordered [`Lesson`], where the order of `parts` carries teaching semantics.
 //!
 //! Scope boundaries (deliberately staying in lane):
 //! - It validates **structure** only: manifest shape, element.toml shape, and
@@ -23,7 +21,7 @@ use serde::{Deserialize, Serialize};
 
 /// An ordered, in-memory lesson loaded from an engineering file.
 ///
-/// Mirrors the Lean master's `Lesson = List (Element P)`: `parts` is an ordered
+/// `parts` is an ordered
 /// `Vec`, and that order is the lesson's order (ADR-0008 §"the lesson manifest
 /// is declarative" — the `[[parts]]` array order is the single source of truth).
 #[derive(Debug, Clone, PartialEq, Serialize)]
@@ -86,9 +84,8 @@ pub struct TargetConfig {
     /// with template `exports/<name>.typ` when no `[[steps]]` are given.
     pub steps: Vec<Step>,
     /// The **render-coverage declaration**: which element kinds this target
-    /// renders. Realizes `Spec.Courseware.TargetSpec.covers : KindId → Prop`
-    /// (`spec/Spec/Courseware/Export/Render.lean`) and ADR-0011's "render
-    /// coverage is a declaration, not a payload": the contract keeps *which
+    /// renders. Realizes ADR-0011's "render
+    /// coverage is a declaration, not a payload": the declaration keeps *which
     /// kinds a target renders* (used by the `renderIgnored` seed diagnostic),
     /// while the rendering "how" lives in the template/steps.
     ///
@@ -102,13 +99,10 @@ pub struct TargetConfig {
 
 /// The artifact an export target produces (ADR-0009/0011).
 ///
-/// **Mirrors `Spec.Courseware.Artifact`** in the Lean semantic master
-/// (`spec/Spec/Courseware/Export/Artifact.lean`), whose definition is exactly:
+/// **Pinned by ADR-0011** as an ADT with fields:
 ///
 /// ```text
-/// inductive Artifact where
-///   | singleFile (filepath : String)
-///   | fileTree (root : String) (outputs : String)
+/// Artifact = singleFile (filepath) | fileTree (root, outputs)
 /// ```
 ///
 /// ADR-0011 pinned the artifact as an ADT **with fields**: "what the product
@@ -120,20 +114,20 @@ pub struct TargetConfig {
 /// `"single-file"` → [`Artifact::SingleFile`], `"file-tree"` →
 /// [`Artifact::FileTree`].
 ///
-/// As with `cph-diag`'s `Severity`, there is no CI gate enforcing this
-/// alignment (see the repo constitution) — it is maintained by review, which is
-/// why the correspondence is documented here.
+/// As with `cph-diag`'s `Severity`, there is no CI gate enforcing ADR↔
+/// implementation alignment (see the repo constitution) — it is maintained by
+/// review, which is why the decision is documented here.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize)]
 pub enum Artifact {
     /// One bundled document landing at `filepath` (relative to the engineering
-    /// root). Mirrors Lean `Artifact.singleFile`. The default artifact shape.
+    /// root). ADR-0011 `singleFile`. The default artifact shape.
     SingleFile {
         /// Where the single product is written (relative to the engineering
         /// root), e.g. `build/student.pdf`.
         filepath: PathBuf,
     },
-    /// A set of files under `root` matching the `outputs` glob. Mirrors Lean
-    /// `Artifact.fileTree`.
+    /// A set of files under `root` matching the `outputs` glob. ADR-0011
+    /// `fileTree`.
     FileTree {
         /// The output directory (relative to the engineering root).
         root: PathBuf,
@@ -156,14 +150,10 @@ impl Artifact {
 
 /// One typed build step (ADR-0011).
 ///
-/// **Mirrors `Spec.Courseware.Step`** in the Lean semantic master
-/// (`spec/Spec/Courseware/Export/Render.lean`), whose definition is exactly:
+/// **Pinned by ADR-0011** as an ADT:
 ///
 /// ```text
-/// inductive Step where
-///   | typstCompile (template : String)
-///   | shell (run : String)
-///   | assembleMarkdown (field : String)
+/// Step = typstCompile (template) | shell (run) | assembleMarkdown (field)
 /// ```
 ///
 /// A step is a *typed* operation (extensible): `TypstCompile` compiles a
@@ -183,20 +173,20 @@ impl Artifact {
 #[derive(Debug, Clone, PartialEq, Eq, Serialize)]
 pub enum Step {
     /// Compile a template file (relative to the engineering root) into the
-    /// artifact; the framework injects the manifest. Mirrors Lean
-    /// `Step.typstCompile`.
+    /// artifact; the framework injects the manifest. ADR-0011
+    /// `typstCompile`.
     TypstCompile {
         /// The template file to compile as main, e.g. `exports/student.typ`.
         template: PathBuf,
     },
-    /// Run a shell command — the escape hatch. Mirrors Lean `Step.shell`.
+    /// Run a shell command — the escape hatch. ADR-0011 `shell`.
     Shell {
         /// The command line to run.
         run: String,
     },
     /// Assemble a single-file markdown deliverable by concatenating each
-    /// element's `field` markdown content file in `[[parts]]` order. Mirrors
-    /// Lean `Step.assembleMarkdown` (ADR-0015). Not a typst build — the
+    /// element's `field` markdown content file in `[[parts]]` order. ADR-0011
+    /// `assembleMarkdown` (ADR-0015). Not a typst build — the
     /// framework owns the read/concatenate/write itself.
     AssembleMarkdown {
         /// The per-element markdown content field to assemble (e.g. `slides`,
@@ -226,12 +216,11 @@ pub struct Project {
 
 /// `[info]` table (passed through to render targets verbatim).
 ///
-/// **Mirrors `Spec.Courseware.Info`** in the Lean semantic master
-/// (`spec/Spec/Courseware/Model/Info.lean`): the *canonical* model whose
+/// The *canonical* model whose
 /// `authors` is always a list. The authoring-surface form (string-or-array
 /// `author`) is the separate [`RawInfo`] / [`RawAuthor`], normalized into this
-/// at the load boundary — mirroring the Lean `RawInfo` / `RawAuthor` split. No
-/// CI gate enforces this alignment (repo constitution); it is kept greppable.
+/// at the load boundary. No
+/// CI gate enforces ADR↔implementation alignment (repo constitution); it is kept greppable.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize)]
 pub struct Info {
     /// Lesson title.
@@ -240,7 +229,6 @@ pub struct Info {
     /// so this is a list, not a single name. Empty when `[info]` declares no
     /// `author`. The on-disk `author` accepts either a bare string (one author)
     /// or an array of strings (see [`RawAuthor`]); both load into this `Vec`.
-    /// Mirrors Lean `Info.authors : List String`.
     pub authors: Vec<String>,
 }
 
@@ -290,8 +278,7 @@ struct RawProject {
     name: String,
 }
 
-/// The authoring-surface `[info]` (mirrors Lean `RawInfo` in
-/// `spec/Spec/Courseware/Model/Info.lean`): the raw form that exists for
+/// The authoring-surface `[info]`: the raw form that exists for
 /// fill-in convenience, normalized into the canonical [`Info`] at the load
 /// boundary. Not the form the rest of the model traffics in.
 #[derive(Debug, Deserialize)]
@@ -301,7 +288,7 @@ struct RawInfo {
 }
 
 /// On-disk `author`: either a single name (`author = "…"`) or a list
-/// (`author = ["…", "…"]`). Mirrors Lean `RawAuthor`: a fill-in convenience whose
+/// (`author = ["…", "…"]`). A fill-in convenience whose
 /// string-or-array union lives **only** at the load boundary — [`RawAuthor::into_vec`]
 /// folds it into the canonical [`Info::authors`] `Vec`, after which it never appears.
 #[derive(Debug, Deserialize)]
@@ -312,7 +299,7 @@ enum RawAuthor {
 }
 
 impl RawAuthor {
-    /// Flatten to the ordered author list (Lean `RawAuthor.normalize`): a single
+    /// Flatten to the ordered author list: a single
     /// name becomes a one-element list; a list passes through verbatim.
     fn into_vec(self) -> Vec<String> {
         match self {

docs/adr/0017-agent-session-is-provider-bound.md

@@ -34,8 +34,12 @@ provider runtime cursor needed to continue a conversation. For Claude Code SDK,
 that cursor is the `result.session_id`; store it in `AgentSession.metadata` as
 `claudeSessionId` and pass it back to the next `query()` call as
 `options.resume`. Role is part of the session binding because role prompts and
-tool surfaces can differ even when the underlying model is the same; `/draft`
-and `/review` must not resume the same Claude runtime cursor by accident.
+tool surfaces can differ even when the underlying model is the same. A Feishu
+project group's active binding selects one Organization role for ordinary
+messages. Switching that selection routes future messages to the selected
+role's own session; it never mutates or merges provider cursors across roles.
+Work freezes the selected role when accepted so queued requests cannot drift
+after a later switch.
 
 Role definitions are Organization-scoped runtime data. A role bundle selects
 its default model, system prompt, tool allowlist and installed Agent skill
@@ -47,6 +51,20 @@ a Hub release or process restart. A change to the role's execution surface
 the next run cannot resume a provider context created under stale instructions;
 label and ordering-only changes preserve conversational continuity.
 
+Exactly one active role per Organization is the default used when a project
+group is first bound. The default is configuration data, not a hard-coded role
+name. Roles are selected through the Hub project console; role ids are not
+public slash commands. A project participant may change the group's shared
+selection only when both `agent.trigger` for the project and `role.trigger` for
+the target role authorize that actor. The selection affects every participant's
+future messages, while already accepted work keeps its frozen role.
+
+Hub slash commands are a closed control-plane protocol. Unknown commands fail
+explicitly and are never downgraded to Agent text. Claude SDK session commands
+are invoked only through typed Hub actions. In particular, compaction resumes
+the selected role session and sends the exact `/compact` prompt without
+prepending Feishu context.
+
 Environment variables:
 ```
 ANTHROPIC_BASE_URL=https://openrouter.ai/api

docs/adr/0018-agent-execution-surface-bounded-by-workspace.md

@@ -123,15 +123,23 @@ The boundary is enforced by the Claude Code SDK's built-in sandbox
   workspace or service-user config from widening tools, hooks, MCP servers, or
   sandbox paths.
 - Agent skills are Organization-scoped runtime configuration, not Hub release
-  assets. A controlled host-console installer imports each version into a
-  content-addressed persistent store and records its digest in PostgreSQL. A
-  role selects enabled Organization skills alongside its model, system prompt
-  and tool allowlist. Each run copies only those selected immutable versions
-  into a run-scoped plugin outside the project workspace; the sandbox exposes
-  that snapshot read-only and deletes it after the run. SDK-bundled skills and
-  filesystem setting sources remain disabled, so project `.claude` content
-  cannot register skills or widen tools. Requested skill versions are recorded
-  on `run.created`; SDK initialization remains authoritative loading evidence.
+  assets. Skill content is imported into a content-addressed persistent store
+  through a shared ingestion pipeline (`importSkillDirectory` for host-console
+  CLI, `importSkillFromFiles` for org-admin web surface) that enforces the same
+  safety checks: `SKILL.md` manifest required, 512-file / 16-byte limits,
+  symlink rejection, SHA-256 content addressing. The web surface
+  (`OrganizationAgentConfiguration.installSkillFromFiles`) writes to the same
+  store as the host-console CLI (`installSkill`); both flow through
+  `commitSkillContent` for deduplication and atomic rename into
+  `versions/<digest>/`. Org-admin authentication gates the web surface; the
+  content-addressed store remains platform-controlled. A role selects enabled
+  Organization skills alongside its model, system prompt and tool allowlist.
+  Each run copies only those selected immutable versions into a run-scoped
+  plugin outside the project workspace; the sandbox exposes that snapshot
+  read-only and deletes it after the run. SDK-bundled skills and filesystem
+  setting sources remain disabled, so project `.claude` content cannot register
+  skills or widen tools. Requested skill versions are recorded on
+  `run.created`; SDK initialization remains authoritative loading evidence.
 - Network: open (see Open Questions).
 
 `bypassPermissions` is kept (headless server — no interactive prompts); the

docs/adr/0026-usage-fact-ledger.md

@@ -0,0 +1,146 @@
+# ADR 0026: Usage Fact Ledger
+
+## Status
+
+Accepted.
+
+## Context
+
+ADR-0022 pins the cost-attribution contract for the platform: token,
+provider-reported cost, run count, and duration are attributed by Organization,
+Project, Run, model, and Provider Connection; "missing provider cost remains
+unknown rather than zero." ADR-0021 scopes usage accounting as operational
+reporting, not payment collection (commercial billing stays deferred).
+
+The implementation today stores this as **one scalar per `AgentRun`**:
+`inputTokens`, `outputTokens`, `costUsd?`, `costSource?`, written once from the
+Claude Agent SDK's `result.total_cost_usd` when the run finishes. This is
+adequate for a single provider-reported model loop, but it cannot represent:
+
+- **External capability consumption** inside a run. PDF→Markdown bundle
+  conversion, audio/video transcription, OCR and similar media transforms are
+  not the main agent loop. They run as side effects of a run, may use a
+  different provider/model, may bill in non-token units (pages, seconds,
+  invocations), and may report cost through a different channel than the
+  OpenRouter gateway. Today there is no row to write that cost to — it would
+  either disappear or silently corrupt the run's single scalar.
+- **Multiple model calls within one run** (e.g. a sub-model invoked by a
+  tool, a gateway-side reroute). The scalar collapses them into one number.
+- **Pricebook derivation** after the fact. With only a final USD figure and no
+  `(provider, model, occurredAt, tokens)` fact, an operator cannot re-derive
+  cost from a price table when the provider did not report it.
+
+Treating each external call as a nested `AgentRun` was considered and
+rejected: `AgentRun` carries lock ownership (ADR-0002), session/provider/role
+binding (ADR-0017), admission/capacity semantics (ADR-0022), and the
+user-visible task boundary. External calls hold none of those. Making them
+`AgentRun`s would pollute run counts, admission, lock semantics, and session
+continuity, and would still not solve non-token metering.
+
+## Decision
+
+Introduce **`UsageFact`** as the single source of truth for billable
+consumption inside an `AgentRun`. An `AgentRun` owns zero or more
+append-only `UsageFact` rows; each row records one billable consumption event:
+
+- `kind` — `model_completion` (the main agent loop) | `external_capability`
+  | `tool_proxy`. The kind set is `OPEN`; new kinds must be surfaced, not
+  silently folded into an existing one.
+- `provider` — e.g. `openrouter`, `mineru`, `openai_whisper`.
+- `model?`, `inputTokens?`, `outputTokens?` — token metering, optional
+  because non-token capabilities have none.
+- `quantity?` + `unit?` — non-token metering (pages, audio_seconds,
+  invocations), coexisting with tokens rather than replacing them.
+- `costUsd?` + `costSource` — `provider_reported` | `pricebook_derived` |
+  `unknown`. `costUsd = null` means **unknown, not zero** (ADR-0022). When the
+  provider reported a cost, `costSource = provider_reported` and that value
+  wins. When only tokens are known, a later pricebook pass may derive
+  `costUsd` with `costSource = pricebook_derived`. When neither is possible,
+  `costSource = unknown` and `costUsd` stays null.
+- `occurredAt` — when the consumption happened; the pricebook derivation
+  depends on this, not on `AgentRun.finishedAt`, because an external
+  capability may complete before the run finishes.
+- `capabilityId?` — for `external_capability` facts, the registered capability
+  id (e.g. `pdf_to_md_bundle`, `audio_video_to_text`).
+- `correlationId?` — external request id for reconciliation / idempotency;
+  not part of the aggregation key.
+
+### Invariants
+
+1. **Append-only.** A `UsageFact` row is never updated or deleted. A cost
+   correction is a new row; the old row stays. `onDelete: Cascade` exists only
+   so a hard run delete (itself not a normal path) cleans up its facts.
+2. **Belongs to exactly one Run; never holds a lock.** A fact is a side-effect
+   ledger of one run, not a sub-run. External capability calls obey the same
+   boundary: their identity is `capabilityId + correlationId`, not `RunId`.
+3. **Missing cost ≠ zero.** Aggregation MUST NOT sum `null` `costUsd` as 0.
+   A run whose facts all have `costUsd = null` is "cost unknown" — reported as
+   `runsWithoutCost`, exactly as the pre-migration `costUsd = null` runs are
+   today. A run with at least one `costUsd`-bearing fact contributes its sum.
+
+### Rollup cache
+
+`AgentRun.costUsd / inputTokens / outputTokens / costSource` columns are kept
+as a **derived rollup cache**, not dropped:
+
+- Existing non-`/usage` readers (slash `/usage`, session detail, integration
+  tests asserting `run.costUsd`) continue to work without code changes for
+  historical runs.
+- On run finish, the writer writes the `UsageFact` row first and then mirrors
+  it onto `AgentRun` as two separate statements, not one transaction. The
+  fact is the truth, so it is written first; the cache is derived, so it is
+  written second. A crash between the two leaves the cache stale, but the
+  usage service re-reads `UsageFact` directly, so staleness is recoverable
+  (and the reverse order would lose the truth, which is not). Keeping the
+  fact insert and the run update in separate statements also avoids holding
+  the `AgentRun` row lock across the FK ShareLock taken by the insert, which
+  deadlocks against concurrent workspace teardown under the cascade path
+  `Organization → Project → AgentRun → UsageFact`.
+- The org/project usage service and the slash `/usage` command read from
+  `UsageFact` directly — they are the canonical aggregation path.
+
+### Migration
+
+A new `UsageFact` table is added. For every existing `AgentRun` with a
+non-null `costUsd` or non-null `inputTokens`/`outputTokens`, the migration
+inserts **one synthetic `model_completion` fact** carrying the run's
+provider, model, tokens, cost, and `costSource`. Its `correlationId` is the
+run id, so the row is identifiable as a backfill artefact. This keeps
+historical reporting correct under the new aggregation path. Pre-migration
+runs with no recorded cost remain `runsWithoutCost` by design, matching
+ADR-0022's "missing cost ≠ zero" rule and the existing migration
+`20260709143000_agent_run_cost_tracking`'s "no backfill" stance for the
+truly unrecorded.
+
+## Consequences
+
+- The billing model now supports external capabilities (PDF→MD, ASR, OCR, …)
+  without per-capability schema changes: a new capability is one new
+  `capabilityId` value and one or more `external_capability` facts.
+- `AgentRun.costUsd` is no longer the truth; it is a convenience cache.
+  Readers that need the truth (cost breakdown, per-capability attribution)
+  must read `UsageFact`. The cache MUST be kept consistent on the write path.
+- The capability registry, pricebook, and any commercial settlement remain
+  `OPEN` and out of pilot scope (ADR-0021). This ADR only pins the ledger
+  shape and invariants.
+- `usage.ts` and `/usage` now perform a join against `UsageFact` rather than a
+  single-table scan of `AgentRun`; the index on `(runId, occurredAt)` and
+  `(provider, model, occurredAt)` keeps the existing org/project/report
+  queries bounded.
+- Cost corrections (e.g. a provider rebills a run) produce a new fact row; the
+  rollup cache must be recomputed. The initial release writes facts once at
+  run finish and does not support post-hoc correction flows — that remains
+  `OPEN`.
+
+## Deferred
+
+- **Capability registry** as a first-class spec entity (`Spec.System.Capability`)
+  with org-scoped enable/disable, input/output contracts, metering schemas,
+  and org-exclusive credentials (ADR-0024 alignment). This ADR only reserves
+  the `capabilityId` field and the `external_capability` fact kind.
+- **Pricebook** — a versioned price table keyed by `(provider, model, unit)`
+  with time validity. Required to actually produce `pricebook_derived` costs;
+  until then, facts without provider-reported cost stay `unknown`.
+- **Post-hoc cost correction flow** — append-only today; correction UI and
+  rollup recompute are `OPEN`.
+- **Commercial billing, invoicing, settlement** — still deferred per ADR-0021.

docs/adr/0027-external-capability-registry.md

@@ -0,0 +1,152 @@
+# ADR 0027: External Capability Registry
+
+## Status
+
+Accepted.
+
+## Context
+
+ADR-0026 introduced the `UsageFact` ledger with a `kind = external_capability`
+fact and a `capabilityId` field, but deferred the capability registry itself.
+Two concrete needs now force the issue:
+
+- **PDF→Markdown bundle** conversion (and, imminently, audio/video→text)
+  must run as a side effect of an `AgentRun`, bill in non-token units
+  (pages, seconds), use a different provider than the model loop, and report
+  cost through a different channel. It is not a sub-run (ADR-0026 rejected
+  that) and not a model-provider call (it does not speak the Anthropic/
+  OpenRouter protocol).
+- The Agent already has a Bash tool. Without a first-class capability seam,
+  the path of least resistance is for the agent to shell out to ad-hoc
+  scripts that embed API keys, write to arbitrary paths, and report nothing
+  to the ledger. That is exactly the unattributed, uncontained external
+  consumption ADR-0022/0026 exist to prevent.
+
+The model-provider connection (`OrganizationProviderConnection`, ADR-0024)
+is the wrong seam for these services:
+
+- Its payload schema (`baseUrl` + `authToken` + `anthropicApiKey`) and
+  readiness probe (`/v1/models?supported_parameters=tools`) are specific to
+  OpenRouter/Anthropic. MinerU, Whisper, and future OCR/ASR services have
+  different auth shapes (an API token, optionally a project id) and no
+  `/v1/models` endpoint.
+- Its uniqueness key is `(organizationId, providerId)` where `providerId`
+  is an OpenRouter-style model-routing id. A capability provider id
+  (`mineru`) names a *service*, not a model.
+- Coupling capability credentials into the model-provider table would force
+  every capability's auth shape through `ProviderSecretPayloadV1` and every
+  readiness probe through `probeOpenRouterCredential`.
+
+The Feishu Application Connection (`OrganizationFeishuApplicationConnection`)
+is the right structural precedent: it reuses the ADR-0024 envelope (KEK →
+DEK → AES-256-GCM, AAD-bound to purpose/org/connection/version) but has its
+own connection table, its own payload schema, its own readiness probe, and
+its own per-org uniqueness. Capability connections follow the same pattern.
+
+## Decision
+
+### External Capability
+
+An **External Capability** is a platform-registered, org-enabled document or
+media transform service invoked as a side effect of an `AgentRun`. It is
+identified by a stable `capabilityId` (e.g. `pdf_to_md_bundle`,
+`audio_video_to_text`). A capability:
+
+- Has an **input kind** (PDF, image, audio, video, …) and an **output
+  contract** (markdown bundle with extracted images, transcript text, …).
+- Bills in **non-token units** (pages, audio-seconds) recorded on a
+  `UsageFact` with `kind = external_capability`, or in tokens when the
+  backing service reports them.
+- Writes its output **into the invoking run's workspace** (ADR-0018
+  `AgentSurface` — no escapes).
+- Is invoked through a **capability adapter** in Hub, never by the Agent
+  shelling out with embedded credentials.
+
+### Capability Connection
+
+Credentials for a capability live in an **`OrganizationCapabilityConnection`**,
+structurally identical to the Feishu Application Connection:
+
+- Belongs to exactly one Organization.
+- Unique by `(organizationId, capabilityId)`.
+- `DRAFT` / `ACTIVE` / `DISABLED`; resolution accepts only `ACTIVE` with a
+  valid active secret version.
+- Secret material is an immutable, AAD-bound, KEK-wrapped envelope version
+  (`CapabilityCredentialVersion`), reusing the ADR-0024 encryption
+  machinery with `purpose = "capability"`.
+- Its payload schema is capability-specific (`CapabilitySecretPayloadV1`:
+  `baseUrl`, `apiToken`, optional `projectId`). New capability types extend
+  the payload, not the connection table.
+- A capability-specific **readiness probe** validates the credential before
+  activation (e.g. MinerU: a trivial authenticated GET). The probe is
+  injectable, matching the Feishu/provider pattern, so tests never hit the
+  network.
+
+### Capability Adapter
+
+The adapter is the seam between the Agent and the external service. It:
+
+- Resolves the org's active capability connection (fail-closed, no
+  process-global fallback — ADR-0024).
+- Accepts a workspace-relative input path and an output directory.
+- Calls the backing service (MinerU, Whisper, …) via an injectable
+  `Client` interface so the real HTTP client is swappable and mockable.
+- Writes the produced markdown + image assets into the run's workspace.
+- Writes one `UsageFact` (or more, if the service reports per-stage
+  consumption) with `kind = external_capability`, `capabilityId`,
+  `provider` (the service id), `quantity + unit` (pages / seconds), and
+  `costUsd + costSource = provider_reported` when the service reports cost.
+
+### Registry
+
+The platform maintains a **registry** of known capabilities: their id,
+input kind, output contract, metering unit, and adapter. This is
+code-level registration (like `ToolRegistry`), not a database table — a
+capability is available to an Organization only when (a) the platform
+knows the adapter and (b) the Organization has an `ACTIVE` connection for
+it. Both gates are required.
+
+### What is NOT in this ADR
+
+- The capability invocation is **not** a first-class persisted record
+  (`CapabilityInvocation` table) in this ADR. The `UsageFact` row with
+  `capabilityId` + `correlationId` is the durable trace. If we later need
+  a richer invocation log (retries, partial output, multi-stage status),
+  that is a follow-up; for now the fact is enough.
+- **Pricebook** remains deferred (ADR-0026). Capability facts use
+  `provider_reported` when the service returns cost; otherwise `unknown`.
+- **Org-scoped enable/disable policy** beyond connection status is
+  deferred. An org with an `ACTIVE` connection has the capability; one
+  without does not. A finer "enabled but no credential" toggle is not
+  needed yet.
+- **Agent-facing tool exposure** (how the Agent discovers and calls the
+  capability — MCP tool, Bash wrapper, or built-in) is an implementation
+  detail of the adapter wiring, not a contract concern. The contract pins
+  that the Agent never receives the capability credential.
+
+## Consequences
+
+- Adding a new external capability (e.g. `image_ocr`) is: register an
+  adapter, add a `capabilityId` constant, optionally extend the secret
+  payload — no schema change to `UsageFact` or `AgentRun`.
+- The model-provider connection table stays focused on model routing;
+  capability credentials do not pollute its payload or readiness probe.
+- Three connection types now share the ADR-0024 envelope: model-provider,
+  Feishu application, and capability. Each has its own table, payload
+  schema, and probe, but the same encryption, rotation, and resolver
+  boundary.
+- The Agent's Bash tool remains available, but the intended path for
+  document/media transforms is the capability adapter. Whether to narrow
+  Bash for capability-shaped tasks is an operational policy decision,
+  not a contract one.
+- Tests prove: workspace containment of capability output, fail-closed
+  credential resolution, `UsageFact` attribution with non-token metering,
+  and that the Agent process never receives the capability credential.
+
+## Deferred
+
+- `CapabilityInvocation` as a first-class durable record (status, retries,
+  partial output) — currently the `UsageFact` row is the only trace.
+- Pricebook derivation for capability costs (ADR-0026 deferred).
+- Org-scoped capability enable/disable policy finer than connection status.
+- Agent-facing tool discovery (MCP vs built-in) for capabilities.

docs/adr/0028-member-group-management-and-resolution.md

@@ -0,0 +1,153 @@
+# ADR 0028: Member Group Management And Resolution
+
+## Status
+
+Accepted.
+
+## Context
+
+ADR-0020 fixed `Organization` as the tenant root and ADR-0019 pinned the
+principal-set permission model. The file library (《文件库-接口契约.md》) computes
+effective permission over two principal kinds — `USER` and `GROUP` — and consumes
+the group side through a single read-only port, `GroupResolver`
+(`resolveMemberGroupIds(userId) → groupIds[]`, contract C2/G2).
+
+The contract's v0.1 proposal framed the Group system as a *separate HTTP service*
+owned by another team, consumed read-only. In practice the schema now carries the
+group tables directly in the hub database (`MemberGroup`, `MemberGroupMembership`,
+`MemberGroupClosure` — a global, unlimited-depth, closure-backed hierarchy), and
+the product requirement is to build **group management in the backend admin**, not
+to integrate a foreign service. Until this ADR, nothing read or wrote those tables:
+the live `GroupResolver` was a transitional implementation reading flat hub `Team`
+membership, and the admin "Group 管理" panel actually managed `Team`.
+
+This ADR settles the semantics needed to make the `MemberGroup` tables the real,
+in-hub group system.
+
+## Decision
+
+### Group system is in-hub, not a foreign service
+
+`MemberGroup` is the platform's global member-group principal. It lives in the hub
+database and is managed through the `/database` backend. The contract's "separate
+service" framing was an unfrozen v0.1 proposal; the implementation aligns to the
+tables that were actually built. The `GroupResolver` port stays — an external
+`HUB_GROUP_SERVICE_URL` HTTP implementation remains a supported override — but the
+default implementation reads the in-hub `MemberGroup` closure.
+
+### Authority: website administrator only
+
+Group create/delete and member add/remove are restricted to the **website
+administrator**, defined (consistently with the rest of the file library, D19/C4
+adaptation) as an `OWNER`/`ADMIN` of the silo Organization (`isWebsiteAdmin` in
+`filelib/guards.ts`). ADR-0023's `PlatformIdentity` is the future "true" platform
+control plane; the file library uniformly uses org OWNER/ADMIN today and this
+feature stays consistent with that. Reading groups for the authorization selector
+(`/groups/search`) is **not** admin-gated — picking a group to grant is a Manage
+holder's ability, not an administrator's.
+
+### Resolution semantics (the crux)
+
+`resolveMemberGroupIds(user)` returns the user's **active direct groups ∪ the
+active ancestors of those groups**, deduplicated (the closure's depth-0 self row
+makes each direct group its own ancestor). This is the single query the permission
+engine relies on; equivalently: a grant placed on group G applies to members of G
+and of every descendant of G (requirement 3.2 — permission flows down the tree, so
+resolution collects up the tree). It is computed **live, never cached** (contract
+D4/G4): a membership change is visible on the very next protected request.
+
+MemberGroup is global (no `organizationId`), so resolution is not org-scoped.
+
+### Soft delete via `archivedAt`, cascading the subtree
+
+Delete is soft: `MemberGroup.archivedAt` is a tag. Deleting a group
+cascade-soft-deletes its **whole subtree** (walk `MemberGroupClosure` where
+`ancestorId = G`, stamp `archivedAt` on each active descendant) — an application
+operation, not a DB constraint. Closure and membership rows are **retained**;
+resolution and listing filter by `archivedAt`, so an archived group and everything
+under it stop contributing to permission at once.
+
+### Closure maintenance
+
+The closure is maintained on **create**: insert `(G, G, 0)`, then for a parent `P`
+insert `(a.ancestorId, G, a.depth + 1)` for every `a` in
+`closure where descendantId = P`. v1 does **not** support reparenting a group
+(moving it under a new parent). The schema reserves reparent (closure rebuild plus
+the cycle guard "reject a new parent inside the moved subtree"); it is a follow-on.
+
+### Rename and description edits are in scope; reparent stays out
+
+A group's `name` and `description` are mutable by the website administrator
+(`PATCH /database/api/groups/:id`, audited as `group.update`). This is deliberately
+separated from reparent: renaming touches **no** closure row and cannot create a
+cycle, so it carries none of the invariant risk that keeps reparent out of v1. The
+endpoint therefore **rejects** a `parentId` field outright rather than ignoring it,
+so a future reparent cannot arrive silently through this route. Passing an empty
+`description` clears it; omitting a field leaves it unchanged.
+
+### Restore is deliberately asymmetric with delete
+
+Archived groups stay visible to the administrator (`GET
+/database/api/groups?includeArchived=1` returns them carrying `archivedAt`; the
+console tags and greys them) and can be restored (`POST
+/database/api/groups/:id/restore`, audited as `group.restore`).
+
+Restore is **not** the mirror image of delete. Delete cascades down the whole
+subtree; restore un-archives **the group plus every archived ancestor of it, and
+nothing below it**:
+
+- Restoring the ancestor chain is **mandatory**, not a convenience. An active group
+  whose parent is archived has no path in the tree, and the `depth` derivation
+  (closure row count) presumes "an active group's ancestors are active" — the
+  invariant that cascade-delete establishes. Restoring a node alone would break it.
+- The subtree is deliberately **left archived**. A group's descendants may have been
+  archived for reasons of their own, and one click should not silently re-grant
+  permission across a whole historical branch. Descendants remain visible in their
+  archived state and are each restored explicitly.
+
+Restore takes effect immediately, like every other membership change (D4/G4): the
+group resumes contributing permission on the next resolution.
+
+An archived group is **readable but not writable**. Its membership rows are never
+revoked by archiving, so `listMembers` succeeds on an archived group — the console
+must be able to show *who was in it* before deciding whether to restore it. Every
+mutation, by contrast, still requires an active group (`requireActiveGroup` → 404):
+rename, child creation, and member add/remove all reject. The group is inert for
+permission purposes and frozen for editing, but not hidden and not forgotten.
+
+### Member picker reads global users, admin-only
+
+`GET /database/api/users/search` backs the "add member" picker: it matches `User`
+by display name or Feishu open id and is gated to the website administrator, the
+same authority that may add members. It widens no existing capability — adding a
+member already accepts **any** global user (`resolveUser` does not require an org
+membership), so the endpoint only replaces blind id entry with search. It is
+deliberately **not** opened to the non-admin authorization-selector audience that
+`/groups/search` serves: choosing a group to grant is a Manage-holder action,
+whereas enumerating people is not. `excludeGroupId` filters out the target group's
+active members so the picker cannot surface a candidate that must 409.
+
+### Audit is written in-hub
+
+The contract (C3 §6.3) originally deferred group actions to the foreign Group
+service's own audit. With the group system in-hub, group mutations are audited
+through the existing file-library sink (`filelib/audit.ts`, same-transaction
+`AuditEntry`) under the silo Organization — `MemberGroup` has no `organizationId`,
+so the audit row is attributed to the silo org. New actions: `group.create`,
+`group.update`, `group.delete`, `group.restore`, `group.member_add`,
+`group.member_remove`; new audit object type `group`.
+
+## Consequences
+
+- The default `GroupResolver` becomes the in-hub `MemberGroup` closure reader.
+  `createTeamGroupResolver` is retained but deprecated (no longer wired); existing
+  flat-Team group grants no longer resolve for the file library.
+- Group grants take effect in real time through the existing `effectiveRole`
+  reducer (P6) with no change to the permission algebra — only the set of group ids
+  fed to it changes.
+- v1 omits reparent; the closure invariants above must hold whenever reparent is
+  added later (rebuild descendants' ancestor rows, reject cycles).
+- Group management is an admin-only surface; the authorization selector is not.
+- Numeric limits (max depth, max members) and a hard-delete/restore path remain
+  follow-on operational decisions; they must not weaken the archived-filter,
+  admin-authority, or live-resolution invariants fixed here.

docs/adr/0029-web-surface-frontend-backend-separation.md

@@ -0,0 +1,132 @@
+# ADR 0029: Web Surfaces Are Static SPAs; the Hub Serves JSON Only
+
+## Status
+
+Accepted.
+
+## Context
+
+The Hub exposes three browser surfaces: the org-admin console (`/admin`), the
+teacher-facing file library (`/app`), and the database admin back office
+(`/database`). They arrived at different times and diverged in how HTML reached
+the browser.
+
+`/admin` and `/app` were already separated: the backend serves a prebuilt static
+`index.html` and never inspects the request; all data flows through JSON
+endpoints. `/database` was not. Roughly 1770 lines across four modules
+(`renderDashboard`/`renderLoginPage` in `routes/databaseRoutes.ts`,
+`routes/adminPanels.ts`, `routes/libraryBrowser.ts`, `routes/libraryPage.ts`)
+assembled HTML template strings server-side, reading the session cookie and
+querying Prisma inside the page handler, with layout expressed as inline
+`style="…"` attributes and behavior as `<script>` text.
+
+A prior migration (`12628c9`) introduced a fourth frontend project,
+`hub/database-admin/`, intended to replace those pages. It was never wired up:
+the concrete route `/database/dashboard` is more specific than the SPA wildcard
+`/database/*`, so the server-rendered handler always won and the SPA's dashboard
+was unreachable. That project's file header claimed the SPA served the dashboard
+and that `/database/config` existed; neither was true. The `npm run build` script
+also never built it, so the `existsSync` guard in `database/static.ts` failed on
+every deploy and the shell was permanently disabled.
+
+Duplicated visual rules were the practical cost: card padding and type sizes were
+restated in each render module, and only the CSS variables in `routes/uiTheme.ts`
+were genuinely shared.
+
+## Decision
+
+**No Hub HTTP handler renders HTML.** Every browser surface is a prebuilt static
+SPA. Page handlers send a byte-identical `index.html` that does not depend on the
+request; all per-user and per-request data is fetched by the client from JSON
+endpoints under `/api/*` or `/database/api/*`.
+
+**`/app` and `/database` are one frontend project, `hub/filelib-web`, built once
+and mounted at two prefixes.** They share the file library browser, the session
+layer, the toast host, and the design tokens; splitting them would duplicate all
+of it. `hub/database-admin` is deleted — superseded before it ever served a
+request.
+
+Two configuration constraints follow from co-hosting two SvelteKit SPAs on one
+Fastify instance, and are load-bearing:
+
+- `filelib-web` sets `appDir: '_filelib'`. The SvelteKit default `_app` collides
+  with the root `/_app/*` asset route that `admin-web` owns
+  (`src/admin/static.ts`); Fastify rejects duplicate routes at startup, so the
+  collision is a boot failure, not a silent misroute.
+- `filelib-web` sets `paths.relative: false`. The same `index.html` is served at
+  different URL depths (`/app`, `/database/dashboard/users`), so relative asset
+  paths would resolve against the wrong base.
+
+**Client-side navigation uses real URL routes, not hash fragments or hidden
+sections.** The six back-office tabs are `/database/dashboard`,
+`/database/dashboard/library`, `/users`, `/groups`, `/search`, `/settings`.
+Refresh preserves position and links are shareable — the previous
+`location.hash` + `display:none` scheme lost both.
+
+Concrete routes must be registered before the SPA wildcards. This is an ordering
+obligation on `database/plugin.ts`, not an incidental detail: the earlier
+`/database/dashboard` shadowing bug is exactly what happens when a concrete page
+route outranks the fallback.
+
+## Consequences
+
+- Authorization is enforced only by the JSON endpoints. A client-side guard (the
+  `isWebsiteAdmin` check in the dashboard layout) is a navigation convenience and
+  carries no security weight; every endpoint keeps its own `fail closed` guard.
+- `/database/api/stats` is a new endpoint carrying what `loadDashboardStats` used
+  to compute inline. It requires silo org `OWNER`/`ADMIN` because it aggregates
+  org-wide counts and the audit stream rather than a per-node permission view.
+- `/database/api/me` grew `displayName` and `avatarUrl`. Anything the old page
+  handler read from Prisma to render chrome has to become part of a JSON payload
+  or it is simply unavailable: the sidebar identity strip showed a raw `userId`
+  until these were added. When migrating a server-rendered surface, the data the
+  template closed over is part of the contract being ported, not an incidental
+  detail of the old implementation.
+- Editing a page no longer requires a Hub restart in development; `vite dev`
+  serves the frontend and proxies data requests to the Hub. In production the
+  `index.html` is cached in memory at startup, so a frontend rebuild does require
+  a restart.
+- Deploy scripts and the silo rate-limit exemption list name `filelib-web` and
+  `/_filelib/*`. Adding a fourth surface means picking another `appDir` and
+  extending that list.
+- The design system is one file, `filelib-web/src/app.css`: an `@theme` block for
+  tokens plus an `@layer components` block for the shared component classes
+  (`.btn`, `.panel`, `.input`, `.select`, `.list`, `.tag`, `.quiet`, …).
+  `routes/uiTheme.ts` is deleted; both halves live there now.
+
+  The first cut of this migration kept only the tokens and restated button,
+  input, and panel styling inline in every component. That reproduced the
+  duplication the old code had — the admin panels visibly regressed — so the
+  component layer was ported too. Components carry layout utilities; they do not
+  restate component styling. The one admitted exception is a data-derived value
+  (tree indent computed from `depth`), which cannot be a static class.
+
+  The icon set (`lib/Icon.svelte`, 13 paths) is likewise shared rather than
+  restated. It came from `adminPanels.ts`; Group nodes deliberately use a
+  two-person silhouette, not a folder glyph, because `MemberGroup` and the file
+  library's `FOLDER`/`PROJECT` are unrelated hierarchies (ADR-0028, ADR-0021).
+
+- **A migrated surface is only done when its endpoint coverage matches.** Two
+  panels were rebuilt from a superficially similar component that predated the
+  migration rather than from the server module they replaced, and the mismatch
+  was invisible in the rendered page:
+
+  - Group management called 5 of 8 endpoints. Rename (`PATCH`),
+    `?includeArchived=1`, `/restore`, and `/users/search` had no entry point, so
+    a soft-deleted group could not be restored through the UI at all even though
+    the backend fully supported it.
+  - The library browser dropped the `授权` tab entirely — `GET/PUT/DELETE
+    .../grants` and `PUT .../independent-permission` had no caller. Permission
+    editing is the point of the back office, and it was unreachable.
+
+  Diffing the route table against the frontend's `api()` call sites catches this;
+  reading the new page does not.
+
+## Deferred
+
+- `/admin` (admin-web) stays a separate project. It has its own design language
+  (`saas-*` classes, `surface-*`/`primary-*` scales) and a different audience;
+  merging it is not motivated by shared code.
+- The `search` and `settings` tabs remain placeholders, as they were server-side.
+- Serving `/admin` and `/database` from a single SPA, which would remove the
+  `appDir` collision constraint entirely.

docs/para-26071100-feishu-setup.md

@@ -32,7 +32,7 @@ App ID 通常以 `cli_` 开头，可以写入交付单。App Secret 必须通过
 | 接收群聊中 @ 机器人的消息 | `im:message.group_at_msg:readonly` |
 | 以应用身份发送消息 | `im:message:send_as_bot` |
 | 读取触发消息和线程上下文 | `im:message:readonly` |
-| 获取与上传图片或文件 | `im:resource` |
+| 获取消息中的图片/文件，并向飞书上传图片或文件（含 Agent 回答中的图片发送） | `im:resource` |
 | 添加、删除消息表情回复 | `im:message.reactions:write_only` |
 | 获取用户基本信息 | `contact:user.base:readonly` |
 | 获取用户基本资料 | `contact:user.basic_profile:readonly` |
@@ -66,14 +66,19 @@ Educraft 机器人以应用身份调用上述 API，因此这些 scope 全部放
 
 如果 API 调试台提示缺少更细粒度权限，请把错误提示和发生时间截图给部署人员。不要自行开通通讯录全量读取等超出本表的权限。
 
+说明：`im:resource` 既用于下载用户发来的图片/文件，也用于 Agent 回复时把本地或远程图片上传为飞书 `image_key` 后嵌入消息卡片。缺少该权限时，带图回答会发送失败或降级为无图文本。已开通该 scope 的存量应用一般无需新增权限，但若权限尚未随最新版本发布，请创建新版本并审核发布。
+
+
 ## 4. 配置事件与卡片回调
 
 进入“事件与回调”。
 
 1. 在“事件配置”中将订阅方式设为“使用长连接接收事件”。
 2. 添加事件“接收消息” `im.message.receive_v1`。
-3. 在“回调配置”中同样选择长连接。
-4. 添加回调“卡片回传交互” `card.action.trigger`，用于审批、运行中断和项目创建/绑定按钮。
+3. 添加事件“解散群” `im.chat.disbanded_v1`，用于立即归档该群的项目绑定。
+4. 添加事件“机器人被移出群” `im.chat.member.bot.deleted_v1`，用于立即归档该群的项目绑定。
+5. 在“回调配置”中同样选择长连接。
+6. 添加回调“卡片回传交互” `card.action.trigger`，用于审批、运行中断和项目创建/绑定按钮。
 
 ![长连接与消息事件配置](assets/feishu-setup/03-events.png)
 
@@ -174,7 +179,7 @@ App ID：cli_...
 App Secret：（通过安全渠道单独发送）
 应用已发布：是 / 否
 机器人能力已启用：是 / 否
-消息事件和卡片回调已配置：是 / 否
+消息事件（含解散群、机器人被移出群）和卡片回调已配置：是 / 否
 OAuth 重定向 URL 已配置：是 / 否
 
 【首位 OWNER】

hub/.env.example

@@ -34,6 +34,10 @@ HUB_FEISHU_EVENTS_PER_MINUTE="120"
 # to this path and rejects any overlap before installing the unit.
 HUB_PROJECT_WORKSPACE_ROOT="/var/lib/cph-hub/workspaces"
 
+# Persistent root for the content-addressed agent skill store. Required at hub
+# startup unless XDG_STATE_HOME is set (then defaults to $XDG_STATE_HOME/skills).
+HUB_SKILL_STORE_ROOT="/var/lib/cph-hub/state/skills"
+
 # This process is pinned to exactly one Organization. Feishu credentials are
 # resolved from that Organization's encrypted ACTIVE connection.
 HUB_SILO_ORGANIZATION_ID=""

hub/.gitignore

@@ -4,3 +4,14 @@ dist/
 .env
 .env.*
 !.env.example
+.secrets/
+.dev-keyring.json
+.dev-workspaces/
+.dev-skills/
+.filelib-repos/
+admin-web/node_modules/
+admin-web/build/
+admin-web/.svelte-kit/
+filelib-web/node_modules/
+filelib-web/build/
+filelib-web/.svelte-kit/

hub/admin-web/.gitignore

@@ -0,0 +1,23 @@
+node_modules
+
+# Output
+.output
+.vercel
+.netlify
+.wrangler
+/.svelte-kit
+/build
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.env.*
+!.env.example
+!.env.test
+
+# Vite
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*

hub/admin-web/.npmrc

@@ -0,0 +1 @@
+engine-strict=true

hub/admin-web/.prettierignore

@@ -0,0 +1,4 @@
+build
+.svelte-kit
+node_modules
+package-lock.json

hub/admin-web/.prettierrc.json

@@ -0,0 +1,9 @@
+{
+	"useTabs": true,
+	"singleQuote": true,
+	"semi": true,
+	"trailingComma": "all",
+	"printWidth": 120,
+	"plugins": ["prettier-plugin-svelte"],
+	"overrides": [{ "files": "*.svelte", "options": { "parser": "svelte" } }]
+}

hub/admin-web/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+	"recommendations": ["svelte.svelte-vscode"]
+}

hub/admin-web/README.md

@@ -0,0 +1,42 @@
+# sv
+
+Everything you need to build a Svelte project, powered by [`sv`](https://github.com/sveltejs/cli).
+
+## Creating a project
+
+If you're seeing this, you've probably already done this step. Congrats!
+
+```sh
+# create a new project
+npx sv create my-app
+```
+
+To recreate this project with the same configuration:
+
+```sh
+# recreate this project
+npx sv@0.16.2 create --template minimal --types ts --install npm D:/Projects/curriculum-project-hub/hub/admin-web
+```
+
+## Developing
+
+Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+
+```sh
+npm run dev
+
+# or start the server and open the app in a new browser tab
+npm run dev -- --open
+```
+
+## Building
+
+To create a production version of your app:
+
+```sh
+npm run build
+```
+
+You can preview the production build with `npm run preview`.
+
+> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.

hub/admin-web/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "admin-web",
+	"private": true,
+	"version": "0.0.1",
+	"type": "module",
+	"scripts": {
+		"dev": "vite dev",
+		"build": "vite build",
+		"preview": "vite preview",
+		"prepare": "svelte-kit sync || echo ''",
+		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+		"format": "prettier --write .",
+		"format:check": "prettier --check ."
+	},
+	"devDependencies": {
+		"@skeletonlabs/skeleton": "^4.15.2",
+		"@skeletonlabs/skeleton-svelte": "^4.15.2",
+		"@sveltejs/adapter-auto": "^7.0.1",
+		"@sveltejs/adapter-static": "^3.0.10",
+		"@sveltejs/kit": "^2.63.0",
+		"@sveltejs/vite-plugin-svelte": "^7.1.2",
+		"@tailwindcss/vite": "^4.3.2",
+		"bits-ui": "^2.18.1",
+		"prettier": "^3.9.5",
+		"prettier-plugin-svelte": "^4.1.1",
+		"svelte": "^5.56.1",
+		"svelte-check": "^4.6.0",
+		"tailwindcss": "^4.3.2",
+		"typescript": "^6.0.3",
+		"vite": "^8.0.16"
+	}
+}

hub/admin-web/src/app.d.ts

@@ -0,0 +1,13 @@
+// See https://svelte.dev/docs/kit/types#app.d.ts
+// for information about these interfaces
+declare global {
+	namespace App {
+		// interface Error {}
+		// interface Locals {}
+		// interface PageData {}
+		// interface PageState {}
+		// interface Platform {}
+	}
+}
+
+export {};

hub/admin-web/src/app.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="zh-CN" data-theme="hamlindigo">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<meta name="text-scale" content="scale" />
+		<meta name="description" content="Curriculum Project Hub — 组织管理后台" />
+		<link rel="icon" href="%sveltekit.assets%/favicon.svg" type="image/svg+xml" />
+		<link rel="preconnect" href="https://fonts.googleapis.com" />
+		<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+		<link
+			href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&family=Noto+Sans+SC:wght@400;500;600;700&display=swap"
+			rel="stylesheet"
+		/>
+		<style>
+			/* Fallback before CSS bundle: CJK-first industrial base */
+			html {
+				font-family: 'Noto Sans SC', 'PingFang SC', 'Microsoft YaHei', 'Inter', sans-serif;
+			}
+		</style>
+		<title>CPH Admin</title>
+		%sveltekit.head%
+	</head>
+	<body data-sveltekit-preload-data="hover">
+		<div style="display: contents">%sveltekit.body%</div>
+	</body>
+</html>

hub/admin-web/src/lib/api.ts

@@ -0,0 +1,518 @@
+/**
+ * Thin API client for the org admin backend. Same-origin cookie auth.
+ */
+
+export class ApiError extends Error {
+	code: string;
+	status: number;
+	constructor(code: string, message: string, status: number) {
+		super(message);
+		this.name = 'ApiError';
+		this.code = code;
+		this.status = status;
+	}
+}
+
+async function request(method: string, url: string, body?: unknown): Promise<unknown> {
+	const init: RequestInit = {
+		method,
+		credentials: 'same-origin',
+		headers: body !== undefined ? { 'content-type': 'application/json' } : undefined,
+		body: body !== undefined ? JSON.stringify(body) : undefined,
+	};
+	const res = await fetch(url, init);
+	const text = await res.text();
+	let data: unknown = null;
+	if (text !== '') {
+		try {
+			data = JSON.parse(text);
+		} catch {
+			data = text;
+		}
+	}
+	if (!res.ok) {
+		const err = (data as { error?: { code?: string; message?: string } } | null)?.error;
+		throw new ApiError(err?.code ?? 'http_error', err?.message ?? `HTTP ${res.status}`, res.status);
+	}
+	return data;
+}
+
+const get = (u: string) => request('GET', u);
+const post = (u: string, b?: unknown) => request('POST', u, b);
+const put = (u: string, b?: unknown) => request('PUT', u, b);
+const patch = (u: string, b?: unknown) => request('PATCH', u, b);
+const del = (u: string) => request('DELETE', u);
+
+const orgBase = (slug: string) => `/api/org/${encodeURIComponent(slug)}`;
+
+// --- Types ---
+
+export interface OrgMembership {
+	id: string;
+	slug: string;
+	name: string;
+	status: string;
+	role: 'OWNER' | 'ADMIN' | 'MEMBER';
+}
+
+export interface MeResponse {
+	user: {
+		id: string;
+		feishuOpenId: string;
+		displayName: string;
+		avatarUrl: string | null;
+	};
+	organizations: OrgMembership[];
+}
+
+export interface OrgMember {
+	userId: string;
+	feishuOpenId: string;
+	displayName: string;
+	avatarUrl: string | null;
+	role: 'OWNER' | 'ADMIN' | 'MEMBER';
+	createdAt: string;
+}
+
+export interface TeamRow {
+	id: string;
+	slug: string;
+	name: string;
+	description: string | null;
+	memberCount: number;
+	createdAt: string;
+}
+
+export interface TeamMemberRow {
+	userId: string;
+	feishuOpenId: string;
+	displayName: string;
+	createdAt: string;
+}
+
+export interface ExplorerFolder {
+	id: string;
+	name: string;
+	parentId: string | null;
+	sortKey: string;
+	projectCount: number;
+	childFolderCount: number;
+}
+
+export interface ExplorerProject {
+	id: string;
+	name: string;
+	folderId: string | null;
+	createdAt: string;
+	binding: { chatId: string; createdAt: string } | null;
+}
+
+export interface ExplorerData {
+	folders: ExplorerFolder[];
+	projects: ExplorerProject[];
+}
+
+export interface ProjectDetail {
+	id: string;
+	name: string;
+	folderId: string | null;
+	folder: { id: string; name: string } | null;
+	workspaceDir: string;
+	createdAt: string;
+	archivedAt: string | null;
+	createdBy: { id: string; displayName: string; feishuOpenId: string } | null;
+	binding: { chatId: string; createdAt: string } | null;
+	actorIsOrgAdmin?: boolean;
+	actorCanManageProject?: boolean;
+}
+
+export interface TeamAccessEntry {
+	grantId: string;
+	projectId: string;
+	organizationId: string;
+	teamId: string;
+	teamSlug: string;
+	teamName: string;
+	role: 'READ' | 'EDIT' | 'MANAGE';
+}
+
+export interface SessionSummary {
+	id: string;
+	provider: string;
+	roleId: string;
+	model: string;
+	title: string | null;
+	runCount: number;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface ProviderConnectionRow {
+	id: string;
+	providerId: string;
+	mode: 'BYOK' | 'PLATFORM_MANAGED';
+	status: 'DRAFT' | 'ACTIVE' | 'DISABLED';
+	activeVersion: number | null;
+	keyId: string | null;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface FeishuApplicationConnection {
+	id: string;
+	appFingerprint: string;
+	status: 'DRAFT' | 'ACTIVE' | 'DISABLED';
+	activeVersion: number | null;
+	keyId: string | null;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface CapabilityConnection {
+	id: string;
+	capabilityId: string;
+	status: 'DRAFT' | 'ACTIVE' | 'DISABLED';
+	activeVersion: number | null;
+	keyId: string | null;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface UsageTotals {
+	runCount: number;
+	runsWithCost: number;
+	runsWithoutCost: number;
+	inputTokens: number;
+	outputTokens: number;
+	costUsd: number | null;
+}
+
+export interface ProjectUsageRow extends UsageTotals {
+	projectId: string;
+	projectName: string;
+	folderId: string | null;
+}
+
+/** Ledger slice from UsageFact (ADR-0026): separates model tokens vs external meters. */
+export interface UsageBreakdownRow {
+	kind: string;
+	provider: string;
+	model: string | null;
+	capabilityId: string | null;
+	unit: string | null;
+	factCount: number;
+	factsWithCost: number;
+	factsWithoutCost: number;
+	inputTokens: number;
+	outputTokens: number;
+	quantity: number | null;
+	costUsd: number | null;
+}
+
+export interface UsageReport {
+	from: string | null;
+	to: string | null;
+	projects: ProjectUsageRow[];
+	totals: UsageTotals;
+	breakdown: UsageBreakdownRow[];
+}
+
+export interface ProjectUsageReport extends ProjectUsageRow {
+	from: string | null;
+	to: string | null;
+	breakdown: UsageBreakdownRow[];
+}
+
+export interface UsageFactRow {
+	id: string;
+	occurredAt: string;
+	kind: string;
+	provider: string;
+	model: string | null;
+	inputTokens: number | null;
+	outputTokens: number | null;
+	quantity: number | null;
+	unit: string | null;
+	costUsd: number | null;
+	costSource: string;
+	capabilityId: string | null;
+	correlationId: string | null;
+}
+
+export interface SessionRunRow {
+	id: string;
+	status: string;
+	model: string;
+	provider: string;
+	inputTokens: number | null;
+	outputTokens: number | null;
+	costUsd: number | null;
+	costSource: string | null;
+	startedAt: string;
+	finishedAt: string | null;
+	error: string | null;
+	usageFacts: UsageFactRow[];
+}
+
+export interface SessionDetail {
+	id: string;
+	provider: string;
+	roleId: string;
+	model: string;
+	title: string | null;
+	createdAt: string;
+	updatedAt: string;
+	archivedAt: string | null;
+	project: { id: string; name: string };
+	runs: SessionRunRow[];
+}
+
+
+export type CapacityDimension =
+	| 'requestRate'
+	| 'requestBodySize'
+	| 'agentConcurrency'
+	| 'admissionQueueLength'
+	| 'admissionQueueWait'
+	| 'fileSize'
+	| 'attachmentCount'
+	| 'archiveExpansion'
+	| 'projectStorage'
+	| 'organizationStorage'
+	| 'memberCount'
+	| 'projectCount'
+	| 'teamCount'
+	| 'folderCount'
+	| 'sessionCount'
+	| 'runWallTime'
+	| 'runTurns'
+	| 'runToolCalls'
+	| 'toolWallTime'
+	| 'runOutputSize'
+	| 'processMemory'
+	| 'processCpu'
+	| 'processCount';
+
+export interface CapacityDimensionRow {
+	dimension: CapacityDimension;
+	platformCeiling: number | null;
+	organizationLimit: number | null;
+	effective: number | null;
+}
+
+export interface CapacityPolicyView {
+	dimensions: CapacityDimensionRow[];
+}
+
+export interface AgentRoleRow {
+	id: string;
+	roleId: string;
+	label: string;
+	defaultModel: string | null;
+	systemPrompt: string | null;
+	tools: readonly string[] | null;
+	sortOrder: number;
+	isDefault: boolean;
+	disabledAt: string | null;
+	createdAt: string;
+	updatedAt: string;
+	skillNames: readonly string[];
+}
+
+export interface AgentSkillRow {
+	id: string;
+	name: string;
+	version: string;
+	description: string | null;
+	contentDigest: string;
+	disabledAt: string | null;
+	createdAt: string;
+	updatedAt: string;
+	boundRoleIds: readonly string[];
+}
+
+export interface SkillFileEntry {
+	path: string;
+	content: string;
+}
+
+export interface InstalledSkillResult {
+	id: string;
+	name: string;
+	contentDigest: string;
+}
+
+export interface AgentModelRow {
+	id: string;
+	label: string;
+	toolCapable: boolean;
+}
+
+// --- API ---
+
+export const api = {
+	me: () => get('/api/me') as Promise<MeResponse>,
+	logout: () => post('/auth/logout'),
+
+	org: (slug: string) =>
+		get(orgBase(slug)) as Promise<{
+			organization: { id: string; slug: string; name: string; status: string };
+			actorRole: string;
+		}>,
+	settings: (slug: string) => get(`${orgBase(slug)}/settings`) as Promise<{ membersCanCreateProjects: boolean }>,
+	setSettings: (slug: string, body: { membersCanCreateProjects: boolean }) =>
+		patch(`${orgBase(slug)}/settings`, body) as Promise<{ membersCanCreateProjects: boolean }>,
+
+	members: (slug: string) => get(`${orgBase(slug)}/members`) as Promise<{ members: OrgMember[] }>,
+	addMember: (slug: string, body: { feishuOpenId: string; displayName?: string; role: string }) =>
+		post(`${orgBase(slug)}/members`, body) as Promise<OrgMember>,
+	setMemberRole: (slug: string, userId: string, role: string) => patch(`${orgBase(slug)}/members/${userId}`, { role }),
+	revokeMember: (slug: string, userId: string) => post(`${orgBase(slug)}/members/${userId}/revoke`),
+
+	teams: (slug: string) => get(`${orgBase(slug)}/teams`) as Promise<{ teams: TeamRow[] }>,
+	createTeam: (slug: string, body: { slug: string; name: string; description?: string }) =>
+		post(`${orgBase(slug)}/teams`, body) as Promise<TeamRow>,
+	updateTeam: (slug: string, teamId: string, body: { name?: string; description?: string | null }) =>
+		patch(`${orgBase(slug)}/teams/${teamId}`, body) as Promise<TeamRow>,
+	archiveTeam: (slug: string, teamId: string) => post(`${orgBase(slug)}/teams/${teamId}/archive`),
+	teamMembers: (slug: string, teamId: string) =>
+		get(`${orgBase(slug)}/teams/${teamId}/members`) as Promise<{ members: TeamMemberRow[] }>,
+	addTeamMember: (slug: string, teamId: string, body: { userId?: string; feishuOpenId?: string }) =>
+		post(`${orgBase(slug)}/teams/${teamId}/members`, body) as Promise<TeamMemberRow>,
+	revokeTeamMember: (slug: string, teamId: string, userId: string) =>
+		post(`${orgBase(slug)}/teams/${teamId}/members/${userId}/revoke`),
+
+	explorer: (slug: string) => get(`${orgBase(slug)}/explorer`) as Promise<ExplorerData>,
+	myProjects: (slug: string) => get(`${orgBase(slug)}/my-projects`) as Promise<{ projects: ExplorerProject[] }>,
+	createFolder: (slug: string, body: { name: string; parentId?: string; sortKey?: string }) =>
+		post(`${orgBase(slug)}/folders`, body) as Promise<{
+			id: string;
+			name: string;
+			parentId: string | null;
+			sortKey: string;
+		}>,
+	renameFolder: (slug: string, folderId: string, body: { name?: string; sortKey?: string; parentId?: string | null }) =>
+		patch(`${orgBase(slug)}/folders/${folderId}`, body) as Promise<{
+			id: string;
+			name: string;
+			parentId: string | null;
+			sortKey: string;
+		}>,
+	archiveFolder: (slug: string, folderId: string) =>
+		post(`${orgBase(slug)}/folders/${folderId}/archive`) as Promise<{ archived: true; folderId: string }>,
+	createProject: (slug: string, body: { name: string; folderId?: string }) =>
+		post(`${orgBase(slug)}/projects`, body) as Promise<{ id: string; name: string }>,
+	project: (slug: string, projectId: string) => get(`${orgBase(slug)}/projects/${projectId}`) as Promise<ProjectDetail>,
+	renameProject: (slug: string, projectId: string, name: string) =>
+		patch(`${orgBase(slug)}/projects/${projectId}`, { name }),
+	moveProject: (slug: string, projectId: string, folderId: string | null) =>
+		patch(`${orgBase(slug)}/projects/${projectId}/folder`, { folderId }),
+	archiveProject: (slug: string, projectId: string) => post(`${orgBase(slug)}/projects/${projectId}/archive`),
+	archiveBinding: (slug: string, projectId: string) => post(`${orgBase(slug)}/projects/${projectId}/binding/archive`),
+
+	teamAccess: (slug: string, projectId: string) =>
+		get(`${orgBase(slug)}/projects/${projectId}/team-access`) as Promise<{ access: TeamAccessEntry[] }>,
+	grantTeamAccess: (slug: string, projectId: string, body: { teamId?: string; teamSlug?: string; role: string }) =>
+		put(`${orgBase(slug)}/projects/${projectId}/team-access`, body) as Promise<TeamAccessEntry>,
+	revokeTeamAccess: (slug: string, projectId: string, teamId: string) =>
+		del(`${orgBase(slug)}/projects/${projectId}/team-access/${teamId}`),
+
+	sessions: (slug: string, projectId: string, limit?: number) =>
+		get(`${orgBase(slug)}/projects/${projectId}/sessions${limit !== undefined ? `?limit=${limit}` : ''}`) as Promise<{
+			sessions: SessionSummary[];
+		}>,
+	session: (slug: string, sessionId: string) =>
+		get(`${orgBase(slug)}/sessions/${encodeURIComponent(sessionId)}`) as Promise<SessionDetail>,
+	usage: (slug: string, params?: { from?: string; to?: string; folderId?: string }) => {
+		const q = new URLSearchParams();
+		if (params?.from) q.set('from', params.from);
+		if (params?.to) q.set('to', params.to);
+		if (params?.folderId) q.set('folderId', params.folderId);
+		const qs = q.toString();
+		return get(`${orgBase(slug)}/usage${qs ? `?${qs}` : ''}`) as Promise<UsageReport>;
+	},
+	projectUsage: (slug: string, projectId: string, params?: { from?: string; to?: string }) => {
+		const q = new URLSearchParams();
+		if (params?.from) q.set('from', params.from);
+		if (params?.to) q.set('to', params.to);
+		const qs = q.toString();
+		return get(
+			`${orgBase(slug)}/projects/${encodeURIComponent(projectId)}/usage${qs ? `?${qs}` : ''}`,
+		) as Promise<ProjectUsageReport>;
+	},
+
+
+	providerConnections: (slug: string) =>
+		get(`${orgBase(slug)}/provider-connections`) as Promise<{ connections: ProviderConnectionRow[] }>,
+	rotateProviderConnection: (
+		slug: string,
+		providerId: string,
+		body: { baseUrl: string; authToken: string; anthropicApiKey?: string },
+	) =>
+		put(
+			`${orgBase(slug)}/provider-connections/${encodeURIComponent(providerId)}`,
+			body,
+		) as Promise<ProviderConnectionRow>,
+
+	feishuApplication: (slug: string) =>
+		get(`${orgBase(slug)}/feishu-application-connection`) as Promise<{
+			connection: FeishuApplicationConnection | null;
+		}>,
+	rotateFeishuApplication: (
+		slug: string,
+		body: {
+			appId: string;
+			appSecret: string;
+			botOpenId: string;
+			verificationToken?: string;
+			encryptKey?: string;
+		},
+	) => put(`${orgBase(slug)}/feishu-application-connection`, body) as Promise<FeishuApplicationConnection>,
+	disableFeishuApplication: (slug: string) =>
+		del(`${orgBase(slug)}/feishu-application-connection`) as Promise<FeishuApplicationConnection>,
+
+	capabilityConnections: (slug: string) =>
+		get(`${orgBase(slug)}/capability-connections`) as Promise<{ connections: CapabilityConnection[] }>,
+	capabilityConnection: (slug: string, capabilityId: string) =>
+		get(`${orgBase(slug)}/capability-connections/${encodeURIComponent(capabilityId)}`) as Promise<{
+			connection: CapabilityConnection | null;
+		}>,
+	rotateCapabilityConnection: (
+		slug: string,
+		capabilityId: string,
+		body: { accessKeyId: string; accessKeySecret: string; endpoint: string },
+	) =>
+		put(`${orgBase(slug)}/capability-connections/${encodeURIComponent(capabilityId)}`, body) as Promise<CapabilityConnection>,
+	disableCapabilityConnection: (slug: string, capabilityId: string) =>
+		del(`${orgBase(slug)}/capability-connections/${encodeURIComponent(capabilityId)}`) as Promise<CapabilityConnection>,
+
+	capacityPolicy: (slug: string) => get(`${orgBase(slug)}/capacity-policy`) as Promise<CapacityPolicyView>,
+	setCapacityPolicy: (slug: string, body: { limits: Partial<Record<CapacityDimension, number | null>> }) =>
+		put(`${orgBase(slug)}/capacity-policy`, body) as Promise<CapacityPolicyView>,
+
+	agentRoles: (slug: string) => get(`${orgBase(slug)}/agent-roles`) as Promise<{ roles: AgentRoleRow[] }>,
+	upsertAgentRole: (
+		slug: string,
+		roleId: string,
+		body: {
+			label: string;
+			defaultModel?: string | null;
+			systemPrompt?: string | null;
+			tools?: readonly string[] | null;
+			sortOrder?: number;
+			isDefault?: boolean;
+		},
+	) => put(`${orgBase(slug)}/agent-roles/${encodeURIComponent(roleId)}`, body) as Promise<AgentRoleRow>,
+	setAgentRoleSkills: (slug: string, roleId: string, skillNames: readonly string[]) =>
+		put(`${orgBase(slug)}/agent-roles/${encodeURIComponent(roleId)}/skills`, { skillNames }) as Promise<{
+			skillNames: string[];
+		}>,
+	agentSkills: (slug: string) => get(`${orgBase(slug)}/agent-skills`) as Promise<{ skills: AgentSkillRow[] }>,
+	agentSkillFiles: (slug: string, name: string) =>
+		get(`${orgBase(slug)}/agent-skills/${encodeURIComponent(name)}/files`) as Promise<{ files: SkillFileEntry[] }>,
+	installAgentSkill: (slug: string, name: string, body: { version: string; files: readonly SkillFileEntry[] }) =>
+		put(`${orgBase(slug)}/agent-skills/${encodeURIComponent(name)}`, body) as Promise<InstalledSkillResult>,
+	patchAgentSkill: (slug: string, name: string, body: { description?: string; disabled?: boolean }) =>
+		patch(`${orgBase(slug)}/agent-skills/${encodeURIComponent(name)}`, body) as Promise<{ disabled?: boolean; updated?: boolean }>,
+	agentModels: (slug: string) => get(`${orgBase(slug)}/agent-models`) as Promise<{ models: AgentModelRow[] }>,
+};

hub/admin-web/src/lib/assets/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="107" height="128" viewBox="0 0 107 128"><title>svelte-logo</title><path d="M94.157 22.819c-10.4-14.885-30.94-19.297-45.792-9.835L22.282 29.608A29.92 29.92 0 0 0 8.764 49.65a31.5 31.5 0 0 0 3.108 20.231 30 30 0 0 0-4.477 11.183 31.9 31.9 0 0 0 5.448 24.116c10.402 14.887 30.942 19.297 45.791 9.835l26.083-16.624A29.92 29.92 0 0 0 98.235 78.35a31.53 31.53 0 0 0-3.105-20.232 30 30 0 0 0 4.474-11.182 31.88 31.88 0 0 0-5.447-24.116" style="fill:#ff3e00"/><path d="M45.817 106.582a20.72 20.72 0 0 1-22.237-8.243 19.17 19.17 0 0 1-3.277-14.503 18 18 0 0 1 .624-2.435l.49-1.498 1.337.981a33.6 33.6 0 0 0 10.203 5.098l.97.294-.09.968a5.85 5.85 0 0 0 1.052 3.878 6.24 6.24 0 0 0 6.695 2.485 5.8 5.8 0 0 0 1.603-.704L69.27 76.28a5.43 5.43 0 0 0 2.45-3.631 5.8 5.8 0 0 0-.987-4.371 6.24 6.24 0 0 0-6.698-2.487 5.7 5.7 0 0 0-1.6.704l-9.953 6.345a19 19 0 0 1-5.296 2.326 20.72 20.72 0 0 1-22.237-8.243 19.17 19.17 0 0 1-3.277-14.502 17.99 17.99 0 0 1 8.13-12.052l26.081-16.623a19 19 0 0 1 5.3-2.329 20.72 20.72 0 0 1 22.237 8.243 19.17 19.17 0 0 1 3.277 14.503 18 18 0 0 1-.624 2.435l-.49 1.498-1.337-.98a33.6 33.6 0 0 0-10.203-5.1l-.97-.294.09-.968a5.86 5.86 0 0 0-1.052-3.878 6.24 6.24 0 0 0-6.696-2.485 5.8 5.8 0 0 0-1.602.704L37.73 51.72a5.42 5.42 0 0 0-2.449 3.63 5.79 5.79 0 0 0 .986 4.372 6.24 6.24 0 0 0 6.698 2.486 5.8 5.8 0 0 0 1.602-.704l9.952-6.342a19 19 0 0 1 5.295-2.328 20.72 20.72 0 0 1 22.237 8.242 19.17 19.17 0 0 1 3.277 14.503 18 18 0 0 1-8.13 12.053l-26.081 16.622a19 19 0 0 1-5.3 2.328" style="fill:#fff"/></svg>

hub/admin-web/src/lib/components/CheckboxControl.svelte

@@ -0,0 +1,32 @@
+<script lang="ts">
+	import { Checkbox } from 'bits-ui';
+	import Icon from './Icon.svelte';
+
+	let {
+		checked = $bindable(false),
+		disabled = false,
+		class: className = '',
+		onchange,
+	}: {
+		checked?: boolean;
+		disabled?: boolean;
+		class?: string;
+		onchange?: (checked: boolean) => void;
+	} = $props();
+</script>
+
+<Checkbox.Root
+	class="saas-checkbox {className}"
+	{disabled}
+	{checked}
+	onCheckedChange={(next) => {
+		checked = next;
+		onchange?.(next);
+	}}
+>
+	{#snippet children({ checked: isChecked })}
+		{#if isChecked}
+			<Icon name="check" class="h-3.5 w-3.5" />
+		{/if}
+	{/snippet}
+</Checkbox.Root>

hub/admin-web/src/lib/components/EmptyState.svelte

@@ -0,0 +1,32 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	let {
+		title = '暂无数据',
+		description,
+		action,
+	}: {
+		title?: string;
+		description?: string;
+		action?: Snippet;
+	} = $props();
+</script>
+
+<div class="saas-empty">
+	<div
+		class="mb-1 flex h-12 w-12 items-center justify-center border border-surface-300 bg-surface-100 text-surface-600"
+	>
+		<svg class="h-6 w-6" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+			<path stroke-linecap="round" stroke-linejoin="round" d="M3.75 6.75h16.5M3.75 12h16.5m-16.5 5.25H12" />
+		</svg>
+	</div>
+	<p class="text-sm font-medium text-surface-900">{title}</p>
+	{#if description}
+		<p class="max-w-sm text-sm text-surface-600">{description}</p>
+	{/if}
+	{#if action}
+		<div class="mt-2">
+			{@render action()}
+		</div>
+	{/if}
+</div>

hub/admin-web/src/lib/components/ErrorBanner.svelte

@@ -0,0 +1,26 @@
+<script lang="ts">
+	let {
+		message,
+		onretry,
+	}: {
+		message: string;
+		onretry?: () => void;
+	} = $props();
+</script>
+
+<div class="saas-card flex flex-wrap items-start gap-3 border-error-200 bg-error-50 p-4 text-error-700">
+	<svg class="mt-0.5 h-5 w-5 shrink-0" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M12 9v3.75m9-.75a9 9 0 11-18 0 9 9 0 0118 0zm-9 3.75h.008v.008H12v-.008z"
+		/>
+	</svg>
+	<div class="min-w-0 flex-1">
+		<p class="text-sm font-medium">请求失败</p>
+		<p class="mt-0.5 text-sm opacity-90">{message}</p>
+	</div>
+	{#if onretry}
+		<button type="button" class="saas-btn-ghost text-sm" onclick={onretry}>重试</button>
+	{/if}
+</div>

hub/admin-web/src/lib/components/FolderNode.svelte

@@ -0,0 +1,78 @@
+<script lang="ts">
+	import type { ExplorerFolder } from '$lib/api';
+	import Icon from './Icon.svelte';
+	import FolderTree from './FolderTree.svelte';
+
+	let {
+		folder,
+		folders,
+		projects,
+		slug,
+		onCreateFolder,
+		onCreateProject,
+	}: {
+		folder: ExplorerFolder;
+		folders: ExplorerFolder[];
+		projects: {
+			id: string;
+			name: string;
+			folderId: string | null;
+			createdAt: string;
+			binding: { chatId: string } | null;
+		}[];
+		slug: string;
+		onCreateFolder?: (parentId: string) => void;
+		onCreateProject?: (folderId: string) => void;
+	} = $props();
+
+	let open = $state(true);
+</script>
+
+<div>
+	<div class="group flex w-full items-center gap-2.5 px-3 py-2.5 text-sm transition hover:bg-surface-100">
+		<button type="button" class="flex min-w-0 flex-1 items-center gap-2.5 text-left" onclick={() => (open = !open)}>
+			<span class="w-3.5 text-center text-xs text-surface-600">{open ? '▾' : '▸'}</span>
+			<span class="flex h-7 w-7 items-center justify-center border border-warning-300 bg-warning-50 text-warning-800">
+				<Icon name="folder" class="h-4 w-4" />
+			</span>
+			<span class="min-w-0 flex-1 truncate font-medium text-surface-900">{folder.name}</span>
+			<span class="saas-badge-neutral">{folder.projectCount} 项目</span>
+			{#if folder.childFolderCount > 0}
+				<span class="saas-badge-neutral">{folder.childFolderCount} 子夹</span>
+			{/if}
+		</button>
+		{#if onCreateFolder || onCreateProject}
+			<span
+				class="flex shrink-0 items-center gap-1 opacity-0 transition group-hover:opacity-100 focus-within:opacity-100"
+			>
+				{#if onCreateFolder}
+					<button
+						type="button"
+						class="flex h-6 w-6 items-center justify-center border border-surface-300 bg-surface-50 text-surface-600 transition hover:border-primary-400 hover:text-primary-700"
+						title="在此新建子文件夹"
+						aria-label="在 {folder.name} 内新建子文件夹"
+						onclick={() => onCreateFolder(folder.id)}
+					>
+						<Icon name="folder-plus" class="h-4 w-4" />
+					</button>
+				{/if}
+				{#if onCreateProject}
+					<button
+						type="button"
+						class="flex h-6 w-6 items-center justify-center border border-surface-300 bg-surface-50 text-surface-600 transition hover:border-primary-400 hover:text-primary-700"
+						title="在此新建项目"
+						aria-label="在 {folder.name} 内新建项目"
+						onclick={() => onCreateProject(folder.id)}
+					>
+						<Icon name="file-plus" class="h-4 w-4" />
+					</button>
+				{/if}
+			</span>
+		{/if}
+	</div>
+	{#if open}
+		<div class="ml-4 border-l border-surface-300 pl-2">
+			<FolderTree {folders} {projects} parentId={folder.id} {slug} {onCreateFolder} {onCreateProject} />
+		</div>
+	{/if}
+</div>

hub/admin-web/src/lib/components/FolderTree.svelte

@@ -0,0 +1,53 @@
+<script lang="ts">
+	import type { ExplorerFolder } from '$lib/api';
+	import { fmtDate } from '$lib/format';
+	import Icon from './Icon.svelte';
+	import FolderNode from './FolderNode.svelte';
+
+	let {
+		folders,
+		projects,
+		parentId,
+		slug,
+		onCreateFolder,
+		onCreateProject,
+	}: {
+		folders: ExplorerFolder[];
+		projects: {
+			id: string;
+			name: string;
+			folderId: string | null;
+			createdAt: string;
+			binding: { chatId: string } | null;
+		}[];
+		parentId: string | null;
+		slug: string;
+		onCreateFolder?: (parentId: string) => void;
+		onCreateProject?: (folderId: string) => void;
+	} = $props();
+
+	let childFolders = $derived(folders.filter((f) => f.parentId === parentId));
+	let childProjects = $derived(projects.filter((p) => p.folderId === parentId));
+</script>
+
+<div class="space-y-0.5">
+	{#each childProjects as p (p.id)}
+		<a
+			href={`/admin/projects/${p.id}`}
+			class="flex items-center gap-2.5 px-3 py-2.5 text-sm transition hover:bg-surface-100"
+		>
+			<span class="flex h-7 w-7 items-center justify-center border border-primary-200 bg-primary-50 text-primary-700">
+				<Icon name="file" class="h-4 w-4" />
+			</span>
+			<span class="min-w-0 flex-1 truncate font-medium text-surface-900">{p.name}</span>
+			{#if p.binding}
+				<span class="saas-badge-success">已绑定</span>
+			{/if}
+			<span class="hidden text-xs text-surface-600 sm:inline">{fmtDate(p.createdAt)}</span>
+		</a>
+	{/each}
+
+	{#each childFolders as f (f.id)}
+		<FolderNode folder={f} {folders} {projects} {slug} {onCreateFolder} {onCreateProject} />
+	{/each}
+</div>

hub/admin-web/src/lib/components/Icon.svelte

@@ -0,0 +1,155 @@
+<script lang="ts">
+	/** Inline nav icons for the admin shell. */
+	let {
+		name,
+		class: className = 'h-4 w-4',
+	}: {
+		name:
+			| 'overview'
+			| 'members'
+			| 'teams'
+			| 'projects'
+			| 'provider'
+			| 'feishu'
+			| 'menu'
+			| 'logout'
+			| 'org'
+			| 'chevron'
+			| 'arrow-left'
+			| 'folder'
+			| 'file'
+			| 'folder-plus'
+			| 'file-plus'
+			| 'check'
+			| 'roles';
+		class?: string;
+	} = $props();
+</script>
+
+{#if name === 'overview'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M3 12l9-9 9 9M5 10v9a1 1 0 001 1h3v-5h6v5h3a1 1 0 001-1v-9"
+		/>
+	</svg>
+{:else if name === 'members'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M15.75 7.5a3.75 3.75 0 11-7.5 0 3.75 3.75 0 017.5 0zM4.5 19.5a7.5 7.5 0 0115 0"
+		/>
+	</svg>
+{:else if name === 'teams'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M18 18.72a9.09 9.09 0 003.74-.72 9 9 0 00-5.07-5.95M15 11a4 4 0 10-8 0 4 4 0 008 0zM4.26 18a9 9 0 0115.48 0"
+		/>
+	</svg>
+{:else if name === 'projects'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M3.75 6.75A2.25 2.25 0 016 4.5h3.379c.6 0 1.175.238 1.6.66l.842.84c.424.423 1 .66 1.6.66H18A2.25 2.25 0 0120.25 9v8.25A2.25 2.25 0 0118 19.5H6a2.25 2.25 0 01-2.25-2.25V6.75z"
+		/>
+	</svg>
+{:else if name === 'provider'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M13.19 8.688a4.5 4.5 0 016.364 6.364l-3.182 3.182a4.5 4.5 0 01-6.364-6.364"
+		/>
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M10.81 15.312a4.5 4.5 0 01-6.364-6.364l3.182-3.182a4.5 4.5 0 016.364 6.364"
+		/>
+	</svg>
+{:else if name === 'feishu'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M4.5 8.25h15a8.25 8.25 0 01-8.25 8.25A8.25 8.25 0 014.5 8.25z"
+		/>
+		<path stroke-linecap="round" stroke-linejoin="round" d="M8.25 11.25h.01M12 11.25h.01M15.75 11.25h.01" />
+	</svg>
+{:else if name === 'menu'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path stroke-linecap="round" stroke-linejoin="round" d="M3.75 6.75h16.5M3.75 12h16.5m-16.5 5.25h16.5" />
+	</svg>
+{:else if name === 'logout'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M15.75 9V5.25A2.25 2.25 0 0013.5 3h-6A2.25 2.25 0 005.25 5.25v13.5A2.25 2.25 0 007.5 21h6a2.25 2.25 0 002.25-2.25V15M12 9l3 3m0 0l-3 3m3-3H6"
+		/>
+	</svg>
+{:else if name === 'org'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M3.75 21h16.5M4.5 3h15M5.25 3v18m13.5-18v18M9 6.75h1.5m-1.5 3h1.5m-1.5 3h1.5m3-6H15m-1.5 3H15m-1.5 3H15M9 21v-3.375c0-.621.504-1.125 1.125-1.125h3.75c.621 0 1.125.504 1.125 1.125V21"
+		/>
+	</svg>
+{:else if name === 'chevron'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path stroke-linecap="round" stroke-linejoin="round" d="M8.25 4.5l7.5 7.5-7.5 7.5" />
+	</svg>
+{:else if name === 'arrow-left'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path stroke-linecap="round" stroke-linejoin="round" d="M10.5 19.5L3 12m0 0l7.5-7.5M3 12h18" />
+	</svg>
+{:else if name === 'folder'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M3.75 6.75A2.25 2.25 0 016 4.5h3.379c.6 0 1.175.238 1.6.66l.842.84c.424.423 1 .66 1.6.66H18A2.25 2.25 0 0120.25 9v8.25A2.25 2.25 0 0118 19.5H6a2.25 2.25 0 01-2.25-2.25V6.75z"
+		/>
+	</svg>
+{:else if name === 'file'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M19.5 14.25v-2.625a3.375 3.375 0 00-3.375-3.375h-1.5A1.125 1.125 0 0113.5 7.125v-1.5a3.375 3.375 0 00-3.375-3.375H8.25m0 12.75h7.5m-7.5 3H12M10.5 2.25H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 00-9-9z"
+		/>
+	</svg>
+{:else if name === 'folder-plus'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M12 10.5v6m3-3H9m4.06-7.19l-2.12-2.12a1.5 1.5 0 00-1.061-.44H4.5A2.25 2.25 0 002.25 6v12a2.25 2.25 0 002.25 2.25h15A2.25 2.25 0 0021.75 18V9a2.25 2.25 0 00-2.25-2.25h-5.379a1.5 1.5 0 01-1.06-.44z"
+		/>
+	</svg>
+{:else if name === 'file-plus'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M19.5 14.25v-2.625a3.375 3.375 0 00-3.375-3.375h-1.5A1.125 1.125 0 0113.5 7.125v-1.5a3.375 3.375 0 00-3.375-3.375H8.25m3.75 9v6m3-3H9m1.5-12H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 00-9-9z"
+		/>
+	</svg>
+{:else if name === 'check'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path stroke-linecap="round" stroke-linejoin="round" d="M4.5 12.75l6 6 9-13.5" />
+	</svg>
+{:else if name === 'roles'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M9.813 15.904L9 18.75l-.813-2.846a4.5 4.5 0 00-3.09-3.09L2.25 12l2.847-.813a4.5 4.5 0 003.09-3.09L9 5.25l.813 2.846a4.5 4.5 0 003.09 3.09L15.75 12l-2.847.813a4.5 4.5 0 00-3.09 3.09zM18.259 8.715L18 9.75l-.259-1.035a3.375 3.375 0 00-2.456-2.456L14.25 6l1.035-.259a3.375 3.375 0 002.456-2.456L18 2.25l.259 1.035a3.375 3.375 0 002.456 2.456L21.75 6l-1.035.259a3.375 3.375 0 00-2.456 2.456zM16.894 20.567L16.5 21.75l-.394-1.183a2.25 2.25 0 00-1.423-1.423L13.5 18.75l1.183-.394a2.25 2.25 0 001.423-1.423l.394-1.183.394 1.183a2.25 2.25 0 001.423 1.423l1.183.394-1.183.394a2.25 2.25 0 00-1.423 1.423z"
+		/>
+	</svg>
+{/if}

hub/admin-web/src/lib/components/LoadingState.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+	let { label = '加载中…' }: { label?: string } = $props();
+</script>
+
+<div class="flex flex-col items-center justify-center gap-3 py-16 text-surface-600">
+	<svg class="h-7 w-7 animate-spin text-primary-500" viewBox="0 0 24 24" fill="none">
+		<circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+		<path
+			class="opacity-90"
+			fill="currentColor"
+			d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+		></path>
+	</svg>
+	<p class="text-sm">{label}</p>
+</div>

hub/admin-web/src/lib/components/Modal.svelte

@@ -0,0 +1,38 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import { Dialog } from 'bits-ui';
+
+	let {
+		open = $bindable(false),
+		title,
+		children,
+		onclose,
+	}: {
+		open?: boolean;
+		title: string;
+		children: Snippet;
+		onclose?: () => void;
+	} = $props();
+</script>
+
+<Dialog.Root
+	bind:open
+	onOpenChange={(next) => {
+		if (!next) onclose?.();
+	}}
+>
+	<Dialog.Portal>
+		<Dialog.Overlay class="saas-modal-backdrop" />
+		<Dialog.Content class="saas-modal">
+			<div class="mb-4 flex items-start justify-between gap-3">
+				<Dialog.Title class="text-lg font-semibold text-surface-900">{title}</Dialog.Title>
+				<Dialog.Close class="saas-btn-ghost px-2! py-1! text-surface-600" aria-label="关闭">
+					<svg class="h-5 w-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+						<path stroke-linecap="round" stroke-linejoin="round" d="M6 18L18 6M6 6l12 12" />
+					</svg>
+				</Dialog.Close>
+			</div>
+			{@render children()}
+		</Dialog.Content>
+	</Dialog.Portal>
+</Dialog.Root>

hub/admin-web/src/lib/components/PageHeader.svelte

@@ -0,0 +1,27 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	let {
+		title,
+		description,
+		actions,
+	}: {
+		title: string;
+		description?: string;
+		actions?: Snippet;
+	} = $props();
+</script>
+
+<div class="saas-toolbar">
+	<div class="min-w-0">
+		<h1 class="saas-page-title">{title}</h1>
+		{#if description}
+			<p class="saas-muted mt-1">{description}</p>
+		{/if}
+	</div>
+	{#if actions}
+		<div class="ml-auto flex flex-wrap items-center gap-2">
+			{@render actions()}
+		</div>
+	{/if}
+</div>

hub/admin-web/src/lib/components/RoleCard.svelte

@@ -0,0 +1,208 @@
+<script lang="ts">
+	import { Checkbox, Label } from 'bits-ui';
+	import type { AgentRoleRow, AgentModelRow, AgentSkillRow } from '$lib/api';
+	import { api } from '$lib/api';
+	import { fmtDate } from '$lib/format';
+	import { TOOL_OPTIONS } from '$lib/constants';
+	import SelectField from '$lib/components/SelectField.svelte';
+	import CheckboxControl from '$lib/components/CheckboxControl.svelte';
+	import Icon from '$lib/components/Icon.svelte';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	let {
+		r,
+		models,
+		skills,
+		slug,
+		onupdated,
+		onskillschanged,
+	}: {
+		r: AgentRoleRow;
+		models: AgentModelRow[];
+		skills: AgentSkillRow[];
+		slug: string;
+		onupdated: (updated: AgentRoleRow) => void;
+		onskillschanged: (roleId: string, skillNames: string[]) => void;
+	} = $props();
+
+	const initial = {
+		label: r.label,
+		defaultModel: r.defaultModel ?? '',
+		systemPrompt: r.systemPrompt ?? '',
+		unrestricted: r.tools === null,
+		tools: r.tools ?? [],
+		sortOrder: String(r.sortOrder),
+		isDefault: r.isDefault,
+		skillNames: r.skillNames,
+	};
+	let label = $state(initial.label);
+	let defaultModel = $state(initial.defaultModel);
+	let systemPrompt = $state(initial.systemPrompt);
+	let unrestricted = $state(initial.unrestricted);
+	let selectedTools = $state<string[]>([...initial.tools]);
+	let sortOrder = $state(initial.sortOrder);
+	let isDefault = $state(initial.isDefault);
+	let selectedSkills = $state<string[]>([...initial.skillNames]);
+	let saving = $state(false);
+
+	const groupedTools = TOOL_OPTIONS.reduce(
+		(acc, t) => {
+			(acc[t.group] ??= []).push(t);
+			return acc;
+		},
+		{} as Record<string, typeof TOOL_OPTIONS>,
+	);
+
+	const modelItems = $derived([
+		{ value: '', label: '（使用平台默认模型）' },
+		...models.map((m) => ({ value: m.id, label: `${m.label}（${m.id}）` })),
+	]);
+
+	const skillItems = $derived(skills.map((s) => ({ value: s.name, label: s.name })));
+
+	function skillsDirty(): boolean {
+		const a = [...selectedSkills].sort();
+		const b = [...r.skillNames].sort();
+		return a.length !== b.length || a.some((v, i) => v !== b[i]);
+	}
+
+	async function save() {
+		const trimmedLabel = label.trim();
+		if (trimmedLabel === '') {
+			toastError('显示名不能为空');
+			return;
+		}
+		const order = Number(sortOrder);
+		if (sortKeyDirty() && (!Number.isSafeInteger(order) || order < 0)) {
+			toastError('排序必须为非负整数');
+			return;
+		}
+		saving = true;
+		const tools = unrestricted ? null : selectedTools;
+		try {
+			const updated = await api.upsertAgentRole(slug, r.roleId, {
+				label: trimmedLabel,
+				defaultModel: defaultModel === '' ? null : defaultModel,
+				systemPrompt: systemPrompt === '' ? null : systemPrompt,
+				tools,
+				...(sortKeyDirty() ? { sortOrder: order } : {}),
+				isDefault,
+			});
+			onupdated(updated);
+			if (skillsDirty()) {
+				const res = await api.setAgentRoleSkills(slug, r.roleId, selectedSkills);
+				selectedSkills = [...res.skillNames];
+				onskillschanged(r.roleId, res.skillNames);
+			}
+			toastSuccess('角色已保存');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			saving = false;
+		}
+	}
+
+	function sortKeyDirty(): boolean {
+		return Number(sortOrder) !== r.sortOrder;
+	}
+</script>
+
+<div class="saas-card-pad">
+	<div class="mb-4 flex flex-wrap items-center gap-2">
+		<span class="saas-badge-primary font-mono">/{r.roleId}</span>
+		<span class="text-sm text-surface-700">{label || r.label}</span>
+		{#if r.isDefault}
+			<span class="saas-badge-success">默认</span>
+		{/if}
+	</div>
+
+	<div class="grid grid-cols-1 gap-4 md:grid-cols-2">
+		<div>
+			<Label.Root for="role-label-{r.id}" class="saas-label">显示名</Label.Root>
+			<input id="role-label-{r.id}" class="saas-input" bind:value={label} />
+		</div>
+		<div>
+			<Label.Root for="role-sort-{r.id}" class="saas-label">排序</Label.Root>
+			<input id="role-sort-{r.id}" class="saas-input" type="number" min="0" bind:value={sortOrder} />
+		</div>
+	</div>
+
+	<div class="mt-4">
+		<p class="saas-label">默认模型</p>
+		<SelectField items={modelItems} bind:value={defaultModel} />
+	</div>
+
+	<div class="mt-4">
+		<span class="saas-label">工具白名单</span>
+		<label class="mb-3 flex cursor-pointer items-center gap-2 border border-surface-300 bg-surface-100 px-3 py-2">
+			<CheckboxControl bind:checked={unrestricted} />
+			<span class="text-sm">不限（使用全部注册工具）</span>
+		</label>
+		<div class="space-y-3 {unrestricted ? 'pointer-events-none opacity-40' : ''}">
+			<Checkbox.Group bind:value={selectedTools} disabled={unrestricted}>
+				{#each Object.entries(groupedTools) as [group, tools]}
+					<div>
+						<p class="mb-1.5 text-xs font-semibold uppercase tracking-wide text-surface-600">{group}</p>
+						<div class="grid grid-cols-1 gap-1.5 sm:grid-cols-2">
+							{#each tools as t}
+								<label class="flex cursor-pointer items-center gap-2 px-2 py-1.5 text-sm hover:bg-surface-100">
+									<Checkbox.Root class="saas-checkbox" value={t.id} id={`tool-${r.id}-${t.id}`}>
+										{#snippet children({ checked })}
+											{#if checked}
+												<Icon name="check" class="h-3.5 w-3.5" />
+											{/if}
+										{/snippet}
+									</Checkbox.Root>
+									<span>{t.label}</span>
+								</label>
+							{/each}
+						</div>
+					</div>
+				{/each}
+			</Checkbox.Group>
+		</div>
+	</div>
+
+	<div class="mt-4">
+		<span class="saas-label">技能绑定</span>
+		{#if skills.length === 0}
+			<p class="text-sm text-surface-600">组织内暂无已安装技能。技能通过 CLI / seed 安装（ADR-0018）。</p>
+		{:else}
+			<div class="grid grid-cols-1 gap-1.5 sm:grid-cols-2">
+				{#each skillItems as s}
+					<label class="flex cursor-pointer items-center gap-2 px-2 py-1.5 text-sm hover:bg-surface-100">
+						<CheckboxControl
+							checked={selectedSkills.includes(s.value)}
+							onchange={(checked) => {
+								selectedSkills = checked ? [...selectedSkills, s.value] : selectedSkills.filter((x) => x !== s.value);
+							}}
+						/>
+						<span class="font-mono text-xs">{s.label}</span>
+					</label>
+				{/each}
+			</div>
+		{/if}
+	</div>
+
+	<div class="mt-4">
+		<Label.Root for="role-prompt-{r.id}" class="saas-label">系统提示词</Label.Root>
+		<textarea
+			id="role-prompt-{r.id}"
+			class="saas-textarea"
+			rows="4"
+			placeholder="系统提示词（可选）。会话开始时注入，定义智能体人格/指令。"
+			bind:value={systemPrompt}></textarea>
+	</div>
+
+	<div class="mt-4 flex flex-wrap items-center gap-3 border-t border-surface-100 pt-4">
+		<label class="flex cursor-pointer items-center gap-2">
+			<CheckboxControl bind:checked={isDefault} />
+			<span class="text-sm">设为组织默认角色</span>
+		</label>
+		<span class="text-xs text-surface-600">更新于 {fmtDate(r.updatedAt)}</span>
+		<div class="flex-1"></div>
+		<button class="saas-btn-primary" onclick={save} disabled={saving}>
+			{saving ? '保存中…' : '保存'}
+		</button>
+	</div>
+</div>

hub/admin-web/src/lib/components/SelectField.svelte

@@ -0,0 +1,66 @@
+<script lang="ts">
+	import { Select } from 'bits-ui';
+	import Icon from './Icon.svelte';
+
+	export type SelectItem = { label: string; value: string; disabled?: boolean };
+
+	let {
+		items,
+		value = $bindable(''),
+		class: className = '',
+		disabled = false,
+		placeholder = '请选择…',
+		onchange,
+	}: {
+		items: SelectItem[];
+		value?: string;
+		class?: string;
+		disabled?: boolean;
+		placeholder?: string;
+		onchange?: (value: string) => void;
+	} = $props();
+</script>
+
+<Select.Root
+	type="single"
+	{items}
+	{disabled}
+	{value}
+	onValueChange={(next) => {
+		value = next;
+		onchange?.(next);
+	}}
+>
+	<Select.Trigger class="saas-select-trigger {className}" {disabled}>
+		<span class="min-w-0 flex-1 truncate text-left">
+			<Select.Value {placeholder} />
+		</span>
+		<svg
+			class="ml-2 h-4 w-4 shrink-0 text-surface-600"
+			viewBox="0 0 24 24"
+			fill="none"
+			stroke="currentColor"
+			stroke-width="1.75"
+			aria-hidden="true"
+		>
+			<path stroke-linecap="round" stroke-linejoin="round" d="M8.25 15l3.75 3.75L15.75 15" />
+			<path stroke-linecap="round" stroke-linejoin="round" d="M8.25 9l3.75-3.75L15.75 9" />
+		</svg>
+	</Select.Trigger>
+	<Select.Portal>
+		<Select.Content class="saas-select-content" sideOffset={6} collisionPadding={8}>
+			<Select.Viewport class="p-1">
+				{#each items as item (item.value)}
+					<Select.Item class="saas-select-item" value={item.value} label={item.label} disabled={item.disabled}>
+						{#snippet children({ selected })}
+							<span class="min-w-0 flex-1 truncate">{item.label}</span>
+							{#if selected}
+								<Icon name="check" class="ml-2 h-4 w-4 shrink-0 text-primary-600" />
+							{/if}
+						{/snippet}
+					</Select.Item>
+				{/each}
+			</Select.Viewport>
+		</Select.Content>
+	</Select.Portal>
+</Select.Root>

hub/admin-web/src/lib/components/SkillEditor.svelte

@@ -0,0 +1,305 @@
+<script lang="ts">
+	import type { AgentSkillRow, SkillFileEntry } from '$lib/api';
+	import { api } from '$lib/api';
+	import { fmtDate } from '$lib/format';
+	import Icon from '$lib/components/Icon.svelte';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	let {
+		slug,
+		skill,
+		oninstalled,
+		ondisabled,
+	}: {
+		slug: string;
+		skill: AgentSkillRow;
+		oninstalled: (result: { id: string; name: string; contentDigest: string }) => void;
+		ondisabled: (name: string) => void;
+	} = $props();
+
+	type FileNode = { path: string; content: string };
+
+	let files = $state<FileNode[]>([]);
+	let selectedPath = $state<string | null>(null);
+	let version = $state(skill.version);
+	let description = $state(skill.description ?? '');
+	let loading = $state(false);
+	let saving = $state(false);
+	let dirty = $state(false);
+	let newFilePath = $state('');
+	let showNewFile = $state(false);
+
+	const selectedFile = $derived(files.find((f) => f.path === selectedPath) ?? null);
+	const hasManifest = $derived(files.some((f) => f.path === 'SKILL.md'));
+	const sortedFiles = $derived([...files].sort((a, b) => a.path.localeCompare(b.path)));
+
+	async function loadFiles() {
+		loading = true;
+		try {
+			const res = await api.agentSkillFiles(slug, skill.name);
+			files = res.files.map((f) => ({ path: f.path, content: f.content }));
+			if (files.length > 0 && selectedPath === null) {
+				selectedPath = files[0]!.path;
+			}
+			dirty = false;
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			loading = false;
+		}
+	}
+
+	function selectFile(path: string) {
+		selectedPath = path;
+	}
+
+	function updateContent(path: string, content: string) {
+		const file = files.find((f) => f.path === path);
+		if (file) {
+			file.content = content;
+			dirty = true;
+			if (path === 'SKILL.md') {
+				const desc = parseDescription(content);
+				if (desc !== null) description = desc;
+			}
+		}
+	}
+
+	function addFile() {
+		const path = newFilePath.trim();
+		if (path === '') {
+			toastError('文件路径不能为空');
+			return;
+		}
+		if (files.some((f) => f.path === path)) {
+			toastError(`文件已存在：${path}`);
+			return;
+		}
+		if (path.startsWith('/') || path.includes('..')) {
+			toastError('文件路径必须为相对路径');
+			return;
+		}
+		files.push({ path, content: '' });
+		selectedPath = path;
+		newFilePath = '';
+		showNewFile = false;
+		dirty = true;
+	}
+
+	function deleteFile(path: string) {
+		if (path === 'SKILL.md') {
+			toastError('SKILL.md 是必需的 manifest，不能删除');
+			return;
+		}
+		files = files.filter((f) => f.path !== path);
+		if (selectedPath === path) {
+			selectedPath = files.length > 0 ? files[0]!.path : null;
+		}
+		dirty = true;
+	}
+
+	function parseDescription(manifest: string): string | null {
+		const match = /^description:\s*['"]?([^'"\r\n]+)['"]?\s*$/m.exec(manifest);
+		return match ? match[1]!.trim() : null;
+	}
+
+	async function save() {
+		if (!hasManifest) {
+			toastError('缺少 SKILL.md manifest 文件');
+			return;
+		}
+		const trimmedVersion = version.trim();
+		if (trimmedVersion === '') {
+			toastError('版本号不能为空');
+			return;
+		}
+		saving = true;
+		try {
+			const fileEntries: SkillFileEntry[] = files.map((f) => ({ path: f.path, content: f.content }));
+			const result = await api.installAgentSkill(slug, skill.name, {
+				version: trimmedVersion,
+				files: fileEntries,
+			});
+			dirty = false;
+			toastSuccess('技能已保存');
+			oninstalled(result);
+			await loadFiles();
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			saving = false;
+		}
+	}
+
+	async function disable() {
+		saving = true;
+		try {
+			await api.patchAgentSkill(slug, skill.name, { disabled: true });
+			toastSuccess('技能已禁用');
+			ondisabled(skill.name);
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			saving = false;
+		}
+	}
+
+	function saveDescription() {
+		const manifest = files.find((f) => f.path === 'SKILL.md');
+		if (!manifest) return;
+		const updated = updateFrontmatter(manifest.content, 'description', description.trim());
+		manifest.content = updated;
+		dirty = true;
+	}
+
+	function updateFrontmatter(content: string, key: string, value: string): string {
+		const regex = new RegExp(`^(${key}:\\s*)(.*?)(\\s*)$`, 'm');
+		if (regex.test(content)) {
+			return content.replace(regex, `${key}: ${value}`);
+		}
+		const lines = content.split('\n');
+		if (lines[0] === '---') {
+			lines.splice(1, 0, `${key}: ${value}`);
+		} else {
+			lines.unshift('---', `${key}: ${value}`, '---');
+		}
+		return lines.join('\n');
+	}
+
+	$effect(() => {
+		if (skill.name) loadFiles();
+	});
+</script>
+
+<div class="saas-card-pad">
+	<div class="mb-4 flex flex-wrap items-center gap-2">
+		<span class="saas-badge-primary font-mono">{skill.name}</span>
+		<span class="text-sm text-surface-700">v{skill.version}</span>
+		{#if skill.disabledAt}
+			<span class="saas-badge-error">已禁用</span>
+		{/if}
+	</div>
+
+	<div class="mb-4 grid grid-cols-1 gap-4 md:grid-cols-2">
+		<div>
+			<label for="skill-version-{skill.id}" class="saas-label">版本号</label>
+			<input id="skill-version-{skill.id}" class="saas-input" bind:value={version} placeholder="如 0.1.0" />
+		</div>
+		<div>
+			<label for="skill-desc-{skill.id}" class="saas-label">描述（同步到 SKILL.md frontmatter）</label>
+			<div class="flex gap-2">
+				<input id="skill-desc-{skill.id}" class="saas-input" bind:value={description} onchange={saveDescription} />
+			</div>
+		</div>
+	</div>
+
+	<div class="mb-4 flex flex-wrap items-center gap-2 text-xs text-surface-600">
+		<span>digest: <code class="font-mono">{skill.contentDigest.slice(0, 12)}</code></span>
+		<span>·</span>
+		<span>更新于 {fmtDate(skill.updatedAt)}</span>
+		{#if skill.boundRoleIds.length > 0}
+			<span>·</span>
+			<span>绑定角色: {skill.boundRoleIds.join(', ')}</span>
+		{/if}
+		{#if dirty}
+			<span>·</span>
+			<span class="font-medium text-warning-700">未保存</span>
+		{/if}
+	</div>
+
+	{#if loading}
+		<div class="py-8 text-center text-sm text-surface-600">加载文件中…</div>
+	{:else}
+		<div class="grid grid-cols-1 gap-4 md:grid-cols-[16rem_1fr]">
+			<div class="border border-surface-300 bg-surface-100">
+				<div class="flex items-center justify-between border-b border-surface-300 px-3 py-2">
+					<span class="text-xs font-medium text-surface-700">文件</span>
+					<button
+						type="button"
+						class="text-xs text-primary-700 hover:text-primary-900"
+						onclick={() => (showNewFile = !showNewFile)}
+					>
+						{showNewFile ? '取消' : '+ 新增'}
+					</button>
+				</div>
+				{#if showNewFile}
+					<div class="border-b border-surface-300 px-3 py-2">
+						<input
+							class="saas-input text-xs"
+							placeholder="如 reference.md"
+							bind:value={newFilePath}
+							onkeydown={(e) => {
+								if (e.key === 'Enter') addFile();
+							}}
+						/>
+					</div>
+				{/if}
+				<div class="max-h-80 overflow-y-auto">
+					{#each sortedFiles as f (f.path)}
+						<button
+							type="button"
+							class="flex w-full items-center gap-2 px-3 py-1.5 text-left text-sm transition hover:bg-surface-200
+								{selectedPath === f.path ? 'bg-primary-100 text-primary-900' : 'text-surface-800'}"
+							onclick={() => selectFile(f.path)}
+						>
+							<Icon name="file" class="h-3.5 w-3.5 shrink-0 opacity-60" />
+							<span class="truncate font-mono text-xs">{f.path}</span>
+							{#if f.path === 'SKILL.md'}
+								<span class="ml-auto text-[10px] text-primary-700">manifest</span>
+							{:else}
+								<span
+									class="ml-auto text-xs text-surface-500 hover:text-error-700"
+									role="button"
+									tabindex="0"
+									onclick={(e) => {
+										e.stopPropagation();
+										deleteFile(f.path);
+									}}
+									onkeydown={(e) => {
+										if (e.key === 'Enter' || e.key === ' ') {
+											e.stopPropagation();
+											deleteFile(f.path);
+										}
+									}}
+								>
+									×
+								</span>
+							{/if}
+						</button>
+					{/each}
+					{#if files.length === 0}
+						<div class="px-3 py-4 text-center text-xs text-surface-600">暂无文件</div>
+					{/if}
+				</div>
+			</div>
+
+			<div>
+				{#if selectedFile}
+					<div class="mb-2 flex items-center gap-2">
+						<span class="font-mono text-xs text-surface-600">{selectedFile.path}</span>
+					</div>
+					<textarea
+						class="h-80 w-full resize-y border border-surface-300 bg-white p-3 font-mono text-xs text-surface-900 focus:border-primary-500 focus:outline-none"
+						bind:value={selectedFile.content}
+						oninput={() => (dirty = true)}
+					></textarea>
+				{:else}
+					<div class="flex h-80 items-center justify-center border border-surface-300 bg-surface-100 text-sm text-surface-600">
+						选择一个文件或新建文件
+					</div>
+				{/if}
+			</div>
+		</div>
+
+		<div class="mt-4 flex flex-wrap items-center gap-3 border-t border-surface-100 pt-4">
+			<button class="saas-btn-primary" onclick={save} disabled={saving || !dirty}>
+				{saving ? '保存中…' : '保存'}
+			</button>
+			{#if !skill.disabledAt}
+				<button class="saas-btn-danger" onclick={disable} disabled={saving}>
+					禁用
+				</button>
+			{/if}
+		</div>
+	{/if}
+</div>

hub/admin-web/src/lib/components/StatCard.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+	let {
+		label,
+		value,
+		hint,
+	}: {
+		label: string;
+		value: string;
+		hint?: string;
+	} = $props();
+</script>
+
+<div class="saas-stat">
+	<div class="saas-stat-label">{label}</div>
+	<div class="saas-stat-value">{value}</div>
+	{#if hint}
+		<div class="saas-help">{hint}</div>
+	{/if}
+</div>

hub/admin-web/src/lib/components/SwitchControl.svelte

@@ -0,0 +1,27 @@
+<script lang="ts">
+	import { Switch } from 'bits-ui';
+
+	let {
+		checked = $bindable(false),
+		disabled = false,
+		class: className = '',
+		onchange,
+	}: {
+		checked?: boolean;
+		disabled?: boolean;
+		class?: string;
+		onchange?: (checked: boolean) => void;
+	} = $props();
+</script>
+
+<Switch.Root
+	class="saas-switch {className}"
+	{disabled}
+	{checked}
+	onCheckedChange={(next) => {
+		checked = next;
+		onchange?.(next);
+	}}
+>
+	<Switch.Thumb class="saas-switch-thumb" />
+</Switch.Root>

hub/admin-web/src/lib/components/ToastHost.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+	import { dismissToast, toasts } from '$lib/toast';
+
+	const kindClass: Record<string, string> = {
+		info: 'border-surface-200 bg-surface-50 text-surface-800',
+		success: 'border-success-200 bg-success-50 text-success-800',
+		error: 'border-error-200 bg-error-50 text-error-800',
+	};
+</script>
+
+<div class="pointer-events-none fixed inset-x-0 top-0 z-100 flex flex-col items-end gap-2 p-4">
+	{#each $toasts as t (t.id)}
+		<div
+			class="pointer-events-auto flex max-w-sm items-start gap-3 border px-4 py-3 text-sm shadow-[4px_4px_0_rgb(15_23_42/0.12)] {kindClass[
+				t.kind
+			] ?? kindClass.info}"
+			role="status"
+		>
+			<p class="min-w-0 flex-1">{t.message}</p>
+			<button type="button" class="opacity-60 hover:opacity-100" onclick={() => dismissToast(t.id)} aria-label="关闭">
+				×
+			</button>
+		</div>
+	{/each}
+</div>

hub/admin-web/src/lib/constants.ts

@@ -0,0 +1,41 @@
+export interface ToolOption {
+	id: string;
+	label: string;
+	group: string;
+}
+
+export const TOOL_OPTIONS: ToolOption[] = [
+	{ id: 'read_file', label: '读取文件', group: '文件' },
+	{ id: 'write_file', label: '写入文件', group: '文件' },
+	{ id: 'list_files', label: '列目录', group: '文件' },
+	{ id: 'search_files', label: '搜索', group: '文件' },
+	{ id: 'bash', label: 'Bash 命令', group: 'Shell' },
+	{ id: 'web_fetch', label: 'WebFetch', group: '网络' },
+	{ id: 'web_search', label: 'WebSearch', group: '网络' },
+	{ id: 'cph_check', label: 'cph check', group: 'CPH' },
+	{ id: 'cph_build', label: 'cph build', group: 'CPH' },
+	{ id: 'send_file', label: '发送文件（飞书）', group: '飞书' },
+	{ id: 'feishu_read_context', label: '读飞书上下文', group: '飞书' },
+	{ id: 'feishu_download_resource', label: '下载飞书资源', group: '飞书' },
+	{ id: 'request_approval', label: '请求审批', group: '飞书' },
+];
+
+/** 组织成员角色（接口枚举保持英文，界面用 orgRoleLabel） */
+export const ORG_ROLES = ['OWNER', 'ADMIN', 'MEMBER'] as const;
+export type OrgRole = (typeof ORG_ROLES)[number];
+
+export const ORG_ROLE_LABELS: Record<OrgRole, string> = {
+	OWNER: '所有者',
+	ADMIN: '管理员',
+	MEMBER: '成员',
+};
+
+/** 项目团队授权角色（接口枚举保持英文，界面用 permissionRoleLabel） */
+export const PERMISSION_ROLES = ['READ', 'EDIT', 'MANAGE'] as const;
+export type PermissionRole = (typeof PERMISSION_ROLES)[number];
+
+export const PERMISSION_ROLE_LABELS: Record<PermissionRole, string> = {
+	READ: '只读',
+	EDIT: '编辑',
+	MANAGE: '管理',
+};

hub/admin-web/src/lib/format.ts

@@ -0,0 +1,92 @@
+import { ORG_ROLE_LABELS, PERMISSION_ROLE_LABELS, type OrgRole, type PermissionRole } from './constants';
+
+export function fmtDate(iso: string): string {
+	if (!iso) return '—';
+	const d = new Date(iso);
+	if (Number.isNaN(d.getTime())) return iso;
+	return d.toLocaleString(undefined, {
+		year: 'numeric',
+		month: 'short',
+		day: '2-digit',
+		hour: '2-digit',
+		minute: '2-digit',
+	});
+}
+
+export function fmtDateOnly(iso: string): string {
+	if (!iso) return '—';
+	const d = new Date(iso);
+	if (Number.isNaN(d.getTime())) return iso;
+	return d.toLocaleDateString(undefined, { year: 'numeric', month: 'short', day: '2-digit' });
+}
+
+export function fmtCost(usd: number | null): string {
+	if (usd === null) return '—';
+	return `$${Number(usd).toFixed(4)}`;
+}
+
+export function fmtNum(n: number): string {
+	return n.toLocaleString();
+}
+
+const USAGE_KIND_LABELS: Record<string, string> = {
+	model_completion: '模型完成',
+	external_capability: '外部能力',
+	tool_proxy: '工具代理',
+};
+
+const METER_UNIT_LABELS: Record<string, string> = {
+	pages: '页',
+	audio_seconds: '音频秒',
+	invocations: '次调用',
+};
+
+export function usageKindLabel(kind: string): string {
+	return USAGE_KIND_LABELS[kind] ?? kind;
+}
+
+export function meterUnitLabel(unit: string | null | undefined): string {
+	if (!unit) return '—';
+	return METER_UNIT_LABELS[unit] ?? unit;
+}
+
+export function fmtQuantity(quantity: number | null | undefined, unit: string | null | undefined): string {
+	if (quantity === null || quantity === undefined) return '—';
+	const u = meterUnitLabel(unit);
+	return u === '—' ? fmtNum(quantity) : `${fmtNum(quantity)} ${u}`;
+}
+
+export function fmtTokens(input: number | null | undefined, output: number | null | undefined): string {
+	const hasIn = input !== null && input !== undefined;
+	const hasOut = output !== null && output !== undefined;
+	if (!hasIn && !hasOut) return '—';
+	return `${fmtNum(input ?? 0)} / ${fmtNum(output ?? 0)}`;
+}
+
+export function runStatusLabel(status: string): string {
+	const key = status.toUpperCase();
+	if (key === 'COMPLETED') return '完成';
+	if (key === 'FAILED') return '失败';
+	if (key === 'CANCELED') return '取消';
+	if (key === 'TIMED_OUT') return '超时';
+	if (key === 'RUNNING') return '运行中';
+	if (key === 'QUEUED') return '排队';
+	return status;
+}
+
+
+export function orgRoleLabel(role: string): string {
+	const key = role.toUpperCase() as OrgRole;
+	return ORG_ROLE_LABELS[key] ?? role;
+}
+
+export function permissionRoleLabel(role: string): string {
+	const key = role.toUpperCase() as PermissionRole;
+	return PERMISSION_ROLE_LABELS[key] ?? role;
+}
+
+export function providerModeLabel(mode: string): string {
+	if (mode === 'BYOK') return '自带密钥';
+	if (mode === 'PLATFORM_MANAGED') return '平台托管';
+	return mode;
+}

hub/admin-web/src/lib/index.ts

@@ -0,0 +1 @@
+// place files you want to import through the `$lib` alias in this folder.

hub/admin-web/src/lib/org.ts

@@ -0,0 +1,40 @@
+import type { MeResponse, OrgMembership } from './api';
+
+/** Alpha Silo host prefix: <slug>.educraft[.dev].… */
+export function hostOrgSlug(hostname: string = typeof window !== 'undefined' ? window.location.hostname : ''): string | null {
+	const host = hostname.toLowerCase();
+	const m = host.match(/^([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\.educraft(?:-dev)?\./);
+	return m?.[1] ?? null;
+}
+
+export function isOrgAdmin(org: OrgMembership | null | undefined): boolean {
+	if (!org) return false;
+	const role = String(org.role ?? '').toUpperCase();
+	return role === 'OWNER' || role === 'ADMIN';
+}
+
+/**
+ * Resolve the tenancy for this browser session.
+ * Prefers hostname slug (silo), then ?org=, then first admin membership, then first membership.
+ */
+export function resolveOrg(me: MeResponse | null | undefined, search: string = ''): OrgMembership | null {
+	if (!me || me.organizations.length === 0) return null;
+	const host = hostOrgSlug();
+	if (host) {
+		const byHost = me.organizations.find((o) => o.slug === host);
+		if (byHost) return byHost;
+	}
+	const q = new URLSearchParams(search).get('org')?.trim();
+	if (q) {
+		const byQuery = me.organizations.find((o) => o.slug === q);
+		if (byQuery) return byQuery;
+	}
+	const admin = me.organizations.find((o) => isOrgAdmin(o));
+	return admin ?? me.organizations[0] ?? null;
+}
+
+/** SPA paths no longer embed org slug (subdomain carries tenancy). */
+export function adminPath(rest: string = ''): string {
+	const cleaned = rest.replace(/^\/+/, '');
+	return cleaned === '' ? '/admin' : `/admin/${cleaned}`;
+}

hub/admin-web/src/lib/session.ts

@@ -0,0 +1,74 @@
+import { writable } from 'svelte/store';
+import { api, type MeResponse } from './api';
+
+interface SessionState {
+	loading: boolean;
+	me: MeResponse | null;
+	error: string | null;
+}
+
+export const session = writable<SessionState>({
+	loading: true,
+	me: null,
+	error: null,
+});
+
+export async function loadSession(): Promise<void> {
+	session.update((s) => ({ ...s, loading: true, error: null }));
+	try {
+		const me = await api.me();
+		session.set({ loading: false, me, error: null });
+	} catch (err) {
+		const status = (err as { status?: number }).status;
+		if (status === 401) {
+			redirectToLogin();
+			return;
+		}
+		session.set({
+			loading: false,
+			me: null,
+			error: err instanceof Error ? err.message : String(err),
+		});
+	}
+}
+
+/**
+ * Resolve org slug for org-scoped Feishu OAuth (`GET /auth/feishu/:orgSlug`).
+ * Unscoped `/auth/feishu` is disabled unless allowLegacyFeishuOAuth is on.
+ * Path no longer carries tenancy: prefer hostname silo slug, then ?org=.
+ */
+export function resolveLoginOrgSlug(): string | null {
+	const q = new URLSearchParams(window.location.search).get('org');
+	if (q && q.trim() !== '') return q.trim();
+
+	// Alpha Silo public host: <slug>.educraft.paradigm-edu.net (or educraft-dev)
+	const host = window.location.hostname.toLowerCase();
+	const m = host.match(/^([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\.educraft(?:-dev)?\./);
+	if (m?.[1]) return m[1];
+
+	// Legacy path while old bookmarks still land briefly before redirect.
+	const path = window.location.pathname.split('/').filter(Boolean);
+	if (path[0] === 'admin' && path[1] === 'org' && path[2]) {
+		return decodeURIComponent(path[2]);
+	}
+	return null;
+}
+
+export function redirectToLogin(): void {
+	if (window.location.pathname === '/admin/login') return;
+	const ret = encodeURIComponent(
+		window.location.pathname + window.location.search + window.location.hash,
+	);
+	const slug = resolveLoginOrgSlug();
+	if (slug === null) {
+		// Need an org slug for scoped OAuth — backend login helper can prompt.
+		window.location.href = `/admin/login?returnTo=${ret}`;
+		return;
+	}
+	window.location.href = `/auth/feishu/${encodeURIComponent(slug)}?returnTo=${ret}`;
+}
+
+export async function logout(): Promise<void> {
+	await api.logout();
+	redirectToLogin();
+}

hub/admin-web/src/lib/toast.ts

@@ -0,0 +1,34 @@
+import { writable } from 'svelte/store';
+
+export type ToastKind = 'info' | 'success' | 'error';
+
+export interface ToastItem {
+	id: number;
+	message: string;
+	kind: ToastKind;
+}
+
+let seq = 0;
+export const toasts = writable<ToastItem[]>([]);
+
+export function pushToast(message: string, kind: ToastKind = 'info', ms = 3200): void {
+	const id = ++seq;
+	toasts.update((list) => [...list, { id, message, kind }]);
+	if (ms > 0) {
+		setTimeout(() => {
+			toasts.update((list) => list.filter((t) => t.id !== id));
+		}, ms);
+	}
+}
+
+export function dismissToast(id: number): void {
+	toasts.update((list) => list.filter((t) => t.id !== id));
+}
+
+export function toastSuccess(message: string): void {
+	pushToast(message, 'success');
+}
+
+export function toastError(message: string): void {
+	pushToast(message, 'error', 5000);
+}

hub/admin-web/src/routes/+layout.svelte

@@ -0,0 +1,364 @@
+<script lang="ts">
+	import '../routes/app.css';
+	import { onMount } from 'svelte';
+	import { goto } from '$app/navigation';
+	import { page } from '$app/state';
+	import { session, loadSession, logout, redirectToLogin } from '$lib/session';
+	import type { OrgMembership } from '$lib/api';
+	import { adminPath, isOrgAdmin, resolveOrg } from '$lib/org';
+	import { orgRoleLabel } from '$lib/format';
+	import Icon from '$lib/components/Icon.svelte';
+	import ToastHost from '$lib/components/ToastHost.svelte';
+	import SelectField from '$lib/components/SelectField.svelte';
+
+	let { children } = $props();
+	let mobileNavOpen = $state(false);
+	let redirecting = $state(false);
+
+	onMount(() => {
+		loadSession();
+	});
+
+	const navItems = [
+		{ key: 'overview', label: '概览', icon: 'overview' as const },
+		{ key: 'usage', label: '用量', icon: 'overview' as const },
+		{ key: 'members', label: '成员', icon: 'members' as const },
+		{ key: 'teams', label: '团队', icon: 'teams' as const },
+		{ key: 'projects', label: '项目', icon: 'projects' as const },
+		{ key: 'capacity', label: '容量', icon: 'overview' as const },
+		{ key: 'provider', label: '供应方', icon: 'provider' as const },
+		{ key: 'skills', label: '技能', icon: 'roles' as const },
+		{ key: 'roles', label: '角色', icon: 'roles' as const },
+		{ key: 'feishu', label: '飞书', icon: 'feishu' as const },
+		{ key: 'capabilities', label: '能力', icon: 'provider' as const },
+	];
+
+	function memberships(): OrgMembership[] {
+		return $session.me?.organizations ?? [];
+	}
+
+	function adminOrgs(): OrgMembership[] {
+		return memberships().filter((o) => isOrgAdmin(o));
+	}
+
+	function currentOrg(): OrgMembership | null {
+		return resolveOrg($session.me, page.url.search);
+	}
+
+	function isOnProjectRoute(): boolean {
+		const parts = page.url.pathname.split('/').filter(Boolean);
+		// /admin/projects or /admin/projects/:id
+		return parts[0] === 'admin' && parts[1] === 'projects';
+	}
+
+	function activeKey(): string {
+		const parts = page.url.pathname.split('/').filter(Boolean);
+		if (parts[0] !== 'admin') return '';
+		// /admin → overview; /admin/usage → usage; /admin/projects/x → projects
+		return parts[1] ?? 'overview';
+	}
+
+	function navHref(key: string): string {
+		if (key === 'overview') return adminPath();
+		return adminPath(key);
+	}
+
+	function pageTitle(): string {
+		const key = activeKey();
+		if (key === 'overview' || key === '') return '概览';
+		if (key === 'sessions') return '会话详情';
+		return navItems.find((i) => i.key === key)?.label ?? '管理后台';
+	}
+
+	function switchOrg(nextSlug: string) {
+		if (!nextSlug || nextSlug === currentOrg()?.slug) return;
+		// Path is tenancy-free; keep optional ?org= for local multi-membership debugging.
+		const url = new URL(page.url.href);
+		url.searchParams.set('org', nextSlug);
+		void goto(`${url.pathname}${url.search}`, { replaceState: true });
+	}
+
+	function handleLogout(e: Event) {
+		e.preventDefault();
+		logout();
+	}
+
+	function orgSelectItems(list: OrgMembership[]) {
+		return list.map((o) => ({
+			value: o.slug,
+			label: `${o.name} · ${orgRoleLabel(o.role)}`,
+		}));
+	}
+
+	$effect(() => {
+		page.url.pathname;
+		mobileNavOpen = false;
+	});
+
+	$effect(() => {
+		if ($session.loading || !$session.me) return;
+
+		const path = page.url.pathname;
+		// Legacy /admin/org/:slug… is handled by admin/org/[...path] page.
+
+		const org = currentOrg();
+		const admins = adminOrgs();
+
+		if (org && isOrgAdmin(org)) {
+			redirecting = false;
+			return;
+		}
+
+		// Member only: allow project routes; bounce admin-only surfaces to projects.
+		if (org && !isOrgAdmin(org)) {
+			redirecting = false;
+			if (!isOnProjectRoute()) {
+				const target = adminPath('projects');
+				if (path !== target) {
+					redirecting = true;
+					void goto(target, { replaceState: true });
+				}
+			}
+			return;
+		}
+
+		// No org resolved but user has memberships → land on first org's projects/overview via resolveOrg next tick
+		if (!org && memberships().length > 0) {
+			const home = admins[0] ?? memberships()[0]!;
+			const target = isOrgAdmin(home) ? adminPath() : adminPath('projects');
+			if (path !== target && !path.startsWith(`${target}/`)) {
+				redirecting = true;
+				void goto(target, { replaceState: true });
+			}
+		}
+	});
+</script>
+
+<ToastHost />
+
+{#if $session.loading || redirecting}
+	<div class="saas-status-panel">
+		<div class="flex flex-col items-center gap-3 text-surface-600">
+			<svg class="h-8 w-8 animate-spin text-primary-500" viewBox="0 0 24 24" fill="none">
+				<circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+				<path
+					class="opacity-90"
+					fill="currentColor"
+					d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+				></path>
+			</svg>
+			<p class="text-sm">加载中…</p>
+		</div>
+	</div>
+{:else if $session.error}
+	<div class="saas-status-panel">
+		<div class="saas-status-card">
+			<div
+				class="mx-auto mb-3 flex h-12 w-12 items-center justify-center border border-error-200 bg-error-50 text-error-700"
+			>
+				!
+			</div>
+			<h2 class="mb-1 text-lg font-semibold">无法连接到后端</h2>
+			<p class="mb-5 text-sm text-surface-700">{$session.error}</p>
+			<button class="saas-btn-primary" onclick={() => loadSession()}>重试</button>
+		</div>
+	</div>
+{:else if !$session.me}
+	<div class="saas-status-panel">
+		<div class="saas-status-card">
+			<div
+				class="mx-auto mb-4 flex h-12 w-12 items-center justify-center border border-primary-700 bg-primary-600 text-sm font-bold text-white"
+			>
+				CPH
+			</div>
+			<h1 class="text-xl font-semibold">Curriculum Project Hub</h1>
+			<p class="mt-2 mb-6 text-sm text-surface-700">登录以管理组织、项目、团队与模型供应。</p>
+			<button class="saas-btn-primary w-full" onclick={() => redirectToLogin()}>使用飞书登录</button>
+		</div>
+	</div>
+{:else if currentOrg() && isOrgAdmin(currentOrg()!)}
+	{@const org = currentOrg()!}
+	{@const me = $session.me!}
+	<div class="saas-shell">
+		{#if mobileNavOpen}
+			<button
+				type="button"
+				class="fixed inset-0 z-40 bg-surface-950/40 md:hidden"
+				aria-label="关闭导航"
+				onclick={() => (mobileNavOpen = false)}
+			></button>
+		{/if}
+
+		<aside
+			class="saas-sidebar fixed inset-y-0 left-0 z-50 transition-transform md:static md:translate-x-0
+				{mobileNavOpen ? 'translate-x-0' : '-translate-x-full md:translate-x-0'}"
+		>
+			<div class="flex items-center gap-2.5 px-4 py-4">
+				<div
+					class="flex h-9 w-9 items-center justify-center border border-primary-700 bg-primary-600 text-xs font-bold tracking-wide text-white"
+				>
+					CPH
+				</div>
+				<div class="min-w-0">
+					<div class="truncate text-sm font-semibold text-surface-900">组织后台</div>
+					<div class="truncate text-xs text-surface-600">{org.name}</div>
+				</div>
+			</div>
+
+			{#if me.organizations.length > 1}
+				<div class="px-3 pb-3">
+					<div class="mb-1.5 flex items-center gap-1.5 text-xs font-medium text-surface-700">
+						<Icon name="org" class="h-3.5 w-3.5" />
+						组织
+					</div>
+					<SelectField items={orgSelectItems(me.organizations)} value={org.slug} onchange={switchOrg} />
+				</div>
+			{/if}
+
+			<nav class="flex-1 space-y-0.5 overflow-y-auto px-2 pb-3">
+				<p class="px-3 pb-1 pt-2 text-[11px] font-semibold uppercase tracking-wider text-surface-600">工作台</p>
+				{#each navItems as item}
+					{@const active =
+						activeKey() === item.key || (item.key === 'overview' && (activeKey() === '' || activeKey() === 'overview'))}
+					<a href={navHref(item.key)} class="saas-nav-item" data-active={active ? 'true' : 'false'}>
+						<Icon name={item.icon} class="h-4 w-4 shrink-0 opacity-80" />
+						<span>{item.label}</span>
+					</a>
+				{/each}
+			</nav>
+
+			<div class="border-t border-surface-300 p-3">
+				<div class="flex items-center gap-2.5 border border-surface-300 bg-surface-100 px-2.5 py-2">
+					{#if me.user.avatarUrl}
+						<img src={me.user.avatarUrl} alt="" class="h-8 w-8 object-cover" />
+					{:else}
+						<div
+							class="flex h-8 w-8 items-center justify-center border border-primary-300 bg-primary-100 text-xs font-semibold text-primary-800"
+						>
+							{me.user.displayName.slice(0, 1)}
+						</div>
+					{/if}
+					<div class="min-w-0 flex-1">
+						<div class="truncate text-sm font-medium text-surface-900">{me.user.displayName}</div>
+						<div class="truncate text-[11px] text-surface-600">{orgRoleLabel(org.role)}</div>
+					</div>
+					<button
+						type="button"
+						class="p-1.5 text-surface-600 transition hover:bg-surface-200 hover:text-error-700"
+						title="退出登录"
+						onclick={handleLogout}
+					>
+						<Icon name="logout" class="h-4 w-4" />
+					</button>
+				</div>
+			</div>
+		</aside>
+
+		<div class="saas-main">
+			<header class="saas-topbar">
+				<button
+					type="button"
+					class="saas-btn-ghost px-2! md:hidden"
+					onclick={() => (mobileNavOpen = !mobileNavOpen)}
+					aria-label="打开导航"
+				>
+					<Icon name="menu" class="h-5 w-5" />
+				</button>
+				<div class="min-w-0">
+					<div class="flex items-center gap-1.5 text-xs text-surface-600">
+						<span class="truncate">{org.name}</span>
+						<span>/</span>
+						<span class="truncate font-medium text-surface-900">{pageTitle()}</span>
+					</div>
+				</div>
+				<div class="ml-auto hidden items-center gap-2 sm:flex">
+					<span class="saas-badge-primary">{org.status}</span>
+					<span class="saas-badge-neutral font-mono">/{org.slug}</span>
+				</div>
+			</header>
+			<main class="saas-content">
+				<div class="saas-content-inner">
+					{@render children()}
+				</div>
+			</main>
+		</div>
+	</div>
+{:else if currentOrg() && !isOrgAdmin(currentOrg()!) && isOnProjectRoute()}
+	{@const org = currentOrg()!}
+	{@const me = $session.me!}
+	<div class="saas-shell">
+		<div class="saas-main">
+			<header class="saas-topbar">
+				<a href={adminPath('projects')} class="saas-btn-ghost px-2!" aria-label="返回项目列表">
+					<Icon name="menu" class="h-5 w-5" />
+				</a>
+				<div class="min-w-0">
+					<div class="flex items-center gap-1.5 text-xs text-surface-600">
+						<span class="truncate">{org.name}</span>
+						<span>/</span>
+						<span class="truncate font-medium text-surface-900">项目</span>
+					</div>
+				</div>
+				<div class="ml-auto flex items-center gap-2">
+					<span class="saas-badge-neutral font-mono">/{org.slug}</span>
+					<button
+						type="button"
+						class="p-1.5 text-surface-600 transition hover:bg-surface-200 hover:text-error-700"
+						title="退出登录"
+						onclick={handleLogout}
+					>
+						<Icon name="logout" class="h-4 w-4" />
+					</button>
+				</div>
+			</header>
+			<main class="saas-content">
+				<div class="saas-content-inner">
+					{@render children()}
+				</div>
+			</main>
+		</div>
+	</div>
+{:else if currentOrg() && !isOrgAdmin(currentOrg()!)}
+	{@const denied = currentOrg()!}
+	<div class="saas-status-panel">
+		<div class="saas-status-card">
+			<h2 class="mb-2 text-lg font-semibold">无权访问管理后台</h2>
+			<p class="mb-3 text-sm text-surface-700">
+				组织 <strong>{denied.name}</strong>（/{denied.slug}）中你的角色是
+				<span class="saas-badge-neutral mx-1">{orgRoleLabel(denied.role)}</span>。普通成员仅可访问自己有授权的项目。
+			</p>
+			<a class="saas-btn-primary" href={adminPath('projects')}>查看我的项目</a>
+			{#if memberships().length > 1}
+				<p class="saas-label text-left mb-1.5 mt-3">切换到其他组织</p>
+				<div class="mb-4">
+					<SelectField items={orgSelectItems(memberships())} value={denied.slug} onchange={switchOrg} />
+				</div>
+			{/if}
+			<button class="saas-btn-ghost mt-3" onclick={handleLogout}>退出登录</button>
+		</div>
+	</div>
+{:else if memberships().length > 0}
+	{@const denied = resolveOrg($session.me) ?? memberships()[0]!}
+	<div class="saas-status-panel">
+		<div class="saas-status-card">
+			<h2 class="mb-2 text-lg font-semibold">正在跳转…</h2>
+			<p class="mb-5 text-sm text-surface-700">
+				即将进入 <strong>{denied.name}</strong>（/{denied.slug}）的项目。
+			</p>
+			<a class="saas-btn-primary" href={adminPath('projects')}>立即进入</a>
+			<button class="saas-btn-ghost mt-3" onclick={handleLogout}>退出登录</button>
+		</div>
+	</div>
+{:else}
+	<div class="saas-status-panel">
+		<div class="saas-status-card">
+			<h2 class="mb-2 text-lg font-semibold">未加入组织</h2>
+			<p class="mb-3 text-sm text-surface-700">飞书账号已登录，但当前账号尚未加入任何组织。</p>
+			<p class="mb-5 text-left text-xs text-surface-600">
+				open_id：
+				<code class="break-all font-mono text-surface-600">{$session.me!.user.feishuOpenId}</code>
+			</p>
+			<button class="saas-btn-primary" onclick={handleLogout}>退出登录</button>
+		</div>
+	</div>
+{/if}

hub/admin-web/src/routes/+page.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+	import { onMount } from 'svelte';
+	import { goto } from '$app/navigation';
+	import { session, redirectToLogin } from '$lib/session';
+
+	function homeForSession(): string | null {
+		const me = $session.me;
+		if (!me) return null;
+		const admin = me.organizations.find((o) => {
+			const r = String(o.role ?? '').toUpperCase();
+			return r === 'OWNER' || r === 'ADMIN';
+		});
+		const target = admin ?? me.organizations[0];
+		return target ? `/admin` : null;
+	}
+
+	onMount(() => {
+		const unsub = session.subscribe((s) => {
+			if (s.loading) return;
+			if (!s.me) {
+				redirectToLogin();
+				return;
+			}
+			const dest = homeForSession();
+			if (dest) void goto(dest, { replaceState: true });
+		});
+		return unsub;
+	});
+</script>
+
+<div class="saas-status-panel">
+	<div class="flex flex-col items-center gap-3 text-surface-600">
+		<svg class="h-7 w-7 animate-spin text-primary-500" viewBox="0 0 24 24" fill="none">
+			<circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+			<path
+				class="opacity-90"
+				fill="currentColor"
+				d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+			></path>
+		</svg>
+		<p class="text-sm">正在进入工作台…</p>
+	</div>
+</div>

hub/admin-web/src/routes/admin/+page.svelte

@@ -0,0 +1,190 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type OrgMembership } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
+	import { fmtCost, fmtNum, orgRoleLabel } from '$lib/format';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import StatCard from '$lib/components/StatCard.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import SwitchControl from '$lib/components/SwitchControl.svelte';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	const orgFromSession = $derived(resolveOrg($session.me, page.url.search));
+	let orgSlug = $derived(orgFromSession?.slug ?? '');
+	let org = $derived($session.me?.organizations.find((o) => o.slug === orgSlug) as OrgMembership | undefined);
+
+	let settings = $state<{ membersCanCreateProjects: boolean } | null>(null);
+	let usage = $state<Awaited<ReturnType<typeof api.usage>> | null>(null);
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+	let saving = $state(false);
+
+	async function load() {
+		loading = true;
+		error = null;
+		try {
+			[settings, usage] = await Promise.all([api.settings(orgSlug), api.usage(orgSlug)]);
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	async function setMembersCanCreate(next: boolean) {
+		if (!settings || settings.membersCanCreateProjects === next) return;
+		saving = true;
+		const prev = settings.membersCanCreateProjects;
+		settings.membersCanCreateProjects = next;
+		try {
+			await api.setSettings(orgSlug, { membersCanCreateProjects: next });
+			toastSuccess(next ? '已允许成员自助建项' : '已关闭成员自助建项');
+		} catch (err) {
+			settings.membersCanCreateProjects = prev;
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			saving = false;
+		}
+	}
+
+	$effect(() => {
+		if (orgSlug) load();
+	});
+</script>
+
+{#if loading}
+	<LoadingState />
+{:else if error}
+	<ErrorBanner message={error} onretry={load} />
+{:else if org && settings && usage}
+	<PageHeader title={org.name} description="组织健康度、用量与生产策略一览。" />
+
+	<div class="mb-6 grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+		<div class="saas-card-pad sm:col-span-2 lg:col-span-1">
+			<p class="saas-section-title mb-3">组织信息</p>
+			<dl class="space-y-2.5 text-sm">
+				<div class="flex items-center justify-between gap-3">
+					<dt class="text-surface-700">Slug</dt>
+					<dd class="font-mono text-xs text-surface-800">/{org.slug}</dd>
+				</div>
+				<div class="flex items-center justify-between gap-3">
+					<dt class="text-surface-700">状态</dt>
+					<dd><span class="saas-badge-success">{org.status}</span></dd>
+				</div>
+				<div class="flex items-center justify-between gap-3">
+					<dt class="text-surface-700">你的角色</dt>
+					<dd><span class="saas-badge-primary">{orgRoleLabel(org.role)}</span></dd>
+				</div>
+			</dl>
+		</div>
+
+		<div class="saas-card-pad sm:col-span-2">
+			<p class="saas-section-title mb-1">项目自助创建策略</p>
+			<p class="saas-muted mb-4">开启后，普通老师可在飞书群自助创建项目；关闭后仅所有者与管理员可建。</p>
+			<div class="flex items-center gap-3 border border-surface-300 bg-surface-100 px-4 py-3">
+				<SwitchControl checked={settings.membersCanCreateProjects} disabled={saving} onchange={setMembersCanCreate} />
+				<div>
+					<div class="text-sm font-medium text-surface-900">允许成员自助创建项目</div>
+					<div class="text-xs text-surface-600">普通成员在飞书群中自助建项</div>
+				</div>
+			</div>
+		</div>
+	</div>
+
+	<div class="mb-4 flex items-end justify-between gap-3">
+		<div>
+			<h2 class="saas-section-title">用量概览</h2>
+			<p class="saas-muted">totals 含全部 UsageFact；分账明细见用量页。</p>
+		</div>
+		<a class="saas-btn-secondary py-1.5! text-sm" href={`/admin/usage`}>完整用量报告</a>
+	</div>
+
+	<div class="mb-6 grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+		<StatCard label="运行总数" value={fmtNum(usage.totals.runCount)} />
+		<StatCard label="有成本运行" value={fmtNum(usage.totals.runsWithCost)} />
+		<StatCard label="无成本运行" value={fmtNum(usage.totals.runsWithoutCost)} hint="未知 ≠ $0" />
+		<StatCard label="输入 tokens" value={fmtNum(usage.totals.inputTokens)} />
+		<StatCard label="输出 tokens" value={fmtNum(usage.totals.outputTokens)} />
+		<StatCard label="成本 (USD)" value={fmtCost(usage.totals.costUsd)} />
+	</div>
+
+	{#if usage.breakdown.length > 0}
+		<div class="saas-card overflow-hidden mb-6">
+			<div class="border-b border-surface-200 px-5 py-3 flex items-center justify-between gap-3">
+				<div>
+					<h3 class="text-sm font-semibold text-surface-800">消费来源（Top）</h3>
+					<p class="saas-muted text-xs">模型完成 vs 外部能力，按成本降序前 5</p>
+				</div>
+				<a class="text-sm text-primary-700 hover:underline" href={`/admin/usage`}>查看全部分账</a>
+			</div>
+			<div class="overflow-x-auto">
+				<table class="data-table">
+					<thead>
+						<tr>
+							<th>类型</th>
+							<th>供应方</th>
+							<th>模型 / 能力</th>
+							<th>次数</th>
+							<th>成本</th>
+						</tr>
+					</thead>
+					<tbody>
+						{#each [...usage.breakdown].sort((a, b) => (b.costUsd ?? -1) - (a.costUsd ?? -1)).slice(0, 5) as row}
+							<tr>
+								<td class="text-sm">{row.kind === 'external_capability' ? '外部能力' : row.kind === 'model_completion' ? '模型完成' : row.kind}</td>
+								<td class="font-mono text-xs">{row.provider}</td>
+								<td class="font-mono text-xs">{row.capabilityId ?? row.model ?? '—'}</td>
+								<td class="tabular-nums">{fmtNum(row.factCount)}</td>
+								<td class="tabular-nums">{fmtCost(row.costUsd)}</td>
+							</tr>
+						{/each}
+					</tbody>
+				</table>
+			</div>
+		</div>
+	{/if}
+
+	<div class="saas-card overflow-hidden">
+		<div class="border-b border-surface-200 px-5 py-3">
+			<h3 class="text-sm font-semibold text-surface-800">按项目用量</h3>
+		</div>
+		{#if usage.projects.length === 0}
+			<div class="saas-empty">
+				<p class="text-sm text-surface-600">暂无项目用量数据</p>
+			</div>
+		{:else}
+			<div class="overflow-x-auto">
+				<table class="data-table">
+					<thead>
+						<tr>
+							<th>项目</th>
+							<th>运行</th>
+							<th>in / out tokens</th>
+							<th>成本</th>
+						</tr>
+					</thead>
+					<tbody>
+						{#each usage.projects as p}
+							<tr>
+								<td class="font-medium">
+									<a class="hover:text-primary-700 hover:underline" href={`/admin/projects/${p.projectId}`}>
+										{p.projectName}
+									</a>
+								</td>
+								<td class="tabular-nums">{fmtNum(p.runCount)}</td>
+								<td class="tabular-nums text-surface-600">{fmtNum(p.inputTokens)} / {fmtNum(p.outputTokens)}</td>
+								<td class="tabular-nums">{fmtCost(p.costUsd)}</td>
+							</tr>
+						{/each}
+					</tbody>
+				</table>
+			</div>
+		{/if}
+	</div>
+{:else}
+	<div class="saas-empty">
+		<p class="text-sm text-surface-600">组织数据不可用</p>
+	</div>
+{/if}

hub/admin-web/src/routes/admin/capabilities/+page.svelte

@@ -0,0 +1,205 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type CapabilityConnection } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
+	import { fmtDate } from '$lib/format';
+	import { Label } from 'bits-ui';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
+
+	const KNOWN_CAPABILITIES = [
+		{ id: 'pdf_to_md_bundle', label: 'PDF → Markdown', description: '将 PDF 转换为带图片的 Markdown bundle（阿里云文档智能，含公式 LaTeX 识别）' },
+		{ id: 'audio_video_to_text', label: '音视频 → 文本', description: '将音频/视频转写为文本（阿里云文档智能，按秒计费）' },
+	] as const;
+
+	let connections = $state<Map<string, CapabilityConnection>>(new Map());
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+
+	let editingCap = $state<string | null>(null);
+	let accessKeyId = $state('');
+	let accessKeySecret = $state('');
+	let endpoint = $state('docmind-api.cn-hangzhou.aliyuncs.com');
+	let saving = $state(false);
+	let disabling = $state<string | null>(null);
+
+	async function load() {
+		loading = true;
+		error = null;
+		try {
+			const res = await api.capabilityConnections(slug);
+			connections = new Map(res.connections.map((c) => [c.capabilityId, c]));
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	function startEdit(capId: string) {
+		editingCap = capId;
+		accessKeyId = '';
+		accessKeySecret = '';
+		endpoint = 'docmind-api.cn-hangzhou.aliyuncs.com';
+	}
+
+	function cancelEdit() {
+		editingCap = null;
+	}
+
+	async function save(capId: string) {
+		if (accessKeyId.trim() === '' || accessKeySecret.trim() === '' || endpoint.trim() === '') {
+			toastError('AccessKey ID、AccessKey Secret、Endpoint 均为必填');
+			return;
+		}
+		saving = true;
+		try {
+			const result = await api.rotateCapabilityConnection(slug, capId, {
+				accessKeyId: accessKeyId.trim(),
+				accessKeySecret: accessKeySecret.trim(),
+				endpoint: endpoint.trim(),
+			});
+			connections.set(capId, result);
+			connections = new Map(connections);
+			editingCap = null;
+			toastSuccess('能力凭据已保存');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			saving = false;
+		}
+	}
+
+	async function disable(capId: string) {
+		if (!confirm('停用后该能力将不可用，确定停用？')) return;
+		disabling = capId;
+		try {
+			const result = await api.disableCapabilityConnection(slug, capId);
+			connections.set(capId, result);
+			connections = new Map(connections);
+			toastSuccess('已停用能力连接');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			disabling = null;
+		}
+	}
+
+	function statusBadge(status: string): string {
+		if (status === 'ACTIVE') return 'saas-badge-primary';
+		if (status === 'DISABLED') return 'saas-badge-error';
+		return 'saas-badge-muted';
+	}
+
+	function statusLabel(status: string): string {
+		if (status === 'ACTIVE') return '已启用';
+		if (status === 'DISABLED') return '已停用';
+		return '草稿';
+	}
+
+	$effect(() => {
+		if (slug) load();
+	});
+</script>
+
+<PageHeader
+	title="外部能力"
+	description="管理文档/媒体转换服务的组织级凭据（ADR-0027）。凭据按组织隔离、版本化信封存储，缺失或校验失败即 fail-closed。"
+/>
+
+{#if loading}
+	<LoadingState />
+{:else if error}
+	<ErrorBanner message={error} onretry={load} />
+{:else}
+	<div class="space-y-6">
+		{#each KNOWN_CAPABILITIES as cap}
+			{@const conn = connections.get(cap.id)}
+			<div class="saas-card-pad">
+				<div class="mb-3 flex items-start justify-between gap-3">
+					<div>
+						<div class="flex items-center gap-2">
+							<h3 class="saas-section-title">{cap.label}</h3>
+							{#if conn}
+								<span class={statusBadge(conn.status)}>{statusLabel(conn.status)}</span>
+							{:else}
+								<span class="saas-badge-muted">未配置</span>
+							{/if}
+						</div>
+						<p class="saas-muted mt-1 text-sm">{cap.description}</p>
+						<p class="mt-0.5 font-mono text-xs text-surface-500">{cap.id}</p>
+					</div>
+					<div class="flex items-center gap-2">
+						{#if conn?.status === 'ACTIVE'}
+							<button
+								class="saas-btn-ghost text-sm"
+								onclick={() => disable(cap.id)}
+								disabled={disabling === cap.id}
+							>
+								{disabling === cap.id ? '停用中…' : '停用'}
+							</button>
+						{/if}
+						<button
+							class="saas-btn-primary text-sm"
+							onclick={() => startEdit(cap.id)}
+							disabled={editingCap === cap.id}
+						>
+							{conn ? '轮换凭据' : '配置凭据'}
+						</button>
+					</div>
+				</div>
+
+				{#if conn}
+					<dl class="space-y-1.5 text-sm text-surface-700">
+						<div class="flex justify-between">
+							<dt class="text-surface-500">版本</dt>
+							<dd class="font-mono">{conn.activeVersion ?? '—'}</dd>
+						</div>
+						<div class="flex justify-between">
+							<dt class="text-surface-500">密钥 ID</dt>
+							<dd class="font-mono text-xs">{conn.keyId ?? '—'}</dd>
+						</div>
+						<div class="flex justify-between">
+							<dt class="text-surface-500">更新时间</dt>
+							<dd>{fmtDate(conn.updatedAt)}</dd>
+						</div>
+					</dl>
+				{/if}
+
+				{#if editingCap === cap.id}
+					<div class="mt-4 border-t border-surface-100 pt-4">
+						<p class="saas-muted mb-3 text-sm">
+							阿里云 RAM 用户的 AccessKey。密钥仅写入新版本，旧版本归档。
+						</p>
+						<div class="grid gap-4">
+							<div>
+								<Label.Root class="saas-label" for="ak-id-{cap.id}">AccessKey ID</Label.Root>
+								<input id="ak-id-{cap.id}" class="saas-input font-mono text-sm" bind:value={accessKeyId} />
+							</div>
+							<div>
+								<Label.Root class="saas-label" for="ak-secret-{cap.id}">AccessKey Secret</Label.Root>
+								<input id="ak-secret-{cap.id}" class="saas-input" type="password" bind:value={accessKeySecret} />
+							</div>
+							<div>
+								<Label.Root class="saas-label" for="endpoint-{cap.id}">Endpoint</Label.Root>
+								<input id="endpoint-{cap.id}" class="saas-input font-mono text-sm" bind:value={endpoint} />
+							</div>
+						</div>
+						<div class="mt-4 flex items-center justify-end gap-3">
+							<button class="saas-btn-ghost" onclick={cancelEdit} disabled={saving}>取消</button>
+							<button class="saas-btn-primary" onclick={() => save(cap.id)} disabled={saving}>
+								{saving ? '保存中…' : '保存'}
+							</button>
+						</div>
+					</div>
+				{/if}
+			</div>
+		{/each}
+	</div>
+{/if}

hub/admin-web/src/routes/admin/capacity/+page.svelte

@@ -0,0 +1,313 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type CapacityDimension, type CapacityDimensionRow, type CapacityPolicyView } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import EmptyState from '$lib/components/EmptyState.svelte';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
+
+	// Friendlier, user-facing labels. No spec jargon (墙钟 → 运行时长, etc.).
+	const DIMENSION_LABELS: Record<CapacityDimension, string> = {
+		requestRate: '请求速率',
+		requestBodySize: '请求体大小',
+		agentConcurrency: '并发数',
+		admissionQueueLength: '队列长度',
+		admissionQueueWait: '队列等待',
+		fileSize: '单文件大小',
+		attachmentCount: '附件数',
+		archiveExpansion: '归档展开',
+		projectStorage: '项目存储',
+		organizationStorage: '组织存储',
+		memberCount: '成员数',
+		projectCount: '项目数',
+		teamCount: '团队数',
+		folderCount: '文件夹数',
+		sessionCount: '会话数',
+		runWallTime: '运行时长',
+		runTurns: '对话轮次',
+		runToolCalls: '工具调用数',
+		toolWallTime: '工具执行时长',
+		runOutputSize: '输出大小',
+		processMemory: '内存',
+		processCpu: 'CPU',
+		processCount: '进程数',
+	};
+
+	// Logical groupings for higher information density.
+	const GROUPS: { title: string; dims: CapacityDimension[] }[] = [
+		{ title: 'HTTP 接入', dims: ['requestRate', 'requestBodySize'] },
+		{ title: '智能体运行', dims: ['agentConcurrency', 'runWallTime', 'runTurns', 'runToolCalls', 'toolWallTime', 'runOutputSize'] },
+		{ title: '接纳队列', dims: ['admissionQueueLength', 'admissionQueueWait'] },
+		{ title: '附件与存储', dims: ['fileSize', 'attachmentCount', 'archiveExpansion', 'projectStorage', 'organizationStorage'] },
+		{ title: '组织配额', dims: ['memberCount', 'projectCount', 'teamCount', 'folderCount', 'sessionCount'] },
+		{ title: '进程资源', dims: ['processMemory', 'processCpu', 'processCount'] },
+	];
+
+	let view = $state<CapacityPolicyView | null>(null);
+	let drafts = $state<Partial<Record<CapacityDimension, string | number>>>({});
+	let loading = $state(true);
+	let saving = $state(false);
+	let error = $state<string | null>(null);
+
+	async function load() {
+		loading = true;
+		error = null;
+		try {
+			view = await api.capacityPolicy(slug);
+			drafts = {};
+			for (const row of view.dimensions) {
+				drafts[row.dimension] = row.organizationLimit === null ? '' : String(row.organizationLimit);
+			}
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	function draftText(dim: CapacityDimension): string {
+		const raw = drafts[dim];
+		if (raw === undefined || raw === null) return '';
+		return String(raw).trim();
+	}
+
+	// Inline validation: surfaced as the user edits, not on submit. Returns null
+	// when the draft is empty (means "use platform ceiling") or valid.
+	function draftError(row: CapacityDimensionRow): string | null {
+		const text = draftText(row.dimension);
+		if (text === '') return null;
+		const n = Number.parseInt(text, 10);
+		if (!Number.isFinite(n) || n < 1) return '需为正整数';
+		if (row.platformCeiling !== null && n > row.platformCeiling) return `不得超过 ${row.platformCeiling}`;
+		return null;
+	}
+
+	// Live effective value: min(platform ceiling, draft). Reflects the draft
+	// before save so the user sees the outcome as they type.
+	function liveEffective(row: CapacityDimensionRow): number | null {
+		if (row.platformCeiling === null) return null;
+		const text = draftText(row.dimension);
+		if (text === '') return row.platformCeiling;
+		const n = Number.parseInt(text, 10);
+		if (!Number.isFinite(n) || n < 1) return row.platformCeiling;
+		return Math.min(row.platformCeiling, n);
+	}
+
+	function isLowered(row: CapacityDimensionRow): boolean {
+		const eff = liveEffective(row);
+		return eff !== null && eff < row.platformCeiling!;
+	}
+
+	const hasErrors = $derived(
+		view?.dimensions.some((row) => draftError(row) !== null) ?? false,
+	);
+
+	async function save() {
+		if (!view || hasErrors) return;
+		saving = true;
+		const limits: Partial<Record<CapacityDimension, number | null>> = {};
+		for (const row of view.dimensions) {
+			const text = draftText(row.dimension);
+			limits[row.dimension] = text === '' ? null : Number.parseInt(text, 10);
+		}
+		try {
+			view = await api.setCapacityPolicy(slug, { limits });
+			drafts = {};
+			for (const row of view.dimensions) {
+				drafts[row.dimension] = row.organizationLimit === null ? '' : String(row.organizationLimit);
+			}
+			toastSuccess('容量策略已保存');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			saving = false;
+		}
+	}
+
+	$effect(() => {
+		if (slug) load();
+	});
+</script>
+
+<PageHeader
+	title="容量策略"
+	description="平台上限不可突破。组织可在此设更低限制，未设置时按平台上限执行。"
+>
+	{#snippet actions()}
+		<button class="saas-btn-primary" disabled={saving || !view || hasErrors} onclick={save}>
+			{saving ? '保存中…' : '保存'}
+		</button>
+	{/snippet}
+</PageHeader>
+
+<p class="saas-muted mb-6">
+	未配置平台上限的维度暂不可设置组织限制。输入框留空即沿用平台上限。
+</p>
+
+{#if loading}
+	<LoadingState />
+{:else if error}
+	<ErrorBanner message={error} onretry={load} />
+{:else if view}
+	{#if view.dimensions.length === 0}
+		<EmptyState title="暂无容量维度" description="容量维度由平台定义。" />
+	{:else}
+		{@const policy = view}
+		<div class="grid gap-4 md:grid-cols-2">
+			{#each GROUPS as group}
+				{@const rows = group.dims
+					.map((d) => policy.dimensions.find((r) => r.dimension === d))
+					.filter((r): r is CapacityDimensionRow => r !== undefined)}
+				{#if rows.length > 0}
+					<section class="saas-card">
+						<header class="group-header">
+							<h3 class="group-title">{group.title}</h3>
+							<span class="group-count">{rows.length} 项</span>
+						</header>
+						<div class="dim-list">
+							{#each rows as row (row.dimension)}
+								{@const err = draftError(row)}
+								{@const eff = liveEffective(row)}
+								{@const lowered = isLowered(row)}
+								{@const disabled = row.platformCeiling === null}
+								<div class="dim-row" class:dim-row-error={err !== null}>
+									<div class="dim-label">{DIMENSION_LABELS[row.dimension] ?? row.dimension}</div>
+									<div class="dim-ceiling">
+										{#if disabled}
+											<span class="text-surface-400">未配置</span>
+										{:else}
+											<span class="tabular-nums">平台 ≤ {row.platformCeiling}</span>
+										{/if}
+									</div>
+									<input
+										class="saas-input dim-input"
+										type="number"
+										placeholder="用平台值"
+										disabled={disabled}
+										bind:value={drafts[row.dimension]}
+									/>
+									<div class="dim-effective">
+										{#if eff === null}
+											<span class="text-surface-400">—</span>
+										{:else if lowered}
+											<span class="saas-badge saas-badge-primary tabular-nums">有效 {eff}</span>
+										{:else}
+											<span class="saas-badge saas-badge-neutral tabular-nums">有效 {eff}</span>
+										{/if}
+									</div>
+									{#if err !== null}
+										<div class="dim-error">{err}</div>
+									{/if}
+								</div>
+							{/each}
+						</div>
+					</section>
+				{/if}
+			{/each}
+		</div>
+	{/if}
+{:else}
+	<EmptyState title="容量数据不可用" description="无法加载容量策略。" />
+{/if}
+
+<style>
+	.group-header {
+		display: flex;
+		align-items: baseline;
+		justify-content: space-between;
+		padding: 0.5rem 0.75rem;
+		border-bottom: 1px solid var(--color-surface-200);
+		background: var(--color-surface-100);
+	}
+	.group-title {
+		font-size: 0.8125rem;
+		font-weight: 600;
+		color: var(--color-surface-800);
+		letter-spacing: 0.02em;
+	}
+	.group-count {
+		font-size: 0.6875rem;
+		color: var(--color-surface-500);
+	}
+	.dim-list {
+		display: flex;
+		flex-direction: column;
+	}
+	.dim-row {
+		display: grid;
+		grid-template-columns: minmax(5rem, 1fr) auto minmax(7rem, 8.5rem) 6.5rem;
+		align-items: center;
+		gap: 0.5rem;
+		padding: 0.4rem 0.75rem;
+		border-bottom: 1px solid var(--color-surface-100);
+	}
+	.dim-row:last-child {
+		border-bottom: none;
+	}
+	.dim-row-error {
+		background: color-mix(in oklab, var(--color-error-100) 40%, transparent);
+	}
+	.dim-label {
+		font-size: 0.8125rem;
+		font-weight: 500;
+		color: var(--color-surface-900);
+		white-space: nowrap;
+		overflow: hidden;
+		text-overflow: ellipsis;
+	}
+	.dim-ceiling {
+		font-size: 0.6875rem;
+		color: var(--color-surface-500);
+		white-space: nowrap;
+	}
+	.dim-input {
+		padding: 0.25rem 0.5rem;
+		font-size: 0.8125rem;
+		text-align: right;
+	}
+	.dim-effective {
+		display: flex;
+		justify-content: flex-end;
+	}
+	.dim-effective > .saas-badge {
+		width: 100%;
+		justify-content: center;
+	}
+	.dim-error {
+		grid-column: 1 / -1;
+		font-size: 0.6875rem;
+		color: var(--color-error-700);
+		padding-bottom: 0.2rem;
+	}
+	@media (max-width: 480px) {
+		.dim-row {
+			grid-template-columns: 1fr 5rem;
+			grid-template-rows: auto auto auto;
+			row-gap: 0.25rem;
+		}
+		.dim-label {
+			grid-column: 1;
+		}
+		.dim-ceiling {
+			grid-column: 2;
+			text-align: right;
+		}
+		.dim-input {
+			grid-column: 1 / -1;
+		}
+		.dim-effective {
+			grid-column: 1 / -1;
+			justify-content: flex-start;
+		}
+		.dim-effective > .saas-badge {
+			width: auto;
+			justify-content: flex-start;
+		}
+	}
+</style>

hub/admin-web/src/routes/admin/feishu/+page.svelte

@@ -0,0 +1,179 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type FeishuApplicationConnection } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
+	import { fmtDate } from '$lib/format';
+	import { Label } from 'bits-ui';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
+
+	let connection = $state<FeishuApplicationConnection | null>(null);
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+
+	let appId = $state('');
+	let appSecret = $state('');
+	let botOpenId = $state('');
+	let verificationToken = $state('');
+	let encryptKey = $state('');
+	let saving = $state(false);
+	let disabling = $state(false);
+
+	async function load() {
+		loading = true;
+		error = null;
+		try {
+			const res = await api.feishuApplication(slug);
+			connection = res.connection;
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	function resetForm() {
+		appId = '';
+		appSecret = '';
+		botOpenId = '';
+		verificationToken = '';
+		encryptKey = '';
+	}
+
+	async function save() {
+		const id = appId.trim();
+		const secret = appSecret.trim();
+		const bot = botOpenId.trim();
+		if (id === '' || secret === '' || bot === '') {
+			toastError('App ID、App Secret、Bot Open ID 均为必填');
+			return;
+		}
+		saving = true;
+		const body: {
+			appId: string;
+			appSecret: string;
+			botOpenId: string;
+			verificationToken?: string;
+			encryptKey?: string;
+		} = { appId: id, appSecret: secret, botOpenId: bot };
+		const vt = verificationToken.trim();
+		if (vt !== '') body.verificationToken = vt;
+		const ek = encryptKey.trim();
+		if (ek !== '') body.encryptKey = ek;
+		try {
+			connection = await api.rotateFeishuApplication(slug, body);
+			resetForm();
+			toastSuccess('飞书应用凭据已保存');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			saving = false;
+		}
+	}
+
+	async function disable() {
+		if (!connection) return;
+		if (!confirm('停用后该组织将无法收发飞书消息，确定停用？')) return;
+		disabling = true;
+		try {
+			connection = await api.disableFeishuApplication(slug);
+			toastSuccess('已停用飞书应用连接');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			disabling = false;
+		}
+	}
+
+	$effect(() => {
+		if (slug) load();
+	});
+</script>
+
+<PageHeader
+	title="飞书应用"
+	description="本组织绑定的飞书应用凭据（ADR-0021：组织与应用 1:1）。凭据按组织隔离、版本化信封存储，缺失或校验失败即 fail-closed。"
+/>
+
+{#if loading}
+	<LoadingState />
+{:else if error}
+	<ErrorBanner message={error} onretry={load} />
+{:else}
+	{#if connection}
+		<div class="saas-card-pad mb-6">
+			<p class="saas-section-title mb-3">当前连接</p>
+			<dl class="space-y-2.5 text-sm">
+				<div class="flex items-center justify-between gap-3">
+					<dt class="text-surface-700">状态</dt>
+					<dd><span class="saas-badge-success">{connection.status}</span></dd>
+				</div>
+				<div class="flex items-center justify-between gap-3">
+					<dt class="text-surface-700">App 指纹</dt>
+					<dd class="font-mono text-xs text-surface-800">{connection.appFingerprint}</dd>
+				</div>
+				<div class="flex items-center justify-between gap-3">
+					<dt class="text-surface-700">版本</dt>
+					<dd class="tabular-nums">{connection.activeVersion ?? '—'}</dd>
+				</div>
+				<div class="flex items-center justify-between gap-3">
+					<dt class="text-surface-700">更新于</dt>
+					<dd class="text-surface-600">{fmtDate(connection.updatedAt)}</dd>
+				</div>
+			</dl>
+			{#if connection.status !== 'DISABLED'}
+				<div class="mt-5 flex items-center justify-end gap-3 border-t border-surface-100 pt-4">
+					<button class="saas-btn-ghost" onclick={disable} disabled={disabling}>
+						{disabling ? '停用中…' : '停用连接'}
+					</button>
+				</div>
+			{/if}
+		</div>
+	{:else}
+		<div class="saas-card-pad mb-6">
+			<p class="text-sm text-surface-700">本组织尚未绑定飞书应用。填写下方凭据以创建连接。</p>
+		</div>
+	{/if}
+
+	<div class="saas-card-pad">
+		<h3 class="saas-section-title mb-1">{connection ? '轮换凭据' : '创建连接'}</h3>
+		<p class="saas-muted mb-4">
+			密钥仅写入新版本，旧版本归档。{#if connection}App ID 不可变更，须与现有应用一致。{/if}
+		</p>
+		<div class="grid gap-5">
+			<div>
+				<Label.Root class="saas-label" for="app-id">App ID</Label.Root>
+				<input id="app-id" class="saas-input font-mono text-sm" bind:value={appId} />
+			</div>
+			<div>
+				<Label.Root class="saas-label" for="app-secret">App Secret</Label.Root>
+				<input id="app-secret" class="saas-input" type="password" bind:value={appSecret} />
+			</div>
+			<div>
+				<Label.Root class="saas-label" for="bot-open-id">Bot Open ID</Label.Root>
+				<input id="bot-open-id" class="saas-input font-mono text-sm" bind:value={botOpenId} />
+			</div>
+			<div>
+				<Label.Root class="saas-label" for="verification-token">Verification Token（可选）</Label.Root>
+				<input id="verification-token" class="saas-input" type="password" bind:value={verificationToken} />
+			</div>
+			<div>
+				<Label.Root class="saas-label" for="encrypt-key">Encrypt Key（可选）</Label.Root>
+				<input id="encrypt-key" class="saas-input" type="password" bind:value={encryptKey} />
+			</div>
+		</div>
+		<div class="mt-6 flex items-center gap-3 border-t border-surface-100 pt-4">
+			<div class="flex-1"></div>
+			<button class="saas-btn-ghost" onclick={resetForm} disabled={saving}>清空</button>
+			<button class="saas-btn-primary" onclick={save} disabled={saving}>
+				{saving ? '保存中…' : '保存'}
+			</button>
+		</div>
+	</div>
+{/if}

hub/admin-web/src/routes/admin/members/+page.svelte

@@ -0,0 +1,167 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type OrgMember } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
+	import { fmtDate } from '$lib/format';
+	import { ORG_ROLES, ORG_ROLE_LABELS, PERMISSION_ROLE_LABELS } from '$lib/constants';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import EmptyState from '$lib/components/EmptyState.svelte';
+	import SelectField from '$lib/components/SelectField.svelte';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
+	const roleItems = ORG_ROLES.map((r) => ({ value: r, label: ORG_ROLE_LABELS[r] }));
+	const permHint = Object.values(PERMISSION_ROLE_LABELS).join(' / ');
+
+	let members = $state<OrgMember[]>([]);
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+
+	let newOpenId = $state('');
+	let newName = $state('');
+	let newRole = $state<string>('MEMBER');
+	let adding = $state(false);
+
+	async function load() {
+		loading = true;
+		error = null;
+		try {
+			const res = await api.members(slug);
+			members = res.members;
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	async function addMember() {
+		if (!newOpenId.trim()) return;
+		adding = true;
+		try {
+			const m = await api.addMember(slug, {
+				feishuOpenId: newOpenId.trim(),
+				role: newRole,
+				...(newName.trim() ? { displayName: newName.trim() } : {}),
+			});
+			members = [...members, m].sort((a, b) => a.role.localeCompare(b.role) || a.createdAt.localeCompare(b.createdAt));
+			newOpenId = '';
+			newName = '';
+			toastSuccess('成员已添加');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			adding = false;
+		}
+	}
+
+	async function changeRole(m: OrgMember, role: string) {
+		try {
+			await api.setMemberRole(slug, m.userId, role);
+			await load();
+			toastSuccess('角色已更新');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		}
+	}
+
+	async function revoke(m: OrgMember) {
+		if (!confirm(`移除成员 ${m.displayName} 出本组织?`)) return;
+		try {
+			await api.revokeMember(slug, m.userId);
+			await load();
+			toastSuccess('成员已移除');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		}
+	}
+
+	$effect(() => {
+		if (slug) load();
+	});
+</script>
+
+<PageHeader title="成员与权限" description="管理组织角色：所有者与管理员可访问本后台，成员不可。" />
+
+{#if loading}
+	<LoadingState />
+{:else if error}
+	<ErrorBanner message={error} onretry={load} />
+{:else}
+	<div class="saas-card-pad mb-6">
+		<h2 class="saas-section-title mb-4">添加成员</h2>
+		<div class="grid gap-3 md:grid-cols-[1.2fr_1fr_12rem_auto]">
+			<input class="saas-input" placeholder="飞书 open_id" bind:value={newOpenId} />
+			<input class="saas-input" placeholder="显示名（可选）" bind:value={newName} />
+			<SelectField items={roleItems} bind:value={newRole} />
+			<button class="saas-btn-primary" onclick={addMember} disabled={adding}>
+				{adding ? '添加中…' : '添加成员'}
+			</button>
+		</div>
+	</div>
+
+	<div class="saas-card overflow-hidden">
+		<div class="flex items-center justify-between border-b border-surface-200 px-5 py-3">
+			<h2 class="text-sm font-semibold">成员列表</h2>
+			<span class="saas-badge-neutral">{members.length}</span>
+		</div>
+		{#if members.length === 0}
+			<EmptyState title="暂无成员" description="使用上方表单按飞书 open_id 添加成员。" />
+		{:else}
+			<div class="overflow-x-auto">
+				<table class="data-table">
+					<thead>
+						<tr>
+							<th>用户</th>
+							<th>open_id</th>
+							<th>组织角色</th>
+							<th>加入时间</th>
+							<th></th>
+						</tr>
+					</thead>
+					<tbody>
+						{#each members as m}
+							<tr>
+								<td>
+									<div class="flex items-center gap-2.5">
+										{#if m.avatarUrl}
+											<img src={m.avatarUrl} alt="" class="h-7 w-7 border border-surface-300 object-cover" />
+										{:else}
+											<div
+												class="flex h-7 w-7 items-center justify-center border border-primary-300 bg-primary-100 text-xs font-semibold text-primary-800"
+											>
+												{m.displayName.slice(0, 1)}
+											</div>
+										{/if}
+										<span class="font-medium">{m.displayName}</span>
+									</div>
+								</td>
+								<td class="font-mono text-xs text-surface-700">{m.feishuOpenId}</td>
+								<td class="min-w-36">
+									<SelectField
+										items={roleItems}
+										value={m.role}
+										onchange={(role) => {
+											if (role !== m.role) changeRole(m, role);
+										}}
+									/>
+								</td>
+								<td class="text-surface-700">{fmtDate(m.createdAt)}</td>
+								<td class="text-right">
+									<button class="saas-btn-danger py-1! text-sm" onclick={() => revoke(m)}>移除</button>
+								</td>
+							</tr>
+						{/each}
+					</tbody>
+				</table>
+			</div>
+		{/if}
+		<p class="border-t border-surface-300 px-5 py-3 text-xs text-surface-600">
+			组织角色控制后台访问；项目级权限由「项目」页团队授权（{permHint}）决定。
+		</p>
+	</div>
+{/if}

hub/admin-web/src/routes/admin/org/[...path]/+page.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">
+	/**
+	 * Legacy bookmarks: /admin/org/:slug[/...] → /admin[/...]
+	 * Tenancy lives on the silo host, not the path.
+	 */
+	import { onMount } from 'svelte';
+	import { goto } from '$app/navigation';
+	import { page } from '$app/state';
+
+	onMount(() => {
+		const raw = page.params.path ?? '';
+		const segments = raw.split('/').filter(Boolean);
+		// Drop the old org slug (first segment) when present.
+		const rest = segments.length > 0 ? segments.slice(1).join('/') : '';
+		const target = rest === '' ? '/admin' : `/admin/${rest}`;
+		const q = page.url.search;
+		void goto(`${target}${q}`, { replaceState: true });
+	});
+</script>
+
+<div class="saas-status-panel">
+	<p class="text-sm text-surface-600">正在重定向到新地址…</p>
+</div>

hub/admin-web/src/routes/admin/projects/+page.svelte

@@ -0,0 +1,223 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type ExplorerData, type ExplorerFolder, type ExplorerProject, type OrgMembership } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
+	import FolderTree from '$lib/components/FolderTree.svelte';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import EmptyState from '$lib/components/EmptyState.svelte';
+	import { Label } from 'bits-ui';
+	import Modal from '$lib/components/Modal.svelte';
+	import SelectField from '$lib/components/SelectField.svelte';
+	import { fmtDate } from '$lib/format';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
+	const isAdmin = $derived(!!org && (org.role === 'OWNER' || org.role === 'ADMIN'));
+
+	let data = $state<ExplorerData | null>(null);
+	let myProjects = $state<ExplorerProject[] | null>(null);
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+
+	let showFolderModal = $state(false);
+	let folderName = $state('');
+	let folderParent = $state('');
+
+	let showProjectModal = $state(false);
+	let projectName = $state('');
+	let projectFolder = $state('');
+
+	function openFolderModal(parentId: string) {
+		folderName = '';
+		folderParent = parentId;
+		showFolderModal = true;
+	}
+
+	function openProjectModal(folderId: string) {
+		projectName = '';
+		projectFolder = folderId;
+		showProjectModal = true;
+	}
+
+	async function load() {
+		loading = true;
+		error = null;
+		try {
+			if (isAdmin) {
+				data = await api.explorer(slug);
+				myProjects = null;
+			} else {
+				myProjects = (await api.myProjects(slug)).projects;
+				data = null;
+			}
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	async function createFolder() {
+		if (!folderName.trim()) return;
+		try {
+			await api.createFolder(slug, {
+				name: folderName.trim(),
+				...(folderParent ? { parentId: folderParent } : {}),
+			});
+			folderName = '';
+			folderParent = '';
+			showFolderModal = false;
+			await load();
+			toastSuccess('文件夹已创建');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		}
+	}
+
+	async function createProject() {
+		if (!projectName.trim()) return;
+		try {
+			const res = await api.createProject(slug, {
+				name: projectName.trim(),
+				...(projectFolder ? { folderId: projectFolder } : {}),
+			});
+			projectName = '';
+			projectFolder = '';
+			showProjectModal = false;
+			window.location.href = `/admin/projects/${res.id}`;
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		}
+	}
+
+	function folderPath(f: ExplorerFolder): string {
+		if (!data) return f.name;
+		const parts: string[] = [f.name];
+		let cur: ExplorerFolder | undefined = f;
+		while (cur?.parentId) {
+			const parent = data.folders.find((x) => x.id === cur!.parentId);
+			if (!parent) break;
+			parts.unshift(parent.name);
+			cur = parent;
+		}
+		return parts.join(' / ');
+	}
+
+	function folderItems() {
+		if (!data) return [{ value: '', label: '（根）' }];
+		return [{ value: '', label: '（根）' }, ...data.folders.map((f) => ({ value: f.id, label: folderPath(f) }))];
+	}
+
+	$effect(() => {
+		if (slug && org) load();
+	});
+</script>
+
+{#if loading}
+	<LoadingState />
+{:else if error}
+	<ErrorBanner message={error} onretry={load} />
+{:else if isAdmin && data}
+	<PageHeader title="项目" description="文件夹是透明组织节点；项目是权限边界。">
+		{#snippet actions()}
+			<button class="saas-btn-secondary" onclick={() => openFolderModal('')}>新建文件夹</button>
+			<button class="saas-btn-primary" onclick={() => openProjectModal('')}>新建项目</button>
+		{/snippet}
+	</PageHeader>
+
+	<div class="saas-card p-2 sm:p-3">
+		{#if data.projects.filter((p) => !p.folderId).length === 0 && data.folders.filter((f) => !f.parentId).length === 0}
+			<EmptyState title="暂无项目" description="新建文件夹或项目，开始组织你的教研资产。" />
+		{:else}
+			<FolderTree
+				folders={data.folders}
+				projects={data.projects}
+				parentId={null}
+				{slug}
+				onCreateFolder={openFolderModal}
+				onCreateProject={openProjectModal}
+			/>
+		{/if}
+	</div>
+
+	<Modal bind:open={showFolderModal} title="新建文件夹">
+		<Label.Root class="saas-label" for="folder-name">名称</Label.Root>
+		<input
+			id="folder-name"
+			class="saas-input mb-4"
+			bind:value={folderName}
+			onkeydown={(e) => {
+				if (e.key === 'Enter') createFolder();
+			}}
+		/>
+		{#if data && data.folders.length > 0}
+			<p class="saas-label">父文件夹（可选）</p>
+			<div class="mb-4">
+				<SelectField items={folderItems()} bind:value={folderParent} />
+			</div>
+		{/if}
+		<div class="flex justify-end gap-2">
+			<button class="saas-btn-ghost" onclick={() => (showFolderModal = false)}>取消</button>
+			<button class="saas-btn-primary" onclick={createFolder}>创建</button>
+		</div>
+	</Modal>
+
+	<Modal bind:open={showProjectModal} title="新建项目">
+		<Label.Root class="saas-label" for="project-name">项目名</Label.Root>
+		<input
+			id="project-name"
+			class="saas-input mb-4"
+			bind:value={projectName}
+			onkeydown={(e) => {
+				if (e.key === 'Enter') createProject();
+			}}
+		/>
+		{#if data && data.folders.length > 0}
+			<p class="saas-label">文件夹（可选）</p>
+			<div class="mb-4">
+				<SelectField items={folderItems()} bind:value={projectFolder} />
+			</div>
+		{/if}
+		<div class="flex justify-end gap-2">
+			<button class="saas-btn-ghost" onclick={() => (showProjectModal = false)}>取消</button>
+			<button class="saas-btn-primary" onclick={createProject}>创建</button>
+		</div>
+	</Modal>
+{:else if myProjects !== null}
+	<PageHeader title="我的项目" description="你拥有访问授权的项目。">
+		{#snippet actions()}
+			<span class="saas-badge-neutral">仅显示已授权项目</span>
+		{/snippet}
+	</PageHeader>
+
+	<div class="saas-card overflow-hidden">
+		{#if myProjects.length === 0}
+			<EmptyState title="暂无可访问项目" description="当团队被授予项目访问权限时，项目会出现在这里。" />
+		{:else}
+			<table class="data-table">
+				<thead>
+					<tr>
+						<th>项目</th>
+						<th>飞书群</th>
+						<th>创建时间</th>
+					</tr>
+				</thead>
+				<tbody>
+					{#each myProjects as p}
+						<tr class="cursor-pointer" onclick={() => (window.location.href = `/admin/projects/${p.id}`)}>
+							<td class="font-medium">{p.name}</td>
+							<td class="font-mono text-xs">{p.binding ? `群 ${p.binding.chatId}` : '—'}</td>
+							<td class="text-surface-700">{fmtDate(p.createdAt)}</td>
+						</tr>
+					{/each}
+				</tbody>
+			</table>
+		{/if}
+	</div>
+{:else}
+	<EmptyState title="项目数据不可用" description="无法加载项目列表。" />
+{/if}

hub/admin-web/src/routes/admin/projects/[projectId]/+page.svelte

@@ -0,0 +1,390 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import {
+		api,
+		type ProjectDetail,
+		type TeamAccessEntry,
+		type TeamRow,
+		type SessionSummary,
+		type ExplorerData,
+		type ProjectUsageReport,
+	} from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
+	import {
+		fmtCost,
+		fmtDate,
+		fmtNum,
+		fmtQuantity,
+		fmtTokens,
+		permissionRoleLabel,
+		usageKindLabel,
+	} from '$lib/format';
+	import { PERMISSION_ROLES, PERMISSION_ROLE_LABELS } from '$lib/constants';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import EmptyState from '$lib/components/EmptyState.svelte';
+	import SelectField from '$lib/components/SelectField.svelte';
+	import Icon from '$lib/components/Icon.svelte';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
+	const projectId = $derived(page.params.projectId ?? '');
+	const roleItems = PERMISSION_ROLES.map((r) => ({ value: r, label: PERMISSION_ROLE_LABELS[r] }));
+	const roleChain = `${PERMISSION_ROLE_LABELS.READ} ⊂ ${PERMISSION_ROLE_LABELS.EDIT} ⊂ ${PERMISSION_ROLE_LABELS.MANAGE}`;
+
+	let proj = $state<ProjectDetail | null>(null);
+	let access = $state<TeamAccessEntry[]>([]);
+	let sessions = $state<SessionSummary[]>([]);
+	let projectUsage = $state<ProjectUsageReport | null>(null);
+	let teams = $state<TeamRow[]>([]);
+	let explorer = $state<ExplorerData | null>(null);
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+
+	let grantTeam = $state('');
+	let grantRole = $state<string>('EDIT');
+	let moveFolder = $state('');
+
+	const actorIsOrgAdmin = $derived(proj?.actorIsOrgAdmin ?? false);
+	const actorCanManage = $derived(proj?.actorCanManageProject ?? false);
+
+	async function load() {
+		loading = true;
+		error = null;
+		try {
+			// Project detail + team-access list are gated to project read/oversight.
+			const [p, a] = await Promise.all([api.project(slug, projectId), api.teamAccess(slug, projectId)]);
+			proj = p;
+			access = a.access;
+			// Team list is needed for grant UI whenever the actor has project MANAGE
+			// (org admin or member). Sessions/explorer stay org-admin oversight only.
+			const needTeams = p.actorIsOrgAdmin === true || p.actorCanManageProject === true;
+			const [s, t, e, u] = await Promise.all([
+				p.actorIsOrgAdmin ? api.sessions(slug, projectId) : Promise.resolve({ sessions: [] as SessionSummary[] }),
+				needTeams ? api.teams(slug) : Promise.resolve({ teams: [] as TeamRow[] }),
+				p.actorIsOrgAdmin ? api.explorer(slug) : Promise.resolve(null as ExplorerData | null),
+				p.actorIsOrgAdmin
+					? api.projectUsage(slug, projectId)
+					: Promise.resolve(null as ProjectUsageReport | null),
+			]);
+			sessions = s.sessions;
+			teams = t.teams;
+			explorer = e;
+			projectUsage = u;
+			if (p.actorIsOrgAdmin) {
+				moveFolder = p.folderId ?? '';
+			}
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	async function rename() {
+		if (!proj) return;
+		const name = prompt('新名称', proj.name);
+		if (!name) return;
+		try {
+			await api.renameProject(slug, projectId, name);
+			await load();
+			toastSuccess('已重命名');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		}
+	}
+
+	async function archiveBinding() {
+		if (!confirm('解绑当前飞书群? 用户将无法通过该群触发智能体。')) return;
+		try {
+			await api.archiveBinding(slug, projectId);
+			await load();
+			toastSuccess('已解绑飞书群');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		}
+	}
+
+	async function archiveProject() {
+		if (!confirm(`归档项目 ${proj?.name}?`)) return;
+		try {
+			await api.archiveProject(slug, projectId);
+			window.location.href = `/admin/projects`;
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		}
+	}
+
+	async function move() {
+		try {
+			await api.moveProject(slug, projectId, moveFolder || null);
+			await load();
+			toastSuccess('已移动');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		}
+	}
+
+	async function grant() {
+		if (!grantTeam) return;
+		try {
+			await api.grantTeamAccess(slug, projectId, { teamId: grantTeam, role: grantRole });
+			grantTeam = '';
+			await load();
+			toastSuccess('已授权');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		}
+	}
+
+	async function revoke(t: TeamAccessEntry) {
+		if (!confirm(`撤销 ${t.teamName} 对此项目的授权?`)) return;
+		try {
+			await api.revokeTeamAccess(slug, projectId, t.teamId);
+			await load();
+			toastSuccess('已撤销授权');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		}
+	}
+
+	function folderItems() {
+		const items = [{ value: '', label: '（根）' }];
+		if (!explorer) return items;
+		return [...items, ...explorer.folders.map((f) => ({ value: f.id, label: f.name }))];
+	}
+
+	function teamItems() {
+		return [{ value: '', label: '选择团队…' }, ...teams.map((t) => ({ value: t.id, label: `${t.name}（${t.slug}）` }))];
+	}
+
+	$effect(() => {
+		if (slug && projectId) load();
+	});
+</script>
+
+{#if loading}
+	<LoadingState />
+{:else if error}
+	<ErrorBanner message={error} onretry={load} />
+{:else if proj}
+	<div class="mb-2">
+		<a
+			href={`/admin/projects`}
+			class="inline-flex items-center gap-1 text-sm text-surface-700 hover:text-primary-600"
+		>
+			<Icon name="arrow-left" class="h-4 w-4" />
+			返回项目列表
+		</a>
+	</div>
+
+	{@const detail = proj}
+	<PageHeader title={detail.name} description={`项目是权限边界；通过团队授予 ${roleChain}。`}>
+		{#snippet actions()}
+			{#if actorIsOrgAdmin}
+				<button class="saas-btn-secondary py-1.5! text-sm" onclick={rename}>重命名</button>
+				{#if detail.binding}
+					<button class="saas-btn-secondary py-1.5! text-sm" onclick={archiveBinding}>解绑飞书群</button>
+				{/if}
+				<button class="saas-btn-danger py-1.5! text-sm" onclick={archiveProject}>归档</button>
+			{/if}
+		{/snippet}
+	</PageHeader>
+
+	<div class="saas-card-pad mb-6">
+		<dl class="grid gap-x-8 gap-y-3 text-sm sm:grid-cols-2">
+			<div>
+				<dt class="text-xs font-medium uppercase tracking-wide text-surface-600">工作区路径</dt>
+				<dd class="mt-0.5 break-all font-mono text-xs text-surface-700">{proj.workspaceDir}</dd>
+			</div>
+			<div>
+				<dt class="text-xs font-medium uppercase tracking-wide text-surface-600">创建者</dt>
+				<dd class="mt-0.5 text-surface-800">
+					{proj.createdBy ? `${proj.createdBy.displayName} (${proj.createdBy.feishuOpenId})` : '—'}
+				</dd>
+			</div>
+			<div>
+				<dt class="text-xs font-medium uppercase tracking-wide text-surface-600">文件夹</dt>
+				<dd class="mt-0.5 text-surface-800">{proj.folder ? proj.folder.name : '（根）'}</dd>
+			</div>
+			<div>
+				<dt class="text-xs font-medium uppercase tracking-wide text-surface-600">飞书群</dt>
+				<dd class="mt-0.5 text-surface-800">
+					{#if proj.binding}
+						<span class="saas-badge-success mr-1">已绑定</span>
+						<span class="font-mono text-xs">群 {proj.binding.chatId}</span>
+						<span class="text-surface-600"> · {fmtDate(proj.binding.createdAt)}</span>
+					{:else}
+						<span class="saas-badge-neutral">未绑定</span>
+					{/if}
+				</dd>
+			</div>
+			<div>
+				<dt class="text-xs font-medium uppercase tracking-wide text-surface-600">创建时间</dt>
+				<dd class="mt-0.5 text-surface-800">{fmtDate(proj.createdAt)}</dd>
+			</div>
+		</dl>
+
+		{#if explorer}
+			<div class="mt-5 flex flex-wrap items-end gap-2 border-t border-surface-100 pt-4">
+				<div class="min-w-48 flex-1">
+					<p class="saas-label">移动到文件夹</p>
+					<SelectField items={folderItems()} bind:value={moveFolder} />
+				</div>
+				<button class="saas-btn-secondary" onclick={move}>移动</button>
+			</div>
+		{/if}
+	</div>
+
+	<div class="saas-card-pad mb-6">
+		<h3 class="saas-section-title mb-1">团队授权</h3>
+		<p class="saas-muted mb-4">通过团队授权项目访问。一项目可授多团队，一团队可访问多项目。</p>
+
+		{#if actorCanManage}
+			<div class="mb-4 grid gap-2 sm:grid-cols-[1fr_10rem_auto]">
+				<SelectField items={teamItems()} bind:value={grantTeam} />
+				<SelectField items={roleItems} bind:value={grantRole} />
+				<button class="saas-btn-primary" onclick={grant}>授权</button>
+			</div>
+		{:else}
+			<p class="mb-4 text-xs text-surface-600">需要项目 MANAGE 授权才能增删团队访问。</p>
+		{/if}
+
+		{#if access.length === 0}
+			<EmptyState title="暂无团队授权" description="选择团队并授予角色以开放项目访问。" />
+		{:else}
+			<table class="data-table">
+				<thead>
+					<tr>
+						<th>团队</th>
+						<th>标识</th>
+						<th>角色</th>
+						<th></th>
+					</tr>
+				</thead>
+				<tbody>
+					{#each access as g}
+						<tr>
+							<td class="font-medium">{g.teamName}</td>
+							<td class="font-mono text-xs">/{g.teamSlug}</td>
+							<td><span class="saas-badge-primary">{permissionRoleLabel(g.role)}</span></td>
+							<td class="text-right">
+								{#if actorCanManage}
+									<button class="saas-btn-danger py-1! text-xs" onclick={() => revoke(g)}>撤销</button>
+								{:else}
+									<span class="text-xs text-surface-500">—</span>
+								{/if}
+							</td>
+						</tr>
+					{/each}
+				</tbody>
+			</table>
+		{/if}
+	</div>
+
+	{#if actorIsOrgAdmin}
+		{#if projectUsage}
+			<div class="saas-card overflow-hidden mb-6">
+				<div class="border-b border-surface-200 px-5 py-3 flex items-center justify-between gap-3">
+					<div>
+						<h3 class="text-sm font-semibold">项目用量分账</h3>
+						<p class="saas-muted mt-0.5 text-xs">
+							{fmtNum(projectUsage.runCount)} 次运行 · 成本 {fmtCost(projectUsage.costUsd)} · tokens
+							{fmtTokens(projectUsage.inputTokens, projectUsage.outputTokens)}
+						</p>
+					</div>
+					<a class="text-sm text-primary-700 hover:underline" href={`/admin/usage`}>组织报告</a>
+				</div>
+				{#if projectUsage.breakdown.length === 0}
+					<div class="px-5 py-4 text-sm text-surface-600">尚无 UsageFact。</div>
+				{:else}
+					<div class="overflow-x-auto">
+						<table class="data-table">
+							<thead>
+								<tr>
+									<th>类型</th>
+									<th>供应方</th>
+									<th>模型 / 能力</th>
+									<th>次数</th>
+									<th>计量</th>
+									<th>成本</th>
+								</tr>
+							</thead>
+							<tbody>
+								{#each projectUsage.breakdown as row}
+									<tr>
+										<td>
+											<span
+												class={row.kind === 'external_capability' ? 'saas-badge-primary' : 'saas-badge-success'}
+											>
+												{usageKindLabel(row.kind)}
+											</span>
+										</td>
+										<td class="font-mono text-xs">{row.provider}</td>
+										<td class="font-mono text-xs">{row.capabilityId ?? row.model ?? '—'}</td>
+										<td class="tabular-nums">{fmtNum(row.factCount)}</td>
+										<td class="tabular-nums text-xs">
+											{#if row.unit}
+												{fmtQuantity(row.quantity, row.unit)}
+											{:else}
+												{fmtTokens(row.inputTokens, row.outputTokens)}
+											{/if}
+										</td>
+										<td class="tabular-nums">{fmtCost(row.costUsd)}</td>
+									</tr>
+								{/each}
+							</tbody>
+						</table>
+					</div>
+				{/if}
+			</div>
+		{/if}
+
+		<div class="saas-card overflow-hidden">
+			<div class="border-b border-surface-200 px-5 py-3">
+				<h3 class="text-sm font-semibold">智能体会话</h3>
+				<p class="saas-muted mt-0.5 text-xs">点进会话可查看每次 run 的 UsageFact 分账（模型 / 外部能力）。</p>
+			</div>
+			{#if sessions.length === 0}
+				<EmptyState title="暂无会话" description="飞书侧触发智能体后会显示在此。" />
+			{:else}
+				<table class="data-table">
+					<thead>
+						<tr>
+							<th>供应方 / 角色</th>
+							<th>模型</th>
+							<th>运行次数</th>
+							<th>更新</th>
+							<th></th>
+						</tr>
+					</thead>
+					<tbody>
+						{#each sessions as s}
+							<tr>
+								<td class="font-mono text-xs">{s.provider} / {s.roleId}</td>
+								<td class="font-mono text-xs">{s.model}</td>
+								<td class="tabular-nums">{s.runCount}</td>
+								<td class="text-surface-700">{fmtDate(s.updatedAt)}</td>
+								<td class="text-right">
+									<a
+										class="text-sm text-primary-700 hover:underline"
+										href={`/admin/sessions/${s.id}`}
+									>
+										详情
+									</a>
+								</td>
+							</tr>
+						{/each}
+					</tbody>
+				</table>
+			{/if}
+		</div>
+	{/if}
+{:else}
+	<div class="saas-empty">
+		<p class="text-sm text-surface-600">项目数据不可用</p>
+	</div>
+{/if}

hub/admin-web/src/routes/admin/provider/+page.svelte

@@ -0,0 +1,172 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type ProviderConnectionRow } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
+	import { fmtDate, providerModeLabel } from '$lib/format';
+	import { Label } from 'bits-ui';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
+
+	let connections = $state<ProviderConnectionRow[]>([]);
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+
+	let providerId = $state('');
+	let baseUrl = $state('');
+	let authToken = $state('');
+	let anthropicApiKey = $state('');
+	let saving = $state(false);
+
+	async function load() {
+		loading = true;
+		error = null;
+		try {
+			const res = await api.providerConnections(slug);
+			connections = res.connections;
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	function startRotate(row: ProviderConnectionRow) {
+		providerId = row.providerId;
+		baseUrl = '';
+		authToken = '';
+		anthropicApiKey = '';
+	}
+
+	function resetForm() {
+		providerId = '';
+		baseUrl = '';
+		authToken = '';
+		anthropicApiKey = '';
+	}
+
+	async function save() {
+		const id = providerId.trim();
+		if (id === '') {
+			toastError('请填写供应方 ID');
+			return;
+		}
+		const url = baseUrl.trim();
+		const token = authToken.trim();
+		if (url === '' || token === '') {
+			toastError('接口地址与访问令牌均为必填');
+			return;
+		}
+		saving = true;
+		const body: { baseUrl: string; authToken: string; anthropicApiKey?: string } = {
+			baseUrl: url,
+			authToken: token,
+		};
+		const key = anthropicApiKey.trim();
+		if (key !== '') body.anthropicApiKey = key;
+		try {
+			await api.rotateProviderConnection(slug, id, body);
+			toastSuccess('凭据已轮换');
+			resetForm();
+			await load();
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			saving = false;
+		}
+	}
+
+	$effect(() => {
+		if (slug) load();
+	});
+</script>
+
+<PageHeader
+	title="模型供应方"
+	description="本组织的模型供应方连接。BYOK 由组织所有者/管理员轮换；平台托管连接由平台管理员配置。凭据按组织隔离，缺失或校验失败即拒绝运行（fail-closed）。"
+/>
+
+{#if loading}
+	<LoadingState />
+{:else if error}
+	<ErrorBanner message={error} onretry={load} />
+{:else}
+	<div class="saas-card overflow-hidden mb-6">
+		<div class="border-b border-surface-200 px-5 py-3">
+			<h3 class="text-sm font-semibold text-surface-800">连接</h3>
+		</div>
+		{#if connections.length === 0}
+			<div class="saas-empty"><p class="text-sm text-surface-600">尚无供应方连接</p></div>
+		{:else}
+			<div class="overflow-x-auto">
+				<table class="data-table">
+					<thead>
+						<tr>
+							<th>供应方</th>
+							<th>凭据模式</th>
+							<th>状态</th>
+							<th>版本</th>
+							<th>更新于</th>
+							<th></th>
+						</tr>
+					</thead>
+					<tbody>
+						{#each connections as row}
+							<tr>
+								<td class="font-mono text-sm">{row.providerId}</td>
+								<td>{providerModeLabel(row.mode)}</td>
+								<td>{row.status}</td>
+								<td class="tabular-nums">{row.activeVersion ?? '—'}</td>
+								<td class="text-surface-600">{fmtDate(row.updatedAt)}</td>
+								<td>
+									{#if row.mode === 'BYOK'}
+										<button class="saas-btn-ghost px-2! py-1! text-xs" onclick={() => startRotate(row)}>轮换</button>
+									{:else}
+										<span class="text-xs text-surface-500">平台管理</span>
+									{/if}
+								</td>
+							</tr>
+						{/each}
+					</tbody>
+				</table>
+			</div>
+		{/if}
+	</div>
+
+	<div class="saas-card-pad">
+		<h3 class="saas-section-title mb-1">轮换 BYOK 凭据</h3>
+		<p class="saas-muted mb-4">
+			密钥仅写入新版本，旧版本归档；保存时需重新填写接口地址与访问令牌。平台托管连接不在此处管理。
+		</p>
+		<div class="grid gap-5">
+			<div>
+				<Label.Root class="saas-label" for="provider-id">供应方 ID</Label.Root>
+				<input id="provider-id" class="saas-input font-mono text-sm" bind:value={providerId} placeholder="openrouter" />
+			</div>
+			<div>
+				<Label.Root class="saas-label" for="base-url">接口地址</Label.Root>
+				<input id="base-url" class="saas-input" placeholder="https://openrouter.ai/api" bind:value={baseUrl} />
+			</div>
+			<div>
+				<Label.Root class="saas-label" for="auth-token">访问令牌</Label.Root>
+				<input id="auth-token" class="saas-input" type="password" bind:value={authToken} />
+			</div>
+			<div>
+				<Label.Root class="saas-label" for="anthropic-key">Anthropic API Key（可选）</Label.Root>
+				<input id="anthropic-key" class="saas-input" type="password" bind:value={anthropicApiKey} />
+			</div>
+		</div>
+		<div class="mt-6 flex items-center gap-3 border-t border-surface-100 pt-4">
+			<div class="flex-1"></div>
+			<button class="saas-btn-ghost" onclick={resetForm} disabled={saving}>清空</button>
+			<button class="saas-btn-primary" onclick={save} disabled={saving}>
+				{saving ? '保存中…' : '保存'}
+			</button>
+		</div>
+	</div>
+{/if}

hub/admin-web/src/routes/admin/roles/+page.svelte

@@ -0,0 +1,132 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type AgentRoleRow, type AgentModelRow, type AgentSkillRow } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import EmptyState from '$lib/components/EmptyState.svelte';
+	import RoleCard from '$lib/components/RoleCard.svelte';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
+
+	let roles = $state<AgentRoleRow[]>([]);
+	let models = $state<AgentModelRow[]>([]);
+	let skills = $state<AgentSkillRow[]>([]);
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+
+	let newRoleId = $state('');
+	let newLabel = $state('');
+	let adding = $state(false);
+
+	async function load() {
+		loading = true;
+		error = null;
+		try {
+			const [r, s] = await Promise.all([api.agentRoles(slug), api.agentSkills(slug)]);
+			roles = r.roles;
+			skills = s.skills;
+			// Model fetch hits the provider API and may fail or be slow; load it
+			// independently so roles remain editable even without a model list.
+			models = [];
+			api.agentModels(slug)
+				.then((m) => { models = m.models; })
+				.catch((err) => { toastError(`模型列表加载失败：${err instanceof Error ? err.message : String(err)}`); });
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	async function add() {
+		const roleId = newRoleId.trim();
+		const label = newLabel.trim();
+		if (roleId === '' || label === '') {
+			toastError('角色 ID 与显示名均为必填');
+			return;
+		}
+		if (roles.some((r) => r.roleId === roleId)) {
+			toastError(`角色 ID 已存在：${roleId}`);
+			return;
+		}
+		adding = true;
+		try {
+			const created = await api.upsertAgentRole(slug, roleId, { label });
+			roles = [...roles, created];
+			newRoleId = '';
+			newLabel = '';
+			toastSuccess('角色已创建');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			adding = false;
+		}
+	}
+
+	function onRoleUpdated(updated: AgentRoleRow) {
+		roles = roles.map((x) => (x.roleId === updated.roleId ? { ...updated, skillNames: x.skillNames } : x));
+		if (updated.isDefault) {
+			roles = roles.map((x) => (x.roleId === updated.roleId ? x : { ...x, isDefault: false }));
+		}
+	}
+
+	function onRoleSkillsChanged(roleId: string, skillNames: string[]) {
+		roles = roles.map((x) => (x.roleId === roleId ? { ...x, skillNames } : x));
+	}
+
+	$effect(() => {
+		if (slug) load();
+	});
+</script>
+
+<PageHeader
+	title="角色"
+	description="角色是组织级数据：组合默认模型、系统提示词、工具白名单与已绑定技能。角色 ID 即飞书斜杠命令（如 /draft）。"
+/>
+
+{#if loading}
+	<LoadingState />
+{:else if error}
+	<ErrorBanner message={error} onretry={load} />
+{:else}
+	<div class="saas-card-pad mb-6">
+		<h2 class="saas-section-title mb-4">新建角色</h2>
+		<div class="grid gap-3 sm:grid-cols-[10rem_1fr_auto]">
+			<input
+				class="saas-input font-mono text-sm"
+				placeholder="角色 ID（如 draft）"
+				bind:value={newRoleId}
+				onkeydown={(e) => {
+					if (e.key === 'Enter') add();
+				}}
+			/>
+			<input
+				class="saas-input"
+				placeholder="显示名（如 草稿）"
+				bind:value={newLabel}
+				onkeydown={(e) => {
+					if (e.key === 'Enter') add();
+				}}
+			/>
+			<button class="saas-btn-primary" onclick={add} disabled={adding}>新建</button>
+		</div>
+		<p class="mt-2 text-xs text-surface-600">角色 ID 仅允许小写字母、数字、下划线与连字符，且以字母或数字开头。</p>
+	</div>
+
+	{#if roles.length === 0}
+		<div class="saas-card">
+			<EmptyState title="暂无角色" description="组织必须且只能有一个启用中的默认角色；新建第一个角色将自动成为默认。" />
+		</div>
+	{:else}
+		<div class="space-y-4">
+			{#each roles as r (r.roleId)}
+				<RoleCard {r} {models} {skills} {slug} onupdated={onRoleUpdated} onskillschanged={onRoleSkillsChanged} />
+			{/each}
+		</div>
+	{/if}
+{/if}

hub/admin-web/src/routes/admin/sessions/[sessionId]/+page.svelte

@@ -0,0 +1,238 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type SessionDetail, type SessionRunRow, type UsageFactRow } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
+	import {
+		fmtCost,
+		fmtDate,
+		fmtNum,
+		fmtQuantity,
+		fmtTokens,
+		runStatusLabel,
+		usageKindLabel,
+	} from '$lib/format';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import EmptyState from '$lib/components/EmptyState.svelte';
+	import Icon from '$lib/components/Icon.svelte';
+
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
+	const sessionId = $derived(page.params.sessionId ?? '');
+
+	let detail = $state<SessionDetail | null>(null);
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+	let expandedRunId = $state<string | null>(null);
+
+	async function load() {
+		if (!slug || !sessionId) return;
+		loading = true;
+		error = null;
+		try {
+			detail = await api.session(slug, sessionId);
+			if (detail.runs.length > 0) {
+				expandedRunId = detail.runs[0]!.id;
+			}
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	function statusClass(status: string): string {
+		const key = status.toUpperCase();
+		if (key === 'COMPLETED') return 'saas-badge-success';
+		if (key === 'FAILED' || key === 'TIMED_OUT' || key === 'CANCELED') return 'saas-badge-error';
+		return 'saas-badge-primary';
+	}
+
+	function factMeter(f: UsageFactRow): string {
+		if (f.unit) return fmtQuantity(f.quantity, f.unit);
+		if (f.inputTokens !== null || f.outputTokens !== null) {
+			return fmtTokens(f.inputTokens, f.outputTokens);
+		}
+		return '—';
+	}
+
+	function factSource(f: UsageFactRow): string {
+		if (f.capabilityId) return f.capabilityId;
+		if (f.model) return f.model;
+		return '—';
+	}
+
+	function runCostHint(run: SessionRunRow): string {
+		const factCost = run.usageFacts.reduce<number | null>((acc, f) => {
+			if (f.costUsd === null) return acc;
+			return (acc ?? 0) + f.costUsd;
+		}, null);
+		const cache = run.costUsd;
+		if (factCost !== null && cache !== null && Math.abs(factCost - cache) > 1e-9) {
+			return `运行缓存 ${fmtCost(cache)}；事实合计 ${fmtCost(factCost)}（缓存可能未含外部能力）`;
+		}
+		if (factCost !== null) return `事实合计 ${fmtCost(factCost)}`;
+		if (cache !== null) return `运行缓存 ${fmtCost(cache)}`;
+		return '成本未知';
+	}
+
+	function toggleRun(id: string) {
+		expandedRunId = expandedRunId === id ? null : id;
+	}
+
+	$effect(() => {
+		if (slug && sessionId) void load();
+	});
+</script>
+
+{#if loading}
+	<LoadingState />
+{:else if error}
+	<ErrorBanner message={error} onretry={load} />
+{:else if detail}
+	<div class="mb-2">
+		<a
+			class="inline-flex items-center gap-1 text-sm text-surface-700 hover:text-primary-700"
+			href={`/admin/projects/${detail.project.id}`}
+		>
+			<Icon name="arrow-left" class="h-4 w-4" />
+			返回项目 {detail.project.name}
+		</a>
+	</div>
+
+	<PageHeader
+		title={detail.title?.trim() || '未命名会话'}
+		description={`${detail.provider} · ${detail.roleId} · ${detail.model}`}
+	/>
+
+	<div class="saas-card-pad mb-6">
+		<dl class="grid gap-x-8 gap-y-3 text-sm sm:grid-cols-2 lg:grid-cols-3">
+			<div>
+				<dt class="text-surface-600">会话 ID</dt>
+				<dd class="mt-0.5 break-all font-mono text-xs">{detail.id}</dd>
+			</div>
+			<div>
+				<dt class="text-surface-600">项目</dt>
+				<dd class="mt-0.5">
+					<a class="text-primary-700 hover:underline" href={`/admin/projects/${detail.project.id}`}>
+						{detail.project.name}
+					</a>
+				</dd>
+			</div>
+			<div>
+				<dt class="text-surface-600">创建 / 更新</dt>
+				<dd class="mt-0.5 text-surface-800">{fmtDate(detail.createdAt)} · {fmtDate(detail.updatedAt)}</dd>
+			</div>
+			{#if detail.archivedAt}
+				<div>
+					<dt class="text-surface-600">已归档</dt>
+					<dd class="mt-0.5">{fmtDate(detail.archivedAt)}</dd>
+				</div>
+			{/if}
+			<div>
+				<dt class="text-surface-600">运行数</dt>
+				<dd class="mt-0.5 tabular-nums">{fmtNum(detail.runs.length)}</dd>
+			</div>
+		</dl>
+	</div>
+
+	<div class="mb-3">
+		<h2 class="saas-section-title">运行与计费事实</h2>
+		<p class="saas-muted">每条 UsageFact 是一次可计费消费；外部能力与模型完成分开列出。</p>
+	</div>
+
+	{#if detail.runs.length === 0}
+		<div class="saas-card">
+			<EmptyState title="尚无运行" description="此会话还没有 Agent run。" />
+		</div>
+	{:else}
+		<div class="space-y-3">
+			{#each detail.runs as run (run.id)}
+				{@const open = expandedRunId === run.id}
+				<div class="saas-card overflow-hidden">
+					<button
+						type="button"
+						class="flex w-full items-start justify-between gap-3 px-5 py-4 text-left hover:bg-surface-50"
+						onclick={() => toggleRun(run.id)}
+					>
+						<div class="min-w-0 space-y-1">
+							<div class="flex flex-wrap items-center gap-2">
+								<span class={statusClass(run.status)}>{runStatusLabel(run.status)}</span>
+								<span class="font-mono text-xs text-surface-700">{run.provider} / {run.model}</span>
+								<span class="font-mono text-[11px] text-surface-500">{run.id}</span>
+							</div>
+							<div class="text-xs text-surface-700">
+								{fmtDate(run.startedAt)}
+								{#if run.finishedAt}
+									→ {fmtDate(run.finishedAt)}
+								{/if}
+							</div>
+							<div class="text-xs text-surface-600">{runCostHint(run)}</div>
+							{#if run.error}
+								<div class="text-xs text-error-700">{run.error}</div>
+							{/if}
+						</div>
+						<div class="shrink-0 text-right text-sm">
+							<div class="tabular-nums text-surface-800">{fmtTokens(run.inputTokens, run.outputTokens)}</div>
+							<div class="tabular-nums font-medium">{fmtCost(run.costUsd)}</div>
+							<div class="mt-1 text-[11px] text-surface-600">{open ? '收起事实' : `${run.usageFacts.length} 条事实`}</div>
+						</div>
+					</button>
+
+					{#if open}
+						<div class="border-t border-surface-200">
+							{#if run.usageFacts.length === 0}
+								<div class="px-5 py-4">
+									<p class="text-sm text-surface-600">此 run 没有 UsageFact（可能尚未结束或未记费）。</p>
+								</div>
+							{:else}
+								<div class="overflow-x-auto">
+									<table class="data-table">
+										<thead>
+											<tr>
+												<th>时间</th>
+												<th>类型</th>
+												<th>供应方</th>
+												<th>模型 / 能力</th>
+												<th>计量</th>
+												<th>成本</th>
+												<th>来源</th>
+												<th>关联 ID</th>
+											</tr>
+										</thead>
+										<tbody>
+											{#each run.usageFacts as fact}
+												<tr>
+													<td class="whitespace-nowrap text-xs text-surface-700">{fmtDate(fact.occurredAt)}</td>
+													<td>
+														<span
+															class={fact.kind === 'external_capability'
+																? 'saas-badge-primary'
+																: 'saas-badge-success'}
+														>
+															{usageKindLabel(fact.kind)}
+														</span>
+													</td>
+													<td class="font-mono text-xs">{fact.provider}</td>
+													<td class="font-mono text-xs">{factSource(fact)}</td>
+													<td class="tabular-nums text-xs">{factMeter(fact)}</td>
+													<td class="tabular-nums">{fmtCost(fact.costUsd)}</td>
+													<td class="font-mono text-[11px] text-surface-600">{fact.costSource}</td>
+													<td class="max-w-[10rem] truncate font-mono text-[11px] text-surface-500" title={fact.correlationId ?? ''}>
+														{fact.correlationId ?? '—'}
+													</td>
+												</tr>
+											{/each}
+										</tbody>
+									</table>
+								</div>
+							{/if}
+						</div>
+					{/if}
+				</div>
+			{/each}
+		</div>
+	{/if}
+{/if}

hub/admin-web/src/routes/admin/skills/+page.svelte

@@ -0,0 +1,144 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type AgentSkillRow, type SkillFileEntry } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import EmptyState from '$lib/components/EmptyState.svelte';
+	import SkillEditor from '$lib/components/SkillEditor.svelte';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
+
+	let skills = $state<AgentSkillRow[]>([]);
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+
+	let showNewSkill = $state(false);
+	let newSkillName = $state('');
+	let newSkillVersion = $state('0.1.0');
+	let newSkillDescription = $state('');
+	let creating = $state(false);
+
+	async function load() {
+		loading = true;
+		error = null;
+		try {
+			const res = await api.agentSkills(slug);
+			skills = res.skills;
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	async function createSkill() {
+		const name = newSkillName.trim();
+		if (name === '') {
+			toastError('技能名称不能为空');
+			return;
+		}
+		if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(name)) {
+			toastError('技能名称仅允许小写字母、数字和连字符，且以字母或数字开头');
+			return;
+		}
+		const version = newSkillVersion.trim();
+		if (version === '') {
+			toastError('版本号不能为空');
+			return;
+		}
+		creating = true;
+		try {
+			const manifest = buildManifest(name, newSkillDescription.trim());
+			const files: SkillFileEntry[] = [{ path: 'SKILL.md', content: manifest }];
+			const result = await api.installAgentSkill(slug, name, { version, files });
+			toastSuccess(`技能 ${result.name} 已创建`);
+			newSkillName = '';
+			newSkillDescription = '';
+			showNewSkill = false;
+			await load();
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			creating = false;
+		}
+	}
+
+	function buildManifest(name: string, description: string): string {
+		const desc = description === '' ? name : description;
+		return `---\nname: ${name}\ndescription: ${desc}\n---\n# ${name}\n\n`;
+	}
+
+	function onInstalled(_result: { id: string; name: string; contentDigest: string }) {
+		load();
+	}
+
+	function onDisabled(_name: string) {
+		load();
+	}
+
+	$effect(() => {
+		if (slug) load();
+	});
+</script>
+
+<PageHeader
+	title="技能"
+	description="技能是组织级 Agent 能力包：一个包含 SKILL.md manifest 的目录。技能内容按 SHA-256 content-addressed 存储，变更后绑定角色的活跃会话自动归档。"
+/>
+
+{#if loading}
+	<LoadingState />
+{:else if error}
+	<ErrorBanner message={error} onretry={load} />
+{:else}
+	<div class="saas-card-pad mb-6">
+		<div class="flex items-center justify-between">
+			<h2 class="saas-section-title">新建技能</h2>
+			<button class="text-sm text-primary-700 hover:text-primary-900" onclick={() => (showNewSkill = !showNewSkill)}>
+				{showNewSkill ? '取消' : '+ 新建'}
+			</button>
+		</div>
+		{#if showNewSkill}
+			<div class="mt-4 grid gap-3 sm:grid-cols-[12rem_8rem_1fr_auto]">
+				<input
+					class="saas-input font-mono text-sm"
+					placeholder="技能名（如 typst-help）"
+					bind:value={newSkillName}
+				/>
+				<input
+					class="saas-input text-sm"
+					placeholder="版本号"
+					bind:value={newSkillVersion}
+				/>
+				<input
+					class="saas-input text-sm"
+					placeholder="描述"
+					bind:value={newSkillDescription}
+				/>
+				<button class="saas-btn-primary" onclick={createSkill} disabled={creating}>
+					{creating ? '创建中…' : '创建'}
+				</button>
+			</div>
+			<p class="mt-2 text-xs text-surface-600">
+				技能名称仅允许小写字母、数字和连字符，且以字母或数字开头。创建后会生成 SKILL.md 模板。
+			</p>
+		{/if}
+	</div>
+
+	{#if skills.length === 0}
+		<div class="saas-card">
+			<EmptyState title="暂无技能" description="新建一个技能，然后在角色管理中绑定到角色。" />
+		</div>
+	{:else}
+		<div class="space-y-4">
+			{#each skills as skill (skill.id)}
+				<SkillEditor {slug} {skill} oninstalled={onInstalled} ondisabled={onDisabled} />
+			{/each}
+		</div>
+	{/if}
+{/if}

hub/admin-web/src/routes/admin/teams/+page.svelte

@@ -0,0 +1,236 @@
+<script lang="ts">
+	import { Collapsible } from 'bits-ui';
+	import { page } from '$app/state';
+	import { api, type TeamRow, type TeamMemberRow } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
+	import { fmtDate } from '$lib/format';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import EmptyState from '$lib/components/EmptyState.svelte';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
+
+	let teams = $state<TeamRow[]>([]);
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+
+	let newSlug = $state('');
+	let newName = $state('');
+	let newDesc = $state('');
+	let adding = $state(false);
+
+	let expandedId = $state<string | null>(null);
+	let teamMembers = $state<TeamMemberRow[]>([]);
+	let memberInput = $state('');
+	let loadingMembers = $state(false);
+
+	async function load() {
+		loading = true;
+		error = null;
+		try {
+			const res = await api.teams(slug);
+			teams = res.teams;
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	const SLUG_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+
+	async function createTeam() {
+		if (!newSlug.trim() || !newName.trim()) return;
+		const teamSlug = newSlug.trim().toLowerCase();
+		if (!SLUG_RE.test(teamSlug)) {
+			toastError('标识须为小写字母数字，可用连字符连接');
+			return;
+		}
+		adding = true;
+		try {
+			await api.createTeam(slug, {
+				slug: teamSlug,
+				name: newName.trim(),
+				...(newDesc.trim() ? { description: newDesc.trim() } : {}),
+			});
+			newSlug = '';
+			newName = '';
+			newDesc = '';
+			await load();
+			toastSuccess('团队已创建');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			adding = false;
+		}
+	}
+
+	async function archiveTeam(t: TeamRow) {
+		if (!confirm(`归档团队 ${t.name}? 归档后该团队不再解析为项目授权主体。`)) return;
+		try {
+			await api.archiveTeam(slug, t.id);
+			if (expandedId === t.id) expandedId = null;
+			await load();
+			toastSuccess('团队已归档');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		}
+	}
+
+	async function openMembers(t: TeamRow) {
+		if (expandedId === t.id) return;
+		expandedId = t.id;
+		loadingMembers = true;
+		memberInput = '';
+		try {
+			const res = await api.teamMembers(slug, t.id);
+			teamMembers = res.members;
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			loadingMembers = false;
+		}
+	}
+
+	function onExpandChange(t: TeamRow, open: boolean) {
+		if (open) void openMembers(t);
+		else if (expandedId === t.id) expandedId = null;
+	}
+
+	async function addMember(t: TeamRow) {
+		if (!memberInput.trim()) return;
+		const v = memberInput.trim();
+		try {
+			await api.addTeamMember(slug, t.id, v.startsWith('ou') ? { feishuOpenId: v } : { userId: v });
+			memberInput = '';
+			const res = await api.teamMembers(slug, t.id);
+			teamMembers = res.members;
+			await load();
+			toastSuccess('已加入团队');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		}
+	}
+
+	async function revokeMember(t: TeamRow, m: TeamMemberRow) {
+		if (!confirm(`将 ${m.displayName} 移出团队 ${t.name}?`)) return;
+		try {
+			await api.revokeTeamMember(slug, t.id, m.userId);
+			const res = await api.teamMembers(slug, t.id);
+			teamMembers = res.members;
+			await load();
+			toastSuccess('已移出团队');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		}
+	}
+
+	$effect(() => {
+		if (slug) load();
+	});
+</script>
+
+<PageHeader title="团队" description="团队是项目授权主体，可被授予只读、编辑或管理权限。" />
+
+{#if loading}
+	<LoadingState />
+{:else if error}
+	<ErrorBanner message={error} onretry={load} />
+{:else}
+	<div class="saas-card-pad mb-6">
+		<h2 class="saas-section-title mb-4">新建团队</h2>
+		<div class="grid gap-3 md:grid-cols-[1fr_1fr_1.2fr_auto]">
+			<input class="saas-input" placeholder="标识（如 math-g7）" bind:value={newSlug} />
+			<input class="saas-input" placeholder="名称" bind:value={newName} />
+			<input class="saas-input" placeholder="描述（可选）" bind:value={newDesc} />
+			<button class="saas-btn-primary" onclick={createTeam} disabled={adding}>新建</button>
+		</div>
+	</div>
+
+	{#if teams.length === 0}
+		<div class="saas-card">
+			<EmptyState title="暂无团队" description="创建团队后，可在项目页授权项目访问。" />
+		</div>
+	{:else}
+		<div class="space-y-3">
+			{#each teams as t (t.id)}
+				<Collapsible.Root
+					class="saas-card p-5"
+					open={expandedId === t.id}
+					onOpenChange={(open) => onExpandChange(t, open)}
+				>
+					<div class="flex flex-wrap items-center gap-2.5">
+						<span class="text-base font-semibold text-surface-900">{t.name}</span>
+						<span class="font-mono text-xs text-surface-600">/{t.slug}</span>
+						<span class="saas-badge-neutral">{t.memberCount} 成员</span>
+						<div class="ml-auto flex flex-wrap gap-2">
+							<Collapsible.Trigger class="saas-btn-secondary py-1.5! text-sm">
+								{expandedId === t.id ? '收起' : '管理成员'}
+							</Collapsible.Trigger>
+							<button type="button" class="saas-btn-danger py-1.5! text-sm" onclick={() => archiveTeam(t)}>
+								归档
+							</button>
+						</div>
+					</div>
+					{#if t.description}
+						<p class="mt-1.5 text-sm text-surface-700">{t.description}</p>
+					{/if}
+					<p class="mt-1 text-xs text-surface-600">创建于 {fmtDate(t.createdAt)}</p>
+
+					<Collapsible.Content>
+						<div class="mt-4 border-t border-surface-200 pt-4">
+							{#if loadingMembers && expandedId === t.id}
+								<p class="text-sm text-surface-600">加载中…</p>
+							{:else if expandedId === t.id}
+								<div class="mb-4 flex gap-2">
+									<input
+										class="saas-input"
+										placeholder="飞书 open_id 或用户 id"
+										bind:value={memberInput}
+										onkeydown={(e) => {
+											if (e.key === 'Enter') addMember(t);
+										}}
+									/>
+									<button class="saas-btn-secondary shrink-0" onclick={() => addMember(t)}>加入</button>
+								</div>
+								{#if teamMembers.length === 0}
+									<p class="py-3 text-center text-sm text-surface-600">团队暂无成员</p>
+								{:else}
+									<table class="data-table">
+										<thead>
+											<tr>
+												<th>成员</th>
+												<th>open_id</th>
+												<th>加入时间</th>
+												<th></th>
+											</tr>
+										</thead>
+										<tbody>
+											{#each teamMembers as m}
+												<tr>
+													<td class="font-medium">{m.displayName}</td>
+													<td class="font-mono text-xs">{m.feishuOpenId}</td>
+													<td class="text-surface-700">{fmtDate(m.createdAt)}</td>
+													<td class="text-right">
+														<button class="saas-btn-danger py-1! text-xs" onclick={() => revokeMember(t, m)}>
+															移除
+														</button>
+													</td>
+												</tr>
+											{/each}
+										</tbody>
+									</table>
+								{/if}
+							{/if}
+						</div>
+					</Collapsible.Content>
+				</Collapsible.Root>
+			{/each}
+		</div>
+	{/if}
+	<p class="mt-4 text-xs text-surface-600">归档团队会同步撤销其活跃的项目授权。</p>
+{/if}

hub/admin-web/src/routes/admin/usage/+page.svelte

@@ -0,0 +1,241 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type UsageReport, type UsageBreakdownRow } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
+	import {
+		fmtCost,
+		fmtDateOnly,
+		fmtNum,
+		fmtQuantity,
+		fmtTokens,
+		usageKindLabel,
+	} from '$lib/format';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import StatCard from '$lib/components/StatCard.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import EmptyState from '$lib/components/EmptyState.svelte';
+
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
+
+	let usage = $state<UsageReport | null>(null);
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+	let from = $state('');
+	let to = $state('');
+
+	function toIsoStart(dateLocal: string): string | undefined {
+		if (!dateLocal) return undefined;
+		const d = new Date(`${dateLocal}T00:00:00`);
+		return Number.isNaN(d.getTime()) ? undefined : d.toISOString();
+	}
+
+	function toIsoEnd(dateLocal: string): string | undefined {
+		if (!dateLocal) return undefined;
+		const d = new Date(`${dateLocal}T23:59:59.999`);
+		return Number.isNaN(d.getTime()) ? undefined : d.toISOString();
+	}
+
+	async function load() {
+		if (!slug) return;
+		loading = true;
+		error = null;
+		try {
+			usage = await api.usage(slug, {
+				...(toIsoStart(from) !== undefined ? { from: toIsoStart(from) } : {}),
+				...(toIsoEnd(to) !== undefined ? { to: toIsoEnd(to) } : {}),
+			});
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	function clearRange() {
+		from = '';
+		to = '';
+		void load();
+	}
+
+	function sourceLabel(row: UsageBreakdownRow): string {
+		if (row.capabilityId) return row.capabilityId;
+		if (row.model) return row.model;
+		return '—';
+	}
+
+	function meterCell(row: UsageBreakdownRow): string {
+		if (row.unit) return fmtQuantity(row.quantity, row.unit);
+		if (row.inputTokens > 0 || row.outputTokens > 0) return fmtTokens(row.inputTokens, row.outputTokens);
+		return '—';
+	}
+
+	function meterHint(row: UsageBreakdownRow): string {
+		if (row.unit) return '非 token 计量';
+		if (row.inputTokens > 0 || row.outputTokens > 0) return 'in / out tokens';
+		return '无计量';
+	}
+
+	$effect(() => {
+		if (slug) void load();
+	});
+</script>
+
+{#if loading && !usage}
+	<LoadingState />
+{:else if error && !usage}
+	<ErrorBanner message={error} onretry={load} />
+{:else if usage}
+	<PageHeader
+		title="用量报告"
+		description="按 UsageFact 分账：模型完成与外部能力（PDF→MD、ASR 等）分开汇总。缺失成本计为未知，不为 0。"
+	/>
+
+	<div class="saas-card-pad mb-6">
+		<div class="flex flex-wrap items-end gap-3">
+			<div>
+				<label class="saas-label" for="usage-from">从</label>
+				<input id="usage-from" class="saas-input" type="date" bind:value={from} />
+			</div>
+			<div>
+				<label class="saas-label" for="usage-to">到</label>
+				<input id="usage-to" class="saas-input" type="date" bind:value={to} />
+			</div>
+			<button class="saas-btn-primary py-1.5! text-sm" type="button" onclick={load} disabled={loading}>
+				{loading ? '加载中…' : '应用筛选'}
+			</button>
+			<button class="saas-btn-secondary py-1.5! text-sm" type="button" onclick={clearRange} disabled={loading}>
+				清除
+			</button>
+			{#if usage.from || usage.to}
+				<p class="saas-muted grow text-right text-xs">
+					窗口：
+					{usage.from ? fmtDateOnly(usage.from) : '—'}
+					→
+					{usage.to ? fmtDateOnly(usage.to) : '—'}
+				</p>
+			{/if}
+		</div>
+		{#if error}
+			<p class="mt-3 text-sm text-error-700">{error}</p>
+		{/if}
+	</div>
+
+	<div class="mb-6 grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+		<StatCard label="运行总数" value={fmtNum(usage.totals.runCount)} />
+		<StatCard
+			label="有成本 / 无成本"
+			value={`${fmtNum(usage.totals.runsWithCost)} / ${fmtNum(usage.totals.runsWithoutCost)}`}
+			hint="无成本 = 成本未知，不是 $0"
+		/>
+		<StatCard label="成本 (USD)" value={fmtCost(usage.totals.costUsd)} hint="仅汇总已知 costUsd" />
+		<StatCard label="输入 tokens" value={fmtNum(usage.totals.inputTokens)} hint="主要来自模型完成" />
+		<StatCard label="输出 tokens" value={fmtNum(usage.totals.outputTokens)} hint="主要来自模型完成" />
+		<StatCard
+			label="分账条目"
+			value={fmtNum(usage.breakdown.reduce((n, b) => n + b.factCount, 0))}
+			hint={`${fmtNum(usage.breakdown.length)} 个分项`}
+		/>
+	</div>
+
+	<div class="saas-card overflow-hidden mb-6">
+		<div class="border-b border-surface-200 px-5 py-3">
+			<h3 class="text-sm font-semibold text-surface-800">按来源分账</h3>
+			<p class="saas-muted mt-0.5 text-xs">
+				kind × provider × model/capability。外部能力显示页数/秒等计量，不与 tokens 混排。
+			</p>
+		</div>
+		{#if usage.breakdown.length === 0}
+			<EmptyState title="暂无用量事实" description="跑过智能体后，模型与外部能力消费会出现在此。" />
+		{:else}
+			<div class="overflow-x-auto">
+				<table class="data-table">
+					<thead>
+						<tr>
+							<th>类型</th>
+							<th>供应方</th>
+							<th>模型 / 能力</th>
+							<th>次数</th>
+							<th>计量</th>
+							<th>有成本 / 未知</th>
+							<th>成本</th>
+						</tr>
+					</thead>
+					<tbody>
+						{#each usage.breakdown as row}
+							<tr>
+								<td>
+									<span
+										class={row.kind === 'external_capability'
+											? 'saas-badge-primary'
+											: row.kind === 'model_completion'
+												? 'saas-badge-success'
+												: 'saas-badge-primary'}
+									>
+										{usageKindLabel(row.kind)}
+									</span>
+								</td>
+								<td class="font-mono text-xs">{row.provider}</td>
+								<td class="font-mono text-xs">{sourceLabel(row)}</td>
+								<td class="tabular-nums">{fmtNum(row.factCount)}</td>
+								<td class="tabular-nums">
+									<div>{meterCell(row)}</div>
+									<div class="text-[11px] text-surface-600">{meterHint(row)}</div>
+								</td>
+								<td class="tabular-nums text-surface-700">
+									{fmtNum(row.factsWithCost)} / {fmtNum(row.factsWithoutCost)}
+								</td>
+								<td class="tabular-nums font-medium">{fmtCost(row.costUsd)}</td>
+							</tr>
+						{/each}
+					</tbody>
+				</table>
+			</div>
+		{/if}
+	</div>
+
+	<div class="saas-card overflow-hidden">
+		<div class="border-b border-surface-200 px-5 py-3">
+			<h3 class="text-sm font-semibold text-surface-800">按项目</h3>
+			<p class="saas-muted mt-0.5 text-xs">项目仍是权限边界；行内成本已含该项目全部 fact 类型。</p>
+		</div>
+		{#if usage.projects.length === 0}
+			<EmptyState title="暂无项目" description="创建项目并触发智能体后会出现用量。" />
+		{:else}
+			<div class="overflow-x-auto">
+				<table class="data-table">
+					<thead>
+						<tr>
+							<th>项目</th>
+							<th>运行</th>
+							<th>有成本 / 未知</th>
+							<th>in / out tokens</th>
+							<th>成本</th>
+							<th></th>
+						</tr>
+					</thead>
+					<tbody>
+						{#each usage.projects as p}
+							<tr>
+								<td class="font-medium">{p.projectName}</td>
+								<td class="tabular-nums">{fmtNum(p.runCount)}</td>
+								<td class="tabular-nums text-surface-700">
+									{fmtNum(p.runsWithCost)} / {fmtNum(p.runsWithoutCost)}
+								</td>
+								<td class="tabular-nums text-surface-600">{fmtTokens(p.inputTokens, p.outputTokens)}</td>
+								<td class="tabular-nums">{fmtCost(p.costUsd)}</td>
+								<td class="text-right">
+									<a class="text-sm text-primary-700 hover:underline" href={`/admin/projects/${p.projectId}`}>
+										查看项目
+									</a>
+								</td>
+							</tr>
+						{/each}
+					</tbody>
+				</table>
+			</div>
+		{/if}
+	</div>
+{/if}

hub/admin-web/src/routes/app.css

@@ -0,0 +1,692 @@
+@import 'tailwindcss';
+
+@import '@skeletonlabs/skeleton';
+@import '@skeletonlabs/skeleton/themes/hamlindigo';
+
+@source './**/*.{html,js,svelte,ts}';
+@source '../lib/**/*.{html,js,svelte,ts}';
+
+/* Flat industrial: zero radius, higher-contrast surfaces, CJK-first type */
+@theme {
+	--font-sans:
+		'Noto Sans SC', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Inter', ui-sans-serif, system-ui,
+		-apple-system, 'Segoe UI', sans-serif;
+	--font-mono: 'JetBrains Mono', ui-monospace, 'SF Mono', Menlo, Consolas, monospace;
+
+	--radius-none: 0;
+	--radius-sm: 0;
+	--radius-md: 0;
+	--radius-lg: 0;
+	--radius-xl: 0;
+	--radius-2xl: 0;
+	--radius-3xl: 0;
+	--radius-full: 0;
+	--radius: 0;
+}
+
+@layer base {
+	html {
+		height: 100%;
+		-webkit-font-smoothing: antialiased;
+		-moz-osx-font-smoothing: grayscale;
+		text-rendering: optimizeLegibility;
+		font-feature-settings:
+			'kern' 1,
+			'liga' 1;
+		/* Prefer readable CJK metrics over Latin optical sizing */
+		text-size-adjust: 100%;
+	}
+
+	body {
+		min-height: 100%;
+		font-family: var(--font-sans);
+		font-size: 15px;
+		line-height: 1.7;
+		letter-spacing: 0.01em;
+		/* Slightly cooler industrial surface */
+		background: var(--color-surface-100);
+		color: var(--color-surface-950, var(--color-surface-900));
+		font-variant-east-asian: proportional-width;
+	}
+
+	/* CJK headings: no negative tracking, breathing line-height */
+	h1,
+	h2,
+	h3,
+	h4,
+	h5,
+	h6 {
+		font-weight: 600;
+		line-height: 1.45;
+		letter-spacing: 0;
+		color: var(--color-surface-950, var(--color-surface-900));
+	}
+
+	p {
+		line-height: 1.75;
+	}
+
+	/* Harder focus ring for industrial UI */
+	:focus-visible {
+		outline: 2px solid var(--color-primary-600);
+		outline-offset: 2px;
+	}
+
+	::selection {
+		background: color-mix(in oklab, var(--color-primary-600) 35%, transparent);
+		color: var(--color-surface-950, var(--color-surface-900));
+	}
+
+	/* Tables: high-contrast grid, flat */
+	table.data-table {
+		width: 100%;
+		border-collapse: collapse;
+		font-size: 0.875rem;
+		line-height: 1.6;
+	}
+
+	table.data-table thead th {
+		padding: 0.625rem 0.75rem;
+		text-align: left;
+		font-weight: 600;
+		color: var(--color-surface-700);
+		background: var(--color-surface-100);
+		border-bottom: 1px solid var(--color-surface-300);
+		white-space: nowrap;
+		letter-spacing: 0.02em;
+	}
+
+	table.data-table tbody td {
+		padding: 0.75rem;
+		border-bottom: 1px solid var(--color-surface-200);
+		vertical-align: middle;
+		color: var(--color-surface-900);
+	}
+
+	table.data-table tbody tr:hover td {
+		background: var(--color-surface-100);
+	}
+
+	table.data-table tbody tr:last-child td {
+		border-bottom: none;
+	}
+}
+
+@layer components {
+	.saas-card {
+		border-radius: 0;
+		border: 1px solid var(--color-surface-300);
+		background: var(--color-surface-50);
+		box-shadow: none;
+	}
+
+	.saas-card-pad {
+		border-radius: 0;
+		border: 1px solid var(--color-surface-300);
+		background: var(--color-surface-50);
+		box-shadow: none;
+		padding: 1.25rem;
+	}
+
+	.saas-page-title {
+		font-size: 1.375rem;
+		line-height: 1.4;
+		font-weight: 700;
+		letter-spacing: 0;
+		color: var(--color-surface-950, var(--color-surface-900));
+	}
+
+	.saas-section-title {
+		font-size: 1rem;
+		line-height: 1.5;
+		font-weight: 600;
+		letter-spacing: 0;
+		color: var(--color-surface-950, var(--color-surface-900));
+	}
+
+	.saas-muted {
+		font-size: 0.875rem;
+		line-height: 1.65;
+		color: var(--color-surface-700);
+	}
+
+	.saas-label {
+		display: block;
+		margin-bottom: 0.375rem;
+		font-size: 0.875rem;
+		line-height: 1.5;
+		font-weight: 600;
+		color: var(--color-surface-800);
+	}
+
+	.saas-help {
+		margin-top: 0.375rem;
+		font-size: 0.8125rem;
+		line-height: 1.6;
+		color: var(--color-surface-600);
+	}
+
+	.saas-toolbar {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: center;
+		gap: 0.75rem;
+		margin-bottom: 1.5rem;
+	}
+
+	.saas-stat {
+		border-radius: 0;
+		border: 1px solid var(--color-surface-300);
+		background: var(--color-surface-50);
+		padding: 1rem;
+		box-shadow: none;
+	}
+
+	.saas-stat-label {
+		font-size: 0.75rem;
+		font-weight: 600;
+		letter-spacing: 0.04em;
+		text-transform: uppercase;
+		color: var(--color-surface-600);
+	}
+
+	.saas-stat-value {
+		margin-top: 0.25rem;
+		font-size: 1.5rem;
+		line-height: 1.3;
+		font-weight: 700;
+		font-variant-numeric: tabular-nums;
+		letter-spacing: 0;
+		color: var(--color-surface-950, var(--color-surface-900));
+	}
+
+	.saas-empty {
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+		justify-content: center;
+		gap: 0.5rem;
+		padding: 3rem 1rem;
+		text-align: center;
+		line-height: 1.7;
+	}
+
+	.saas-shell {
+		display: flex;
+		height: 100vh;
+		overflow: hidden;
+		background: var(--color-surface-100);
+	}
+
+	.saas-sidebar {
+		display: flex;
+		width: 16rem;
+		flex-shrink: 0;
+		flex-direction: column;
+		border-right: 1px solid var(--color-surface-300);
+		background: var(--color-surface-50);
+	}
+
+	.saas-main {
+		display: flex;
+		min-width: 0;
+		flex: 1;
+		flex-direction: column;
+		overflow: hidden;
+	}
+
+	.saas-topbar {
+		display: flex;
+		height: 3.5rem;
+		flex-shrink: 0;
+		align-items: center;
+		gap: 0.75rem;
+		border-bottom: 1px solid var(--color-surface-300);
+		background: var(--color-surface-50);
+		padding: 0 1.5rem;
+		/* flat: no glass */
+		backdrop-filter: none;
+	}
+
+	.saas-content {
+		flex: 1;
+		overflow-y: auto;
+	}
+
+	.saas-content-inner {
+		margin-inline: auto;
+		width: 100%;
+		max-width: 72rem;
+		padding: 1.5rem;
+	}
+
+	@media (min-width: 768px) {
+		.saas-content-inner {
+			padding: 2rem;
+		}
+	}
+
+	.saas-nav-item {
+		display: flex;
+		align-items: center;
+		gap: 0.75rem;
+		border-radius: 0;
+		padding: 0.5rem 0.75rem;
+		font-size: 0.875rem;
+		line-height: 1.5;
+		font-weight: 500;
+		color: var(--color-surface-700);
+		border-left: 2px solid transparent;
+		transition:
+			color 0.1s,
+			background-color 0.1s,
+			border-color 0.1s;
+	}
+
+	.saas-nav-item:hover {
+		background: var(--color-surface-100);
+		color: var(--color-surface-950, var(--color-surface-900));
+	}
+
+	.saas-nav-item[data-active='true'] {
+		background: var(--color-primary-50, var(--color-primary-100));
+		color: var(--color-primary-800);
+		border-left-color: var(--color-primary-600);
+		font-weight: 600;
+	}
+
+	.saas-badge {
+		display: inline-flex;
+		align-items: center;
+		border-radius: 0;
+		padding: 0.125rem 0.5rem;
+		font-size: 0.75rem;
+		line-height: 1.4;
+		font-weight: 600;
+		letter-spacing: 0.02em;
+	}
+
+	.saas-badge-neutral {
+		display: inline-flex;
+		align-items: center;
+		border-radius: 0;
+		padding: 0.125rem 0.5rem;
+		font-size: 0.75rem;
+		line-height: 1.4;
+		font-weight: 600;
+		border: 1px solid var(--color-surface-300);
+		background: var(--color-surface-100);
+		color: var(--color-surface-800);
+	}
+
+	.saas-badge-primary {
+		display: inline-flex;
+		align-items: center;
+		border-radius: 0;
+		padding: 0.125rem 0.5rem;
+		font-size: 0.75rem;
+		line-height: 1.4;
+		font-weight: 600;
+		border: 1px solid var(--color-primary-300);
+		background: var(--color-primary-100);
+		color: var(--color-primary-800);
+	}
+
+	.saas-badge-success {
+		display: inline-flex;
+		align-items: center;
+		border-radius: 0;
+		padding: 0.125rem 0.5rem;
+		font-size: 0.75rem;
+		line-height: 1.4;
+		font-weight: 600;
+		border: 1px solid var(--color-success-300);
+		background: var(--color-success-100);
+		color: var(--color-success-800);
+	}
+
+	.saas-badge-warning {
+		display: inline-flex;
+		align-items: center;
+		border-radius: 0;
+		padding: 0.125rem 0.5rem;
+		font-size: 0.75rem;
+		line-height: 1.4;
+		font-weight: 600;
+		border: 1px solid var(--color-warning-300);
+		background: var(--color-warning-100);
+		color: var(--color-warning-900);
+	}
+
+	.saas-badge-error {
+		display: inline-flex;
+		align-items: center;
+		border-radius: 0;
+		padding: 0.125rem 0.5rem;
+		font-size: 0.75rem;
+		line-height: 1.4;
+		font-weight: 600;
+		border: 1px solid var(--color-error-300);
+		background: var(--color-error-100);
+		color: var(--color-error-800);
+	}
+
+	.saas-input,
+	.saas-select,
+	.saas-textarea {
+		width: 100%;
+		border-radius: 0;
+		border: 1px solid var(--color-surface-400);
+		background: var(--color-surface-50);
+		color: var(--color-surface-950, var(--color-surface-900));
+		padding: 0.5rem 0.75rem;
+		font-size: 0.875rem;
+		line-height: 1.5;
+		outline: none;
+		transition:
+			border-color 0.1s,
+			box-shadow 0.1s;
+	}
+
+	.saas-input::placeholder,
+	.saas-textarea::placeholder {
+		color: var(--color-surface-500);
+	}
+
+	.saas-input:focus,
+	.saas-select:focus,
+	.saas-textarea:focus {
+		border-color: var(--color-primary-600);
+		box-shadow: inset 0 0 0 1px var(--color-primary-600);
+	}
+
+	.saas-textarea {
+		font-family: var(--font-mono);
+		line-height: 1.55;
+		resize: vertical;
+	}
+
+	.saas-select-trigger {
+		display: inline-flex;
+		width: 100%;
+		align-items: center;
+		border-radius: 0;
+		border: 1px solid var(--color-surface-400);
+		background: var(--color-surface-50);
+		color: var(--color-surface-950, var(--color-surface-900));
+		padding: 0.5rem 0.75rem;
+		font-size: 0.875rem;
+		line-height: 1.5;
+		outline: none;
+		transition:
+			border-color 0.1s,
+			box-shadow 0.1s;
+		cursor: pointer;
+		text-align: left;
+	}
+
+	.saas-select-trigger:focus-visible,
+	.saas-select-trigger[data-state='open'] {
+		border-color: var(--color-primary-600);
+		box-shadow: inset 0 0 0 1px var(--color-primary-600);
+	}
+
+	.saas-select-trigger:disabled,
+	.saas-select-trigger[data-disabled] {
+		cursor: not-allowed;
+		opacity: 0.55;
+	}
+
+	.saas-select-trigger [data-placeholder] {
+		color: var(--color-surface-500);
+	}
+
+	.saas-select-content {
+		z-index: 70;
+		max-height: min(18rem, var(--bits-select-content-available-height, 18rem));
+		width: var(--bits-select-anchor-width);
+		min-width: var(--bits-select-anchor-width);
+		overflow: hidden;
+		border-radius: 0;
+		border: 1px solid var(--color-surface-400);
+		background: var(--color-surface-50);
+		box-shadow: 4px 4px 0 rgb(15 23 42 / 0.12);
+		outline: none;
+	}
+
+	.saas-select-item {
+		display: flex;
+		align-items: center;
+		border-radius: 0;
+		padding: 0.45rem 0.65rem;
+		font-size: 0.875rem;
+		line-height: 1.5;
+		color: var(--color-surface-900);
+		cursor: pointer;
+		outline: none;
+		user-select: none;
+	}
+
+	.saas-select-item[data-highlighted] {
+		background: var(--color-primary-100);
+		color: var(--color-primary-900);
+	}
+
+	.saas-select-item[data-selected] {
+		color: var(--color-primary-900);
+		font-weight: 600;
+	}
+
+	.saas-select-item[data-disabled] {
+		cursor: not-allowed;
+		opacity: 0.45;
+	}
+
+	.saas-btn-primary,
+	.saas-btn-secondary,
+	.saas-btn-ghost,
+	.saas-btn-danger {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		gap: 0.375rem;
+		border-radius: 0;
+		padding: 0.5rem 0.875rem;
+		font-size: 0.875rem;
+		font-weight: 600;
+		line-height: 1.4;
+		letter-spacing: 0.01em;
+		border: 1px solid transparent;
+		cursor: pointer;
+		transition:
+			background-color 0.1s,
+			color 0.1s,
+			border-color 0.1s,
+			opacity 0.1s;
+	}
+
+	.saas-btn-primary:disabled,
+	.saas-btn-secondary:disabled,
+	.saas-btn-ghost:disabled,
+	.saas-btn-danger:disabled {
+		opacity: 0.55;
+		cursor: not-allowed;
+	}
+
+	.saas-btn-primary {
+		background: var(--color-primary-600);
+		border-color: var(--color-primary-700);
+		color: var(--color-primary-contrast-500, white);
+	}
+
+	.saas-btn-primary:hover:not(:disabled) {
+		background: var(--color-primary-700);
+		border-color: var(--color-primary-800);
+	}
+
+	.saas-btn-secondary {
+		background: var(--color-surface-100);
+		border-color: var(--color-surface-400);
+		color: var(--color-surface-900);
+	}
+
+	.saas-btn-secondary:hover:not(:disabled) {
+		background: var(--color-surface-200);
+		border-color: var(--color-surface-500);
+	}
+
+	.saas-btn-ghost {
+		background: transparent;
+		border-color: transparent;
+		color: var(--color-surface-800);
+	}
+
+	.saas-btn-ghost:hover:not(:disabled) {
+		background: var(--color-surface-200);
+		color: var(--color-surface-950, var(--color-surface-900));
+	}
+
+	.saas-btn-danger {
+		background: var(--color-error-100);
+		border-color: var(--color-error-400);
+		color: var(--color-error-800);
+	}
+
+	.saas-btn-danger:hover:not(:disabled) {
+		background: var(--color-error-200);
+		border-color: var(--color-error-500);
+	}
+
+	.saas-checkbox {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		width: 1.1rem;
+		height: 1.1rem;
+		flex-shrink: 0;
+		border-radius: 0;
+		border: 1px solid var(--color-surface-500);
+		background: var(--color-surface-50);
+		color: white;
+		cursor: pointer;
+		transition:
+			background 0.1s,
+			border-color 0.1s;
+	}
+
+	.saas-checkbox[data-state='checked'] {
+		background: var(--color-primary-700);
+		border-color: var(--color-primary-700);
+	}
+
+	.saas-checkbox:focus-visible {
+		outline: none;
+		box-shadow:
+			0 0 0 2px var(--color-surface-50),
+			0 0 0 4px var(--color-primary-600);
+	}
+
+	.saas-checkbox[data-disabled] {
+		cursor: not-allowed;
+		opacity: 0.5;
+	}
+
+	/* Square industrial switch (no pill) */
+	.saas-switch {
+		position: relative;
+		display: inline-flex;
+		width: 2.5rem;
+		height: 1.35rem;
+		flex-shrink: 0;
+		align-items: center;
+		border-radius: 0;
+		border: 1px solid var(--color-surface-500);
+		background: var(--color-surface-300);
+		padding: 0.125rem;
+		cursor: pointer;
+		transition:
+			background 0.1s,
+			border-color 0.1s;
+	}
+
+	.saas-switch[data-state='checked'] {
+		background: var(--color-primary-600);
+		border-color: var(--color-primary-700);
+	}
+
+	.saas-switch:focus-visible {
+		outline: none;
+		box-shadow:
+			0 0 0 2px var(--color-surface-50),
+			0 0 0 4px var(--color-primary-600);
+	}
+
+	.saas-switch[data-disabled] {
+		cursor: not-allowed;
+		opacity: 0.5;
+	}
+
+	.saas-switch-thumb {
+		display: block;
+		width: 1rem;
+		height: 1rem;
+		border-radius: 0;
+		background: white;
+		border: 1px solid var(--color-surface-400);
+		box-shadow: none;
+		transition: transform 0.1s;
+		transform: translateX(0);
+	}
+
+	.saas-switch[data-state='checked'] .saas-switch-thumb,
+	.saas-switch-thumb[data-state='checked'] {
+		transform: translateX(1.1rem);
+		border-color: var(--color-primary-800);
+	}
+
+	.saas-modal-backdrop {
+		position: fixed;
+		inset: 0;
+		z-index: 50;
+		background: rgb(2 6 23 / 0.55);
+		backdrop-filter: none;
+	}
+
+	.saas-modal {
+		position: fixed;
+		left: 50%;
+		top: 50%;
+		z-index: 51;
+		width: calc(100% - 2rem);
+		max-width: 28rem;
+		transform: translate(-50%, -50%);
+		border-radius: 0;
+		border: 1px solid var(--color-surface-400);
+		background: var(--color-surface-50);
+		padding: 1.5rem;
+		box-shadow: 6px 6px 0 rgb(15 23 42 / 0.15);
+		outline: none;
+	}
+
+	.saas-status-panel {
+		display: flex;
+		min-height: 100vh;
+		flex-direction: column;
+		align-items: center;
+		justify-content: center;
+		background: var(--color-surface-100);
+		padding: 1rem;
+	}
+
+	.saas-status-card {
+		width: 100%;
+		max-width: 28rem;
+		border-radius: 0;
+		border: 1px solid var(--color-surface-400);
+		background: var(--color-surface-50);
+		padding: 2rem;
+		text-align: center;
+		box-shadow: 4px 4px 0 rgb(15 23 42 / 0.1);
+		line-height: 1.7;
+	}
+}

hub/admin-web/static/favicon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
+	<rect width="32" height="32" rx="8" fill="#4F46E5"/>
+	<path d="M8 10.5h7.5a3.5 3.5 0 0 1 0 7H11v4H8v-11Zm3 4.5h4.5a1.5 1.5 0 0 0 0-3H11v3Z" fill="white"/>
+	<path d="M20.5 21.5c1.93 0 3.5-1.34 3.5-3s-1.57-3-3.5-3S17 16.84 17 18.5s1.57 3 3.5 3Z" fill="white" opacity=".9"/>
+</svg>

hub/admin-web/static/robots.txt

@@ -0,0 +1,3 @@
+# allow crawling everything by default
+User-agent: *
+Disallow:

hub/admin-web/svelte.config.js

@@ -0,0 +1,18 @@
+import adapter from '@sveltejs/adapter-static';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+	preprocess: vitePreprocess(),
+	kit: {
+		adapter: adapter({
+			pages: 'build',
+			assets: 'build',
+			fallback: 'index.html',
+			precompress: false,
+			strict: false,
+		}),
+	},
+};
+
+export default config;

hub/admin-web/tsconfig.json

@@ -0,0 +1,20 @@
+{
+	"extends": "./.svelte-kit/tsconfig.json",
+	"compilerOptions": {
+		"rewriteRelativeImportExtensions": true,
+		"allowJs": true,
+		"checkJs": true,
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"sourceMap": true,
+		"strict": true,
+		"moduleResolution": "bundler"
+	}
+	// Path aliases are handled by https://svelte.dev/docs/kit/configuration#alias
+	// except $lib which is handled by https://svelte.dev/docs/kit/configuration#files
+	//
+	// To make changes to top-level options such as include and exclude, we recommend extending
+	// the generated config; see https://svelte.dev/docs/kit/configuration#typescript
+}

hub/admin-web/vite.config.ts

@@ -0,0 +1,17 @@
+import { sveltekit } from '@sveltejs/kit/vite';
+import tailwindcss from '@tailwindcss/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+	plugins: [tailwindcss(), sveltekit()],
+	server: {
+		proxy: {
+			'/api': 'http://127.0.0.1:8788',
+			'/auth': 'http://127.0.0.1:8788',
+			// Backend owns /admin/login (registered before the SPA fallback in
+			// src/admin/static.ts). Proxy it in dev so the SPA doesn't re-render
+			// its layout on that path and 401-redirect into a returnTo loop.
+			'/admin/login': 'http://127.0.0.1:8788',
+		},
+	},
+});

hub/deploy/README.md

@@ -11,6 +11,32 @@ See [NEW_SILO_RUNBOOK.md](NEW_SILO_RUNBOOK.md). The remainder of this document
 describes the individual installer and maintenance primitives used by the
 generated bundle.
 
+## CI: roll Hub + admin SPA by fleet (`educraft` / `educraft-dev`)
+
+`.gitea/workflows/deploy-admin.yml` deploys Hub releases (including the org-admin
+SPA) to the managed Alpha host via `deploy_fleet_release.sh`. Fleets share the
+host and are selected by the middle DNS label of `HUB_PUBLIC_BASE_URL`:
+
+| Fleet | Domain | CI trigger |
+|-------|--------|------------|
+| **dev** | `https://<slug>.educraft-dev.paradigm-edu.net` | every push + PR (paths under `hub/`) |
+| **prod** | `https://<slug>.educraft.paradigm-edu.net` | push to `main` + tags |
+
+Example prod tenant:
+`https://para-26071100.educraft.paradigm-edu.net/auth/feishu/para-26071100`.
+
+Required Gitea secret: `DEPLOY_SSH_KEY` (private key for `root@39.107.254.4`).
+Optional: `DEPLOY_HOST` / `DEPLOY_USER` / `DEPLOY_SSH_PORT` / `DEPLOY_BASE`.
+Set repository var `ALLOW_EMPTY_FLEET=1` until the first silo exists for a fleet.
+
+Local dry-run against the host:
+
+```sh
+CPH_FLEET=dev \
+  PLATFORM_DEPLOY_SSH_KEY=$HOME/.ssh/id_ed25519 \
+  bash hub/deploy/deploy_fleet_release.sh
+```
+
 The supervised alpha runs one Organization per named Silo. The supported host
 has systemd, PostgreSQL, Node.js 24+, `pg_isready`, `runuser`, `setpriv`,
 bubblewrap, `socat`, `pg_dump`, `tar`, `sha256sum`, and a compatible `cph`.

hub/deploy/deploy_fleet_release.sh

@@ -0,0 +1,225 @@
+#!/usr/bin/env bash
+# Publish one immutable Hub release (tsc + admin-web SPA) to the managed host,
+# then repoint every Silo in the chosen fleet to that release and restart it.
+#
+# Fleet is selected by the middle DNS label of each Silo's HUB_PUBLIC_BASE_URL:
+#
+#   prod → https://<slug>.educraft.paradigm-edu.net
+#   dev  → https://<slug>.educraft-dev.paradigm-edu.net
+#
+# Example tenant (prod):
+#   https://para-26071100.educraft.paradigm-edu.net/auth/feishu/para-26071100
+#
+# Configure (CI secrets / env):
+#   CPH_FLEET                 required: dev | prod
+#   PLATFORM_DEPLOY_HOST      default 39.107.254.4
+#   PLATFORM_DEPLOY_USER      default root
+#   PLATFORM_DEPLOY_SSH_KEY   required (path to private key)
+#   PLATFORM_DEPLOY_PORT      default 22
+#   PLATFORM_DEPLOY_BASE      default /srv/curriculum-project-hub
+#   PLATFORM_DEPLOY_RELEASE   default git HEAD (must be safe for paths)
+#   ALLOW_EMPTY_FLEET         optional: if 1, succeed when no silo matches
+#
+# This is a code-roll for existing silos. It does not create databases, domains,
+# or Feishu apps — use new_silo.sh / apply_new_silo.sh for that.
+set -euo pipefail
+
+FLEET="${CPH_FLEET:?CPH_FLEET required (dev|prod)}"
+case "$FLEET" in
+  dev) FLEET_DOMAIN_SUFFIX="educraft-dev.paradigm-edu.net" ;;
+  prod) FLEET_DOMAIN_SUFFIX="educraft.paradigm-edu.net" ;;
+  *)
+    echo "CPH_FLEET must be dev or prod, got: $FLEET" >&2
+    exit 1
+    ;;
+esac
+
+HOST="${PLATFORM_DEPLOY_HOST:-39.107.254.4}"
+DEPLOY_USER="${PLATFORM_DEPLOY_USER:-root}"
+PORT="${PLATFORM_DEPLOY_PORT:-22}"
+SSH_KEY="${PLATFORM_DEPLOY_SSH_KEY:?PLATFORM_DEPLOY_SSH_KEY required}"
+BASE="${PLATFORM_DEPLOY_BASE:-/srv/curriculum-project-hub}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+RELEASE_ID="${PLATFORM_DEPLOY_RELEASE:-$(git -C "$REPO_ROOT" rev-parse --verify HEAD)}"
+[[ "$RELEASE_ID" =~ ^[A-Za-z0-9._-]+$ ]] || {
+  echo "invalid PLATFORM_DEPLOY_RELEASE: $RELEASE_ID" >&2
+  exit 1
+}
+ALLOW_EMPTY_FLEET="${ALLOW_EMPTY_FLEET:-0}"
+
+HUB_DIR="$BASE/releases/$RELEASE_ID/hub"
+RELEASE_DIR="$BASE/releases/$RELEASE_ID"
+SSH_OPTS=(-i "$SSH_KEY" -p "$PORT" -o BatchMode=yes -o StrictHostKeyChecking=accept-new)
+
+echo "[fleet] fleet=$FLEET domain=*.$FLEET_DOMAIN_SUFFIX host=$DEPLOY_USER@$HOST release=$RELEASE_ID"
+
+# --- 1. Publish immutable release (shared; flock so parallel fleet jobs do not race) ---
+release_ready=false
+if ssh "${SSH_OPTS[@]}" "$DEPLOY_USER@$HOST" "test -f '$RELEASE_DIR/.complete'"; then
+  release_ready=true
+  echo "[fleet] release already complete: $RELEASE_DIR"
+fi
+
+if [ "$release_ready" = false ]; then
+  # Drop a prior incomplete tree for this release id (failed CI leave leftovers).
+  ssh "${SSH_OPTS[@]}" "$DEPLOY_USER@$HOST" bash -s <<REMOTE
+set -euo pipefail
+flock /var/lock/cph-hub-release-publish bash -c '
+  set -euo pipefail
+  if [ -f "$RELEASE_DIR/.complete" ]; then
+    exit 0
+  fi
+  if [ -e "$RELEASE_DIR" ]; then
+    echo "[fleet] removing incomplete release: $RELEASE_DIR"
+    rm -rf "$RELEASE_DIR"
+  fi
+  mkdir -p "$HUB_DIR"
+'
+REMOTE
+
+  echo "[fleet] rsync hub → $HUB_DIR"
+  rsync -az --delete \
+    --exclude node_modules --exclude dist --exclude .env \
+    --exclude admin-web/node_modules --exclude admin-web/build --exclude admin-web/.svelte-kit \
+    --exclude filelib-web/node_modules --exclude filelib-web/build --exclude filelib-web/.svelte-kit \
+    -e "ssh ${SSH_OPTS[*]}" \
+    "$REPO_ROOT/hub/" "$DEPLOY_USER@$HOST:$HUB_DIR/"
+
+  echo "[fleet] npm ci + build (tsc + admin-web & filelib-web SPAs)"
+  ssh "${SSH_OPTS[@]}" "$DEPLOY_USER@$HOST" bash -s <<REMOTE
+set -euo pipefail
+flock /var/lock/cph-hub-release-publish bash -c '
+  set -euo pipefail
+  if [ -f "$RELEASE_DIR/.complete" ]; then
+    echo "[fleet] release completed by another job"
+    exit 0
+  fi
+  cd "$HUB_DIR"
+  PUPPETEER_SKIP_DOWNLOAD=1 npm ci
+  npm ci --prefix admin-web
+  npm ci --prefix filelib-web
+  npm run audit:production
+  npm run build
+  test -f admin-web/build/index.html
+  test -f filelib-web/build/index.html
+  touch "$RELEASE_DIR/.complete"
+'
+REMOTE
+fi
+
+# --- 2. Discover silos in this fleet and roll them onto the release ---
+ssh "${SSH_OPTS[@]}" "$DEPLOY_USER@$HOST" \
+  env BASE="$BASE" HUB_DIR="$HUB_DIR" FLEET="$FLEET" \
+  FLEET_DOMAIN_SUFFIX="$FLEET_DOMAIN_SUFFIX" ALLOW_EMPTY_FLEET="$ALLOW_EMPTY_FLEET" \
+  bash -s <<'REMOTE'
+set -euo pipefail
+
+fleet_match() {
+  local public_url="$1"
+  local host="${public_url#https://}"
+  host="${host#http://}"
+  host="${host%%/*}"
+  host="${host%%:*}"
+  case "$FLEET" in
+    prod)
+      [[ "$host" == *."$FLEET_DOMAIN_SUFFIX" || "$host" == "$FLEET_DOMAIN_SUFFIX" ]] || return 1
+      # Avoid matching educraft-dev when suffix is educraft.…
+      [[ "$host" != *.educraft-dev.paradigm-edu.net && "$host" != educraft-dev.paradigm-edu.net ]] || return 1
+      return 0
+      ;;
+    dev)
+      [[ "$host" == *."$FLEET_DOMAIN_SUFFIX" || "$host" == "$FLEET_DOMAIN_SUFFIX" ]]
+      return
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+env_value() {
+  local file="$1"
+  local key="$2"
+  # Do not source secrets — only read the KEY=value line.
+  local line
+  line="$(grep -E "^${key}=" "$file" | tail -n1 || true)"
+  printf '%s' "${line#"${key}="}"
+}
+
+matched=0
+shopt -s nullglob
+for env_file in "$BASE"/.secrets/*/platform.env; do
+  instance_id="$(basename "$(dirname "$env_file")")"
+  public_url="$(env_value "$env_file" HUB_PUBLIC_BASE_URL)"
+  if [ -z "$public_url" ]; then
+    echo "[fleet] skip $instance_id: HUB_PUBLIC_BASE_URL empty"
+    continue
+  fi
+  if ! fleet_match "$public_url"; then
+    echo "[fleet] skip $instance_id: $public_url (not $FLEET)"
+    continue
+  fi
+
+  port="$(env_value "$env_file" PORT)"
+  workspace="$(env_value "$env_file" HUB_PROJECT_WORKSPACE_ROOT)"
+  unit="cph-hub-${instance_id}.service"
+  if [ ! -f "/etc/systemd/system/$unit" ]; then
+    echo "[fleet] skip $instance_id: unit missing ($unit)" >&2
+    continue
+  fi
+
+  # Prefer unit file ceilings (MemoryMax=16G) over systemctl's byte form.
+  memory_max="$(sed -n 's/^MemoryMax=//p' "/etc/systemd/system/$unit" | tail -n1)"
+  cpu_quota="$(sed -n 's/^CPUQuota=//p' "/etc/systemd/system/$unit" | tail -n1)"
+  tasks_max="$(sed -n 's/^TasksMax=//p' "/etc/systemd/system/$unit" | tail -n1)"
+
+  if [ -z "$port" ] || [ -z "$workspace" ] || [ -z "$memory_max" ] || [ -z "$cpu_quota" ] || [ -z "$tasks_max" ]; then
+    echo "[fleet] error: $instance_id missing PORT/workspace/ceilings (port=$port workspace=$workspace memory=$memory_max cpu=$cpu_quota tasks=$tasks_max)" >&2
+    exit 1
+  fi
+
+  echo "[fleet] roll $instance_id → $HUB_DIR ($public_url port=$port)"
+  BASE="$BASE" \
+    HUB_DIR="$HUB_DIR" \
+    INSTANCE_ID="$instance_id" \
+    WORKSPACE_ROOT="$workspace" \
+    PORT="$port" \
+    MEMORY_MAX="$memory_max" \
+    CPU_QUOTA="$cpu_quota" \
+    TASKS_MAX="$tasks_max" \
+    bash "$HUB_DIR/deploy/install_service.sh"
+
+  systemctl restart "$unit"
+  systemctl is-active --quiet "$unit"
+
+  health="http://127.0.0.1:${port}/api/healthz"
+  ok=false
+  for _ in $(seq 1 45); do
+    if curl --fail --silent "$health" >/dev/null 2>&1; then
+      ok=true
+      break
+    fi
+    sleep 1
+  done
+  if [ "$ok" != true ]; then
+    curl --fail --silent --show-error "$health" >/dev/null
+  fi
+  echo "[fleet] healthy $instance_id ($health)"
+  matched=$((matched + 1))
+done
+
+if [ "$matched" -eq 0 ]; then
+  msg="[fleet] no silos matched *.$FLEET_DOMAIN_SUFFIX under $BASE/.secrets"
+  if [ "$ALLOW_EMPTY_FLEET" = "1" ]; then
+    echo "$msg (ALLOW_EMPTY_FLEET=1)"
+    exit 0
+  fi
+  echo "$msg" >&2
+  exit 1
+fi
+
+echo "[fleet] rolled $matched silo(s) on $FLEET"
+REMOTE
+
+echo "[fleet] done fleet=$FLEET release=$RELEASE_ID hub=$HUB_DIR"

hub/deploy/deploy_platform.sh

@@ -60,9 +60,11 @@ if [ "$release_ready" = false ]; then
     -e "ssh ${SSH_OPTS[*]}" \
     "$REPO_ROOT/hub/" "$DEPLOY_USER@$HOST:$HUB_DIR/"
 
-  # 2. Install deps, audit and build, then atomically mark the release complete.
+  # 2. Install deps (hub + both SPAs), audit hub prod, build tsc + SPAs, mark complete.
+  # `npm run build` → tsc then admin:build + filelib:build → admin-web/build and
+  # filelib-web/build for registerStaticSpa / registerDatabaseSpa.
   ssh "${SSH_OPTS[@]}" "$DEPLOY_USER@$HOST" \
-    "cd '$HUB_DIR' && npm ci && npm run audit:production && npm run build && touch '$RELEASE_DIR/.complete'"
+    "cd '$HUB_DIR' && PUPPETEER_SKIP_DOWNLOAD=1 npm ci && npm ci --prefix admin-web && npm ci --prefix filelib-web && npm run audit:production && npm run build && touch '$RELEASE_DIR/.complete'"
 fi
 
 # 3. Ensure the service is installed (idempotent), then restart.

hub/filelib-web/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "filelib-web",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "vite preview",
+    "prepare": "svelte-kit sync || echo ''",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-static": "^3.0.10",
+    "@sveltejs/kit": "^2.63.0",
+    "@sveltejs/vite-plugin-svelte": "^7.1.2",
+    "@tailwindcss/vite": "^4.3.2",
+    "svelte": "^5.56.1",
+    "svelte-check": "^4.6.0",
+    "tailwindcss": "^4.3.2",
+    "typescript": "^5.7.0",
+    "vite": "^8.0.16"
+  }
+}

hub/filelib-web/src/app.css

@@ -0,0 +1,263 @@
+@import "tailwindcss";
+
+/* 全局 UI 主题令牌(与 hub 端 uiTheme.ts 同源) */
+@theme {
+  --color-bg: #fcfcfb;
+  --color-panel: #ffffff;
+  --color-sidebar: #f7f7f5;
+  --color-ink: #1a1a18;
+  --color-ink-2: #6b6a66;
+  --color-ink-3: #9c9b96;
+  --color-line: #ecece8;
+  --color-line-soft: #f1f1ee;
+  --color-hover: #f4f4f1;
+  --color-selected: #ebebe7;
+  --color-accent: #1a1a18;
+  --color-accent-hover: #333330;
+  --color-danger: #a13a33;
+  --color-guide: #e9e9e5;
+  --color-diff-add-bg: #f3f6f2;
+  --color-diff-add-text: #4a6741;
+  --color-diff-del-bg: #f8f2f1;
+  --color-diff-del-text: #a13a33;
+}
+
+html,
+body {
+  height: 100%;
+}
+
+body {
+  background: var(--color-bg);
+  color: var(--color-ink);
+  font-family:
+    "Inter",
+    -apple-system,
+    "Segoe UI",
+    "PingFang SC",
+    "Microsoft YaHei",
+    sans-serif;
+  font-size: 14px;
+  line-height: 1.65;
+  -webkit-font-smoothing: antialiased;
+}
+
+.font-mono {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+
+/* 共享组件层(ADR-0029)。
+ *
+ * 从已删除的 hub/src/database/routes/uiTheme.ts 原样搬来。组件只带布局工具类,
+ * 不重述这里的组件样式 —— 第一版迁移只搬了上面的 @theme 令牌,把按钮/输入框/
+ * 面板样式在每个组件里内联重写了一遍,后台随即明显退化。 */
+@layer components {
+  .btn {
+    display: inline-flex;
+    align-items: center;
+    gap: 5px;
+    padding: 6px 14px;
+    border-radius: 8px;
+    border: 1px solid var(--color-line);
+    background: var(--color-panel);
+    color: var(--color-ink);
+    font-size: 12.5px;
+    font-weight: 500;
+    cursor: pointer;
+    transition: all 120ms ease;
+    white-space: nowrap;
+  }
+  .btn:hover {
+    background: var(--color-hover);
+  }
+  .btn-sm {
+    padding: 4px 9px;
+    font-size: 11.5px;
+  }
+  .btn-primary {
+    background: var(--color-accent);
+    border-color: var(--color-accent);
+    color: #fff;
+  }
+  .btn-primary:hover {
+    background: var(--color-accent-hover);
+    border-color: var(--color-accent-hover);
+  }
+  .btn-danger {
+    border-color: transparent;
+    background: transparent;
+    color: var(--color-danger);
+  }
+  .btn-danger:hover {
+    background: color-mix(in srgb, var(--color-danger) 7%, transparent);
+  }
+
+  .panel {
+    background: var(--color-panel);
+    border: 1px solid var(--color-line-soft);
+    border-radius: 10px;
+    padding: 20px 22px;
+  }
+
+  .tag {
+    display: inline-flex;
+    align-items: center;
+    gap: 3px;
+    font-size: 10.5px;
+    font-weight: 500;
+    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    padding: 2px 8px;
+    border-radius: 999px;
+    border: 1px solid var(--color-line-soft);
+    color: var(--color-ink-3);
+    background: var(--color-panel);
+  }
+
+  .input,
+  .select,
+  .textarea {
+    width: 100%;
+    padding: 7px 11px;
+    border-radius: 8px;
+    border: 1px solid var(--color-line);
+    background: var(--color-panel);
+    font-size: 13px;
+    color: var(--color-ink);
+    font-family: inherit;
+    outline: none;
+    transition: border-color 120ms ease;
+  }
+  .input:focus,
+  .select:focus,
+  .textarea:focus {
+    border-color: var(--color-accent);
+  }
+  .textarea {
+    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    font-size: 12.5px;
+    line-height: 1.75;
+    resize: vertical;
+  }
+  .form-label {
+    display: block;
+    font-size: 11.5px;
+    color: var(--color-ink-3);
+    margin-bottom: 4px;
+  }
+  .form-row {
+    margin-bottom: 12px;
+  }
+
+  table.list {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 13px;
+  }
+  table.list th {
+    text-align: left;
+    font-size: 11.5px;
+    font-weight: 500;
+    color: var(--color-ink-3);
+    padding: 4px 0;
+  }
+  table.list td {
+    padding: 8px 0;
+    border-top: 1px solid var(--color-line-soft);
+  }
+  table.list tr:first-child td {
+    border-top: none;
+  }
+
+  .quiet {
+    color: var(--color-ink-3);
+    font-size: 12.5px;
+  }
+  .section-title {
+    font-size: 13px;
+    font-weight: 600;
+  }
+  .section-note {
+    font-size: 11.5px;
+    color: var(--color-ink-3);
+  }
+  .file-meta {
+    font-size: 11px;
+    color: var(--color-ink-3);
+    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  }
+  .link-danger {
+    color: var(--color-danger);
+    font-size: 12.5px;
+    background: none;
+    border: none;
+    cursor: pointer;
+    padding: 0;
+  }
+  .link-danger:hover {
+    text-decoration: underline;
+  }
+
+  /* 开关。真 checkbox 藏在下面 —— 保留键盘可达与 :checked 语义,不做 div 假开关。 */
+  .switch {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    cursor: pointer;
+    user-select: none;
+  }
+  .switch > input {
+    position: absolute;
+    opacity: 0;
+    width: 0;
+    height: 0;
+  }
+  .switch > span {
+    position: relative;
+    flex-shrink: 0;
+    width: 30px;
+    height: 17px;
+    border-radius: 999px;
+    background: var(--color-line);
+    transition: background 0.16s;
+  }
+  .switch > span::after {
+    content: "";
+    position: absolute;
+    top: 2px;
+    left: 2px;
+    width: 13px;
+    height: 13px;
+    border-radius: 50%;
+    background: #fff;
+    transition: transform 0.16s;
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
+  }
+  .switch > input:checked + span {
+    background: var(--color-accent);
+  }
+  .switch > input:checked + span::after {
+    transform: translateX(13px);
+  }
+  .switch > input:focus-visible + span {
+    outline: 2px solid var(--color-accent);
+    outline-offset: 2px;
+  }
+}
+
+/* diff 渲染 */
+pre.diff {
+  white-space: pre-wrap;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 12.5px;
+  line-height: 1.75;
+}
+pre.diff .add {
+  display: block;
+  color: var(--color-diff-add-text);
+  background: var(--color-diff-add-bg);
+}
+pre.diff .del {
+  display: block;
+  color: var(--color-diff-del-text);
+  background: var(--color-diff-del-bg);
+}

hub/filelib-web/src/app.d.ts

@@ -0,0 +1,12 @@
+// See https://svelte.dev/docs/kit/types#app
+declare global {
+	namespace App {
+		// interface Error {}
+		// interface Locals {}
+		// interface PageData {}
+		// interface PageState {}
+		// interface Platform {}
+	}
+}
+
+export {};

hub/filelib-web/src/app.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="zh-CN">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<link rel="preconnect" href="https://fonts.googleapis.com" />
+		<link
+			href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap"
+			rel="stylesheet"
+		/>
+		%sveltekit.head%
+	</head>
+	<body data-sveltekit-preload-data="hover" style="height: 100%">
+		<div style="display: contents; height: 100%">%sveltekit.body%</div>
+	</body>
+</html>

hub/filelib-web/src/lib/Avatar.svelte

@@ -0,0 +1,31 @@
+<script lang="ts">
+  /** 头像:有 avatarUrl 用图,否则显示首字母色块。 */
+  let {
+    displayName,
+    userId,
+    avatarUrl = null,
+    size = 28,
+  }: {
+    displayName?: string | null;
+    userId?: string | null;
+    avatarUrl?: string | null;
+    size?: number;
+  } = $props();
+
+  const initial = $derived((displayName || userId || "?").slice(0, 1).toUpperCase());
+</script>
+
+{#if avatarUrl}
+  <img
+    src={avatarUrl}
+    alt=""
+    class="shrink-0 rounded-full object-cover"
+    style="width:{size}px;height:{size}px"
+  />
+{:else}
+  <span
+    class="inline-flex shrink-0 items-center justify-center rounded-full bg-accent font-semibold text-white"
+    style="width:{size}px;height:{size}px;font-size:{Math.round(size * 0.42)}px"
+    aria-hidden="true">{initial}</span
+  >
+{/if}

hub/filelib-web/src/lib/FileEditor.svelte

@@ -0,0 +1,166 @@
+<script lang="ts">
+  import { api, ApiError } from "./api.js";
+  import { toastOk, toastErr, toast } from "./stores.js";
+  import type { FileContent, VersionInfo, Role } from "./types.js";
+  import Modal from "./Modal.svelte";
+  import Icon from "./Icon.svelte";
+
+  let { projectId, path, role, onchanged, onclose }: { projectId: string; path: string; role: Role; onchanged: () => void; onclose?: () => void } = $props();
+
+  let file = $state<FileContent | null>(null);
+  let draft = $state("");
+  let loadError = $state<string | null>(null);
+  let conflict = $state<{ currentVersion: string; diff: string } | null>(null);
+  let showHistory = $state(false);
+  let history = $state<VersionInfo[]>([]);
+
+  const canEdit = $derived(role !== "VIEW");
+
+  async function load(): Promise<void> {
+    try {
+      file = await api<FileContent>(`/database/api/projects/${projectId}/file?path=${encodeURIComponent(path)}`);
+      draft = file.encoding === "utf8" ? file.content : "";
+      loadError = null;
+      conflict = null;
+    } catch (e) {
+      loadError = e instanceof Error ? e.message : String(e);
+    }
+  }
+
+  $effect(() => {
+    void projectId;
+    void path;
+    void load();
+  });
+
+  async function save(): Promise<void> {
+    if (file === null) return;
+    try {
+      const r = await api<{ version: string }>(`/database/api/projects/${projectId}/file/commits`, {
+        method: "POST",
+        body: { path: file.path, baseVersion: file.version, content: draft },
+      });
+      toastOk("已提交 " + r.version);
+      await load();
+      onchanged();
+    } catch (e) {
+      if (e instanceof ApiError && e.status === 409 && typeof e.details?.["currentVersion"] === "string") {
+        await showConflict(e.details["currentVersion"]);
+      } else {
+        toastErr(e instanceof Error ? e.message : String(e));
+      }
+    }
+  }
+
+  async function showConflict(currentVersion: string): Promise<void> {
+    if (file === null) return;
+    try {
+      const r = await api<{ diff: string }>(
+        `/database/api/projects/${projectId}/file/diff?path=${encodeURIComponent(file.path)}&from=${encodeURIComponent(file.version)}&to=${encodeURIComponent(currentVersion)}`,
+      );
+      conflict = { currentVersion, diff: r.diff };
+      file = { ...file, version: currentVersion };
+    } catch (e) {
+      toastErr(e instanceof Error ? e.message : String(e));
+    }
+  }
+
+  async function acceptLatest(): Promise<void> {
+    conflict = null;
+    await load();
+    toast("已载入最新内容,请在此基础上合并", "info");
+  }
+
+  async function remove(): Promise<void> {
+    if (file === null || !confirm("删除文件 " + file.path + "?")) return;
+    try {
+      await api(`/database/api/projects/${projectId}/file?path=${encodeURIComponent(file.path)}`, {
+        method: "DELETE",
+        body: { baseVersion: file.version },
+      });
+      toastOk("已删除");
+      file = null;
+      onchanged();
+    } catch (e) {
+      toastErr(e instanceof Error ? e.message : String(e));
+    }
+  }
+
+  async function openHistory(): Promise<void> {
+    try {
+      const r = await api<{ history: VersionInfo[] }>(`/database/api/projects/${projectId}/file/history?path=${encodeURIComponent(path)}`);
+      history = r.history;
+      showHistory = true;
+    } catch (e) {
+      toastErr(e instanceof Error ? e.message : String(e));
+    }
+  }
+
+  function renderDiff(diff: string): string {
+    return diff
+      .replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+      .replace(/^\+(.*)$/gm, '<span class="add">+$1</span>')
+      .replace(/^-(.*)$/gm, '<span class="del">-$1</span>');
+  }
+</script>
+
+{#if loadError}
+  <div class="panel text-xs text-danger">{loadError}</div>
+{:else if file}
+  <div class="panel">
+    <div class="mb-2.5 flex items-center justify-between">
+      <span class="file-meta">{file.path} @ {file.version}</span>
+      <div class="flex items-center gap-1.5">
+        <a class="btn" href="/database/api/projects/{projectId}/file/raw?path={encodeURIComponent(file.path)}" download>下载</a>
+        <button class="btn" onclick={openHistory}><Icon name="clock" size={13} /> 历史</button>
+        {#if canEdit}
+          <button class="btn btn-danger" onclick={remove}><Icon name="trash" size={13} /> 删除文件</button>
+        {/if}
+        {#if onclose}
+          <button class="btn !px-2.5" onclick={onclose} title="关闭预览" aria-label="关闭预览">✕</button>
+        {/if}
+      </div>
+    </div>
+
+    {#if file.encoding === "base64"}
+      <div class="quiet">二进制文件({file.size} B),不支持在线编辑</div>
+    {:else}
+      <textarea rows="14" class="textarea !leading-7" bind:value={draft} readonly={!canEdit}></textarea>
+    {/if}
+
+    {#if canEdit && file.encoding !== "base64"}
+      <div class="mt-3 flex justify-end">
+        <button class="btn btn-primary" onclick={save}>提交修改</button>
+      </div>
+    {/if}
+
+    {#if conflict}
+      <div class="mt-3.5 rounded-xl border border-[#E8E2C8] bg-[#FCFBF4] p-4">
+        <div class="mb-2 text-[13px] font-semibold text-[#6E6329]">冲突:他人已提交 {conflict.currentVersion},差异如下(你的基版 → 最新版)</div>
+        <pre class="diff rounded-lg border border-line-soft bg-panel p-3">{@html renderDiff(conflict.diff)}</pre>
+        <div class="mt-2 text-[11.5px] text-[#8A8059]">请人工合并后,以最新内容为全文重新提交(基版将更新为 {conflict.currentVersion})</div>
+        <div class="mt-2 flex justify-end">
+          <button class="btn" onclick={acceptLatest}>载入最新内容</button>
+        </div>
+      </div>
+    {/if}
+  </div>
+{:else}
+  <div class="panel quiet">加载中…</div>
+{/if}
+
+{#if showHistory}
+  <Modal title="版本历史" onclose={() => (showHistory = false)}>
+    <div class="max-h-80 overflow-y-auto">
+      {#each history as v (v.version)}
+        <div class="border-t border-line-soft py-2 text-xs first:border-t-0">
+          <span class="font-mono text-accent">{v.version}</span> {v.message}
+          <div class="text-ink-3">{new Date(v.committedAt).toLocaleString("zh-CN")}{v.author ? " · " + v.author : ""}</div>
+        </div>
+      {/each}
+    </div>
+    <div class="mt-3 flex justify-end">
+      <button class="btn" onclick={() => (showHistory = false)}>关闭</button>
+    </div>
+  </Modal>
+{/if}

hub/filelib-web/src/lib/FilesPanel.svelte

@@ -0,0 +1,139 @@
+<script lang="ts">
+  import { api } from "./api.js";
+  import { toastOk, toastErr } from "./stores.js";
+  import { selectedFilePath, filesVersion } from "./browser.js";
+  import type { FileEntry, NodeDetail } from "./types.js";
+  import Modal from "./Modal.svelte";
+  import Icon from "./Icon.svelte";
+
+  let { node }: { node: NodeDetail } = $props();
+
+  let files = $state<FileEntry[] | null>(null);
+  let loadError = $state<string | null>(null);
+  let showNewFile = $state(false);
+  let newPath = $state("");
+  let newContent = $state("");
+  // bind:this 的目标要用 $state,否则 svelte 5 warn 不会正确更新。
+  let uploadInput = $state<HTMLInputElement | null>(null);
+
+  const canEdit = $derived(node.role !== "VIEW");
+
+  async function loadFiles(): Promise<void> {
+    try {
+      const r = await api<{ files: FileEntry[] }>(`/database/api/projects/${node.id}/files`);
+      files = r.files;
+      loadError = null;
+    } catch (e) {
+      loadError = e instanceof Error ? e.message : String(e);
+    }
+  }
+
+  $effect(() => {
+    void node.id;
+    void $filesVersion;
+    void loadFiles();
+  });
+
+  async function submitNewFile(): Promise<void> {
+    const path = newPath.trim();
+    if (path === "") return;
+    try {
+      await api(`/database/api/projects/${node.id}/file`, {
+        method: "PUT",
+        body: { path, content: newContent },
+      });
+      toastOk("已创建");
+      showNewFile = false;
+      newPath = ""; newContent = "";
+      await loadFiles();
+    } catch (e) {
+      toastErr(e instanceof Error ? e.message : String(e));
+    }
+  }
+
+  function u8ToBase64(bytes: Uint8Array): string {
+    let bin = "";
+    const CHUNK = 0x8000;
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+      bin += String.fromCharCode.apply(null, Array.from(bytes.subarray(i, i + CHUNK)) as unknown as number[]);
+    }
+    return btoa(bin);
+  }
+
+  async function doUpload(e: Event): Promise<void> {
+    const input = e.target as HTMLInputElement;
+    const file = input.files?.[0];
+    input.value = "";
+    if (!file) return;
+    if (file.size > 10 * 1024 * 1024) {
+      toastErr("文件超过 10MB 上限");
+      return;
+    }
+    const targetPath = prompt("保存到路径(可含目录):", "材料/" + file.name);
+    if (!targetPath) return;
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    const isBinary = bytes.includes(0);
+    const body = isBinary
+      ? { path: targetPath, content: u8ToBase64(bytes), encoding: "base64" }
+      : { path: targetPath, content: new TextDecoder("utf-8").decode(bytes), encoding: "utf8" };
+    try {
+      await api(`/database/api/projects/${node.id}/file`, { method: "PUT", body });
+      toastOk("已上传 " + file.name);
+      await loadFiles();
+    } catch (err) {
+      toastErr(err instanceof Error ? err.message : String(err));
+    }
+  }
+</script>
+
+<div class="panel">
+  <div class="mb-1.5 flex items-center justify-between">
+    <div class="section-title">项目文件({files?.length ?? 0})</div>
+    {#if canEdit}
+      <div class="flex gap-1.5">
+        <button class="btn" onclick={() => (showNewFile = true)}><Icon name="plus" size={13} /> 新建文件</button>
+        <button class="btn btn-primary" onclick={() => uploadInput?.click()}>上传文件</button>
+        <input bind:this={uploadInput} type="file" class="hidden" onchange={doUpload} />
+      </div>
+    {/if}
+  </div>
+
+  {#if files === null && loadError === null}
+    <div class="quiet py-5 text-center">加载中…</div>
+  {:else if loadError}
+    <div class="py-5 text-center text-xs text-danger">{loadError}</div>
+  {:else if files && files.length === 0}
+    <div class="quiet py-5 text-center">空仓库 · 可新建或上传文件</div>
+  {:else if files}
+    <table class="list">
+      <tbody>
+        {#each files as f (f.path)}
+          <tr
+            class="cursor-pointer {$selectedFilePath === f.path ? 'bg-selected' : 'hover:bg-hover'}"
+            onclick={() => selectedFilePath.set(f.path)}
+          >
+            <td class="font-mono text-[12.5px] text-ink">{f.path}</td>
+            <td class="file-meta text-right">{f.size} B</td>
+          </tr>
+        {/each}
+      </tbody>
+    </table>
+  {/if}
+</div>
+
+{#if showNewFile}
+  <Modal title="新建文件" onclose={() => (showNewFile = false)}>
+    <div class="form-row">
+      <label class="form-label" for="nf-path">路径</label>
+      <input id="nf-path" class="input font-mono" bind:value={newPath} placeholder="docs/intro.md" />
+    </div>
+    <div class="form-row">
+      <label class="form-label" for="nf-content">内容</label>
+      <textarea id="nf-content" rows="8" class="textarea" bind:value={newContent} placeholder="内容…"></textarea>
+    </div>
+    <div class="mt-4 flex justify-end gap-2">
+      <button class="btn" onclick={() => (showNewFile = false)}>取消</button>
+      <button class="btn btn-primary" onclick={submitNewFile}>创建</button>
+    </div>
+  </Modal>
+{/if}

hub/filelib-web/src/lib/GrantsPanel.svelte

@@ -0,0 +1,381 @@
+<script lang="ts">
+  /**
+   * 节点授权面板(表格化改版)。迁自已删除的 routes/libraryBrowser.ts
+   * `renderGrantsTab`(ADR-0029)。
+   *
+   * 布局:顶部工具条(左:授权成员搜索框;右:「+ 添加授权」弹窗入口);
+   * 下方一行一条授权 —— 成员(名称+id,点击跳用户管理/Group 管理)、
+   * 类型(个人/Group)、权限(下拉可改)、加入时间、操作(删除)。
+   *
+   * 语义(契约 8.1 / ADR-0021 / ADR-0028):
+   *  - 创建者授权(isCreatorGrant)不可收回、不可改;
+   *  - MANAGE 仅创建者可授,前端不做矩阵拦截 —— 后端 fail closed,报错原样 toast;
+   *  - GROUP 主体走 in-hub MemberGroup,/groups/search 搜索选(MANAGE 即可);
+   *    USER 主体用 /users/search(仅网站管理员),老师端无此权限时回落手输 id。
+   */
+  import { api } from "./api.js";
+  import { toastOk, toastErr } from "./stores.js";
+  import { ROLE_LABEL } from "./labels.js";
+  import type { Grant, MemberGroupSearchResult, NodeDetail, Role, UserSearchResult } from "./types.js";
+  import Icon from "./Icon.svelte";
+  import Modal from "./Modal.svelte";
+  import Avatar from "./Avatar.svelte";
+
+  let { node }: { node: NodeDetail } = $props();
+
+  const ROLES: readonly Role[] = ["VIEW", "EDIT", "MANAGE"];
+
+  interface PrincipalOption {
+    readonly id: string;
+    readonly label: string;
+    readonly sub: string;
+  }
+
+  let grants = $state<Grant[] | null>(null);
+  let error = $state<string | null>(null);
+  let searchText = $state("");
+
+  // 添加授权弹窗
+  let showAdd = $state(false);
+  let principalType = $state<"USER" | "GROUP">("USER");
+  let principalQuery = $state("");
+  let principalOptions = $state<readonly PrincipalOption[] | null>(null);
+  let selectedPrincipal = $state<{ readonly id: string; readonly label: string } | null>(null);
+  let manualId = $state("");
+  let searchUnavailable = $state(false);
+  let role = $state<Role>("VIEW");
+  let saving = $state(false);
+  let searchSeq = 0;
+  let searchTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const canManage = $derived(node.role === "MANAGE");
+  const errText = (e: unknown): string => (e instanceof Error ? e.message : String(e));
+
+  /** 工具条搜索:按名称 / id / 类型过滤当前授权行(纯前端过滤,数据已全量在手)。 */
+  const shown = $derived.by((): Grant[] | null => {
+    if (grants === null) return null;
+    const q = searchText.trim().toLowerCase();
+    if (q === "") return grants;
+    return grants.filter(
+      (g) =>
+        g.principalId.toLowerCase().includes(q) ||
+        (g.principalName ?? "").toLowerCase().includes(q) ||
+        (g.principalOpenId ?? "").toLowerCase().includes(q) ||
+        (g.principalType === "USER" ? "个人" : "group").includes(q),
+    );
+  });
+
+  $effect(() => {
+    void node.id;
+    void load();
+  });
+
+  async function load(): Promise<void> {
+    grants = null;
+    error = null;
+    try {
+      const r = await api<{ grants: Grant[] }>(`/database/api/nodes/${node.id}/grants`);
+      grants = r.grants;
+    } catch (e) {
+      error = errText(e);
+    }
+  }
+
+  /** 成员单元格跳转:USER → 用户管理(带过滤词);GROUP → Group 管理(选中该组)。 */
+  function principalHref(g: Grant): string {
+    return g.principalType === "USER"
+      ? `/database/dashboard/users?q=${encodeURIComponent(g.principalId)}`
+      : `/database/dashboard/groups?select=${encodeURIComponent(g.principalId)}`;
+  }
+
+  function fmtDate(iso: string): string {
+    try {
+      return new Date(iso).toLocaleString("zh-CN", { dateStyle: "medium", timeStyle: "short" });
+    } catch {
+      return iso;
+    }
+  }
+
+  /* ------------------------------------------------------------ 添加授权弹窗 */
+
+  function openAdd(): void {
+    showAdd = true;
+    principalType = "USER";
+    principalQuery = "";
+    principalOptions = null;
+    selectedPrincipal = null;
+    manualId = "";
+    searchUnavailable = false;
+    role = "VIEW";
+    void searchPrincipals("");
+  }
+
+  function onTypeChange(): void {
+    principalQuery = "";
+    principalOptions = null;
+    selectedPrincipal = null;
+    manualId = "";
+    searchUnavailable = false;
+    void searchPrincipals("");
+  }
+
+  function onQueryInput(): void {
+    selectedPrincipal = null;
+    if (searchTimer !== undefined) clearTimeout(searchTimer);
+    const q = principalQuery.trim();
+    searchTimer = setTimeout(() => void searchPrincipals(q), 250);
+  }
+
+  async function searchPrincipals(q: string): Promise<void> {
+    // seq 防乱序:慢响应不覆盖新查询的结果。
+    const seq = ++searchSeq;
+    try {
+      if (principalType === "USER") {
+        const r = await api<{ users: UserSearchResult[] }>(
+          `/database/api/users/search?q=${encodeURIComponent(q)}`,
+        );
+        if (seq !== searchSeq) return;
+        principalOptions = r.users.map((u) => ({
+          id: u.userId,
+          label: u.displayName === "" ? u.userId : u.displayName,
+          sub: u.feishuOpenId,
+        }));
+      } else {
+        const r = await api<{ groups: MemberGroupSearchResult[] }>(
+          `/database/api/groups/search?q=${encodeURIComponent(q)}`,
+        );
+        if (seq !== searchSeq) return;
+        principalOptions = r.groups.map((g) => ({ id: g.id, label: g.name, sub: g.breadcrumb }));
+      }
+      searchUnavailable = false;
+    } catch {
+      if (seq !== searchSeq) return;
+      // 老师端 MANAGE 持有者没有 users/search 权限(403)——回落为手输 id。
+      principalOptions = null;
+      searchUnavailable = true;
+    }
+  }
+
+  function pick(option: PrincipalOption): void {
+    selectedPrincipal = { id: option.id, label: option.label };
+    principalQuery = option.label;
+    principalOptions = null;
+  }
+
+  async function addGrant(): Promise<void> {
+    const principalId = selectedPrincipal?.id ?? manualId.trim();
+    if (principalId === "") {
+      toastErr("请选择或填写授权主体");
+      return;
+    }
+    saving = true;
+    try {
+      // PUT /grants 是 upsert 语义(putGrants):同主体已有授权则改级别,否则新建。
+      await api(`/database/api/nodes/${node.id}/grants`, {
+        method: "PUT",
+        body: { grants: [{ principalType, principalId, role }] },
+      });
+      toastOk("已授予");
+      showAdd = false;
+      await load();
+    } catch (e) {
+      toastErr(errText(e));
+    } finally {
+      saving = false;
+    }
+  }
+
+  /** 权限下拉改级别:复用 PUT upsert;被 8.1 矩阵拒绝时 toast 并 reload 回显真实态。 */
+  async function changeRole(g: Grant, next: Role): Promise<void> {
+    if (next === g.role) return;
+    try {
+      await api(`/database/api/nodes/${node.id}/grants`, {
+        method: "PUT",
+        body: { grants: [{ principalType: g.principalType, principalId: g.principalId, role: next }] },
+      });
+      toastOk("权限已更新");
+      await load();
+    } catch (e) {
+      toastErr(errText(e));
+      await load();
+    }
+  }
+
+  async function revoke(g: Grant): Promise<void> {
+    if (!confirm(`删除「${g.principalName ?? g.principalId}」的${ROLE_LABEL[g.role]}授权?`)) return;
+    try {
+      await api(`/database/api/nodes/${node.id}/grants/${encodeURIComponent(g.id)}`, {
+        method: "DELETE",
+      });
+      toastOk("已删除");
+      await load();
+    } catch (e) {
+      toastErr(errText(e));
+    }
+  }
+</script>
+
+<div class="panel">
+  <!-- 工具条:左侧授权成员搜索框,右侧添加授权入口 -->
+  <div class="mb-3 flex items-center gap-2">
+    <div class="relative min-w-0 flex-1">
+      <span class="pointer-events-none absolute left-2.5 top-1/2 -translate-y-1/2 text-ink-3">
+        <Icon name="search" size={14} />
+      </span>
+      <input
+        class="input w-full !pl-8"
+        placeholder="搜索授权成员(名称 / id / 类型)"
+        bind:value={searchText}
+      />
+    </div>
+    {#if canManage}
+      <button class="btn btn-primary shrink-0" onclick={openAdd}>
+        <Icon name="plus" size={13} /> 添加授权
+      </button>
+    {/if}
+  </div>
+
+  {#if error !== null}
+    <div class="py-2 text-[12.5px] text-danger">{error}</div>
+  {:else if shown === null}
+    <div class="quiet py-[18px] text-center">加载中…</div>
+  {:else}
+    <!-- 内容不可断行(头像名/id/日期/下拉)可能超宽:溢出时横向滚动,
+         而不是把表格挤变形或顶出 panel 右边界(文件预览打开时主区变窄)。 -->
+    <div class="overflow-x-auto">
+      <table class="list">
+      <thead>
+        <tr>
+          <th class="whitespace-nowrap pr-4">成员</th>
+          <th class="whitespace-nowrap pr-4">userId</th>
+          <th class="whitespace-nowrap pr-4">飞书 ID</th>
+          <th class="whitespace-nowrap pr-4">类型</th>
+          <th class="whitespace-nowrap pr-4">权限</th>
+          <th class="whitespace-nowrap pr-4">加入时间</th>
+          <th></th>
+        </tr>
+      </thead>
+      <tbody>
+        {#if shown.length === 0}
+          <tr>
+            <td colspan="7" class="quiet !py-[18px] text-center">
+              {searchText.trim() === "" ? "暂无授权" : `无匹配「${searchText.trim()}」的授权`}
+            </td>
+          </tr>
+        {:else}
+          {#each shown as g (g.id)}
+            <tr>
+              <td class="whitespace-nowrap pr-4">
+                <a class="inline-flex items-center gap-2 text-ink hover:text-accent" href={principalHref(g)}>
+                  <Avatar displayName={g.principalName} userId={g.principalId} size={26} />
+                  <span class="flex items-center gap-1.5 text-[13px]">
+                    {g.principalName ?? g.principalId}
+                    {#if g.isCreatorGrant}<span class="quiet">(创建者)</span>{/if}
+                  </span>
+                </a>
+              </td>
+              <td class="file-meta max-w-[230px] truncate pr-4 font-mono" title={g.principalType === "USER" ? g.principalId : ""}>
+                {g.principalType === "USER" ? g.principalId : "—"}
+              </td>
+              <td class="file-meta max-w-[230px] truncate pr-4 font-mono" title={g.principalOpenId ?? ""}>
+                {g.principalOpenId ?? "—"}
+              </td>
+              <td class="whitespace-nowrap pr-4"><span class="tag">{g.principalType === "USER" ? "个人" : "Group"}</span></td>
+              <td class="whitespace-nowrap pr-4">
+                <!-- 创建者授权不可动(契约 8.1);非 MANAGE 持有者只读。 -->
+                {#if !g.isCreatorGrant && canManage}
+                  <select
+                    class="select !w-[110px]"
+                    value={g.role}
+                    onchange={(e) => void changeRole(g, e.currentTarget.value as Role)}
+                  >
+                    {#each ROLES as r (r)}
+                      <option value={r}>{ROLE_LABEL[r]}</option>
+                    {/each}
+                  </select>
+                {:else}
+                  <span class="file-meta">{ROLE_LABEL[g.role]}</span>
+                {/if}
+              </td>
+              <td class="file-meta whitespace-nowrap pr-4">{fmtDate(g.createdAt)}</td>
+              <td class="whitespace-nowrap pr-2 text-right">
+                {#if !g.isCreatorGrant && canManage}
+                  <button class="link-danger inline-flex items-center gap-1" onclick={() => void revoke(g)}>
+                    <Icon name="trash" size={12} /> 删除
+                  </button>
+                {/if}
+              </td>
+            </tr>
+          {/each}
+        {/if}
+      </tbody>
+      </table>
+    </div>
+  {/if}
+</div>
+
+{#if showAdd}
+  <Modal title="添加授权" onclose={() => (showAdd = false)}>
+    <div class="form-row">
+      <label class="form-label" for="grant-type">类型</label>
+      <select id="grant-type" class="select" bind:value={principalType} onchange={onTypeChange}>
+        <option value="USER">个人</option>
+        <option value="GROUP">Group</option>
+      </select>
+    </div>
+    <div class="form-row">
+      <label class="form-label" for="grant-principal">{principalType === "USER" ? "用户" : "Group"}</label>
+      <input
+        id="grant-principal"
+        class="input"
+        placeholder={principalType === "USER" ? "搜索显示名 / openId" : "搜索组名"}
+        bind:value={principalQuery}
+        oninput={onQueryInput}
+      />
+    </div>
+    {#if selectedPrincipal !== null}
+      <div class="form-row">
+        <span class="form-label">已选</span>
+        <span class="quiet self-center text-[12.5px]">
+          {selectedPrincipal.label}<span class="font-mono">({selectedPrincipal.id})</span>
+        </span>
+      </div>
+    {/if}
+    {#if principalOptions !== null && principalOptions.length > 0}
+      <div class="mb-3 max-h-[180px] overflow-y-auto rounded-lg border border-line-soft">
+        {#each principalOptions as o (o.id)}
+          <button class="block w-full px-3 py-2 text-left hover:bg-hover" onclick={() => pick(o)}>
+            <span class="block text-[13px] text-ink">{o.label}</span>
+            <span class="block font-mono text-[11px] text-ink-3">{o.sub}</span>
+          </button>
+        {/each}
+      </div>
+    {:else if searchUnavailable}
+      <div class="form-row">
+        <label class="form-label" for="grant-manual-id">主体 id</label>
+        <input
+          id="grant-manual-id"
+          class="input font-mono"
+          placeholder="无搜索权限,请直接填写 id"
+          bind:value={manualId}
+        />
+      </div>
+    {:else if principalOptions !== null}
+      <div class="quiet mb-3 py-2 text-center text-[12px]">无匹配结果</div>
+    {/if}
+    <div class="form-row">
+      <label class="form-label" for="grant-role">权限</label>
+      <select id="grant-role" class="select" bind:value={role}>
+        {#each ROLES as r (r)}
+          <option value={r}>{ROLE_LABEL[r]}</option>
+        {/each}
+      </select>
+    </div>
+    <div class="mt-4 flex justify-end gap-2">
+      <button class="btn" onclick={() => (showAdd = false)}>取消</button>
+      <button class="btn btn-primary disabled:opacity-50" onclick={addGrant} disabled={saving}>
+        {saving ? "授予中…" : "添加"}
+      </button>
+    </div>
+  </Modal>
+{/if}

hub/filelib-web/src/lib/GroupAdmin.svelte

@@ -0,0 +1,769 @@
+<script lang="ts">
+  /**
+   * Group 管理面板。从已删除的 routes/adminPanels.ts `renderGroupsPanel`(747 行)
+   * 迁来(ADR-0029),功能与视觉逐条对齐:折叠树 / 组名过滤(命中项保留祖先链)/
+   * 归档组展示与恢复 / 右键菜单 / 面包屑 / 统计条 / 成员表(头像·openId·加入时间)。
+   */
+  import { onMount } from "svelte";
+  import { page } from "$app/state";
+  import { api } from "./api.js";
+  import { toastErr, toastOk } from "./stores.js";
+  import type { MemberGroupNode, MemberGroupMember, UserSearchResult } from "./types.js";
+  import Modal from "./Modal.svelte";
+  import Icon from "./Icon.svelte";
+  import Avatar from "./Avatar.svelte";
+
+  // 后端返回扁平列表(ADR-0028);前端按 parentId/depth 拼成有序树。
+  let groups = $state<MemberGroupNode[]>([]);
+  let loaded = $state(false);
+  let listError = $state<string | null>(null);
+  let selectedId = $state<string | null>(null);
+
+  // 折叠的组 id(默认全展开)。用数组而非 Set:$state 的深层代理只跟踪普通对象/
+  // 数组,Set 的变更不会触发重渲染。
+  let collapsedIds = $state<string[]>([]);
+  const isCollapsed = (id: string): boolean => collapsedIds.includes(id);
+  const toggleCollapsed = (id: string): void => {
+    collapsedIds = isCollapsed(id) ? collapsedIds.filter((x) => x !== id) : [...collapsedIds, id];
+  };
+
+  let filterText = $state("");
+  let showArchived = $state(false);
+
+  let members = $state<MemberGroupMember[]>([]);
+  let membersLoaded = $state(false);
+  let membersError = $state<string | null>(null);
+  let memberFilter = $state("");
+
+  const selected = $derived(groups.find((g) => g.id === selectedId) ?? null);
+  const isArchived = $derived(selected?.archivedAt != null);
+
+  interface Row {
+    readonly g: MemberGroupNode;
+    readonly hasKids: boolean;
+    /** 过滤态下:自身是否命中(祖先链上的非命中项半透明显示)。 */
+    readonly hit: boolean;
+  }
+
+  /** 扁平列表 → 先根遍历顺序;折叠的子树整段跳过。过滤时命中项的祖先链保留。 */
+  const rows = $derived.by((): Row[] => {
+    const byParent = new Map<string | null, MemberGroupNode[]>();
+    const byId = new Map<string, MemberGroupNode>();
+    for (const g of groups) {
+      byId.set(g.id, g);
+      const arr = byParent.get(g.parentId) ?? [];
+      arr.push(g);
+      byParent.set(g.parentId, arr);
+    }
+    for (const arr of byParent.values()) arr.sort((a, b) => a.name.localeCompare(b.name, "zh-CN"));
+
+    // 过滤:命中集 = 名字命中的组 ∪ 其全部祖先(否则命中的深层组无路径可展示)。
+    const q = filterText.trim().toLowerCase();
+    let keep: Set<string> | null = null;
+    if (q !== "") {
+      keep = new Set<string>();
+      for (const g of groups) {
+        if (!g.name.toLowerCase().includes(q)) continue;
+        let cur: MemberGroupNode | undefined = g;
+        while (cur !== undefined) {
+          keep.add(cur.id);
+          cur = cur.parentId === null ? undefined : byId.get(cur.parentId);
+        }
+      }
+    }
+
+    const out: Row[] = [];
+    const walk = (parentId: string | null): void => {
+      for (const g of byParent.get(parentId) ?? []) {
+        if (keep !== null && !keep.has(g.id)) continue;
+        const kids = (byParent.get(g.id) ?? []).filter((k) => keep === null || keep.has(k.id));
+        out.push({ g, hasKids: kids.length > 0, hit: q === "" || g.name.toLowerCase().includes(q) });
+        // 过滤态下强制展开(否则命中项被折叠的祖先藏住)。
+        if (keep !== null || !isCollapsed(g.id)) walk(g.id);
+      }
+    };
+    walk(null);
+    // 兜底:父不在列表的孤儿(级联软删理论上不产生)也列出,避免"看不见"。
+    const seen = new Set(out.map((r) => r.g.id));
+    for (const g of groups) {
+      if (seen.has(g.id)) continue;
+      if (keep !== null && !keep.has(g.id)) continue;
+      out.push({ g, hasKids: false, hit: true });
+    }
+    return out;
+  });
+
+  const treeFoot = $derived.by(() => {
+    const active = groups.filter((g) => g.archivedAt === null);
+    const archivedN = groups.length - active.length;
+    const totalMembers = active.reduce((n, g) => n + g.memberCount, 0);
+    return (
+      `${active.length} 个活跃组 · ${totalMembers} 条成员关系` +
+      (archivedN > 0 ? ` · ${archivedN} 个已删除` : "")
+    );
+  });
+
+  /** 面包屑:祖先链(根在前,自身在末)。 */
+  const chain = $derived.by((): MemberGroupNode[] => {
+    if (selected === null) return [];
+    const byId = new Map(groups.map((g) => [g.id, g]));
+    const out: MemberGroupNode[] = [];
+    for (let cur: MemberGroupNode | undefined = selected; cur !== undefined; ) {
+      out.unshift(cur);
+      cur = cur.parentId === null ? undefined : byId.get(cur.parentId);
+    }
+    return out;
+  });
+
+  const childCount = $derived(groups.filter((g) => g.parentId === selectedId).length);
+
+  const shownMembers = $derived.by(() => {
+    const q = memberFilter.trim().toLowerCase();
+    if (q === "") return members;
+    return members.filter(
+      (m) =>
+        m.displayName.toLowerCase().includes(q) ||
+        m.userId.toLowerCase().includes(q) ||
+        m.feishuOpenId.toLowerCase().includes(q),
+    );
+  });
+
+  function fmtDate(iso: string): string {
+    try {
+      return new Date(iso).toLocaleString("zh-CN", { dateStyle: "medium", timeStyle: "short" });
+    } catch {
+      return iso;
+    }
+  }
+
+  const errText = (e: unknown): string => (e instanceof Error ? e.message : String(e));
+
+  async function loadGroups(): Promise<void> {
+    try {
+      const r = await api<{ groups: MemberGroupNode[] }>(
+        `/database/api/groups${showArchived ? "?includeArchived=1" : ""}`,
+      );
+      groups = r.groups;
+      listError = null;
+      loaded = true;
+      if (selectedId !== null && !groups.some((g) => g.id === selectedId)) {
+        selectedId = null;
+        members = [];
+        membersLoaded = false;
+      }
+    } catch (e) {
+      listError = errText(e);
+      loaded = true;
+    }
+  }
+
+  async function loadMembers(): Promise<void> {
+    if (selectedId === null) return;
+    membersLoaded = false;
+    membersError = null;
+    try {
+      const r = await api<{ members: MemberGroupMember[] }>(
+        `/database/api/groups/${encodeURIComponent(selectedId)}/members`,
+      );
+      members = r.members;
+      membersLoaded = true;
+    } catch (e) {
+      membersError = errText(e);
+      membersLoaded = true;
+    }
+  }
+
+  onMount(async () => {
+    await loadGroups();
+    // 授权面板「成员」单元格跳转:?select=<groupId> 直接选中该组。
+    // 组不在列表(已归档且未开归档展示)时不动作,停留默认态。
+    const target = page.url.searchParams.get("select");
+    if (target !== null && groups.some((g) => g.id === target)) select(target);
+  });
+
+  function select(id: string): void {
+    selectedId = id;
+    memberFilter = "";
+    void loadMembers();
+  }
+
+  async function toggleArchived(): Promise<void> {
+    showArchived = !showArchived;
+    await loadGroups();
+  }
+
+  /* ---------------- 右键菜单 ---------------- */
+
+  interface MenuItem {
+    readonly label?: string;
+    readonly ic?: import("./Icon.svelte").IconName;
+    readonly danger?: boolean;
+    readonly sep?: boolean;
+    readonly fn?: () => void;
+  }
+
+  let menu = $state<{ x: number; y: number; items: MenuItem[] } | null>(null);
+
+  function openMenu(e: MouseEvent, target: MemberGroupNode | null): void {
+    e.preventDefault();
+    // 已归档组:只给「恢复」—— 归档态下不允许建子组/加成员/改名(后端亦 404 兜底)。
+    const items: MenuItem[] =
+      target === null
+        ? [{ label: "新建根 Group", ic: "plus", fn: () => openCreate(null) }]
+        : target.archivedAt !== null
+          ? [
+              { label: "查看成员(只读)", ic: "users", fn: () => select(target.id) },
+              { label: "恢复此 Group", ic: "restore", fn: () => void restoreGroup(target) },
+              { sep: true },
+              { label: "新建根 Group", ic: "layers", fn: () => openCreate(null) },
+            ]
+          : [
+              { label: "新建子 Group", ic: "plus", fn: () => openCreate(target) },
+              { label: "添加成员", ic: "user", fn: () => { select(target.id); openAddMember(); } },
+              { label: "重命名 / 改描述", ic: "pencil", fn: () => openRename(target) },
+              { sep: true },
+              { label: "新建根 Group", ic: "layers", fn: () => openCreate(null) },
+              { label: "删除(级联子树)", ic: "trash", danger: true, fn: () => void deleteGroup(target) },
+            ];
+    // 贴边翻转,避免菜单溢出视口(菜单宽 184、每项约 34)。
+    const w = 184;
+    const h = items.reduce((n, it) => n + (it.sep === true ? 9 : 34), 10);
+    menu = {
+      x: Math.min(e.clientX, window.innerWidth - w - 8),
+      y: Math.min(e.clientY, window.innerHeight - h - 8),
+      items,
+    };
+  }
+
+  /* ---------------- 弹窗 ---------------- */
+
+  let showCreate = $state(false);
+  let createParent = $state<MemberGroupNode | null>(null);
+  let newName = $state("");
+  let newDesc = $state("");
+
+  let showRename = $state(false);
+  let renameTarget = $state<MemberGroupNode | null>(null);
+  let editName = $state("");
+  let editDesc = $state("");
+
+  let showAdd = $state(false);
+  let addQuery = $state("");
+  let addResults = $state<UserSearchResult[]>([]);
+  let addSearching = $state(false);
+
+  function openCreate(parent: MemberGroupNode | null): void {
+    createParent = parent;
+    newName = "";
+    newDesc = "";
+    showCreate = true;
+  }
+
+  async function createGroup(): Promise<void> {
+    const name = newName.trim();
+    if (name === "") {
+      toastErr("名称必填");
+      return;
+    }
+    const parentId = createParent?.id ?? null;
+    try {
+      await api("/database/api/groups", {
+        method: "POST",
+        body: { name, parentId, ...(newDesc.trim() !== "" ? { description: newDesc.trim() } : {}) },
+      });
+      showCreate = false;
+      // 建完自动展开父节点,否则新子组藏在折叠的父下面看不见。
+      if (parentId !== null) collapsedIds = collapsedIds.filter((x) => x !== parentId);
+      toastOk("已创建成员组");
+      await loadGroups();
+    } catch (e) {
+      toastErr(errText(e));
+    }
+  }
+
+  function openRename(g: MemberGroupNode): void {
+    renameTarget = g;
+    editName = g.name;
+    editDesc = g.description ?? "";
+    showRename = true;
+  }
+
+  async function saveRename(): Promise<void> {
+    if (renameTarget === null) return;
+    const name = editName.trim();
+    if (name === "") {
+      toastErr("名称必填");
+      return;
+    }
+    try {
+      // description 总是回传(含空串)—— 空串即清除描述(ADR-0028 决策6)。
+      await api(`/database/api/groups/${encodeURIComponent(renameTarget.id)}`, {
+        method: "PATCH",
+        body: { name, description: editDesc.trim() },
+      });
+      showRename = false;
+      toastOk("已保存");
+      await loadGroups();
+    } catch (e) {
+      toastErr(errText(e));
+    }
+  }
+
+  async function deleteGroup(g: MemberGroupNode): Promise<void> {
+    if (
+      !confirm(
+        `删除「${g.name}」?\n\n软删除:整棵子树一并标记删除,相关授权立即失效,` +
+          "但数据保留 —— 可在左侧打开「显示已删除的组」后恢复。",
+      )
+    )
+      return;
+    try {
+      const r = await api<{ archivedCount: number }>(
+        `/database/api/groups/${encodeURIComponent(g.id)}`,
+        { method: "DELETE" },
+      );
+      if (selectedId === g.id && !showArchived) {
+        selectedId = null;
+        members = [];
+        membersLoaded = false;
+      }
+      toastOk(`已删除 ${r.archivedCount} 个组(软删除,可恢复)`);
+      await loadGroups();
+      if (selectedId === g.id) await loadMembers();
+    } catch (e) {
+      toastErr(errText(e));
+    }
+  }
+
+  async function restoreGroup(g: MemberGroupNode): Promise<void> {
+    // 恢复语义与删除不对称(ADR-0028 决策7):只回该组 + 已归档祖先链,子树仍归档。
+    if (
+      !confirm(
+        `恢复「${g.name}」?\n\n其已删除的上级会一并恢复(否则它在树上无路径);` +
+          "子组保持删除状态,需各自恢复。恢复后该组的授权立即重新生效。",
+      )
+    )
+      return;
+    try {
+      const r = await api<{ restoredCount: number }>(
+        `/database/api/groups/${encodeURIComponent(g.id)}/restore`,
+        { method: "POST" },
+      );
+      toastOk(`已恢复 ${r.restoredCount} 个组`);
+      await loadGroups();
+      if (selectedId === g.id) await loadMembers();
+    } catch (e) {
+      toastErr(errText(e));
+    }
+  }
+
+  function openAddMember(): void {
+    addQuery = "";
+    addResults = [];
+    showAdd = true;
+  }
+
+  /** 成员选择器:搜全局用户,excludeGroupId 过滤掉本组已有成员。 */
+  async function searchUsers(): Promise<void> {
+    if (selectedId === null) return;
+    addSearching = true;
+    try {
+      const r = await api<{ users: UserSearchResult[] }>(
+        `/database/api/users/search?q=${encodeURIComponent(addQuery.trim())}` +
+          `&excludeGroupId=${encodeURIComponent(selectedId)}`,
+      );
+      addResults = r.users;
+    } catch (e) {
+      toastErr(errText(e));
+    } finally {
+      addSearching = false;
+    }
+  }
+
+  async function addMember(userId: string): Promise<void> {
+    if (selectedId === null) return;
+    try {
+      await api(`/database/api/groups/${encodeURIComponent(selectedId)}/members`, {
+        method: "POST",
+        body: { userId },
+      });
+      toastOk("已添加成员");
+      addResults = addResults.filter((u) => u.userId !== userId);
+      await Promise.all([loadMembers(), loadGroups()]);
+    } catch (e) {
+      toastErr(errText(e));
+    }
+  }
+
+  async function removeMember(m: MemberGroupMember): Promise<void> {
+    if (selectedId === null) return;
+    if (!confirm(`将「${m.displayName || m.userId}」移出本组?其经由本组获得的授权立即失效。`)) return;
+    try {
+      await api(
+        `/database/api/groups/${encodeURIComponent(selectedId)}/members/${encodeURIComponent(m.userId)}`,
+        { method: "DELETE" },
+      );
+      toastOk("已移除成员");
+      await Promise.all([loadMembers(), loadGroups()]);
+    } catch (e) {
+      toastErr(errText(e));
+    }
+  }
+</script>
+
+<svelte:window
+  onclick={() => (menu = null)}
+  onkeydown={(e) => {
+    if (e.key === "Escape") menu = null;
+  }}
+/>
+
+<div class="flex h-full min-h-0 items-stretch gap-3.5">
+  <!-- 左:组树 -->
+  <div class="panel flex w-[326px] shrink-0 flex-col !p-3.5" style="min-height:0">
+    <div class="mb-2.5 flex items-center gap-2">
+      <span class="flex text-accent"><Icon name="layers" size={17} /></span>
+      <div class="section-title flex-1">Group 树</div>
+      <button class="btn btn-sm" onclick={() => openCreate(null)}>
+        <Icon name="plus" size={13} /> 根组
+      </button>
+    </div>
+
+    <div class="relative mb-2">
+      <span class="pointer-events-none absolute left-[9px] top-1/2 flex -translate-y-1/2 text-ink-3">
+        <Icon name="search" size={13} />
+      </span>
+      <input class="input !pl-7 !text-[12.5px]" placeholder="过滤组名…" bind:value={filterText} />
+    </div>
+
+    <label class="switch mb-2.5 text-[11.5px] text-ink-3">
+      <input type="checkbox" checked={showArchived} onchange={toggleArchived} />
+      <span></span>
+      显示已删除的组
+    </label>
+
+    <!-- 树空白处右键 = 建根组 -->
+    <div
+      class="-mx-1.5 min-h-0 flex-1 overflow-y-auto"
+      role="tree"
+      tabindex="-1"
+      oncontextmenu={(e) => {
+        if ((e.target as HTMLElement).closest("[data-node]") !== null) return;
+        openMenu(e, null);
+      }}
+    >
+      {#if !loaded}
+        <div class="quiet px-3 py-6 text-center">加载中…</div>
+      {:else if listError !== null}
+        <div class="px-3 py-6 text-center text-xs text-danger">{listError}</div>
+      {:else if groups.length === 0}
+        <div class="quiet flex flex-col items-center gap-2 px-3 py-[22px] text-center">
+          <span class="flex text-line"><Icon name="layers" size={30} /></span>
+          暂无成员组 · 点上方「根组」开始
+        </div>
+      {:else if rows.length === 0}
+        <div class="quiet px-3 py-[22px] text-center">无匹配的组</div>
+      {:else}
+        {#each rows as { g, hasKids, hit } (g.id)}
+          {@const arch = g.archivedAt !== null}
+          <div
+            data-node
+            class="flex cursor-pointer select-none items-center gap-1.5 rounded-lg py-1.5 pr-2 text-[13px]"
+            class:bg-selected={selectedId === g.id}
+            class:opacity-50={!hit}
+            style="padding-left: {8 + g.depth * 15}px"
+            role="treeitem"
+            aria-selected={selectedId === g.id}
+            tabindex="-1"
+            onclick={() => select(g.id)}
+            onkeydown={(e) => {
+              if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                select(g.id);
+              }
+            }}
+            oncontextmenu={(e) => openMenu(e, g)}
+          >
+            {#if hasKids}
+              <span
+                class="flex w-[15px] shrink-0 justify-center text-ink-3 transition-transform"
+                class:rotate-90={!(isCollapsed(g.id) && filterText.trim() === "")}
+                role="button"
+                tabindex="-1"
+                aria-label="折叠 / 展开"
+                onclick={(e) => {
+                  e.stopPropagation();
+                  toggleCollapsed(g.id);
+                }}
+                onkeydown={(e) => {
+                  if (e.key === "Enter") toggleCollapsed(g.id);
+                }}
+              >
+                <Icon name="chevron" size={13} />
+              </span>
+            {:else}
+              <span class="inline-block w-[15px] shrink-0"></span>
+            {/if}
+
+            <span class="flex" class:text-accent={selectedId === g.id && !arch} class:text-ink-3={arch || selectedId !== g.id}>
+              <Icon name={arch ? "archive" : "group"} size={15} />
+            </span>
+            <span class="flex-1 truncate" class:text-ink-3={arch} class:line-through={arch}>{g.name}</span>
+            <span class="tag shrink-0" class:opacity-70={arch}>
+              <Icon name="user" size={10} />{g.memberCount}
+            </span>
+            {#if arch}
+              <span class="tag shrink-0 !text-[10px] opacity-85">已删除</span>
+            {/if}
+          </div>
+        {/each}
+      {/if}
+    </div>
+
+    <div class="section-note mt-2 border-t border-line-soft pt-2">{loaded ? treeFoot : ""}</div>
+  </div>
+
+  <!-- 右:成员表 -->
+  <div class="panel flex min-h-0 min-w-0 flex-1 flex-col !p-0">
+    {#if selected === null}
+      <div class="quiet m-auto flex flex-col items-center gap-2.5 p-7 text-center">
+        <span class="flex text-line"><Icon name="users" size={40} /></span>
+        从左侧选择一个 Group 查看成员
+      </div>
+    {:else}
+      {#if isArchived}
+        <!-- 归档横幅:软删除是"打标",数据仍在,只是不再贡献权限。 -->
+        <div
+          class="flex shrink-0 items-center gap-2.5 border-b border-line-soft bg-hover px-[18px] py-2.5 text-[12.5px]"
+        >
+          <span class="flex text-ink-3"><Icon name="archive" size={15} /></span>
+          <span class="flex-1">
+            此 Group 已删除于 {fmtDate(selected.archivedAt ?? "")} · 成员只读,不再授予任何权限
+          </span>
+          <button class="btn !text-xs" onclick={() => void restoreGroup(selected)}>
+            <Icon name="restore" size={13} /> 恢复
+          </button>
+        </div>
+      {/if}
+
+      <div class="shrink-0 border-b border-line-soft px-[18px] pb-3 pt-4">
+        <div class="mb-1.5 text-xs">
+          {#each chain as c, i (c.id)}
+            {#if i > 0}<span class="mx-[5px] text-ink-3">/</span>{/if}
+            <span class={i === chain.length - 1 ? "font-medium text-ink" : "text-ink-3"}>{c.name}</span>
+          {/each}
+        </div>
+
+        <div class="flex items-center gap-2.5">
+          <span class="flex" class:text-ink-3={isArchived} class:text-accent={!isArchived}>
+            <Icon name={isArchived ? "archive" : "group"} size={20} />
+          </span>
+          <div class="min-w-0 flex-1">
+            <div class="text-base font-semibold" class:text-ink-3={isArchived}>{selected.name}</div>
+            {#if selected.description !== null && selected.description !== ""}
+              <div class="section-note mt-0.5">{selected.description}</div>
+            {:else}
+              <div class="section-note mt-0.5 opacity-60">无描述</div>
+            {/if}
+          </div>
+          <!-- 归档态不给改名/加成员入口(后端 requireActiveGroup 亦 404 兜底)。 -->
+          {#if !isArchived}
+            <button class="btn !text-xs" onclick={() => openRename(selected)}>
+              <Icon name="pencil" size={13} /> 编辑
+            </button>
+            <button class="btn btn-primary !text-xs" onclick={openAddMember}>
+              <Icon name="plus" size={13} /> 添加成员
+            </button>
+          {/if}
+        </div>
+
+        <div class="mt-3 flex gap-4 text-xs text-ink-3">
+          <span class="inline-flex items-center gap-1"><Icon name="user" size={12} />{members.length} 名成员</span>
+          <span class="inline-flex items-center gap-1"><Icon name="layers" size={12} />层级 {selected.depth}</span>
+          <span class="inline-flex items-center gap-1"><Icon name="group" size={12} />{childCount} 个子组</span>
+        </div>
+      </div>
+
+      <div class="flex shrink-0 items-center gap-2.5 px-[18px] py-2.5">
+        <div class="relative max-w-[280px] flex-1">
+          <span class="pointer-events-none absolute left-[9px] top-1/2 flex -translate-y-1/2 text-ink-3">
+            <Icon name="search" size={13} />
+          </span>
+          <input class="input !pl-7 !text-[12.5px]" placeholder="搜索成员…" bind:value={memberFilter} />
+        </div>
+        <span class="file-meta">
+          {memberFilter.trim() === "" ? "" : `${shownMembers.length} / ${members.length}`}
+        </span>
+      </div>
+
+      <div class="min-h-0 flex-1 overflow-y-auto px-[18px] pb-[18px]">
+        {#if !membersLoaded}
+          <div class="quiet px-3 py-9 text-center">加载中…</div>
+        {:else if membersError !== null}
+          <div class="px-3 py-9 text-center text-xs text-danger">{membersError}</div>
+        {:else if members.length === 0}
+          <div class="quiet flex flex-col items-center gap-2.5 px-3 py-9 text-center">
+            <span class="flex text-line"><Icon name="users" size={34} /></span>
+            {isArchived ? "此组无成员记录" : "此组暂无成员 · 点右上「添加成员」"}
+          </div>
+        {:else if shownMembers.length === 0}
+          <div class="quiet px-3 py-[30px] text-center">无匹配成员</div>
+        {:else}
+          <table class="list">
+            <thead>
+              <tr>
+                <th>成员</th>
+                <th>userId</th>
+                <th>飞书 openId</th>
+                <th>加入时间</th>
+                {#if !isArchived}<th class="!text-right">操作</th>{/if}
+              </tr>
+            </thead>
+            <tbody>
+              {#each shownMembers as m (m.userId)}
+                <tr>
+                  <td>
+                    <span class="inline-flex items-center gap-2.5">
+                      <Avatar displayName={m.displayName} userId={m.userId} avatarUrl={m.avatarUrl} size={28} />
+                      <span class="font-medium">{m.displayName || "(未命名)"}</span>
+                    </span>
+                  </td>
+                  <td class="file-meta">{m.userId}</td>
+                  <td class="file-meta">{m.feishuOpenId || "—"}</td>
+                  <td class="file-meta">{fmtDate(m.joinedAt)}</td>
+                  {#if !isArchived}
+                    <td class="text-right">
+                      <button class="link-danger inline-flex items-center gap-1" onclick={() => void removeMember(m)}>
+                        <Icon name="minus" size={12} /> 移除
+                      </button>
+                    </td>
+                  {/if}
+                </tr>
+              {/each}
+            </tbody>
+          </table>
+        {/if}
+      </div>
+    {/if}
+  </div>
+</div>
+
+<!-- 右键菜单 -->
+{#if menu !== null}
+  <div
+    class="fixed z-[60] min-w-[184px] rounded-[10px] border border-line bg-panel p-[5px] text-[13px] shadow-[0_4px_20px_rgba(26,26,24,.07)]"
+    style="left:{menu.x}px;top:{menu.y}px"
+    role="menu"
+    tabindex="-1"
+  >
+    {#each menu.items as it, i (i)}
+      {#if it.sep === true}
+        <div class="mx-1.5 my-1 h-px bg-line-soft"></div>
+      {:else}
+        <div
+          class="flex cursor-pointer items-center gap-2 rounded-md px-[11px] py-[7px] hover:bg-hover"
+          class:text-danger={it.danger === true}
+          role="menuitem"
+          tabindex="-1"
+          onclick={(e) => {
+            e.stopPropagation();
+            menu = null;
+            it.fn?.();
+          }}
+          onkeydown={(e) => {
+            if (e.key === "Enter") {
+              menu = null;
+              it.fn?.();
+            }
+          }}
+        >
+          {#if it.ic !== undefined}<span class="flex opacity-75"><Icon name={it.ic} size={14} /></span>{/if}
+          {it.label}
+        </div>
+      {/if}
+    {/each}
+  </div>
+{/if}
+
+{#if showCreate}
+  <Modal
+    title={createParent === null ? "新建根 Group" : `在「${createParent.name}」下新建子 Group`}
+    onclose={() => (showCreate = false)}
+  >
+    <div class="form-row">
+      <label class="form-label" for="gc-name">名称</label>
+      <input id="gc-name" class="input" bind:value={newName} placeholder="例如:物理教研组" />
+    </div>
+    <div class="form-row">
+      <label class="form-label" for="gc-desc">描述(可选)</label>
+      <input id="gc-desc" class="input" bind:value={newDesc} placeholder="一句话说明" />
+    </div>
+    <div class="mt-4 flex justify-end gap-2">
+      <button class="btn" onclick={() => (showCreate = false)}>取消</button>
+      <button class="btn btn-primary" onclick={createGroup}>创建</button>
+    </div>
+  </Modal>
+{/if}
+
+{#if showRename && renameTarget !== null}
+  <Modal title="重命名 / 改描述" onclose={() => (showRename = false)}>
+    <div class="form-row">
+      <label class="form-label" for="gr-name">名称</label>
+      <input id="gr-name" class="input" bind:value={editName} />
+    </div>
+    <div class="form-row">
+      <label class="form-label" for="gr-desc">描述</label>
+      <input id="gr-desc" class="input" bind:value={editDesc} placeholder="留空则清除描述" />
+    </div>
+    <div class="mt-4 flex justify-end gap-2">
+      <button class="btn" onclick={() => (showRename = false)}>取消</button>
+      <button class="btn btn-primary" onclick={saveRename}>保存</button>
+    </div>
+  </Modal>
+{/if}
+
+{#if showAdd && selected !== null}
+  <Modal title={`向「${selected.name}」添加成员`} onclose={() => (showAdd = false)}>
+    <div class="form-row">
+      <label class="form-label" for="ga-q">搜索用户(姓名 / userId / 飞书 openId)</label>
+      <div class="flex gap-2">
+        <input
+          id="ga-q"
+          class="input"
+          bind:value={addQuery}
+          placeholder="留空列出全部候选"
+          onkeydown={(e) => {
+            if (e.key === "Enter") void searchUsers();
+          }}
+        />
+        <button class="btn" onclick={searchUsers}><Icon name="search" size={13} /> 搜索</button>
+      </div>
+      <div class="section-note mt-1.5">已在本组的成员不会出现在结果里。</div>
+    </div>
+
+    <div class="max-h-[280px] overflow-y-auto">
+      {#if addSearching}
+        <div class="quiet px-3 py-6 text-center">搜索中…</div>
+      {:else if addResults.length === 0}
+        <div class="quiet px-3 py-6 text-center">无候选用户 · 先点「搜索」</div>
+      {:else}
+        {#each addResults as u (u.userId)}
+          <div class="flex items-center gap-2.5 border-b border-line-soft py-2 last:border-b-0">
+            <Avatar displayName={u.displayName} userId={u.userId} avatarUrl={u.avatarUrl} size={26} />
+            <div class="min-w-0 flex-1">
+              <div class="truncate text-[13px] font-medium">{u.displayName || "(未命名)"}</div>
+              <div class="file-meta truncate">{u.feishuOpenId || u.userId}</div>
+            </div>
+            <button class="btn btn-sm" onclick={() => void addMember(u.userId)}>
+              <Icon name="plus" size={12} /> 添加
+            </button>
+          </div>
+        {/each}
+      {/if}
+    </div>
+
+    <div class="mt-4 flex justify-end gap-2">
+      <button class="btn" onclick={() => (showAdd = false)}>关闭</button>
+    </div>
+  </Modal>
+{/if}

hub/filelib-web/src/lib/Icon.svelte

@@ -0,0 +1,41 @@
+<script lang="ts" module>
+  // 从已删除的 routes/adminPanels.ts 的 GROUP_ICONS 原样搬来(ADR-0029)。
+  export const ICONS = {
+    // Group 节点 = 人的集合。**不用文件夹图标** —— Group 不是目录,与文件库的
+    // FOLDER/PROJECT 是两套体系,图标上也不应混淆。两人剪影。
+    group:
+      "M16 19v-1.5a3.5 3.5 0 0 0-3.5-3.5h-5A3.5 3.5 0 0 0 4 17.5V19M10 11.5a3.25 3.25 0 1 0 0-6.5 3.25 3.25 0 0 0 0 6.5ZM20 19v-1.5a3.5 3.5 0 0 0-2.6-3.38M15.4 5.22a3.25 3.25 0 0 1 0 6.06",
+    users:
+      "M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2M9 11a4 4 0 1 0 0-8 4 4 0 0 0 0 8Zm14 10v-2a4 4 0 0 0-3-3.87M16 3.13a4 4 0 0 1 0 7.75",
+    user: "M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2M12 11a4 4 0 1 0 0-8 4 4 0 0 0 0 8Z",
+    plus: "M12 5v14M5 12h14",
+    pencil: "M17 3a2.8 2.8 0 0 1 4 4L7.5 20.5 2 22l1.5-5.5L17 3Z",
+    trash: "M3 6h18M8 6V4h8v2m-9 0 1 14h8l1-14",
+    search: "m21 21-4.3-4.3M11 18a7 7 0 1 0 0-14 7 7 0 0 0 0 14Z",
+    chevron: "m9 18 6-6-6-6",
+    layers: "m12 2 9 5-9 5-9-5 9-5Zm9 11-9 5-9-5m18 5-9 5-9-5",
+    clock: "M12 22a10 10 0 1 0 0-20 10 10 0 0 0 0 20Zm0-14v6l4 2",
+    minus: "M5 12h14",
+    // 已归档(软删)标记用;与"删除"区分 —— 数据仍在,只是打了 archivedAt。
+    archive: "M3 8h18v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8Zm1-5h16l1 5H3l1-5Zm5 9h6",
+    restore: "M3 12a9 9 0 1 0 3-6.7M3 4v4.5h4.5",
+  } as const;
+
+  export type IconName = keyof typeof ICONS;
+</script>
+
+<script lang="ts">
+  let { name, size = 16 }: { name: IconName; size?: number } = $props();
+</script>
+
+<svg
+  style="width:{size}px;height:{size}px"
+  class="shrink-0"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="1.8"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+  aria-hidden="true"
+><path d={ICONS[name]} /></svg>

hub/filelib-web/src/lib/LibraryView.svelte

@@ -0,0 +1,147 @@
+<script lang="ts">
+  /**
+   * 文件库浏览器(树 + 详情 + 文件编辑栏)。
+   *
+   * 两处复用:老师端 /app(showUserFooter=true,侧栏底部带身份与退出)
+   * 与管理后台 /database/dashboard/library(false —— 外层壳已有身份区)。
+   */
+  import { onMount } from "svelte";
+  import { api } from "./api.js";
+  import { me, toastErr, toastOk } from "./stores.js";
+  import { logout } from "./session.js";
+  import { treeVersion, bumpTree, currentNode, selectedFilePath, clearSelectedFile, bumpFiles } from "./browser.js";
+  import type { NodeChild } from "./types.js";
+  import TreeNode from "./TreeNode.svelte";
+  import NodeDetailPanel from "./NodeDetailPanel.svelte";
+  import FileEditor from "./FileEditor.svelte";
+  import Modal from "./Modal.svelte";
+
+  let { showUserFooter = false }: { showUserFooter?: boolean } = $props();
+
+  let roots = $state<NodeChild[] | null>(null);
+  let treeError = $state<string | null>(null);
+  let showCreateRoot = $state(false);
+  let newName = $state("");
+  let newKind = $state<"FOLDER" | "PROJECT">("FOLDER");
+  let newDesc = $state("");
+
+  async function loadRoots(): Promise<void> {
+    try {
+      const r = await api<{ nodes: NodeChild[] }>("/database/api/nodes");
+      roots = r.nodes;
+      treeError = null;
+    } catch (e) {
+      treeError = e instanceof Error ? e.message : String(e);
+    }
+  }
+
+  onMount(loadRoots);
+  $effect(() => {
+    void $treeVersion;
+    void loadRoots();
+  });
+
+  async function createRoot(): Promise<void> {
+    const name = newName.trim();
+    if (name === "") return;
+    try {
+      await api("/database/api/nodes", {
+        method: "POST",
+        body: {
+          parentId: null,
+          kind: newKind,
+          name,
+          ...(newDesc.trim() !== "" ? { description: newDesc.trim() } : {}),
+        },
+      });
+      toastOk("已创建");
+      showCreateRoot = false;
+      newName = ""; newKind = "FOLDER"; newDesc = "";
+      bumpTree();
+    } catch (e) {
+      toastErr(e instanceof Error ? e.message : String(e));
+    }
+  }
+
+  const initial = $derived(($me?.userId ?? "U").slice(0, 1).toUpperCase());
+</script>
+
+<div class="flex min-h-0 flex-1">
+  <!-- 侧栏 -->
+  <aside class="flex w-[300px] shrink-0 flex-col border-r border-line-soft bg-sidebar">
+    <div class="flex items-center justify-between border-b border-line-soft px-4 py-3.5">
+      <span class="text-[15px] font-semibold text-ink">文件库</span>
+      {#if $me?.isWebsiteAdmin}
+        <button class="btn btn-sm" onclick={() => (showCreateRoot = true)}>
+          + 根目录
+        </button>
+      {/if}
+    </div>
+
+    <div class="flex-1 overflow-y-auto px-2 py-2 text-[13px]">
+      {#if treeError}
+        <div class="px-3 py-6 text-center text-xs text-danger">{treeError}</div>
+      {:else if roots === null}
+        <div class="px-3 py-6 text-center text-xs text-ink-3">加载中…</div>
+      {:else if roots.length === 0}
+        <div class="px-3 py-6 text-center text-xs text-ink-3">
+          {$me?.isWebsiteAdmin ? "空文件库 · 点上方「+ 根目录」开始" : "文件库为空,请联系管理员创建根目录"}
+        </div>
+      {:else}
+        {#each roots as node (node.id)}
+          <TreeNode {node} depth={0} />
+        {/each}
+      {/if}
+    </div>
+
+    {#if showUserFooter}
+      <div class="flex items-center gap-2 border-t border-line-soft px-4 py-3 text-[12.5px]">
+        <div class="flex h-6 w-6 shrink-0 items-center justify-center rounded-full bg-accent text-[11px] font-semibold text-white">{initial}</div>
+        <span class="flex-1 truncate text-ink">{$me?.userId ?? ""}</span>
+        <button class="rounded-lg border border-line-soft px-2.5 py-1 text-[11.5px] text-ink-3 transition hover:bg-hover hover:text-ink" onclick={logout} title="退出登录">退出</button>
+      </div>
+    {/if}
+  </aside>
+
+  <!-- 主区 -->
+  <main class="flex-1 overflow-y-auto">
+    <NodeDetailPanel />
+  </main>
+
+  <!-- 右侧:文件预览/编辑栏(选中文件时出现) -->
+  {#if $selectedFilePath && $currentNode?.kind === "PROJECT"}
+    <section class="flex w-[46%] min-w-[420px] shrink-0 flex-col overflow-y-auto border-l border-line-soft bg-bg p-4">
+      <FileEditor
+        projectId={$currentNode.id}
+        path={$selectedFilePath}
+        role={$currentNode.role}
+        onchanged={bumpFiles}
+        onclose={clearSelectedFile}
+      />
+    </section>
+  {/if}
+</div>
+
+{#if showCreateRoot}
+  <Modal title="新建根目录" onclose={() => (showCreateRoot = false)}>
+    <div class="form-row">
+      <label class="form-label" for="root-name">名称</label>
+      <input id="root-name" class="input" bind:value={newName} placeholder="例如:物理教研" />
+    </div>
+    <div class="form-row">
+      <label class="form-label" for="root-kind">类型</label>
+      <select id="root-kind" class="select" bind:value={newKind}>
+        <option value="FOLDER">文件夹</option>
+        <option value="PROJECT">项目(课程资源库)</option>
+      </select>
+    </div>
+    <div class="form-row">
+      <label class="form-label" for="root-desc">简介(可选)</label>
+      <textarea id="root-desc" rows="3" class="textarea" bind:value={newDesc} placeholder="简要说明用途…"></textarea>
+    </div>
+    <div class="mt-4 flex justify-end gap-2">
+      <button class="btn" onclick={() => (showCreateRoot = false)}>取消</button>
+      <button class="btn btn-primary" onclick={createRoot}>创建</button>
+    </div>
+  </Modal>
+{/if}

hub/filelib-web/src/lib/LoginView.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+  import { onMount } from "svelte";
+  import { loadConfig, type AppConfig } from "./config.js";
+
+  let info = $state<AppConfig | null>(null);
+  let loadFailed = $state(false);
+
+  onMount(async () => {
+    try {
+      info = await loadConfig();
+    } catch {
+      loadFailed = true;
+    }
+  });
+</script>
+
+<div class="flex min-h-full items-center justify-center p-6">
+  <div class="w-full max-w-[380px] rounded-2xl border border-line-soft bg-panel p-9 shadow-[0_4px_20px_rgba(26,26,24,.07)]">
+    <div class="text-center text-[26px] font-semibold tracking-wide text-ink">文件库</div>
+    <p class="mt-2.5 mb-8 text-center text-[13px] text-ink-3">课程资源与教研文件,一处安放,随处可查</p>
+
+    {#if info}
+      <a
+        href="/auth/feishu/{encodeURIComponent(info.orgSlug)}"
+        data-sveltekit-reload
+        class="flex w-full items-center justify-center rounded-lg bg-accent px-4 py-3 text-sm font-medium text-white transition hover:bg-accent-hover"
+      >使用飞书登录</a>
+
+      {#if info.devLoginEnabled}
+        <div class="my-5 flex items-center gap-2.5 text-[11px] text-ink-3">
+          <span class="flex-1 border-t border-line-soft"></span>开发模式
+          <span class="flex-1 border-t border-line-soft"></span>
+        </div>
+        <a href="/app/dev-login-teacher" data-sveltekit-reload class="flex w-full items-center justify-center rounded-lg border border-line bg-panel px-4 py-2 text-[12.5px] font-medium text-ink transition hover:bg-hover">⚡ 一键登录(老师)</a>
+        <p class="mt-2.5 text-center text-[11px] text-ink-3">仅开发环境可见 · 跳过飞书 OAuth</p>
+      {/if}
+    {:else if loadFailed}
+      <p class="text-center text-[12.5px] text-danger">无法加载登录配置,请稍后重试</p>
+    {:else}
+      <p class="text-center text-[12.5px] text-ink-3">加载中…</p>
+    {/if}
+  </div>
+</div>

hub/filelib-web/src/lib/Modal.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+  import type { Snippet } from "svelte";
+
+  let { title, onclose, children }: { title: string; onclose: () => void; children: Snippet } = $props();
+</script>
+
+<div
+  class="fixed inset-0 z-40 flex items-center justify-center bg-black/30 p-4"
+  role="presentation"
+  onclick={(e) => { if (e.target === e.currentTarget) onclose(); }}
+>
+  <div class="w-full max-w-[440px] rounded-2xl border border-line-soft bg-panel p-6 shadow-[0_4px_20px_rgba(26,26,24,.07)]">
+    <div class="mb-4 text-[15px] font-semibold">{title}</div>
+    {@render children()}
+  </div>
+</div>

hub/filelib-web/src/lib/NodeDetailPanel.svelte

@@ -0,0 +1,164 @@
+<script lang="ts">
+  import { api } from "./api.js";
+  import { currentNode, breadcrumb, bumpTree, clearSelectedFile } from "./browser.js";
+  import { toastOk, toastErr } from "./stores.js";
+  import { ROLE_LABEL } from "./labels.js";
+  import OverviewPanel from "./OverviewPanel.svelte";
+  import FilesPanel from "./FilesPanel.svelte";
+  import GrantsPanel from "./GrantsPanel.svelte";
+  import Modal from "./Modal.svelte";
+  import Icon from "./Icon.svelte";
+
+  type Tab = "detail" | "files" | "grants";
+  let tab = $state<Tab>("detail");
+  let showCreateChild = $state(false);
+  let newName = $state("");
+  let newKind = $state<"FOLDER" | "PROJECT">("FOLDER");
+  let newDesc = $state("");
+
+  const node = $derived($currentNode);
+  const crumbs = $derived($breadcrumb);
+  const canManage = $derived(node?.role === "MANAGE");
+  const canEdit = $derived(canManage || node?.role === "EDIT");
+
+  // 与旧 libraryBrowser 的 tab 组装一致:概览恒有;文件仅 PROJECT;授权仅 MANAGE
+  // (FOLDER 也有授权 —— 它虽是透明组织节点,授权仍挂在节点上,ADR-0021)。
+  const tabs = $derived.by((): ReadonlyArray<readonly [Tab, string]> => {
+    const out: Array<readonly [Tab, string]> = [["detail", "概览"]];
+    if (node?.kind === "PROJECT") out.push(["files", "文件"]);
+    if (canManage) out.push(["grants", "授权"]);
+    return out;
+  });
+
+  $effect(() => {
+    void node?.id;
+    tab = "detail";
+    clearSelectedFile();
+  });
+
+  async function createChild(): Promise<void> {
+    const name = newName.trim();
+    if (name === "" || node === null) return;
+    try {
+      await api("/database/api/nodes", {
+        method: "POST",
+        body: {
+          parentId: node.id,
+          kind: newKind,
+          name,
+          ...(newDesc.trim() !== "" ? { description: newDesc.trim() } : {}),
+        },
+      });
+      toastOk("已创建");
+      showCreateChild = false;
+      newName = ""; newKind = "FOLDER"; newDesc = "";
+      bumpTree();
+    } catch (e) {
+      toastErr(e instanceof Error ? e.message : String(e));
+    }
+  }
+
+  async function renameNode(): Promise<void> {
+    if (node === null) return;
+    const name = prompt("新名称", node.name);
+    if (name === null) return;
+    try {
+      await api(`/database/api/nodes/${node.id}`, { method: "PATCH", body: { name } });
+      toastOk("已重命名");
+      bumpTree();
+      currentNode.update((n) => (n ? { ...n, name } : n));
+    } catch (e) {
+      toastErr(e instanceof Error ? e.message : String(e));
+    }
+  }
+
+  async function deleteNode(): Promise<void> {
+    if (node === null || !confirm(`确认删除「${node.name}」?软删除后不可见。`)) return;
+    try {
+      await api(`/database/api/nodes/${node.id}`, { method: "DELETE" });
+      toastOk("已删除");
+      currentNode.set(null);
+      bumpTree();
+    } catch (e) {
+      toastErr(e instanceof Error ? e.message : String(e));
+    }
+  }
+</script>
+
+{#if node === null}
+  <div class="flex h-full items-center justify-center text-[13px] text-ink-3">从左侧选择一个文件夹或项目</div>
+{:else}
+  <div class="mx-auto max-w-[1120px] px-9 py-9">
+    <div class="mb-2 text-[12.5px] text-ink-3">
+      {#each crumbs as c, i (i)}
+        {#if i > 0}<span class="mx-1 text-line">/</span>{/if}
+        <span>{c.name ?? "…"}</span>
+      {/each}
+    </div>
+
+    <div class="mb-5 flex items-center justify-between">
+      <div class="flex items-center gap-2 text-[17px] font-semibold text-ink">
+        {node.name}
+        <span class="tag">{node.kind === "PROJECT" ? "项目" : "文件夹"}</span>
+        <span class="tag !border-line !text-ink-2">{ROLE_LABEL[node.role]}</span>
+      </div>
+      <div class="flex gap-1.5">
+        {#if canEdit && node.kind === "FOLDER"}
+          <button class="btn" onclick={() => (showCreateChild = true)}>
+            <Icon name="plus" size={13} /> 新建子节点
+          </button>
+        {/if}
+        {#if canManage}
+          <button class="btn" onclick={renameNode}><Icon name="pencil" size={13} /> 重命名</button>
+          <button class="btn btn-danger" onclick={deleteNode}><Icon name="trash" size={13} /> 删除</button>
+        {/if}
+      </div>
+    </div>
+
+    <div class="mb-[18px] flex gap-0.5 border-b border-line-soft">
+      {#each tabs as [id, label] (id)}
+        <button
+          class="-mb-px border-b-2 px-3.5 py-2 text-[13px] transition {tab === id
+            ? 'border-accent font-semibold text-ink'
+            : 'border-transparent text-ink-3 hover:text-ink'}"
+          onclick={() => (tab = id)}
+        >{label}</button>
+      {/each}
+    </div>
+
+    {#if tab === "grants"}
+      <GrantsPanel {node} />
+    {:else if tab === "files" && node.kind === "PROJECT"}
+      <FilesPanel {node} />
+    {:else}
+      <OverviewPanel {node} />
+      {#if node.kind === "FOLDER"}
+        <div class="quiet mt-3.5">文件夹是透明组织节点,点左侧树展开以浏览子内容。</div>
+      {/if}
+    {/if}
+  </div>
+{/if}
+
+{#if showCreateChild && node}
+  <Modal title="新建子节点" onclose={() => (showCreateChild = false)}>
+    <div class="form-row">
+      <label class="form-label" for="child-name">名称</label>
+      <input id="child-name" class="input" bind:value={newName} placeholder="例如:物理必修一" />
+    </div>
+    <div class="form-row">
+      <label class="form-label" for="child-kind">类型</label>
+      <select id="child-kind" class="select" bind:value={newKind}>
+        <option value="FOLDER">文件夹</option>
+        <option value="PROJECT">项目(课程资源库)</option>
+      </select>
+    </div>
+    <div class="form-row">
+      <label class="form-label" for="child-desc">简介(可选)</label>
+      <textarea id="child-desc" rows="3" class="textarea" bind:value={newDesc} placeholder="简要说明用途…"></textarea>
+    </div>
+    <div class="mt-4 flex justify-end gap-2">
+      <button class="btn" onclick={() => (showCreateChild = false)}>取消</button>
+      <button class="btn btn-primary" onclick={createChild}>创建</button>
+    </div>
+  </Modal>
+{/if}

hub/filelib-web/src/lib/OverviewPanel.svelte

@@ -0,0 +1,156 @@
+<script lang="ts">
+  import { api } from "./api.js";
+  import { toastOk, toastErr } from "./stores.js";
+  import { currentNode } from "./browser.js";
+  import { ROLE_LABEL } from "./labels.js";
+  import type { ExportJob, NodeDetail } from "./types.js";
+  import Modal from "./Modal.svelte";
+
+  let { node }: { node: NodeDetail } = $props();
+
+  let showEditDesc = $state(false);
+  let descDraft = $state("");
+  let exportJob = $state<ExportJob | null>(null);
+
+  const canEdit = $derived(node.role === "MANAGE" || node.role === "EDIT");
+  const canManage = $derived(node.role === "MANAGE");
+  const roleLabel = $derived(ROLE_LABEL[node.role]);
+
+  /** 独立权限开关(仅 PROJECT;关闭时只继承父级权限,创建者除外)。 */
+  async function toggleIndependent(): Promise<void> {
+    try {
+      await api(`/database/api/projects/${node.id}/independent-permission`, {
+        method: "PUT",
+        body: { enabled: !node.independentPermission },
+      });
+      toastOk("已切换");
+      currentNode.update((n) =>
+        n !== null && n.id === node.id ? { ...n, independentPermission: !node.independentPermission } : n,
+      );
+    } catch (e) {
+      toastErr(e instanceof Error ? e.message : String(e));
+    }
+  }
+
+  $effect(() => {
+    void node.id;
+    exportJob = null;
+  });
+
+  function openEditDesc(): void {
+    descDraft = node.description ?? "";
+    showEditDesc = true;
+  }
+
+  async function saveDesc(): Promise<void> {
+    const description = descDraft.trim();
+    try {
+      await api(`/database/api/nodes/${node.id}`, {
+        method: "PATCH",
+        body: { description: description === "" ? null : description },
+      });
+      toastOk("简介已保存");
+      showEditDesc = false;
+      const next = description === "" ? null : description;
+      currentNode.update((n) => (n && n.id === node.id ? { ...n, description: next } : n));
+    } catch (e) {
+      toastErr(e instanceof Error ? e.message : String(e));
+    }
+  }
+
+  async function submitExport(): Promise<void> {
+    try {
+      const r = await api<{ jobId: string; status: string }>(`/database/api/projects/${node.id}/exports`, {
+        method: "POST",
+        body: { target: "manifest" },
+      });
+      toastOk("导出已提交");
+      void pollExport(r.jobId);
+    } catch (e) {
+      toastErr(e instanceof Error ? e.message : String(e));
+    }
+  }
+
+  async function pollExport(jobId: string): Promise<void> {
+    for (;;) {
+      await new Promise((r) => setTimeout(r, 800));
+      try {
+        const job = await api<ExportJob>(`/database/api/exports/${jobId}`);
+        exportJob = job;
+        if (job.status === "DONE" || job.status === "FAILED") break;
+      } catch {
+        break;
+      }
+    }
+  }
+</script>
+
+<div class="panel">
+  <div class="mb-4">
+    <div class="mb-1.5 text-[11.5px] text-ink-3">简介</div>
+    <div class="text-[13.5px] leading-7 text-ink">
+      {#if node.description}
+        {node.description}
+      {:else}
+        <span class="italic text-ink-3">暂无简介</span>
+      {/if}
+      {#if canEdit}
+        <button class="btn ml-2.5 !px-2.5 !py-0.5 align-middle !text-[11.5px]" onclick={openEditDesc}>编辑</button>
+      {/if}
+    </div>
+  </div>
+
+  <div class="my-4 border-t border-line-soft"></div>
+
+  <div class="flex flex-col gap-1.5 text-[13px] text-ink-2">
+    <div>类型 <b class="font-semibold text-ink">{node.kind === "PROJECT" ? "项目" : "文件夹"}</b></div>
+    <div>我的角色 <b class="font-semibold text-ink">{roleLabel}</b></div>
+    <div>创建时间 <b class="font-semibold text-ink">{new Date(node.createdAt).toLocaleString("zh-CN")}</b></div>
+    <div>更新时间 <b class="font-semibold text-ink">{new Date(node.updatedAt).toLocaleString("zh-CN")}</b></div>
+  </div>
+
+  <!-- 独立权限与导出都只对 PROJECT 有意义(FOLDER 是透明组织节点,ADR-0021)。 -->
+  {#if node.kind === "PROJECT"}
+    <div class="my-4 border-t border-line-soft"></div>
+    <div class="flex flex-wrap items-center gap-2.5">
+      <span class="quiet">独立权限</span>
+      <b class="text-[13px]">{node.independentPermission ? "开启" : "关闭"}</b>
+      {#if canManage}
+        <button class="btn" onclick={toggleIndependent}>{node.independentPermission ? "关闭" : "开启"}</button>
+      {/if}
+      <span class="quiet">关闭时仅继承父级权限(创建者除外)</span>
+    </div>
+
+    <div class="my-4 border-t border-line-soft"></div>
+
+    <div class="section-title mb-2">导出</div>
+    <div class="flex items-center gap-2">
+      <select class="select !w-auto"><option value="manifest">manifest(stub)</option></select>
+      <button class="btn" onclick={submitExport}>开始导出</button>
+      {#if exportJob}
+        <span class="file-meta">
+          {#if exportJob.status === "DONE"}
+            完成 · <a class="text-accent underline" href="/database/api/exports/{exportJob.id}/download">下载</a>
+          {:else if exportJob.status === "FAILED"}
+            失败:{exportJob.error ?? ""}
+          {:else}
+            {exportJob.status}…
+          {/if}
+        </span>
+      {/if}
+    </div>
+  {/if}
+</div>
+
+{#if showEditDesc}
+  <Modal title="编辑简介" onclose={() => (showEditDesc = false)}>
+    <div class="form-row">
+      <label class="form-label" for="desc-draft">简要说明这个项目的内容</label>
+      <textarea id="desc-draft" rows="5" class="input !leading-7" bind:value={descDraft} placeholder="例如:高中物理必修一第三章,表面张力相关内容……"></textarea>
+    </div>
+    <div class="mt-4 flex justify-end gap-2">
+      <button class="btn" onclick={() => (showEditDesc = false)}>取消</button>
+      <button class="btn btn-primary" onclick={saveDesc}>保存</button>
+    </div>
+  </Modal>
+{/if}