feat(database): init database folder frontend and permission

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

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

.omo/run-continuation/ses_0705f8afbffePWIq7GrFfwfFwV.json

@@ -0,0 +1,10 @@
+{
+  "sessionID": "ses_0705f8afbffePWIq7GrFfwfFwV",
+  "updatedAt": "2026-07-23T15:40:15.630Z",
+  "sources": {
+    "background-task": {
+      "state": "idle",
+      "updatedAt": "2026-07-23T15:40:15.630Z"
+    }
+  }
+}

.omo/run-continuation/ses_07252990dffeRFmXnvdyynty2z.json

@@ -0,0 +1,10 @@
+{
+  "sessionID": "ses_07252990dffeRFmXnvdyynty2z",
+  "updatedAt": "2026-07-23T06:33:33.086Z",
+  "sources": {
+    "background-task": {
+      "state": "idle",
+      "updatedAt": "2026-07-23T06:33:33.086Z"
+    }
+  }
+}

.omo/run-continuation/ses_075d214a0ffe6mU8VNgukUfH5L.json

@@ -0,0 +1,10 @@
+{
+  "sessionID": "ses_075d214a0ffe6mU8VNgukUfH5L",
+  "updatedAt": "2026-07-22T14:15:01.741Z",
+  "sources": {
+    "background-task": {
+      "state": "idle",
+      "updatedAt": "2026-07-22T14:15:01.741Z"
+    }
+  }
+}

.omo/run-continuation/ses_075d3282bffejz0HFE00taOaGM.json

@@ -0,0 +1,10 @@
+{
+  "sessionID": "ses_075d3282bffejz0HFE00taOaGM",
+  "updatedAt": "2026-07-22T14:13:54.785Z",
+  "sources": {
+    "background-task": {
+      "state": "idle",
+      "updatedAt": "2026-07-22T14:13:54.785Z"
+    }
+  }
+}

.omo/run-continuation/ses_0781484caffeKJHXVKiD4BqEJw.json

@@ -0,0 +1,10 @@
+{
+  "sessionID": "ses_0781484caffeKJHXVKiD4BqEJw",
+  "updatedAt": "2026-07-22T06:17:18.238Z",
+  "sources": {
+    "background-task": {
+      "state": "idle",
+      "updatedAt": "2026-07-22T06:17:18.238Z"
+    }
+  }
+}

.omo/run-continuation/ses_07b163c13ffeudULxSfIfK986T.json

@@ -0,0 +1,10 @@
+{
+  "sessionID": "ses_07b163c13ffeudULxSfIfK986T",
+  "updatedAt": "2026-07-21T13:55:58.878Z",
+  "sources": {
+    "background-task": {
+      "state": "idle",
+      "updatedAt": "2026-07-21T13:55:58.878Z"
+    }
+  }
+}

.omo/run-continuation/ses_07b1e6c8effeq7bdmj6NgO0LqC.json

@@ -0,0 +1,10 @@
+{
+  "sessionID": "ses_07b1e6c8effeq7bdmj6NgO0LqC",
+  "updatedAt": "2026-07-21T13:38:01.132Z",
+  "sources": {
+    "background-task": {
+      "state": "idle",
+      "updatedAt": "2026-07-21T13:38:01.132Z"
+    }
+  }
+}

.omo/run-continuation/ses_07b932dddffecSipFLwlJOvoJ9.json

@@ -0,0 +1,10 @@
+{
+  "sessionID": "ses_07b932dddffecSipFLwlJOvoJ9",
+  "updatedAt": "2026-07-21T11:27:10.420Z",
+  "sources": {
+    "background-task": {
+      "state": "idle",
+      "updatedAt": "2026-07-21T11:27:10.420Z"
+    }
+  }
+}

.omo/run-continuation/ses_07b9c4268ffeic4mMXCPUt225j.json

@@ -0,0 +1,10 @@
+{
+  "sessionID": "ses_07b9c4268ffeic4mMXCPUt225j",
+  "updatedAt": "2026-07-21T11:18:53.449Z",
+  "sources": {
+    "background-task": {
+      "state": "idle",
+      "updatedAt": "2026-07-21T11:18:53.449Z"
+    }
+  }
+}

.omo/run-continuation/ses_07b9c4346ffeVBdV5pf4h6s9PW.json

@@ -0,0 +1,10 @@
+{
+  "sessionID": "ses_07b9c4346ffeVBdV5pf4h6s9PW",
+  "updatedAt": "2026-07-21T11:18:29.979Z",
+  "sources": {
+    "background-task": {
+      "state": "idle",
+      "updatedAt": "2026-07-21T11:18:29.979Z"
+    }
+  }
+}

.omo/run-continuation/ses_07b9c9a75ffeOyJ4ewp3DBvXhz.json

@@ -0,0 +1,10 @@
+{
+  "sessionID": "ses_07b9c9a75ffeOyJ4ewp3DBvXhz",
+  "updatedAt": "2026-07-21T11:21:09.776Z",
+  "sources": {
+    "background-task": {
+      "state": "idle",
+      "updatedAt": "2026-07-21T11:21:09.776Z"
+    }
+  }
+}

.omo/run-continuation/ses_07cdbac0effeiBrdcHLUUUfwuF.json

@@ -0,0 +1,10 @@
+{
+  "sessionID": "ses_07cdbac0effeiBrdcHLUUUfwuF",
+  "updatedAt": "2026-07-23T15:37:59.918Z",
+  "sources": {
+    "background-task": {
+      "state": "idle",
+      "updatedAt": "2026-07-23T15:37:59.918Z"
+    }
+  }
+}

.omo/文件库-开工计划.md

@@ -0,0 +1,114 @@
+# 文件库 · 开工计划（v1.0）
+
+> 配套文档：《文件库-接口契约.md》(v0.1，仓库根目录)。本计划已吸收规划顾问评审意见，包含开工前必须先冻结的**架构收口决策 D11–D19**（回写契约 v0.2 时并入）。
+> 工期按 1 人全栈估算；前端从 Phase 2 后可并行。
+
+## 开工判定
+
+**可以开工。** 四个外部依赖（版本包 / Group / 审计 / 平台身份）全部有契约可依、可 mock 并行开发；无阻塞项。唯一前置：本文件的 D11–D19 决策在写第一行 schema 前过一遍（半天，自查即可，有异议再升级）。
+
+## 架构收口决策（新增，先冻结再动工）
+
+| 编号 | 决策 | 理由 |
+|---|---|---|
+| D11 | `creator` 是 Node 的**不可变列**，创建时同时落一条 Manage grant；独立权限开关关闭时，**creator 的 Manage 仍生效**，其余项目级 grant 冻结不参与计算 | 否则 creator 可能被自己关掉的开关锁死 |
+| D12 | 移动节点授权 = **本节点 Manage + 目标父 Edit+**；移动在事务 + Postgres 咨询锁内完成，防并发成环 | 预检环检测在并发下不安全 |
+| D13 | Group resolve 失败返回 **503**（不伪装 404/403）；每次 HTTP 请求 fresh resolve，不跨请求缓存；单请求内多次校验合并为一次调用（此点与 Group 团队确认，OPEN-9） | 依赖故障 ≠ 无权限；契约 G4 要求实时 |
+| D14 | 命名规则：NFC 归一化、trim、≤128 字符、禁 `/` 与控制字符；**活跃兄弟节点大小写不敏感唯一**；根节点全局唯一 | 缺命名规则必有脏数据 |
+| D15 | 删除 = 只给被删节点打标，后代**不递归打标**，靠"任一祖先已删"过滤；所有查询链路强制此过滤（含递归 SQL，不只靠 Prisma middleware） | 递归打标的写放大与恢复复杂度不可控 |
+| D16 | `baseVersion` 为**文件级版本**（GET file 返回的 version）；无关文件的提交不产生冲突 | 与 C1 `head(dir, filePath)` 语义一致 |
+| D17 | breadcrumb 只暴露用户有 View 的祖先名称；无权限祖先显示占位符 `…`，不暴露名字 | 404 不泄露语义（D8）延伸到面包屑 |
+| D18 | v1 **单副本部署**（git 仓库在本地磁盘）；多副本需共享存储或分片，后置 | 不解决不存在的扩展问题 |
+| D19 | 网站管理员**不隐式读内容**；force_adjust 凭 node id 操作（id 从审计或用户上报获得） | C4 已定的最小权限原则 |
+
+## 阶段计划
+
+### Phase 0 · 骨架与身份先行（1–2 天）
+
+- [ ] 过 D11–D19，回写契约 v0.2
+- [ ] repo 骨架 `server/` + `web/`，Postgres docker-compose，CI（lint / typecheck / vitest / 集成测试用真实 Postgres service container）
+- [ ] **JWT 中间件 + 本地 JWKS 测试服务 + 签名 token fixtures**（有效/过期/错 issuer/错 audience/错算法/未知 kid/轮换）——身份先行，不做"宽松 mock 身份"
+- [ ] 4 个 port 接口定义 + mock：`VersionStore`、`GroupResolver`、`AuditSink`（直写 outbox 表的实现就是真的，mock 的是对端服务）、`ExportAdapter`
+- [ ] fastify-swagger 接入，OpenAPI 骨架——**OpenAPI 随每个端点同步产出，不留到最后**
+- **验收**：骨架可 `pnpm dev` 起服务；本地 JWKS 六类 token fixture（有效/过期/错 issuer/错 audience/错算法/未知 kid）中间件行为全对；CI 流水线绿
+
+### Phase 1 · 数据模型与权限引擎（2–3 天）⚑ 心脏
+
+- [ ] Prisma schema：`Node`（parentId **权威** + id 编码的 materialized path 派生列，name 不入 path）、`Grant`、`ProjectIndependentSettings`、`OutboxEvent`（含 attempts/nextAttemptAt/lease/lastError，relay 字段一次到位）、`ExportJob`
+- [ ] 数据库约束：kind 枚举、项目无子节点、活跃兄弟名唯一（部分唯一索引，root 的 NULL parent 特殊处理）、活跃 grant 按 (nodeId, principalType, principalId) 唯一、独立设置仅项目
+- [ ] **纯权限 reducer**：输入已解析的 grants + 祖先链 + 用户组集合，输出 role|null；不碰 DB/网络。fast-check 属性测试：max 单调、加 grant 只升不降、祖先继承、toggle 行为、顺序无关、软删过滤
+- [ ] 数据获取层 + `effective(user, node)` 组装
+- [ ] 树操作服务：create（creator 自动 Manage、root 仅管理员且必带 ≥1 Manage）、rename、move（D12 事务+咨询锁）、soft delete（D15）、breadcrumb（D17）
+- **验收**：并发对移（A→B 与 B→A）、移动+并发建子、property tests、删除祖先过滤，真实 Postgres 全绿
+
+### Phase 2 · 树与授权 API（1–2 天）
+
+- [ ] nodes 端点组 + grants 端点组 + independent-permission 开关 + effective-permission 自查
+- [ ] 授权矩阵校验（契约 8.1：creator-only 授 Manage、Manage 不可动 creator、force_adjust 独立通道）
+- [ ] 全部写操作落 outbox 事件（C3 词汇表）
+- **验收**：契约 8.1 矩阵逐格 API 测试；D8 的 404/403/503 三分语义测试
+
+### Phase 3 · 仓库生命周期与文件 API（2 天）
+
+- [ ] 项目 provisioning 状态机 `PROVISIONING → READY | FAILED`：先建 DB 行（PROVISIONING）→ 调 `VersionStore.init`（幂等）→ 置 READY；失败可重试；孤儿仓库对账 job
+- [ ] 每项目写锁（Postgres 咨询锁，跨进程安全）——不假设版本包能跨进程串行
+- [ ] 路径安全：canonical 后必须落在项目根内、拒绝 `.git`、禁 symlink 逃逸、路径长度上限
+- [ ] 上传限额（单文件 10MB / 单项目配额，数值 OPEN-5）+ 流式接收
+- [ ] files 端点组全量（list/read/upload/commits→409/diff/history/delete）+ 双客户端冲突 e2e
+- **验收**：DB/git 故障注入（init 失败、提交后崩溃）→ 对账能收敛；路径穿越语料库测试全拒
+
+### Phase 4 · 外部集成（1–2 天）
+
+- [ ] `GroupResolver` HTTP client：超时/5xx/429/畸形 JSON/万级 group 的故障注入测试；失败 → 503（D13）
+- [ ] Audit relay worker：租约领取、指数退避、eventId 幂等、重启恢复、积压告警
+- [ ] 导出 job：状态机 + 轮询 + 下载权限校验；`ExportAdapter` 桩（参数 OPEN-6 未定前**不计入完成标准**）
+- **验收**：relay 重启不丢不重（对端幂等）；group 故障时写操作 503、读操作按 D13
+
+### Phase 5 · 前端（3–5 天，Phase 2 后并行启动）
+
+- [ ] 登录（平台 SSO 占位 + 本地 JWKS 直通开关）
+- [ ] 树浏览（懒加载 + 分页）、breadcrumb（D17 占位符）、创建对话框（类型 + 批量授权选择器，Group search 接 C2）
+- [ ] 权限管理面板（按 8.1 矩阵控制可选项，creator 标识）
+- [ ] 文件页：查看/上传/下载/历史列表（编辑 UI 不归我方，留对接位）
+- [ ] 导出按钮 + job 轮询
+- **验收**：无权限节点全链路不可见；授权面板不会送出矩阵禁止的组合
+
+### Phase 6 · 硬化与交付（1–2 天）
+
+- [ ] 404/403/503 全端点核对；并发与重试幂等抽查
+- [ ] 备份脚本（DB + git 仓库一致性快照）、健康检查（DB/JWKS/磁盘/Group）、磁盘水位告警
+- [ ] OpenAPI 终稿 + 部署脚本 + 一页运维手册
+
+## 里程碑
+
+| 里程碑 | 内容 | 累计工期 |
+|---|---|---|
+| M1 | Phase 0–1：骨架 + 权限引擎 + 树操作可跑 | ~4 天 |
+| M2 | Phase 2–3：后端 API 全量（含文件冲突流） | ~7 天 |
+| M3 | Phase 4：外部集成（导出不计） | ~9 天 |
+| M4 | Phase 5–6：前端 + 硬化，可交付 | ~14–18 天 |
+
+## Mock 保真红线（mock 可以顶，但不许骗）
+
+| Mock | 不许掩盖的事 | 真身到位后的契约测试 |
+|---|---|---|
+| VersionStore | 磁盘延迟、半初始化、锁残留、跨进程并发 | 真包跑临时仓库：并发 commit/init 重试/遍历与 symlink 语料 |
+| GroupResolver | 超时、5xx、畸形响应、大规模组集 | 故障注入 HTTP 桩全过；我方绝不自己推祖先 |
+| GroupSearch（前端选择器） | 与 resolve 是**两个独立端点**，不可用 resolve mock 顶替 | C2 `/groups/search` 真身到位后跑分页/空结果/超时 |
+| Audit 对端 | 重复投递、乱序、长时间不可用 | relay 重启恢复 + 对端幂等 |
+| JWT | issuer/audience/算法/轮换 | 本地 JWKS 全用例 |
+| ExportAdapter | 参数、幂等、耗时 | 参数定了再写，之前不算完成 |
+
+## Top 5 风险
+
+1. **DB/git 分裂**（崩溃导致元数据、仓库、审计三边不一致）→ provisioning 状态机 + 对账 job，Phase 3 前置
+2. **移动子树改变整树权限** → D12 事务+锁+源目标双授权，并发测试
+3. **creator/独立权限开关交互** → D11 先冻结
+4. **外部契约缺口**（导出参数、请求内 resolve 合并）→ OPEN 清单跟踪，mock 保真红线不许掩盖
+5. **存储滥用/路径逃逸** → 路径安全 + 配额进 Phase 3 验收，不拖到硬化
+
+## OPEN 清单（在契约文档基础上增补）
+
+- OPEN-9：单请求内合并多次 resolve 是否符合 G4"实时"语义（找 Group 团队确认）
+- OPEN-10：恶意软件扫描归属（我方/平台/不做）
+- 其余 OPEN-1~8 见《文件库-接口契约.md》第 10 节

.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,29 +1,25 @@
 # 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
@@ -44,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 写操作前与开发者确认(这是开发者的全局偏好)。

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/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,6 +66,9 @@ Educraft 机器人以应用身份调用上述 API，因此这些 scope 全部放
 
 如果 API 调试台提示缺少更细粒度权限，请把错误提示和发生时间截图给部署人员。不要自行开通通讯录全量读取等超出本表的权限。
 
+说明：`im:resource` 既用于下载用户发来的图片/文件，也用于 Agent 回复时把本地或远程图片上传为飞书 `image_key` 后嵌入消息卡片。缺少该权限时，带图回答会发送失败或降级为无图文本。已开通该 scope 的存量应用一般无需新增权限，但若权限尚未随最新版本发布，请创建新版本并审核发布。
+
+
 ## 4. 配置事件与卡片回调
 
 进入“事件与回调”。

hub/.gitignore

@@ -5,6 +5,9 @@ dist/
 .env.*
 !.env.example
 .secrets/
+.dev-keyring.json
+.dev-workspaces/
+.dev-skills/
 admin-web/node_modules/
 admin-web/build/
 admin-web/.svelte-kit/

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

@@ -193,13 +193,81 @@ export interface ProjectUsageRow extends UsageTotals {
 	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'
@@ -353,6 +421,8 @@ export const api = {
 		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);
@@ -361,6 +431,16 @@ export const api = {
 		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[] }>,

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

@@ -33,7 +33,7 @@
 <div class="space-y-0.5">
 	{#each childProjects as p (p.id)}
 		<a
-			href={`/admin/org/${slug}/projects/${p.id}`}
+			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">

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

@@ -29,6 +29,52 @@ 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;

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

@@ -35,12 +35,9 @@ export async function loadSession(): Promise<void> {
 /**
  * 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 path = window.location.pathname.split('/').filter(Boolean);
-	if (path[0] === 'admin' && path[1] === 'org' && path[2]) {
-		return decodeURIComponent(path[2]);
-	}
 	const q = new URLSearchParams(window.location.search).get('org');
 	if (q && q.trim() !== '') return q.trim();
 
@@ -48,6 +45,12 @@ export function resolveLoginOrgSlug(): string | null {
 	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;
 }
 

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

@@ -5,6 +5,7 @@
 	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';
@@ -20,6 +21,7 @@
 
 	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 },
@@ -31,66 +33,49 @@
 		{ key: 'capabilities', label: '能力', icon: 'provider' as const },
 	];
 
-	function isAdmin(org: OrgMembership): boolean {
-		const role = String(org.role ?? '').toUpperCase();
-		return role === 'OWNER' || role === 'ADMIN';
-	}
-
-	function orgSlugFromPath(): string | null {
-		const parts = page.url.pathname.split('/').filter(Boolean);
-		if (parts[0] === 'admin' && parts[1] === 'org' && parts[2]) {
-			return decodeURIComponent(parts[2]);
-		}
-		return null;
-	}
-
-	function isOnProjectRoute(): boolean {
-		const parts = page.url.pathname.split('/').filter(Boolean);
-		return parts[0] === 'admin' && parts[1] === 'org' && parts[3] === 'projects';
-	}
-
 	function memberships(): OrgMembership[] {
 		return $session.me?.organizations ?? [];
 	}
 
 	function adminOrgs(): OrgMembership[] {
-		return memberships().filter(isAdmin);
+		return memberships().filter((o) => isOrgAdmin(o));
 	}
 
 	function currentOrg(): OrgMembership | null {
-		const slug = orgSlugFromPath();
-		if (!slug) return null;
-		return memberships().find((o) => o.slug === slug) ?? null;
+		return resolveOrg($session.me, page.url.search);
 	}
 
-	function pickHomeOrg(): OrgMembership | null {
-		const admin = adminOrgs()[0];
-		if (admin) return admin;
-		return memberships()[0] ?? null;
+	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' || parts[1] !== 'org' || !parts[2]) return '';
-		return parts[3] ?? 'overview';
+		if (parts[0] !== 'admin') return '';
+		// /admin → overview; /admin/usage → usage; /admin/projects/x → projects
+		return parts[1] ?? 'overview';
 	}
 
 	function navHref(key: string): string {
-		const slug = currentOrg()?.slug ?? pickHomeOrg()?.slug;
-		if (!slug) return '/';
-		if (key === 'overview') return `/admin/org/${slug}`;
-		return `/admin/org/${slug}/${key}`;
+		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;
-		void goto(`/admin/org/${nextSlug}`);
+		// 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) {
@@ -113,33 +98,23 @@
 	$effect(() => {
 		if ($session.loading || !$session.me) return;
 
-		const slug = orgSlugFromPath();
-		const matched = slug ? memberships().find((o) => o.slug === slug) : null;
+		const path = page.url.pathname;
+		// Legacy /admin/org/:slug… is handled by admin/org/[...path] page.
 
-		// Org admins: route to their first admin org if none matched as admin.
+		const org = currentOrg();
 		const admins = adminOrgs();
-		if (matched && isAdmin(matched)) {
+
+		if (org && isOrgAdmin(org)) {
 			redirecting = false;
 			return;
 		}
-		if (!matched && admins.length > 0) {
-			const target = `/admin/org/${admins[0].slug}`;
-			if (page.url.pathname !== target && !page.url.pathname.startsWith(`${target}/`)) {
-				redirecting = true;
-				void goto(target, { replaceState: true });
-			}
-			return;
-		}
 
-		// Members (non-admin): project pages are open to project MANAGE holders;
-		// the org overview and other admin-only surfaces are not for them.
-		if (matched && !isAdmin(matched)) {
+		// Member only: allow project routes; bounce admin-only surfaces to projects.
+		if (org && !isOrgAdmin(org)) {
 			redirecting = false;
-			const parts = page.url.pathname.split('/').filter(Boolean);
-			const onOverview = parts.length === 3; // /admin/org/:slug
-			if (onOverview) {
-				const target = `/admin/org/${matched.slug}/projects`;
-				if (page.url.pathname !== target) {
+			if (!isOnProjectRoute()) {
+				const target = adminPath('projects');
+				if (path !== target) {
 					redirecting = true;
 					void goto(target, { replaceState: true });
 				}
@@ -147,12 +122,11 @@
 			return;
 		}
 
-		// No matched org and no admin orgs: route a member to their first org's
-		// projects page so they can reach project MANAGE surfaces.
-		if (!matched && memberships().length > 0) {
-			const home = memberships()[0];
-			const target = `/admin/org/${home.slug}/projects`;
-			if (page.url.pathname !== target && !page.url.pathname.startsWith(`${target}/`)) {
+		// 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 });
 			}
@@ -173,14 +147,14 @@
 					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">{redirecting ? '正在进入组织…' : '正在加载会话…'}</p>
+			<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-4 flex h-12 w-12 items-center justify-center border border-error-300 bg-error-100 text-error-700 font-bold"
+				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>
@@ -193,7 +167,7 @@
 	<div class="saas-status-panel">
 		<div class="saas-status-card">
 			<div
-				class="mx-auto mb-5 flex h-12 w-12 items-center justify-center border border-primary-700 bg-primary-600 text-white font-bold"
+				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>
@@ -202,7 +176,7 @@
 			<button class="saas-btn-primary w-full" onclick={() => redirectToLogin()}>使用飞书登录</button>
 		</div>
 	</div>
-{:else if currentOrg() && isAdmin(currentOrg()!)}
+{:else if currentOrg() && isOrgAdmin(currentOrg()!)}
 	{@const org = currentOrg()!}
 	{@const me = $session.me!}
 	<div class="saas-shell">
@@ -227,17 +201,19 @@
 				</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">Curriculum Hub</div>
+					<div class="truncate text-xs text-surface-600">{org.name}</div>
 				</div>
 			</div>
 
-			<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" />
-					组织
+			{#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>
-				<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>
@@ -307,13 +283,13 @@
 			</main>
 		</div>
 	</div>
-{:else if currentOrg() && !isAdmin(currentOrg()!) && isOnProjectRoute()}
+{: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={`/admin/org/${org.slug}/projects`} class="saas-btn-ghost px-2!" aria-label="返回项目列表">
+				<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">
@@ -342,7 +318,7 @@
 			</main>
 		</div>
 	</div>
-{:else if currentOrg() && !isAdmin(currentOrg()!)}
+{:else if currentOrg() && !isOrgAdmin(currentOrg()!)}
 	{@const denied = currentOrg()!}
 	<div class="saas-status-panel">
 		<div class="saas-status-card">
@@ -351,7 +327,7 @@
 				组织 <strong>{denied.name}</strong>（/{denied.slug}）中你的角色是
 				<span class="saas-badge-neutral mx-1">{orgRoleLabel(denied.role)}</span>。普通成员仅可访问自己有授权的项目。
 			</p>
-			<a class="saas-btn-primary" href={`/admin/org/${denied.slug}/projects`}>查看我的项目</a>
+			<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">
@@ -362,14 +338,14 @@
 		</div>
 	</div>
 {:else if memberships().length > 0}
-	{@const denied = pickHomeOrg()!}
+	{@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={`/admin/org/${denied.slug}/projects`}>立即进入</a>
+			<a class="saas-btn-primary" href={adminPath('projects')}>立即进入</a>
 			<button class="saas-btn-ghost mt-3" onclick={handleLogout}>退出登录</button>
 		</div>
 	</div>

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

@@ -11,7 +11,7 @@
 			return r === 'OWNER' || r === 'ADMIN';
 		});
 		const target = admin ?? me.organizations[0];
-		return target ? `/admin/org/${target.slug}` : null;
+		return target ? `/admin` : null;
 	}
 
 	onMount(() => {

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

@@ -2,6 +2,7 @@
 	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';
@@ -10,7 +11,8 @@
 	import SwitchControl from '$lib/components/SwitchControl.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';
 
-	let orgSlug = $derived(page.params.slug ?? '');
+	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);
@@ -94,19 +96,56 @@
 	<div class="mb-4 flex items-end justify-between gap-3">
 		<div>
 			<h2 class="saas-section-title">用量概览</h2>
-			<p class="saas-muted">全组织智能体运行汇总</p>
+			<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)} />
+		<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>
@@ -129,7 +168,11 @@
 					<tbody>
 						{#each usage.projects as p}
 							<tr>
-								<td class="font-medium">{p.projectName}</td>
+								<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>

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

@@ -1,6 +1,8 @@
 <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';
@@ -8,7 +10,8 @@
 	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';
 
-	const slug = $derived(page.params.slug ?? '');
+	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 识别）' },

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

@@ -1,13 +1,16 @@
 <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 slug = $derived(page.params.slug ?? '');
+	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> = {

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

@@ -1,6 +1,8 @@
 <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';
@@ -8,7 +10,8 @@
 	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';
 
-	const slug = $derived(page.params.slug ?? '');
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
 
 	let connection = $state<FeishuApplicationConnection | null>(null);
 	let loading = $state(true);

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

@@ -1,6 +1,8 @@
 <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';
@@ -10,7 +12,8 @@
 	import SelectField from '$lib/components/SelectField.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';
 
-	const slug = $derived(page.params.slug ?? '');
+	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(' / ');
 

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

@@ -2,6 +2,7 @@
 	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';
@@ -13,8 +14,8 @@
 	import { fmtDate } from '$lib/format';
 	import { toastError, toastSuccess } from '$lib/toast';
 
-	const slug = $derived(page.params.slug ?? '');
-	const org = $derived(($session.me?.organizations.find((o) => o.slug === slug) as OrgMembership | undefined) ?? null);
+	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);
@@ -87,7 +88,7 @@
 			projectName = '';
 			projectFolder = '';
 			showProjectModal = false;
-			window.location.href = `/admin/org/${slug}/projects/${res.id}`;
+			window.location.href = `/admin/projects/${res.id}`;
 		} catch (err) {
 			toastError(err instanceof Error ? err.message : String(err));
 		}
@@ -207,7 +208,7 @@
 				</thead>
 				<tbody>
 					{#each myProjects as p}
-						<tr class="cursor-pointer" onclick={() => (window.location.href = `/admin/org/${slug}/projects/${p.id}`)}>
+						<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>

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

@@ -7,8 +7,19 @@
 		type TeamRow,
 		type SessionSummary,
 		type ExplorerData,
+		type ProjectUsageReport,
 	} from '$lib/api';
-	import { fmtDate, permissionRoleLabel } from '$lib/format';
+	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';
@@ -18,7 +29,8 @@
 	import Icon from '$lib/components/Icon.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';
 
-	const slug = $derived(page.params.slug ?? '');
+	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}`;
@@ -26,6 +38,7 @@
 	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);
@@ -49,14 +62,18 @@
 			// 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] = await Promise.all([
+			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 ?? '';
 			}
@@ -95,7 +112,7 @@
 		if (!confirm(`归档项目 ${proj?.name}?`)) return;
 		try {
 			await api.archiveProject(slug, projectId);
-			window.location.href = `/admin/org/${slug}/projects`;
+			window.location.href = `/admin/projects`;
 		} catch (err) {
 			toastError(err instanceof Error ? err.message : String(err));
 		}
@@ -156,7 +173,7 @@
 {:else if proj}
 	<div class="mb-2">
 		<a
-			href={`/admin/org/${slug}/projects`}
+			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" />
@@ -269,9 +286,67 @@
 	</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="飞书侧触发智能体后会显示在此。" />
@@ -283,6 +358,7 @@
 							<th>模型</th>
 							<th>运行次数</th>
 							<th>更新</th>
+							<th></th>
 						</tr>
 					</thead>
 					<tbody>
@@ -292,6 +368,14 @@
 								<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>

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

@@ -1,6 +1,8 @@
 <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';
@@ -8,7 +10,8 @@
 	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';
 
-	const slug = $derived(page.params.slug ?? '');
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
 
 	let connections = $state<ProviderConnectionRow[]>([]);
 	let loading = $state(true);

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

@@ -1,6 +1,8 @@
 <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';
@@ -8,7 +10,8 @@
 	import RoleCard from '$lib/components/RoleCard.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';
 
-	const slug = $derived(page.params.slug ?? '');
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
 
 	let roles = $state<AgentRoleRow[]>([]);
 	let models = $state<AgentModelRow[]>([]);

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

@@ -1,6 +1,8 @@
 <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';
@@ -8,7 +10,8 @@
 	import SkillEditor from '$lib/components/SkillEditor.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';
 
-	const slug = $derived(page.params.slug ?? '');
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
 
 	let skills = $state<AgentSkillRow[]>([]);
 	let loading = $state(true);

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

@@ -2,6 +2,8 @@
 	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';
@@ -9,7 +11,8 @@
 	import EmptyState from '$lib/components/EmptyState.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';
 
-	const slug = $derived(page.params.slug ?? '');
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
 
 	let teams = $state<TeamRow[]>([]);
 	let loading = $state(true);

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/filelib-web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>文件库</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

hub/filelib-web/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "filelib-web",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "check": "svelte-check --tsconfig ./tsconfig.json"
+  },
+  "devDependencies": {
+    "@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.svelte

@@ -0,0 +1,30 @@
+<script lang="ts">
+  import { onMount } from "svelte";
+  import { api, UnauthenticatedError } from "./lib/api.js";
+  import { me, authChecked } from "./lib/stores.js";
+  import type { MeResponse } from "./lib/types.js";
+  import LoginView from "./lib/LoginView.svelte";
+  import BrowserShell from "./lib/BrowserShell.svelte";
+  import Toasts from "./lib/Toasts.svelte";
+
+  onMount(async () => {
+    try {
+      me.set(await api<MeResponse>("/database/api/me"));
+    } catch (e) {
+      if (!(e instanceof UnauthenticatedError)) console.error(e);
+      me.set(null);
+    } finally {
+      authChecked.set(true);
+    }
+  });
+</script>
+
+{#if !$authChecked}
+  <div class="flex h-full items-center justify-center text-ink-3">加载中…</div>
+{:else if $me}
+  <BrowserShell />
+{:else}
+  <LoginView />
+{/if}
+
+<Toasts />

hub/filelib-web/src/app.css

@@ -0,0 +1,66 @@
+@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,
+#app {
+  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;
+}
+
+/* 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/lib/BrowserShell.svelte

@@ -0,0 +1,141 @@
+<script lang="ts">
+  import { onMount } from "svelte";
+  import { api } from "./api.js";
+  import { me, toastErr, toastOk } from "./stores.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 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));
+    }
+  }
+
+  async function logout(): Promise<void> {
+    try { await fetch("/auth/logout", { method: "POST", credentials: "same-origin" }); } catch { /* ignore */ }
+    me.set(null);
+  }
+
+  const initial = $derived(($me?.userId ?? "U").slice(0, 1).toUpperCase());
+</script>
+
+<div class="flex h-full">
+  <!-- 侧栏 -->
+  <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="rounded-lg border border-line bg-panel px-2.5 py-1 text-[11.5px] font-medium text-ink transition hover:bg-hover" onclick={() => (showCreateRoot = true)}>
+          + 根目录
+        </button>
+      {/if}
+    </div>
+
+    <div class="flex-1 overflow-y-auto px-2 py-2 text-[13px]">
+      {#if roots === null}
+        <div class="px-3 py-6 text-center text-xs text-ink-3">加载中…</div>
+      {:else if treeError}
+        <div class="px-3 py-6 text-center text-xs text-danger">{treeError}</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>
+
+    <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>
+  </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="mb-3">
+      <label class="mb-1 block text-[11.5px] text-ink-3" for="root-name">名称</label>
+      <input id="root-name" class="w-full rounded-lg border border-line bg-panel px-3 py-2 text-[13px] outline-none focus:border-accent" bind:value={newName} placeholder="例如:物理教研" />
+    </div>
+    <div class="mb-3">
+      <label class="mb-1 block text-[11.5px] text-ink-3" for="root-kind">类型</label>
+      <select id="root-kind" class="w-full rounded-lg border border-line bg-panel px-3 py-2 text-[13px] outline-none focus:border-accent" bind:value={newKind}>
+        <option value="FOLDER">文件夹</option>
+        <option value="PROJECT">项目(课程资源库)</option>
+      </select>
+    </div>
+    <div class="mb-3">
+      <label class="mb-1 block text-[11.5px] text-ink-3" for="root-desc">简介(可选)</label>
+      <textarea id="root-desc" rows="3" class="w-full rounded-lg border border-line bg-panel px-3 py-2 font-mono text-xs outline-none focus:border-accent" bind:value={newDesc} placeholder="简要说明用途…"></textarea>
+    </div>
+    <div class="mt-4 flex justify-end gap-2">
+      <button class="rounded-lg border border-line bg-panel px-3.5 py-1.5 text-[12.5px] font-medium text-ink transition hover:bg-hover" onclick={() => (showCreateRoot = false)}>取消</button>
+      <button class="rounded-lg bg-accent px-3.5 py-1.5 text-[12.5px] font-medium text-white transition hover:bg-accent-hover" onclick={createRoot}>创建</button>
+    </div>
+  </Modal>
+{/if}

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

@@ -0,0 +1,165 @@
+<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";
+
+  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="rounded-xl border border-line-soft bg-panel p-5 text-xs text-danger">{loadError}</div>
+{:else if file}
+  <div class="rounded-xl border border-line-soft bg-panel p-5">
+    <div class="mb-2.5 flex items-center justify-between">
+      <span class="font-mono text-[11px] text-ink-3">{file.path} @ {file.version}</span>
+      <div class="flex items-center gap-2">
+        <a class="rounded-lg border border-line bg-panel px-3 py-1 text-[12px] font-medium text-ink transition hover:bg-hover" href="/database/api/projects/{projectId}/file/raw?path={encodeURIComponent(file.path)}" download>下载</a>
+        <button class="rounded-lg border border-line bg-panel px-3 py-1 text-[12px] font-medium text-ink transition hover:bg-hover" onclick={openHistory}>历史</button>
+        {#if canEdit}
+          <button class="rounded-lg border border-transparent px-3 py-1 text-[12px] font-medium text-danger transition hover:bg-[#A13A3312]" onclick={remove}>删除文件</button>
+        {/if}
+        {#if onclose}
+          <button class="rounded-lg border border-line bg-panel px-2.5 py-1 text-[12px] font-medium text-ink-3 transition hover:bg-hover hover:text-ink" onclick={onclose} title="关闭预览">✕</button>
+        {/if}
+      </div>
+    </div>
+
+    {#if file.encoding === "base64"}
+      <div class="text-xs text-ink-3">二进制文件({file.size} B),不支持在线编辑</div>
+    {:else}
+      <textarea rows="14" class="w-full rounded-lg border border-line bg-panel px-3 py-2 font-mono text-xs leading-7 outline-none focus:border-accent" bind:value={draft} readonly={!canEdit}></textarea>
+    {/if}
+
+    {#if canEdit && file.encoding !== "base64"}
+      <div class="mt-3 flex justify-end">
+        <button class="rounded-lg bg-accent px-3.5 py-1.5 text-[12.5px] font-medium text-white transition hover:bg-accent-hover" 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="rounded-lg border border-line bg-panel px-3 py-1 text-[12px] font-medium text-ink transition hover:bg-hover" onclick={acceptLatest}>载入最新内容</button>
+        </div>
+      </div>
+    {/if}
+  </div>
+{:else}
+  <div class="rounded-xl border border-line-soft bg-panel p-5 text-xs text-ink-3">加载中…</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="rounded-lg border border-line bg-panel px-3 py-1 text-[12px] font-medium text-ink transition hover:bg-hover" onclick={() => (showHistory = false)}>关闭</button>
+    </div>
+  </Modal>
+{/if}

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

@@ -0,0 +1,137 @@
+<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";
+
+  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("");
+  let uploadInput: HTMLInputElement;
+
+  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="rounded-xl border border-line-soft bg-panel p-5">
+  <div class="mb-2 flex items-center justify-between">
+    <div class="text-[13px] font-semibold">项目文件({files?.length ?? 0})</div>
+    {#if canEdit}
+      <div class="flex gap-2">
+        <button class="rounded-lg border border-line bg-panel px-3 py-1.5 text-[12.5px] font-medium text-ink transition hover:bg-hover" onclick={() => (showNewFile = true)}>+ 新建文件</button>
+        <button class="rounded-lg bg-accent px-3 py-1.5 text-[12.5px] font-medium text-white transition hover:bg-accent-hover" onclick={() => uploadInput.click()}>上传文件</button>
+        <input bind:this={uploadInput} type="file" class="hidden" onchange={doUpload} />
+      </div>
+    {/if}
+  </div>
+
+  {#if files === null && loadError === null}
+    <div class="py-5 text-center text-xs text-ink-3">加载中…</div>
+  {:else if loadError}
+    <div class="py-5 text-center text-xs text-danger">{loadError}</div>
+  {:else if files && files.length === 0}
+    <div class="py-5 text-center text-xs text-ink-3">空仓库 · 可新建或上传文件</div>
+  {:else if files}
+    <table class="w-full border-collapse text-[13px]">
+      <tbody>
+        {#each files as f (f.path)}
+          <tr
+            class="cursor-pointer border-t border-line-soft first:border-t-0 {$selectedFilePath === f.path ? 'bg-selected' : 'hover:bg-hover'}"
+            onclick={() => selectedFilePath.set(f.path)}
+          >
+            <td class="py-2 font-mono text-[12.5px] text-ink">{f.path}</td>
+            <td class="py-2 text-right font-mono text-[11px] text-ink-3">{f.size} B</td>
+          </tr>
+        {/each}
+      </tbody>
+    </table>
+  {/if}
+</div>
+
+{#if showNewFile}
+  <Modal title="新建文件" onclose={() => (showNewFile = false)}>
+    <div class="mb-3">
+      <label class="mb-1 block text-[11.5px] text-ink-3" for="nf-path">路径</label>
+      <input id="nf-path" class="w-full rounded-lg border border-line bg-panel px-3 py-2 font-mono text-[13px] outline-none focus:border-accent" bind:value={newPath} placeholder="docs/intro.md" />
+    </div>
+    <div class="mb-3">
+      <label class="mb-1 block text-[11.5px] text-ink-3" for="nf-content">内容</label>
+      <textarea id="nf-content" rows="8" class="w-full rounded-lg border border-line bg-panel px-3 py-2 font-mono text-xs outline-none focus:border-accent" bind:value={newContent} placeholder="内容…"></textarea>
+    </div>
+    <div class="mt-4 flex justify-end gap-2">
+      <button class="rounded-lg border border-line bg-panel px-3.5 py-1.5 text-[12.5px] font-medium text-ink transition hover:bg-hover" onclick={() => (showNewFile = false)}>取消</button>
+      <button class="rounded-lg bg-accent px-3.5 py-1.5 text-[12.5px] font-medium text-white transition hover:bg-accent-hover" onclick={submitNewFile}>创建</button>
+    </div>
+  </Modal>
+{/if}

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

@@ -0,0 +1,47 @@
+<script lang="ts">
+  import { onMount } from "svelte";
+  import { api } from "./api.js";
+
+  interface LoginInfo {
+    orgSlug: string;
+    devLoginEnabled: boolean;
+  }
+
+  let info = $state<LoginInfo | null>(null);
+  let loadFailed = $state(false);
+
+  onMount(async () => {
+    try {
+      info = await api<LoginInfo>("/database/api/login-info");
+    } 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)}"
+        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" 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,144 @@
+<script lang="ts">
+  import { api } from "./api.js";
+  import { currentNode, breadcrumb, bumpTree, clearSelectedFile } from "./browser.js";
+  import { toastOk, toastErr } from "./stores.js";
+  import OverviewPanel from "./OverviewPanel.svelte";
+  import FilesPanel from "./FilesPanel.svelte";
+  import Modal from "./Modal.svelte";
+
+  let tab = $state<"detail" | "files">("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");
+
+  $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-[880px] 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.5 text-[19px] font-semibold text-ink">
+        {node.name}
+        <span class="rounded-full border border-line-soft bg-panel px-2 py-0.5 font-mono text-[10.5px] text-ink-3">{node.kind === "PROJECT" ? "项目" : "文件夹"}</span>
+      </div>
+      <div class="flex gap-2">
+        {#if canEdit && node.kind === "FOLDER"}
+          <button class="rounded-lg border border-line bg-panel px-3 py-1.5 text-[12.5px] font-medium text-ink transition hover:bg-hover" onclick={() => (showCreateChild = true)}>+ 新建</button>
+        {/if}
+        {#if canManage}
+          <button class="rounded-lg border border-line bg-panel px-3 py-1.5 text-[12.5px] font-medium text-ink transition hover:bg-hover" onclick={renameNode}>重命名</button>
+          <button class="rounded-lg border border-transparent px-3 py-1.5 text-[12.5px] font-medium text-danger transition hover:bg-[#A13A3312]" onclick={deleteNode}>删除</button>
+        {/if}
+      </div>
+    </div>
+
+    {#if node.kind === "FOLDER"}
+      <div class="py-7 text-[13px] text-ink-3">点击左侧树展开以浏览子内容</div>
+    {:else}
+      <div class="mb-5 flex gap-1 border-b border-line-soft">
+        {#each [["detail", "概览"], ["files", "文件"]] as [id, label] (id)}
+          <button
+            class="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 as "detail" | "files")}
+          >{label}</button>
+        {/each}
+      </div>
+      {#if tab === "detail"}
+        <OverviewPanel {node} />
+      {:else}
+        <FilesPanel {node} />
+      {/if}
+    {/if}
+  </div>
+{/if}
+
+{#if showCreateChild && node}
+  <Modal title="新建子节点" onclose={() => (showCreateChild = false)}>
+    <div class="mb-3">
+      <label class="mb-1 block text-[11.5px] text-ink-3" for="child-name">名称</label>
+      <input id="child-name" class="w-full rounded-lg border border-line bg-panel px-3 py-2 text-[13px] outline-none focus:border-accent" bind:value={newName} placeholder="例如:物理必修一" />
+    </div>
+    <div class="mb-3">
+      <label class="mb-1 block text-[11.5px] text-ink-3" for="child-kind">类型</label>
+      <select id="child-kind" class="w-full rounded-lg border border-line bg-panel px-3 py-2 text-[13px] outline-none focus:border-accent" bind:value={newKind}>
+        <option value="FOLDER">文件夹</option>
+        <option value="PROJECT">项目(课程资源库)</option>
+      </select>
+    </div>
+    <div class="mb-3">
+      <label class="mb-1 block text-[11.5px] text-ink-3" for="child-desc">简介(可选)</label>
+      <textarea id="child-desc" rows="3" class="w-full rounded-lg border border-line bg-panel px-3 py-2 font-mono text-xs outline-none focus:border-accent" bind:value={newDesc} placeholder="简要说明用途…"></textarea>
+    </div>
+    <div class="mt-4 flex justify-end gap-2">
+      <button class="rounded-lg border border-line bg-panel px-3.5 py-1.5 text-[12.5px] font-medium text-ink transition hover:bg-hover" onclick={() => (showCreateChild = false)}>取消</button>
+      <button class="rounded-lg bg-accent px-3.5 py-1.5 text-[12.5px] font-medium text-white transition hover:bg-accent-hover" onclick={createChild}>创建</button>
+    </div>
+  </Modal>
+{/if}

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

@@ -0,0 +1,123 @@
+<script lang="ts">
+  import { api } from "./api.js";
+  import { toastOk, toastErr } from "./stores.js";
+  import { currentNode } from "./browser.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 roleLabel = $derived(node.role === "MANAGE" ? "可管理" : node.role === "EDIT" ? "可编辑" : "只读");
+
+  $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="rounded-xl border border-line-soft bg-panel p-5">
+  <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="ml-2.5 rounded-lg border border-line bg-panel px-2.5 py-0.5 align-middle text-[11.5px] text-ink transition hover:bg-hover" 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">{roleLabel}</b></div>
+    <div>创建时间 <b class="font-semibold text-ink">{new Date(node.createdAt).toLocaleDateString("zh-CN", { year: "numeric", month: "long", day: "numeric" })}</b></div>
+    <div>最近修改 <b class="font-semibold text-ink">{new Date(node.updatedAt).toLocaleDateString("zh-CN", { year: "numeric", month: "long", day: "numeric" })}</b></div>
+  </div>
+
+  <div class="my-4 border-t border-line-soft"></div>
+
+  <div class="mb-2 text-[12.5px] font-semibold">导出</div>
+  <div class="flex items-center gap-2">
+    <button class="rounded-lg border border-line bg-panel px-3 py-1.5 text-[12.5px] font-medium text-ink transition hover:bg-hover" onclick={submitExport}>开始导出</button>
+    {#if exportJob}
+      <span class="font-mono text-[11px] text-ink-3">
+        {#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>
+</div>
+
+{#if showEditDesc}
+  <Modal title="编辑简介" onclose={() => (showEditDesc = false)}>
+    <div class="mb-3">
+      <label class="mb-1 block text-[11.5px] text-ink-3" for="desc-draft">简要说明这个项目的内容</label>
+      <textarea id="desc-draft" rows="5" class="w-full rounded-lg border border-line bg-panel px-3 py-2 text-[13px] leading-7 outline-none focus:border-accent" bind:value={descDraft} placeholder="例如:高中物理必修一第三章,表面张力相关内容……"></textarea>
+    </div>
+    <div class="mt-4 flex justify-end gap-2">
+      <button class="rounded-lg border border-line bg-panel px-3.5 py-1.5 text-[12.5px] font-medium text-ink transition hover:bg-hover" onclick={() => (showEditDesc = false)}>取消</button>
+      <button class="rounded-lg bg-accent px-3.5 py-1.5 text-[12.5px] font-medium text-white transition hover:bg-accent-hover" onclick={saveDesc}>保存</button>
+    </div>
+  </Modal>
+{/if}

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

@@ -0,0 +1,11 @@
+<script lang="ts">
+  import { toasts } from "./stores.js";
+</script>
+
+<div class="fixed bottom-4 right-4 z-50 flex flex-col gap-2">
+  {#each $toasts as t (t.id)}
+    <div class="max-w-[340px] rounded-lg px-4 py-2 text-sm text-white {t.kind === 'err' ? 'bg-[#7E2C26]' : 'bg-[#333230]'}">
+      {t.message}
+    </div>
+  {/each}
+</div>

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

@@ -0,0 +1,82 @@
+<script lang="ts">
+  import TreeNode from "./TreeNode.svelte";
+  import { api } from "./api.js";
+  import { expanded, currentNode, breadcrumb, toggleExpanded, treeVersion } from "./browser.js";
+  import { toastErr } from "./stores.js";
+  import type { BreadcrumbEntry, NodeChild, NodeDetail } from "./types.js";
+
+  let { node, depth }: { node: NodeChild; depth: number } = $props();
+
+  let children = $state<NodeChild[] | null>(null);
+  const isOpen = $derived($expanded.has(node.id));
+  const isSelected = $derived($currentNode?.id === node.id);
+
+  // 树刷新信号(增/删/移/重命名)→ 失效子节点缓存,展开状态下随之重载
+  $effect(() => {
+    void $treeVersion;
+    children = null;
+  });
+
+  $effect(() => {
+    if (isOpen && node.kind === "FOLDER" && children === null) {
+      api<{ nodes: NodeChild[] }>(`/database/api/nodes?parentId=${encodeURIComponent(node.id)}`)
+        .then((r) => (children = r.nodes))
+        .catch((e) => toastErr(e instanceof Error ? e.message : String(e)));
+    }
+  });
+
+  async function select(): Promise<void> {
+    if (node.kind === "FOLDER") toggleExpanded(node.id);
+    try {
+      const [detail, crumb] = await Promise.all([
+        api<{ node: NodeDetail }>(`/database/api/nodes/${node.id}`),
+        api<{ breadcrumb: BreadcrumbEntry[] }>(`/database/api/nodes/${node.id}/breadcrumb`),
+      ]);
+      currentNode.set(detail.node);
+      breadcrumb.set(crumb.breadcrumb);
+    } catch (e) {
+      toastErr(e instanceof Error ? e.message : String(e));
+    }
+  }
+</script>
+
+<div>
+  <div
+    class="tree-item flex cursor-pointer items-center gap-1 rounded-lg px-1.5 py-1.5 select-none {isSelected ? 'bg-selected' : 'hover:bg-hover'}"
+    role="button"
+    tabindex="0"
+    onclick={select}
+    onkeydown={(e) => e.key === "Enter" && select()}
+  >
+    <span class="flex h-4 w-4 shrink-0 items-center justify-center text-ink-3">
+      {#if node.kind === "FOLDER"}
+        <svg width="9" height="9" viewBox="0 0 24 24" fill="currentColor">
+          {#if isOpen}<path d="M6 9l6 6 6-6z" />{:else}<path d="M9 6l6 6-6 6z" />{/if}
+        </svg>
+      {/if}
+    </span>
+    <span class="flex h-4 w-4 shrink-0 items-center justify-center {node.kind === 'PROJECT' ? 'text-ink' : 'text-ink-3'}">
+      {#if node.kind === "PROJECT"}
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M20 7l-8-4-8 4m16 0l-8 4m8-4v10l-8 4m0-10L4 7m8 4v10M4 7v10l8 4" /></svg>
+      {:else}
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor"><path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V7Z" /></svg>
+      {/if}
+    </span>
+    <span class="truncate">{node.name}</span>
+    {#if node.role !== "MANAGE"}
+      <span class="ml-auto pr-1 font-mono text-[10px] text-ink-3">{node.role}</span>
+    {/if}
+  </div>
+
+  {#if node.kind === "FOLDER" && isOpen}
+    <div class="ml-[15px] border-l border-guide pl-1">
+      {#if children === null}
+        <div class="px-3 py-1.5 text-xs text-ink-3">…</div>
+      {:else}
+        {#each children as child (child.id)}
+          <TreeNode node={child} depth={depth + 1} />
+        {/each}
+      {/if}
+    </div>
+  {/if}
+</div>

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

@@ -0,0 +1,49 @@
+/** 与 /database/api/* 的约定一致;401 时清空会话(回到登录视图)。 */
+
+import { me } from "./stores.js";
+
+export class ApiError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: string,
+    message: string,
+    readonly details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+export class UnauthenticatedError extends Error {
+  constructor() {
+    super("unauthenticated");
+    this.name = "UnauthenticatedError";
+  }
+}
+
+interface RequestOpts {
+  readonly method?: string;
+  readonly body?: unknown;
+}
+
+export async function api<T = unknown>(path: string, opts: RequestOpts = {}): Promise<T> {
+  const res = await fetch(path, {
+    credentials: "same-origin",
+    method: opts.method ?? "GET",
+    ...(opts.body !== undefined
+      ? { headers: { "Content-Type": "application/json" }, body: JSON.stringify(opts.body) }
+      : {}),
+  });
+  if (res.status === 401) {
+    me.set(null);
+    throw new UnauthenticatedError();
+  }
+  if (res.status === 204) return null as T;
+  const text = await res.text();
+  const data = text === "" ? null : (JSON.parse(text) as unknown);
+  if (!res.ok) {
+    const err = (data as { error?: { code?: string; message?: string } } | null)?.error ?? {};
+    throw new ApiError(res.status, err.code ?? "unknown", err.message ?? res.statusText, err as Record<string, unknown>);
+  }
+  return data as T;
+}

hub/filelib-web/src/lib/browser.ts

@@ -0,0 +1,34 @@
+import { writable } from "svelte/store";
+import type { BreadcrumbEntry, NodeDetail } from "./types.js";
+
+/** 树展开集合 / 当前选中节点 / 面包屑 / 树刷新计数。 */
+export const expanded = writable<Set<string>>(new Set());
+export const currentNode = writable<NodeDetail | null>(null);
+export const breadcrumb = writable<BreadcrumbEntry[]>([]);
+export const treeVersion = writable(0);
+
+/** 右侧预览栏:当前选中文件路径(项目内);切换节点时清空。 */
+export const selectedFilePath = writable<string | null>(null);
+/** 文件列表刷新计数(编辑器保存/删除后 bump,列表随之重载)。 */
+export const filesVersion = writable(0);
+
+export function bumpTree(): void {
+  treeVersion.update((v) => v + 1);
+}
+
+export function bumpFiles(): void {
+  filesVersion.update((v) => v + 1);
+}
+
+export function clearSelectedFile(): void {
+  selectedFilePath.set(null);
+}
+
+export function toggleExpanded(id: string): void {
+  expanded.update((set) => {
+    const next = new Set(set);
+    if (next.has(id)) next.delete(id);
+    else next.add(id);
+    return next;
+  });
+}

hub/filelib-web/src/lib/stores.ts

@@ -0,0 +1,26 @@
+import { writable } from "svelte/store";
+import type { MeResponse } from "./types.js";
+
+/** 当前登录身份;null = 未登录(显示登录视图)。 */
+export const me = writable<MeResponse | null>(null);
+export const authChecked = writable(false);
+
+export interface ToastItem {
+  readonly id: number;
+  readonly message: string;
+  readonly kind: "info" | "err";
+}
+
+let nextToastId = 1;
+export const toasts = writable<ToastItem[]>([]);
+
+export function toast(message: string, kind: ToastItem["kind"] = "info"): void {
+  const id = nextToastId++;
+  toasts.update((list) => [...list, { id, message, kind }]);
+  setTimeout(() => {
+    toasts.update((list) => list.filter((t) => t.id !== id));
+  }, 3600);
+}
+
+export const toastOk = (m: string): void => toast(m, "info");
+export const toastErr = (m: string): void => toast(m, "err");

hub/filelib-web/src/lib/types.ts

@@ -0,0 +1,85 @@
+/** 与后端 /database/api/* 响应形状对齐。 */
+
+export type NodeKind = "FOLDER" | "PROJECT";
+export type Role = "VIEW" | "EDIT" | "MANAGE";
+
+export interface NodeChild {
+  readonly id: string;
+  readonly parentId: string | null;
+  readonly kind: NodeKind;
+  readonly name: string;
+  readonly role: Role;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+
+export interface BreadcrumbEntry {
+  readonly depth: number;
+  readonly id: string | null;
+  readonly name: string | null;
+  readonly kind: NodeKind;
+}
+
+export interface NodeDetail {
+  readonly id: string;
+  readonly parentId: string | null;
+  readonly kind: NodeKind;
+  readonly name: string;
+  readonly description: string | null;
+  readonly role: Role;
+  readonly provisionStatus: "PROVISIONING" | "READY" | "FAILED";
+  readonly independentPermission: boolean;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+
+export interface MeResponse {
+  readonly userId: string;
+  readonly isWebsiteAdmin: boolean;
+}
+
+export interface FileEntry {
+  readonly path: string;
+  readonly size: number;
+}
+
+export type FileContentEncoding = "utf8" | "base64";
+
+export interface FileContent {
+  readonly path: string;
+  readonly version: string;
+  readonly encoding: FileContentEncoding;
+  readonly content: string;
+  readonly size: number;
+}
+
+export interface VersionInfo {
+  readonly version: string;
+  readonly message: string;
+  readonly author?: string;
+  readonly committedAt: string;
+}
+
+export interface ExportJob {
+  readonly id: string;
+  readonly nodeId: string;
+  readonly target: string;
+  readonly status: "QUEUED" | "RUNNING" | "DONE" | "FAILED";
+  readonly error: string | null;
+  readonly createdAt: string;
+}
+
+export interface Grant {
+  readonly id: string;
+  readonly principalType: "USER" | "GROUP";
+  readonly principalId: string;
+  readonly role: Role;
+  readonly isCreatorGrant: boolean;
+  readonly createdAt: string;
+}
+
+export interface GroupSearchResult {
+  readonly id: string;
+  readonly name: string;
+  readonly breadcrumb: string;
+}

hub/filelib-web/src/main.ts

@@ -0,0 +1,5 @@
+import { mount } from "svelte";
+import App from "./App.svelte";
+import "./app.css";
+
+export default mount(App, { target: document.getElementById("app")! });

hub/filelib-web/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.svelte"]
+}

hub/filelib-web/vite.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from "vite";
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+import tailwindcss from "@tailwindcss/vite";
+
+// 老师端独立 SPA:构建产物由 hub 后端静态托管于 /app;
+// 开发时 vite dev(:5173)把 API/认证请求代理到后端(:8788)。
+const backend = "http://127.0.0.1:8788";
+
+export default defineConfig({
+  plugins: [svelte(), tailwindcss()],
+  base: "/app/",
+  build: {
+    outDir: "dist",
+    emptyOutDir: true,
+  },
+  server: {
+    port: 5173,
+    proxy: {
+      "/database/api": backend,
+      "/auth": backend,
+      "/app/dev-login": backend,
+      "/app/dev-login-teacher": backend,
+    },
+  },
+});

hub/package-lock.json

@@ -1,18 +1,19 @@
 {
   "name": "@paradigm/hub",
-  "version": "0.0.31",
+  "version": "0.0.36",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@paradigm/hub",
-      "version": "0.0.31",
+      "version": "0.0.36",
       "dependencies": {
         "@alicloud/credentials": "^2.4.5",
         "@alicloud/docmind-api20220711": "^1.4.15",
         "@alicloud/tea-util": "^1.4.11",
         "@anthropic-ai/claude-agent-sdk": "^0.3.202",
         "@fastify/cookie": "^11.0.2",
+        "@fastify/static": "^10.1.2",
         "@larksuiteoapi/node-sdk": "^1.70.0",
         "@prisma/client": "^6.19.3",
         "ai": "^7.0.16",
@@ -902,6 +903,22 @@
         "node": ">=18"
       }
     },
+    "node_modules/@fastify/accept-negotiator": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/@fastify/accept-negotiator/-/accept-negotiator-2.0.1.tgz",
+      "integrity": "sha512-/c/TW2bO/v9JeEgoD/g1G5GxGeCF1Hafdf79WPmUlgYiBXummY0oX3VVq4yFkKKVBKDNlaDUYoab7g38RpPqCQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "MIT"
+    },
     "node_modules/@fastify/ajv-compiler": {
       "version": "4.0.5",
       "resolved": "https://registry.npmjs.org/@fastify/ajv-compiler/-/ajv-compiler-4.0.5.tgz",
@@ -1033,6 +1050,83 @@
         "ipaddr.js": "^2.1.0"
       }
     },
+    "node_modules/@fastify/send": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/@fastify/send/-/send-4.1.0.tgz",
+      "integrity": "sha512-TMYeQLCBSy2TOFmV95hQWkiTYgC/SEx7vMdV+wnZVX4tt8VBLKzmH8vV9OzJehV0+XBfg+WxPMt5wp+JBUKsVw==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@lukeed/ms": "^2.0.2",
+        "escape-html": "~1.0.3",
+        "fast-decode-uri-component": "^1.0.1",
+        "http-errors": "^2.0.0",
+        "mime": "^3"
+      }
+    },
+    "node_modules/@fastify/static": {
+      "version": "10.1.2",
+      "resolved": "https://registry.npmjs.org/@fastify/static/-/static-10.1.2.tgz",
+      "integrity": "sha512-G/g18cG9tLutT/OVyN1AIsHIl9L1UwmJ+S3dkyhVpplIx0nEMicd7RGQ+uJLyhKKF4a3tTcQydccn3Mop1fX+Q==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@fastify/accept-negotiator": "^2.0.0",
+        "@fastify/error": "^4.0.0",
+        "@fastify/send": "^4.0.0",
+        "content-disposition": "^2.0.1",
+        "fastify-plugin": "^6.0.0",
+        "fastq": "^1.17.1",
+        "glob": "^13.0.0"
+      }
+    },
+    "node_modules/@fastify/static/node_modules/content-disposition": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-2.0.1.tgz",
+      "integrity": "sha512-e+H0ZXHSWYrENhQzw1LPuP4oF5MzVKmDU6d3hxlvaPEYLLg62MxtQNPRx4SYSuYJSBUgnQIG4HIN2tEtNv7Dog==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/@fastify/static/node_modules/fastify-plugin": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/fastify-plugin/-/fastify-plugin-6.0.0.tgz",
+      "integrity": "sha512-fZOty7z3O7vOliF6d8bHE3wiEh1KcNnKEQensSgTk9C1DvN6nRLS++XVd86v33Hw/8u9Un8A1zDrQ8ujcQDHEg==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "MIT"
+    },
     "node_modules/@hono/node-server": {
       "version": "1.19.14",
       "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.14.tgz",
@@ -1068,6 +1162,15 @@
         "ws": "^8.19.0"
       }
     },
+    "node_modules/@lukeed/ms": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/@lukeed/ms/-/ms-2.0.2.tgz",
+      "integrity": "sha512-9I2Zn6+NJLfaGoz9jN3lpwDgAYvfGeNYdbAIjJOqzs4Tpc+VU3Jqq4IofSUBKajiDS8k9fZIg18/z13mpk1bsA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/@modelcontextprotocol/sdk": {
       "version": "1.29.0",
       "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.29.0.tgz",
@@ -1934,6 +2037,15 @@
         "proxy-from-env": "^2.1.0"
       }
     },
+    "node_modules/balanced-match": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
+      "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
+      "license": "MIT",
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
     "node_modules/body-parser": {
       "version": "2.3.0",
       "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.3.0.tgz",
@@ -1973,6 +2085,18 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/brace-expansion": {
+      "version": "5.0.7",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.7.tgz",
+      "integrity": "sha512-7oFy703dxfY3/NLxC1fh2SUCQ0H9rmAY+5EpDVfXjUTTs+HEwR2nYaqLv+GWcTsumwxPfiz6CzCNkwXwBUwqCA==",
+      "license": "MIT",
+      "dependencies": {
+        "balanced-match": "^4.0.2"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
     "node_modules/bytes": {
       "version": "3.1.2",
       "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz",
@@ -2254,7 +2378,6 @@
       "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz",
       "integrity": "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">= 0.8"
       }
@@ -2447,8 +2570,7 @@
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz",
       "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==",
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/estree-walker": {
       "version": "3.0.3",
@@ -2947,6 +3069,23 @@
         "giget": "dist/cli.mjs"
       }
     },
+    "node_modules/glob": {
+      "version": "13.0.6",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-13.0.6.tgz",
+      "integrity": "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==",
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "minimatch": "^10.2.2",
+        "minipass": "^7.1.3",
+        "path-scurry": "^2.0.2"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/gopd": {
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
@@ -3013,7 +3152,6 @@
       "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz",
       "integrity": "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "depd": "~2.0.0",
         "inherits": "~2.0.4",
@@ -3096,8 +3234,7 @@
       "version": "2.0.4",
       "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
       "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
-      "license": "ISC",
-      "peer": true
+      "license": "ISC"
     },
     "node_modules/ini": {
       "version": "1.3.8",
@@ -3546,6 +3683,15 @@
       "integrity": "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==",
       "license": "Apache-2.0"
     },
+    "node_modules/lru-cache": {
+      "version": "11.5.2",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.2.tgz",
+      "integrity": "sha512-4pfM1Ff0x50o0tQwb5ucw/RzNyD0/YJME6IVcStalZuMWxdt3sR3huStTtxz4PUmvZfRguvDejasvQ2kifR11g==",
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": "20 || >=22"
+      }
+    },
     "node_modules/magic-string": {
       "version": "0.30.21",
       "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
@@ -3588,6 +3734,18 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/mime": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/mime/-/mime-3.0.0.tgz",
+      "integrity": "sha512-jSCU7/VB1loIWBZe14aEYHU/+1UMEHoaO7qxCOVJOw9GgH72VAWppxNcjU+x9a2k3GSIBXNKxXQFqRvvZ7vr3A==",
+      "license": "MIT",
+      "bin": {
+        "mime": "cli.js"
+      },
+      "engines": {
+        "node": ">=10.0.0"
+      }
+    },
     "node_modules/mime-db": {
       "version": "1.52.0",
       "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz",
@@ -3609,6 +3767,30 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/minimatch": {
+      "version": "10.2.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.5.tgz",
+      "integrity": "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==",
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "brace-expansion": "^5.0.5"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/minipass": {
+      "version": "7.1.3",
+      "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz",
+      "integrity": "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==",
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": ">=16 || 14 >=14.17"
+      }
+    },
     "node_modules/moment": {
       "version": "2.30.1",
       "resolved": "https://registry.npmjs.org/moment/-/moment-2.30.1.tgz",
@@ -3792,6 +3974,22 @@
         "node": ">=8"
       }
     },
+    "node_modules/path-scurry": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.2.tgz",
+      "integrity": "sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==",
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "lru-cache": "^11.0.0",
+        "minipass": "^7.1.2"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/path-to-regexp": {
       "version": "8.4.2",
       "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.4.2.tgz",
@@ -4370,8 +4568,7 @@
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz",
       "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==",
-      "license": "ISC",
-      "peer": true
+      "license": "ISC"
     },
     "node_modules/shebang-command": {
       "version": "2.0.0",
@@ -4570,7 +4767,6 @@
       "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz",
       "integrity": "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">= 0.8"
       }
@@ -4658,7 +4854,6 @@
       "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz",
       "integrity": "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=0.6"
       }

hub/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paradigm/hub",
-  "version": "0.0.32",
+  "version": "0.0.36",
   "private": true,
   "type": "module",
   "engines": {
@@ -12,6 +12,7 @@
     "@alicloud/tea-util": "^1.4.11",
     "@anthropic-ai/claude-agent-sdk": "^0.3.202",
     "@fastify/cookie": "^11.0.2",
+    "@fastify/static": "^10.1.2",
     "@larksuiteoapi/node-sdk": "^1.70.0",
     "@prisma/client": "^6.19.3",
     "ai": "^7.0.16",
@@ -30,10 +31,10 @@
       "axios": "1.18.1"
     }
   },
-  "description": "Curriculum Project Hub — org-scoped Feishu collaboration and confined Agent runtime. Aligns to spec/System through ADR-0024.",
+  "description": "Curriculum Project Hub — org-scoped Feishu collaboration and confined Agent runtime. Semantics pinned by docs/adr/ (ADR-0001 through ADR-0027).",
   "scripts": {
     "dev": "npm run prisma:migrate && tsx watch src/server.ts",
-    "build": "tsc -p tsconfig.json && npm run admin:build",
+    "build": "tsc -p tsconfig.json && npm run admin:build && npm run filelib:build",
     "start": "npm run prisma:migrate && node dist/server.js",
     "check": "tsc -p tsconfig.json --noEmit",
     "audit:production": "npm audit --omit=dev --audit-level=high",
@@ -48,6 +49,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "admin:dev": "npm run dev --prefix admin-web",
-    "admin:build": "npm run build --prefix admin-web"
+    "admin:build": "npm run build --prefix admin-web",
+    "filelib:dev": "npm run dev --prefix filelib-web",
+    "filelib:build": "npm run build --prefix filelib-web"
   }
 }

hub/prisma/migrations/20260714120000_drop_legacy_platform_role_assignment/migration.sql

@@ -1,6 +1,6 @@
 -- ADR-0023 rejected the legacy `PlatformRoleAssignment` / `PlatformRole`{ADMIN,TEACHER}
 -- model: the platform administration control plane is a separate identity/session/
--- audit surface (see `Spec.System.PlatformAdministration`), intentionally not built
+-- audit surface, intentionally not built
 -- in alpha (ADR-0025, `hub/deploy/README.md`). The legacy table has no runtime
 -- reader — no guard, route, or service queries it for an authorization decision —
 -- and ADR-0023 requires it to be migrated/replaced before the platform panel ships.

hub/prisma/migrations/20260721120000_file_library/migration.sql

@@ -0,0 +1,92 @@
+-- File library (文件库) — 语义锚定:仓库根《文件库-接口契约.md》、.omo/文件库-开工计划.md (D11–D19)。
+-- 本地无 PG 时手写;有 PG 后可用 `prisma migrate diff` 核对与 schema 的一致性。
+
+-- CreateEnum
+CREATE TYPE "FileLibNodeKind" AS ENUM ('FOLDER', 'PROJECT');
+CREATE TYPE "FileLibProvisionStatus" AS ENUM ('PROVISIONING', 'READY', 'FAILED');
+CREATE TYPE "FileLibRole" AS ENUM ('VIEW', 'EDIT', 'MANAGE');
+CREATE TYPE "FileLibPrincipalType" AS ENUM ('USER', 'GROUP');
+CREATE TYPE "FileLibExportStatus" AS ENUM ('QUEUED', 'RUNNING', 'DONE', 'FAILED');
+
+-- CreateTable
+CREATE TABLE "FileLibNode" (
+    "id" TEXT NOT NULL,
+    "organizationId" TEXT NOT NULL,
+    "parentId" TEXT,
+    "kind" "FileLibNodeKind" NOT NULL,
+    "name" TEXT NOT NULL,
+    "nameLower" TEXT NOT NULL,
+    "pathIds" TEXT NOT NULL,
+    "creatorId" TEXT NOT NULL,
+    "provisionStatus" "FileLibProvisionStatus" NOT NULL DEFAULT 'READY',
+    "storageDir" TEXT,
+    "deletedAt" TIMESTAMP(3),
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "FileLibNode_pkey" PRIMARY KEY ("id")
+);
+
+CREATE TABLE "FileLibGrant" (
+    "id" TEXT NOT NULL,
+    "organizationId" TEXT NOT NULL,
+    "nodeId" TEXT NOT NULL,
+    "principalType" "FileLibPrincipalType" NOT NULL,
+    "principalId" TEXT NOT NULL,
+    "role" "FileLibRole" NOT NULL,
+    "isCreatorGrant" BOOLEAN NOT NULL DEFAULT false,
+    "createdByUserId" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "revokedAt" TIMESTAMP(3),
+
+    CONSTRAINT "FileLibGrant_pkey" PRIMARY KEY ("id")
+);
+
+CREATE TABLE "FileLibProjectSettings" (
+    "nodeId" TEXT NOT NULL,
+    "independentPermissionsEnabled" BOOLEAN NOT NULL DEFAULT false,
+
+    CONSTRAINT "FileLibProjectSettings_pkey" PRIMARY KEY ("nodeId")
+);
+
+CREATE TABLE "FileLibExportJob" (
+    "id" TEXT NOT NULL,
+    "organizationId" TEXT NOT NULL,
+    "nodeId" TEXT NOT NULL,
+    "target" TEXT NOT NULL,
+    "params" JSONB NOT NULL,
+    "status" "FileLibExportStatus" NOT NULL DEFAULT 'QUEUED',
+    "downloadUrl" TEXT,
+    "error" TEXT,
+    "createdByUserId" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "FileLibExportJob_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex (schema-declared)
+CREATE INDEX "FileLibNode_organizationId_parentId_deletedAt_idx" ON "FileLibNode"("organizationId", "parentId", "deletedAt");
+CREATE INDEX "FileLibNode_organizationId_pathIds_idx" ON "FileLibNode"("organizationId", "pathIds");
+CREATE INDEX "FileLibNode_creatorId_idx" ON "FileLibNode"("creatorId");
+CREATE INDEX "FileLibGrant_organizationId_revokedAt_idx" ON "FileLibGrant"("organizationId", "revokedAt");
+CREATE INDEX "FileLibGrant_principalType_principalId_revokedAt_idx" ON "FileLibGrant"("principalType", "principalId", "revokedAt");
+CREATE INDEX "FileLibGrant_nodeId_revokedAt_idx" ON "FileLibGrant"("nodeId", "revokedAt");
+CREATE INDEX "FileLibExportJob_organizationId_status_idx" ON "FileLibExportJob"("organizationId", "status");
+
+-- D14:活跃兄弟节点大小写不敏感唯一。root 的 parentId 为 NULL,用 COALESCE 归入同一键空间。
+CREATE UNIQUE INDEX "FileLibNode_active_sibling_name_key"
+    ON "FileLibNode"("organizationId", COALESCE("parentId", ''), "nameLower")
+    WHERE "deletedAt" IS NULL;
+
+-- 契约 2.3:同一节点上同一 principal 至多一条活跃授权(Postgres 原生 UNIQUE 无法约束 NULL revokedAt)。
+CREATE UNIQUE INDEX "FileLibGrant_active_unique"
+    ON "FileLibGrant"("nodeId", "principalType", "principalId")
+    WHERE "revokedAt" IS NULL;
+
+-- AddForeignKey
+ALTER TABLE "FileLibNode" ADD CONSTRAINT "FileLibNode_organizationId_fkey" FOREIGN KEY ("organizationId") REFERENCES "Organization"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "FileLibNode" ADD CONSTRAINT "FileLibNode_parentId_fkey" FOREIGN KEY ("parentId") REFERENCES "FileLibNode"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+ALTER TABLE "FileLibGrant" ADD CONSTRAINT "FileLibGrant_nodeId_fkey" FOREIGN KEY ("nodeId") REFERENCES "FileLibNode"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "FileLibProjectSettings" ADD CONSTRAINT "FileLibProjectSettings_nodeId_fkey" FOREIGN KEY ("nodeId") REFERENCES "FileLibNode"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "FileLibExportJob" ADD CONSTRAINT "FileLibExportJob_nodeId_fkey" FOREIGN KEY ("nodeId") REFERENCES "FileLibNode"("id") ON DELETE CASCADE ON UPDATE CASCADE;

hub/prisma/migrations/20260723130000_filelib_description/migration.sql

@@ -0,0 +1,2 @@
+-- 为 FileLibNode 加简介字段，老师在创建/概览页填写。
+ALTER TABLE "FileLibNode" ADD COLUMN "description" TEXT;

hub/prisma/schema.prisma

@@ -1,6 +1,6 @@
 // Prisma schema for Curriculum Project Hub.
 //
-// Aligns to spec/System (ADR-0001..0004, 0017). Key divergences from the
+// Aligns to ADR-0001..0004, 0017. Key divergences from the
 // legacy teaching-material-host-service schema, each deliberate:
 //
 //  - AgentSession is provider/model-bound. Provider runtime cursors such as
@@ -11,8 +11,8 @@
 //  - ProjectGroupBinding is project→chat only (ADR-0001 1:1); legacy mixed
 //    user/chat targets into one binding table.
 //  - PermissionGrant + PermissionSettings land (ADR-0004), missing in legacy.
-//  - AgentRunStatus adds WAITING_FOR_USER + TIMED_OUT (spec RunState; enum
-//    completeness OPEN — add states without a schema migration war).
+//  - AgentRunStatus adds WAITING_FOR_USER + TIMED_OUT (the run-state set is
+//    open — add states without a schema migration war).
 
 generator client {
   provider = "prisma-client-js"
@@ -50,6 +50,7 @@ model Organization {
   projectGroupBindings         ProjectGroupBinding[]
   auditEntries                 AuditEntry[]                             @relation("organizationAudit")
   projectSearchDocuments       ProjectSearchDocument[]
+  fileLibNodes                 FileLibNode[]
 
   @@index([status])
 }
@@ -61,7 +62,7 @@ enum OrganizationStatus {
 }
 
 /// Org-scoped membership role. Distinct from project PermissionRole and from
-/// the platform administrator surface (ADR-0023 / Spec.System.PlatformAdministration),
+/// the platform administrator surface (ADR-0023),
 /// which is a separate control plane not modeled in alpha (ADR-0025).
 model OrganizationMembership {
   id             String                 @id @default(cuid())
@@ -923,3 +924,127 @@ model CapabilityCredentialVersion {
   @@index([keyId])
   @@index([createdByUserId])
 }
+
+// --- File library (文件库) -------------------------------------------------
+//
+// 独立模块,语义由仓库根《文件库-接口契约.md》(C/D 编号)与 .omo/文件库-开工计划.md
+// (D11–D19)锚定。与上面的 Folder/Project(hub 自己的 explorer,ADR-0021)是两套
+// 体系,不复用、不互相引用。
+
+/// 文件库目录树节点:文件夹(容器)或项目(叶子,关联 git 仓库)。
+/// parentId 是树的权威关系;pathIds 是 id 编码的物化路径(派生),随 create/move
+/// 在事务内维护(计划 D12;name 不入路径,rename 不重写后代)。
+model FileLibNode {
+  id              String                 @id
+  organizationId  String
+  parentId        String?
+  kind            FileLibNodeKind
+  name            String
+  /// D14:NFC+trim 的小写形式;活跃兄弟节点大小写不敏感唯一(部分唯一索引在迁移 SQL)。
+  nameLower       String
+  /// id 编码物化路径,形如 "/rootId/childId/selfId"。祖先展开与前缀查询都用它。
+  pathIds         String
+  /// D11:创建者不可变,自动持有 isCreatorGrant=true 的 MANAGE grant。
+  /// 故意不建 FK:这是不可变历史事实,不随 User 生命周期变化。
+  creatorId       String
+  /// 老师可填写的简介，创建/概览页展示，通俗易懂地说明这个节点的用途。
+  description     String?
+  /// 项目 provisioning 状态机(DB/git 双写协调,Metis 风险#1);文件夹恒 READY。
+  provisionStatus FileLibProvisionStatus @default(READY)
+  /// 项目仓库目录(绝对路径);文件夹为 null。
+  storageDir      String?
+  deletedAt       DateTime?
+  createdAt       DateTime               @default(now())
+  updatedAt       DateTime               @updatedAt
+
+  organization    Organization            @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  parent          FileLibNode?            @relation("fileLibTree", fields: [parentId], references: [id], onDelete: Restrict)
+  children        FileLibNode[]           @relation("fileLibTree")
+  grants          FileLibGrant[]
+  projectSettings FileLibProjectSettings?
+  exportJobs      FileLibExportJob[]
+
+  @@index([organizationId, parentId, deletedAt])
+  @@index([organizationId, pathIds])
+  @@index([creatorId])
+}
+
+enum FileLibNodeKind {
+  FOLDER
+  PROJECT
+}
+
+enum FileLibProvisionStatus {
+  PROVISIONING
+  READY
+  FAILED
+}
+
+/// 文件库权限级别:MANAGE > EDIT > VIEW(契约 2.2,只取最高、无降权)。
+enum FileLibRole {
+  VIEW
+  EDIT
+  MANAGE
+}
+
+enum FileLibPrincipalType {
+  USER
+  GROUP
+}
+
+/// 契约 2.3:grant 直接挂在节点上,最终权限 = max(个人, 递归 Group, 祖先继承)。
+/// 活跃授权唯一性由迁移里的部分唯一索引保证(revokedAt IS NULL)。
+model FileLibGrant {
+  id              String               @id @default(cuid())
+  organizationId  String
+  nodeId          String
+  principalType   FileLibPrincipalType
+  principalId     String
+  role            FileLibRole
+  /// D11:创建者自动 grant;独立权限开关关闭时,项目级 grant 里只有它仍生效。
+  isCreatorGrant  Boolean              @default(false)
+  createdByUserId String?
+  createdAt       DateTime             @default(now())
+  revokedAt       DateTime?
+
+  node FileLibNode @relation(fields: [nodeId], references: [id], onDelete: Cascade)
+
+  @@index([organizationId, revokedAt])
+  @@index([principalType, principalId, revokedAt])
+  @@index([nodeId, revokedAt])
+}
+
+/// 契约 P5/D11:项目独立权限开关。默认关闭(仅继承);关闭时项目级非创建者
+/// grant 冻结不删除,重新开启即恢复。
+model FileLibProjectSettings {
+  nodeId                        String  @id
+  independentPermissionsEnabled Boolean @default(false)
+
+  node FileLibNode @relation(fields: [nodeId], references: [id], onDelete: Cascade)
+}
+
+enum FileLibExportStatus {
+  QUEUED
+  RUNNING
+  DONE
+  FAILED
+}
+
+/// 契约 D10:导出为异步任务。外部导出工具参数 OPEN-6,adapter 就位前先建模型。
+model FileLibExportJob {
+  id              String             @id @default(cuid())
+  organizationId  String
+  nodeId          String
+  target          String
+  params          Json
+  status          FileLibExportStatus @default(QUEUED)
+  downloadUrl     String?
+  error           String?
+  createdByUserId String
+  createdAt       DateTime           @default(now())
+  updatedAt       DateTime           @updatedAt
+
+  node FileLibNode @relation(fields: [nodeId], references: [id], onDelete: Cascade)
+
+  @@index([organizationId, status])
+}

hub/skills/pdf-to-md/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: pdf-to-md
+description: >
+  Convert PDF documents to Markdown bundles using the convert_pdf_to_md tool.
+  Handles PDFs from Feishu messages, local workspace files, and produces
+  high-quality Markdown with LaTeX formulas and extracted images.
+---
+
+# PDF to Markdown Conversion
+
+## When to use
+
+Use this skill when the user asks to convert a PDF to Markdown, extract text
+from a PDF, or turn a PDF document into an editable format.
+
+## How it works
+
+The `convert_pdf_to_md` tool (provided by the `cph_hub` MCP server) calls
+Alibaba Cloud Document Mind to parse the PDF. It:
+
+- Extracts text in reading order (handles multi-column, scanned, and
+  multi-language documents)
+- Converts mathematical formulas to **LaTeX** (`$...$` inline, `$$...$$` block)
+- Extracts tables as Markdown tables
+- Downloads embedded images into the output directory
+- Writes a single `document.md` file plus image files
+
+## Workflow
+
+### PDF from a Feishu message
+
+1. Use `feishu_read_context` to find the `file_key` of the PDF attachment.
+2. Use `feishu_download_resource` to download it into the workspace.
+3. Use `convert_pdf_to_md` with the downloaded file path and an output directory.
+
+### PDF already in the workspace
+
+1. Use `convert_pdf_to_md` directly with the file path and an output directory.
+
+## Important rules
+
+- **Always** use `convert_pdf_to_md` for PDF→Markdown. Do NOT attempt to parse
+  PDFs yourself with Read, Bash, Python, or any other method. The tool provides
+  accurate formula, table, and image extraction that manual methods cannot
+  match.
+- If `convert_pdf_to_md` fails because no capability connection is configured,
+  tell the user to ask their organization admin to configure the Aliyun
+  docmind credential in the admin web UI (组织后台 → 能力).
+- The output directory will be created if it does not exist.
+- After conversion, use `send_file` to send the generated markdown back to the
+  user if they requested it.
+
+## Output
+
+The tool returns a list of generated files:
+- `document.md` — the main markdown file
+- `*.jpg` / `*.png` — extracted images, referenced from the markdown
+
+## Cost
+
+The conversion is billed per page (0.04 CNY/page ≈ $0.0056/page for the
+enhanced formula mode). The cost is automatically recorded on the run's
+usage ledger.

hub/src/admin/routes/authRoutes.ts

@@ -432,16 +432,16 @@ async function resolvePostLoginRedirect(
       select: { organization: { select: { slug: true, name: true } } },
     });
     if (intended === null) return "/admin?error=not_an_active_org_member";
-    const orgRoot = `/admin/org/${intended.organization.slug}`;
+    const orgRoot = "/admin";
     // Default / missing returnTo sanitizes to "/admin". Always land in the org
     // admin SPA (not the legacy static "close this tab" complete page).
     if (returnTo === "/admin") {
       return orgRoot;
     }
-    return returnTo === orgRoot || returnTo.startsWith(`${orgRoot}/`) ? returnTo : orgRoot;
+    return normalizeAdminReturnTo(returnTo) ?? orgRoot;
   }
   if (returnTo !== "/admin" && returnTo.startsWith("/admin")) {
-    return returnTo;
+    return normalizeAdminReturnTo(returnTo) ?? "/admin";
   }
   const membership = await prisma.organizationMembership.findFirst({
     where: {
@@ -454,7 +454,7 @@ async function resolvePostLoginRedirect(
     orderBy: { createdAt: "asc" },
   });
   if (membership !== null) {
-    return `/admin/org/${membership.organization.slug}`;
+    return "/admin";
   }
   // Member-only or no org: still land on a shell page (SPA will explain).
   const any = await prisma.organizationMembership.findFirst({
@@ -463,7 +463,7 @@ async function resolvePostLoginRedirect(
     orderBy: { createdAt: "asc" },
   });
   if (any !== null) {
-    return `/admin/org/${any.organization.slug}`;
+    return "/admin/projects";
   }
   return "/admin/login?error=no_organization";
 }
@@ -489,7 +489,18 @@ export function sanitizeReturnTo(raw: string): string {
   if (!raw.startsWith("/admin")) {
     return "/admin";
   }
-  return raw;
+  return normalizeAdminReturnTo(raw) ?? "/admin";
+}
+
+/** Map legacy `/admin/org/:slug[...]` bookmarks onto slugless `/admin[...]` paths. */
+export function normalizeAdminReturnTo(path: string): string | null {
+  if (!path.startsWith("/admin")) return null;
+  const legacy = path.match(/^\/admin\/org\/[^/]+(\/.*)?$/);
+  if (legacy) {
+    const rest = legacy[1] ?? "";
+    return rest === "" ? "/admin" : `/admin${rest}`;
+  }
+  return path;
 }
 
 function trimTrailingSlash(url: string): string {

hub/src/agent/roleTools.ts

@@ -14,6 +14,7 @@ export const CPH_HUB_MCP_TOOL_IDS = [
   "feishu_read_context",
   "feishu_download_resource",
   "request_approval",
+  "convert_pdf_to_md",
 ] as const;
 
 export type CphHubMcpToolId = (typeof CPH_HUB_MCP_TOOL_IDS)[number];
@@ -50,10 +51,12 @@ const ROLE_TOOL_TO_CPH_HUB_MCP_TOOL = new Map<string, CphHubMcpToolId>([
   ["feishu_read_context", "feishu_read_context"],
   ["feishu_download_resource", "feishu_download_resource"],
   ["request_approval", "request_approval"],
+  ["convert_pdf_to_md", "convert_pdf_to_md"],
   ["mcp__cph_hub__send_file", "send_file"],
   ["mcp__cph_hub__feishu_read_context", "feishu_read_context"],
   ["mcp__cph_hub__feishu_download_resource", "feishu_download_resource"],
   ["mcp__cph_hub__request_approval", "request_approval"],
+  ["mcp__cph_hub__convert_pdf_to_md", "convert_pdf_to_md"],
 ]);
 
 const SUPPORTED_ROLE_TOOLS = new Set([

hub/src/agent/runner.ts

@@ -24,10 +24,10 @@
  * denied by default and re-opened only for the workspace plus named system
  * runtimes, and `failIfUnavailable` hard-fails if the sandbox can't start. The
  * subprocess gets a minimal environment and SDK credential protection removes
- * provider secrets from Bash. This upholds `AgentFileOp.Authorized`
- * (ADR-0018 / `Spec.System.AgentSurface`) without re-implementing the
+ * provider secrets from Bash. This upholds the workspace-bounded file-op
+ * invariant (ADR-0018) without re-implementing the
  * `workspace.ts` `confine()` path validator as a tool wrapper — the OS sandbox
- * is the mechanism, the contract pins the invariant.
+ * is the mechanism, the ADR pins the invariant.
  */
 import { query, type HookCallback, type McpServerConfig, type SDKMessage, type SDKAssistantMessage, type SDKUserMessage, type SDKResultMessage, type SDKPartialAssistantMessage, type SDKSystemMessage } from "@anthropic-ai/claude-agent-sdk";
 import type { PrismaClient } from "@prisma/client";

hub/src/capacity/dimensions.ts

@@ -1,6 +1,6 @@
 /**
- * ADR-0022 capacity dimensions (spec `Spec.System.Capacity.CapacityDimension`).
- * The 23 PINNED dimensions; exact numeric ceilings are `OPEN` and calibrated by
+ * ADR-0022 capacity dimensions.
+ * The 23 pinned dimensions; exact numeric ceilings are open and calibrated by
  * capacity testing. This module is the single source of the dimension set shared
  * by the platform-ceiling config and the org capacity-policy service.
  */

hub/src/database/README.md

@@ -0,0 +1,126 @@
+# src/database/
+
+`/database/*` HTTP 面。代码写在这个目录里，`hub.ts` 通过 `plugin.ts` 挂载它，
+所以服务器启动时能正确识别这些路由。
+
+页面：
+
+- `/database/admin` —— 飞书登录页（唯一登录方式）
+- `/database/dashboard` —— 左菜单 + 右内容的后台，未登录会跳回 `/database/admin`
+
+登录走平台既有的飞书 OAuth：登录页的按钮指向 `/auth/feishu/<orgSlug>`，
+回调由 `src/admin/routes/authRoutes.ts` 处理并种下 session cookie。
+
+## 开发模式：用环境变量开启一键登录
+
+本地开发没有真实飞书 app 时，可以用环境变量开启一键登录，跳过飞书 OAuth，
+直接以现有 OWNER/ADMIN 身份登入后台。**仅限开发，不是生产登录路径。**
+
+### 怎么开
+
+在 `hub/.env` 里设：
+
+```sh
+HUB_DEV_LOGIN_BYPASS="true"
+```
+
+改完重启服务（`npm run dev`，或本地手动 `npx tsx src/server.ts`）。启动日志会
+打印一行 `DEV login bypass enabled: /database/dev-login ...` 作为确认。
+
+开启后：
+
+- `/database/admin` 登录页显示「⚡ 一键登录管理员」按钮
+- 后端注册 `/database/dev-login` 端点：按钮就是打它，它签发一个和飞书 OAuth
+  回调完全一样的 session，然后跳到 `/database/dashboard`
+
+### 怎么关
+
+把值设成 `false`（或 `0` / `no` / `off`），或删掉这一行。关闭后按钮消失、
+`/database/dev-login` 返回 404 —— 按钮和端点同进同退。
+
+### 双重门禁（重要）
+
+真正的开关是两个条件的**与**（判断在 `plugin.ts`）：
+
+```
+allowDevLoginBypass = (NODE_ENV !== "production") && HUB_DEV_LOGIN_BYPASS 为真
+```
+
+即：**只要 `NODE_ENV=production`，无论 `HUB_DEV_LOGIN_BYPASS` 设成什么，一键登录
+都强制关闭。** 生产始终只能走真实飞书 OAuth。
+
+> 提醒：`HUB_DEV_LOGIN_BYPASS` 是敏感开关，别把开着它的 `.env` 带到任何联网 /
+> 共享环境。整个旁路逻辑自包含在本目录（`plugin.ts` + `routes/databaseRoutes.ts`），
+> `src/admin` 的登录路由未受影响。
+
+## 文件
+
+| 文件 | 职责 |
+|------|------|
+| `plugin.ts` | 模块对外入口，`hub.ts` 调 `registerDatabasePlugin()` |
+| `routes/databaseRoutes.ts` | 登录页/dashboard + 各子路由装配点 |
+| `routes/filelibRoutes.ts` | 文件库 树/授权/搜索 API |
+| `routes/fileRoutes.ts` | 文件库 文件内容/导出 API |
+| `routes/libraryPage.ts` | `/database/library` 文件库浏览页 |
+| `filelib/` | 文件库领域层(见下) |
+
+新增一类端点时：要么直接往 `databaseRoutes.ts` 加 `app.get("/database/...")`，
+要么新建 `routes/xxxRoutes.ts` 并在 `databaseRoutes.ts` 里 `registerXxxRoutes(app, {...})`
+注册一次。
+
+## 文件库(filelib/)
+
+独立文件库模块,语义由仓库根《文件库-接口契约.md》(C/D 编号)与
+`.omo/文件库-开工计划.md`(D11–D19)锚定。**与 hub 自己的 Folder/Project
+(ADR-0021 explorer)是两套体系,不复用。**
+
+| 文件 | 职责 |
+|------|------|
+| `filelib/model.ts` | 角色秩(MANAGE>EDIT>VIEW)、D14 命名规则、FileLibError |
+| `filelib/permission.ts` | 纯权限 reducer(取最高/不降权/祖先继承/D11 冻结),不碰 IO |
+| `filelib/treeService.ts` | 树增删改查;每个写操作同事务落审计 |
+| `filelib/grantService.ts` | 授权管理 + 契约 8.1 矩阵强制 + force_adjust |
+| `filelib/fileService.ts` | 文件路径安全 + 版本化读写(先 git 后审计的顺序铁律) |
+| `filelib/exportService.ts` | 导出 job 状态机(D10 异步)+ ExportAdapter port |
+| `filelib/versionStore.ts` | 契约 C1 port + 内存实现(版本团队 npm 包到位后替换) |
+| `filelib/groupResolver.ts` | 契约 C2 port + Team 过渡实现 |
+| `filelib/groupResolverHttp.ts` | C2 HTTP 实现(HUB_GROUP_SERVICE_URL 启用;失败 → 503) |
+| `filelib/audit.ts` | 审计动作词表(C3 §6.3)+ 同事务写入 |
+| `filelib/guards.ts` | session → FileLibActor;网站管理员 = org OWNER/ADMIN(D19) |
+| `filelib/routeShared.ts` | 路由共享件(依赖装配/错误映射/请求体校验) |
+
+环境变量:
+
+- `HUB_FILELIB_STORAGE_ROOT` — 项目 git 仓库根目录(默认 `./.filelib-repos`)
+- `HUB_GROUP_SERVICE_URL` — Group 团队服务地址(C2);未配置时读 hub Team(扁平)
+
+> ⚠️ 开发期注意:当前 VersionStore 是**进程内存**实现,**服务重启后仓库全失**,
+> 此前创建的项目再访问文件会报 `repo_not_found`(需重建项目)。版本团队的
+> 持久化 git 包到位后此问题消失。
+
+关键语义速查:
+
+- **D8**:无权限 → 404(不泄露存在性);越权 → 403;Group 服务故障 → 503
+- **D11**:creator 不可变 + 自动 MANAGE;独立权限关闭时项目级非创建者 grant 冻结
+- **D12**:move = 本节点 MANAGE + 目标父 EDIT+,事务 + pg 咨询锁
+- **D15**:删除只打标本节点,"任一祖先已删"即整支不可见
+- **8.1**:MANAGE 仅创建者可授/收;creator grant 不可动
+- **审计**:一切写操作在业务事务内写 AuditEntry(同事务,失败即回滚);
+  文件内容写先 versionStore.commit 再审计(宁多版本,不造假审计)
+
+## 约定（与 admin 面一致）
+
+1. 路由用**绝对路径** `"/database/..."`，不用 Fastify prefix —— 每条路由 grep 得到。
+2. **guard 前置、fail closed**：凡碰数据的端点第一行先跑
+   `requireSession` / `requireOrgRole` / `requireProjectPermission`
+   （都在 `../admin/auth/guards.js`）。
+3. **租户隔离**（ADR-0020）：每个 Prisma 查询都 scope 到 `auth.organization.id`，
+   不得跨 org。禁止无鉴权的数据路由。
+4. 数据库通过传入的 `config.prisma` 访问（全进程单例，见 `../db.ts`）；
+   不要在这里 `new PrismaClient()`。
+
+## 为什么代码在 `src/` 下
+
+`tsconfig.json` 固定 `rootDir: "src"` 且 `include: ["src/**/*.ts"]`。只有
+`src/` 下的 `.ts` 会被 `tsc` 编译、被 `tsx watch`（`npm run dev`）加载。放在
+`src/` 之外的目录不会被构建，外部识别不到。

hub/src/database/filelib/audit.ts

@@ -0,0 +1,72 @@
+/**
+ * 文件库审计 sink(契约 C3 的入驻适配)。
+ *
+ * 契约原文:本地 outbox 表(与业务同事务)→ 中继 POST 到独立审计服务。
+ * 入驻 hub 后的适配:审计同事 = 本库 AuditEntry,与业务写在同一 Prisma 事务
+ * 内落库 —— 同库同事务天然满足"操作成功则日志必存在",比 outbox+relay 更强。
+ * 若审计团队日后独立成服务,只换本文件的实现,action 词汇表保持不变。
+ */
+
+import type { Prisma } from "@prisma/client";
+
+/** C3 §6.3:文件库审计动作词汇表(与契约文档逐条对应,改词需升契约版本)。 */
+export const FILE_LIB_AUDIT_ACTIONS = {
+  folderCreate: "folder.create",
+  folderRename: "folder.rename",
+  folderMove: "folder.move",
+  folderDelete: "folder.delete",
+  projectCreate: "project.create",
+  projectRename: "project.rename",
+  projectMove: "project.move",
+  projectDelete: "project.delete",
+  permissionGrant: "permission.grant",
+  permissionUpdate: "permission.update",
+  permissionRevoke: "permission.revoke",
+  independentEnable: "project.independent_permission.enable",
+  independentDisable: "project.independent_permission.disable",
+  independentChange: "project.independent_permission.change",
+  fileUpload: "file.upload",
+  fileRename: "file.rename",
+  fileDelete: "file.delete",
+  fileCommit: "file.commit",
+  fileConflictDetected: "file.conflict_detected",
+  exportRun: "export.run",
+  adminForceAdjust: "admin.force_adjust",
+} as const;
+
+export type FileLibAuditObjectType = "folder" | "project" | "file" | "grant" | "export_job";
+
+export interface FileLibAuditEntry {
+  readonly action: string;
+  readonly actorUserId: string;
+  readonly organizationId: string;
+  readonly objectType: FileLibAuditObjectType;
+  readonly objectId: string;
+  /** 节点 id 路径(pathIds)或项目内文件路径,便于按路径检索。 */
+  readonly objectPath: string;
+  readonly detail?: Record<string, unknown> | undefined;
+}
+
+/**
+ * 在调用方的事务里写一条审计。刻意不吞错:写不出来整个业务操作回滚
+ * (需求 5.1"操作成功则日志必存在"的强保证)。
+ */
+export async function writeFileLibAudit(
+  tx: Prisma.TransactionClient,
+  entry: FileLibAuditEntry,
+): Promise<void> {
+  const metadata: Record<string, unknown> = {
+    objectType: entry.objectType,
+    objectId: entry.objectId,
+    objectPath: entry.objectPath,
+    ...(entry.detail ?? {}),
+  };
+  await tx.auditEntry.create({
+    data: {
+      action: entry.action,
+      actorUserId: entry.actorUserId,
+      organizationId: entry.organizationId,
+      metadata: metadata as Prisma.InputJsonValue,
+    },
+  });
+}

hub/src/database/filelib/exportService.ts

@@ -0,0 +1,195 @@
+/**
+ * 导出(契约 D10):异步任务 + 状态机 QUEUED → RUNNING → DONE/FAILED。
+ *
+ * ExportAdapter 是外部导出工具的 port(参数清单 OPEN-6,真身到位后替换)。
+ * 当前 stub 适配器产出"文件清单 manifest"文本,证明状态机端到端可跑;
+ * 产物存进程内存(v1 stub;生产应落对象存储/磁盘 —— 见 OPEN 清单)。
+ */
+
+import { randomUUID } from "node:crypto";
+import { FileLibError } from "./model.js";
+import { FILE_LIB_AUDIT_ACTIONS, writeFileLibAudit } from "./audit.js";
+import { requireAccessInTx, type FileLibActor } from "./treeService.js";
+import type { FileDeps } from "./fileService.js";
+
+export interface ExportAdapterInput {
+  readonly storageDir: string;
+  readonly target: string;
+  readonly params: Record<string, unknown>;
+  readonly listFiles: (prefix?: string) => Promise<readonly { path: string; size: number }[]>;
+  readonly readFile: (path: string) => Promise<Buffer>;
+}
+
+export interface ExportArtifact {
+  readonly filename: string;
+  readonly content: Buffer;
+}
+
+export interface ExportAdapter {
+  readonly target: string;
+  run(input: ExportAdapterInput): Promise<ExportArtifact>;
+}
+
+/** stub 适配器:生成项目文件清单,端到端验证 job 状态机。OPEN-6 后换真导出工具。 */
+export function createManifestStubAdapter(versionStore: FileDeps["versionStore"]): ExportAdapter {
+  return {
+    target: "manifest",
+    async run(input) {
+      const files = await input.listFiles();
+      const lines = [
+        `# Export manifest (stub adapter)`,
+        `target: ${input.target}`,
+        `storageDir: ${input.storageDir}`,
+        `files: ${files.length}`,
+        ``,
+        ...files.map((f) => `${String(f.size).padStart(10)}  ${f.path}`),
+      ];
+      return { filename: "manifest.txt", content: Buffer.from(lines.join("\n"), "utf8") };
+    },
+  };
+}
+
+// v1 stub 产物存储(进程内存,重启即失;生产替换为持久存储)。
+const artifacts = new Map<string, ExportArtifact>();
+
+export interface ExportDeps extends FileDeps {
+  readonly adapters: readonly ExportAdapter[];
+}
+
+export interface ExportJobDto {
+  readonly id: string;
+  readonly nodeId: string;
+  readonly target: string;
+  readonly status: "QUEUED" | "RUNNING" | "DONE" | "FAILED";
+  readonly error: string | null;
+  readonly createdAt: Date;
+}
+
+/** 提交导出(需 VIEW):建行(QUEUED)+ export.run 审计,同事务;异步执行。 */
+export async function submitExport(
+  deps: ExportDeps,
+  actor: FileLibActor,
+  projectId: string,
+  target: string,
+  params: Record<string, unknown>,
+): Promise<ExportJobDto> {
+  const { node } = await deps.prisma.$transaction(async (tx) =>
+    requireAccessInTx(tx, deps, actor, projectId, "VIEW"),
+  );
+  if (node.kind !== "PROJECT") {
+    throw new FileLibError(400, "invalid_node_kind", "export applies to projects only");
+  }
+  const adapter = deps.adapters.find((a) => a.target === target);
+  if (adapter === undefined) {
+    throw new FileLibError(400, "unknown_target", `no export adapter for target "${target}"`);
+  }
+  if (node.storageDir === null) {
+    throw new FileLibError(409, "project_not_ready", "project repository is not ready");
+  }
+
+  const jobId = randomUUID();
+  const job = await deps.prisma.$transaction(async (tx) => {
+    const created = await tx.fileLibExportJob.create({
+      data: {
+        id: jobId,
+        organizationId: deps.organizationId,
+        nodeId: node.id,
+        target,
+        params: params as never,
+        status: "QUEUED",
+        createdByUserId: actor.userId,
+      },
+    });
+    await writeFileLibAudit(tx, {
+      action: FILE_LIB_AUDIT_ACTIONS.exportRun,
+      actorUserId: actor.userId,
+      organizationId: deps.organizationId,
+      objectType: "export_job",
+      objectId: jobId,
+      objectPath: node.pathIds,
+      detail: { target, params },
+    });
+    return created;
+  });
+
+  const storageDir = node.storageDir;
+  setImmediate(() => {
+    void runExportJob(deps, adapter, jobId, storageDir, target, params).catch(() => undefined);
+  });
+  return toDto(job);
+}
+
+async function runExportJob(
+  deps: ExportDeps,
+  adapter: ExportAdapter,
+  jobId: string,
+  storageDir: string,
+  target: string,
+  params: Record<string, unknown>,
+): Promise<void> {
+  await deps.prisma.fileLibExportJob.update({ where: { id: jobId }, data: { status: "RUNNING" } });
+  try {
+    const artifact = await adapter.run({
+      storageDir,
+      target,
+      params,
+      listFiles: (prefix) => deps.versionStore.list(storageDir, prefix),
+      readFile: (path) => deps.versionStore.read(storageDir, path),
+    });
+    artifacts.set(jobId, artifact);
+    await deps.prisma.fileLibExportJob.update({
+      where: { id: jobId },
+      data: { status: "DONE", downloadUrl: `/database/api/exports/${jobId}/download` },
+    });
+  } catch (error) {
+    await deps.prisma.fileLibExportJob.update({
+      where: { id: jobId },
+      data: { status: "FAILED", error: String(error) },
+    });
+  }
+}
+
+export async function getExportJob(
+  deps: ExportDeps,
+  actor: FileLibActor,
+  jobId: string,
+): Promise<ExportJobDto> {
+  const job = await deps.prisma.fileLibExportJob.findFirst({
+    where: { id: jobId, organizationId: deps.organizationId },
+  });
+  if (job === null) throw new FileLibError(404, "export_not_found", "export job not found");
+  // D8:对源项目无 View → 404(不泄露 job 存在性)。
+  await deps.prisma.$transaction(async (tx) => requireAccessInTx(tx, deps, actor, job.nodeId, "VIEW"));
+  return toDto(job);
+}
+
+export async function downloadExport(
+  deps: ExportDeps,
+  actor: FileLibActor,
+  jobId: string,
+): Promise<ExportArtifact> {
+  await getExportJob(deps, actor, jobId);
+  const artifact = artifacts.get(jobId);
+  if (artifact === undefined) {
+    throw new FileLibError(409, "export_not_ready", "export artifact is not available");
+  }
+  return artifact;
+}
+
+function toDto(job: {
+  id: string;
+  nodeId: string;
+  target: string;
+  status: "QUEUED" | "RUNNING" | "DONE" | "FAILED";
+  error: string | null;
+  createdAt: Date;
+}): ExportJobDto {
+  return {
+    id: job.id,
+    nodeId: job.nodeId,
+    target: job.target,
+    status: job.status,
+    error: job.error,
+    createdAt: job.createdAt,
+  };
+}

hub/src/database/filelib/fileService.ts

@@ -0,0 +1,275 @@
+/**
+ * 文件内容服务(Phase 3):路径安全 + 版本化文件操作 + 审计。
+ *
+ * 顺序铁律(Metis 风险#1 的落地):
+ *  - 内容写:先 versionStore.commit(业务事实本体)→ 再 DB 事务(审计)。
+ *    宁多一个无审计的版本,不造一条假审计。
+ *  - conflict:写 file.conflict_detected(冲突本身就是事件),再抛 409。
+ *  - 读:随取随读,不写审计(需求 5.2 未列读操作)。
+ */
+
+import { FileLibError } from "./model.js";
+import { FILE_LIB_AUDIT_ACTIONS, writeFileLibAudit } from "./audit.js";
+import type { CommitResult, FileEntry, VersionInfo, VersionStore } from "./versionStore.js";
+import type { AccessDeps, FileLibActor } from "./treeService.js";
+import { requireAccessInTx } from "./treeService.js";
+import type { FileLibNode, PrismaClient } from "@prisma/client";
+
+export const FILE_PATH_MAX_LENGTH = 512;
+export const FILE_PATH_MAX_DEPTH = 32;
+export const FILE_CONTENT_MAX_BYTES = 10 * 1024 * 1024; // OPEN-5 初值
+
+const CONTROL_CHARS = /[\p{C}]/u;
+const FORBIDDEN_SEGMENTS = new Set(["", ".", "..", ".git"]);
+
+/**
+ * 路径安全(Metis 安全红线):NFC;拒绝反斜杠、控制字符、空段、
+ * "." / ".." / ".git" 段、绝对路径、超长/超深。返回规范化相对路径。
+ */
+export function validateFilePath(raw: string): string {
+  const normalized = raw.normalize("NFC");
+  if (normalized.length === 0 || normalized.length > FILE_PATH_MAX_LENGTH) {
+    throw new FileLibError(400, "invalid_path", `path must be 1..${FILE_PATH_MAX_LENGTH} characters`);
+  }
+  if (normalized.includes("\\")) {
+    throw new FileLibError(400, "invalid_path", "path must use '/' separators");
+  }
+  if (CONTROL_CHARS.test(normalized)) {
+    throw new FileLibError(400, "invalid_path", "path must not contain control characters");
+  }
+  const segments = normalized.split("/");
+  if (segments.length > FILE_PATH_MAX_DEPTH) {
+    throw new FileLibError(400, "invalid_path", `path depth exceeds ${FILE_PATH_MAX_DEPTH}`);
+  }
+  for (const segment of segments) {
+    if (FORBIDDEN_SEGMENTS.has(segment)) {
+      throw new FileLibError(400, "invalid_path", `forbidden path segment: "${segment}"`);
+    }
+  }
+  return normalized;
+}
+
+export interface FileDeps extends AccessDeps {
+  readonly prisma: PrismaClient;
+  readonly versionStore: VersionStore;
+}
+
+type ProjectChain = { readonly node: FileLibNode; readonly storageDir: string };
+
+async function requireProject(
+  deps: FileDeps,
+  actor: FileLibActor,
+  projectId: string,
+  minRole: "VIEW" | "EDIT",
+): Promise<ProjectChain> {
+  const { node } = await deps.prisma.$transaction(async (tx) =>
+    requireAccessInTx(tx, deps, actor, projectId, minRole),
+  );
+  if (node.kind !== "PROJECT") {
+    throw new FileLibError(400, "invalid_node_kind", "file operations apply to projects only");
+  }
+  if (node.provisionStatus === "PROVISIONING") {
+    throw new FileLibError(409, "project_not_ready", "project repository is still provisioning");
+  }
+  if (node.provisionStatus === "FAILED") {
+    throw new FileLibError(409, "project_not_ready", "project repository provisioning failed");
+  }
+  if (node.storageDir === null) {
+    throw new FileLibError(500, "storage_missing", "project has no storage directory");
+  }
+  return { node, storageDir: node.storageDir };
+}
+
+export type FileContentEncoding = "utf8" | "base64";
+
+export interface FileContentDto {
+  readonly path: string;
+  readonly version: string;
+  readonly encoding: FileContentEncoding;
+  readonly content: string;
+  readonly size: number;
+}
+
+export function decodeContent(content: string, encoding: FileContentEncoding): string | Buffer {
+  return encoding === "base64" ? Buffer.from(content, "base64") : content;
+}
+
+function encodeContent(buffer: Buffer): { readonly encoding: FileContentEncoding; readonly content: string } {
+  // 粗判二进制:含 NUL 字节即按 base64 返回(需求 2.5 在线编辑仅针对文本)。
+  return buffer.includes(0)
+    ? { encoding: "base64", content: buffer.toString("base64") }
+    : { encoding: "utf8", content: buffer.toString("utf8") };
+}
+
+function checkSize(content: string | Buffer): void {
+  const bytes = typeof content === "string" ? Buffer.byteLength(content, "utf8") : content.byteLength;
+  if (bytes > FILE_CONTENT_MAX_BYTES) {
+    throw new FileLibError(413, "file_too_large", `file exceeds ${FILE_CONTENT_MAX_BYTES} bytes`);
+  }
+}
+
+async function auditFile(
+  deps: FileDeps,
+  actor: FileLibActor,
+  action: string,
+  project: ProjectChain,
+  filePath: string,
+  detail: Record<string, unknown>,
+): Promise<void> {
+  await deps.prisma.$transaction(async (tx) => {
+    await writeFileLibAudit(tx, {
+      action,
+      actorUserId: actor.userId,
+      organizationId: deps.organizationId,
+      objectType: "file",
+      objectId: project.node.id,
+      objectPath: `${project.node.pathIds}:${filePath}`,
+      detail,
+    });
+  });
+}
+
+/* ---------------------------------------------------------------- 读操作 */
+
+export async function listFiles(
+  deps: FileDeps,
+  actor: FileLibActor,
+  projectId: string,
+  prefix?: string,
+): Promise<readonly FileEntry[]> {
+  const project = await requireProject(deps, actor, projectId, "VIEW");
+  return deps.versionStore.list(project.storageDir, prefix === undefined ? undefined : validateFilePath(prefix));
+}
+
+export async function readFile(
+  deps: FileDeps,
+  actor: FileLibActor,
+  projectId: string,
+  rawPath: string,
+): Promise<FileContentDto> {
+  const filePath = validateFilePath(rawPath);
+  const project = await requireProject(deps, actor, projectId, "VIEW");
+  const [version, buffer] = await Promise.all([
+    deps.versionStore.head(project.storageDir, filePath),
+    deps.versionStore.read(project.storageDir, filePath),
+  ]);
+  const { encoding, content } = encodeContent(buffer);
+  return { path: filePath, version, encoding, content, size: buffer.byteLength };
+}
+
+/** 原始字节下载(浏览器 save-as 用):JSON 之外的第二条读取通道,同样的 VIEW 门禁。 */
+export async function readFileRaw(
+  deps: FileDeps,
+  actor: FileLibActor,
+  projectId: string,
+  rawPath: string,
+): Promise<{ readonly buffer: Buffer; readonly version: string; readonly filename: string }> {
+  const filePath = validateFilePath(rawPath);
+  const project = await requireProject(deps, actor, projectId, "VIEW");
+  const [version, buffer] = await Promise.all([
+    deps.versionStore.head(project.storageDir, filePath),
+    deps.versionStore.read(project.storageDir, filePath),
+  ]);
+  return { buffer, version, filename: filePath.split("/").pop() ?? "download" };
+}
+
+export async function fileHistory(
+  deps: FileDeps,
+  actor: FileLibActor,
+  projectId: string,
+  rawPath: string,
+  limit?: number,
+): Promise<readonly VersionInfo[]> {
+  const filePath = validateFilePath(rawPath);
+  const project = await requireProject(deps, actor, projectId, "VIEW");
+  return deps.versionStore.history(project.storageDir, filePath, limit);
+}
+
+export async function diffFile(
+  deps: FileDeps,
+  actor: FileLibActor,
+  projectId: string,
+  rawPath: string,
+  from: string,
+  to: string,
+): Promise<{ readonly diff: string }> {
+  const filePath = validateFilePath(rawPath);
+  const project = await requireProject(deps, actor, projectId, "VIEW");
+  return { diff: await deps.versionStore.diff(project.storageDir, filePath, from, to) };
+}
+
+/* ---------------------------------------------------------------- 写操作 */
+
+export interface CommitInput {
+  readonly path: string;
+  /** null = 新建(已存在则 409);编辑时传 readFile 拿到的 version。 */
+  readonly baseVersion: string | null;
+  readonly content: string;
+  readonly encoding?: FileContentEncoding | undefined;
+  readonly message?: string | undefined;
+}
+
+/**
+ * 统一写入口(上传/编辑共用):先 commit,成功写 file.commit / file.upload 审计;
+ * 冲突写 file.conflict_detected 后抛 409(details 带 currentVersion,编辑 UI 用它拉 diff)。
+ */
+export async function commitFile(
+  deps: FileDeps,
+  actor: FileLibActor,
+  projectId: string,
+  input: CommitInput,
+): Promise<{ readonly version: string }> {
+  const filePath = validateFilePath(input.path);
+  const content = decodeContent(input.content, input.encoding ?? "utf8");
+  checkSize(content);
+  const project = await requireProject(deps, actor, projectId, "EDIT");
+
+  const result: CommitResult = await deps.versionStore.commit(project.storageDir, filePath, {
+    baseVersion: input.baseVersion,
+    content,
+    message: input.message,
+    author: actor.userId,
+  });
+
+  if (result.status === "conflict") {
+    await auditFile(deps, actor, FILE_LIB_AUDIT_ACTIONS.fileConflictDetected, project, filePath, {
+      baseVersion: input.baseVersion,
+      currentVersion: result.currentVersion,
+    });
+    throw new FileLibError(409, "version_conflict", "file was modified since baseVersion", {
+      currentVersion: result.currentVersion,
+    });
+  }
+
+  await auditFile(
+    deps,
+    actor,
+    input.baseVersion === null ? FILE_LIB_AUDIT_ACTIONS.fileUpload : FILE_LIB_AUDIT_ACTIONS.fileCommit,
+    project,
+    filePath,
+    { version: result.version, message: input.message ?? null },
+  );
+  return { version: result.version };
+}
+
+export async function deleteFile(
+  deps: FileDeps,
+  actor: FileLibActor,
+  projectId: string,
+  rawPath: string,
+  baseVersion: string,
+): Promise<void> {
+  const filePath = validateFilePath(rawPath);
+  const project = await requireProject(deps, actor, projectId, "EDIT");
+  const result = await deps.versionStore.remove(project.storageDir, filePath, baseVersion);
+  if (result.status === "conflict") {
+    await auditFile(deps, actor, FILE_LIB_AUDIT_ACTIONS.fileConflictDetected, project, filePath, {
+      baseVersion,
+      currentVersion: result.currentVersion,
+    });
+    throw new FileLibError(409, "version_conflict", "file was modified since baseVersion", {
+      currentVersion: result.currentVersion,
+    });
+  }
+  await auditFile(deps, actor, FILE_LIB_AUDIT_ACTIONS.fileDelete, project, filePath, { baseVersion });
+}

hub/src/database/filelib/grantService.ts

@@ -0,0 +1,319 @@
+/**
+ * 授权管理(契约 8.1 矩阵的服务端强制)。
+ *
+ * 矩阵:
+ *  - 创建者(creatorId 不可变):可授/改/收 MANAGE、EDIT、VIEW;自身 creator grant 不可动
+ *  - MANAGE 持有者:可授/改/收 EDIT、VIEW;不可碰 MANAGE;不可动创建者
+ *  - EDIT/VIEW:无授权能力(requireAccess MANAGE 已挡)
+ *  - 网站管理员:走 forceAdjustGrants(不查节点权限,D19),全部留 admin.force_adjust 审计
+ *
+ * D8:目标节点不可见/无权限 → 404;有权限但矩阵禁止 → 403。
+ */
+
+import { Prisma } from "@prisma/client";
+import type { FileLibGrant, FileLibNode, PrismaClient } from "@prisma/client";
+import { FileLibError, type FileLibRole } from "./model.js";
+import { FILE_LIB_AUDIT_ACTIONS, writeFileLibAudit } from "./audit.js";
+import {
+  requireAccessInTx,
+  type AccessDeps,
+  type FileLibActor,
+  type InitialGrant,
+} from "./treeService.js";
+
+export interface GrantDto {
+  readonly id: string;
+  readonly principalType: "USER" | "GROUP";
+  readonly principalId: string;
+  readonly role: FileLibRole;
+  readonly isCreatorGrant: boolean;
+  readonly createdAt: Date;
+}
+
+function toDto(grant: FileLibGrant): GrantDto {
+  return {
+    id: grant.id,
+    principalType: grant.principalType,
+    principalId: grant.principalId,
+    role: grant.role,
+    isCreatorGrant: grant.isCreatorGrant,
+    createdAt: grant.createdAt,
+  };
+}
+
+type Tx = Prisma.TransactionClient;
+type Deps = AccessDeps & { readonly prisma: PrismaClient };
+
+/** MANAGE 门禁:带 tx 时用调用方事务(与后续写同绳),不带时自开一个。 */
+async function requireManage(
+  deps: Deps,
+  actor: FileLibActor,
+  nodeId: string,
+  tx?: Tx,
+): Promise<{ readonly node: FileLibNode; readonly role: FileLibRole }> {
+  if (tx !== undefined) return requireAccessInTx(tx, deps, actor, nodeId, "MANAGE");
+  return deps.prisma.$transaction(async (inner) => requireAccessInTx(inner, deps, actor, nodeId, "MANAGE"));
+}
+
+/** 列出节点活跃授权(需 MANAGE)。 */
+export async function listGrants(
+  deps: Deps,
+  actor: FileLibActor,
+  nodeId: string,
+): Promise<readonly GrantDto[]> {
+  await requireManage(deps, actor, nodeId);
+  const grants = await deps.prisma.fileLibGrant.findMany({
+    where: { organizationId: deps.organizationId, nodeId, revokedAt: null },
+    orderBy: [{ isCreatorGrant: "desc" }, { createdAt: "asc" }],
+  });
+  return grants.map(toDto);
+}
+
+export interface PutGrantsResult {
+  readonly granted: number;
+  readonly updated: number;
+  readonly grants: readonly GrantDto[];
+}
+
+/**
+ * 批量授予/修改(upsert 语义):同 principal 已有活跃授权 → 改级别(permission.update);
+ * 没有 → 新建(permission.grant)。8.1 矩阵在写之前整体校验。
+ */
+export async function putGrants(
+  deps: Deps,
+  actor: FileLibActor,
+  nodeId: string,
+  items: readonly InitialGrant[],
+): Promise<PutGrantsResult> {
+  validateGrantItems(items);
+  return deps.prisma.$transaction(async (tx) => {
+    const { node } = await requireManage(deps, actor, nodeId, tx);
+    const isCreator = node.creatorId === actor.userId;
+    for (const item of items) {
+      if (item.role === "MANAGE" && !isCreator) {
+        throw new FileLibError(403, "only_creator_can_grant_manage", "only the creator can grant MANAGE");
+      }
+      if (item.principalType === "USER" && item.principalId === node.creatorId) {
+        throw new FileLibError(403, "cannot_touch_creator", "the creator's grant is immutable");
+      }
+    }
+
+    let granted = 0;
+    let updated = 0;
+    for (const item of items) {
+      const existing = await tx.fileLibGrant.findFirst({
+        where: {
+          nodeId: node.id,
+          principalType: item.principalType,
+          principalId: item.principalId,
+          revokedAt: null,
+        },
+      });
+      if (existing !== null) {
+        if (existing.isCreatorGrant) {
+          throw new FileLibError(403, "cannot_touch_creator", "the creator's grant is immutable");
+        }
+        if (existing.role !== item.role) {
+          await tx.fileLibGrant.update({ where: { id: existing.id }, data: { role: item.role } });
+          updated += 1;
+          await audit(tx, deps, actor, FILE_LIB_AUDIT_ACTIONS.permissionUpdate, node.id, node.pathIds, { ...item });
+        }
+      } else {
+        await tx.fileLibGrant.create({
+          data: {
+            organizationId: deps.organizationId,
+            nodeId: node.id,
+            principalType: item.principalType,
+            principalId: item.principalId,
+            role: item.role,
+            createdByUserId: actor.userId,
+          },
+        });
+        granted += 1;
+        await audit(tx, deps, actor, FILE_LIB_AUDIT_ACTIONS.permissionGrant, node.id, node.pathIds, { ...item });
+      }
+    }
+    const grants = await tx.fileLibGrant.findMany({
+      where: { organizationId: deps.organizationId, nodeId: node.id, revokedAt: null },
+      orderBy: [{ isCreatorGrant: "desc" }, { createdAt: "asc" }],
+    });
+    return { granted, updated, grants: grants.map(toDto) };
+  });
+}
+
+/** 收回授权(需 MANAGE;creator grant 与 MANAGE grant 有额外限制,见 8.1)。 */
+export async function revokeGrant(
+  deps: Deps,
+  actor: FileLibActor,
+  nodeId: string,
+  grantId: string,
+): Promise<void> {
+  await deps.prisma.$transaction(async (tx) => {
+    const { node } = await requireManage(deps, actor, nodeId, tx);
+    const grant = await tx.fileLibGrant.findFirst({
+      where: { id: grantId, nodeId: node.id, revokedAt: null },
+    });
+    if (grant === null) throw new FileLibError(404, "grant_not_found", "grant not found");
+    if (grant.isCreatorGrant) {
+      throw new FileLibError(403, "cannot_touch_creator", "the creator's grant is immutable");
+    }
+    if (grant.role === "MANAGE" && node.creatorId !== actor.userId) {
+      throw new FileLibError(403, "only_creator_can_revoke_manage", "only the creator can revoke MANAGE");
+    }
+    await tx.fileLibGrant.update({ where: { id: grant.id }, data: { revokedAt: new Date() } });
+    await audit(tx, deps, actor, FILE_LIB_AUDIT_ACTIONS.permissionRevoke, node.id, node.pathIds, {
+      principalType: grant.principalType,
+      principalId: grant.principalId,
+      role: grant.role,
+    });
+  });
+}
+
+/**
+ * 网站管理员强制调整(D19):凭 node id 操作,不查操作者节点权限;矩阵豁免;
+ * 每一条变更都落 admin.force_adjust 审计(高危留痕)。
+ */
+export async function forceAdjustGrants(
+  deps: Deps,
+  actor: FileLibActor,
+  nodeId: string,
+  items: readonly InitialGrant[],
+): Promise<PutGrantsResult> {
+  if (!actor.isWebsiteAdmin) {
+    throw new FileLibError(403, "forbidden", "force adjust requires website administrator");
+  }
+  validateGrantItems(items);
+  return deps.prisma.$transaction(async (tx) => {
+    const node = await tx.fileLibNode.findFirst({
+      where: { id: nodeId, organizationId: deps.organizationId, deletedAt: null },
+    });
+    if (node === null) throw new FileLibError(404, "node_not_found", "node not found");
+
+    let granted = 0;
+    let updated = 0;
+    for (const item of items) {
+      const existing = await tx.fileLibGrant.findFirst({
+        where: {
+          nodeId: node.id,
+          principalType: item.principalType,
+          principalId: item.principalId,
+          revokedAt: null,
+        },
+      });
+      if (existing !== null) {
+        if (existing.role !== item.role) {
+          await tx.fileLibGrant.update({ where: { id: existing.id }, data: { role: item.role } });
+          updated += 1;
+          await audit(tx, deps, actor, FILE_LIB_AUDIT_ACTIONS.adminForceAdjust, node.id, node.pathIds, {
+            change: "update",
+            principalType: item.principalType,
+            principalId: item.principalId,
+            from: existing.role,
+            to: item.role,
+          });
+        }
+      } else {
+        await tx.fileLibGrant.create({
+          data: {
+            organizationId: deps.organizationId,
+            nodeId: node.id,
+            principalType: item.principalType,
+            principalId: item.principalId,
+            role: item.role,
+            createdByUserId: actor.userId,
+          },
+        });
+        granted += 1;
+        await audit(tx, deps, actor, FILE_LIB_AUDIT_ACTIONS.adminForceAdjust, node.id, node.pathIds, {
+          change: "grant",
+          principalType: item.principalType,
+          principalId: item.principalId,
+          role: item.role,
+        });
+      }
+    }
+    const grants = await tx.fileLibGrant.findMany({
+      where: { organizationId: deps.organizationId, nodeId: node.id, revokedAt: null },
+      orderBy: [{ isCreatorGrant: "desc" }, { createdAt: "asc" }],
+    });
+    return { granted, updated, grants: grants.map(toDto) };
+  });
+}
+
+/** 项目独立权限开关(P5/D11):需 MANAGE;状态不变则空操作。 */
+export async function setIndependentPermission(
+  deps: Deps,
+  actor: FileLibActor,
+  nodeId: string,
+  enabled: boolean,
+): Promise<{ readonly enabled: boolean }> {
+  return deps.prisma.$transaction(async (tx) => {
+    const { node } = await requireManage(deps, actor, nodeId, tx);
+    if (node.kind !== "PROJECT") {
+      throw new FileLibError(400, "invalid_node_kind", "independent permission applies to projects only");
+    }
+    const current = await tx.fileLibProjectSettings.findUnique({
+      where: { nodeId: node.id },
+      select: { independentPermissionsEnabled: true },
+    });
+    if ((current?.independentPermissionsEnabled ?? false) === enabled) {
+      return { enabled }; // 状态未变:空操作,不产生审计
+    }
+    await tx.fileLibProjectSettings.upsert({
+      where: { nodeId: node.id },
+      update: { independentPermissionsEnabled: enabled },
+      create: { nodeId: node.id, independentPermissionsEnabled: enabled },
+    });
+    await writeFileLibAudit(tx, {
+      action: enabled
+        ? FILE_LIB_AUDIT_ACTIONS.independentEnable
+        : FILE_LIB_AUDIT_ACTIONS.independentDisable,
+      actorUserId: actor.userId,
+      organizationId: deps.organizationId,
+      objectType: "project",
+      objectId: node.id,
+      objectPath: node.pathIds,
+      detail: { enabled },
+    });
+    return { enabled };
+  });
+}
+
+function validateGrantItems(items: readonly InitialGrant[]): void {
+  if (items.length === 0) throw new FileLibError(400, "invalid_request", "grants must not be empty");
+  const seen = new Set<string>();
+  for (const item of items) {
+    if (item.principalType !== "USER" && item.principalType !== "GROUP") {
+      throw new FileLibError(400, "invalid_request", `bad principalType: ${String(item.principalType)}`);
+    }
+    if (item.role !== "VIEW" && item.role !== "EDIT" && item.role !== "MANAGE") {
+      throw new FileLibError(400, "invalid_request", `bad role: ${String(item.role)}`);
+    }
+    if (item.principalId.trim() === "") {
+      throw new FileLibError(400, "invalid_request", "principalId must not be empty");
+    }
+    const key = `${item.principalType}:${item.principalId}`;
+    if (seen.has(key)) throw new FileLibError(400, "duplicate_principal", `duplicate principal: ${key}`);
+    seen.add(key);
+  }
+}
+
+async function audit(
+  tx: Prisma.TransactionClient,
+  deps: Deps,
+  actor: FileLibActor,
+  action: string,
+  nodeId: string,
+  pathIds: string,
+  detail: Record<string, unknown>,
+): Promise<void> {
+  await writeFileLibAudit(tx, {
+    action,
+    actorUserId: actor.userId,
+    organizationId: deps.organizationId,
+    objectType: "grant",
+    objectId: nodeId,
+    objectPath: pathIds,
+    detail,
+  });
+}

hub/src/database/filelib/groupResolver.ts

@@ -0,0 +1,48 @@
+/**
+ * GroupResolver port(契约 C2)。
+ *
+ * 权限计算只依赖这一个查询:"用户 → 所属 Group(含全部祖先)"。
+ * Group 系统(需求系统二:全局、无限嵌套)由别的团队交付;调用方只依赖此
+ * port,真身到位后替换实现,不换调用点。
+ */
+
+import type { PrismaClient } from "@prisma/client";
+
+export interface GroupResolver {
+  resolveMemberGroupIds(userId: string): Promise<readonly string[]>;
+}
+
+/**
+ * 过渡实现:读 hub 既有 Team(org 内、扁平无嵌套 → "祖先即自身")。
+ * 需求 3.2 的祖先递归语义在嵌套 Group 落地前无从谈起;此实现保证权限引擎
+ * 的 Group 通路今天就是真的,而不是 mock。
+ */
+export function createTeamGroupResolver(
+  prisma: PrismaClient,
+  organizationId: string,
+): GroupResolver {
+  return {
+    async resolveMemberGroupIds(userId) {
+      const memberships = await prisma.teamMembership.findMany({
+        where: {
+          userId,
+          revokedAt: null,
+          team: { organizationId, archivedAt: null },
+        },
+        select: { teamId: true },
+      });
+      return memberships.map((m) => m.teamId);
+    },
+  };
+}
+
+/** 单测 mock:静态 用户→组 映射。 */
+export function createStaticGroupResolver(
+  map: Readonly<Record<string, readonly string[]>>,
+): GroupResolver {
+  return {
+    async resolveMemberGroupIds(userId) {
+      return map[userId] ?? [];
+    },
+  };
+}

hub/src/database/filelib/groupResolverHttp.ts

@@ -0,0 +1,49 @@
+/**
+ * GroupResolver 的 HTTP 实现(契约 C2,Group 团队服务到位后启用,
+ * 经 HUB_GROUP_SERVICE_URL 配置)。
+ *
+ * 语义红线:
+ *  - 失败 → FileLibError(503, group_unavailable)。依赖故障不是"无权限",
+ *    绝不伪装成 404/403(计划 D13)。
+ *  - 我方绝不自己推祖先:返回什么用什么,不在本地补逻辑。
+ */
+
+import { FileLibError } from "./model.js";
+import type { GroupResolver } from "./groupResolver.js";
+
+export interface HttpGroupResolverConfig {
+  readonly baseUrl: string;
+  readonly timeoutMs?: number;
+  /** 测试可注入假 fetch;生产用全局 fetch。 */
+  readonly fetchFn?: typeof fetch;
+}
+
+export function createHttpGroupResolver(config: HttpGroupResolverConfig): GroupResolver {
+  const timeoutMs = config.timeoutMs ?? 2_000;
+  const fetchFn = config.fetchFn ?? fetch;
+  return {
+    async resolveMemberGroupIds(userId) {
+      const url = `${config.baseUrl.replace(/\/$/, "")}/groups/resolve-member-groups?userId=${encodeURIComponent(userId)}`;
+      let response: Response;
+      try {
+        response = await fetchFn(url, { signal: AbortSignal.timeout(timeoutMs) });
+      } catch (error) {
+        throw new FileLibError(503, "group_unavailable", `group service unreachable: ${String(error)}`);
+      }
+      if (!response.ok) {
+        throw new FileLibError(503, "group_unavailable", `group service returned ${response.status}`);
+      }
+      let body: unknown;
+      try {
+        body = await response.json();
+      } catch {
+        throw new FileLibError(503, "group_unavailable", "group service returned malformed JSON");
+      }
+      const groupIds = (body as { groupIds?: unknown }).groupIds;
+      if (!Array.isArray(groupIds) || groupIds.some((id) => typeof id !== "string")) {
+        throw new FileLibError(503, "group_unavailable", "group service returned malformed payload");
+      }
+      return groupIds as readonly string[];
+    },
+  };
+}

hub/src/database/filelib/guards.ts

@@ -0,0 +1,47 @@
+/**
+ * 文件库 HTTP 门禁(契约 C4 的入驻适配)。
+ *
+ * 身份链:hub session(飞书 OAuth / dev bypass)→ silo org membership。
+ * 网站管理员 = org 的 OWNER/ADMIN(D19:仅 root 创建与 force_adjust 特权,
+ * 不给内容读旁路);普通成员 = 任何活跃 membership;非成员 = 403。
+ */
+
+import type { FastifyReply, FastifyRequest } from "fastify";
+import type { OrganizationMemberRole, PrismaClient } from "@prisma/client";
+import { requireSession, sendError } from "../../admin/auth/guards.js";
+import type { FileLibActor } from "./treeService.js";
+
+export interface FileLibGuardDeps {
+  readonly prisma: PrismaClient;
+  readonly sessionSecret: string;
+  /** 文件库归属的 silo org(ADR-0020/0025)。 */
+  readonly organizationId: string;
+}
+
+const WEBSITE_ADMIN_ROLES: readonly OrganizationMemberRole[] = ["OWNER", "ADMIN"];
+
+/** 每个 /database/api/* 端点第一行调它;返回 null 时响应已发出,fail closed。 */
+export async function requireFileLibActor(
+  request: FastifyRequest,
+  reply: FastifyReply,
+  deps: FileLibGuardDeps,
+): Promise<FileLibActor | null> {
+  const auth = await requireSession(request, reply, {
+    prisma: deps.prisma,
+    sessionSecret: deps.sessionSecret,
+  });
+  if (auth === null) return null;
+
+  const membership = await deps.prisma.organizationMembership.findFirst({
+    where: { organizationId: deps.organizationId, userId: auth.user.id, revokedAt: null },
+    select: { role: true },
+  });
+  if (membership === null) {
+    await sendError(reply, 403, "forbidden", "not a member of this organization");
+    return null;
+  }
+  return {
+    userId: auth.user.id,
+    isWebsiteAdmin: WEBSITE_ADMIN_ROLES.includes(membership.role),
+  };
+}

hub/src/database/filelib/model.ts

@@ -0,0 +1,59 @@
+/**
+ * 文件库领域基础:角色秩、命名规则(D14)、错误类型。
+ *
+ * 语义锚定:仓库根《文件库-接口契约.md》(2.2 权限等级 / D8 可见性 / D14 命名)
+ * 与 .omo/文件库-开工计划.md。本模块是独立文件库,不复用 hub 的
+ * Folder/Project/PermissionGrant 体系。
+ */
+
+export const FILE_LIB_ROLES = ["VIEW", "EDIT", "MANAGE"] as const;
+export type FileLibRole = (typeof FILE_LIB_ROLES)[number];
+
+/** 契约 2.2:MANAGE > EDIT > VIEW,严格全序。 */
+export const ROLE_RANK: Record<FileLibRole, number> = { VIEW: 1, EDIT: 2, MANAGE: 3 };
+
+export function roleAtLeast(role: FileLibRole, min: FileLibRole): boolean {
+  return ROLE_RANK[role] >= ROLE_RANK[min];
+}
+
+/** 业务错误。statusCode 由路由层映射为 HTTP 响应(D8 语义在此层只表达为 code)。 */
+export class FileLibError extends Error {
+  constructor(
+    readonly statusCode: number,
+    readonly code: string,
+    message: string,
+    /** 结构化附加信息(如 409 时的 currentVersion),路由层并入错误响应。 */
+    readonly details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = "FileLibError";
+  }
+}
+
+export const NODE_NAME_MAX_LENGTH = 128;
+
+/** D14:禁 `/`;反斜杠同样禁止(它会变成存储路径的分隔符,且易用于伪装)。控制字符禁。 */
+const FORBIDDEN_NAME_CHARS = /[/\\\p{C}]/u;
+
+/**
+ * D14:NFC 归一化 + trim,然后校验长度与字符集。
+ * 违规抛 FileLibError(400, "invalid_name"),路由层原样透传。
+ */
+export function normalizeNodeName(raw: string): string {
+  const name = raw.normalize("NFC").trim();
+  if (name.length === 0) {
+    throw new FileLibError(400, "invalid_name", "name must not be empty");
+  }
+  if (name.length > NODE_NAME_MAX_LENGTH) {
+    throw new FileLibError(400, "invalid_name", `name exceeds ${NODE_NAME_MAX_LENGTH} characters`);
+  }
+  if (FORBIDDEN_NAME_CHARS.test(name)) {
+    throw new FileLibError(400, "invalid_name", "name must not contain '/', '\\' or control characters");
+  }
+  return name;
+}
+
+/** D14:活跃兄弟节点大小写不敏感唯一的比较键(DB 层另有部分唯一索引兜底)。 */
+export function nameKey(normalizedName: string): string {
+  return normalizedName.toLowerCase();
+}

hub/src/database/filelib/permission.ts

@@ -0,0 +1,74 @@
+/**
+ * 纯权限 reducer(契约 P6 / D11 / D8)。
+ *
+ * 设计约束(Metis 评审):本文件是纯函数层 —— 输入是"已解析好的" grant、祖先链
+ * 与用户组集合,不碰 DB / 网络。数据获取在 treeService。这样权限代数可以脱离
+ * 存储做密集单测与随机化不变量测试。
+ */
+
+import type { FileLibRole } from "./model.js";
+import { ROLE_RANK } from "./model.js";
+
+export interface FileLibGrantFact {
+  readonly nodeId: string;
+  readonly principalType: "USER" | "GROUP";
+  readonly principalId: string;
+  readonly role: FileLibRole;
+  readonly isCreatorGrant: boolean;
+}
+
+export interface EffectiveRoleInput {
+  /** 目标节点(self)。 */
+  readonly nodeId: string;
+  readonly nodeKind: "FOLDER" | "PROJECT";
+  /** 目标的全部祖先 id(不含 self,顺序无关)。 */
+  readonly ancestorIds: readonly string[];
+  /** 项目独立权限开关(D11/P5);文件夹忽略此值。 */
+  readonly independentPermissionsEnabled: boolean;
+  readonly userId: string;
+  /** C2 resolve 结果:用户直接所属 + 全部祖先 group 的 id 集合。 */
+  readonly groupIds: readonly string[];
+  /** self ∪ ancestors 上的全部活跃 grant(revokedAt 已由获取层过滤)。 */
+  readonly grants: readonly FileLibGrantFact[];
+}
+
+/**
+ * 契约 P6:effective(user, R) = max { grant.role | s ∈ {user} ∪ groups*(user),
+ * r ∈ {R} ∪ ancestors(R) };无匹配 → null(无任何权限)。
+ * "个人权限不能降权"在 max 语义下天然成立 —— 只取最高,不做减法。
+ *
+ * D11:目标为 PROJECT 且独立权限关闭时,项目级(挂在 self 上)非创建者 grant
+ * 冻结不参与计算;创建者的自动 grant(isCreatorGrant)始终生效。祖先链上的
+ * grant 不受开关影响。
+ */
+export function effectiveRole(input: EffectiveRoleInput): FileLibRole | null {
+  const onChain = new Set<string>([input.nodeId, ...input.ancestorIds]);
+  const groups = new Set(input.groupIds);
+  const freezeProjectGrants =
+    input.nodeKind === "PROJECT" && !input.independentPermissionsEnabled;
+
+  let best: FileLibRole | null = null;
+  for (const grant of input.grants) {
+    if (!onChain.has(grant.nodeId)) continue;
+    if (freezeProjectGrants && grant.nodeId === input.nodeId && !grant.isCreatorGrant) continue;
+    if (grant.principalType === "USER" && grant.principalId !== input.userId) continue;
+    if (grant.principalType === "GROUP" && !groups.has(grant.principalId)) continue;
+    if (best === null || ROLE_RANK[grant.role] > ROLE_RANK[best]) best = grant.role;
+  }
+  return best;
+}
+
+/**
+ * D8 可见性语义:
+ *  - 完全无权限(effective === null)→ "not_found"(路由层映射 404,不泄露存在性);
+ *  - 有权限但不足 → "forbidden"(路由层映射 403)。
+ */
+export type AccessVerdict =
+  | { readonly allowed: true; readonly role: FileLibRole }
+  | { readonly allowed: false; readonly reason: "not_found" | "forbidden" };
+
+export function checkAccess(effective: FileLibRole | null, min: FileLibRole): AccessVerdict {
+  if (effective === null) return { allowed: false, reason: "not_found" };
+  if (ROLE_RANK[effective] < ROLE_RANK[min]) return { allowed: false, reason: "forbidden" };
+  return { allowed: true, role: effective };
+}

hub/src/database/filelib/routeShared.ts

@@ -0,0 +1,89 @@
+/**
+ * /database/api/* 路由共享件:依赖装配、actor 门禁、统一错误映射。
+ * 约定(与 admin 面一致):绝对路径;guard 前置 fail closed;查询 scope 到 silo org。
+ */
+
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { Prisma } from "@prisma/client";
+import type { PrismaClient } from "@prisma/client";
+import { FileLibError } from "./model.js";
+import { requireFileLibActor } from "./guards.js";
+import type { FileLibActor, TreeServiceDeps } from "./treeService.js";
+import type { GroupResolver } from "./groupResolver.js";
+import type { VersionStore } from "./versionStore.js";
+import type { ExportAdapter } from "./exportService.js";
+
+export interface FileLibRouteDeps {
+  readonly prisma: PrismaClient;
+  readonly sessionSecret: string;
+  readonly organizationId: string;
+  readonly storageRoot: string;
+  readonly groupResolver: GroupResolver;
+  readonly versionStore: VersionStore;
+  readonly exportAdapters: readonly ExportAdapter[];
+}
+
+/** 组装 treeService 依赖(路由处理内直接使用)。 */
+export function treeDeps(deps: FileLibRouteDeps): TreeServiceDeps {
+  return {
+    prisma: deps.prisma,
+    groupResolver: deps.groupResolver,
+    versionStore: deps.versionStore,
+    organizationId: deps.organizationId,
+    storageRoot: deps.storageRoot,
+  };
+}
+
+/** 端点第一行调用;null = 响应已发(401/403),fail closed。 */
+export async function actorOrNull(
+  request: FastifyRequest,
+  reply: FastifyReply,
+  deps: FileLibRouteDeps,
+): Promise<FileLibActor | null> {
+  return requireFileLibActor(request, reply, {
+    prisma: deps.prisma,
+    sessionSecret: deps.sessionSecret,
+    organizationId: deps.organizationId,
+  });
+}
+
+/** 统一错误出口:FileLibError → 语义码;P2002 → 409;其余 → 500(不泄露内部)。 */
+export async function sendRouteError(reply: FastifyReply, error: unknown): Promise<void> {
+  if (error instanceof FileLibError) {
+    await reply.status(error.statusCode).send({
+      error: { code: error.code, message: error.message, ...(error.details ?? {}) },
+    });
+    return;
+  }
+  if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === "P2002") {
+    await reply.status(409).send({ error: { code: "conflict", message: "uniqueness conflict" } });
+    return;
+  }
+  reply.log.error({ err: error }, "filelib route: unexpected error");
+  await reply.status(500).send({ error: { code: "internal", message: "internal error" } });
+}
+
+/** 请求体轻量校验(抛 FileLibError 400)。 */
+export function bodyObject(body: unknown): Record<string, unknown> {
+  if (typeof body !== "object" || body === null || Array.isArray(body)) {
+    throw new FileLibError(400, "invalid_request", "request body must be a JSON object");
+  }
+  return body as Record<string, unknown>;
+}
+
+export function requireString(obj: Record<string, unknown>, key: string): string {
+  const value = obj[key];
+  if (typeof value !== "string" || value === "") {
+    throw new FileLibError(400, "invalid_request", `missing or invalid field: ${key}`);
+  }
+  return value;
+}
+
+export function optionalString(obj: Record<string, unknown>, key: string): string | undefined {
+  const value = obj[key];
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string") {
+    throw new FileLibError(400, "invalid_request", `invalid field: ${key}`);
+  }
+  return value;
+}

hub/src/database/filelib/treeService.ts

@@ -0,0 +1,598 @@
+/**
+ * 文件库树服务(Phase 1 服务层,Phase 2 路由直接调用)。
+ *
+ * 语义锚定:
+ *  - D8  无权限 → 404 不泄露;越权 → 403(loadChain / requireAccess)
+ *  - D11 creator 不可变 + 自动 MANAGE grant;独立权限开关语义在 permission.ts
+ *  - D12 move = 本节点 MANAGE + 目标父 EDIT+,事务 + pg 咨询锁防并发成环
+ *  - D14 命名规则(model.ts)+ 活跃兄弟唯一(DB 部分唯一索引兜底)
+ *  - D15 删除只打标本节点;"任一祖先已删"即整支不可见
+ *  - D17 breadcrumb 无 View 的祖先只给占位,不泄露名字
+ *  - 树表示:parentId 权威;pathIds 为 id 编码的派生物化路径(name 不入路径,
+ *    rename 不重写后代;move 用一次前缀重写维护)
+ *
+ * 网站管理员(D19)= silo org 的 OWNER/ADMIN(契约 C4 的入驻适配):仅 root 创建
+ * 与 force_adjust 特权,不隐式穿透内容权限 —— 本文件所有读路径对它同样走
+ * effectiveRole,没有 admin 旁路。
+ */
+
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { Prisma } from "@prisma/client";
+import type { PrismaClient, FileLibNode } from "@prisma/client";
+import {
+  FileLibError,
+  nameKey,
+  normalizeNodeName,
+  type FileLibRole,
+} from "./model.js";
+import { checkAccess, effectiveRole } from "./permission.js";
+import type { GroupResolver } from "./groupResolver.js";
+import type { VersionStore } from "./versionStore.js";
+import { FILE_LIB_AUDIT_ACTIONS, writeFileLibAudit } from "./audit.js";
+
+export interface FileLibActor {
+  readonly userId: string;
+  /** silo org OWNER/ADMIN(契约 C4 适配)。仅 root 创建/force_adjust 用,不给读旁路。 */
+  readonly isWebsiteAdmin: boolean;
+}
+
+export interface TreeServiceDeps {
+  readonly prisma: PrismaClient;
+  readonly groupResolver: GroupResolver;
+  readonly versionStore: VersionStore;
+  /** 文件库归属的 silo org(ADR-0020 租户隔离,一切查询 scope 到它)。 */
+  readonly organizationId: string;
+  /** 项目 git 仓库的磁盘根目录;项目仓 = <storageRoot>/<nodeId>。 */
+  readonly storageRoot: string;
+}
+
+/** 权限判定实际需要的最小依赖(grantService 等兄弟模块复用)。 */
+export type AccessDeps = Pick<TreeServiceDeps, "organizationId" | "groupResolver">;
+
+export interface InitialGrant {
+  readonly principalType: "USER" | "GROUP";
+  readonly principalId: string;
+  readonly role: FileLibRole;
+}
+
+type Tx = Prisma.TransactionClient;
+
+interface Chain {
+  readonly node: FileLibNode;
+  /** 根在前、直接父在后;不含 node 自身。 */
+  readonly ancestors: readonly FileLibNode[];
+}
+
+/* ---------------------------------------------------------------- 内部工具 */
+
+/** pathIds = "/rootId/.../selfId";切出祖先 id(不含 self)。 */
+function ancestorIdsOf(node: FileLibNode): string[] {
+  return node.pathIds.split("/").filter((seg) => seg !== "").slice(0, -1);
+}
+
+/** 取节点 + 祖先链(org scope);D15:自身或任一祖先已删 → 404。 */
+async function loadVisibleChain(
+  tx: Tx,
+  organizationId: string,
+  nodeId: string,
+): Promise<Chain> {
+  const node = await tx.fileLibNode.findFirst({ where: { id: nodeId, organizationId } });
+  if (node === null) throw new FileLibError(404, "node_not_found", "node not found");
+  const ancestorIds = ancestorIdsOf(node);
+  const ancestors = ancestorIds.length === 0
+    ? []
+    : await tx.fileLibNode.findMany({ where: { organizationId, id: { in: ancestorIds } } });
+  if (node.deletedAt !== null || ancestors.some((a) => a.deletedAt !== null)) {
+    // D15:已删子树对外"不存在"(D8 不泄露)。
+    throw new FileLibError(404, "node_not_found", "node not found");
+  }
+  const byId = new Map(ancestors.map((a) => [a.id, a]));
+  const ordered = ancestorIds
+    .map((id) => byId.get(id))
+    .filter((a): a is FileLibNode => a !== undefined);
+  return { node, ancestors: ordered };
+}
+
+/** 数据获取层:把 chain、grants、groups、toggle 装配成纯 reducer 的输入。 */
+async function resolveRole(
+  tx: Tx,
+  deps: AccessDeps,
+  actor: FileLibActor,
+  chain: Chain,
+): Promise<FileLibRole | null> {
+  const chainIds = [...chain.ancestors.map((a) => a.id), chain.node.id];
+  const grants = await tx.fileLibGrant.findMany({
+    where: { organizationId: deps.organizationId, revokedAt: null, nodeId: { in: chainIds } },
+    select: { nodeId: true, principalType: true, principalId: true, role: true, isCreatorGrant: true },
+  });
+  let independentPermissionsEnabled = false;
+  if (chain.node.kind === "PROJECT") {
+    const settings = await tx.fileLibProjectSettings.findUnique({
+      where: { nodeId: chain.node.id },
+      select: { independentPermissionsEnabled: true },
+    });
+    independentPermissionsEnabled = settings?.independentPermissionsEnabled ?? false;
+  }
+  const groupIds = await deps.groupResolver.resolveMemberGroupIds(actor.userId);
+  return effectiveRole({
+    nodeId: chain.node.id,
+    nodeKind: chain.node.kind,
+    ancestorIds: chain.ancestors.map((a) => a.id),
+    independentPermissionsEnabled,
+    userId: actor.userId,
+    groupIds,
+    grants,
+  });
+}
+
+/** D8 门禁:loadVisibleChain + resolveRole + checkAccess,失败抛 FileLibError。 */
+async function requireAccess(
+  tx: Tx,
+  deps: AccessDeps,
+  actor: FileLibActor,
+  nodeId: string,
+  minRole: FileLibRole,
+): Promise<Chain & { readonly role: FileLibRole }> {
+  const chain = await loadVisibleChain(tx, deps.organizationId, nodeId);
+  const role = await resolveRole(tx, deps, actor, chain);
+  const verdict = checkAccess(role, minRole);
+  if (!verdict.allowed) {
+    throw verdict.reason === "not_found"
+      ? new FileLibError(404, "node_not_found", "node not found")
+      : new FileLibError(403, "forbidden", `requires ${minRole}`);
+  }
+  return { ...chain, role: verdict.role };
+}
+
+/**
+ * 兄弟模块(grantService 等)共用的 tx 内门禁:在调用方自己的事务里做
+ * 权限校验,校验与后续写同一根事务绳,避免 check-tx / write-tx 之间的竞态。
+ */
+export async function requireAccessInTx(
+  tx: Tx,
+  deps: AccessDeps,
+  actor: FileLibActor,
+  nodeId: string,
+  minRole: FileLibRole,
+): Promise<Chain & { readonly role: FileLibRole }> {
+  return requireAccess(tx, deps, actor, nodeId, minRole);
+}
+
+/** P2002(活跃兄弟名部分唯一索引)→ 409。 */
+function rethrowNameConflict(error: unknown, name: string): never {
+  if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === "P2002") {
+    throw new FileLibError(409, "name_conflict", `an active sibling named "${name}" already exists`);
+  }
+  throw error;
+}
+
+function nodeAction(kind: FileLibNode["kind"], verb: "Create" | "Rename" | "Move" | "Delete"): string {
+  const table = kind === "PROJECT"
+    ? { Create: FILE_LIB_AUDIT_ACTIONS.projectCreate, Rename: FILE_LIB_AUDIT_ACTIONS.projectRename, Move: FILE_LIB_AUDIT_ACTIONS.projectMove, Delete: FILE_LIB_AUDIT_ACTIONS.projectDelete }
+    : { Create: FILE_LIB_AUDIT_ACTIONS.folderCreate, Rename: FILE_LIB_AUDIT_ACTIONS.folderRename, Move: FILE_LIB_AUDIT_ACTIONS.folderMove, Delete: FILE_LIB_AUDIT_ACTIONS.folderDelete };
+  return table[verb];
+}
+
+function validateInitialGrants(actor: FileLibActor, grants: readonly InitialGrant[]): void {
+  const seen = new Set<string>();
+  for (const grant of grants) {
+    const key = `${grant.principalType}:${grant.principalId}`;
+    if (seen.has(key)) throw new FileLibError(400, "duplicate_principal", `duplicate grant principal: ${key}`);
+    seen.add(key);
+    if (grant.principalType === "USER" && grant.principalId === actor.userId) {
+      throw new FileLibError(400, "duplicate_principal", "creator already holds MANAGE via the creator grant");
+    }
+    // v1:不校验 group 存在性(C2 未提供批量校验口;给不存在 group 的授权天然无效,不危害)。
+  }
+}
+
+/* ---------------------------------------------------------------- 公共操作 */
+
+export interface CreateNodeInput {
+  readonly parentId: string | null;
+  readonly kind: "FOLDER" | "PROJECT";
+  readonly name: string;
+  readonly description?: string | undefined;
+  readonly grants?: readonly InitialGrant[] | undefined;
+}
+
+/**
+ * 创建文件夹/项目。root 创建仅网站管理员(契约 2.1);非 root 需父节点 EDIT+。
+ * creator 自动 MANAGE(D11);项目走 provisioning 状态机:PROVISIONING → init → READY。
+ */
+export async function createNode(
+  deps: TreeServiceDeps,
+  actor: FileLibActor,
+  input: CreateNodeInput,
+): Promise<FileLibNode> {
+  const name = normalizeNodeName(input.name);
+  const initialGrants = input.grants ?? [];
+  validateInitialGrants(actor, initialGrants);
+
+  const id = randomUUID();
+  let pathIds: string;
+  let storageDir: string | null = null;
+
+  const created = await deps.prisma.$transaction(async (tx) => {
+    if (input.parentId === null) {
+      if (!actor.isWebsiteAdmin) {
+        throw new FileLibError(403, "forbidden", "root creation requires website administrator");
+      }
+      pathIds = `/${id}`;
+    } else {
+      const parent = await requireAccess(tx, deps, actor, input.parentId, "EDIT");
+      if (parent.node.kind !== "FOLDER") {
+        throw new FileLibError(400, "invalid_parent", "projects cannot have children");
+      }
+      pathIds = `${parent.node.pathIds}/${id}`;
+    }
+
+    if (input.kind === "PROJECT") {
+      storageDir = path.join(deps.storageRoot, id);
+    }
+
+    let node: FileLibNode;
+    try {
+      node = await tx.fileLibNode.create({
+        data: {
+          id,
+          organizationId: deps.organizationId,
+          parentId: input.parentId,
+          kind: input.kind,
+          name,
+          nameLower: nameKey(name),
+          pathIds,
+          creatorId: actor.userId,
+          provisionStatus: input.kind === "PROJECT" ? "PROVISIONING" : "READY",
+          storageDir,
+          ...(input.description !== undefined && input.description.trim() !== ""
+            ? { description: input.description.trim() }
+            : {}),
+        },
+      });
+    } catch (error) {
+      rethrowNameConflict(error, name);
+    }
+
+    await tx.fileLibGrant.create({
+      data: {
+        organizationId: deps.organizationId,
+        nodeId: id,
+        principalType: "USER",
+        principalId: actor.userId,
+        role: "MANAGE",
+        isCreatorGrant: true,
+        createdByUserId: actor.userId,
+      },
+    });
+    for (const grant of initialGrants) {
+      await tx.fileLibGrant.create({
+        data: {
+          organizationId: deps.organizationId,
+          nodeId: id,
+          principalType: grant.principalType,
+          principalId: grant.principalId,
+          role: grant.role,
+          createdByUserId: actor.userId,
+        },
+      });
+    }
+    if (input.kind === "PROJECT") {
+      await tx.fileLibProjectSettings.create({
+        data: { nodeId: id, independentPermissionsEnabled: false },
+      });
+    }
+
+    await writeFileLibAudit(tx, {
+      action: nodeAction(input.kind, "Create"),
+      actorUserId: actor.userId,
+      organizationId: deps.organizationId,
+      objectType: input.kind === "PROJECT" ? "project" : "folder",
+      objectId: id,
+      objectPath: pathIds,
+      detail: { name, parentId: input.parentId, initialGrants: initialGrants.length },
+    });
+    for (const grant of initialGrants) {
+      await writeFileLibAudit(tx, {
+        action: FILE_LIB_AUDIT_ACTIONS.permissionGrant,
+        actorUserId: actor.userId,
+        organizationId: deps.organizationId,
+        objectType: "grant",
+        objectId: id,
+        objectPath: pathIds,
+        detail: { principalType: grant.principalType, principalId: grant.principalId, role: grant.role },
+      });
+    }
+    return node;
+  });
+
+  // provisioning 状态机(Metis 风险#1):DB 行已持久,init 失败 → FAILED 可重试/对账。
+  if (input.kind === "PROJECT" && storageDir !== null) {
+    try {
+      await deps.versionStore.init(storageDir);
+      return await deps.prisma.fileLibNode.update({
+        where: { id: created.id },
+        data: { provisionStatus: "READY" },
+      });
+    } catch (error) {
+      await deps.prisma.fileLibNode
+        .update({ where: { id: created.id }, data: { provisionStatus: "FAILED" } })
+        .catch(() => undefined);
+      throw new FileLibError(500, "provision_failed", `repository initialization failed: ${String(error)}`);
+    }
+  }
+  return created;
+}
+
+/** 重命名(需本节点 MANAGE,契约 8.2)。id 路径不含 name,后代无需重写。 */
+export async function renameNode(
+  deps: TreeServiceDeps,
+  actor: FileLibActor,
+  nodeId: string,
+  rawName: string,
+): Promise<FileLibNode> {
+  const name = normalizeNodeName(rawName);
+  return deps.prisma.$transaction(async (tx) => {
+    const { node } = await requireAccess(tx, deps, actor, nodeId, "MANAGE");
+    let updated: FileLibNode;
+    try {
+      updated = await tx.fileLibNode.update({
+        where: { id: node.id },
+        data: { name, nameLower: nameKey(name) },
+      });
+    } catch (error) {
+      rethrowNameConflict(error, name);
+    }
+    await writeFileLibAudit(tx, {
+      action: nodeAction(node.kind, "Rename"),
+      actorUserId: actor.userId,
+      organizationId: deps.organizationId,
+      objectType: node.kind === "PROJECT" ? "project" : "folder",
+      objectId: node.id,
+      objectPath: node.pathIds,
+      detail: { from: node.name, to: name },
+    });
+    return updated;
+  });
+}
+
+/**
+ * 移动(D12):本节点 MANAGE + 目标父 EDIT+(移到 root 需网站管理员);
+ * 事务 + org 级咨询锁防并发成环;后代 pathIds 一次前缀重写。
+ */
+export async function moveNode(
+  deps: TreeServiceDeps,
+  actor: FileLibActor,
+  nodeId: string,
+  newParentId: string | null,
+): Promise<FileLibNode> {
+  return deps.prisma.$transaction(async (tx) => {
+    await tx.$executeRaw`SELECT pg_advisory_xact_lock(hashtext(${"filelib:tree:" + deps.organizationId}))`;
+
+    const { node } = await requireAccess(tx, deps, actor, nodeId, "MANAGE");
+    if (node.parentId === newParentId) return node;
+
+    let newPathIds: string;
+    if (newParentId === null) {
+      if (!actor.isWebsiteAdmin) {
+        throw new FileLibError(403, "forbidden", "moving to root requires website administrator");
+      }
+      newPathIds = `/${node.id}`;
+    } else {
+      const parent = await requireAccess(tx, deps, actor, newParentId, "EDIT");
+      if (parent.node.kind !== "FOLDER") {
+        throw new FileLibError(400, "invalid_parent", "projects cannot have children");
+      }
+      if (parent.node.id === node.id || parent.node.pathIds.startsWith(`${node.pathIds}/`)) {
+        throw new FileLibError(400, "move_into_own_subtree", "cannot move a node into its own subtree");
+      }
+      newPathIds = `${parent.node.pathIds}/${node.id}`;
+    }
+
+    const oldPrefix = node.pathIds;
+    let updated: FileLibNode;
+    try {
+      updated = await tx.fileLibNode.update({
+        where: { id: node.id },
+        data: { parentId: newParentId, pathIds: newPathIds },
+      });
+      // 派生列维护:整支后代的前缀重写(id 编码,与 name 无关)。
+      await tx.$executeRaw`
+        UPDATE "FileLibNode"
+        SET "pathIds" = ${newPathIds} || substring("pathIds" from ${oldPrefix.length + 1}::int)
+        WHERE "organizationId" = ${deps.organizationId}
+          AND "pathIds" LIKE ${oldPrefix + "/%"}
+      `;
+    } catch (error) {
+      rethrowNameConflict(error, node.name);
+    }
+    await writeFileLibAudit(tx, {
+      action: nodeAction(node.kind, "Move"),
+      actorUserId: actor.userId,
+      organizationId: deps.organizationId,
+      objectType: node.kind === "PROJECT" ? "project" : "folder",
+      objectId: node.id,
+      objectPath: newPathIds,
+      detail: { fromParentId: node.parentId, toParentId: newParentId },
+    });
+    return updated;
+  });
+}
+
+/** 软删除(D15):只打标本节点,后代靠"任一祖先已删"过滤;需 MANAGE。 */
+export async function softDeleteNode(
+  deps: TreeServiceDeps,
+  actor: FileLibActor,
+  nodeId: string,
+): Promise<void> {
+  await deps.prisma.$transaction(async (tx) => {
+    const { node } = await requireAccess(tx, deps, actor, nodeId, "MANAGE");
+    await tx.fileLibNode.update({ where: { id: node.id }, data: { deletedAt: new Date() } });
+    await writeFileLibAudit(tx, {
+      action: nodeAction(node.kind, "Delete"),
+      actorUserId: actor.userId,
+      organizationId: deps.organizationId,
+      objectType: node.kind === "PROJECT" ? "project" : "folder",
+      objectId: node.id,
+      objectPath: node.pathIds,
+      detail: { name: node.name },
+    });
+  });
+}
+
+/** 自查生效权限(契约 9.2 effective-permission)。D8:null 角色即不可见,404。 */
+export async function getEffectiveRole(
+  deps: TreeServiceDeps,
+  actor: FileLibActor,
+  nodeId: string,
+): Promise<FileLibRole | null> {
+  return deps.prisma.$transaction(async (tx) => {
+    const chain = await loadVisibleChain(tx, deps.organizationId, nodeId);
+    const role = await resolveRole(tx, deps, actor, chain);
+    if (role === null) throw new FileLibError(404, "node_not_found", "node not found");
+    return role;
+  });
+}
+
+export interface BreadcrumbEntry {
+  readonly depth: number;
+  /** D17:无 View 的祖先 id/name 都为 null(不泄露)。 */
+  readonly id: string | null;
+  readonly name: string | null;
+  readonly kind: "FOLDER" | "PROJECT";
+}
+
+/** D17 面包屑:需 self VIEW;链上每个节点单独算权限,无 View 只留占位。 */
+export async function breadcrumb(
+  deps: TreeServiceDeps,
+  actor: FileLibActor,
+  nodeId: string,
+): Promise<readonly BreadcrumbEntry[]> {
+  return deps.prisma.$transaction(async (tx) => {
+    const chain = await loadVisibleChain(tx, deps.organizationId, nodeId);
+    const selfRole = await resolveRole(tx, deps, actor, chain);
+    if (checkAccess(selfRole, "VIEW").allowed !== true) {
+      throw new FileLibError(404, "node_not_found", "node not found");
+    }
+    const groupIds = await deps.groupResolver.resolveMemberGroupIds(actor.userId);
+    const chainNodes = [...chain.ancestors, chain.node];
+    const chainIds = chainNodes.map((n) => n.id);
+    const allGrants = await tx.fileLibGrant.findMany({
+      where: { organizationId: deps.organizationId, revokedAt: null, nodeId: { in: chainIds } },
+      select: { nodeId: true, principalType: true, principalId: true, role: true, isCreatorGrant: true },
+    });
+    const settings = chain.node.kind === "PROJECT"
+      ? await tx.fileLibProjectSettings.findUnique({
+          where: { nodeId: chain.node.id },
+          select: { independentPermissionsEnabled: true },
+        })
+      : null;
+
+    return chainNodes.map((current, depth) => {
+      const role = effectiveRole({
+        nodeId: current.id,
+        nodeKind: current.kind,
+        ancestorIds: chainNodes.slice(0, depth).map((n) => n.id),
+        independentPermissionsEnabled:
+          current.id === chain.node.id ? settings?.independentPermissionsEnabled ?? false : false,
+        userId: actor.userId,
+        groupIds,
+        grants: allGrants,
+      });
+      const visible = role !== null;
+      return {
+        depth,
+        id: visible ? current.id : null,
+        name: visible ? current.name : null,
+        kind: current.kind,
+      };
+    });
+  });
+}
+
+export interface ChildNodeDto {
+  readonly id: string;
+  readonly parentId: string | null;
+  readonly kind: "FOLDER" | "PROJECT";
+  readonly name: string;
+  readonly role: FileLibRole;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+}
+
+/** 列子节点(parentId=null 列 root);只返回调用者有 View 的(D8/P7)。 */
+export async function listChildren(
+  deps: TreeServiceDeps,
+  actor: FileLibActor,
+  parentId: string | null,
+): Promise<readonly ChildNodeDto[]> {
+  return deps.prisma.$transaction(async (tx) => {
+    let parentAncestorIds: string[] = [];
+    if (parentId !== null) {
+      const parent = await requireAccess(tx, deps, actor, parentId, "VIEW");
+      parentAncestorIds = [...parent.ancestors.map((a) => a.id), parent.node.id];
+    }
+    const children = await tx.fileLibNode.findMany({
+      where: { organizationId: deps.organizationId, parentId, deletedAt: null },
+      orderBy: [{ kind: "asc" }, { nameLower: "asc" }],
+    });
+    if (children.length === 0) return [];
+
+    // D13:一次请求只 resolve 一次组、拉一次 grant 集,批量计算,不做 per-child 往返。
+    const idsToFetch = [...parentAncestorIds, ...children.map((c) => c.id)];
+    const allGrants = await tx.fileLibGrant.findMany({
+      where: { organizationId: deps.organizationId, revokedAt: null, nodeId: { in: idsToFetch } },
+      select: { nodeId: true, principalType: true, principalId: true, role: true, isCreatorGrant: true },
+    });
+    const projectIds = children.filter((c) => c.kind === "PROJECT").map((c) => c.id);
+    const settingsRows = projectIds.length === 0
+      ? []
+      : await tx.fileLibProjectSettings.findMany({
+          where: { nodeId: { in: projectIds } },
+          select: { nodeId: true, independentPermissionsEnabled: true },
+        });
+    const toggleByNode = new Map(settingsRows.map((s) => [s.nodeId, s.independentPermissionsEnabled]));
+    const groupIds = await deps.groupResolver.resolveMemberGroupIds(actor.userId);
+
+    const out: ChildNodeDto[] = [];
+    for (const child of children) {
+      const role = effectiveRole({
+        nodeId: child.id,
+        nodeKind: child.kind,
+        ancestorIds: parentAncestorIds,
+        independentPermissionsEnabled: toggleByNode.get(child.id) ?? false,
+        userId: actor.userId,
+        groupIds,
+        grants: allGrants,
+      });
+      if (role === null) continue;
+      out.push({
+        id: child.id,
+        parentId: child.parentId,
+        kind: child.kind,
+        name: child.name,
+        role,
+        createdAt: child.createdAt,
+        updatedAt: child.updatedAt,
+      });
+    }
+    return out;
+  });
+}
+
+/** 更新节点简介（需 EDIT+；不记审计，非权限敏感的内容字段）。 */
+export async function updateNodeDescription(
+  deps: TreeServiceDeps,
+  actor: FileLibActor,
+  nodeId: string,
+  description: string | null,
+): Promise<FileLibNode> {
+  return deps.prisma.$transaction(async (tx) => {
+    const { node } = await requireAccessInTx(tx, deps, actor, nodeId, "EDIT");
+    return tx.fileLibNode.update({
+      where: { id: node.id },
+      data: { description: description?.trim() || null },
+    });
+  });
+}

hub/src/database/filelib/versionStore.ts

@@ -0,0 +1,280 @@
+/**
+ * VersionStore port(契约 C1)+ 开发用内存实现。
+ *
+ * 版本团队交付 npm 工具包后,用同一接口替换 createInMemoryVersionStore。
+ * 语义红线(计划"Mock 保真红线"):冲突走返回值(S1)、baseVersion=null 表新建(S2)、
+ * init 幂等(S7)、同 projectDir 写操作串行化(S4)、文件级版本(D16)。
+ *
+ * 持久化:传 persistPath 时把仓库快照落盘(JSON),重启后恢复 —— 纯粹为开发期
+ * demo 稳定,不改变任何语义;生产由真包替换,此文件不参与。
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { FileLibError } from "./model.js";
+
+export type VersionId = string;
+
+export interface CommitRequest {
+  /** 编辑起始版本;null 表示新建文件(已存在则 conflict,S2)。 */
+  readonly baseVersion: VersionId | null;
+  readonly content: string | Buffer;
+  readonly message?: string | undefined;
+  readonly author?: string | undefined;
+}
+
+export type CommitResult =
+  | { readonly status: "ok"; readonly version: VersionId }
+  | { readonly status: "conflict"; readonly currentVersion: VersionId };
+
+export interface VersionInfo {
+  readonly version: VersionId;
+  readonly message: string;
+  readonly author: string | undefined;
+  readonly committedAt: string;
+}
+
+export interface FileEntry {
+  readonly path: string;
+  readonly size: number;
+}
+
+export interface VersionStore {
+  init(projectDir: string): Promise<void>;
+  list(projectDir: string, prefix?: string): Promise<FileEntry[]>;
+  head(projectDir: string, filePath: string): Promise<VersionId>;
+  read(projectDir: string, filePath: string, at?: VersionId): Promise<Buffer>;
+  commit(projectDir: string, filePath: string, req: CommitRequest): Promise<CommitResult>;
+  remove(projectDir: string, filePath: string, baseVersion: VersionId): Promise<CommitResult>;
+  diff(projectDir: string, filePath: string, from: VersionId, to: VersionId): Promise<string>;
+  history(projectDir: string, filePath: string, limit?: number): Promise<VersionInfo[]>;
+}
+
+interface StoredVersion {
+  readonly version: VersionId;
+  readonly content: Buffer;
+  readonly message: string;
+  readonly author: string | undefined;
+  readonly committedAt: string;
+  readonly deleted: boolean;
+}
+
+interface Repo {
+  /** 每文件一条版本链(D16:版本是文件级的,互不干扰)。 */
+  readonly files: Map<string, StoredVersion[]>;
+  counter: number;
+}
+
+/** S4:同 projectDir 的写操作经 per-repo promise 链串行化。 */
+function createKeySerializer(): <T>(key: string, fn: () => Promise<T>) => Promise<T> {
+  const tails = new Map<string, Promise<unknown>>();
+  return <T>(key: string, fn: () => Promise<T>): Promise<T> => {
+    const prev = tails.get(key) ?? Promise.resolve();
+    const next = prev.then(fn, fn);
+    tails.set(key, next.catch(() => undefined));
+    return next;
+  };
+}
+
+function toBuffer(content: string | Buffer): Buffer {
+  return typeof content === "string" ? Buffer.from(content, "utf8") : content;
+}
+
+/** 极简 unified-diff(mock 保真够用;真包的 diff 以版本团队为准)。 */
+function naiveDiff(fromText: string, toText: string): string {
+  const a = fromText.split("\n");
+  const b = toText.split("\n");
+  const out: string[] = ["--- a", "+++ b"];
+  const max = Math.max(a.length, b.length);
+  for (let i = 0; i < max; i += 1) {
+    const al = a[i];
+    const bl = b[i];
+    if (al === bl) {
+      if (al !== undefined) out.push(` ${al}`);
+    } else {
+      if (al !== undefined) out.push(`-${al}`);
+      if (bl !== undefined) out.push(`+${bl}`);
+    }
+  }
+  return out.join("\n");
+}
+
+export function createInMemoryVersionStore(persistPath?: string): VersionStore {
+  const repos = new Map<string, Repo>();
+  const serialize = createKeySerializer();
+
+  /* ---------------- 开发期快照持久化(语义不变,仅防重启丢失) ---------------- */
+  interface PersistedVersion extends Omit<StoredVersion, "content"> {
+    content: string; // base64
+  }
+  function loadPersisted(): void {
+    if (persistPath === undefined) return;
+    try {
+      const raw = JSON.parse(readFileSync(persistPath, "utf8")) as {
+        repos: Record<string, { counter: number; files: Record<string, PersistedVersion[]> }>;
+      };
+      for (const [dir, repo] of Object.entries(raw.repos)) {
+        const files = new Map<string, StoredVersion[]>();
+        for (const [filePath, versions] of Object.entries(repo.files)) {
+          files.set(filePath, versions.map((v) => ({ ...v, content: Buffer.from(v.content, "base64") })));
+        }
+        repos.set(dir, { files, counter: repo.counter });
+      }
+    } catch { /* 无快照或损坏 → 空库起步(开发语义) */ }
+  }
+  function savePersisted(): void {
+    if (persistPath === undefined) return;
+    const out: Record<string, { counter: number; files: Record<string, PersistedVersion[]> }> = {};
+    for (const [dir, repo] of repos) {
+      const files: Record<string, PersistedVersion[]> = {};
+      for (const [filePath, versions] of repo.files) {
+        files[filePath] = versions.map((v) => ({ ...v, content: v.content.toString("base64") }));
+      }
+      out[dir] = { counter: repo.counter, files };
+    }
+    try {
+      mkdirSync(path.dirname(persistPath), { recursive: true });
+      const tmp = `${persistPath}.tmp`;
+      writeFileSync(tmp, JSON.stringify({ repos: out }), "utf8");
+      renameSync(tmp, persistPath);
+    } catch { /* 快照失败不影响开发使用 */ }
+  }
+  loadPersisted();
+
+  function requireRepo(projectDir: string): Repo {
+    const repo = repos.get(projectDir);
+    if (repo === undefined) {
+      throw new FileLibError(404, "repo_not_found", `repository not initialized: ${projectDir}`);
+    }
+    return repo;
+  }
+
+  function liveVersion(repo: Repo, filePath: string): StoredVersion {
+    const chain = repo.files.get(filePath);
+    const latest = chain?.[chain.length - 1];
+    if (chain === undefined || latest === undefined || latest.deleted) {
+      throw new FileLibError(404, "file_not_found", `file not found: ${filePath}`);
+    }
+    return latest;
+  }
+
+  function findVersion(repo: Repo, filePath: string, version: VersionId): StoredVersion {
+    const found = repo.files.get(filePath)?.find((v) => v.version === version);
+    if (found === undefined) {
+      throw new FileLibError(404, "version_not_found", `version not found: ${filePath}@${version}`);
+    }
+    return found;
+  }
+
+  return {
+    async init(projectDir) {
+      await serialize(projectDir, async () => {
+        // S7:幂等,重复调用不报错、不重建。
+        const created = repos.get(projectDir) === undefined;
+        repos.set(projectDir, repos.get(projectDir) ?? { files: new Map(), counter: 0 });
+        if (created) savePersisted();
+      });
+    },
+
+    async list(projectDir, prefix) {
+      const repo = requireRepo(projectDir);
+      const out: FileEntry[] = [];
+      for (const [path, chain] of repo.files) {
+        const latest = chain[chain.length - 1];
+        if (latest === undefined || latest.deleted) continue;
+        if (prefix !== undefined && !path.startsWith(prefix)) continue;
+        out.push({ path, size: latest.content.byteLength });
+      }
+      return out.sort((a, b) => a.path.localeCompare(b.path));
+    },
+
+    async head(projectDir, filePath) {
+      return liveVersion(requireRepo(projectDir), filePath).version;
+    },
+
+    async read(projectDir, filePath, at) {
+      const repo = requireRepo(projectDir);
+      if (at !== undefined) return findVersion(repo, filePath, at).content;
+      return liveVersion(repo, filePath).content;
+    },
+
+    async commit(projectDir, filePath, req) {
+      return serialize(projectDir, async (): Promise<CommitResult> => {
+        const repo = requireRepo(projectDir);
+        const chain = repo.files.get(filePath) ?? [];
+        const latest = chain[chain.length - 1];
+        const currentVersion = latest !== undefined && !latest.deleted ? latest.version : null;
+
+        // S2:新建(baseVersion null)要求文件当前不存在;否则要求 baseVersion 精确等于当前版本(S1)。
+        if (req.baseVersion === null) {
+          if (currentVersion !== null) return { status: "conflict", currentVersion };
+        } else if (req.baseVersion !== currentVersion) {
+          return {
+            status: "conflict",
+            currentVersion: currentVersion ?? req.baseVersion,
+          };
+        }
+
+        repo.counter += 1;
+        const version = `v${repo.counter}`;
+        chain.push({
+          version,
+          content: toBuffer(req.content),
+          message: req.message ?? `commit ${version}`,
+          author: req.author,
+          committedAt: new Date().toISOString(),
+          deleted: false,
+        });
+        repo.files.set(filePath, chain);
+        savePersisted();
+        return { status: "ok", version };
+      });
+    },
+
+    async remove(projectDir, filePath, baseVersion) {
+      return serialize(projectDir, async (): Promise<CommitResult> => {
+        const repo = requireRepo(projectDir);
+        const chain = repo.files.get(filePath) ?? [];
+        const latest = chain[chain.length - 1];
+        const currentVersion = latest !== undefined && !latest.deleted ? latest.version : null;
+        if (currentVersion === null) {
+          throw new FileLibError(404, "file_not_found", `file not found: ${filePath}`);
+        }
+        if (baseVersion !== currentVersion) return { status: "conflict", currentVersion };
+        repo.counter += 1;
+        const version = `v${repo.counter}`;
+        chain.push({
+          version,
+          content: Buffer.alloc(0),
+          message: `remove ${filePath}`,
+          author: undefined,
+          committedAt: new Date().toISOString(),
+          deleted: true,
+        });
+        repo.files.set(filePath, chain);
+        savePersisted();
+        return { status: "ok", version };
+      });
+    },
+
+    async diff(projectDir, filePath, from, to) {
+      const repo = requireRepo(projectDir);
+      const a = findVersion(repo, filePath, from);
+      const b = findVersion(repo, filePath, to);
+      return naiveDiff(a.content.toString("utf8"), b.content.toString("utf8"));
+    },
+
+    async history(projectDir, filePath, limit) {
+      const repo = requireRepo(projectDir);
+      const chain = repo.files.get(filePath) ?? [];
+      const infos: VersionInfo[] = chain.map((v) => ({
+        version: v.version,
+        message: v.message,
+        author: v.author,
+        committedAt: v.committedAt,
+      }));
+      const ordered = infos.reverse();
+      return limit !== undefined ? ordered.slice(0, limit) : ordered;
+    },
+  };
+}

hub/src/database/plugin.ts

@@ -0,0 +1,45 @@
+/**
+ * Registers the `/database/*` HTTP surface onto the Fastify app.
+ *
+ * Single public entry point (mirrors src/admin/plugin.ts). hub.ts calls
+ * registerDatabasePlugin() so the routes are recognized at startup.
+ *
+ * Register AFTER registerAdminPlugin: it relies on the @fastify/cookie parser
+ * and the /auth/feishu/* login routes that the admin plugin adds.
+ *
+ * The dev login bypass is self-contained in THIS module: the flag is read here
+ * (not threaded from hub.ts) and only ever enables the `/database/dev-login`
+ * route below. Double-gated: NODE_ENV must not be production AND
+ * HUB_DEV_LOGIN_BYPASS must be truthy. Production always requires real Feishu
+ * OAuth.
+ */
+import type { FastifyInstance } from "fastify";
+import type { PrismaClient } from "@prisma/client";
+import { registerDatabaseRoutes } from "./routes/databaseRoutes.js";
+
+export interface DatabasePluginConfig {
+  readonly prisma: PrismaClient;
+  readonly sessionSecret: string;
+  readonly siloOrganizationSlug: string;
+}
+
+const FALSY = new Set(["", "0", "false", "no", "off"]);
+
+export async function registerDatabasePlugin(
+  app: FastifyInstance,
+  config: DatabasePluginConfig,
+): Promise<void> {
+  const allowDevLoginBypass =
+    process.env["NODE_ENV"] !== "production" &&
+    !FALSY.has((process.env["HUB_DEV_LOGIN_BYPASS"] ?? "").trim().toLowerCase());
+  if (allowDevLoginBypass) {
+    app.log.warn("DEV login bypass enabled: /database/dev-login mints a session without Feishu OAuth");
+  }
+
+  await registerDatabaseRoutes(app, {
+    prisma: config.prisma,
+    sessionSecret: config.sessionSecret,
+    siloOrganizationSlug: config.siloOrganizationSlug,
+    allowDevLoginBypass,
+  });
+}

hub/src/database/routes/adminPanels.ts

@@ -0,0 +1,227 @@
+/**
+ * 管理员后台「用户管理」「Group 管理」面板(复用 hub 已有 org 管理 API)。
+ *
+ * 用户管理 = org 成员(/api/org/:orgSlug/members);
+ * Group 管理 = Team(当前 Group 的过渡实现,/api/org/:orgSlug/teams),
+ * 真 Group 系统落地后此面板改接新 API 即可,文件库授权侧不动。
+ */
+
+function apiBase(orgSlug: string): string {
+  return `/api/org/${encodeURIComponent(orgSlug)}`;
+}
+
+/* ---------------------------------------------------------------- 用户管理 */
+
+export function renderUsersPanel(orgSlug: string): string {
+  return `
+<div id="users-root" style="max-width:880px">
+  <div class="panel" style="margin-bottom:14px">
+    <div class="section-title">添加成员</div>
+    <div class="inline-form">
+      <input id="u-openid" class="input" placeholder="用户 openId(飞书 ou_ 开头)" style="flex:2"/>
+      <input id="u-name" class="input" placeholder="显示名(可选)" style="flex:1"/>
+      <select id="u-role" class="select" style="width:130px">
+        <option value="MEMBER">普通老师</option>
+        <option value="ADMIN">管理员</option>
+        <option value="OWNER">所有者</option>
+      </select>
+      <button id="u-add" class="btn btn-primary">添加</button>
+    </div>
+  </div>
+  <div class="panel">
+    <div class="section-title">成员列表</div>
+    <table class="list">
+      <thead><tr><th>成员</th><th>userId</th><th>角色</th><th></th></tr></thead>
+      <tbody id="u-tbody"></tbody>
+    </table>
+  </div>
+</div>
+<script>
+(function () {
+  const BASE = "${apiBase(orgSlug)}";
+  const tbody = document.getElementById("u-tbody");
+  const esc = (s) => String(s).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;");
+  const ROLE_LABEL = { OWNER: "所有者", ADMIN: "管理员", MEMBER: "普通老师" };
+  async function req(path, opts = {}) {
+    const res = await fetch(BASE + path, {
+      credentials: "same-origin",
+      headers: opts.body ? { "Content-Type": "application/json" } : undefined,
+      method: opts.method ?? "GET",
+      body: opts.body ? JSON.stringify(opts.body) : undefined,
+    });
+    if (res.status === 401) { location.href = "/database/admin"; throw new Error("unauthenticated"); }
+    const text = await res.text();
+    const data = text ? JSON.parse(text) : null;
+    if (!res.ok) throw new Error((data && data.error && data.error.message) || res.statusText);
+    return data;
+  }
+  async function load() {
+    const { members } = await req("/members");
+    tbody.innerHTML = members.length === 0
+      ? '<tr><td colspan="4" class="quiet" style="text-align:center;padding:18px">暂无成员</td></tr>'
+      : members.map((m) =>
+        "<tr>" +
+          "<td>" + esc(m.displayName || m.userId) + "</td>" +
+          '<td class="file-meta">' + esc(m.userId) + "</td>" +
+          '<td><select class="select" style="width:110px;padding:3px 8px;font-size:12px" data-user="' + esc(m.userId) + '">' +
+            ["OWNER","ADMIN","MEMBER"].map((r) =>
+              '<option value="' + r + '"' + (m.role === r ? " selected" : "") + ">" + ROLE_LABEL[r] + "</option>").join("") +
+          "</select></td>" +
+          '<td style="text-align:right"><button class="link-danger" data-revoke="' + esc(m.userId) + '">移除</button></td>' +
+        "</tr>").join("");
+    tbody.querySelectorAll("select[data-user]").forEach((sel) => {
+      sel.onchange = async () => {
+        try { await req("/members/" + encodeURIComponent(sel.dataset.user), { method: "PATCH", body: { role: sel.value } }); }
+        catch (e) { alert(e.message); load(); }
+      };
+    });
+    tbody.querySelectorAll("button[data-revoke]").forEach((btn) => {
+      btn.onclick = async () => {
+        if (!confirm("移除该成员?")) return;
+        try { await req("/members/" + encodeURIComponent(btn.dataset.revoke) + "/revoke", { method: "POST" }); load(); }
+        catch (e) { alert(e.message); }
+      };
+    });
+  }
+  document.getElementById("u-add").onclick = async () => {
+    const openId = document.getElementById("u-openid").value.trim();
+    if (!openId) return alert("请填写用户 openId");
+    const displayName = document.getElementById("u-name").value.trim();
+    try {
+      await req("/members", { method: "POST", body: {
+        feishuOpenId: openId,
+        role: document.getElementById("u-role").value,
+        ...(displayName ? { displayName } : {}),
+      }});
+      document.getElementById("u-openid").value = "";
+      document.getElementById("u-name").value = "";
+      load();
+    } catch (e) { alert(e.message); }
+  };
+  load().catch((e) => { tbody.innerHTML = '<tr><td colspan="4" style="color:var(--danger);padding:12px">' + esc(e.message) + "</td></tr>"; });
+})();
+</script>`;
+}
+
+/* ---------------------------------------------------------------- Group 管理 */
+
+export function renderGroupsPanel(orgSlug: string): string {
+  return `
+<div id="groups-root" style="display:flex;gap:14px;align-items:flex-start">
+  <div style="width:340px;flex-shrink:0">
+    <div class="panel" style="margin-bottom:14px">
+      <div class="section-title">新建 Group</div>
+      <div class="form-row"><label class="form-label">标识(slug)</label><input id="g-slug" class="input" placeholder="physics-dept"/></div>
+      <div class="form-row"><label class="form-label">名称</label><input id="g-name" class="input" placeholder="物理教研组"/></div>
+      <div class="form-row"><label class="form-label">描述(可选)</label><input id="g-desc" class="input" placeholder="一句话说明"/></div>
+      <div style="text-align:right"><button id="g-create" class="btn btn-primary">创建</button></div>
+    </div>
+    <div class="panel">
+      <div class="section-title">Group 列表</div>
+      <div id="g-list"></div>
+    </div>
+  </div>
+  <div class="panel" style="flex:1;min-height:200px">
+    <div id="g-detail" class="quiet" style="padding:18px;text-align:center">从左侧选择一个 Group 查看成员</div>
+  </div>
+</div>
+<script>
+(function () {
+  const BASE = "${apiBase(orgSlug)}";
+  const listEl = document.getElementById("g-list");
+  const detailEl = document.getElementById("g-detail");
+  const esc = (s) => String(s).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;");
+  let selected = null;
+  async function req(path, opts = {}) {
+    const res = await fetch(BASE + path, {
+      credentials: "same-origin",
+      headers: opts.body ? { "Content-Type": "application/json" } : undefined,
+      method: opts.method ?? "GET",
+      body: opts.body ? JSON.stringify(opts.body) : undefined,
+    });
+    if (res.status === 401) { location.href = "/database/admin"; throw new Error("unauthenticated"); }
+    const text = await res.text();
+    const data = text ? JSON.parse(text) : null;
+    if (!res.ok) throw new Error((data && data.error && data.error.message) || res.statusText);
+    return data;
+  }
+  async function loadList() {
+    const { teams } = await req("/teams");
+    listEl.innerHTML = teams.length === 0
+      ? '<div class="quiet" style="text-align:center;padding:12px">暂无 Group</div>'
+      : teams.map((t) =>
+        '<div class="g-team" data-id="' + esc(t.id) + '" data-name="' + esc(t.name) + '" style="display:flex;align-items:center;gap:8px;padding:8px 6px;border-radius:8px;cursor:pointer">' +
+          '<span style="flex:1"><b>' + esc(t.name) + '</b> <span class="file-meta">' + esc(t.slug) + "</span></span>" +
+          '<button class="link-danger" data-archive="' + esc(t.id) + '" style="font-size:11px">归档</button>' +
+        "</div>").join("");
+    listEl.querySelectorAll(".g-team").forEach((el) => {
+      el.onclick = (e) => {
+        if (e.target.closest("button")) return;
+        selected = { id: el.dataset.id, name: el.dataset.name };
+        listEl.querySelectorAll(".g-team").forEach((x) => x.style.background = "");
+        el.style.background = "var(--selected)";
+        loadMembers();
+      };
+    });
+    listEl.querySelectorAll("button[data-archive]").forEach((btn) => {
+      btn.onclick = async () => {
+        if (!confirm("归档该 Group?其成员授权将失效。")) return;
+        try { await req("/teams/" + encodeURIComponent(btn.dataset.archive) + "/archive", { method: "POST" }); selected = null; detailEl.innerHTML = '<div class="quiet" style="padding:18px;text-align:center">从左侧选择一个 Group 查看成员</div>'; loadList(); }
+        catch (e) { alert(e.message); }
+      };
+    });
+  }
+  async function loadMembers() {
+    if (!selected) return;
+    detailEl.innerHTML = '<div class="quiet" style="padding:12px;text-align:center">加载中…</div>';
+    const { members } = await req("/teams/" + encodeURIComponent(selected.id) + "/members");
+    detailEl.innerHTML =
+      '<div class="section-title">' + esc(selected.name) + " · 成员(" + members.length + ")</div>" +
+      '<table class="list"><tbody>' +
+        (members.length === 0
+          ? '<tr><td class="quiet" style="text-align:center;padding:14px">暂无成员</td></tr>'
+          : members.map((m) =>
+            "<tr><td>" + esc(m.displayName || m.userId) + '</td><td class="file-meta">' + esc(m.userId) + "</td>" +
+            '<td style="text-align:right"><button class="link-danger" data-revoke="' + esc(m.userId) + '">移除</button></td></tr>').join("")) +
+      "</tbody></table>" +
+      '<div class="divider"></div>' +
+      '<div class="section-title">添加成员</div>' +
+      '<div class="inline-form">' +
+        '<input id="g-add-openid" class="input" placeholder="用户 openId 或 userId"/>' +
+        '<button id="g-add" class="btn btn-primary">添加</button>' +
+      "</div>";
+    detailEl.querySelectorAll("button[data-revoke]").forEach((btn) => {
+      btn.onclick = async () => {
+        try { await req("/teams/" + encodeURIComponent(selected.id) + "/members/" + encodeURIComponent(btn.dataset.revoke) + "/revoke", { method: "POST" }); loadMembers(); }
+        catch (e) { alert(e.message); }
+      };
+    });
+    detailEl.querySelector("#g-add").onclick = async () => {
+      const v = detailEl.querySelector("#g-add-openid").value.trim();
+      if (!v) return alert("请填写用户 id");
+      try {
+        await req("/teams/" + encodeURIComponent(selected.id) + "/members", {
+          method: "POST",
+          body: v.startsWith("ou_") ? { feishuOpenId: v } : { userId: v },
+        });
+        loadMembers();
+      } catch (e) { alert(e.message); }
+    };
+  }
+  document.getElementById("g-create").onclick = async () => {
+    const slug = document.getElementById("g-slug").value.trim();
+    const name = document.getElementById("g-name").value.trim();
+    const description = document.getElementById("g-desc").value.trim();
+    if (!slug || !name) return alert("slug 和名称必填");
+    try {
+      await req("/teams", { method: "POST", body: { slug, name, ...(description ? { description } : {}) } });
+      document.getElementById("g-slug").value = "";
+      document.getElementById("g-name").value = "";
+      document.getElementById("g-desc").value = "";
+      loadList();
+    } catch (e) { alert(e.message); }
+  };
+  loadList().catch((e) => { listEl.innerHTML = '<div style="color:var(--danger);padding:12px">' + esc(e.message) + "</div>"; });
+})();
+</script>`;
+}

hub/src/database/routes/databaseRoutes.ts

@@ -0,0 +1,418 @@
+/**
+ * `/database/*` route aggregator.
+ *
+ * Owns the `/database` HTTP surface (single place new sub-routes get wired in).
+ * Handlers use ABSOLUTE paths (no Fastify prefix) so every route greps as the
+ * literal string it serves.
+ *
+ *   /database/admin      — Feishu-only login page (+ dev one-click button)
+ *   /database/dashboard  — sidebar + content admin shell, session-gated
+ *   /database/dev-login  — DEV ONLY bypass, registered only when the flag is on
+ *
+ * The dev bypass (button + /database/dev-login) is self-contained here and
+ * gated by allowDevLoginBypass (computed in ./plugin.ts from HUB_DEV_LOGIN_BYPASS
+ * + NODE_ENV). Production requires real Feishu OAuth.
+ */
+import type { FastifyInstance } from "fastify";
+import type { PrismaClient } from "@prisma/client";
+import path from "node:path";
+import { SESSION_COOKIE_NAME, signSession, verifySession } from "../../admin/auth/session.js";
+import { registerFileLibRoutes } from "./filelibRoutes.js";
+import { registerFileRoutes } from "./fileRoutes.js";
+import { registerTeacherApp } from "./teacherApp.js";
+import { renderLibraryBrowser } from "./libraryBrowser.js";
+import { renderGroupsPanel, renderUsersPanel } from "./adminPanels.js";
+import { createInMemoryVersionStore } from "../filelib/versionStore.js";
+import { createTeamGroupResolver } from "../filelib/groupResolver.js";
+import { createHttpGroupResolver } from "../filelib/groupResolverHttp.js";
+import { createManifestStubAdapter } from "../filelib/exportService.js";
+import { FILE_LIB_AUDIT_ACTIONS } from "../filelib/audit.js";
+import { UI_HEAD_FONTS, UI_THEME_CSS } from "./uiTheme.js";
+import type { FileLibRouteDeps } from "../filelib/routeShared.js";
+
+export interface DatabaseRouteConfig {
+  readonly prisma: PrismaClient;
+  /** HMAC secret for the signed session cookie — reused from the admin plane. */
+  readonly sessionSecret: string;
+  /** Silo Organization slug — builds the org-scoped Feishu login link. */
+  readonly siloOrganizationSlug: string;
+  /** DEV ONLY. Enables the one-click button and the /database/dev-login route. */
+  readonly allowDevLoginBypass: boolean;
+}
+
+export async function registerDatabaseRoutes(
+  app: FastifyInstance,
+  config: DatabaseRouteConfig,
+): Promise<void> {
+  // 文件库依赖在下方装配;概览页统计在请求时经此引用读取(请求一定晚于装配完成)。
+  let filelibDepsForStats: FileLibRouteDeps | null = null;
+
+  app.get("/database/admin", async (request, reply) => {
+    // Already signed in → straight to the dashboard.
+    if ((await resolveUser(request.cookies[SESSION_COOKIE_NAME], config)) !== null) {
+      return reply.redirect("/database/dashboard");
+    }
+    return reply.type("text/html").send(renderLoginPage(config));
+  });
+
+  app.get("/database/dashboard", async (request, reply) => {
+    const user = await resolveUser(request.cookies[SESSION_COOKIE_NAME], config);
+    if (user === null) return reply.redirect("/database/admin");
+    const stats = await loadDashboardStats(config.prisma, filelibDepsForStats);
+    return reply.type("text/html").send(renderDashboard(user.displayName, stats, config.siloOrganizationSlug));
+  });
+
+  // DEV ONLY bypass — self-contained here, registered only when the flag is on
+  // (see ./plugin.ts). Mints a session for an existing OWNER/ADMIN, reusing the
+  // scoped SessionIdentity shape the Feishu OAuth callback produces so the
+  // session guard behaves identically. Never registered in production.
+  if (config.allowDevLoginBypass) {
+    app.get("/database/dev-login", async (_request, reply) => {
+      const membership = await config.prisma.organizationMembership.findFirst({
+        where: {
+          revokedAt: null,
+          role: { in: ["OWNER", "ADMIN"] },
+          organization: { status: "ACTIVE" },
+        },
+        select: { userId: true, organizationId: true },
+        orderBy: { createdAt: "asc" },
+      });
+      if (membership === null) {
+        return reply.status(404).send({ error: { code: "no_admin", message: "no active OWNER/ADMIN to impersonate" } });
+      }
+      const identity = await config.prisma.feishuUserIdentity.findFirst({
+        where: {
+          userId: membership.userId,
+          connection: { organizationId: membership.organizationId, status: "ACTIVE" },
+        },
+        select: { id: true, connectionId: true, connection: { select: { organizationId: true } } },
+      });
+      if (identity === null) {
+        return reply.status(404).send({ error: { code: "no_identity", message: "admin has no active scoped Feishu identity" } });
+      }
+      const token = signSession(
+        {
+          userId: membership.userId,
+          feishuIdentityId: identity.id,
+          feishuConnectionId: identity.connectionId,
+          feishuOrganizationId: identity.connection.organizationId,
+        },
+        config.sessionSecret,
+      );
+      // Local dev is http://127.0.0.1, so secure:false. This route only ever
+      // runs outside production (double-gated in ./plugin.ts).
+      reply.setCookie(SESSION_COOKIE_NAME, token, {
+        path: "/",
+        httpOnly: true,
+        sameSite: "lax",
+        secure: false,
+        maxAge: 7 * 24 * 60 * 60,
+      });
+      reply.log.warn({ userId: membership.userId, orgId: membership.organizationId }, "DEV database login bypass used");
+      return reply.redirect("/database/dashboard");
+    });
+  }
+
+  // 文件库(独立模块,《文件库-接口契约.md》):API + 浏览页 + 老师端 /app。
+  // 依赖装配:VersionStore 当前为内存+快照实现(版本团队 npm 包到位后替换);
+  // GroupResolver 默认读 hub Team,HUB_GROUP_SERVICE_URL 配置后切 HTTP(C2);
+  // 导出适配器当前为 manifest stub(OPEN-6,真导出工具到位后替换)。
+  const siloOrg = await config.prisma.organization.findUnique({
+    where: { slug: config.siloOrganizationSlug },
+    select: { id: true },
+  });
+  if (siloOrg === null) {
+    app.log.warn({ slug: config.siloOrganizationSlug }, "filelib: silo organization not found, routes not registered");
+    return;
+  }
+  const storageRoot = process.env["HUB_FILELIB_STORAGE_ROOT"] ?? path.resolve(".filelib-repos");
+  const versionStore = createInMemoryVersionStore(path.join(storageRoot, ".version-store.json"));
+  const groupServiceUrl = process.env["HUB_GROUP_SERVICE_URL"];
+  const filelibDeps: FileLibRouteDeps = {
+    prisma: config.prisma,
+    sessionSecret: config.sessionSecret,
+    organizationId: siloOrg.id,
+    storageRoot,
+    groupResolver: groupServiceUrl === undefined || groupServiceUrl.trim() === ""
+      ? createTeamGroupResolver(config.prisma, siloOrg.id)
+      : createHttpGroupResolver({ baseUrl: groupServiceUrl }),
+    versionStore,
+    exportAdapters: [createManifestStubAdapter(versionStore)],
+  };
+  await registerFileLibRoutes(app, filelibDeps);
+  await registerFileRoutes(app, filelibDeps);
+  await registerTeacherApp(app, {
+    prisma: config.prisma,
+    sessionSecret: config.sessionSecret,
+    siloOrganizationSlug: config.siloOrganizationSlug,
+    allowDevLoginBypass: config.allowDevLoginBypass,
+  });
+
+  // 独立文件库页已并入后台「文件库」tab(/database/dashboard#library),旧地址跳转保留兼容。
+  app.get("/database/library", async (_request, reply) =>
+    reply.redirect("/database/dashboard#library"),
+  );
+
+  filelibDepsForStats = filelibDeps;
+}
+
+/* ------------------------------------------------------------ 概览页统计 */
+
+interface DashboardStats {
+  readonly folders: number;
+  readonly projects: number;
+  readonly files: number;
+  readonly grants: number;
+  readonly recent: ReadonlyArray<{
+    readonly action: string;
+    readonly actor: string;
+    readonly label: string;
+    readonly when: Date;
+  }>;
+}
+
+/** 概览页统计:org 范围内的文件夹/项目/授权(DB)+ 文件(版本库)+ 最近活动(AuditEntry)。 */
+async function loadDashboardStats(
+  prisma: PrismaClient,
+  deps: FileLibRouteDeps | null,
+): Promise<DashboardStats | null> {
+  if (deps === null) return null;
+  const organizationId = deps.organizationId;
+  const [folders, projects, grants] = await Promise.all([
+    prisma.fileLibNode.count({ where: { organizationId, kind: "FOLDER", deletedAt: null } }),
+    prisma.fileLibNode.count({ where: { organizationId, kind: "PROJECT", deletedAt: null } }),
+    prisma.fileLibGrant.count({ where: { organizationId, revokedAt: null } }),
+  ]);
+  // 文件计数:遍历 READY 项目问版本库(demo 规模;真版本包到位后应换成存储侧统计)
+  const readyProjects = await prisma.fileLibNode.findMany({
+    where: {
+      organizationId, kind: "PROJECT", deletedAt: null,
+      provisionStatus: "READY", storageDir: { not: null },
+    },
+    select: { storageDir: true },
+  });
+  let files = 0;
+  for (const project of readyProjects) {
+    if (project.storageDir === null) continue;
+    try {
+      files += (await deps.versionStore.list(project.storageDir)).length;
+    } catch { /* repo 缺失(如重启未恢复)不计 */ }
+  }
+  const entries = await prisma.auditEntry.findMany({
+    where: { organizationId, action: { in: Object.values(FILE_LIB_AUDIT_ACTIONS) } },
+    orderBy: { createdAt: "desc" },
+    take: 8,
+  });
+  const actorIds = [...new Set(entries.map((e) => e.actorUserId).filter((x): x is string => x !== null))];
+  const users = actorIds.length === 0
+    ? []
+    : await prisma.user.findMany({ where: { id: { in: actorIds } }, select: { id: true, displayName: true } });
+  const nameById = new Map(users.map((u) => [u.id, u.displayName]));
+  const recent = entries.map((entry) => {
+    const meta = (entry.metadata ?? {}) as Record<string, unknown>;
+    const label =
+      (typeof meta["name"] === "string" ? meta["name"] : undefined) ??
+      (typeof meta["to"] === "string" ? meta["to"] : undefined) ??
+      (typeof meta["path"] === "string" ? meta["path"] : undefined) ??
+      (typeof meta["objectId"] === "string" ? meta["objectId"].slice(0, 8) : "");
+    return {
+      action: entry.action,
+      actor: nameById.get(entry.actorUserId ?? "") ?? entry.actorUserId ?? "unknown",
+      label,
+      when: entry.createdAt,
+    };
+  });
+  return { folders, projects, files, grants, recent };
+}
+
+/** Verify the session cookie and load the user, or null if not signed in. */
+async function resolveUser(
+  rawCookie: string | undefined,
+  config: DatabaseRouteConfig,
+): Promise<{ displayName: string } | null> {
+  if (rawCookie === undefined || rawCookie === "") return null;
+  const session = verifySession(rawCookie, config.sessionSecret);
+  if (session === null) return null;
+  const user = await config.prisma.user.findUnique({
+    where: { id: session.userId },
+    select: { displayName: true },
+  });
+  return user;
+}
+
+/** 管理后台共享 head(全局 UI 主题,与老师端 /app 同源)。 */
+function pageHead(title: string): string {
+  return `<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1"/>
+  <title>${title}</title>
+  ${UI_HEAD_FONTS}
+  <style>${UI_THEME_CSS}</style>
+</head>`;
+}
+
+function renderLoginPage(config: DatabaseRouteConfig): string {
+  const feishuHref = `/auth/feishu/${encodeURIComponent(config.siloOrganizationSlug)}`;
+  const devButton = config.allowDevLoginBypass
+    ? `<div style="display:flex;align-items:center;gap:10px;margin:22px 0;color:var(--text-3);font-size:11px">
+         <span style="flex:1;border-top:1px solid var(--border-soft)"></span>开发模式
+         <span style="flex:1;border-top:1px solid var(--border-soft)"></span>
+       </div>
+       <a href="/database/dev-login" class="btn" style="width:100%;justify-content:center">⚡ 一键登录管理员</a>
+       <p style="margin:10px 0 0;text-align:center;font-size:11px;color:var(--text-3)">仅开发环境可见 · 跳过飞书 OAuth</p>`
+    : "";
+
+  return `<!doctype html>
+<html lang="zh-CN">
+${pageHead("Database Admin · 登录")}
+<body>
+  <div style="min-height:100vh;display:flex;align-items:center;justify-content:center;padding:24px">
+    <div style="width:100%;max-width:380px;background:var(--panel);border:1px solid var(--border-soft);border-radius:16px;padding:40px 36px;box-shadow:var(--shadow-pop)">
+      <div style="font-size:26px;font-weight:600;text-align:center">Database Admin</div>
+      <p style="margin:10px 0 30px;text-align:center;font-size:13px;color:var(--text-3)">使用飞书登录以管理数据库</p>
+      <a href="${feishuHref}" class="btn btn-primary" style="width:100%;justify-content:center;padding:11px 16px;font-size:14px">使用飞书登录</a>
+      ${devButton}
+    </div>
+  </div>
+</body>
+</html>`;
+}
+
+/** Sidebar nav items. `active` marks the current page. `href` "#" = placeholder. */
+const NAV_TABS: ReadonlyArray<{ id: string; label: string; icon: string }> = [
+  { id: "overview", label: "概览", icon: "M4 13h6V4H4v9Zm0 7h6v-5H4v5Zm10 0h6V11h-6v9Zm0-16v5h6V4h-6Z" },
+  { id: "library", label: "文件库", icon: "M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V7Z" },
+  { id: "users", label: "用户管理", icon: "M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2M9 11a4 4 0 1 0 0-8 4 4 0 0 0 0 8Zm13 10v-2a4 4 0 0 0-3-3.87M16 3.13a4 4 0 0 1 0 7.75" },
+  { id: "groups", label: "Group 管理", icon: "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.75M23 21v-2a4 4 0 0 0-3-3.87" },
+  { id: "search", label: "查询", icon: "m21 21-4.3-4.3M11 18a7 7 0 1 0 0-14 7 7 0 0 0 0 14Z" },
+  { id: "settings", label: "设置", icon: "M12 15a3 3 0 1 0 0-6 3 3 0 0 0 0 6Zm7-3 2 1-2 3-2-1a7 7 0 0 1-2 1l-1 2h-4l-1-2a7 7 0 0 1-2-1l-2 1-2-3 2-1a7 7 0 0 1 0-2l-2-1 2-3 2 1a7 7 0 0 1 2 1l1-2h4l1 2a7 7 0 0 1 0 2l2-1 2 3-2 1a7 7 0 0 1 0 2Z" },
+];
+
+function renderDashboard(displayName: string, stats: DashboardStats | null, orgSlug: string): string {
+  const nav = NAV_TABS.map((t) => `
+    <button class="admin-tab" data-tab="${t.id}" style="display:flex;align-items:center;gap:10px;border-radius:10px;padding:9px 14px;font-size:13px;color:var(--text-3);background:none;border:none;cursor:pointer;text-align:left;width:100%">
+      <svg style="width:16px;height:16px;flex-shrink:0" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="${t.icon}"/></svg>
+      ${t.label}
+    </button>`).join("\n");
+
+  const cards = [
+    { label: "文件夹", value: stats?.folders ?? "—" },
+    { label: "项目", value: stats?.projects ?? "—" },
+    { label: "文件", value: stats?.files ?? "—" },
+    { label: "活跃授权", value: stats?.grants ?? "—" },
+  ].map((s) => `
+        <div class="panel" style="padding:18px 20px">
+          <p style="font-size:12.5px;color:var(--text-3)">${s.label}</p>
+          <p style="margin-top:6px;font-size:28px;font-weight:600;color:var(--text)">${s.value}</p>
+        </div>`).join("");
+
+  const recentRows = stats === null || stats.recent.length === 0
+    ? `<div style="padding:26px 0;text-align:center;font-size:12.5px;color:var(--text-3)">暂无文件库活动 · 到「文件库」里创建第一个文件夹吧</div>`
+    : stats.recent.map((r) => `
+          <div style="display:flex;align-items:center;gap:12px;border-top:1px solid var(--border-soft);padding:9px 0;font-size:13px">
+            <span class="tag">${escapeHtml(r.action)}</span>
+            <span style="overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:var(--text)">${escapeHtml(r.label)}</span>
+            <span style="margin-left:auto;flex-shrink:0;font-size:11.5px;color:var(--text-3)">${escapeHtml(r.actor)} · ${escapeHtml(r.when.toLocaleString("zh-CN"))}</span>
+          </div>`).join("");
+
+  const initial = escapeHtml(displayName.slice(0, 1) || "U");
+
+  return `<!doctype html>
+<html lang="zh-CN">
+${pageHead("Database Admin")}
+<body>
+  <div style="display:flex;height:100vh">
+    <aside style="width:240px;flex-shrink:0;background:var(--sidebar);border-right:1px solid var(--border-soft);display:flex;flex-direction:column">
+      <div style="padding:16px 16px 12px;border-bottom:1px solid var(--border-soft)">
+        <span style="font-size:15px;font-weight:600">Database Admin</span>
+      </div>
+      <nav style="flex:1;display:flex;flex-direction:column;gap:2px;padding:10px">
+        ${nav}
+      </nav>
+      <div style="margin:10px;padding:10px 12px;border-top:1px solid var(--border-soft);display:flex;align-items:center;gap:9px">
+        <div style="width:26px;height:26px;border-radius:50%;background:var(--accent);color:#fff;display:flex;align-items:center;justify-content:center;font-size:11px;font-weight:600;flex-shrink:0">${initial}</div>
+        <div style="min-width:0;flex:1">
+          <p style="font-size:10.5px;color:var(--text-3)">已登录</p>
+          <p style="overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-size:12.5px;color:var(--text)">${escapeHtml(displayName)}</p>
+        </div>
+        <button id="logout" class="btn" style="padding:3px 10px;font-size:11px">退出</button>
+      </div>
+    </aside>
+
+    <div style="flex:1;display:flex;flex-direction:column;min-width:0">
+      <section id="tab-overview" class="admin-tab-section" style="flex:1;overflow-y:auto;padding:28px">
+        <h1 style="font-size:18px;font-weight:600;margin-bottom:4px">概览</h1>
+        <p style="font-size:11.5px;color:var(--text-3);margin-bottom:20px">文件库实时数据</p>
+        <div style="display:grid;grid-template-columns:repeat(4,1fr);gap:16px">
+          ${cards}
+        </div>
+        <div class="panel" style="margin-top:18px">
+          <h2 style="font-size:13.5px;font-weight:600;margin-bottom:8px">最近活动</h2>
+          ${recentRows}
+        </div>
+      </section>
+
+      <section id="tab-library" class="admin-tab-section" style="display:none;flex:1;min-height:0">
+        ${renderLibraryBrowser()}
+      </section>
+
+      <section id="tab-users" class="admin-tab-section" style="display:none;flex:1;overflow-y:auto;padding:28px">
+        <h1 style="font-size:18px;font-weight:600;margin-bottom:16px">用户管理</h1>
+        ${renderUsersPanel(orgSlug)}
+      </section>
+
+      <section id="tab-groups" class="admin-tab-section" style="display:none;flex:1;overflow-y:auto;padding:28px">
+        <h1 style="font-size:18px;font-weight:600;margin-bottom:16px">Group 管理</h1>
+        ${renderGroupsPanel(orgSlug)}
+      </section>
+
+      <section id="tab-search" class="admin-tab-section" style="display:none;flex:1;overflow-y:auto;padding:28px">
+        <h1 style="font-size:18px;font-weight:600;margin-bottom:4px">查询</h1>
+        <p style="font-size:12.5px;color:var(--text-3)">查询功能建设中</p>
+      </section>
+
+      <section id="tab-settings" class="admin-tab-section" style="display:none;flex:1;overflow-y:auto;padding:28px">
+        <h1 style="font-size:18px;font-weight:600;margin-bottom:4px">设置</h1>
+        <p style="font-size:12.5px;color:var(--text-3)">设置功能建设中</p>
+      </section>
+    </div>
+  </div>
+
+  <script>
+    (function () {
+      const tabs = [...document.querySelectorAll(".admin-tab")];
+      const sections = Object.fromEntries(
+        [...document.querySelectorAll(".admin-tab-section")].map((s) => [s.id.replace("tab-", ""), s]),
+      );
+      function activate(id) {
+        tabs.forEach((t) => {
+          const on = t.dataset.tab === id;
+          t.style.background = on ? "var(--selected)" : "none";
+          t.style.color = on ? "var(--text)" : "var(--text-3)";
+          t.style.fontWeight = on ? "600" : "400";
+        });
+        Object.entries(sections).forEach(([key, s]) => {
+          s.style.display = key === id ? (key === "library" ? "block" : "block") : "none";
+        });
+        if (location.hash !== "#" + id) history.replaceState(null, "", "#" + id);
+      }
+      tabs.forEach((t) => t.addEventListener("click", () => activate(t.dataset.tab)));
+      document.getElementById("logout").addEventListener("click", async () => {
+        try { await fetch("/auth/logout", { method: "POST", credentials: "same-origin" }); } catch (e) {}
+        location.href = "/database/admin";
+      });
+      const fromHash = location.hash.replace(/^#/, "");
+      activate(tabs.some((t) => t.dataset.tab === fromHash) ? fromHash : "overview");
+    })();
+  </script>
+</body>
+</html>`;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}

hub/src/database/routes/fileRoutes.ts

@@ -0,0 +1,235 @@
+/**
+ * /database/api/* 文件内容与导出端点(契约 9.3/9.4)。
+ * 冲突流:POST commits 返回 200 {version} 或 409 {currentVersion}(编辑 UI 拉 diff 后重提)。
+ */
+
+import type { FastifyInstance, FastifyRequest } from "fastify";
+import {
+  commitFile,
+  deleteFile,
+  diffFile,
+  fileHistory,
+  listFiles,
+  readFile,
+  readFileRaw,
+  type FileContentEncoding,
+} from "../filelib/fileService.js";
+import {
+  createManifestStubAdapter,
+  downloadExport,
+  getExportJob,
+  submitExport,
+} from "../filelib/exportService.js";
+import { FileLibError } from "../filelib/model.js";
+import {
+  actorOrNull,
+  bodyObject,
+  optionalString,
+  requireString,
+  sendRouteError,
+  type FileLibRouteDeps,
+} from "../filelib/routeShared.js";
+
+export async function registerFileRoutes(
+  app: FastifyInstance,
+  deps: FileLibRouteDeps,
+): Promise<void> {
+  const fileDeps = {
+    prisma: deps.prisma,
+    organizationId: deps.organizationId,
+    groupResolver: deps.groupResolver,
+    versionStore: deps.versionStore,
+  };
+  const exportDeps = { ...fileDeps, adapters: deps.exportAdapters };
+
+  function pathParam(request: FastifyRequest): string {
+    const path = (request.query as { path?: string }).path;
+    if (path === undefined) throw new FileLibError(400, "invalid_request", "missing query: path");
+    return path;
+  }
+
+  function encodingParam(raw: unknown): FileContentEncoding {
+    if (raw === undefined || raw === "utf8") return "utf8";
+    if (raw === "base64") return "base64";
+    throw new FileLibError(400, "invalid_request", "encoding must be utf8 or base64");
+  }
+
+  app.get("/database/api/projects/:id/files", async (request, reply) => {
+    const actor = await actorOrNull(request, reply, deps);
+    if (actor === null) return reply;
+    try {
+      const { id } = request.params as { id: string };
+      const prefix = (request.query as { prefix?: string }).prefix;
+      return { files: await listFiles(fileDeps, actor, id, prefix) };
+    } catch (error) {
+      return sendRouteError(reply, error);
+    }
+  });
+
+  app.get("/database/api/projects/:id/file", async (request, reply) => {
+    const actor = await actorOrNull(request, reply, deps);
+    if (actor === null) return reply;
+    try {
+      const { id } = request.params as { id: string };
+      return await readFile(fileDeps, actor, id, pathParam(request));
+    } catch (error) {
+      return sendRouteError(reply, error);
+    }
+  });
+
+  // 原始字节下载(Content-Disposition: attachment;浏览器直接 save-as)
+  app.get("/database/api/projects/:id/file/raw", async (request, reply) => {
+    const actor = await actorOrNull(request, reply, deps);
+    if (actor === null) return reply;
+    try {
+      const { id } = request.params as { id: string };
+      const raw = await readFileRaw(fileDeps, actor, id, pathParam(request));
+      return reply
+        .header("Content-Disposition",
+          `attachment; filename="${encodeURIComponent(raw.filename)}"; filename*=UTF-8''${encodeURIComponent(raw.filename)}`)
+        .header("X-Content-Version", raw.version)
+        .type("application/octet-stream")
+        .send(raw.buffer);
+    } catch (error) {
+      return sendRouteError(reply, error);
+    }
+  });
+
+  // 新建/上传(baseVersion 恒 null;已存在 → 409)
+  app.put("/database/api/projects/:id/file", async (request, reply) => {
+    const actor = await actorOrNull(request, reply, deps);
+    if (actor === null) return reply;
+    try {
+      const { id } = request.params as { id: string };
+      const body = bodyObject(request.body);
+      const result = await commitFile(fileDeps, actor, id, {
+        path: requireString(body, "path"),
+        baseVersion: null,
+        content: requireString(body, "content"),
+        encoding: encodingParam(body["encoding"]),
+        message: optionalString(body, "message"),
+      });
+      return reply.status(201).send(result);
+    } catch (error) {
+      return sendRouteError(reply, error);
+    }
+  });
+
+  // 提交编辑(乐观并发;409 → details.currentVersion + file.conflict_detected 审计)
+  app.post("/database/api/projects/:id/file/commits", async (request, reply) => {
+    const actor = await actorOrNull(request, reply, deps);
+    if (actor === null) return reply;
+    try {
+      const { id } = request.params as { id: string };
+      const body = bodyObject(request.body);
+      const baseVersion = body["baseVersion"];
+      if (typeof baseVersion !== "string" || baseVersion === "") {
+        throw new FileLibError(400, "invalid_request", "baseVersion must be a non-empty string");
+      }
+      return await commitFile(fileDeps, actor, id, {
+        path: requireString(body, "path"),
+        baseVersion,
+        content: requireString(body, "content"),
+        encoding: encodingParam(body["encoding"]),
+        message: optionalString(body, "message"),
+      });
+    } catch (error) {
+      return sendRouteError(reply, error);
+    }
+  });
+
+  app.delete("/database/api/projects/:id/file", async (request, reply) => {
+    const actor = await actorOrNull(request, reply, deps);
+    if (actor === null) return reply;
+    try {
+      const { id } = request.params as { id: string };
+      const body = bodyObject(request.body);
+      await deleteFile(fileDeps, actor, id, pathParam(request), requireString(body, "baseVersion"));
+      return reply.status(204).send();
+    } catch (error) {
+      return sendRouteError(reply, error);
+    }
+  });
+
+  app.get("/database/api/projects/:id/file/diff", async (request, reply) => {
+    const actor = await actorOrNull(request, reply, deps);
+    if (actor === null) return reply;
+    try {
+      const { id } = request.params as { id: string };
+      const query = request.query as { from?: string; to?: string };
+      if (query.from === undefined || query.to === undefined) {
+        throw new FileLibError(400, "invalid_request", "missing query: from / to");
+      }
+      return await diffFile(fileDeps, actor, id, pathParam(request), query.from, query.to);
+    } catch (error) {
+      return sendRouteError(reply, error);
+    }
+  });
+
+  app.get("/database/api/projects/:id/file/history", async (request, reply) => {
+    const actor = await actorOrNull(request, reply, deps);
+    if (actor === null) return reply;
+    try {
+      const { id } = request.params as { id: string };
+      const rawLimit = (request.query as { limit?: string }).limit;
+      const limit = rawLimit === undefined ? undefined : Number.parseInt(rawLimit, 10);
+      if (limit !== undefined && (!Number.isSafeInteger(limit) || limit <= 0)) {
+        throw new FileLibError(400, "invalid_request", "limit must be a positive integer");
+      }
+      return { history: await fileHistory(fileDeps, actor, id, pathParam(request), limit) };
+    } catch (error) {
+      return sendRouteError(reply, error);
+    }
+  });
+
+  /* ------------------------------------------------------------ 导出(D10 异步) */
+
+  app.post("/database/api/projects/:id/exports", async (request, reply) => {
+    const actor = await actorOrNull(request, reply, deps);
+    if (actor === null) return reply;
+    try {
+      const { id } = request.params as { id: string };
+      const body = bodyObject(request.body);
+      const params = body["params"];
+      if (params !== undefined && (typeof params !== "object" || params === null || Array.isArray(params))) {
+        throw new FileLibError(400, "invalid_request", "params must be an object");
+      }
+      const job = await submitExport(
+        exportDeps,
+        actor,
+        id,
+        requireString(body, "target"),
+        (params as Record<string, unknown> | undefined) ?? {},
+      );
+      return reply.status(202).send({ jobId: job.id, status: job.status });
+    } catch (error) {
+      return sendRouteError(reply, error);
+    }
+  });
+
+  app.get("/database/api/exports/:jobId", async (request, reply) => {
+    const actor = await actorOrNull(request, reply, deps);
+    if (actor === null) return reply;
+    try {
+      const { jobId } = request.params as { jobId: string };
+      return await getExportJob(exportDeps, actor, jobId);
+    } catch (error) {
+      return sendRouteError(reply, error);
+    }
+  });
+
+  app.get("/database/api/exports/:jobId/download", async (request, reply) => {
+    const actor = await actorOrNull(request, reply, deps);
+    if (actor === null) return reply;
+    try {
+      const { jobId } = request.params as { jobId: string };
+      const artifact = await downloadExport(exportDeps, actor, jobId);
+      return reply
+        .header("Content-Disposition", `attachment; filename="${artifact.filename}"`)
+        .type("application/octet-stream")
+        .send(artifact.content);
+    } catch (error) {
+      return sendRouteError(reply, error);
+    }
+  });
+}