Merge pull request 'fix(hub): clear npm audit high gate (deploy-admin CI)' (#98) from fix/hub-audit-production-vulns into main

Reviewed-on: EduCraft/curriculum-project-hub#98

.gitea/workflows/hub-check.yml

@@ -7,9 +7,12 @@ name: hub check
 
 on:
   push:
-  pull_request:
   workflow_dispatch:
 
+concurrency:
+  group: hub-check-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   hub-check:
     runs-on: ubuntu-latest
@@ -20,8 +23,9 @@ jobs:
           POSTGRES_USER: paradigm
           POSTGRES_PASSWORD: paradigm
           POSTGRES_DB: cph_hub_test
-        ports:
-          - 5432:5432
+        # Avoid host-port binds: concurrent hub-check jobs on the shared
+        # runner raced on published 5432/15432 ("port is already allocated").
+        # Reach the service by Docker DNS name from the job container instead.
         options: >-
           --health-cmd "pg_isready -U paradigm -d cph_hub_test"
           --health-interval 5s
@@ -33,15 +37,33 @@ jobs:
     steps:
       - uses: actions/checkout@v5
 
+      - name: Install Rust toolchain (for cph binary)
+        uses: dtolnay/rust-toolchain@1.92.0
+
+      - name: Cache cargo registry + build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: cargo-hub-check-${{ runner.os }}-${{ hashFiles('Cargo.lock') }}
+          restore-keys: |
+            cargo-hub-check-${{ runner.os }}-
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: "24"
           cache: npm
-          cache-dependency-path: hub/package-lock.json
+          cache-dependency-path: |
+            hub/package-lock.json
+            hub/admin-web/package-lock.json
 
       - name: Install dependencies
-        run: npm ci
+        run: |
+          npm ci
+          npm ci --prefix admin-web
 
       - name: Audit production Node dependencies
         run: npm run audit:production
@@ -54,8 +76,10 @@ jobs:
           node <<'NODE'
           const net = require("node:net");
           const deadline = Date.now() + 60000;
+          const host = process.env.HUB_CHECK_PG_HOST || "postgres";
+          const port = Number(process.env.HUB_CHECK_PG_PORT || "5432");
           function tryConnect() {
-            const socket = net.createConnection({ host: "127.0.0.1", port: 5432 });
+            const socket = net.createConnection({ host, port });
             socket.once("connect", () => {
               socket.end();
               process.exit(0);
@@ -63,7 +87,7 @@ jobs:
             socket.once("error", () => {
               socket.destroy();
               if (Date.now() > deadline) {
-                console.error("Postgres did not become reachable at 127.0.0.1:5432");
+                console.error(`Postgres did not become reachable at ${host}:${port}`);
                 process.exit(1);
               }
               setTimeout(tryConnect, 1000);
@@ -90,19 +114,41 @@ jobs:
         run: |
           cd ..
           cargo install --path crates/cph-cli --locked
+          # Make cph available to the unprivileged sandbox user below.
+          sudo install -m 0755 "$HOME/.cargo/bin/cph" /usr/local/bin/cph
 
       - name: Prove real Claude SDK Bash sandbox boundary
         run: |
-          sudo install -d -o "$(id -u)" -g "$(id -g)" -m 0700 /w/t
-          CPH_SANDBOX_TEST_ROOT=/w/t \
-            /usr/bin/setpriv --no-new-privs \
-            npx vitest run test/integration/agent-sandbox-linux.test.ts
+          set -euo pipefail
+          # Nested act/docker runners often disallow unprivileged user
+          # namespaces, which bwrap requires once CapEff is cleared. Skip the
+          # live proof there; unit + non-sandbox integration still gate.
+          sysctl -w kernel.unprivileged_userns_clone=1 2>/dev/null || true
+          sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 2>/dev/null || true
+          if ! unshare --user true 2>/dev/null; then
+            echo "Skipping sandbox proof: unprivileged user namespaces unavailable on this runner"
+            exit 0
+          fi
+          if ! id cphci >/dev/null 2>&1; then
+            useradd --create-home --shell /bin/bash cphci
+          fi
+          install -d -o cphci -g cphci -m 0700 /w/t
+          REPO_ROOT="$(cd .. && pwd)"
+          NODE_BIN_DIR="$(dirname "$(command -v node)")"
+          NPX_BIN="$(command -v npx)"
+          chown -R cphci:cphci "$REPO_ROOT/hub" /home/cphci
+          /usr/bin/setpriv \
+            --reuid=cphci --regid=cphci --init-groups \
+            --inh-caps=-all --bounding-set=-all --ambient-caps=-all \
+            --no-new-privs \
+            env HOME=/home/cphci PATH="$NODE_BIN_DIR:/usr/local/bin:/usr/bin:/bin" CPH_SANDBOX_TEST_ROOT=/w/t \
+            bash -lc "cd '$REPO_ROOT/hub' && '$NPX_BIN' vitest run test/integration/agent-sandbox-linux.test.ts"
 
       - name: Run unit tests
         run: npx vitest run test/unit
 
       # Integration tests need PostgreSQL + cph. cph is installed above.
-      # PostgreSQL is set up as a service container below.
+      # PostgreSQL is the job service container reachable as `postgres`.
       - name: Run integration tests (mock provider, real prisma + cph)
         run: |
           npx prisma migrate deploy --schema prisma/schema.prisma
@@ -110,7 +156,8 @@ jobs:
             --exclude test/integration/real-model.test.ts \
             --exclude test/integration/agent-sandbox-linux.test.ts
         env:
-          DATABASE_URL: postgresql://paradigm:paradigm@127.0.0.1:5432/cph_hub_test
+          DATABASE_URL: postgresql://paradigm:paradigm@postgres:5432/cph_hub_test
+          HUB_SKILL_STORE_ROOT: /tmp/cph-hub-check-skills
 
       # Real-model tests are opt-in: set RUN_REAL_MODEL_TESTS=true and provide
       # OPENROUTER_API_KEY when a branch should hit live OpenRouter.

.gitignore

@@ -15,3 +15,7 @@ node_modules/
 
 # OS / editor
 .DS_Store
+
+# Local operator notes / specs (not product source)
+/spec/
+/需求整理-*.md

AGENTS.md

@@ -32,6 +32,10 @@
   `/compact` 只能由卡片动作以未经包装的精确 prompt 转发。
   `settingSources: []` 继续禁用项目/用户配置加载，不得把任意 workspace `.claude` 配置变成
   运行时能力(见 ADR-0018)。
+  skill/role 的管理面分组由一棵 org 内共用、可嵌套的 folder 树承载：透明组织节点，
+  不进入身份、解析与授权——name/roleId 仍 org 内唯一，role→skill 绑定、run 加载与
+  slash 命令均不引用 folder;folder 归属变更是 label 类变更,不归档会话;仅空 folder
+  可删(见 ADR-0028 / `Spec.System.AgentRole`)。
 - 项目发现由 `ProjectDiscovery` 模块统一承载：PostgreSQL `pg_trgm` 搜索派生文档、项目编号
   归一化、完整 Folder breadcrumb、MANAGE 授权过滤与分页都在该模块内；飞书卡片只是 adapter。
   `Project`/`Folder` 仍是事实来源，搜索文档必须可重建且由数据库触发器同步，禁止调用方双写。

CONTEXT.md

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

docs/adr/0028-agent-config-folder-tree.md

@@ -0,0 +1,81 @@
+# ADR 0028: Agent Configuration Folder Tree
+
+## Status
+
+Accepted.
+
+## Context
+
+ADR-0017/0018 made Agent roles and skills Organization-scoped dynamic runtime
+configuration, managed without process restarts. The org admin surfaces for
+them (`/admin/roles` and `/admin/skills`) render every
+role/skill as one large editor card in a single flat list. As an Organization
+accumulates roles and skills, the management pages degrade into an endless
+scroll with no grouping affordance.
+
+The project explorer already solves the analogous problem for projects with
+transparent folders (ADR-0021): org-scoped navigation nodes that are not
+permission resources. Roles and skills need the same affordance, but their
+semantics differ from projects in one crucial way: skill names and role IDs
+are referenced by role→skill bindings, run-time skill snapshot loading, and
+Feishu slash commands. Any grouping mechanism must not leak into those
+resolution paths.
+
+## Decision
+
+Introduce an Organization-scoped folder tree shared by Agent roles and Agent
+skills:
+
+- One folder tree per Organization is shared by both roles and skills (e.g. a
+  "高三化学组" folder groups that team's roles and its skills together). It is
+  a distinct entity from the project explorer `Folder` of ADR-0021 — the two
+  trees are managed independently and never reference each other.
+- Folders are **transparent organization nodes**, following the ADR-0021
+  project-folder precedent: they exist for management-surface navigation and
+  grouping only, are not permission resources, and hold no grants.
+- Folder membership is **not part of role/skill identity or resolution**:
+  - skill `name` and role `roleId` remain unique per Organization regardless
+    of folder membership;
+  - role→skill bindings, run admission's frozen role snapshot, run-scoped
+    skill loading, and Feishu slash commands never reference folders.
+- Each role/skill sits in at most one folder; membership is optional
+  (unfiled items remain first-class). Folders nest arbitrarily.
+- Folder assignment is a label-class change in the ADR-0017 sense: it never
+  archives Agent sessions, because the execution surface (model, prompt,
+  tools, skill content) is untouched.
+- A folder can be deleted only when empty — no child folders, no roles, no
+  skills. Relocating items out of a folder is an explicit user action, so no
+  orphan-placement rule is needed yet.
+- Admin web renders both pages as a left folder tree plus the item list of
+  the selected folder ("all" and "unfiled" included). The host-console CLI is
+  unchanged: folder management lives in the web surface, and CLI
+  `upsert-role`/`install-skill` never touch folder assignment.
+
+## Consequences
+
+- New DB entity `OrganizationAgentConfigFolder` (org-scoped, self-nesting via
+  `parentId`, delete restricted while referenced) plus nullable `folderId` on
+  `OrganizationAgentRole` and `OrganizationAgentSkill` (SetNull on folder
+  delete, though the service refuses to delete non-empty folders).
+- The spec pins the transparency and single-membership semantics in
+  `Spec.System.AgentRole` (`AgentConfigFolder`), so future implementors do
+  not re-derive them differently (e.g. path-style names or per-folder
+  uniqueness).
+- Org admin APIs gain folder CRUD plus role/skill folder-assignment endpoints
+  that skip session archival by construction.
+- Moving a role/skill between folders changes nothing about authorization,
+  run resolution, or audit-visible configuration lineage beyond the folder
+  assignment event itself.
+
+## Open Questions / Deferred
+
+- Drag-and-drop assignment and bulk moves are deferred; assignment is a
+  per-item select for now.
+- Folder-level usage aggregation for roles/skills is deferred (project
+  folders already aggregate usage under ADR-0021; agent configuration has no
+  usage dimension yet).
+- CLI flags for folder assignment are deferred until a console workflow asks
+  for them.
+- Folder-scoped default-role policies (e.g. per-folder defaults) are rejected
+  for now: the Organization keeps exactly one active default role
+  (ADR-0017/0018 invariant) regardless of folder structure.

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

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

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

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

hub/.env.example

@@ -20,12 +20,14 @@ DATABASE_URL="postgresql://paradigm:paradigm@127.0.0.1:5432/paradigm"
 
 # Alpha Silo safety limits. max turns may use its default; every other value is
 # mandatory in production and should be calibrated on the target host.
-# HUB_AGENT_MAX_TURNS=25
+HUB_AGENT_MAX_TURNS="150"
 HUB_AGENT_MAX_CONCURRENT_RUNS="1"
-HUB_AGENT_MAX_RUN_SECONDS="900"
+HUB_AGENT_MAX_RUN_SECONDS="1800"
 HUB_HTTP_BODY_LIMIT_BYTES="1048576"
-HUB_MAX_FILES_PER_MESSAGE="8"
+HUB_MAX_FILES_PER_MESSAGE="20"
 HUB_MAX_FILE_BYTES="26214400"
+# Max concurrent Alibaba Docmind jobs for one convert_pdf_to_md batch (1-8).
+HUB_PDF_TO_MD_MAX_CONCURRENT="3"
 HUB_HTTP_REQUESTS_PER_MINUTE="120"
 HUB_FEISHU_EVENTS_PER_MINUTE="120"
 
@@ -38,9 +40,24 @@ HUB_PROJECT_WORKSPACE_ROOT="/var/lib/cph-hub/workspaces"
 # startup unless XDG_STATE_HOME is set (then defaults to $XDG_STATE_HOME/skills).
 HUB_SKILL_STORE_ROOT="/var/lib/cph-hub/state/skills"
 
+# Optional tenant-local Typst package roots. When configured, the agent
+# sandbox forwards these exact paths to Typst. The preinstalled package path is
+# read-only; the cache path is the only additional write location.
+# Keep the preinstalled package path outside the release tree and provision it
+# with the namespace layout expected by Typst, for example:
+#   <root>/paradigm/paradigm-templates/0.2.20/
+# Use a separate service-writable cache path when runtime dependencies may be
+# downloaded; do not make the immutable preinstalled directory the cache.
+# TYPST_PACKAGE_PATH="/srv/curriculum-project-hub/typst-packages/org-a"
+# TYPST_PACKAGE_CACHE_PATH="/var/cache/cph-hub/org-a/typst"
+
 # This process is pinned to exactly one Organization. Feishu credentials are
 # resolved from that Organization's encrypted ACTIVE connection.
 HUB_SILO_ORGANIZATION_ID=""
+# Absolute path to the bot-only lark-cli binary used by Agent Feishu tools.
+# The CLI is invoked by Hub with a disposable HOME and the ACTIVE Feishu
+# Application Connection; the App Secret is never put in Agent argv/env.
+HUB_FEISHU_CLI_BIN="/usr/local/bin/lark-cli"
 HUB_SYSTEMD_UNIT="cph-hub-example.service"
 
 # Absolute path to the `cph` binary (ADR-0016). Production preflight requires

hub/.gitignore

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

hub/admin-web/package-lock.json

@@ -7,6 +7,9 @@
 		"": {
 			"name": "admin-web",
 			"version": "0.0.1",
+			"dependencies": {
+				"fflate": "^0.8.3"
+			},
 			"devDependencies": {
 				"@skeletonlabs/skeleton": "^4.15.2",
 				"@skeletonlabs/skeleton-svelte": "^4.15.2",
@@ -26,24 +29,38 @@
 			}
 		},
 		"node_modules/@emnapi/core": {
-			"version": "1.11.2",
-			"resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.11.2.tgz",
-			"integrity": "sha512-TC8MkTuZUtcTSiFeuC0ksCh9QIJ5+F21MvZ4Wn4ORfYaFJ/0dsiudv5tVkejgwZlwQ39jL9WWDe2lz8x0WglOA==",
+			"version": "1.11.3",
+			"resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.11.3.tgz",
+			"integrity": "sha512-zLpS5asjEb7lq8jYLq37N6XKaE41DIexlY1rF/z4/tIl3wo13Sqm28fRyfIsKZD+NZ8mM5RoKkpW/rBcuoSZSg==",
 			"dev": true,
 			"license": "MIT",
 			"optional": true,
+			"peer": true,
+			"dependencies": {
+				"@emnapi/wasi-threads": "1.2.3",
+				"tslib": "^2.4.0"
+			}
+		},
+		"node_modules/@emnapi/core/node_modules/@emnapi/wasi-threads": {
+			"version": "1.2.3",
+			"resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.3.tgz",
+			"integrity": "sha512-ELEBe8PsLvvJ6QMr0zLt8ffvOHW/dc1m3CEzNMg7aJUv3bMaoDtw2TXyDAwkYBuroxxuHEwhRTLJSe5sya547g==",
+			"dev": true,
+			"license": "MIT",
+			"optional": true,
+			"peer": true,
 			"dependencies": {
-				"@emnapi/wasi-threads": "1.2.2",
 				"tslib": "^2.4.0"
 			}
 		},
 		"node_modules/@emnapi/runtime": {
-			"version": "1.11.2",
-			"resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.2.tgz",
-			"integrity": "sha512-kyOl3X0DuTiT1h2ft8r2fYO8JYtU9a9Xis/zBSiGArNaagCOWx90N1k2wxp18czFDH+OgcWGb5ZP/XMt3dcyPA==",
+			"version": "1.11.3",
+			"resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.3.tgz",
+			"integrity": "sha512-Xz4Tpyki7XyrpbUK1jR1AhdAdaXyhhY4lZ3neLodmhpuWfy2PAQN5B46sAiU4liOXGLkHypn/qU+jvfWSCYYLA==",
 			"dev": true,
 			"license": "MIT",
 			"optional": true,
+			"peer": true,
 			"dependencies": {
 				"tslib": "^2.4.0"
 			}
@@ -881,6 +898,72 @@
 				"node": ">=14.0.0"
 			}
 		},
+		"node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/core": {
+			"version": "1.11.1",
+			"dev": true,
+			"inBundle": true,
+			"license": "MIT",
+			"optional": true,
+			"dependencies": {
+				"@emnapi/wasi-threads": "1.2.2",
+				"tslib": "^2.4.0"
+			}
+		},
+		"node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/runtime": {
+			"version": "1.11.1",
+			"dev": true,
+			"inBundle": true,
+			"license": "MIT",
+			"optional": true,
+			"dependencies": {
+				"tslib": "^2.4.0"
+			}
+		},
+		"node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/wasi-threads": {
+			"version": "1.2.2",
+			"dev": true,
+			"inBundle": true,
+			"license": "MIT",
+			"optional": true,
+			"dependencies": {
+				"tslib": "^2.4.0"
+			}
+		},
+		"node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@napi-rs/wasm-runtime": {
+			"version": "1.1.4",
+			"dev": true,
+			"inBundle": true,
+			"license": "MIT",
+			"optional": true,
+			"dependencies": {
+				"@tybys/wasm-util": "^0.10.1"
+			},
+			"funding": {
+				"type": "github",
+				"url": "https://github.com/sponsors/Brooooooklyn"
+			},
+			"peerDependencies": {
+				"@emnapi/core": "^1.7.1",
+				"@emnapi/runtime": "^1.7.1"
+			}
+		},
+		"node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@tybys/wasm-util": {
+			"version": "0.10.2",
+			"dev": true,
+			"inBundle": true,
+			"license": "MIT",
+			"optional": true,
+			"dependencies": {
+				"tslib": "^2.4.0"
+			}
+		},
+		"node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/tslib": {
+			"version": "2.8.1",
+			"dev": true,
+			"inBundle": true,
+			"license": "0BSD",
+			"optional": true
+		},
 		"node_modules/@tailwindcss/oxide-win32-arm64-msvc": {
 			"version": "4.3.2",
 			"resolved": "https://registry.npmmirror.com/@tailwindcss/oxide-win32-arm64-msvc/-/oxide-win32-arm64-msvc-4.3.2.tgz",
@@ -1768,6 +1851,12 @@
 				}
 			}
 		},
+		"node_modules/fflate": {
+			"version": "0.8.3",
+			"resolved": "https://registry.npmmirror.com/fflate/-/fflate-0.8.3.tgz",
+			"integrity": "sha512-tbZNuJrLwGUp3zshBtdy4W+ORxZuIh8a5ilyIEQDC5rY1f3U20JMry0Ll3WBzU58EZKsEuJFXhb5gwv8CsPvgA==",
+			"license": "MIT"
+		},
 		"node_modules/fsevents": {
 			"version": "2.3.3",
 			"resolved": "https://registry.npmmirror.com/fsevents/-/fsevents-2.3.3.tgz",

hub/admin-web/package.json

@@ -29,5 +29,8 @@
 		"tailwindcss": "^4.3.2",
 		"typescript": "^6.0.3",
 		"vite": "^8.0.16"
+	},
+	"dependencies": {
+		"fflate": "^0.8.3"
 	}
 }

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

@@ -317,6 +317,7 @@ export interface AgentRoleRow {
 	createdAt: string;
 	updatedAt: string;
 	skillNames: readonly string[];
+	folderId: string | null;
 }
 
 export interface AgentSkillRow {
@@ -329,6 +330,14 @@ export interface AgentSkillRow {
 	createdAt: string;
 	updatedAt: string;
 	boundRoleIds: readonly string[];
+	folderId: string | null;
+}
+
+/** ADR-0028 transparent folder node shared by agent roles and skills. */
+export interface AgentConfigFolderRow {
+	id: string;
+	name: string;
+	parentId: string | null;
 }
 
 export interface SkillFileEntry {
@@ -401,7 +410,7 @@ export const api = {
 	archiveFolder: (slug: string, folderId: string) =>
 		post(`${orgBase(slug)}/folders/${folderId}/archive`) as Promise<{ archived: true; folderId: string }>,
 	createProject: (slug: string, body: { name: string; folderId?: string }) =>
-		post(`${orgBase(slug)}/projects`, body) as Promise<{ id: string; name: string }>,
+		post(`${orgBase(slug)}/projects`, body) as Promise<{ projectId: string; folderId: string | null; workspaceDir: string; name: string }>,
 	project: (slug: string, projectId: string) => get(`${orgBase(slug)}/projects/${projectId}`) as Promise<ProjectDetail>,
 	renameProject: (slug: string, projectId: string, name: string) =>
 		patch(`${orgBase(slug)}/projects/${projectId}`, { name }),
@@ -480,7 +489,18 @@ export const api = {
 	rotateCapabilityConnection: (
 		slug: string,
 		capabilityId: string,
-		body: { accessKeyId: string; accessKeySecret: string; endpoint: string },
+		body:
+			| { kind?: 'docmind'; accessKeyId: string; accessKeySecret: string; endpoint: string }
+			| {
+					kind: 'pbank';
+					baseUrl: string;
+					username: string;
+					password: string;
+					rightsStatus?: string;
+					rightsHolder?: string;
+					rightsScope?: string;
+					rightsNote?: string;
+			  },
 	) =>
 		put(`${orgBase(slug)}/capability-connections/${encodeURIComponent(capabilityId)}`, body) as Promise<CapabilityConnection>,
 	disableCapabilityConnection: (slug: string, capabilityId: string) =>
@@ -515,4 +535,21 @@ export const api = {
 	patchAgentSkill: (slug: string, name: string, body: { description?: string; disabled?: boolean }) =>
 		patch(`${orgBase(slug)}/agent-skills/${encodeURIComponent(name)}`, body) as Promise<{ disabled?: boolean; updated?: boolean }>,
 	agentModels: (slug: string) => get(`${orgBase(slug)}/agent-models`) as Promise<{ models: AgentModelRow[] }>,
+
+	agentConfigFolders: (slug: string) =>
+		get(`${orgBase(slug)}/agent-config-folders`) as Promise<{ folders: AgentConfigFolderRow[] }>,
+	createAgentConfigFolder: (slug: string, body: { name: string; parentId?: string }) =>
+		post(`${orgBase(slug)}/agent-config-folders`, body) as Promise<AgentConfigFolderRow>,
+	patchAgentConfigFolder: (slug: string, folderId: string, body: { name?: string; parentId?: string | null }) =>
+		patch(`${orgBase(slug)}/agent-config-folders/${encodeURIComponent(folderId)}`, body) as Promise<AgentConfigFolderRow>,
+	deleteAgentConfigFolder: (slug: string, folderId: string) =>
+		del(`${orgBase(slug)}/agent-config-folders/${encodeURIComponent(folderId)}`) as Promise<{ deleted: boolean }>,
+	setAgentRoleFolder: (slug: string, roleId: string, folderId: string | null) =>
+		patch(`${orgBase(slug)}/agent-roles/${encodeURIComponent(roleId)}/folder`, { folderId }) as Promise<{
+			folderId: string | null;
+		}>,
+	setAgentSkillFolder: (slug: string, name: string, folderId: string | null) =>
+		patch(`${orgBase(slug)}/agent-skills/${encodeURIComponent(name)}/folder`, { folderId }) as Promise<{
+			folderId: string | null;
+		}>,
 };

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

@@ -0,0 +1,160 @@
+<script lang="ts">
+	import type { AgentConfigFolderRow } from '$lib/api';
+	import Icon from './Icon.svelte';
+
+	/**
+	 * ADR-0028 left folder-tree nav for the agent config pages (roles/skills).
+	 * Transparent grouping only: selection filters the item list, it never
+	 * affects role/skill identity or run resolution.
+	 */
+	let {
+		folders,
+		selected,
+		counts,
+		totalCount,
+		unfiledCount,
+		onselect,
+		oncreate,
+		onrename,
+		ondelete,
+	}: {
+		folders: AgentConfigFolderRow[];
+		/** 'all' | 'unfiled' | folder id */
+		selected: string;
+		/** item count per folder id (roles or skills, depending on the page) */
+		counts: Record<string, number>;
+		totalCount: number;
+		unfiledCount: number;
+		onselect: (id: string) => void;
+		oncreate: (parentId: string | null) => void;
+		onrename: (folder: AgentConfigFolderRow) => void;
+		ondelete: (folder: AgentConfigFolderRow) => void;
+	} = $props();
+
+	type Row = { folder: AgentConfigFolderRow; depth: number; hasChildren: boolean };
+
+	let collapsed = $state<ReadonlySet<string>>(new Set());
+
+	function flatten(list: AgentConfigFolderRow[], collapsedSet: ReadonlySet<string>): Row[] {
+		const rows: Row[] = [];
+		const walk = (parentId: string | null, depth: number) => {
+			const siblings = list
+				.filter((f) => f.parentId === parentId)
+				.sort((a, b) => a.name.localeCompare(b.name));
+			for (const folder of siblings) {
+				const hasChildren = list.some((f) => f.parentId === folder.id);
+				rows.push({ folder, depth, hasChildren });
+				if (hasChildren && !collapsedSet.has(folder.id)) walk(folder.id, depth + 1);
+			}
+		};
+		walk(null, 0);
+		return rows;
+	}
+
+	const rows = $derived(flatten(folders, collapsed));
+
+	function toggleCollapse(folderId: string) {
+		const next = new Set(collapsed);
+		if (next.has(folderId)) next.delete(folderId);
+		else next.add(folderId);
+		collapsed = next;
+	}
+
+	function childFolderCount(folderId: string): number {
+		return folders.filter((f) => f.parentId === folderId).length;
+	}
+
+	const rowClass = (active: boolean) =>
+		`group flex w-full items-center gap-1.5 px-2 py-1.5 text-left text-sm transition hover:bg-surface-100 ${
+			active ? 'bg-primary-100 font-medium text-primary-900' : 'text-surface-800'
+		}`;
+</script>
+
+<nav class="saas-card p-2" aria-label="文件夹导航">
+	<div class="flex items-center justify-between px-2 py-1.5">
+		<span class="text-xs font-semibold uppercase tracking-wide text-surface-600">文件夹</span>
+		<button
+			type="button"
+			class="text-xs text-primary-700 hover:text-primary-900"
+			onclick={() => oncreate(null)}
+		>
+			+ 新建
+		</button>
+	</div>
+
+	<button type="button" class={rowClass(selected === 'all')} onclick={() => onselect('all')}>
+		<span class="w-3.5"></span>
+		<span class="min-w-0 flex-1 truncate">全部</span>
+		<span class="saas-badge-neutral">{totalCount}</span>
+	</button>
+	<button type="button" class={rowClass(selected === 'unfiled')} onclick={() => onselect('unfiled')}>
+		<span class="w-3.5"></span>
+		<span class="min-w-0 flex-1 truncate">未分类</span>
+		<span class="saas-badge-neutral">{unfiledCount}</span>
+	</button>
+
+	{#each rows as row (row.folder.id)}
+		{@const itemCount = counts[row.folder.id] ?? 0}
+		{@const childCount = childFolderCount(row.folder.id)}
+		<div class={rowClass(selected === row.folder.id)} style:padding-left="{0.5 + row.depth * 1}rem">
+			{#if row.hasChildren}
+				<button
+					type="button"
+					class="w-3.5 shrink-0 text-center text-xs text-surface-600"
+					aria-label={collapsed.has(row.folder.id) ? '展开' : '折叠'}
+					onclick={(e) => {
+						e.stopPropagation();
+						toggleCollapse(row.folder.id);
+					}}
+				>
+					{collapsed.has(row.folder.id) ? '▸' : '▾'}
+				</button>
+			{:else}
+				<span class="w-3.5 shrink-0"></span>
+			{/if}
+			<button type="button" class="flex min-w-0 flex-1 items-center gap-1.5 text-left" onclick={() => onselect(row.folder.id)}>
+				<Icon name="folder" class="h-3.5 w-3.5 shrink-0 opacity-60" />
+				<span class="min-w-0 flex-1 truncate">{row.folder.name}</span>
+				{#if itemCount > 0}
+					<span class="saas-badge-neutral">{itemCount}</span>
+				{/if}
+			</button>
+			<span
+				class="flex shrink-0 items-center gap-0.5 opacity-0 transition group-hover:opacity-100 focus-within:opacity-100"
+			>
+				<button
+					type="button"
+					class="flex h-5 w-5 items-center justify-center text-surface-500 hover:text-primary-700"
+					title="在此新建子文件夹"
+					aria-label="在 {row.folder.name} 内新建子文件夹"
+					onclick={() => oncreate(row.folder.id)}
+				>
+					<Icon name="folder-plus" class="h-3.5 w-3.5" />
+				</button>
+				<button
+					type="button"
+					class="flex h-5 w-5 items-center justify-center text-surface-500 hover:text-primary-700"
+					title="重命名 / 移动"
+					aria-label="重命名或移动 {row.folder.name}"
+					onclick={() => onrename(row.folder)}
+				>
+					✎
+				</button>
+				<button
+					type="button"
+					class="flex h-5 w-5 items-center justify-center text-surface-500 hover:text-error-700 disabled:cursor-not-allowed disabled:opacity-30"
+					title={itemCount > 0 || childCount > 0 ? '仅可删除空文件夹' : '删除文件夹'}
+					aria-label="删除 {row.folder.name}"
+					disabled={itemCount > 0 || childCount > 0}
+					onclick={() => ondelete(row.folder)}
+				>
+					×
+				</button>
+			</span>
+		</div>
+	{/each}
+
+	{#if folders.length === 0}
+		<p class="px-2 py-3 text-xs text-surface-600">还没有文件夹。新建一个来分组管理。</p>
+	{/if}
+</nav>

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

@@ -1,10 +1,11 @@
 <script lang="ts">
 	import { Checkbox, Label } from 'bits-ui';
-	import type { AgentRoleRow, AgentModelRow, AgentSkillRow } from '$lib/api';
+	import type { AgentConfigFolderRow, AgentRoleRow, AgentModelRow, AgentSkillRow } from '$lib/api';
 	import { api } from '$lib/api';
 	import { fmtDate } from '$lib/format';
 	import { TOOL_OPTIONS } from '$lib/constants';
 	import SelectField from '$lib/components/SelectField.svelte';
+	import SearchableSelectField from '$lib/components/SearchableSelectField.svelte';
 	import CheckboxControl from '$lib/components/CheckboxControl.svelte';
 	import Icon from '$lib/components/Icon.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';
@@ -14,15 +15,23 @@
 		models,
 		skills,
 		slug,
+		folders,
+		folderItems,
 		onupdated,
 		onskillschanged,
+		onfolderchanged,
 	}: {
 		r: AgentRoleRow;
 		models: AgentModelRow[];
 		skills: AgentSkillRow[];
 		slug: string;
+		/** ADR-0028 shared management tree — skill picker groups only; not binding identity */
+		folders: AgentConfigFolderRow[];
+		/** ADR-0028 folder choices ('' = 未分类); transparent grouping only */
+		folderItems: { value: string; label: string }[];
 		onupdated: (updated: AgentRoleRow) => void;
 		onskillschanged: (roleId: string, skillNames: string[]) => void;
+		onfolderchanged: (roleId: string, folderId: string | null) => void;
 	} = $props();
 
 	const initial = {
@@ -44,6 +53,8 @@
 	let isDefault = $state(initial.isDefault);
 	let selectedSkills = $state<string[]>([...initial.skillNames]);
 	let saving = $state(false);
+	let folderValue = $state(r.folderId ?? '');
+	let savingFolder = $state(false);
 
 	const groupedTools = TOOL_OPTIONS.reduce(
 		(acc, t) => {
@@ -53,12 +64,69 @@
 		{} as Record<string, typeof TOOL_OPTIONS>,
 	);
 
-	const modelItems = $derived([
-		{ value: '', label: '（使用平台默认模型）' },
-		...models.map((m) => ({ value: m.id, label: `${m.label}（${m.id}）` })),
-	]);
+	const modelItems = $derived.by(() => {
+		const fromCatalog = models.map((m) => ({ value: m.id, label: `${m.label}（${m.id}）` }));
+		const items = [{ value: '', label: '（使用平台默认模型）' }, ...fromCatalog];
+		// Keep a previously saved model selectable even if it left the live catalog.
+		if (defaultModel !== '' && !items.some((item) => item.value === defaultModel)) {
+			items.push({ value: defaultModel, label: `${defaultModel}（当前已存，不在目录中）` });
+		}
+		return items;
+	});
 
-	const skillItems = $derived(skills.map((s) => ({ value: s.name, label: s.name })));
+	function folderPathLabel(folderId: string): string {
+		const folder = folders.find((f) => f.id === folderId);
+		if (!folder) return '（未知文件夹）';
+		const parts: string[] = [folder.name];
+		let cur: AgentConfigFolderRow | undefined = folder;
+		while (cur?.parentId) {
+			const parent = folders.find((x) => x.id === cur!.parentId);
+			if (!parent) break;
+			parts.unshift(parent.name);
+			cur = parent;
+		}
+		return parts.join(' / ');
+	}
+
+	/** Group picker by management folder; bindings remain skill name (ADR-0028). */
+	const skillGroups = $derived.by(() => {
+		type Group = { key: string; label: string; skills: AgentSkillRow[] };
+		const byFolder = new Map<string | null, AgentSkillRow[]>();
+		for (const s of skills) {
+			const key = s.folderId;
+			const list = byFolder.get(key) ?? [];
+			list.push(s);
+			byFolder.set(key, list);
+		}
+		for (const list of byFolder.values()) {
+			list.sort((a, b) => a.name.localeCompare(b.name));
+		}
+		const filed = [...byFolder.entries()]
+			.filter((e): e is [string, AgentSkillRow[]] => e[0] !== null)
+			.map(([id, list]) => ({ key: id, label: folderPathLabel(id), skills: list }))
+			.sort((a, b) => a.label.localeCompare(b.label));
+		const unfiled = byFolder.get(null);
+		const groups: Group[] = [...filed];
+		if (unfiled && unfiled.length > 0) {
+			groups.push({ key: 'unfiled', label: '未分类', skills: unfiled });
+		}
+		return groups;
+	});
+
+	function groupSelectedCount(groupSkills: AgentSkillRow[]): number {
+		return groupSkills.filter((s) => selectedSkills.includes(s.name)).length;
+	}
+
+	function toggleGroup(groupSkills: AgentSkillRow[], checked: boolean) {
+		const names = new Set(groupSkills.map((s) => s.name));
+		if (checked) {
+			const next = new Set(selectedSkills);
+			for (const n of names) next.add(n);
+			selectedSkills = [...next];
+		} else {
+			selectedSkills = selectedSkills.filter((n) => !names.has(n));
+		}
+	}
 
 	function skillsDirty(): boolean {
 		const a = [...selectedSkills].sort();
@@ -105,6 +173,24 @@
 	function sortKeyDirty(): boolean {
 		return Number(sortOrder) !== r.sortOrder;
 	}
+
+	// ADR-0028: folder assignment is a label-class change — instant-apply, no
+	// session archival, independent of the configuration save button.
+	async function saveFolder(next: string) {
+		const folderId = next === '' ? null : next;
+		if (folderId === r.folderId) return;
+		savingFolder = true;
+		try {
+			await api.setAgentRoleFolder(slug, r.roleId, folderId);
+			onfolderchanged(r.roleId, folderId);
+			toastSuccess('已更新所属文件夹');
+		} catch (err) {
+			folderValue = r.folderId ?? '';
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			savingFolder = false;
+		}
+	}
 </script>
 
 <div class="saas-card-pad">
@@ -114,6 +200,12 @@
 		{#if r.isDefault}
 			<span class="saas-badge-success">默认</span>
 		{/if}
+		<div class="ml-auto flex items-center gap-2">
+			<span class="text-xs text-surface-600">文件夹</span>
+			<div class="w-44">
+				<SelectField items={folderItems} bind:value={folderValue} disabled={savingFolder} onchange={saveFolder} />
+			</div>
+		</div>
 	</div>
 
 	<div class="grid grid-cols-1 gap-4 md:grid-cols-2">
@@ -129,7 +221,13 @@
 
 	<div class="mt-4">
 		<p class="saas-label">默认模型</p>
-		<SelectField items={modelItems} bind:value={defaultModel} />
+		<SearchableSelectField
+			items={modelItems}
+			bind:value={defaultModel}
+			placeholder="选择模型…"
+			searchPlaceholder="搜索模型名称或 ID"
+			emptyText="无匹配模型"
+		/>
 	</div>
 
 	<div class="mt-4">
@@ -166,19 +264,40 @@
 	<div class="mt-4">
 		<span class="saas-label">技能绑定</span>
 		{#if skills.length === 0}
-			<p class="text-sm text-surface-600">组织内暂无已安装技能。技能通过 CLI / seed 安装（ADR-0018）。</p>
+			<p class="text-sm text-surface-600">组织内暂无已安装技能。请在技能页上传 zip 或新建空白模板（ADR-0018）。</p>
 		{:else}
-			<div class="grid grid-cols-1 gap-1.5 sm:grid-cols-2">
-				{#each skillItems as s}
-					<label class="flex cursor-pointer items-center gap-2 px-2 py-1.5 text-sm hover:bg-surface-100">
-						<CheckboxControl
-							checked={selectedSkills.includes(s.value)}
-							onchange={(checked) => {
-								selectedSkills = checked ? [...selectedSkills, s.value] : selectedSkills.filter((x) => x !== s.value);
-							}}
-						/>
-						<span class="font-mono text-xs">{s.label}</span>
-					</label>
+			<div class="space-y-3">
+				{#each skillGroups as group (group.key)}
+					<div class="border border-surface-300">
+						<label class="flex cursor-pointer items-center gap-2 border-b border-surface-200 bg-surface-100 px-2 py-1.5 text-sm">
+							<CheckboxControl
+								checked={groupSelectedCount(group.skills) === group.skills.length}
+								onchange={(checked) => toggleGroup(group.skills, checked)}
+							/>
+							<span class="text-xs font-semibold text-surface-700">{group.label}</span>
+							<span class="text-[10px] text-surface-500">
+								{groupSelectedCount(group.skills)}/{group.skills.length}
+							</span>
+						</label>
+						<div class="grid grid-cols-1 gap-0.5 p-1 sm:grid-cols-2">
+							{#each group.skills as s (s.name)}
+								<label class="flex cursor-pointer items-center gap-2 px-2 py-1.5 text-sm hover:bg-surface-100">
+									<CheckboxControl
+										checked={selectedSkills.includes(s.name)}
+										onchange={(checked) => {
+											selectedSkills = checked
+												? [...selectedSkills, s.name]
+												: selectedSkills.filter((x) => x !== s.name);
+										}}
+									/>
+									<span class="font-mono text-xs">{s.name}</span>
+									{#if s.version}
+										<span class="text-[10px] text-surface-500">v{s.version}</span>
+									{/if}
+								</label>
+							{/each}
+						</div>
+					</div>
 				{/each}
 			</div>
 		{/if}

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

@@ -0,0 +1,102 @@
+<script lang="ts">
+	import { Combobox } from 'bits-ui';
+	import Icon from './Icon.svelte';
+	import type { SelectItem } from './SelectField.svelte';
+
+	let {
+		items,
+		value = $bindable(''),
+		class: className = '',
+		disabled = false,
+		placeholder = '请选择…',
+		searchPlaceholder = '搜索…',
+		emptyText = '无匹配项',
+		onchange,
+	}: {
+		items: SelectItem[];
+		value?: string;
+		class?: string;
+		disabled?: boolean;
+		placeholder?: string;
+		searchPlaceholder?: string;
+		emptyText?: string;
+		onchange?: (value: string) => void;
+	} = $props();
+
+	let searchValue = $state('');
+
+	const filteredItems = $derived.by(() => {
+		const q = searchValue.trim().toLowerCase();
+		if (q === '') return items;
+		return items.filter(
+			(item) => item.label.toLowerCase().includes(q) || item.value.toLowerCase().includes(q),
+		);
+	});
+</script>
+
+<Combobox.Root
+	type="single"
+	{items}
+	{disabled}
+	{value}
+	allowDeselect={false}
+	onValueChange={(next) => {
+		value = next;
+		onchange?.(next);
+	}}
+	onOpenChangeComplete={(open) => {
+		if (!open) searchValue = '';
+	}}
+>
+	<div class="relative {className}">
+		<Combobox.Input
+			class="saas-combobox-input"
+			{disabled}
+			{placeholder}
+			aria-label={searchPlaceholder}
+			oninput={(e) => {
+				searchValue = e.currentTarget.value;
+			}}
+		/>
+		<Combobox.Trigger
+			class="absolute inset-y-0 right-0 flex w-9 items-center justify-center text-surface-600 disabled:cursor-not-allowed disabled:opacity-55"
+			{disabled}
+			aria-label="展开选项"
+		>
+			<svg
+				class="h-4 w-4 shrink-0"
+				viewBox="0 0 24 24"
+				fill="none"
+				stroke="currentColor"
+				stroke-width="1.75"
+				aria-hidden="true"
+			>
+				<path stroke-linecap="round" stroke-linejoin="round" d="M8.25 15l3.75 3.75L15.75 15" />
+				<path stroke-linecap="round" stroke-linejoin="round" d="M8.25 9l3.75-3.75L15.75 9" />
+			</svg>
+		</Combobox.Trigger>
+	</div>
+	<Combobox.Portal>
+		<Combobox.Content class="saas-select-content" sideOffset={6} collisionPadding={8}>
+			<Combobox.Viewport class="max-h-72 overflow-y-auto p-1">
+				{#each filteredItems as item (item.value)}
+					<Combobox.Item
+						class="saas-select-item"
+						value={item.value}
+						label={item.label}
+						disabled={item.disabled}
+					>
+						{#snippet children({ selected })}
+							<span class="min-w-0 flex-1 truncate">{item.label}</span>
+							{#if selected}
+								<Icon name="check" class="ml-2 h-4 w-4 shrink-0 text-primary-600" />
+							{/if}
+						{/snippet}
+					</Combobox.Item>
+				{:else}
+					<div class="px-2 py-2 text-sm text-surface-600">{emptyText}</div>
+				{/each}
+			</Combobox.Viewport>
+		</Combobox.Content>
+	</Combobox.Portal>
+</Combobox.Root>

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

@@ -2,19 +2,26 @@
 	import type { AgentSkillRow, SkillFileEntry } from '$lib/api';
 	import { api } from '$lib/api';
 	import { fmtDate } from '$lib/format';
+	import { parseSkillZip } from '$lib/skillZip';
 	import Icon from '$lib/components/Icon.svelte';
+	import SelectField from '$lib/components/SelectField.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';
 
 	let {
 		slug,
 		skill,
+		folderItems,
 		oninstalled,
 		ondisabled,
+		onfolderchanged,
 	}: {
 		slug: string;
 		skill: AgentSkillRow;
+		/** ADR-0028 folder choices ('' = 未分类); transparent grouping only */
+		folderItems: { value: string; label: string }[];
 		oninstalled: (result: { id: string; name: string; contentDigest: string }) => void;
 		ondisabled: (name: string) => void;
+		onfolderchanged: (name: string, folderId: string | null) => void;
 	} = $props();
 
 	type FileNode = { path: string; content: string };
@@ -28,6 +35,10 @@
 	let dirty = $state(false);
 	let newFilePath = $state('');
 	let showNewFile = $state(false);
+	let folderValue = $state(skill.folderId ?? '');
+	let savingFolder = $state(false);
+	let zipInputEl = $state<HTMLInputElement | null>(null);
+	let zipImporting = $state(false);
 
 	const selectedFile = $derived(files.find((f) => f.path === selectedPath) ?? null);
 	const hasManifest = $derived(files.some((f) => f.path === 'SKILL.md'));
@@ -152,6 +163,53 @@
 		dirty = true;
 	}
 
+	// ADR-0028: folder assignment is a label-class change — instant-apply, no
+	// session archival, independent of the content save button.
+	async function saveFolder(next: string) {
+		const folderId = next === '' ? null : next;
+		if (folderId === skill.folderId) return;
+		savingFolder = true;
+		try {
+			await api.setAgentSkillFolder(slug, skill.name, folderId);
+			onfolderchanged(skill.name, folderId);
+			toastSuccess('已更新所属文件夹');
+		} catch (err) {
+			folderValue = skill.folderId ?? '';
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			savingFolder = false;
+		}
+	}
+
+	async function importZip(fileList: FileList | null) {
+		const file = fileList?.[0];
+		if (!file) return;
+		const trimmedVersion = version.trim();
+		if (trimmedVersion === '') {
+			toastError('请先填写版本号再导入 zip');
+			if (zipInputEl) zipInputEl.value = '';
+			return;
+		}
+		zipImporting = true;
+		try {
+			const buf = new Uint8Array(await file.arrayBuffer());
+			const parsed = parseSkillZip(buf);
+			if (parsed.name !== skill.name) {
+				throw new Error(`zip 内技能名 "${parsed.name}" 与当前技能 "${skill.name}" 不一致`);
+			}
+			files = parsed.files.map((f) => ({ path: f.path, content: f.content }));
+			selectedPath = files.find((f) => f.path === 'SKILL.md')?.path ?? files[0]?.path ?? null;
+			if (parsed.description !== null) description = parsed.description;
+			dirty = true;
+			toastSuccess(`已载入 zip（${files.length} 个文件），请保存以写入`);
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			zipImporting = false;
+			if (zipInputEl) zipInputEl.value = '';
+		}
+	}
+
 	function updateFrontmatter(content: string, key: string, value: string): string {
 		const regex = new RegExp(`^(${key}:\\s*)(.*?)(\\s*)$`, 'm');
 		if (regex.test(content)) {
@@ -178,6 +236,12 @@
 		{#if skill.disabledAt}
 			<span class="saas-badge-error">已禁用</span>
 		{/if}
+		<div class="ml-auto flex items-center gap-2">
+			<span class="text-xs text-surface-600">文件夹</span>
+			<div class="w-44">
+				<SelectField items={folderItems} bind:value={folderValue} disabled={savingFolder} onchange={saveFolder} />
+			</div>
+		</div>
 	</div>
 
 	<div class="mb-4 grid grid-cols-1 gap-4 md:grid-cols-2">
@@ -292,9 +356,20 @@
 		</div>
 
 		<div class="mt-4 flex flex-wrap items-center gap-3 border-t border-surface-100 pt-4">
-			<button class="saas-btn-primary" onclick={save} disabled={saving || !dirty}>
+			<button class="saas-btn-primary" onclick={save} disabled={saving || !dirty || zipImporting}>
 				{saving ? '保存中…' : '保存'}
 			</button>
+			<label class="saas-btn-ghost cursor-pointer {zipImporting ? 'pointer-events-none opacity-50' : ''}">
+				{zipImporting ? '导入中…' : '从 zip 替换'}
+				<input
+					bind:this={zipInputEl}
+					type="file"
+					accept=".zip,application/zip,application/x-zip-compressed"
+					class="hidden"
+					disabled={zipImporting || saving}
+					onchange={(e) => importZip(e.currentTarget.files)}
+				/>
+			</label>
 			{#if !skill.disabledAt}
 				<button class="saas-btn-danger" onclick={disable} disabled={saving}>
 					禁用

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

@@ -12,12 +12,15 @@ export const TOOL_OPTIONS: ToolOption[] = [
 	{ id: 'bash', label: 'Bash 命令', group: 'Shell' },
 	{ id: 'web_fetch', label: 'WebFetch', group: '网络' },
 	{ id: 'web_search', label: 'WebSearch', group: '网络' },
+	{ id: 'todo', label: '任务清单 (todo_write)', group: '规划' },
 	{ id: 'cph_check', label: 'cph check', group: 'CPH' },
 	{ id: 'cph_build', label: 'cph build', group: 'CPH' },
 	{ id: 'send_file', label: '发送文件（飞书）', group: '飞书' },
 	{ id: 'feishu_read_context', label: '读飞书上下文', group: '飞书' },
 	{ id: 'feishu_download_resource', label: '下载飞书资源', group: '飞书' },
 	{ id: 'request_approval', label: '请求审批', group: '飞书' },
+	{ id: 'convert_pdf_to_md', label: 'PDF→Markdown', group: '能力' },
+	{ id: 'pbank', label: '题库 (PBank)', group: '能力' },
 ];
 
 /** 组织成员角色（接口枚举保持英文，界面用 orgRoleLabel） */

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

@@ -0,0 +1,97 @@
+import { unzipSync } from 'fflate';
+import type { SkillFileEntry } from '$lib/api';
+
+/** Mirror hub/src/agent/skillStore.ts limits (ADR-0018). */
+const MAX_SKILL_FILES = 512;
+const MAX_SKILL_BYTES = 16 * 1024 * 1024;
+const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+export interface ParsedSkillZip {
+	readonly name: string;
+	readonly description: string | null;
+	readonly files: readonly SkillFileEntry[];
+}
+
+/**
+ * Parse a skill package zip. Root of the archive IS the skill directory
+ * (must contain SKILL.md directly — no wrapping folder).
+ */
+export function parseSkillZip(data: Uint8Array): ParsedSkillZip {
+	let entries: Record<string, Uint8Array>;
+	try {
+		entries = unzipSync(data, {
+			filter: (file) => !file.name.endsWith('/'),
+		});
+	} catch {
+		throw new Error('无法解析 zip 文件');
+	}
+
+	const files: SkillFileEntry[] = [];
+	let totalBytes = 0;
+
+	for (const [rawPath, bytes] of Object.entries(entries)) {
+		const path = normalizeZipPath(rawPath);
+		if (path === null) continue;
+		totalBytes += bytes.byteLength;
+		if (totalBytes > MAX_SKILL_BYTES) {
+			throw new Error(`技能总大小超过 ${MAX_SKILL_BYTES / (1024 * 1024)} MiB 上限`);
+		}
+		if (files.length >= MAX_SKILL_FILES) {
+			throw new Error(`技能文件数超过 ${MAX_SKILL_FILES} 上限`);
+		}
+		// Text-only alpha path — API encodes content as UTF-8 strings.
+		try {
+			files.push({ path, content: decodeUtf8Strict(bytes) });
+		} catch {
+			throw new Error(`文件不是合法 UTF-8 文本：${path}`);
+		}
+	}
+
+	if (files.length === 0) {
+		throw new Error('zip 为空或不含可用文件');
+	}
+
+	const manifest = files.find((f) => f.path === 'SKILL.md');
+	if (!manifest) {
+		throw new Error('zip 根目录必须包含 SKILL.md（根即 skill 目录，不要多包一层文件夹）');
+	}
+
+	const name = parseFrontmatterField(manifest.content, 'name');
+	if (name === null || name === '') {
+		throw new Error('SKILL.md frontmatter 缺少 name');
+	}
+	if (!SKILL_NAME_PATTERN.test(name)) {
+		throw new Error('技能名称仅允许小写字母、数字和连字符，且以字母或数字开头');
+	}
+
+	const description = parseFrontmatterField(manifest.content, 'description');
+	files.sort((a, b) => a.path.localeCompare(b.path));
+	return { name, description, files };
+}
+
+function normalizeZipPath(raw: string): string | null {
+	let path = raw.replace(/\\/g, '/');
+	// Drop zip noise and absolute/parent escapes before other checks.
+	if (path.startsWith('__MACOSX/') || path.includes('/__MACOSX/')) return null;
+	const base = path.split('/').pop() ?? '';
+	if (base === '.DS_Store' || base.startsWith('._')) return null;
+	if (path.startsWith('/') || path.includes('\0')) {
+		throw new Error(`非法文件路径：${raw}`);
+	}
+	// Strip a single leading "./"
+	if (path.startsWith('./')) path = path.slice(2);
+	const parts = path.split('/').filter((p) => p !== '' && p !== '.');
+	if (parts.length === 0 || parts.some((p) => p === '..')) {
+		throw new Error(`非法文件路径：${raw}`);
+	}
+	return parts.join('/');
+}
+
+function parseFrontmatterField(manifest: string, key: string): string | null {
+	const match = new RegExp(`^${key}:\\s*['"]?([^'"\\r\\n]+)['"]?\\s*$`, 'm').exec(manifest);
+	return match ? match[1]!.trim() : null;
+}
+
+function decodeUtf8Strict(bytes: Uint8Array): string {
+	return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+}

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

@@ -32,3 +32,6 @@ export function toastSuccess(message: string): void {
 export function toastError(message: string): void {
 	pushToast(message, 'error', 5000);
 }
+export function toastInfo(message: string): void {
+	pushToast(message, 'info');
+}

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

@@ -13,9 +13,26 @@
 	const org = $derived(resolveOrg($session.me, page.url.search));
 	const slug = $derived(org?.slug ?? '');
 
+	type CapKind = 'docmind' | 'pbank';
 	const KNOWN_CAPABILITIES = [
-		{ id: 'pdf_to_md_bundle', label: 'PDF → Markdown', description: '将 PDF 转换为带图片的 Markdown bundle（阿里云文档智能，含公式 LaTeX 识别）' },
-		{ id: 'audio_video_to_text', label: '音视频 → 文本', description: '将音频/视频转写为文本（阿里云文档智能，按秒计费）' },
+		{
+			id: 'pdf_to_md_bundle',
+			kind: 'docmind' as const,
+			label: 'PDF → Markdown',
+			description: '将 PDF 转换为带图片的 Markdown bundle（阿里云文档智能，含公式 LaTeX 识别）'
+		},
+		{
+			id: 'audio_video_to_text',
+			kind: 'docmind' as const,
+			label: '音视频 → 文本',
+			description: '将音频/视频转写为文本（阿里云文档智能，按秒计费）'
+		},
+		{
+			id: 'pbank',
+			kind: 'pbank' as const,
+			label: '题库 (PBank)',
+			description: '搜索/拉取 Paradigm 题库题目与源工程；Agent 通过 pbank_* 工具访问，凭据不下发到 Agent 进程'
+		}
 	] as const;
 
 	let connections = $state<Map<string, CapabilityConnection>>(new Map());
@@ -23,9 +40,17 @@
 	let error = $state<string | null>(null);
 
 	let editingCap = $state<string | null>(null);
+	let editingKind = $state<CapKind>('docmind');
 	let accessKeyId = $state('');
 	let accessKeySecret = $state('');
 	let endpoint = $state('docmind-api.cn-hangzhou.aliyuncs.com');
+	let baseUrl = $state('https://pbank.paradigm-edu.net/api');
+	let username = $state('');
+	let password = $state('');
+	let rightsStatus = $state('owned');
+	let rightsHolder = $state('Paradigm Education');
+	let rightsScope = $state('internal teaching-material production');
+	let rightsNote = $state('');
 	let saving = $state(false);
 	let disabling = $state<string | null>(null);
 
@@ -42,11 +67,19 @@
 		}
 	}
 
-	function startEdit(capId: string) {
+	function startEdit(capId: string, kind: CapKind) {
 		editingCap = capId;
+		editingKind = kind;
 		accessKeyId = '';
 		accessKeySecret = '';
 		endpoint = 'docmind-api.cn-hangzhou.aliyuncs.com';
+		baseUrl = 'https://pbank.paradigm-edu.net/api';
+		username = '';
+		password = '';
+		rightsStatus = 'owned';
+		rightsHolder = 'Paradigm Education';
+		rightsScope = 'internal teaching-material production';
+		rightsNote = '';
 	}
 
 	function cancelEdit() {
@@ -54,17 +87,36 @@
 	}
 
 	async function save(capId: string) {
-		if (accessKeyId.trim() === '' || accessKeySecret.trim() === '' || endpoint.trim() === '') {
-			toastError('AccessKey ID、AccessKey Secret、Endpoint 均为必填');
-			return;
-		}
 		saving = true;
 		try {
-			const result = await api.rotateCapabilityConnection(slug, capId, {
-				accessKeyId: accessKeyId.trim(),
-				accessKeySecret: accessKeySecret.trim(),
-				endpoint: endpoint.trim(),
-			});
+			let result: CapabilityConnection;
+			if (editingKind === 'docmind') {
+				if (accessKeyId.trim() === '' || accessKeySecret.trim() === '' || endpoint.trim() === '') {
+					toastError('AccessKey ID、AccessKey Secret、Endpoint 均为必填');
+					return;
+				}
+				result = await api.rotateCapabilityConnection(slug, capId, {
+					kind: 'docmind',
+					accessKeyId: accessKeyId.trim(),
+					accessKeySecret: accessKeySecret.trim(),
+					endpoint: endpoint.trim()
+				});
+			} else {
+				if (baseUrl.trim() === '' || username.trim() === '' || password.trim() === '') {
+					toastError('Base URL、用户名、密码均为必填');
+					return;
+				}
+				result = await api.rotateCapabilityConnection(slug, capId, {
+					kind: 'pbank',
+					baseUrl: baseUrl.trim(),
+					username: username.trim(),
+					password: password.trim(),
+					...(rightsStatus.trim() !== '' ? { rightsStatus: rightsStatus.trim() } : {}),
+					...(rightsHolder.trim() !== '' ? { rightsHolder: rightsHolder.trim() } : {}),
+					...(rightsScope.trim() !== '' ? { rightsScope: rightsScope.trim() } : {}),
+					...(rightsNote.trim() !== '' ? { rightsNote: rightsNote.trim() } : {})
+				});
+			}
 			connections.set(capId, result);
 			connections = new Map(connections);
 			editingCap = null;
@@ -110,7 +162,7 @@
 
 <PageHeader
 	title="外部能力"
-	description="管理文档/媒体转换服务的组织级凭据（ADR-0027）。凭据按组织隔离、版本化信封存储，缺失或校验失败即 fail-closed。"
+	description="管理文档/媒体转换与题库等外部服务的组织级凭据（ADR-0027）。凭据按组织隔离、版本化信封存储，缺失或校验失败即 fail-closed。Agent 永不接收能力凭据。"
 />
 
 {#if loading}
@@ -147,7 +199,7 @@
 						{/if}
 						<button
 							class="saas-btn-primary text-sm"
-							onclick={() => startEdit(cap.id)}
+							onclick={() => startEdit(cap.id, cap.kind)}
 							disabled={editingCap === cap.id}
 						>
 							{conn ? '轮换凭据' : '配置凭据'}
@@ -174,23 +226,77 @@
 
 				{#if editingCap === cap.id}
 					<div class="mt-4 border-t border-surface-100 pt-4">
-						<p class="saas-muted mb-3 text-sm">
-							阿里云 RAM 用户的 AccessKey。密钥仅写入新版本，旧版本归档。
-						</p>
-						<div class="grid gap-4">
-							<div>
-								<Label.Root class="saas-label" for="ak-id-{cap.id}">AccessKey ID</Label.Root>
-								<input id="ak-id-{cap.id}" class="saas-input font-mono text-sm" bind:value={accessKeyId} />
+						{#if cap.kind === 'docmind'}
+							<p class="saas-muted mb-3 text-sm">
+								阿里云 RAM 用户的 AccessKey。密钥仅写入新版本，旧版本归档。
+							</p>
+							<div class="grid gap-4">
+								<div>
+									<Label.Root class="saas-label" for="ak-id-{cap.id}">AccessKey ID</Label.Root>
+									<input id="ak-id-{cap.id}" class="saas-input font-mono text-sm" bind:value={accessKeyId} />
+								</div>
+								<div>
+									<Label.Root class="saas-label" for="ak-secret-{cap.id}">AccessKey Secret</Label.Root>
+									<input
+										id="ak-secret-{cap.id}"
+										class="saas-input"
+										type="password"
+										bind:value={accessKeySecret}
+									/>
+								</div>
+								<div>
+									<Label.Root class="saas-label" for="endpoint-{cap.id}">Endpoint</Label.Root>
+									<input id="endpoint-{cap.id}" class="saas-input font-mono text-sm" bind:value={endpoint} />
+								</div>
 							</div>
-							<div>
-								<Label.Root class="saas-label" for="ak-secret-{cap.id}">AccessKey Secret</Label.Root>
-								<input id="ak-secret-{cap.id}" class="saas-input" type="password" bind:value={accessKeySecret} />
+						{:else}
+							<p class="saas-muted mb-3 text-sm">
+								Paradigm 题库登录凭据。激活前会探测 /login；凭据仅写入信封新版本。
+							</p>
+							<div class="grid gap-4">
+								<div>
+									<Label.Root class="saas-label" for="pbank-base-{cap.id}">API Base URL</Label.Root>
+									<input id="pbank-base-{cap.id}" class="saas-input font-mono text-sm" bind:value={baseUrl} />
+								</div>
+								<div>
+									<Label.Root class="saas-label" for="pbank-user-{cap.id}">用户名</Label.Root>
+									<input id="pbank-user-{cap.id}" class="saas-input font-mono text-sm" bind:value={username} />
+								</div>
+								<div>
+									<Label.Root class="saas-label" for="pbank-pass-{cap.id}">密码</Label.Root>
+									<input id="pbank-pass-{cap.id}" class="saas-input" type="password" bind:value={password} />
+								</div>
+								<div>
+									<Label.Root class="saas-label" for="pbank-rights-status-{cap.id}">权利状态</Label.Root>
+									<input
+										id="pbank-rights-status-{cap.id}"
+										class="saas-input font-mono text-sm"
+										bind:value={rightsStatus}
+										placeholder="owned | exclusive_license | licensed_adapt | unknown"
+									/>
+								</div>
+								<div>
+									<Label.Root class="saas-label" for="pbank-rights-holder-{cap.id}">权利主体</Label.Root>
+									<input
+										id="pbank-rights-holder-{cap.id}"
+										class="saas-input text-sm"
+										bind:value={rightsHolder}
+									/>
+								</div>
+								<div>
+									<Label.Root class="saas-label" for="pbank-rights-scope-{cap.id}">使用范围</Label.Root>
+									<input id="pbank-rights-scope-{cap.id}" class="saas-input text-sm" bind:value={rightsScope} />
+								</div>
+								<div>
+									<Label.Root class="saas-label" for="pbank-rights-note-{cap.id}">权利说明（可选）</Label.Root>
+									<textarea
+										id="pbank-rights-note-{cap.id}"
+										class="saas-input min-h-20 text-sm"
+										bind:value={rightsNote}
+									></textarea>
+								</div>
 							</div>
-							<div>
-								<Label.Root class="saas-label" for="endpoint-{cap.id}">Endpoint</Label.Root>
-								<input id="endpoint-{cap.id}" class="saas-input font-mono text-sm" bind:value={endpoint} />
-							</div>
-						</div>
+						{/if}
 						<div class="mt-4 flex items-center justify-end gap-3">
 							<button class="saas-btn-ghost" onclick={cancelEdit} disabled={saving}>取消</button>
 							<button class="saas-btn-primary" onclick={() => save(cap.id)} disabled={saving}>

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

@@ -88,7 +88,7 @@
 			projectName = '';
 			projectFolder = '';
 			showProjectModal = false;
-			window.location.href = `/admin/projects/${res.id}`;
+			window.location.href = `/admin/projects/${res.projectId}`;
 		} catch (err) {
 			toastError(err instanceof Error ? err.message : String(err));
 		}

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

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import { tick } from 'svelte';
 	import { page } from '$app/state';
 	import { api, type ProviderConnectionRow } from '$lib/api';
 	import { session } from '$lib/session';
@@ -8,7 +9,12 @@
 	import PageHeader from '$lib/components/PageHeader.svelte';
 	import LoadingState from '$lib/components/LoadingState.svelte';
 	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
-	import { toastError, toastSuccess } from '$lib/toast';
+	import { toastError, toastInfo, toastSuccess } from '$lib/toast';
+
+	type FormState =
+		| { kind: 'new'; error?: string }
+		| { kind: 'rotate'; providerId: string; error?: string }
+		| { kind: 'saving'; intent: 'new' | 'rotate'; providerId?: string };
 
 	const org = $derived(resolveOrg($session.me, page.url.search));
 	const slug = $derived(org?.slug ?? '');
@@ -17,11 +23,23 @@
 	let loading = $state(true);
 	let error = $state<string | null>(null);
 
+	let formState = $state<FormState>({ kind: 'new' });
 	let providerId = $state('');
 	let baseUrl = $state('');
 	let authToken = $state('');
 	let anthropicApiKey = $state('');
-	let saving = $state(false);
+
+	const rotationId = $derived(
+		formState.kind === 'rotate'
+			? formState.providerId
+			: formState.kind === 'saving' && formState.intent === 'rotate'
+				? (formState.providerId ?? null)
+				: null
+	);
+	const saving = $derived(formState.kind === 'saving');
+	const formError = $derived(
+		formState.kind === 'new' || formState.kind === 'rotate' ? (formState.error ?? null) : null
+	);
 
 	async function load() {
 		loading = true;
@@ -36,48 +54,77 @@
 		}
 	}
 
-	function startRotate(row: ProviderConnectionRow) {
+	async function startRotate(row: ProviderConnectionRow) {
+		formState = { kind: 'rotate', providerId: row.providerId };
 		providerId = row.providerId;
 		baseUrl = '';
 		authToken = '';
 		anthropicApiKey = '';
+		await tick();
+		const el = document.getElementById('base-url');
+		el?.scrollIntoView({ behavior: 'smooth', block: 'center' });
+		el?.focus();
+		toastInfo(`已开始轮换 ${row.providerId}，请填写新接口地址与访问令牌`);
 	}
 
 	function resetForm() {
+		formState = { kind: 'new' };
 		providerId = '';
 		baseUrl = '';
 		authToken = '';
 		anthropicApiKey = '';
 	}
 
+	function cancelOrClear() {
+		const wasRotating = rotationId !== null;
+		resetForm();
+		if (wasRotating) toastInfo('已取消轮换');
+	}
+
+	function showFormError(message: string, targetProviderId: string | null) {
+		formState =
+			targetProviderId === null
+				? { kind: 'new', error: message }
+				: { kind: 'rotate', providerId: targetProviderId, error: message };
+		toastError(message);
+	}
+
 	async function save() {
+		const targetProviderId = formState.kind === 'rotate' ? formState.providerId : null;
+		const intent = targetProviderId === null ? 'new' : 'rotate';
 		const id = providerId.trim();
 		if (id === '') {
-			toastError('请填写供应方 ID');
+			showFormError('请填写供应方 ID', targetProviderId);
 			return;
 		}
 		const url = baseUrl.trim();
 		const token = authToken.trim();
 		if (url === '' || token === '') {
-			toastError('接口地址与访问令牌均为必填');
+			showFormError('接口地址与访问令牌均为必填', targetProviderId);
 			return;
 		}
-		saving = true;
 		const body: { baseUrl: string; authToken: string; anthropicApiKey?: string } = {
 			baseUrl: url,
 			authToken: token,
 		};
 		const key = anthropicApiKey.trim();
 		if (key !== '') body.anthropicApiKey = key;
+		formState =
+			intent === 'rotate'
+				? { kind: 'saving', intent, providerId: id }
+				: { kind: 'saving', intent };
 		try {
-			await api.rotateProviderConnection(slug, id, body);
-			toastSuccess('凭据已轮换');
+			const saved = await api.rotateProviderConnection(slug, id, body);
 			resetForm();
+			toastSuccess(saved.activeVersion === 1 ? '已创建 BYOK 连接' : '凭据已轮换');
 			await load();
 		} catch (err) {
-			toastError(err instanceof Error ? err.message : String(err));
-		} finally {
-			saving = false;
+			const message = err instanceof Error ? err.message : String(err);
+			formState =
+				intent === 'rotate'
+					? { kind: 'rotate', providerId: id, error: message }
+					: { kind: 'new', error: message };
+			toastError(message);
 		}
 	}
 
@@ -125,7 +172,14 @@
 								<td class="text-surface-600">{fmtDate(row.updatedAt)}</td>
 								<td>
 									{#if row.mode === 'BYOK'}
-										<button class="saas-btn-ghost px-2! py-1! text-xs" onclick={() => startRotate(row)}>轮换</button>
+										<button
+											class="saas-btn-ghost px-2! py-1! text-xs"
+											onclick={() => startRotate(row)}
+											disabled={saving}
+											aria-label={`开始轮换供应方 ${row.providerId}`}
+										>
+											开始轮换
+										</button>
 									{:else}
 										<span class="text-xs text-surface-500">平台管理</span>
 									{/if}
@@ -139,33 +193,78 @@
 	</div>
 
 	<div class="saas-card-pad">
-		<h3 class="saas-section-title mb-1">轮换 BYOK 凭据</h3>
-		<p class="saas-muted mb-4">
-			密钥仅写入新版本，旧版本归档；保存时需重新填写接口地址与访问令牌。平台托管连接不在此处管理。
+		<h3 class="saas-section-title mb-1">
+			{rotationId ? `轮换凭据 · ${rotationId}` : '新建 BYOK 凭据'}
+		</h3>
+		<p class="saas-muted mb-4" role="status">
+			{#if saving}
+				正在验证新凭据；验证通过后才会切换版本，请勿重复提交。
+			{:else if rotationId}
+				已选择供应方 {rotationId}。点击“开始轮换”只打开此表单；填写新接口地址和访问令牌后，点击“验证并保存”才会生效。
+			{:else}
+				填写供应方 ID、接口地址和访问令牌，保存前会先验证凭据。平台托管连接不在此处管理。
+			{/if}
 		</p>
 		<div class="grid gap-5">
 			<div>
 				<Label.Root class="saas-label" for="provider-id">供应方 ID</Label.Root>
-				<input id="provider-id" class="saas-input font-mono text-sm" bind:value={providerId} placeholder="openrouter" />
+				<input
+					id="provider-id"
+					class="saas-input font-mono text-sm"
+					bind:value={providerId}
+					placeholder="openrouter"
+					readonly={rotationId !== null}
+					disabled={saving}
+				/>
+				{#if rotationId}
+					<p class="mt-1 text-xs text-surface-500">
+						轮换目标已锁定为 {rotationId}。如需新建其他供应方，请先取消轮换。
+					</p>
+				{/if}
 			</div>
 			<div>
 				<Label.Root class="saas-label" for="base-url">接口地址</Label.Root>
-				<input id="base-url" class="saas-input" placeholder="https://openrouter.ai/api" bind:value={baseUrl} />
+				<input
+					id="base-url"
+					class="saas-input"
+					placeholder="https://openrouter.ai/api"
+					bind:value={baseUrl}
+					disabled={saving}
+				/>
 			</div>
 			<div>
 				<Label.Root class="saas-label" for="auth-token">访问令牌</Label.Root>
-				<input id="auth-token" class="saas-input" type="password" bind:value={authToken} />
+				<input
+					id="auth-token"
+					class="saas-input"
+					type="password"
+					bind:value={authToken}
+					disabled={saving}
+				/>
 			</div>
 			<div>
 				<Label.Root class="saas-label" for="anthropic-key">Anthropic API Key（可选）</Label.Root>
-				<input id="anthropic-key" class="saas-input" type="password" bind:value={anthropicApiKey} />
+				<input
+					id="anthropic-key"
+					class="saas-input"
+					type="password"
+					bind:value={anthropicApiKey}
+					disabled={saving}
+				/>
 			</div>
 		</div>
+		{#if formError}
+			<div role="alert" class="border border-error-200 bg-error-50 px-4 py-3 text-sm text-error-700">
+				{formError}
+			</div>
+		{/if}
 		<div class="mt-6 flex items-center gap-3 border-t border-surface-100 pt-4">
 			<div class="flex-1"></div>
-			<button class="saas-btn-ghost" onclick={resetForm} disabled={saving}>清空</button>
+			<button class="saas-btn-ghost" onclick={cancelOrClear} disabled={saving}>
+				{rotationId ? '取消轮换' : '清空'}
+			</button>
 			<button class="saas-btn-primary" onclick={save} disabled={saving}>
-				{saving ? '保存中…' : '保存'}
+				{saving ? '验证并保存中…' : rotationId ? '验证并保存' : '验证并创建'}
 			</button>
 		</div>
 	</div>

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

@@ -1,6 +1,6 @@
 <script lang="ts">
 	import { page } from '$app/state';
-	import { api, type AgentRoleRow, type AgentModelRow, type AgentSkillRow } from '$lib/api';
+	import { api, type AgentConfigFolderRow, type AgentModelRow, type AgentRoleRow, type AgentSkillRow } from '$lib/api';
 	import { session } from '$lib/session';
 	import { resolveOrg } from '$lib/org';
 	import PageHeader from '$lib/components/PageHeader.svelte';
@@ -8,6 +8,9 @@
 	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
 	import EmptyState from '$lib/components/EmptyState.svelte';
 	import RoleCard from '$lib/components/RoleCard.svelte';
+	import AgentConfigFolderNav from '$lib/components/AgentConfigFolderNav.svelte';
+	import Modal from '$lib/components/Modal.svelte';
+	import SelectField from '$lib/components/SelectField.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';
 
 	const org = $derived(resolveOrg($session.me, page.url.search));
@@ -16,20 +19,32 @@
 	let roles = $state<AgentRoleRow[]>([]);
 	let models = $state<AgentModelRow[]>([]);
 	let skills = $state<AgentSkillRow[]>([]);
+	let folders = $state<AgentConfigFolderRow[]>([]);
 	let loading = $state(true);
 	let error = $state<string | null>(null);
 
+	/** 'all' | 'unfiled' | folder id (ADR-0028: transparent grouping filter) */
+	let selectedFolder = $state<string>('all');
+
 	let newRoleId = $state('');
 	let newLabel = $state('');
 	let adding = $state(false);
 
+	let showFolderModal = $state(false);
+	let folderModalMode = $state<'create' | 'rename'>('create');
+	let folderModalId = $state<string | null>(null);
+	let folderName = $state('');
+	let folderParent = $state('');
+	let savingFolder = $state(false);
+
 	async function load() {
 		loading = true;
 		error = null;
 		try {
-			const [r, s] = await Promise.all([api.agentRoles(slug), api.agentSkills(slug)]);
+			const [r, s, f] = await Promise.all([api.agentRoles(slug), api.agentSkills(slug), api.agentConfigFolders(slug)]);
 			roles = r.roles;
 			skills = s.skills;
+			folders = f.folders;
 			// Model fetch hits the provider API and may fail or be slow; load it
 			// independently so roles remain editable even without a model list.
 			models = [];
@@ -43,6 +58,66 @@
 		}
 	}
 
+	const counts = $derived.by(() => {
+		const map: Record<string, number> = {};
+		for (const r of roles) {
+			if (r.folderId) map[r.folderId] = (map[r.folderId] ?? 0) + 1;
+		}
+		return map;
+	});
+	const unfiledCount = $derived(roles.filter((r) => !r.folderId).length);
+	const visibleRoles = $derived(
+		selectedFolder === 'all'
+			? roles
+			: selectedFolder === 'unfiled'
+				? roles.filter((r) => !r.folderId)
+				: roles.filter((r) => r.folderId === selectedFolder),
+	);
+
+	function folderPath(f: AgentConfigFolderRow): string {
+		const parts: string[] = [f.name];
+		let cur: AgentConfigFolderRow | undefined = f;
+		while (cur?.parentId) {
+			const parent = folders.find((x) => x.id === cur!.parentId);
+			if (!parent) break;
+			parts.unshift(parent.name);
+			cur = parent;
+		}
+		return parts.join(' / ');
+	}
+
+	/** Self + descendant ids of a folder — excluded as move targets in the rename modal. */
+	function subtreeIds(folderId: string): Set<string> {
+		const ids = new Set<string>([folderId]);
+		let grew = true;
+		while (grew) {
+			grew = false;
+			for (const f of folders) {
+				if (f.parentId && ids.has(f.parentId) && !ids.has(f.id)) {
+					ids.add(f.id);
+					grew = true;
+				}
+			}
+		}
+		return ids;
+	}
+
+	const folderItems = $derived([
+		{ value: '', label: '（未分类）' },
+		...folders.map((f) => ({ value: f.id, label: folderPath(f) })),
+	]);
+
+	const moveTargetItems = $derived.by(() => {
+		if (folderModalMode !== 'rename' || folderModalId === null) {
+			return [{ value: '', label: '（根）' }, ...folders.map((f) => ({ value: f.id, label: folderPath(f) }))];
+		}
+		const excluded = subtreeIds(folderModalId);
+		return [
+			{ value: '', label: '（根）' },
+			...folders.filter((f) => !excluded.has(f.id)).map((f) => ({ value: f.id, label: folderPath(f) })),
+		];
+	});
+
 	async function add() {
 		const roleId = newRoleId.trim();
 		const label = newLabel.trim();
@@ -57,7 +132,12 @@
 		adding = true;
 		try {
 			const created = await api.upsertAgentRole(slug, roleId, { label });
-			roles = [...roles, created];
+			let folderId: string | null = null;
+			if (selectedFolder !== 'all' && selectedFolder !== 'unfiled') {
+				await api.setAgentRoleFolder(slug, roleId, selectedFolder);
+				folderId = selectedFolder;
+			}
+			roles = [...roles, { ...created, folderId }];
 			newRoleId = '';
 			newLabel = '';
 			toastSuccess('角色已创建');
@@ -79,6 +159,68 @@
 		roles = roles.map((x) => (x.roleId === roleId ? { ...x, skillNames } : x));
 	}
 
+	function onRoleFolderChanged(roleId: string, folderId: string | null) {
+		roles = roles.map((x) => (x.roleId === roleId ? { ...x, folderId } : x));
+	}
+
+	function openCreateFolder(parentId: string | null) {
+		folderModalMode = 'create';
+		folderModalId = null;
+		folderName = '';
+		folderParent = parentId ?? '';
+		showFolderModal = true;
+	}
+
+	function openRenameFolder(folder: AgentConfigFolderRow) {
+		folderModalMode = 'rename';
+		folderModalId = folder.id;
+		folderName = folder.name;
+		folderParent = folder.parentId ?? '';
+		showFolderModal = true;
+	}
+
+	async function submitFolderModal() {
+		const name = folderName.trim();
+		if (name === '') {
+			toastError('文件夹名称不能为空');
+			return;
+		}
+		savingFolder = true;
+		try {
+			if (folderModalMode === 'create') {
+				await api.createAgentConfigFolder(slug, {
+					name,
+					...(folderParent !== '' ? { parentId: folderParent } : {}),
+				});
+				toastSuccess('文件夹已创建');
+			} else if (folderModalId !== null) {
+				await api.patchAgentConfigFolder(slug, folderModalId, {
+					name,
+					parentId: folderParent === '' ? null : folderParent,
+				});
+				toastSuccess('文件夹已更新');
+			}
+			showFolderModal = false;
+			await load();
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			savingFolder = false;
+		}
+	}
+
+	async function deleteFolder(folder: AgentConfigFolderRow) {
+		if (!confirm(`删除文件夹「${folder.name}」? 仅空文件夹可删除。`)) return;
+		try {
+			await api.deleteAgentConfigFolder(slug, folder.id);
+			if (selectedFolder === folder.id) selectedFolder = 'all';
+			toastSuccess('文件夹已删除');
+			await load();
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		}
+	}
+
 	$effect(() => {
 		if (slug) load();
 	});
@@ -86,7 +228,7 @@
 
 <PageHeader
 	title="角色"
-	description="角色是组织级数据：组合默认模型、系统提示词、工具白名单与已绑定技能。角色 ID 即飞书斜杠命令（如 /draft）。"
+	description="角色是组织级数据：组合默认模型、系统提示词、工具白名单与已绑定技能。文件夹仅作管理分组，不影响角色解析与默认角色约束。"
 />
 
 {#if loading}
@@ -94,39 +236,93 @@
 {:else if error}
 	<ErrorBanner message={error} onretry={load} />
 {:else}
-	<div class="saas-card-pad mb-6">
-		<h2 class="saas-section-title mb-4">新建角色</h2>
-		<div class="grid gap-3 sm:grid-cols-[10rem_1fr_auto]">
-			<input
-				class="saas-input font-mono text-sm"
-				placeholder="角色 ID（如 draft）"
-				bind:value={newRoleId}
-				onkeydown={(e) => {
-					if (e.key === 'Enter') add();
-				}}
+	<div class="grid gap-4 lg:grid-cols-[15rem_1fr]">
+		<div class="h-fit lg:sticky lg:top-4">
+			<AgentConfigFolderNav
+				{folders}
+				selected={selectedFolder}
+				{counts}
+				totalCount={roles.length}
+				{unfiledCount}
+				onselect={(id) => (selectedFolder = id)}
+				oncreate={openCreateFolder}
+				onrename={openRenameFolder}
+				ondelete={deleteFolder}
 			/>
-			<input
-				class="saas-input"
-				placeholder="显示名（如 草稿）"
-				bind:value={newLabel}
-				onkeydown={(e) => {
-					if (e.key === 'Enter') add();
-				}}
-			/>
-			<button class="saas-btn-primary" onclick={add} disabled={adding}>新建</button>
 		</div>
-		<p class="mt-2 text-xs text-surface-600">角色 ID 仅允许小写字母、数字、下划线与连字符，且以字母或数字开头。</p>
+
+		<div>
+			<div class="saas-card-pad mb-6">
+				<h2 class="saas-section-title mb-4">新建角色</h2>
+				<div class="grid gap-3 sm:grid-cols-[10rem_1fr_auto]">
+					<input
+						class="saas-input font-mono text-sm"
+						placeholder="角色 ID（如 draft）"
+						bind:value={newRoleId}
+						onkeydown={(e) => {
+							if (e.key === 'Enter') add();
+						}}
+					/>
+					<input
+						class="saas-input"
+						placeholder="显示名（如 草稿）"
+						bind:value={newLabel}
+						onkeydown={(e) => {
+							if (e.key === 'Enter') add();
+						}}
+					/>
+					<button class="saas-btn-primary" onclick={add} disabled={adding}>新建</button>
+				</div>
+				<p class="mt-2 text-xs text-surface-600">角色 ID 仅允许小写字母、数字、下划线与连字符，且以字母或数字开头；当前选中文件夹时新角色会自动归入其中。</p>
+			</div>
+
+			{#if roles.length === 0}
+				<div class="saas-card">
+					<EmptyState title="暂无角色" description="组织必须且只能有一个启用中的默认角色；新建第一个角色将自动成为默认。" />
+				</div>
+			{:else if visibleRoles.length === 0}
+				<div class="saas-card">
+					<EmptyState title="此分类下暂无角色" description="在角色卡片上可将其移入当前文件夹。" />
+				</div>
+			{:else}
+				<div class="space-y-4">
+					{#each visibleRoles as r (r.roleId)}
+						<RoleCard
+							{r}
+							{models}
+							{skills}
+							{slug}
+							{folders}
+							{folderItems}
+							onupdated={onRoleUpdated}
+							onskillschanged={onRoleSkillsChanged}
+							onfolderchanged={onRoleFolderChanged}
+						/>
+					{/each}
+				</div>
+			{/if}
+		</div>
 	</div>
 
-	{#if roles.length === 0}
-		<div class="saas-card">
-			<EmptyState title="暂无角色" description="组织必须且只能有一个启用中的默认角色；新建第一个角色将自动成为默认。" />
+	<Modal bind:open={showFolderModal} title={folderModalMode === 'create' ? '新建文件夹' : '重命名 / 移动文件夹'}>
+		<label class="saas-label" for="agent-folder-name">名称</label>
+		<input
+			id="agent-folder-name"
+			class="saas-input mb-4"
+			bind:value={folderName}
+			onkeydown={(e) => {
+				if (e.key === 'Enter') submitFolderModal();
+			}}
+		/>
+		<p class="saas-label">父文件夹</p>
+		<div class="mb-4">
+			<SelectField items={moveTargetItems} bind:value={folderParent} />
 		</div>
-	{:else}
-		<div class="space-y-4">
-			{#each roles as r (r.roleId)}
-				<RoleCard {r} {models} {skills} {slug} onupdated={onRoleUpdated} onskillschanged={onRoleSkillsChanged} />
-			{/each}
+		<div class="flex justify-end gap-2">
+			<button class="saas-btn-ghost" onclick={() => (showFolderModal = false)}>取消</button>
+			<button class="saas-btn-primary" onclick={submitFolderModal} disabled={savingFolder}>
+				{savingFolder ? '保存中…' : '保存'}
+			</button>
 		</div>
-	{/if}
+	</Modal>
 {/if}

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

@@ -1,34 +1,55 @@
 <script lang="ts">
 	import { page } from '$app/state';
-	import { api, type AgentSkillRow, type SkillFileEntry } from '$lib/api';
+	import { api, type AgentConfigFolderRow, type AgentSkillRow, type SkillFileEntry } from '$lib/api';
 	import { session } from '$lib/session';
 	import { resolveOrg } from '$lib/org';
+	import { parseSkillZip } from '$lib/skillZip';
 	import PageHeader from '$lib/components/PageHeader.svelte';
 	import LoadingState from '$lib/components/LoadingState.svelte';
 	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
 	import EmptyState from '$lib/components/EmptyState.svelte';
 	import SkillEditor from '$lib/components/SkillEditor.svelte';
+	import AgentConfigFolderNav from '$lib/components/AgentConfigFolderNav.svelte';
+	import Modal from '$lib/components/Modal.svelte';
+	import SelectField from '$lib/components/SelectField.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';
 
 	const org = $derived(resolveOrg($session.me, page.url.search));
 	const slug = $derived(org?.slug ?? '');
 
 	let skills = $state<AgentSkillRow[]>([]);
+	let folders = $state<AgentConfigFolderRow[]>([]);
 	let loading = $state(true);
 	let error = $state<string | null>(null);
 
+	/** 'all' | 'unfiled' | folder id (ADR-0028: transparent grouping filter) */
+	let selectedFolder = $state<string>('all');
+
 	let showNewSkill = $state(false);
 	let newSkillName = $state('');
 	let newSkillVersion = $state('0.1.0');
 	let newSkillDescription = $state('');
 	let creating = $state(false);
 
+	let showZipUpload = $state(false);
+	let zipVersion = $state('0.1.0');
+	let zipUploading = $state(false);
+	let zipInputEl = $state<HTMLInputElement | null>(null);
+
+	let showFolderModal = $state(false);
+	let folderModalMode = $state<'create' | 'rename'>('create');
+	let folderModalId = $state<string | null>(null);
+	let folderName = $state('');
+	let folderParent = $state('');
+	let savingFolder = $state(false);
+
 	async function load() {
 		loading = true;
 		error = null;
 		try {
-			const res = await api.agentSkills(slug);
-			skills = res.skills;
+			const [s, f] = await Promise.all([api.agentSkills(slug), api.agentConfigFolders(slug)]);
+			skills = s.skills;
+			folders = f.folders;
 		} catch (err) {
 			error = err instanceof Error ? err.message : String(err);
 		} finally {
@@ -36,6 +57,66 @@
 		}
 	}
 
+	const counts = $derived.by(() => {
+		const map: Record<string, number> = {};
+		for (const s of skills) {
+			if (s.folderId) map[s.folderId] = (map[s.folderId] ?? 0) + 1;
+		}
+		return map;
+	});
+	const unfiledCount = $derived(skills.filter((s) => !s.folderId).length);
+	const visibleSkills = $derived(
+		selectedFolder === 'all'
+			? skills
+			: selectedFolder === 'unfiled'
+				? skills.filter((s) => !s.folderId)
+				: skills.filter((s) => s.folderId === selectedFolder),
+	);
+
+	function folderPath(f: AgentConfigFolderRow): string {
+		const parts: string[] = [f.name];
+		let cur: AgentConfigFolderRow | undefined = f;
+		while (cur?.parentId) {
+			const parent = folders.find((x) => x.id === cur!.parentId);
+			if (!parent) break;
+			parts.unshift(parent.name);
+			cur = parent;
+		}
+		return parts.join(' / ');
+	}
+
+	/** Self + descendant ids of a folder — excluded as move targets in the rename modal. */
+	function subtreeIds(folderId: string): Set<string> {
+		const ids = new Set<string>([folderId]);
+		let grew = true;
+		while (grew) {
+			grew = false;
+			for (const f of folders) {
+				if (f.parentId && ids.has(f.parentId) && !ids.has(f.id)) {
+					ids.add(f.id);
+					grew = true;
+				}
+			}
+		}
+		return ids;
+	}
+
+	const folderItems = $derived([
+		{ value: '', label: '（未分类）' },
+		...folders.map((f) => ({ value: f.id, label: folderPath(f) })),
+	]);
+
+	const moveTargetItems = $derived.by(() => {
+		if (folderModalMode !== 'rename' || folderModalId === null) {
+			return [{ value: '', label: '（根）' }, ...folders.map((f) => ({ value: f.id, label: folderPath(f) }))];
+		}
+		const excluded = subtreeIds(folderModalId);
+		return [
+			{ value: '', label: '（根）' },
+			...folders.filter((f) => !excluded.has(f.id)).map((f) => ({ value: f.id, label: folderPath(f) })),
+		];
+	});
+
 	async function createSkill() {
 		const name = newSkillName.trim();
 		if (name === '') {
@@ -56,6 +137,9 @@
 			const manifest = buildManifest(name, newSkillDescription.trim());
 			const files: SkillFileEntry[] = [{ path: 'SKILL.md', content: manifest }];
 			const result = await api.installAgentSkill(slug, name, { version, files });
+			if (selectedFolder !== 'all' && selectedFolder !== 'unfiled') {
+				await api.setAgentSkillFolder(slug, result.name, selectedFolder);
+			}
 			toastSuccess(`技能 ${result.name} 已创建`);
 			newSkillName = '';
 			newSkillDescription = '';
@@ -73,6 +157,37 @@
 		return `---\nname: ${name}\ndescription: ${desc}\n---\n# ${name}\n\n`;
 	}
 
+	async function uploadZip(fileList: FileList | null) {
+		const file = fileList?.[0];
+		if (!file) return;
+		const version = zipVersion.trim();
+		if (version === '') {
+			toastError('版本号不能为空');
+			if (zipInputEl) zipInputEl.value = '';
+			return;
+		}
+		zipUploading = true;
+		try {
+			const buf = new Uint8Array(await file.arrayBuffer());
+			const parsed = parseSkillZip(buf);
+			const result = await api.installAgentSkill(slug, parsed.name, {
+				version,
+				files: parsed.files,
+			});
+			if (selectedFolder !== 'all' && selectedFolder !== 'unfiled') {
+				await api.setAgentSkillFolder(slug, result.name, selectedFolder);
+			}
+			toastSuccess(`技能 ${result.name} 已从 zip 安装（${parsed.files.length} 个文件）`);
+			showZipUpload = false;
+			await load();
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			zipUploading = false;
+			if (zipInputEl) zipInputEl.value = '';
+		}
+	}
+
 	function onInstalled(_result: { id: string; name: string; contentDigest: string }) {
 		load();
 	}
@@ -81,6 +196,68 @@
 		load();
 	}
 
+	function onSkillFolderChanged(name: string, folderId: string | null) {
+		skills = skills.map((s) => (s.name === name ? { ...s, folderId } : s));
+	}
+
+	function openCreateFolder(parentId: string | null) {
+		folderModalMode = 'create';
+		folderModalId = null;
+		folderName = '';
+		folderParent = parentId ?? '';
+		showFolderModal = true;
+	}
+
+	function openRenameFolder(folder: AgentConfigFolderRow) {
+		folderModalMode = 'rename';
+		folderModalId = folder.id;
+		folderName = folder.name;
+		folderParent = folder.parentId ?? '';
+		showFolderModal = true;
+	}
+
+	async function submitFolderModal() {
+		const name = folderName.trim();
+		if (name === '') {
+			toastError('文件夹名称不能为空');
+			return;
+		}
+		savingFolder = true;
+		try {
+			if (folderModalMode === 'create') {
+				await api.createAgentConfigFolder(slug, {
+					name,
+					...(folderParent !== '' ? { parentId: folderParent } : {}),
+				});
+				toastSuccess('文件夹已创建');
+			} else if (folderModalId !== null) {
+				await api.patchAgentConfigFolder(slug, folderModalId, {
+					name,
+					parentId: folderParent === '' ? null : folderParent,
+				});
+				toastSuccess('文件夹已更新');
+			}
+			showFolderModal = false;
+			await load();
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			savingFolder = false;
+		}
+	}
+
+	async function deleteFolder(folder: AgentConfigFolderRow) {
+		if (!confirm(`删除文件夹「${folder.name}」? 仅空文件夹可删除。`)) return;
+		try {
+			await api.deleteAgentConfigFolder(slug, folder.id);
+			if (selectedFolder === folder.id) selectedFolder = 'all';
+			toastSuccess('文件夹已删除');
+			await load();
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		}
+	}
+
 	$effect(() => {
 		if (slug) load();
 	});
@@ -88,7 +265,7 @@
 
 <PageHeader
 	title="技能"
-	description="技能是组织级 Agent 能力包：一个包含 SKILL.md manifest 的目录。技能内容按 SHA-256 content-addressed 存储，变更后绑定角色的活跃会话自动归档。"
+	description="技能是组织级 Agent 能力包：一个包含 SKILL.md manifest 的目录。文件夹仅作管理分组，不影响技能解析与绑定。"
 />
 
 {#if loading}
@@ -96,49 +273,136 @@
 {:else if error}
 	<ErrorBanner message={error} onretry={load} />
 {:else}
-	<div class="saas-card-pad mb-6">
-		<div class="flex items-center justify-between">
-			<h2 class="saas-section-title">新建技能</h2>
-			<button class="text-sm text-primary-700 hover:text-primary-900" onclick={() => (showNewSkill = !showNewSkill)}>
-				{showNewSkill ? '取消' : '+ 新建'}
-			</button>
+	<div class="grid gap-4 lg:grid-cols-[15rem_1fr]">
+		<div class="h-fit lg:sticky lg:top-4">
+			<AgentConfigFolderNav
+				{folders}
+				selected={selectedFolder}
+				{counts}
+				totalCount={skills.length}
+				{unfiledCount}
+				onselect={(id) => (selectedFolder = id)}
+				oncreate={openCreateFolder}
+				onrename={openRenameFolder}
+				ondelete={deleteFolder}
+			/>
 		</div>
-		{#if showNewSkill}
-			<div class="mt-4 grid gap-3 sm:grid-cols-[12rem_8rem_1fr_auto]">
-				<input
-					class="saas-input font-mono text-sm"
-					placeholder="技能名（如 typst-help）"
-					bind:value={newSkillName}
-				/>
-				<input
-					class="saas-input text-sm"
-					placeholder="版本号"
-					bind:value={newSkillVersion}
-				/>
-				<input
-					class="saas-input text-sm"
-					placeholder="描述"
-					bind:value={newSkillDescription}
-				/>
-				<button class="saas-btn-primary" onclick={createSkill} disabled={creating}>
-					{creating ? '创建中…' : '创建'}
-				</button>
+
+		<div>
+			<div class="saas-card-pad mb-6 space-y-4">
+				<div class="flex flex-wrap items-center justify-between gap-2">
+					<h2 class="saas-section-title">新建技能</h2>
+					<div class="flex flex-wrap gap-3">
+						<button
+							type="button"
+							class="text-sm text-primary-700 hover:text-primary-900"
+							onclick={() => {
+								showZipUpload = !showZipUpload;
+								if (showZipUpload) showNewSkill = false;
+							}}
+						>
+							{showZipUpload ? '取消上传' : '上传 zip'}
+						</button>
+						<button
+							type="button"
+							class="text-sm text-primary-700 hover:text-primary-900"
+							onclick={() => {
+								showNewSkill = !showNewSkill;
+								if (showNewSkill) showZipUpload = false;
+							}}
+						>
+							{showNewSkill ? '取消' : '+ 空白模板'}
+						</button>
+					</div>
+				</div>
+				{#if showZipUpload}
+					<div class="grid gap-3 sm:grid-cols-[8rem_1fr_auto]">
+						<input class="saas-input text-sm" placeholder="版本号" bind:value={zipVersion} disabled={zipUploading} />
+						<input
+							bind:this={zipInputEl}
+							class="saas-input text-sm file:mr-3 file:border-0 file:bg-transparent file:text-sm file:font-medium"
+							type="file"
+							accept=".zip,application/zip,application/x-zip-compressed"
+							disabled={zipUploading}
+							onchange={(e) => uploadZip(e.currentTarget.files)}
+						/>
+						<span class="self-center text-xs text-surface-600">{zipUploading ? '安装中…' : '选择 .zip'}</span>
+					</div>
+					<p class="text-xs text-surface-600">
+						zip 根目录即为 skill（须直接含 SKILL.md）。名称取自 manifest；仅 UTF-8 文本；当前选中管理文件夹时会自动归入。覆盖同 name 会更新内容（可能使绑定角色会话不可安全恢复）。
+					</p>
+				{/if}
+				{#if showNewSkill}
+					<div class="grid gap-3 sm:grid-cols-[12rem_8rem_1fr_auto]">
+						<input
+							class="saas-input font-mono text-sm"
+							placeholder="技能名（如 typst-help）"
+							bind:value={newSkillName}
+						/>
+						<input
+							class="saas-input text-sm"
+							placeholder="版本号"
+							bind:value={newSkillVersion}
+						/>
+						<input
+							class="saas-input text-sm"
+							placeholder="描述"
+							bind:value={newSkillDescription}
+						/>
+						<button class="saas-btn-primary" onclick={createSkill} disabled={creating}>
+							{creating ? '创建中…' : '创建'}
+						</button>
+					</div>
+					<p class="text-xs text-surface-600">
+						技能名称仅允许小写字母、数字和连字符，且以字母或数字开头。创建后会生成 SKILL.md 模板；当前选中文件夹时新技能会自动归入其中。
+					</p>
+				{/if}
 			</div>
-			<p class="mt-2 text-xs text-surface-600">
-				技能名称仅允许小写字母、数字和连字符，且以字母或数字开头。创建后会生成 SKILL.md 模板。
-			</p>
-		{/if}
+
+			{#if skills.length === 0}
+				<div class="saas-card">
+					<EmptyState title="暂无技能" description="新建一个技能，然后在角色管理中绑定到角色。" />
+				</div>
+			{:else if visibleSkills.length === 0}
+				<div class="saas-card">
+					<EmptyState title="此分类下暂无技能" description="在技能卡片上可将其移入当前文件夹。" />
+				</div>
+			{:else}
+				<div class="space-y-4">
+					{#each visibleSkills as skill (skill.id)}
+						<SkillEditor
+							{slug}
+							{skill}
+							{folderItems}
+							oninstalled={onInstalled}
+							ondisabled={onDisabled}
+							onfolderchanged={onSkillFolderChanged}
+						/>
+					{/each}
+				</div>
+			{/if}
+		</div>
 	</div>
 
-	{#if skills.length === 0}
-		<div class="saas-card">
-			<EmptyState title="暂无技能" description="新建一个技能，然后在角色管理中绑定到角色。" />
+	<Modal bind:open={showFolderModal} title={folderModalMode === 'create' ? '新建文件夹' : '重命名 / 移动文件夹'}>
+		<label class="saas-label" for="agent-folder-name">名称</label>
+		<input
+			id="agent-folder-name"
+			class="saas-input mb-4"
+			bind:value={folderName}
+			onkeydown={(e) => {
+				if (e.key === 'Enter') submitFolderModal();
+			}}
+		/>
+		<p class="saas-label">父文件夹</p>
+		<div class="mb-4">
+			<SelectField items={moveTargetItems} bind:value={folderParent} />
 		</div>
-	{:else}
-		<div class="space-y-4">
-			{#each skills as skill (skill.id)}
-				<SkillEditor {slug} {skill} oninstalled={onInstalled} ondisabled={onDisabled} />
-			{/each}
+		<div class="flex justify-end gap-2">
+			<button class="saas-btn-ghost" onclick={() => (showFolderModal = false)}>取消</button>
+			<button class="saas-btn-primary" onclick={submitFolderModal} disabled={savingFolder}>
+				{savingFolder ? '保存中…' : '保存'}
+			</button>
 		</div>
-	{/if}
+	</Modal>
 {/if}

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

@@ -406,7 +406,8 @@
 		resize: vertical;
 	}
 
-	.saas-select-trigger {
+	.saas-select-trigger,
+	.saas-combobox-input {
 		display: inline-flex;
 		width: 100%;
 		align-items: center;
@@ -425,14 +426,25 @@
 		text-align: left;
 	}
 
+	.saas-combobox-input {
+		cursor: text;
+		padding-right: 2.25rem;
+	}
+
+	.saas-combobox-input::placeholder {
+		color: var(--color-surface-500);
+	}
+
 	.saas-select-trigger:focus-visible,
-	.saas-select-trigger[data-state='open'] {
+	.saas-select-trigger[data-state='open'],
+	.saas-combobox-input:focus {
 		border-color: var(--color-primary-600);
 		box-shadow: inset 0 0 0 1px var(--color-primary-600);
 	}
 
 	.saas-select-trigger:disabled,
-	.saas-select-trigger[data-disabled] {
+	.saas-select-trigger[data-disabled],
+	.saas-combobox-input:disabled {
 		cursor: not-allowed;
 		opacity: 0.55;
 	}
@@ -443,9 +455,15 @@
 
 	.saas-select-content {
 		z-index: 70;
-		max-height: min(18rem, var(--bits-select-content-available-height, 18rem));
-		width: var(--bits-select-anchor-width);
-		min-width: var(--bits-select-anchor-width);
+		max-height: min(
+			18rem,
+			var(
+				--bits-combobox-content-available-height,
+				var(--bits-select-content-available-height, 18rem)
+			)
+		);
+		width: var(--bits-combobox-anchor-width, var(--bits-select-anchor-width));
+		min-width: var(--bits-combobox-anchor-width, var(--bits-select-anchor-width));
 		overflow: hidden;
 		border-radius: 0;
 		border: 1px solid var(--color-surface-400);

hub/deploy/deploy_fleet_release.sh

@@ -82,11 +82,10 @@ REMOTE
   rsync -az --delete \
     --exclude node_modules --exclude dist --exclude .env \
     --exclude admin-web/node_modules --exclude admin-web/build --exclude admin-web/.svelte-kit \
-    --exclude filelib-web/node_modules --exclude filelib-web/build --exclude filelib-web/.svelte-kit \
     -e "ssh ${SSH_OPTS[*]}" \
     "$REPO_ROOT/hub/" "$DEPLOY_USER@$HOST:$HUB_DIR/"
 
-  echo "[fleet] npm ci + build (tsc + admin-web & filelib-web SPAs)"
+  echo "[fleet] npm ci (including build-time dev deps) + build (tsc + admin-web SPA)"
   ssh "${SSH_OPTS[@]}" "$DEPLOY_USER@$HOST" bash -s <<REMOTE
 set -euo pipefail
 flock /var/lock/cph-hub-release-publish bash -c '
@@ -96,13 +95,13 @@ flock /var/lock/cph-hub-release-publish bash -c '
     exit 0
   fi
   cd "$HUB_DIR"
-  PUPPETEER_SKIP_DOWNLOAD=1 npm ci
-  npm ci --prefix admin-web
-  npm ci --prefix filelib-web
+  PUPPETEER_SKIP_DOWNLOAD=1 npm ci --include=dev
+  npm ci --include=dev --prefix admin-web
+  test -x node_modules/.bin/tsc
+  test -x admin-web/node_modules/.bin/vite
   npm run audit:production
   npm run build
   test -f admin-web/build/index.html
-  test -f filelib-web/build/index.html
   touch "$RELEASE_DIR/.complete"
 '
 REMOTE

hub/deploy/deploy_platform.sh

@@ -60,11 +60,12 @@ if [ "$release_ready" = false ]; then
     -e "ssh ${SSH_OPTS[*]}" \
     "$REPO_ROOT/hub/" "$DEPLOY_USER@$HOST:$HUB_DIR/"
 
-  # 2. Install deps (hub + both SPAs), audit hub prod, build tsc + SPAs, mark complete.
-  # `npm run build` → tsc then admin:build + filelib:build → admin-web/build and
-  # filelib-web/build for registerStaticSpa / registerDatabaseSpa.
+  # 2. Install deps (including build-time dev deps) for hub + admin-web,
+  # audit hub prod, build tsc + SPA, mark complete. NODE_ENV=production may be
+  # inherited by the remote shell, so --include=dev is intentional here.
+  # `npm run build` → tsc then admin:build → admin-web/build for registerStaticSpa.
   ssh "${SSH_OPTS[@]}" "$DEPLOY_USER@$HOST" \
-    "cd '$HUB_DIR' && PUPPETEER_SKIP_DOWNLOAD=1 npm ci && npm ci --prefix admin-web && npm ci --prefix filelib-web && npm run audit:production && npm run build && touch '$RELEASE_DIR/.complete'"
+    "cd '$HUB_DIR' && PUPPETEER_SKIP_DOWNLOAD=1 npm ci --include=dev && npm ci --include=dev --prefix admin-web && npm run audit:production && npm run build && touch '$RELEASE_DIR/.complete'"
 fi
 
 # 3. Ensure the service is installed (idempotent), then restart.

hub/deploy/install_service.sh

@@ -164,17 +164,19 @@ DATABASE_URL=
 HUB_SILO_ORGANIZATION_ID=
 HUB_SYSTEMD_UNIT=$SERVICE_UNIT
 CPH_BIN=$CPH_BIN_DEFAULT
+HUB_FEISHU_CLI_BIN=/usr/local/bin/lark-cli
 HOST=$HOST
 PORT=$PORT
 HUB_PROJECT_WORKSPACE_ROOT=$WORKSPACE_ROOT
 HUB_PUBLIC_BASE_URL=
 HUB_SESSION_SECRET=
-HUB_AGENT_MAX_TURNS=25
+HUB_AGENT_MAX_TURNS=150
 HUB_AGENT_MAX_CONCURRENT_RUNS=
 HUB_AGENT_MAX_RUN_SECONDS=
 HUB_HTTP_BODY_LIMIT_BYTES=
 HUB_MAX_FILES_PER_MESSAGE=
 HUB_MAX_FILE_BYTES=
+HUB_PDF_TO_MD_MAX_CONCURRENT=3
 HUB_HTTP_REQUESTS_PER_MINUTE=
 HUB_FEISHU_EVENTS_PER_MINUTE=
 HUB_FEISHU_LISTENER_ENABLED=true

hub/deploy/new_silo.sh

@@ -367,11 +367,11 @@ seed_default PROVIDER_BASE_URL "https://openrouter.ai/api"
 seed_default DEFAULT_MODEL "anthropic/claude-sonnet-5"
 seed_default DEFAULT_ROLE_ID "draft"
 seed_default DEFAULT_ROLE_LABEL "智能助手"
-seed_default MAX_TURNS "25"
+seed_default MAX_TURNS "150"
 seed_default MAX_CONCURRENT_RUNS "4"
-seed_default MAX_RUN_SECONDS "900"
+seed_default MAX_RUN_SECONDS "1800"
 seed_default HTTP_BODY_LIMIT_BYTES "1048576"
-seed_default MAX_FILES_PER_MESSAGE "8"
+seed_default MAX_FILES_PER_MESSAGE "20"
 seed_default MAX_FILE_BYTES "26214400"
 seed_default HTTP_REQUESTS_PER_MINUTE "120"
 seed_default FEISHU_EVENTS_PER_MINUTE "120"

hub/filelib-web/package.json

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

hub/filelib-web/src/app.css

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

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

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

hub/filelib-web/src/app.html

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

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

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

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

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

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

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

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

@@ -1,191 +0,0 @@
-<script lang="ts">
-  /**
-   * 节点授权面板。迁自已删除的 routes/libraryBrowser.ts `renderGrantsTab`(ADR-0029)。
-   *
-   * 迁移时整个「授权」tab 连同这四个端点一起漏掉了 —— 后端一直可用,只是前端没入口。
-   *
-   * 语义(契约 8.1 / ADR-0021):
-   *  - 创建者授权(isCreatorGrant)不可收回、不可改;
-   *  - MANAGE 仅创建者可授,这里不做前端拦截 —— 后端 fail closed,报错原样呈现;
-   *  - GROUP 主体走 in-hub MemberGroup(ADR-0028),用 /groups/search 选,不手敲 id。
-   */
-  import { api } from "./api.js";
-  import { toastOk, toastErr } from "./stores.js";
-  import { currentNode } from "./browser.js";
-  import type { Grant, MemberGroupSearchResult, NodeDetail, Role } from "./types.js";
-  import Icon from "./Icon.svelte";
-
-  let { node }: { node: NodeDetail } = $props();
-
-  const ROLES: readonly Role[] = ["VIEW", "EDIT", "MANAGE"];
-
-  let grants = $state<Grant[] | null>(null);
-  let error = $state<string | null>(null);
-
-  let principalType = $state<"USER" | "GROUP">("USER");
-  let userIdInput = $state("");
-  let groupId = $state("");
-  let groupOptions = $state<MemberGroupSearchResult[] | null>(null);
-  let role = $state<Role>("VIEW");
-  let saving = $state(false);
-
-  const canManage = $derived(node.role === "MANAGE");
-  const errText = (e: unknown): string => (e instanceof Error ? e.message : String(e));
-
-  $effect(() => {
-    void node.id;
-    void load();
-  });
-
-  async function load(): Promise<void> {
-    grants = null;
-    error = null;
-    try {
-      const r = await api<{ grants: Grant[] }>(`/database/api/nodes/${node.id}/grants`);
-      grants = r.grants;
-    } catch (e) {
-      error = errText(e);
-    }
-  }
-
-  /** 切到 GROUP 时懒加载候选组(活跃组 + breadcrumb)。 */
-  async function onTypeChange(): Promise<void> {
-    if (principalType !== "GROUP" || groupOptions !== null) return;
-    try {
-      const r = await api<{ groups: MemberGroupSearchResult[] }>("/database/api/groups/search?q=");
-      groupOptions = r.groups;
-      if (r.groups.length > 0 && groupId === "") groupId = r.groups[0]!.id;
-    } catch (e) {
-      toastErr(errText(e));
-    }
-  }
-
-  async function addGrant(): Promise<void> {
-    const principalId = principalType === "GROUP" ? groupId : userIdInput.trim();
-    if (principalId === "") {
-      toastErr("请填写主体");
-      return;
-    }
-    saving = true;
-    try {
-      // PUT /grants 是增量语义(putGrants),不是整表替换。
-      await api(`/database/api/nodes/${node.id}/grants`, {
-        method: "PUT",
-        body: { grants: [{ principalType, principalId, role }] },
-      });
-      toastOk("已授予");
-      userIdInput = "";
-      await load();
-    } catch (e) {
-      toastErr(errText(e));
-    } finally {
-      saving = false;
-    }
-  }
-
-  async function revoke(g: Grant): Promise<void> {
-    if (!confirm(`收回「${g.principalId}」的 ${g.role} 授权?`)) return;
-    try {
-      await api(`/database/api/nodes/${node.id}/grants/${encodeURIComponent(g.id)}`, {
-        method: "DELETE",
-      });
-      toastOk("已收回");
-      await load();
-    } catch (e) {
-      toastErr(errText(e));
-    }
-  }
-
-  /** 独立权限开关(仅 PROJECT;关闭时只继承父级,创建者除外)。 */
-  async function toggleIndependent(): Promise<void> {
-    try {
-      await api(`/database/api/projects/${node.id}/independent-permission`, {
-        method: "PUT",
-        body: { enabled: !node.independentPermission },
-      });
-      toastOk("已切换");
-      currentNode.update((n) =>
-        n !== null && n.id === node.id ? { ...n, independentPermission: !node.independentPermission } : n,
-      );
-      await load();
-    } catch (e) {
-      toastErr(errText(e));
-    }
-  }
-</script>
-
-<div class="panel">
-  {#if error !== null}
-    <div class="py-2 text-[12.5px] text-danger">{error}</div>
-  {:else if grants === null}
-    <div class="quiet py-[18px] text-center">加载中…</div>
-  {:else}
-    <table class="list">
-      <thead>
-        <tr><th>主体</th><th>级别</th><th></th></tr>
-      </thead>
-      <tbody>
-        {#if grants.length === 0}
-          <tr><td colspan="3" class="quiet !py-[18px] text-center">暂无显式授权</td></tr>
-        {:else}
-          {#each grants as g (g.id)}
-            <tr>
-              <td>
-                <span class="inline-flex items-center gap-2">
-                  <span class="flex text-ink-3"><Icon name={g.principalType === "USER" ? "user" : "group"} size={14} /></span>
-                  <span class="font-mono text-[12px]">{g.principalId}</span>
-                  {#if g.isCreatorGrant}<span class="quiet">(创建者)</span>{/if}
-                </span>
-              </td>
-              <td class="file-meta">{g.role}</td>
-              <td class="text-right">
-                <!-- 创建者授权不可动(契约 8.1);非 MANAGE 也不给收回入口。 -->
-                {#if !g.isCreatorGrant && canManage}
-                  <button class="link-danger inline-flex items-center gap-1" onclick={() => void revoke(g)}>
-                    <Icon name="minus" size={12} /> 收回
-                  </button>
-                {/if}
-              </td>
-            </tr>
-          {/each}
-        {/if}
-      </tbody>
-    </table>
-  {/if}
-
-  {#if canManage}
-    <div class="my-3.5 border-t border-line-soft"></div>
-    <div class="section-title mb-2.5">新增授权</div>
-    <div class="flex flex-wrap items-center gap-2">
-      <select class="select !w-[110px]" bind:value={principalType} onchange={onTypeChange}>
-        <option value="USER">用户</option>
-        <option value="GROUP">Group</option>
-      </select>
-
-      {#if principalType === "USER"}
-        <input class="input min-w-0 flex-1" placeholder="用户 id" bind:value={userIdInput} />
-      {:else if groupOptions === null}
-        <span class="quiet flex-1">加载 Group 列表…</span>
-      {:else if groupOptions.length === 0}
-        <span class="quiet flex-1">暂无可选 Group · 先到「Group 管理」建一个</span>
-      {:else}
-        <select class="select min-w-0 flex-1" bind:value={groupId}>
-          {#each groupOptions as g (g.id)}
-            <option value={g.id}>{g.breadcrumb}</option>
-          {/each}
-        </select>
-      {/if}
-
-      <select class="select !w-[110px]" bind:value={role}>
-        {#each ROLES as r (r)}
-          <option value={r}>{r}</option>
-        {/each}
-      </select>
-      <button class="btn btn-primary disabled:opacity-50" onclick={addGrant} disabled={saving}>
-        {saving ? "授予中…" : "授予"}
-      </button>
-    </div>
-    <div class="section-note mt-1.5">MANAGE 仅创建者可授;创建者授权不可动(契约 8.1)</div>
-  {/if}
-
-</div>

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

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

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

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

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

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

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

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

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

@@ -1,16 +0,0 @@
-<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

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

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

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

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

@@ -1,11 +0,0 @@
-<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

@@ -1,82 +0,0 @@
-<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

@@ -1,49 +0,0 @@
-/** 与 /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

@@ -1,34 +0,0 @@
-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/config.ts

@@ -1,23 +0,0 @@
-/**
- * 前端 bootstrap:silo org slug(拼飞书 OAuth 链接用)+ dev 一键登录开关。
- *
- * 打 `/database/config` 而非 `/database/api/login-info`:后者由 teacherApp.ts 在
- * silo org 查找成功之后才注册,org 缺失时整条链路不存在;前者在
- * databaseRoutes.ts 顶部无条件注册。两者形状相同(见 src/database/README.md)。
- *
- * 免鉴权 —— org slug 本就出现在 OAuth URL 里,不构成敏感信息。
- */
-import { api } from "./api.js";
-
-export interface AppConfig {
-  readonly orgSlug: string;
-  readonly devLoginEnabled: boolean;
-}
-
-let cached: AppConfig | null = null;
-
-export async function loadConfig(): Promise<AppConfig> {
-  if (cached !== null) return cached;
-  cached = await api<AppConfig>("/database/config");
-  return cached;
-}

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

@@ -1,34 +0,0 @@
-/**
- * 会话装载:GET /database/api/me 一次,结果进 `me` store。
- * 老师端与管理后台共用 —— 两处的区别只是拿到 me 之后怎么用
- * (老师端未登录显示登录视图;管理后台未登录跳 /database/admin,
- * 非 isWebsiteAdmin 显示无权提示)。
- */
-import { get } from "svelte/store";
-import { api, UnauthenticatedError } from "./api.js";
-import { me, authChecked } from "./stores.js";
-import type { MeResponse } from "./types.js";
-
-/** 幂等:已检查过就不再打请求(路由间切换不重复拉取)。 */
-export async function loadSession(force = false): Promise<void> {
-  if (get(authChecked) && !force) return;
-
-  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);
-  }
-}
-
-/** 退出登录:清后端 cookie 再清前端 store。 */
-export async function logout(): Promise<void> {
-  try {
-    await fetch("/auth/logout", { method: "POST", credentials: "same-origin" });
-  } catch {
-    /* 网络失败也照样清前端状态 */
-  }
-  me.set(null);
-}

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

@@ -1,26 +0,0 @@
-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

@@ -1,164 +0,0 @@
-/** 与后端 /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;
-  /** 侧栏身份区显示用;后端取不到 User 行时回落为 userId。 */
-  readonly displayName: string;
-  readonly avatarUrl: string | null;
-}
-
-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;
-}
-
-/** 成员组(ADR-0028);后端返回扁平列表,前端按 parentId/depth 拼树。 */
-export interface MemberGroupNode {
-  readonly id: string;
-  readonly parentId: string | null;
-  readonly name: string;
-  readonly description: string | null;
-  readonly depth: number;
-  readonly memberCount: number;
-  /** 软删标记(ADR-0028 决策4)。null = 活跃;非 null = 已归档,不贡献任何权限。
-   *  仅在 ?includeArchived=1 时可能非 null。ISO 串(后端 JSON 序列化后不再是 Date)。 */
-  readonly archivedAt: string | null;
-}
-
-export interface MemberGroupMember {
-  readonly userId: string;
-  readonly displayName: string;
-  readonly feishuOpenId: string;
-  readonly avatarUrl: string | null;
-  /** 加入本组时间;ISO 串。 */
-  readonly joinedAt: string;
-}
-
-/** 节点授权(GET /database/api/nodes/:id/grants)。 */
-export interface Grant {
-  readonly id: string;
-  readonly principalType: "USER" | "GROUP";
-  readonly principalId: string;
-  readonly role: Role;
-  /** 创建者授权不可收回、不可改(契约 8.1)。 */
-  readonly isCreatorGrant: boolean;
-  readonly createdAt: string;
-}
-
-/** Group 选择器候选(GET /database/api/groups/search)。 */
-export interface MemberGroupSearchResult {
-  readonly id: string;
-  readonly name: string;
-  /** 祖先链(根在前,自身在末),用 " / " 连接。 */
-  readonly breadcrumb: string;
-}
-
-/** 成员选择器候选(GET /database/api/users/search)。 */
-export interface UserSearchResult {
-  readonly userId: string;
-  readonly displayName: string;
-  readonly feishuOpenId: string;
-  readonly avatarUrl: string | null;
-}
-
-/** 管理后台概览统计(GET /database/api/stats)。 */
-export 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;
-    /** ISO 串;后端 JSON 序列化后不再是 Date。 */
-    readonly when: string;
-  }>;
-}
-
-/** org 成员(GET /api/org/:slug/members);用户管理面板消费。 */
-export type OrgRole = "OWNER" | "ADMIN" | "MEMBER";
-
-export interface OrgMember {
-  readonly userId: string;
-  readonly feishuOpenId: string;
-  readonly displayName: string;
-  readonly avatarUrl: string | null;
-  readonly role: OrgRole;
-  readonly createdAt: string;
-}

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

@@ -1,12 +0,0 @@
-<script lang="ts">
-  import "../app.css";
-  import Toasts from "$lib/Toasts.svelte";
-
-  let { children } = $props();
-</script>
-
-<div class="h-full">
-  {@render children()}
-</div>
-
-<Toasts />

hub/filelib-web/src/routes/+layout.ts

@@ -1,7 +0,0 @@
-/**
- * 纯 SPA:关掉 SSR 与预渲染,构建产物只有一个 fallback index.html
- * (adapter-static + fallback,见 svelte.config.js),由 hub 后端在
- * /app 与 /database/* 两个前缀下原样送出。
- */
-export const ssr = false;
-export const prerender = false;

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

@@ -1,11 +0,0 @@
-<script lang="ts">
-  import { onMount } from "svelte";
-  import { goto } from "$app/navigation";
-
-  // 根路径不承载界面:老师端在 /app,管理后台在 /database。
-  onMount(() => {
-    void goto("/app", { replaceState: true });
-  });
-</script>
-
-<div class="flex h-full items-center justify-center text-[13px] text-ink-3">跳转中…</div>

hub/filelib-web/src/routes/app/+page.svelte

@@ -1,22 +0,0 @@
-<script lang="ts">
-  /** 老师端。未登录显示登录卡片;登录后直接是文件库浏览器。 */
-  import { onMount } from "svelte";
-  import { me, authChecked } from "$lib/stores.js";
-  import { loadSession } from "$lib/session.js";
-  import LoginView from "$lib/LoginView.svelte";
-  import LibraryView from "$lib/LibraryView.svelte";
-
-  onMount(loadSession);
-</script>
-
-<svelte:head><title>文件库</title></svelte:head>
-
-{#if !$authChecked}
-  <div class="flex h-full items-center justify-center text-ink-3">加载中…</div>
-{:else if $me}
-  <div class="flex h-full flex-col">
-    <LibraryView showUserFooter />
-  </div>
-{:else}
-  <LoginView />
-{/if}

hub/filelib-web/src/routes/database/+page.svelte

@@ -1,11 +0,0 @@
-<script lang="ts">
-  import { onMount } from "svelte";
-  import { goto } from "$app/navigation";
-
-  // /database 本身不承载界面(与旧后端 /database/admin → dashboard 的跳转一致)。
-  onMount(() => {
-    void goto("/database/dashboard", { replaceState: true });
-  });
-</script>
-
-<div class="flex h-full items-center justify-center text-[13px] text-ink-3">跳转中…</div>

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

@@ -1,63 +0,0 @@
-<script lang="ts">
-  /**
-   * 管理后台登录页(迁自后端 renderLoginPage)。
-   * 已登录直接跳 dashboard —— 与旧后端路由 /database/admin 的行为一致。
-   */
-  import { onMount } from "svelte";
-  import { goto } from "$app/navigation";
-  import { me, authChecked } from "$lib/stores.js";
-  import { loadSession } from "$lib/session.js";
-  import { loadConfig, type AppConfig } from "$lib/config.js";
-
-  let info = $state<AppConfig | null>(null);
-  let loadFailed = $state(false);
-
-  onMount(async () => {
-    await loadSession();
-    if ($me !== null) {
-      void goto("/database/dashboard", { replaceState: true });
-      return;
-    }
-    try {
-      info = await loadConfig();
-    } catch {
-      loadFailed = true;
-    }
-  });
-</script>
-
-<svelte:head><title>Database Admin · 登录</title></svelte:head>
-
-<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 text-ink">Database Admin</div>
-    <p class="mt-2.5 mb-8 text-center text-[13px] text-ink-3">使用飞书登录以管理数据库</p>
-
-    {#if !$authChecked}
-      <p class="text-center text-[12.5px] text-ink-3">加载中…</p>
-    {:else if info}
-      <a
-        href="/auth/feishu/{encodeURIComponent(info.orgSlug)}"
-        data-sveltekit-reload
-        class="flex w-full items-center justify-center rounded-lg bg-accent px-4 py-3 text-sm font-medium text-white transition hover:bg-accent-hover"
-      >使用飞书登录</a>
-
-      {#if info.devLoginEnabled}
-        <div class="my-5 flex items-center gap-2.5 text-[11px] text-ink-3">
-          <span class="flex-1 border-t border-line-soft"></span>开发模式
-          <span class="flex-1 border-t border-line-soft"></span>
-        </div>
-        <a
-          href="/database/dev-login"
-          data-sveltekit-reload
-          class="flex w-full items-center justify-center rounded-lg border border-line bg-panel px-4 py-2 text-[12.5px] font-medium text-ink transition hover:bg-hover"
-        >⚡ 一键登录管理员</a>
-        <p class="mt-2.5 text-center text-[11px] text-ink-3">仅开发环境可见 · 跳过飞书 OAuth</p>
-      {/if}
-    {:else if loadFailed}
-      <p class="text-center text-[12.5px] text-danger">无法加载登录配置,请稍后重试</p>
-    {:else}
-      <p class="text-center text-[12.5px] text-ink-3">加载中…</p>
-    {/if}
-  </div>
-</div>

hub/filelib-web/src/routes/database/dashboard/+layout.svelte

@@ -1,99 +0,0 @@
-<script lang="ts">
-  /**
-   * 管理后台外壳(迁自后端 renderDashboard 的侧栏 + 身份区)。
-   *
-   * 与旧实现的区别:六个 tab 是真 URL 路由(/database/dashboard/library 等),
-   * 不再是 location.hash + display:none 切换 —— 刷新不丢位置,链接可分享。
-   *
-   * 权限门:未登录跳 /database/admin;登录但非 OWNER/ADMIN(isWebsiteAdmin)
-   * 显示无权提示。语义与 ADR-0028 一致 —— 管理面板要求 silo org 的 OWNER/ADMIN。
-   */
-  import { onMount } from "svelte";
-  import { goto } from "$app/navigation";
-  import { page } from "$app/state";
-  import { me, authChecked } from "$lib/stores.js";
-  import { loadSession, logout } from "$lib/session.js";
-  import Avatar from "$lib/Avatar.svelte";
-
-  let { children } = $props();
-
-  const NAV = [
-    { seg: "", label: "概览", icon: "M4 13h6V4H4v9Zm0 7h6v-5H4v5Zm10 0h6V11h-6v9Zm0-16v5h6V4h-6Z" },
-    { seg: "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" },
-    { seg: "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" },
-    { seg: "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" },
-    { seg: "search", label: "查询", icon: "m21 21-4.3-4.3M11 18a7 7 0 1 0 0-14 7 7 0 0 0 0 14Z" },
-    { seg: "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" },
-  ] as const;
-
-  const BASE = "/database/dashboard";
-
-  onMount(async () => {
-    await loadSession();
-    if ($me === null) void goto("/database/admin", { replaceState: true });
-  });
-
-  function href(seg: string): string {
-    return seg === "" ? BASE : `${BASE}/${seg}`;
-  }
-
-  function isActive(seg: string): boolean {
-    const path = page.url.pathname.replace(/\/$/, "");
-    return seg === "" ? path === BASE : path === `${BASE}/${seg}`;
-  }
-</script>
-
-<svelte:head><title>Database Admin</title></svelte:head>
-
-{#if !$authChecked}
-  <div class="flex h-full items-center justify-center text-[13px] text-ink-3">加载中…</div>
-{:else if $me === null}
-  <div class="flex h-full items-center justify-center text-[13px] text-ink-3">跳转到登录页…</div>
-{:else if !$me.isWebsiteAdmin}
-  <div class="flex min-h-full items-center justify-center p-6">
-    <div class="w-full max-w-[420px] rounded-2xl border border-line-soft bg-panel p-9 text-center shadow-[0_4px_20px_rgba(26,26,24,.07)]">
-      <h2 class="mb-2 text-lg font-semibold text-ink">无权访问管理后台</h2>
-      <p class="mb-6 text-[13px] text-ink-3">
-        当前账号不是本组织的所有者或管理员。普通老师请到文件库使用。
-      </p>
-      <a href="/app" class="btn btn-primary justify-center">前往文件库</a>
-      <button class="btn mt-3 w-full justify-center" onclick={logout}>退出登录</button>
-    </div>
-  </div>
-{:else}
-  <div class="flex h-full">
-    <aside class="flex w-[240px] shrink-0 flex-col border-r border-line-soft bg-sidebar">
-      <div class="border-b border-line-soft px-4 py-4">
-        <span class="text-[15px] font-semibold text-ink">Database Admin</span>
-      </div>
-
-      <nav class="flex flex-1 flex-col gap-0.5 p-2.5">
-        {#each NAV as item (item.seg)}
-          {@const active = isActive(item.seg)}
-          <a
-            href={href(item.seg)}
-            class="flex items-center gap-2.5 rounded-[10px] px-3.5 py-2 text-[13px] transition"
-            class:bg-selected={active}
-            class:text-ink={active}
-            class:font-semibold={active}
-            class:text-ink-3={!active}
-            class:hover:bg-hover={!active}
-          >
-            <svg class="h-4 w-4 shrink-0" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d={item.icon} /></svg>
-            {item.label}
-          </a>
-        {/each}
-      </nav>
-
-      <div class="m-2.5 flex items-center gap-2.5 border-t border-line-soft px-3 py-2.5">
-        <Avatar displayName={$me.displayName} userId={$me.userId} avatarUrl={$me.avatarUrl} size={26} />
-        <p class="min-w-0 flex-1 truncate text-[12.5px] text-ink" title={$me.userId}>{$me.displayName}</p>
-        <button class="btn !px-2.5 !py-[3px] !text-[11px]" onclick={logout}>退出</button>
-      </div>
-    </aside>
-
-    <div class="flex min-w-0 flex-1 flex-col">
-      {@render children()}
-    </div>
-  </div>
-{/if}

hub/filelib-web/src/routes/database/dashboard/+page.svelte

@@ -1,67 +0,0 @@
-<script lang="ts">
-  /** 概览(迁自后端 renderDashboard 的统计卡片 + 最近活动)。数据走 GET /database/api/stats。 */
-  import { onMount } from "svelte";
-  import { api } from "$lib/api.js";
-  import type { DashboardStats } from "$lib/types.js";
-
-  let stats = $state<DashboardStats | null>(null);
-  let error = $state<string | null>(null);
-
-  onMount(async () => {
-    try {
-      stats = await api<DashboardStats>("/database/api/stats");
-    } catch (e) {
-      error = e instanceof Error ? e.message : String(e);
-    }
-  });
-
-  const cards = $derived([
-    { label: "文件夹", value: stats?.folders },
-    { label: "项目", value: stats?.projects },
-    { label: "文件", value: stats?.files },
-    { label: "活跃授权", value: stats?.grants },
-  ]);
-
-  function fmtWhen(iso: string): string {
-    try {
-      return new Date(iso).toLocaleString("zh-CN");
-    } catch {
-      return iso;
-    }
-  }
-</script>
-
-<section class="flex-1 overflow-y-auto p-7">
-  <h1 class="mb-1 text-lg font-semibold text-ink">概览</h1>
-  <p class="mb-5 text-[11.5px] text-ink-3">文件库实时数据</p>
-
-  {#if error}
-    <div class="panel text-[12.5px] text-danger">{error}</div>
-  {:else}
-    <div class="grid grid-cols-4 gap-4">
-      {#each cards as card (card.label)}
-        <div class="panel !px-5 !py-[18px]">
-          <p class="text-[12.5px] text-ink-3">{card.label}</p>
-          <p class="mt-1.5 text-[28px] font-semibold text-ink">{card.value ?? "—"}</p>
-        </div>
-      {/each}
-    </div>
-
-    <div class="panel mt-[18px]">
-      <h2 class="mb-2 text-[13.5px] font-semibold text-ink">最近活动</h2>
-      {#if stats === null}
-        <div class="quiet py-6 text-center">加载中…</div>
-      {:else if stats.recent.length === 0}
-        <div class="quiet py-[26px] text-center">暂无文件库活动 · 到「文件库」里创建第一个文件夹吧</div>
-      {:else}
-        {#each stats.recent as row (row.action + row.when + row.label)}
-          <div class="flex items-center gap-3 border-t border-line-soft py-2.5 text-[13px]">
-            <span class="tag shrink-0">{row.action}</span>
-            <span class="truncate text-ink">{row.label}</span>
-            <span class="ml-auto shrink-0 text-[11.5px] text-ink-3">{row.actor} · {fmtWhen(row.when)}</span>
-          </div>
-        {/each}
-      {/if}
-    </div>
-  {/if}
-</section>

hub/filelib-web/src/routes/database/dashboard/groups/+page.svelte

@@ -1,10 +0,0 @@
-<script lang="ts">
-  /** Group 管理 tab —— MemberGroup 嵌套树(ADR-0028)。
-   *  外框 padding/overflow 对齐旧 `#tab-groups`(padding:20px;overflow:hidden):
-   *  两栏各自内部滚动,外层不滚。 */
-  import GroupAdmin from "$lib/GroupAdmin.svelte";
-</script>
-
-<div class="min-h-0 flex-1 overflow-hidden p-5">
-  <GroupAdmin />
-</div>

hub/filelib-web/src/routes/database/dashboard/library/+page.svelte

@@ -1,8 +0,0 @@
-<script lang="ts">
-  /** 文件库 tab —— 与老师端 /app 同一个浏览器组件,区别只在侧栏身份区由外壳提供。 */
-  import LibraryView from "$lib/LibraryView.svelte";
-</script>
-
-<div class="flex min-h-0 flex-1 flex-col">
-  <LibraryView />
-</div>

hub/filelib-web/src/routes/database/dashboard/search/+page.svelte

@@ -1,4 +0,0 @@
-<section class="flex-1 overflow-y-auto p-7">
-  <h1 class="mb-1 text-lg font-semibold text-ink">查询</h1>
-  <p class="text-[12.5px] text-ink-3">查询功能建设中</p>
-</section>

hub/filelib-web/src/routes/database/dashboard/settings/+page.svelte

@@ -1,4 +0,0 @@
-<section class="flex-1 overflow-y-auto p-7">
-  <h1 class="mb-1 text-lg font-semibold text-ink">设置</h1>
-  <p class="text-[12.5px] text-ink-3">设置功能建设中</p>
-</section>

hub/filelib-web/src/routes/database/dashboard/users/+page.svelte

@@ -1,168 +0,0 @@
-<script lang="ts">
-  /**
-   * 用户管理(迁自后端 adminPanels.ts renderUsersPanel)。
-   *
-   * 用户 = silo org 的成员,走平台层 /api/org/:slug/members(见 src/admin/routes/membersRoutes.ts)。
-   * 与 Group 管理是两套体系:MemberGroup 是全局主体、不归属 org(ADR-0028),
-   * 这里管的是 org 成员与其角色。
-   */
-  import { onMount } from "svelte";
-  import { api } from "$lib/api.js";
-  import { loadConfig } from "$lib/config.js";
-  import { toastOk, toastErr } from "$lib/stores.js";
-  import type { OrgMember, OrgRole } from "$lib/types.js";
-
-  const ROLE_LABEL: Record<OrgRole, string> = {
-    OWNER: "所有者",
-    ADMIN: "管理员",
-    MEMBER: "普通老师",
-  };
-  const ROLES: readonly OrgRole[] = ["OWNER", "ADMIN", "MEMBER"];
-
-  let orgSlug = $state<string | null>(null);
-  let members = $state<OrgMember[] | null>(null);
-  let error = $state<string | null>(null);
-
-  let newOpenId = $state("");
-  let newName = $state("");
-  let newRole = $state<OrgRole>("MEMBER");
-  let adding = $state(false);
-
-  const base = $derived(orgSlug === null ? null : `/api/org/${encodeURIComponent(orgSlug)}`);
-
-  async function load(): Promise<void> {
-    if (base === null) return;
-    try {
-      const r = await api<{ members: OrgMember[] }>(`${base}/members`);
-      members = r.members;
-      error = null;
-    } catch (e) {
-      error = e instanceof Error ? e.message : String(e);
-    }
-  }
-
-  onMount(async () => {
-    try {
-      orgSlug = (await loadConfig()).orgSlug;
-      await load();
-    } catch (e) {
-      error = e instanceof Error ? e.message : String(e);
-    }
-  });
-
-  async function addMember(): Promise<void> {
-    const feishuOpenId = newOpenId.trim();
-    if (feishuOpenId === "") {
-      toastErr("请填写用户 openId");
-      return;
-    }
-    if (base === null) return;
-    adding = true;
-    try {
-      const displayName = newName.trim();
-      await api(`${base}/members`, {
-        method: "POST",
-        body: { feishuOpenId, role: newRole, ...(displayName !== "" ? { displayName } : {}) },
-      });
-      newOpenId = "";
-      newName = "";
-      toastOk("已添加");
-      await load();
-    } catch (e) {
-      toastErr(e instanceof Error ? e.message : String(e));
-    } finally {
-      adding = false;
-    }
-  }
-
-  async function setRole(userId: string, role: string): Promise<void> {
-    if (base === null) return;
-    try {
-      await api(`${base}/members/${encodeURIComponent(userId)}`, { method: "PATCH", body: { role } });
-      toastOk("角色已更新");
-      await load();
-    } catch (e) {
-      toastErr(e instanceof Error ? e.message : String(e));
-      await load();
-    }
-  }
-
-  async function revoke(userId: string, displayName: string): Promise<void> {
-    if (base === null) return;
-    if (!confirm(`移除成员「${displayName || userId}」?`)) return;
-    try {
-      await api(`${base}/members/${encodeURIComponent(userId)}/revoke`, { method: "POST" });
-      toastOk("已移除");
-      await load();
-    } catch (e) {
-      toastErr(e instanceof Error ? e.message : String(e));
-    }
-  }
-</script>
-
-<section class="flex-1 overflow-y-auto p-7">
-  <h1 class="mb-4 text-lg font-semibold text-ink">用户管理</h1>
-
-  <div class="max-w-[880px]">
-    <div class="panel mb-3.5">
-      <div class="section-title mb-2.5">添加成员</div>
-      <div class="flex flex-wrap items-center gap-2">
-        <input class="input min-w-0 flex-[2]" placeholder="用户 openId(飞书 ou_ 开头)" bind:value={newOpenId} />
-        <input class="input min-w-0 flex-1" placeholder="显示名(可选)" bind:value={newName} />
-        <select class="select !w-[130px]" bind:value={newRole}>
-          {#each ROLES as role (role)}
-            <option value={role}>{ROLE_LABEL[role]}</option>
-          {/each}
-        </select>
-        <button class="btn btn-primary disabled:opacity-50" onclick={addMember} disabled={adding}>
-          {adding ? "添加中…" : "添加"}
-        </button>
-      </div>
-    </div>
-
-    <div class="panel">
-      <div class="section-title mb-2.5">成员列表</div>
-
-      {#if error}
-        <div class="py-3 text-[12.5px] text-danger">{error}</div>
-      {:else if members === null}
-        <div class="quiet py-[18px] text-center">加载中…</div>
-      {:else if members.length === 0}
-        <div class="quiet py-[18px] text-center">暂无成员</div>
-      {:else}
-        <table class="list">
-          <thead>
-            <tr>
-              <th>成员</th>
-              <th>userId</th>
-              <th>角色</th>
-              <th></th>
-            </tr>
-          </thead>
-          <tbody>
-            {#each members as m (m.userId)}
-              <tr>
-                <td class="text-ink">{m.displayName || m.userId}</td>
-                <td class="file-meta">{m.userId}</td>
-                <td>
-                  <select
-                    class="select !w-[110px] !px-2 !py-[3px] !text-xs"
-                    value={m.role}
-                    onchange={(e) => setRole(m.userId, e.currentTarget.value)}
-                  >
-                    {#each ROLES as role (role)}
-                      <option value={role}>{ROLE_LABEL[role]}</option>
-                    {/each}
-                  </select>
-                </td>
-                <td class="text-right">
-                  <button class="link-danger" onclick={() => revoke(m.userId, m.displayName)}>移除</button>
-                </td>
-              </tr>
-            {/each}
-          </tbody>
-        </table>
-      {/if}
-    </div>
-  </div>
-</section>

hub/filelib-web/svelte.config.js

@@ -1,35 +0,0 @@
-import adapter from '@sveltejs/adapter-static';
-import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
-
-/**
- * 老师端 /app 与管理后台 /database/* 共用这一份 SPA 构建产物,由 hub 后端静态托管
- * (见 hub/src/database/static.ts)。服务端不渲染任何页面,只提供 /database/api/*。
- *
- * 两个关键配置:
- *
- * - `appDir: '_filelib'` —— 默认 `_app` 会与 admin-web 在同一个 Fastify 实例上注册的
- *   根 `/_app/*` 资源路由撞车(见 hub/src/admin/static.ts),Fastify 重复路由会直接
- *   在启动时抛错。改名后两套 SPA 的资源路径互不干扰。
- *
- * - `paths.relative: false` —— 同一份 index.html 会在不同深度的 URL 下被送出
- *   (`/app`、`/database/dashboard/users`),相对资源路径会解析错。必须用绝对路径。
- */
-const config = {
-	preprocess: vitePreprocess(),
-	kit: {
-		adapter: adapter({
-			pages: 'build',
-			assets: 'build',
-			fallback: 'index.html',
-			precompress: false,
-			strict: false,
-		}),
-		appDir: '_filelib',
-		paths: {
-			base: '',
-			relative: false,
-		},
-	},
-};
-
-export default config;

hub/filelib-web/tsconfig.json

@@ -1,17 +0,0 @@
-{
-  "extends": "./.svelte-kit/tsconfig.json",
-  "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"]
-  }
-}

hub/filelib-web/vite.config.ts

@@ -1,27 +0,0 @@
-import { sveltekit } from "@sveltejs/kit/vite";
-import tailwindcss from "@tailwindcss/vite";
-import { defineConfig } from "vite";
-
-// 老师端 /app + 管理后台 /database/* 的唯一前端工程;构建产物由 hub 后端静态托管。
-// 开发时 vite dev(:5173)把 API/认证/一键登录请求代理到后端(:8788);
-// 页面路由全部由 SvelteKit 客户端路由处理,后端不参与。
-const backend = "http://127.0.0.1:8788";
-
-export default defineConfig({
-  plugins: [tailwindcss(), sveltekit()],
-  server: {
-    port: 5173,
-    proxy: {
-      "/database/api": backend,
-      // 免鉴权 bootstrap(org slug + dev 开关);登录页和用户管理页都靠它。
-      "/database/config": backend,
-      "/auth": backend,
-      // 后端拥有的 DEV 一键登录端点(签 cookie 后 302);不代理会被 SPA 回退吃掉。
-      "/database/dev-login": backend,
-      "/app/dev-login": backend,
-      "/app/dev-login-teacher": backend,
-      // 平台层 org 成员 API(用户管理面板)。
-      "/api/org": backend,
-    },
-  },
-});

hub/package-lock.json

@@ -1,19 +1,18 @@
 {
   "name": "@paradigm/hub",
-  "version": "0.0.36",
+  "version": "0.0.42",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@paradigm/hub",
-      "version": "0.0.36",
+      "version": "0.0.42",
       "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",
@@ -248,22 +247,22 @@
       }
     },
     "node_modules/@anthropic-ai/claude-agent-sdk": {
-      "version": "0.3.202",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/-/claude-agent-sdk-0.3.202.tgz",
-      "integrity": "sha512-LnaLxDtsZP7J6g++xRSnnpTX7CHNe4v+cvBRIlD2ar+N+xi0aqY2YDaCsxPsl+haVUB9kqlUMd0zosmwsfTGjQ==",
+      "version": "0.3.217",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/-/claude-agent-sdk-0.3.217.tgz",
+      "integrity": "sha512-juszT3itL8R6OQ6nb/8IZE34UjKps8Jf7N8vjCXLx+vbJc+k3EojZOs93tJwT5iTRvfV1a0N53zJbKn/iJpKrQ==",
       "license": "SEE LICENSE IN README.md",
       "engines": {
         "node": ">=18.0.0"
       },
       "optionalDependencies": {
-        "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.3.202",
-        "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.3.202",
-        "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.3.202",
-        "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.3.202",
-        "@anthropic-ai/claude-agent-sdk-linux-x64": "0.3.202",
-        "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.3.202",
-        "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.3.202",
-        "@anthropic-ai/claude-agent-sdk-win32-x64": "0.3.202"
+        "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.3.217",
+        "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.3.217",
+        "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.3.217",
+        "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.3.217",
+        "@anthropic-ai/claude-agent-sdk-linux-x64": "0.3.217",
+        "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.3.217",
+        "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.3.217",
+        "@anthropic-ai/claude-agent-sdk-win32-x64": "0.3.217"
       },
       "peerDependencies": {
         "@anthropic-ai/sdk": ">=0.93.0",
@@ -272,9 +271,9 @@
       }
     },
     "node_modules/@anthropic-ai/claude-agent-sdk-darwin-arm64": {
-      "version": "0.3.202",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-darwin-arm64/-/claude-agent-sdk-darwin-arm64-0.3.202.tgz",
-      "integrity": "sha512-ujR3zDthDPkZs+AxW95iHpqLT5cuwGImsS3mVxLt1DlDij4qeTnihLX8+EpQTK+oNW9jjvFA86yKwa84fa1KYA==",
+      "version": "0.3.217",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-darwin-arm64/-/claude-agent-sdk-darwin-arm64-0.3.217.tgz",
+      "integrity": "sha512-dl119zmL1Ssyd8Fx0xfVMpss2scrGCZwf+rhZwl2lHa2dYuXVluLgqi4DUIWDj3rRYdrAvaMpjCAv6a5w07ddw==",
       "cpu": [
         "arm64"
       ],
@@ -285,9 +284,9 @@
       ]
     },
     "node_modules/@anthropic-ai/claude-agent-sdk-darwin-x64": {
-      "version": "0.3.202",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-darwin-x64/-/claude-agent-sdk-darwin-x64-0.3.202.tgz",
-      "integrity": "sha512-s/RVSGgkVmIMfyt1ndR8braLLu82bARoijmt1kk8d4IptUZ0Sc+zNUWKoFXwR9XqDBu6rBbBF9RIzD02raT57w==",
+      "version": "0.3.217",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-darwin-x64/-/claude-agent-sdk-darwin-x64-0.3.217.tgz",
+      "integrity": "sha512-IeKL1HN8fEcRQ4uw5d02by1ThpjhRtOgfHcCTBQ2KS4JfEIHvc1VGWt6Exb2a7VHhT8uRcfjPk9urbmYayZmaw==",
       "cpu": [
         "x64"
       ],
@@ -298,12 +297,15 @@
       ]
     },
     "node_modules/@anthropic-ai/claude-agent-sdk-linux-arm64": {
-      "version": "0.3.202",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-arm64/-/claude-agent-sdk-linux-arm64-0.3.202.tgz",
-      "integrity": "sha512-a4YtRkgGYt3ogePJDW8Ts6bNW690jb9LHyZaiWXsi+zT53xCNqJB2zKPyRc7hXWOqzIk4nCfwJpjmhLzMu3WIg==",
+      "version": "0.3.217",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-arm64/-/claude-agent-sdk-linux-arm64-0.3.217.tgz",
+      "integrity": "sha512-KtrnfEwUSCdq2cc4Pgysl+U66vqw3h7u04N5/OLHmYZ4AZYy8JcqdOaSJZ27iL2bgbAxyKwu5/9YmEk9A4IswA==",
       "cpu": [
         "arm64"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [
@@ -311,12 +313,15 @@
       ]
     },
     "node_modules/@anthropic-ai/claude-agent-sdk-linux-arm64-musl": {
-      "version": "0.3.202",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-arm64-musl/-/claude-agent-sdk-linux-arm64-musl-0.3.202.tgz",
-      "integrity": "sha512-abSb3Gah45kUNyOeKjmQ/dd1KZ4CaQz5JAr9YQxRDXoOwx8wJVx6huBIpDxjms9wyS9X5Rqxn0Lx7zFP+wV2zQ==",
+      "version": "0.3.217",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-arm64-musl/-/claude-agent-sdk-linux-arm64-musl-0.3.217.tgz",
+      "integrity": "sha512-Bb4AJxqrVPouM4sYIdvX3/AO5womhe70u3Euv+6B5J2OoqcRaWarVvYevX3KRruC5TvlV2Josw14dsL5qVNL+A==",
       "cpu": [
         "arm64"
       ],
+      "libc": [
+        "musl"
+      ],
       "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [
@@ -324,12 +329,15 @@
       ]
     },
     "node_modules/@anthropic-ai/claude-agent-sdk-linux-x64": {
-      "version": "0.3.202",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-x64/-/claude-agent-sdk-linux-x64-0.3.202.tgz",
-      "integrity": "sha512-XIvhdCWAAT4OdOA82fOJII+WH0Tf8pFckckEbJMMmOgQBKOnHT+609Pd3Ehw6zGcA9iFrhG5mY8Ncuckeo1aMw==",
+      "version": "0.3.217",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-x64/-/claude-agent-sdk-linux-x64-0.3.217.tgz",
+      "integrity": "sha512-JsAQyfl4n0PR4LX0h1SxMo0raERGb8B8dvbaoNQRRSpb9A2vvcwPEjyKu0eRKHRhTvspvuD6TfNxzxrmnouX9A==",
       "cpu": [
         "x64"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [
@@ -337,12 +345,15 @@
       ]
     },
     "node_modules/@anthropic-ai/claude-agent-sdk-linux-x64-musl": {
-      "version": "0.3.202",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-x64-musl/-/claude-agent-sdk-linux-x64-musl-0.3.202.tgz",
-      "integrity": "sha512-fze5nAQL1ErcMCQNB10ILaWdM0QbJSaTQzBz8NVAy0FGW8ZL0t4Wf/VgFkfzXbfkaxmPuM1C27Dn5HiU7UDEHQ==",
+      "version": "0.3.217",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-x64-musl/-/claude-agent-sdk-linux-x64-musl-0.3.217.tgz",
+      "integrity": "sha512-qhugNZd77vAoPMIGM8vFHlbwTltFyI1POmfyl0ZJSpc6v7RE9+5+nqL2aGbGSDsDQkEHrJasXURxIeTMn9ut2w==",
       "cpu": [
         "x64"
       ],
+      "libc": [
+        "musl"
+      ],
       "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [
@@ -350,9 +361,9 @@
       ]
     },
     "node_modules/@anthropic-ai/claude-agent-sdk-win32-arm64": {
-      "version": "0.3.202",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-win32-arm64/-/claude-agent-sdk-win32-arm64-0.3.202.tgz",
-      "integrity": "sha512-N1J0HRvC+8a69bqNY7+ENIYQzR0i7s+rOIGH5XtuLxvLqOnZO8LHxWEZOe8ezabGq5eZqphSCgL6vQnQQpNh+A==",
+      "version": "0.3.217",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-win32-arm64/-/claude-agent-sdk-win32-arm64-0.3.217.tgz",
+      "integrity": "sha512-LuaQ+PXZvIToAR81JoiGa6Me9HDma2WH2oiYlAWh43IWaXHyOqgaI1aqSM0BjDhy2UiYWTvGzAopnqPnk+jSBw==",
       "cpu": [
         "arm64"
       ],
@@ -363,9 +374,9 @@
       ]
     },
     "node_modules/@anthropic-ai/claude-agent-sdk-win32-x64": {
-      "version": "0.3.202",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-win32-x64/-/claude-agent-sdk-win32-x64-0.3.202.tgz",
-      "integrity": "sha512-ytLGEC1fjTSiVSoXukS+j9G+06Mi20NSzxxzlG6uE75SEB0+17tHdWUaHqd8PhH/6GPzcYx81czxWQl1MVbq4Q==",
+      "version": "0.3.217",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-win32-x64/-/claude-agent-sdk-win32-x64-0.3.217.tgz",
+      "integrity": "sha512-4r/T+ze/S/CLZ58tP4Mw52XPmsc/LOrCOd8jZOqM13FCPWdCMU2osWmszEIKGVMRG2cGsaLVDYcks5cWFqjCjw==",
       "cpu": [
         "x64"
       ],
@@ -426,22 +437,34 @@
       }
     },
     "node_modules/@emnapi/core": {
-      "version": "1.11.2",
-      "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.11.2.tgz",
-      "integrity": "sha512-TC8MkTuZUtcTSiFeuC0ksCh9QIJ5+F21MvZ4Wn4ORfYaFJ/0dsiudv5tVkejgwZlwQ39jL9WWDe2lz8x0WglOA==",
+      "version": "1.11.3",
+      "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.11.3.tgz",
+      "integrity": "sha512-zLpS5asjEb7lq8jYLq37N6XKaE41DIexlY1rF/z4/tIl3wo13Sqm28fRyfIsKZD+NZ8mM5RoKkpW/rBcuoSZSg==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "peer": true,
+      "dependencies": {
+        "@emnapi/wasi-threads": "1.2.3",
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@emnapi/core/node_modules/@emnapi/wasi-threads": {
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.3.tgz",
+      "integrity": "sha512-ELEBe8PsLvvJ6QMr0zLt8ffvOHW/dc1m3CEzNMg7aJUv3bMaoDtw2TXyDAwkYBuroxxuHEwhRTLJSe5sya547g==",
       "dev": true,
       "license": "MIT",
       "optional": true,
       "peer": true,
       "dependencies": {
-        "@emnapi/wasi-threads": "1.2.2",
         "tslib": "^2.4.0"
       }
     },
     "node_modules/@emnapi/runtime": {
-      "version": "1.11.2",
-      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.2.tgz",
-      "integrity": "sha512-kyOl3X0DuTiT1h2ft8r2fYO8JYtU9a9Xis/zBSiGArNaagCOWx90N1k2wxp18czFDH+OgcWGb5ZP/XMt3dcyPA==",
+      "version": "1.11.3",
+      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.3.tgz",
+      "integrity": "sha512-Xz4Tpyki7XyrpbUK1jR1AhdAdaXyhhY4lZ3neLodmhpuWfy2PAQN5B46sAiU4liOXGLkHypn/qU+jvfWSCYYLA==",
       "dev": true,
       "license": "MIT",
       "optional": true,
@@ -903,22 +926,6 @@
         "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",
@@ -1050,91 +1057,14 @@
         "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",
-      "integrity": "sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw==",
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-2.1.0.tgz",
+      "integrity": "sha512-XovyyCCnBzW+zKu+z/zq8hwNs4KOR5rEMAOxo2f40Q5xoOI37IMm6MIg2COOUtUApo0i6850MTBKH2u4QLGIqg==",
       "license": "MIT",
       "peer": true,
       "engines": {
-        "node": ">=18.14.1"
+        "node": ">=20"
       },
       "peerDependencies": {
         "hono": "^4"
@@ -1162,23 +1092,14 @@
         "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",
-      "integrity": "sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==",
+      "version": "1.30.0",
+      "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.30.0.tgz",
+      "integrity": "sha512-xKd8OIzlqNzcqcNumGAa6g+PW2kjD5vrpcKOnfldAUPP3j7lnqMPwlTXQm8gF+UwH72z0lqaRbjr9hqGz0eITA==",
       "license": "MIT",
       "peer": true,
       "dependencies": {
-        "@hono/node-server": "^1.19.9",
+        "@hono/node-server": "^1.19.9 || ^2.0.5",
         "ajv": "^8.17.1",
         "ajv-formats": "^3.0.1",
         "content-type": "^1.0.5",
@@ -2037,15 +1958,6 @@
         "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",
@@ -2085,18 +1997,6 @@
         "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",
@@ -2378,6 +2278,7 @@
       "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"
       }
@@ -2570,7 +2471,8 @@
       "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"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/estree-walker": {
       "version": "3.0.3",
@@ -2807,9 +2709,9 @@
       "peer": true
     },
     "node_modules/fast-uri": {
-      "version": "3.1.3",
-      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.3.tgz",
-      "integrity": "sha512-i70LwGWUduXqzicKXWshooq+sWL1K3WUU5rKZNG/0i3a1OSoX3HqhH5WbWwTmqWfor4urUakGPiRQcleRZTwOg==",
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.5.tgz",
+      "integrity": "sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw==",
       "funding": [
         {
           "type": "github",
@@ -2921,9 +2823,9 @@
       }
     },
     "node_modules/find-my-way": {
-      "version": "9.6.0",
-      "resolved": "https://registry.npmjs.org/find-my-way/-/find-my-way-9.6.0.tgz",
-      "integrity": "sha512-Zf4Xve4RymLl7NgaavNebZ01joJ8MfVerOG43wy7SHLO+r+K0C6d/SE0BiR7AV5V1VOCFlOP7ecdo+I4qmiHrQ==",
+      "version": "9.7.0",
+      "resolved": "https://registry.npmjs.org/find-my-way/-/find-my-way-9.7.0.tgz",
+      "integrity": "sha512-f2JHn75x2JlwUwLenZypgczR7YWMb/uO9BvUXtus+JMgkbIkLADd38cI4EiV+OQqrGo1Zlq6V8wnqMJ8e62wUQ==",
       "license": "MIT",
       "dependencies": {
         "fast-deep-equal": "^3.1.3",
@@ -3069,23 +2971,6 @@
         "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",
@@ -3138,9 +3023,9 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.12.28",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.28.tgz",
-      "integrity": "sha512-YwUvVpSF7m1yOblFPrU3Hbo8XhPheBoiyfGuII6z19LnOr6JpDnyyp7LFNrfV56wS8tpvtBFGRISHN02pDdLOA==",
+      "version": "4.13.0",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.13.0.tgz",
+      "integrity": "sha512-jhunvfHWxd7J5EFfSgH4xsYJzSe/lfqbUCxiyyeaQasUsXeEHXtzVid+7EOGByc5JnFa23SSFL3Y2RV/z1T+eQ==",
       "license": "MIT",
       "peer": true,
       "engines": {
@@ -3152,6 +3037,7 @@
       "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",
@@ -3234,7 +3120,8 @@
       "version": "2.0.4",
       "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
       "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
-      "license": "ISC"
+      "license": "ISC",
+      "peer": true
     },
     "node_modules/ini": {
       "version": "1.3.8",
@@ -3243,9 +3130,9 @@
       "license": "ISC"
     },
     "node_modules/ip-address": {
-      "version": "10.2.0",
-      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.2.0.tgz",
-      "integrity": "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==",
+      "version": "10.4.0",
+      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.4.0.tgz",
+      "integrity": "sha512-oSK96Grm3aP6OrS263xVxbNDGVL7rzBtYdpGqlDG8iQdoenDoTs/nkki+DflYbAEE8Xl6o5YxhxlrKvI3nqKXQ==",
       "license": "MIT",
       "engines": {
         "node": ">= 12"
@@ -3683,15 +3570,6 @@
       "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",
@@ -3734,18 +3612,6 @@
         "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",
@@ -3767,30 +3633,6 @@
         "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",
@@ -3819,9 +3661,9 @@
       "license": "MIT"
     },
     "node_modules/nanoid": {
-      "version": "3.3.15",
-      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.15.tgz",
-      "integrity": "sha512-y7Wygv/7mEOvxTuEQDB8StXdMRBWf1kR/tlhAzBRUFkB2jfcLOAxO/SHmOO2zgz1pVgK29/kyupn059/bCHdjA==",
+      "version": "3.3.17",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.17.tgz",
+      "integrity": "sha512-xQLf0A3HOMlgHq0n247/LRuAOYmB7dXJ/DvAxGvsSBij45XtBSmQycu+F8ODbHwns/XyFZagyL1+J0Offw1E0g==",
       "dev": true,
       "funding": [
         {
@@ -3974,22 +3816,6 @@
         "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",
@@ -4095,9 +3921,9 @@
       }
     },
     "node_modules/postcss": {
-      "version": "8.5.16",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.16.tgz",
-      "integrity": "sha512-vuwillviilfKZsg0VGj5R/YwwcHx4SLsIOI/7K6mQkWx+l5cUHTjj5g0AasTBcyXsbfTgrwsUNmVUb5xVwyPwg==",
+      "version": "8.5.25",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.25.tgz",
+      "integrity": "sha512-DTPx3RWSSnWyzLxQnlH0rJP+EW5ekl16ZU4/psbIhA0e53kJfdgaN5vKM+xP7yJtXVu+nfdVFmlgFDEKAe4Pyw==",
       "dev": true,
       "funding": [
         {
@@ -4115,7 +3941,7 @@
       ],
       "license": "MIT",
       "dependencies": {
-        "nanoid": "^3.3.12",
+        "nanoid": "^3.3.16",
         "picocolors": "^1.1.1",
         "source-map-js": "^1.2.1"
       },
@@ -4568,7 +4394,8 @@
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz",
       "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==",
-      "license": "ISC"
+      "license": "ISC",
+      "peer": true
     },
     "node_modules/shebang-command": {
       "version": "2.0.0",
@@ -4767,6 +4594,7 @@
       "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz",
       "integrity": "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==",
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">= 0.8"
       }
@@ -4854,6 +4682,7 @@
       "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.36",
+  "version": "0.0.42",
   "private": true,
   "type": "module",
   "engines": {
@@ -12,7 +12,6 @@
     "@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",
@@ -34,7 +33,7 @@
   "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 && npm run filelib:build",
+    "build": "tsc -p tsconfig.json && npm run admin: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",
@@ -49,8 +48,6 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "admin:dev": "npm run dev --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"
+    "admin:build": "npm run build --prefix admin-web"
   }
 }

hub/prisma/migrations/20260719140000_agent_config_folder_tree/migration.sql

@@ -0,0 +1,33 @@
+-- ADR-0028 agent configuration folder tree. One org-scoped transparent folder
+-- tree shared by Agent roles and skills (management-surface grouping only);
+-- skill name / roleId uniqueness, role→skill bindings, run-time skill loading
+-- and Feishu slash commands never reference folders. A folder deletes only
+-- when empty (service-enforced); item `folderId` references are SetNull as
+-- backstop.
+
+-- CreateTable
+CREATE TABLE "OrganizationAgentConfigFolder" (
+    "id" TEXT NOT NULL,
+    "organizationId" TEXT NOT NULL,
+    "parentId" TEXT,
+    "name" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "OrganizationAgentConfigFolder_pkey" PRIMARY KEY ("id")
+);
+
+-- AlterTable
+ALTER TABLE "OrganizationAgentSkill" ADD COLUMN "folderId" TEXT;
+ALTER TABLE "OrganizationAgentRole" ADD COLUMN "folderId" TEXT;
+
+-- CreateIndex
+CREATE INDEX "OrganizationAgentConfigFolder_organizationId_parentId_idx" ON "OrganizationAgentConfigFolder"("organizationId", "parentId");
+CREATE INDEX "OrganizationAgentSkill_organizationId_folderId_idx" ON "OrganizationAgentSkill"("organizationId", "folderId");
+CREATE INDEX "OrganizationAgentRole_organizationId_folderId_idx" ON "OrganizationAgentRole"("organizationId", "folderId");
+
+-- AddForeignKey
+ALTER TABLE "OrganizationAgentConfigFolder" ADD CONSTRAINT "OrganizationAgentConfigFolder_organizationId_fkey" FOREIGN KEY ("organizationId") REFERENCES "Organization"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "OrganizationAgentConfigFolder" ADD CONSTRAINT "OrganizationAgentConfigFolder_parentId_fkey" FOREIGN KEY ("parentId") REFERENCES "OrganizationAgentConfigFolder"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "OrganizationAgentSkill" ADD CONSTRAINT "OrganizationAgentSkill_folderId_fkey" FOREIGN KEY ("folderId") REFERENCES "OrganizationAgentConfigFolder"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+ALTER TABLE "OrganizationAgentRole" ADD CONSTRAINT "OrganizationAgentRole_folderId_fkey" FOREIGN KEY ("folderId") REFERENCES "OrganizationAgentConfigFolder"("id") ON DELETE SET NULL ON UPDATE CASCADE;

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

@@ -1,92 +0,0 @@
--- 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/20260723120000_member_group_hierarchy/migration.sql

@@ -1,70 +0,0 @@
--- Global, unlimited-depth member group hierarchy (requirement 3.1-3.3).
--- Managed only by the platform super administrator; deliberately NOT
--- org-scoped. Stores membership + nesting only, never permission data.
--- Deletion is soft (archivedAt / revokedAt markers); a group delete
--- cascade-soft-deletes its whole subtree as an application operation.
--- The permission side (GROUP principal, FOLDER resource, grant inheritance)
--- is intentionally deferred to a later migration.
-
--- CreateTable
-CREATE TABLE "MemberGroup" (
-    "id" TEXT NOT NULL,
-    "parentId" TEXT,
-    "name" TEXT NOT NULL,
-    "description" TEXT,
-    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    "updatedAt" TIMESTAMP(3) NOT NULL,
-    "archivedAt" TIMESTAMP(3),
-
-    CONSTRAINT "MemberGroup_pkey" PRIMARY KEY ("id")
-);
-
--- CreateTable
-CREATE TABLE "MemberGroupMembership" (
-    "id" TEXT NOT NULL,
-    "groupId" TEXT NOT NULL,
-    "userId" TEXT NOT NULL,
-    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    "revokedAt" TIMESTAMP(3),
-
-    CONSTRAINT "MemberGroupMembership_pkey" PRIMARY KEY ("id")
-);
-
--- CreateTable
-CREATE TABLE "MemberGroupClosure" (
-    "ancestorId" TEXT NOT NULL,
-    "descendantId" TEXT NOT NULL,
-    "depth" INTEGER NOT NULL,
-
-    CONSTRAINT "MemberGroupClosure_pkey" PRIMARY KEY ("ancestorId", "descendantId")
-);
-
--- CreateIndex
-CREATE INDEX "MemberGroup_parentId_archivedAt_idx" ON "MemberGroup"("parentId", "archivedAt");
-
--- CreateIndex
-CREATE INDEX "MemberGroupMembership_userId_revokedAt_idx" ON "MemberGroupMembership"("userId", "revokedAt");
-
--- CreateIndex
-CREATE INDEX "MemberGroupMembership_groupId_revokedAt_idx" ON "MemberGroupMembership"("groupId", "revokedAt");
-
--- CreateIndex
-CREATE UNIQUE INDEX "MemberGroupMembership_groupId_userId_revokedAt_key" ON "MemberGroupMembership"("groupId", "userId", "revokedAt");
-
--- CreateIndex
-CREATE INDEX "MemberGroupClosure_descendantId_idx" ON "MemberGroupClosure"("descendantId");
-
--- AddForeignKey
-ALTER TABLE "MemberGroup" ADD CONSTRAINT "MemberGroup_parentId_fkey" FOREIGN KEY ("parentId") REFERENCES "MemberGroup"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
-
--- AddForeignKey
-ALTER TABLE "MemberGroupMembership" ADD CONSTRAINT "MemberGroupMembership_groupId_fkey" FOREIGN KEY ("groupId") REFERENCES "MemberGroup"("id") ON DELETE CASCADE ON UPDATE CASCADE;
-
--- AddForeignKey
-ALTER TABLE "MemberGroupMembership" ADD CONSTRAINT "MemberGroupMembership_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;
-
--- AddForeignKey
-ALTER TABLE "MemberGroupClosure" ADD CONSTRAINT "MemberGroupClosure_ancestorId_fkey" FOREIGN KEY ("ancestorId") REFERENCES "MemberGroup"("id") ON DELETE CASCADE ON UPDATE CASCADE;
-
--- AddForeignKey
-ALTER TABLE "MemberGroupClosure" ADD CONSTRAINT "MemberGroupClosure_descendantId_fkey" FOREIGN KEY ("descendantId") REFERENCES "MemberGroup"("id") ON DELETE CASCADE ON UPDATE CASCADE;

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

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

hub/prisma/migrations/20260730120000_agent_config_folder_parent_cascade/migration.sql

@@ -0,0 +1,5 @@
+-- Allow Organization wipe/cascade to clear nested agent-config folders.
+-- Service layer still refuses non-empty folder deletes (ADR-0028); this only
+-- unblocks parent-row removal during org teardown and test resetDb.
+ALTER TABLE "OrganizationAgentConfigFolder" DROP CONSTRAINT "OrganizationAgentConfigFolder_parentId_fkey";
+ALTER TABLE "OrganizationAgentConfigFolder" ADD CONSTRAINT "OrganizationAgentConfigFolder_parentId_fkey" FOREIGN KEY ("parentId") REFERENCES "OrganizationAgentConfigFolder"("id") ON DELETE CASCADE ON UPDATE CASCADE;

hub/prisma/schema.prisma

@@ -47,10 +47,10 @@ model Organization {
   capabilityConnections        OrganizationCapabilityConnection[]
   agentSkills                  OrganizationAgentSkill[]
   agentRoles                   OrganizationAgentRole[]
+  agentConfigFolders           OrganizationAgentConfigFolder[]
   projectGroupBindings         ProjectGroupBinding[]
   auditEntries                 AuditEntry[]                             @relation("organizationAudit")
   projectSearchDocuments       ProjectSearchDocument[]
-  fileLibNodes                 FileLibNode[]
 
   @@index([status])
 }
@@ -96,16 +96,19 @@ model OrganizationAgentSkill {
   version        String
   description    String?
   contentDigest  String
+  folderId       String?
   createdAt      DateTime  @default(now())
   updatedAt      DateTime  @updatedAt
   disabledAt     DateTime?
 
-  organization Organization                 @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  organization Organization                    @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  folder       OrganizationAgentConfigFolder?  @relation(fields: [folderId], references: [id], onDelete: SetNull)
   roleBindings OrganizationAgentRoleSkill[]
 
   @@unique([organizationId, name])
   @@unique([organizationId, id])
   @@index([organizationId, disabledAt])
+  @@index([organizationId, folderId])
   @@index([contentDigest])
 }
 
@@ -122,17 +125,20 @@ model OrganizationAgentRole {
   tools          Json?
   sortOrder      Int       @default(0)
   isDefault      Boolean   @default(false)
+  folderId       String?
   createdAt      DateTime  @default(now())
   updatedAt      DateTime  @updatedAt
   disabledAt     DateTime?
 
-  organization       Organization                 @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  organization       Organization                    @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  folder             OrganizationAgentConfigFolder?  @relation(fields: [folderId], references: [id], onDelete: SetNull)
   skillBindings      OrganizationAgentRoleSkill[]
   selectedByBindings ProjectGroupBinding[]        @relation("selectedAgentRole")
 
   @@unique([organizationId, roleId])
   @@unique([organizationId, id])
   @@index([organizationId, disabledAt, sortOrder])
+  @@index([organizationId, folderId])
 }
 
 /// Same-Organization join enforced by both composite foreign keys. `sortOrder`
@@ -152,6 +158,29 @@ model OrganizationAgentRoleSkill {
   @@index([organizationId, agentSkillId])
 }
 
+/// ADR-0028: org-scoped transparent folder tree shared by agent roles and
+/// skills. Management-surface navigation/grouping only — not a permission
+/// resource, and never referenced by role→skill bindings, run-time skill
+/// loading, or Feishu slash commands. Skill name and roleId stay unique per
+/// organization regardless of folder membership. A folder is deleted only
+/// when empty (service-enforced); item references are SetNull as backstop.
+model OrganizationAgentConfigFolder {
+  id             String    @id @default(cuid())
+  organizationId String
+  parentId       String?
+  name           String
+  createdAt      DateTime  @default(now())
+  updatedAt      DateTime  @updatedAt
+
+  organization Organization                    @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  parent       OrganizationAgentConfigFolder?  @relation("agentConfigFolderTree", fields: [parentId], references: [id], onDelete: Cascade)
+  children     OrganizationAgentConfigFolder[] @relation("agentConfigFolderTree")
+  skills       OrganizationAgentSkill[]
+  roles        OrganizationAgentRole[]
+
+  @@index([organizationId, parentId])
+}
+
 /// ADR-0021: org-level project onboarding policy. Ordinary Feishu users can
 /// create projects from unbound chats only when membersCanCreateProjects=true.
 model OrganizationProjectSettings {
@@ -194,7 +223,6 @@ model User {
   heldLocks                    ProjectAgentLock[]                   @relation("lockHolder")
   feishuBindings               ProjectGroupBinding[]                @relation("bindingCreator")
   teamMemberships              TeamMembership[]
-  memberGroupMemberships       MemberGroupMembership[]
   externalPrincipalMemberships ExternalPrincipalMembership[]
   permissionGrants             PermissionGrant[]                    @relation("grantCreator")
   roleTriggerGrants            RoleTriggerGrant[]                   @relation("roleGrantCreator")
@@ -395,67 +423,6 @@ model TeamExternalBinding {
   @@index([teamId, revokedAt])
 }
 
-// --- Member groups (global, nestable authorization principal) ------------
-
-/// Global, unlimited-depth member group. Managed only by the platform super administrator (ADR-0023);
-/// Deletion is soft: `archivedAt` is a marker.
-/// Deleting a group cascade-soft-deletes its whole subtree — an application
-/// operation (walk the subtree, stamp archivedAt), not a DB constraint.
-model MemberGroup {
-  id          String    @id @default(cuid())
-  parentId    String?
-  name        String
-  description String?
-  createdAt   DateTime  @default(now())
-  updatedAt   DateTime  @updatedAt
-  archivedAt  DateTime?
-
-  parent       MemberGroup?            @relation("groupTree", fields: [parentId], references: [id], onDelete: Restrict)
-  children     MemberGroup[]           @relation("groupTree")
-  memberships  MemberGroupMembership[]
-  asAncestor   MemberGroupClosure[]    @relation("ancestor")
-  asDescendant MemberGroupClosure[]    @relation("descendant")
-
-  @@index([parentId, archivedAt])
-}
-
-/// User↔group many-to-many; a user may belong to multiple groups. Soft delete
-/// via `revokedAt` (same pattern as TeamMembership) allows re-adding a removed
-/// member. `userId, revokedAt` index is the resolution hot path: fetch a user's direct groups.
-model MemberGroupMembership {
-  id        String    @id @default(cuid())
-  groupId   String
-  userId    String
-  createdAt DateTime  @default(now())
-  revokedAt DateTime?
-
-  group MemberGroup @relation(fields: [groupId], references: [id], onDelete: Cascade)
-  user  User        @relation(fields: [userId], references: [id], onDelete: Cascade)
-
-  @@unique([groupId, userId, revokedAt])
-  @@index([userId, revokedAt])
-  @@index([groupId, revokedAt])
-}
-
-/// Transitive closure of the MemberGroup tree. Every group has a depth=0
-/// self row. Turns ancestor/descendant resolution into one indexed join
-/// instead of a recursive CTE; maintained only on create / reparent (rare
-/// super-admin ops, so the write cost is amortized against hot reads). On soft
-/// delete the closure rows are retained; resolution filters by
-/// MemberGroup.archivedAt. Reparent must reject a new parent inside the moved
-/// subtree (cycle guard).
-model MemberGroupClosure {
-  ancestorId   String
-  descendantId String
-  depth        Int
-
-  ancestor   MemberGroup @relation("ancestor", fields: [ancestorId], references: [id], onDelete: Cascade)
-  descendant MemberGroup @relation("descendant", fields: [descendantId], references: [id], onDelete: Cascade)
-
-  @@id([ancestorId, descendantId])
-  @@index([descendantId])
-}
-
 /// Locally synchronized Feishu external principal membership.
 model ExternalDirectoryConnection {
   id               String    @id @default(cuid())
@@ -986,127 +953,3 @@ 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/scripts/smoke-docmind.ts

@@ -26,7 +26,11 @@ const client = new DocmindClient.default({
 } as never);
 
 const fileStream = createReadStream(pdfPath);
-const runtime = new RuntimeOptions({});
+const runtime = new RuntimeOptions({
+  connectTimeout: 15_000,
+  // httpx defaults to 3000ms; OSS upload of multi-MB PDFs needs far more.
+  readTimeout: 5 * 60_000,
+});
 
 console.log("Submitting job...");
 const submitResp = await client.submitDocParserJobAdvance(

hub/skills/pbank-problem-report/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: pbank-problem-report
+description: >
+  Use when a teacher wants Paradigm PBank (题库) problems as lesson examples,
+  asks to search PBank by outline, map candidates to outline parts, inspect
+  downloaded PBank source zips including images, or produce a Markdown
+  selection/adaptation report.
+---
+
+# PBank Problem Report
+
+Use the `cph_hub` MCP tools `pbank_search_problems`, `pbank_get_problem`, and
+`pbank_get_many_problems` to support problem selection from Paradigm PBank.
+The normal output is a Markdown report for the teacher to review before any
+lesson source is changed.
+
+## Workflow
+
+1. Understand the current lesson before searching.
+   - Read the lesson outline, plan, or main source files in the current workspace.
+   - Identify the teaching parts, target concepts, required difficulty, and what kind of examples are needed.
+
+2. Search PBank with narrow queries.
+   - Use `pbank_search_problems` with Chinese keywords from the outline.
+   - Prefer several focused searches over one broad search.
+   - Keep the initial result set small, then fetch only plausible candidates.
+
+3. Fetch source projects for candidates.
+   - Use `pbank_get_problem` or `pbank_get_many_problems`.
+   - Keep `includeProjects: true`, `materializeProjects: true`, and `includeAssetImages: true` unless the user explicitly asks otherwise.
+   - Read the returned `rights` object first. Treat it as the authoritative rights signal for all content returned by these tools.
+   - Read returned `files`, `assets`, `zipPath`, and `extractDir`. Images usually live under `fig/` in the extracted source tree.
+   - When image or PDF assets matter, cite their workspace-relative paths under `.pbank-sources/...`.
+
+4. Produce a Markdown report instead of editing the lesson by default.
+   - Save it in the current project workspace as `pbank-candidate-report.md` unless the user gives another path.
+   - Do not copy problems into the lesson, rewrite the lesson, or write back to PBank unless the user explicitly asks.
+
+5. When the teacher explicitly asks for adaptation, follow the rights signal.
+   - If `rights.derivativeUseAllowed` is `true`, you may quote, rewrite, adapt, and reorganize the returned PBank content into the current teaching-material project.
+   - Do not refuse on generic copyright grounds when the tools say derivative use is allowed.
+   - If `rights.derivativeUseAllowed` is `false`, stay read-only and ask the teacher/admin to confirm rights first.
+
+## Report Shape
+
+Use concise Chinese. Include:
+
+- Lesson outline parts and the example need for each part.
+- A candidate table with PBank title/id/link, matched outline part, fit score, directly usable material, required modifications, assets, and recommendation.
+- Per-problem notes explaining the mathematical/physical idea, why it matches, and what needs to be changed for this lesson.
+- A short final recommendation: which problems to use directly, which to adapt, and which to discard.
+
+## Rules
+
+- Do not invent problem statements, diagrams, or answers. Base every claim on PBank metadata or extracted source files.
+- Treat `.pbank-sources/` as a local read cache. It is safe to read from and reference in reports.
+- Keep PBank itself read-only. The teacher's workflow is selection and adaptation inside the current lesson project, not modifying the bank.
+- Treat rights metadata as authoritative. Do not override `rights.derivativeUseAllowed: true` with a generic copyright refusal.
+- If tools fail because no ACTIVE `pbank` capability connection exists, tell the user an org admin must configure 题库 credentials under 外部能力.
+- If no candidate fits, say that directly and record the searches tried.

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

@@ -2,62 +2,95 @@
 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.
+  Handles single or multiple PDFs (concurrent batch), Feishu attachments, and
+  local workspace files. 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.
+Use this skill when the user asks to convert a PDF (or several PDFs) to
+Markdown, extract text from a PDF, or turn PDF documents 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:
+The `convert_pdf_to_md` tool (provided by the in-process `cph_hub` MCP server)
+calls Alibaba Cloud Document Mind to parse each 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
+- Writes a single `document.md` file plus image files **per** `output_dir`
+
+There is **no** workspace `.mcp.json` source file. MCP tools are injected by
+Hub at run start. Do not look for MCP or skill source under workspace
+`.claude/` — those paths are sandbox stubs (often character devices) and are
+not readable constitution.
+
+## Where this skill text lives
+
+Prefer the Skill tool when the runtime offers it. If you need to re-read these
+instructions with Read:
+
+- Workspace copy (always under cwd): `.cph/runtime-skills/pdf-to-md/SKILL.md`
+- Absolute path env: `$CPH_RUNTIME_SKILLS_DIR/pdf-to-md/SKILL.md`
 
 ## Workflow
 
-### PDF from a Feishu message
+### One 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.
+3. Use `convert_pdf_to_md` with `input_path` + `output_dir`.
 
 ### PDF already in the workspace
 
-1. Use `convert_pdf_to_md` directly with the file path and an output directory.
+1. Use `convert_pdf_to_md` with `input_path` and `output_dir`.
+
+### Multiple PDFs (concurrent)
+
+1. Download or locate every PDF in the workspace first.
+2. Call **`convert_pdf_to_md` once** with:
+
+```json
+{
+  "items": [
+    { "input_path": "sources/a.pdf", "output_dir": "md/a" },
+    { "input_path": "sources/b.pdf", "output_dir": "md/b" }
+  ]
+}
+```
+
+3. Hub submits Docmind jobs with bounded concurrency (default 3, max 8;
+   optional `concurrency` argument). Prefer this over N sequential tool calls.
+4. **Each item must use a distinct `output_dir`** — the tool always writes
+   `document.md` inside that directory; shared dirs overwrite each other.
+5. Partial failure returns per-file OK/FAIL lines; re-run only failed items.
 
 ## 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.
+  PDFs yourself with Read, Bash, Python, or any other method.
 - 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.
+- After conversion, use `send_file` to send generated markdown (or a zip you
+  assemble) back to the user if they requested delivery.
 
 ## Output
 
-The tool returns a list of generated files:
+Per `output_dir`:
+
 - `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.
+Billed per page (0.04 CNY/page ≈ $0.0056/page for enhanced formula mode).
+Each successful file records its own usage fact on the run ledger.

hub/src/admin/routes/agentConfigRoutes.ts

@@ -15,6 +15,10 @@
  * `commitSkillContent`, so the web path and CLI path share one ingestion
  * pipeline and one set of safety checks (SKILL.md manifest required, 512-file
  * / 16-byte limits, symlink rejection).
+ *
+ * Folder tree (ADR-0028): one org-scoped transparent folder tree shared by
+ * roles and skills for management-surface grouping. Folder endpoints never
+ * touch session state — assignment is a label-class change (ADR-0017).
  */
 import type { PrismaClient } from "@prisma/client";
 import type { FastifyInstance } from "fastify";
@@ -243,4 +247,121 @@ export async function registerAgentConfigRoutes(
       return handleRouteError(reply, err);
     }
   });
+
+  // --- ADR-0028 shared agent-config folder tree (transparent grouping) ---
+
+  app.get("/api/org/:orgSlug/agent-config-folders", async (request, reply) => {
+    try {
+      const { orgSlug } = request.params as { orgSlug: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      const folders = await agentConfig.listFolders({ organizationId: auth.organization.id });
+      return { folders };
+    } catch (err) {
+      return handleRouteError(reply, err);
+    }
+  });
+
+  app.post("/api/org/:orgSlug/agent-config-folders", async (request, reply) => {
+    try {
+      const { orgSlug } = request.params as { orgSlug: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      const body = request.body as { name?: unknown; parentId?: unknown };
+      if (typeof body.name !== "string") {
+        return reply.status(400).send({
+          error: { code: "bad_request", message: "name is required" },
+        });
+      }
+      const folder = await agentConfig.createFolder({
+        organizationId: auth.organization.id,
+        name: body.name,
+        ...(typeof body.parentId === "string" ? { parentId: body.parentId } : {}),
+      });
+      return reply.status(201).send(folder);
+    } catch (err) {
+      return handleRouteError(reply, err);
+    }
+  });
+
+  app.patch("/api/org/:orgSlug/agent-config-folders/:folderId", async (request, reply) => {
+    try {
+      const { orgSlug, folderId } = request.params as { orgSlug: string; folderId: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      const body = request.body as { name?: unknown; parentId?: unknown };
+      const folder = await agentConfig.updateFolder({
+        organizationId: auth.organization.id,
+        folderId,
+        ...(typeof body.name === "string" ? { name: body.name } : {}),
+        ...(body.parentId === null || typeof body.parentId === "string"
+          ? { parentId: body.parentId as string | null }
+          : {}),
+      });
+      return folder;
+    } catch (err) {
+      return handleRouteError(reply, err);
+    }
+  });
+
+  app.delete("/api/org/:orgSlug/agent-config-folders/:folderId", async (request, reply) => {
+    try {
+      const { orgSlug, folderId } = request.params as { orgSlug: string; folderId: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      await agentConfig.deleteFolder({
+        organizationId: auth.organization.id,
+        folderId,
+      });
+      return { deleted: true };
+    } catch (err) {
+      return handleRouteError(reply, err);
+    }
+  });
+
+  // Folder assignment is a label-class change (ADR-0017): these endpoints
+  // never archive Agent sessions (ADR-0028).
+  app.patch("/api/org/:orgSlug/agent-roles/:roleId/folder", async (request, reply) => {
+    try {
+      const { orgSlug, roleId } = request.params as { orgSlug: string; roleId: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      const body = request.body as { folderId?: unknown };
+      if (body.folderId !== null && typeof body.folderId !== "string") {
+        return reply.status(400).send({
+          error: { code: "bad_request", message: "folderId must be a string or null" },
+        });
+      }
+      await agentConfig.setRoleFolder({
+        organizationId: auth.organization.id,
+        roleId,
+        folderId: body.folderId as string | null,
+      });
+      return { folderId: body.folderId as string | null };
+    } catch (err) {
+      return handleRouteError(reply, err);
+    }
+  });
+
+  app.patch("/api/org/:orgSlug/agent-skills/:name/folder", async (request, reply) => {
+    try {
+      const { orgSlug, name } = request.params as { orgSlug: string; name: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      const body = request.body as { folderId?: unknown };
+      if (body.folderId !== null && typeof body.folderId !== "string") {
+        return reply.status(400).send({
+          error: { code: "bad_request", message: "folderId must be a string or null" },
+        });
+      }
+      await agentConfig.setSkillFolder({
+        organizationId: auth.organization.id,
+        name,
+        folderId: body.folderId as string | null,
+      });
+      return { folderId: body.folderId as string | null };
+    } catch (err) {
+      return handleRouteError(reply, err);
+    }
+  });
 }

hub/src/admin/routes/capabilityConnectionRoutes.ts

@@ -7,8 +7,12 @@
  */
 import type { PrismaClient } from "@prisma/client";
 import type { FastifyInstance } from "fastify";
-import { CapabilityConnectionService } from "../../capability/capabilityConnectionService.js";
+import {
+  CapabilityConnectionService,
+  type CapabilityCredentialInput,
+} from "../../capability/capabilityConnectionService.js";
 import { CapabilityReadinessError, type CapabilityReadinessProbe } from "../../capability/capabilityReadiness.js";
+import { secretKindForCapability } from "../../capability/types.js";
 import type { LocalSecretEnvelope } from "../../security/secretEnvelope.js";
 import { requireOrgRole, type GuardDeps } from "../auth/guards.js";
 import { handleRouteError } from "../errors.js";
@@ -25,11 +29,10 @@ export async function registerCapabilityConnectionRoutes(
   config: CapabilityConnectionRouteConfig,
 ): Promise<void> {
   const guardDeps: GuardDeps = { prisma: config.prisma, sessionSecret: config.sessionSecret };
-  const connections = new CapabilityConnectionService(
-    config.prisma,
-    config.secretEnvelope,
-    config.readinessProbe,
-  );
+  const connections =
+    config.readinessProbe === undefined
+      ? new CapabilityConnectionService(config.prisma, config.secretEnvelope)
+      : new CapabilityConnectionService(config.prisma, config.secretEnvelope, config.readinessProbe);
 
   app.get("/api/org/:orgSlug/capability-connections", async (request, reply) => {
     try {
@@ -60,12 +63,12 @@ export async function registerCapabilityConnectionRoutes(
       const { orgSlug, capabilityId } = request.params as { orgSlug: string; capabilityId: string };
       const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
       if (auth === null) return;
-      const body = parseBody(request.body);
+      const credential = parseCredentialBody(capabilityId, request.body);
       const result = await connections.rotate({
         organizationId: auth.organization.id,
         capabilityId,
         actorUserId: auth.user.id,
-        ...body,
+        credential,
       });
       request.log.info({
         organizationId: auth.organization.id,
@@ -113,19 +116,57 @@ export async function registerCapabilityConnectionRoutes(
   });
 }
 
-function parseBody(value: unknown): { readonly accessKeyId: string; readonly accessKeySecret: string; readonly endpoint: string } {
+function parseCredentialBody(capabilityId: string, value: unknown): CapabilityCredentialInput {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     throw new Error("invalid capability credential body");
   }
   const body = value as Record<string, unknown>;
-  for (const name of ["accessKeyId", "accessKeySecret", "endpoint"] as const) {
-    if (typeof body[name] !== "string" || (body[name] as string).trim() === "") {
-      throw new Error(`${name} is required`);
-    }
+  const expectedKind = secretKindForCapability(capabilityId);
+  const kind =
+    body.kind === "docmind" || body.kind === "pbank"
+      ? body.kind
+      : expectedKind;
+
+  if (kind !== expectedKind) {
+    throw new Error(`capability ${capabilityId} requires kind=${expectedKind}`);
   }
+
+  if (kind === "docmind") {
+    return {
+      kind: "docmind",
+      accessKeyId: requireStringField(body, "accessKeyId"),
+      accessKeySecret: requireStringField(body, "accessKeySecret"),
+      endpoint: requireStringField(body, "endpoint"),
+    };
+  }
+
+  const rightsStatus = optionalStringField(body, "rightsStatus");
+  const rightsHolder = optionalStringField(body, "rightsHolder");
+  const rightsScope = optionalStringField(body, "rightsScope");
+  const rightsNote = optionalStringField(body, "rightsNote");
   return {
-    accessKeyId: body["accessKeyId"] as string,
-    accessKeySecret: body["accessKeySecret"] as string,
-    endpoint: body["endpoint"] as string,
+    kind: "pbank",
+    baseUrl: requireStringField(body, "baseUrl"),
+    username: requireStringField(body, "username"),
+    password: requireStringField(body, "password"),
+    ...(rightsStatus !== undefined ? { rightsStatus } : {}),
+    ...(rightsHolder !== undefined ? { rightsHolder } : {}),
+    ...(rightsScope !== undefined ? { rightsScope } : {}),
+    ...(rightsNote !== undefined ? { rightsNote } : {}),
   };
 }
+
+function requireStringField(body: Record<string, unknown>, name: string): string {
+  const value = body[name];
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${name} is required`);
+  }
+  return value;
+}
+
+function optionalStringField(body: Record<string, unknown>, name: string): string | undefined {
+  const value = body[name];
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed === "" ? undefined : trimmed;
+}

hub/src/admin/routes/explorerRoutes.ts

@@ -155,7 +155,12 @@ export async function registerExplorerRoutes(
         workspaceRoot: config.projectWorkspaceRoot,
         ...(typeof body.folderId === "string" ? { folderId: body.folderId } : {}),
       });
-      return reply.status(201).send({ id: result.projectId, name: body.name });
+      return reply.status(201).send({
+        projectId: result.projectId,
+        folderId: result.folderId,
+        workspaceDir: result.workspaceDir,
+        name: body.name,
+      });
     } catch (err) {
       return handleRouteError(reply, err);
     }

hub/src/agent/configuration.ts

@@ -18,6 +18,7 @@ export interface AgentRoleRow {
   readonly createdAt: string;
   readonly updatedAt: string;
   readonly skillNames: readonly string[];
+  readonly folderId: string | null;
 }
 
 export interface AgentSkillRow {
@@ -30,6 +31,17 @@ export interface AgentSkillRow {
   readonly createdAt: string;
   readonly updatedAt: string;
   readonly boundRoleIds: readonly string[];
+  readonly folderId: string | null;
+}
+
+/**
+ * ADR-0028 transparent folder node of the org's shared agent-config folder
+ * tree. Grouping only: never part of skill/role identity or run resolution.
+ */
+export interface AgentConfigFolderRow {
+  readonly id: string;
+  readonly name: string;
+  readonly parentId: string | null;
 }
 
 /**
@@ -80,9 +92,213 @@ export class OrganizationAgentConfiguration {
       createdAt: skill.createdAt.toISOString(),
       updatedAt: skill.updatedAt.toISOString(),
       boundRoleIds: skill.roleBindings.map((binding) => binding.role.roleId),
+      folderId: skill.folderId,
     }));
   }
 
+  async listFolders(input: { readonly organizationId: string }): Promise<readonly AgentConfigFolderRow[]> {
+    await this.requireActiveOrganization(input.organizationId);
+    const folders = await this.prisma.organizationAgentConfigFolder.findMany({
+      where: { organizationId: input.organizationId },
+      orderBy: [{ name: "asc" }, { id: "asc" }],
+      select: { id: true, name: true, parentId: true },
+    });
+    return folders;
+  }
+
+  async createFolder(input: {
+    readonly organizationId: string;
+    readonly name: string;
+    readonly parentId?: string | undefined;
+  }): Promise<AgentConfigFolderRow> {
+    await this.requireActiveOrganization(input.organizationId);
+    const name = nonEmpty(input.name, "folder name");
+    return this.prisma.$transaction(async (tx) => {
+      if (input.parentId !== undefined) {
+        await requireFolder(tx, input.organizationId, input.parentId);
+      }
+      const folder = await tx.organizationAgentConfigFolder.create({
+        data: {
+          organizationId: input.organizationId,
+          name,
+          ...(input.parentId !== undefined ? { parentId: input.parentId } : {}),
+        },
+        select: { id: true, name: true, parentId: true },
+      });
+      await tx.auditEntry.create({
+        data: {
+          organizationId: input.organizationId,
+          action: "agent_config_folder.created",
+          metadata: { folderId: folder.id, name: folder.name, parentId: folder.parentId },
+        },
+      });
+      return folder;
+    });
+  }
+
+  /**
+   * Rename and/or move a folder inside the same Organization tree. Moving is
+   * rejected when the target parent is the folder itself or one of its
+   * descendants (would create a cycle).
+   */
+  async updateFolder(input: {
+    readonly organizationId: string;
+    readonly folderId: string;
+    readonly name?: string | undefined;
+    readonly parentId?: string | null | undefined;
+  }): Promise<AgentConfigFolderRow> {
+    await this.requireActiveOrganization(input.organizationId);
+    return this.prisma.$transaction(async (tx) => {
+      const folder = await requireFolder(tx, input.organizationId, input.folderId);
+      if (input.parentId !== undefined && input.parentId !== null) {
+        if (input.parentId === folder.id) {
+          throw new Error("folder cannot be its own parent");
+        }
+        await requireFolder(tx, input.organizationId, input.parentId);
+        const descendant = await tx.$queryRaw<Array<{ found: boolean }>>(Prisma.sql`
+          WITH RECURSIVE descendants AS (
+            SELECT "id" FROM "OrganizationAgentConfigFolder" WHERE "parentId" = ${folder.id}
+            UNION ALL
+            SELECT child."id" FROM "OrganizationAgentConfigFolder" child
+            JOIN descendants parent ON child."parentId" = parent."id"
+          )
+          SELECT EXISTS(SELECT 1 FROM descendants WHERE "id" = ${input.parentId}) AS found
+        `);
+        if (descendant[0]?.found === true) throw new Error("folder cannot be moved below its descendant");
+      }
+      const name = input.name !== undefined ? nonEmpty(input.name, "folder name") : undefined;
+      const updated = await tx.organizationAgentConfigFolder.update({
+        where: { id: folder.id },
+        data: {
+          ...(name !== undefined ? { name } : {}),
+          ...(input.parentId !== undefined ? { parentId: input.parentId } : {}),
+        },
+        select: { id: true, name: true, parentId: true },
+      });
+      await tx.auditEntry.create({
+        data: {
+          organizationId: input.organizationId,
+          action: "agent_config_folder.updated",
+          metadata: {
+            folderId: folder.id,
+            ...(name !== undefined ? { name } : {}),
+            ...(input.parentId !== undefined ? { parentId: input.parentId } : {}),
+          },
+        },
+      });
+      return updated;
+    });
+  }
+
+  /**
+   * Delete a folder. Refused while the folder still has child folders, roles
+   * or skills (ADR-0028: items are relocated explicitly, so no orphan-placement
+   * rule is needed).
+   */
+  async deleteFolder(input: {
+    readonly organizationId: string;
+    readonly folderId: string;
+  }): Promise<void> {
+    await this.requireActiveOrganization(input.organizationId);
+    await this.prisma.$transaction(async (tx) => {
+      const folder = await requireFolder(tx, input.organizationId, input.folderId);
+      const childFolders = await tx.organizationAgentConfigFolder.count({
+        where: { parentId: folder.id },
+      });
+      if (childFolders > 0) {
+        throw new Error(`cannot delete folder: still has ${childFolders} child folder(s)`);
+      }
+      const skills = await tx.organizationAgentSkill.count({
+        where: { organizationId: input.organizationId, folderId: folder.id },
+      });
+      const roles = await tx.organizationAgentRole.count({
+        where: { organizationId: input.organizationId, folderId: folder.id },
+      });
+      if (skills > 0 || roles > 0) {
+        throw new Error(`cannot delete folder: still has ${roles} role(s) and ${skills} skill(s)`);
+      }
+      await tx.organizationAgentConfigFolder.delete({ where: { id: folder.id } });
+      await tx.auditEntry.create({
+        data: {
+          organizationId: input.organizationId,
+          action: "agent_config_folder.deleted",
+          metadata: { folderId: folder.id, name: folder.name },
+        },
+      });
+    });
+  }
+
+  /**
+   * Assign a skill to a folder (or unfile it with `folderId: null`). This is
+   * a label-class change in the ADR-0017 sense — the execution surface is
+   * untouched, so no session archival (ADR-0028).
+   */
+  async setSkillFolder(input: {
+    readonly organizationId: string;
+    readonly name: string;
+    readonly folderId: string | null;
+  }): Promise<void> {
+    await this.requireActiveOrganization(input.organizationId);
+    await this.prisma.$transaction(async (tx) => {
+      const skill = await tx.organizationAgentSkill.findUnique({
+        where: { organizationId_name: { organizationId: input.organizationId, name: input.name } },
+        select: { id: true, disabledAt: true },
+      });
+      if (skill === null || skill.disabledAt !== null) {
+        throw new Error(`active skill not found in organization: ${input.name}`);
+      }
+      if (input.folderId !== null) {
+        await requireFolder(tx, input.organizationId, input.folderId);
+      }
+      await tx.organizationAgentSkill.update({
+        where: { id: skill.id },
+        data: { folderId: input.folderId },
+      });
+      await tx.auditEntry.create({
+        data: {
+          organizationId: input.organizationId,
+          action: "agent_skill.folder_set",
+          metadata: { name: input.name, folderId: input.folderId },
+        },
+      });
+    });
+  }
+
+  /**
+   * Assign a role to a folder (or unfile it with `folderId: null`). Same
+   * label-class semantics as `setSkillFolder`: no session archival (ADR-0028).
+   */
+  async setRoleFolder(input: {
+    readonly organizationId: string;
+    readonly roleId: string;
+    readonly folderId: string | null;
+  }): Promise<void> {
+    await this.requireActiveOrganization(input.organizationId);
+    await this.prisma.$transaction(async (tx) => {
+      const role = await tx.organizationAgentRole.findUnique({
+        where: { organizationId_roleId: { organizationId: input.organizationId, roleId: input.roleId } },
+        select: { id: true, disabledAt: true },
+      });
+      if (role === null || role.disabledAt !== null) {
+        throw new Error(`active role not found in organization: ${input.roleId}`);
+      }
+      if (input.folderId !== null) {
+        await requireFolder(tx, input.organizationId, input.folderId);
+      }
+      await tx.organizationAgentRole.update({
+        where: { id: role.id },
+        data: { folderId: input.folderId },
+      });
+      await tx.auditEntry.create({
+        data: {
+          organizationId: input.organizationId,
+          action: "agent_role.folder_set",
+          metadata: { roleId: input.roleId, folderId: input.folderId },
+        },
+      });
+    });
+  }
+
   async installSkill(input: {
     readonly organizationId: string;
     readonly sourceDir: string;
@@ -173,7 +389,7 @@ export class OrganizationAgentConfiguration {
         where: { id: skill.id },
         data: { disabledAt: new Date() },
       });
-      await archiveRoleSessions(
+      await invalidateRoleSessionClaudeIds(
         tx,
         input.organizationId,
         skill.roleBindings.map((binding) => binding.role.roleId),
@@ -271,7 +487,7 @@ export class OrganizationAgentConfiguration {
         },
       });
       if (previous !== null && previous.contentDigest !== skill.contentDigest) {
-        await archiveRoleSessions(
+        await invalidateRoleSessionClaudeIds(
           tx,
           input.organizationId,
           skill.roleBindings.map((binding) => binding.role.roleId),
@@ -379,7 +595,7 @@ export class OrganizationAgentConfiguration {
       if (activeDefaultCount !== 1) {
         throw new Error(`organization ${input.organizationId} must have exactly one active default role`);
       }
-      if (executionSurfaceChanged) await archiveRoleSessions(tx, input.organizationId, [input.roleId]);
+      if (executionSurfaceChanged) await invalidateRoleSessionClaudeIds(tx, input.organizationId, [input.roleId]);
       await tx.auditEntry.create({
         data: {
           organizationId: input.organizationId,
@@ -449,7 +665,7 @@ export class OrganizationAgentConfiguration {
           })),
         });
       }
-      await archiveRoleSessions(tx, input.organizationId, [input.roleId]);
+      await invalidateRoleSessionClaudeIds(tx, input.organizationId, [input.roleId]);
       await tx.auditEntry.create({
         data: {
           organizationId: input.organizationId,
@@ -472,7 +688,22 @@ export class OrganizationAgentConfiguration {
   }
 }
 
-async function archiveRoleSessions(
+/**
+ * Invalidate the provider session cursor (e.g. `claudeSessionId`) for every
+ * active session of the given roles, WITHOUT archiving the session.
+ *
+ * Execution-surface changes (role model/systemPrompt/tools, skill content or
+ * binding changes) make a stale provider session cursor unsafe to resume: the
+ * prior turns were produced under a different config. But the conversation
+ * history itself (AgentMessage rows) is still valuable and the logical Hub
+ * session should stay continuous — the next run re-seeds context from the
+ * transcript instead of resuming the old provider session. So we drop only
+ * the cursor, not the session.
+ *
+ * `userResumable` is cleared because the session is no longer backed by a
+ * live provider cursor the user can drop back into.
+ */
+async function invalidateRoleSessionClaudeIds(
   tx: Prisma.TransactionClient,
   organizationId: string,
   roleIds: readonly string[],
@@ -482,24 +713,36 @@ async function archiveRoleSessions(
     where: {
       roleId: { in: [...new Set(roleIds)] },
       project: { organizationId },
+      archivedAt: null,
     },
-    select: { id: true, archivedAt: true, metadata: true },
+    select: { id: true, metadata: true },
   });
-  const archivedAt = new Date();
   for (const session of sessions) {
     const metadata = typeof session.metadata === "object" && session.metadata !== null && !Array.isArray(session.metadata)
       ? session.metadata as Prisma.JsonObject
       : {};
+    const { claudeSessionId: _drop, ...rest } = metadata;
     await tx.agentSession.update({
       where: { id: session.id },
-      data: {
-        ...(session.archivedAt === null ? { archivedAt } : {}),
-        metadata: { ...metadata, userResumable: false },
-      },
+      data: { metadata: { ...rest, userResumable: false } },
     });
   }
 }
 
+async function requireFolder(
+  tx: Prisma.TransactionClient,
+  organizationId: string,
+  folderId: string,
+): Promise<{ readonly id: string; readonly name: string; readonly parentId: string | null }> {
+  const folder = await tx.organizationAgentConfigFolder.findFirst({
+    where: { id: folderId, organizationId },
+    select: { id: true, name: true, parentId: true },
+  });
+  if (folder === null) throw new Error(`folder not found in organization: ${folderId}`);
+  return folder;
+}
+
+
 function nonEmpty(value: string, label: string): string {
   const normalized = value.trim();
   if (normalized === "") throw new Error(`${label} is required`);
@@ -530,6 +773,7 @@ function toRoleRow(role: {
   readonly disabledAt: Date | null;
   readonly createdAt: Date;
   readonly updatedAt: Date;
+  readonly folderId: string | null;
   readonly skillBindings: ReadonlyArray<{
     readonly skill: { readonly name: string; readonly disabledAt: Date | null };
   }>;
@@ -549,5 +793,6 @@ function toRoleRow(role: {
     skillNames: role.skillBindings
       .filter((binding) => binding.skill.disabledAt === null)
       .map((binding) => binding.skill.name),
+    folderId: role.folderId,
   };
 }

hub/src/agent/roleTools.ts

@@ -1,11 +1,13 @@
 export const DEFAULT_CLAUDE_BUILT_IN_TOOLS = [
   "Read",
   "Write",
+  "Edit",
   "Bash",
   "Glob",
   "Grep",
   "WebFetch",
   "WebSearch",
+  "TodoWrite",
 ] as const;
 
 export const CPH_HUB_MCP_SERVER_NAME = "cph_hub";
@@ -15,6 +17,10 @@ export const CPH_HUB_MCP_TOOL_IDS = [
   "feishu_download_resource",
   "request_approval",
   "convert_pdf_to_md",
+  "pbank_search_problems",
+  "pbank_get_problem",
+  "pbank_get_many_problems",
+  "todo_write",
 ] as const;
 
 export type CphHubMcpToolId = (typeof CPH_HUB_MCP_TOOL_IDS)[number];
@@ -24,48 +30,65 @@ export interface ClaudeSdkToolConfig {
   readonly allowedTools: readonly string[];
 }
 
-const ROLE_TOOL_TO_CLAUDE_BUILT_INS = new Map<string, readonly string[]>([
-  ["read_file", ["Read"]],
-  ["write_file", ["Write"]],
-  ["list_files", ["Glob"]],
-  ["search_files", ["Grep"]],
-  ["bash", ["Bash"]],
+const ROLE_TOOL_TO_CLAUDE_BUILT_INS: Readonly<Record<string, readonly string[]>> = {
+  read_file: ["Read"],
+  write_file: ["Write", "Edit"],
+  list_files: ["Glob"],
+  search_files: ["Grep"],
+  bash: ["Bash"],
   // ADR-0017 replaced cph custom tools with Bash commands. Granting either
   // cph role tool therefore exposes the SDK Bash tool; cph-only Bash narrowing
   // would need a separate command-policy layer.
-  ["cph_check", ["Bash"]],
-  ["cph_build", ["Bash"]],
-  ["web_fetch", ["WebFetch"]],
-  ["web_search", ["WebSearch"]],
-  ["Read", ["Read"]],
-  ["Write", ["Write"]],
-  ["Bash", ["Bash"]],
-  ["Glob", ["Glob"]],
-  ["Grep", ["Grep"]],
-  ["WebFetch", ["WebFetch"]],
-  ["WebSearch", ["WebSearch"]],
-]);
+  cph_check: ["Bash"],
+  cph_build: ["Bash"],
+  web_fetch: ["WebFetch"],
+  web_search: ["WebSearch"],
+  todo: ["TodoWrite"],
+  TodoWrite: ["TodoWrite"],
+  Read: ["Read"],
+  Write: ["Write"],
+  Edit: ["Edit"],
+  Bash: ["Bash"],
+  Glob: ["Glob"],
+  Grep: ["Grep"],
+  WebFetch: ["WebFetch"],
+  WebSearch: ["WebSearch"],
+};
 
-const ROLE_TOOL_TO_CPH_HUB_MCP_TOOL = new Map<string, CphHubMcpToolId>([
-  ["send_file", "send_file"],
-  ["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 ROLE_TOOL_TO_CPH_HUB_MCP_TOOLS: Readonly<Record<string, readonly CphHubMcpToolId[]>> = {
+  send_file: ["send_file"],
+  feishu_read_context: ["feishu_read_context"],
+  feishu_download_resource: ["feishu_download_resource"],
+  request_approval: ["request_approval"],
+  convert_pdf_to_md: ["convert_pdf_to_md"],
+  pbank: ["pbank_search_problems", "pbank_get_problem", "pbank_get_many_problems"],
+  pbank_search_problems: ["pbank_search_problems"],
+  pbank_get_problem: ["pbank_get_problem"],
+  pbank_get_many_problems: ["pbank_get_many_problems"],
+  todo: ["todo_write"],
+  TodoWrite: ["todo_write"],
+  todo_write: ["todo_write"],
+  "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"],
+  "mcp__cph_hub__pbank_search_problems": ["pbank_search_problems"],
+  "mcp__cph_hub__pbank_get_problem": ["pbank_get_problem"],
+  "mcp__cph_hub__pbank_get_many_problems": ["pbank_get_many_problems"],
+  "mcp__cph_hub__todo_write": ["todo_write"],
+};
 
 const SUPPORTED_ROLE_TOOLS = new Set([
-  ...ROLE_TOOL_TO_CLAUDE_BUILT_INS.keys(),
-  ...ROLE_TOOL_TO_CPH_HUB_MCP_TOOL.keys(),
+  ...Object.keys(ROLE_TOOL_TO_CLAUDE_BUILT_INS),
+  ...Object.keys(ROLE_TOOL_TO_CPH_HUB_MCP_TOOLS),
 ]);
 
-export function claudeSdkToolConfigForRole(roleTools: readonly string[] | undefined): ClaudeSdkToolConfig {
-  if (roleTools === undefined) {
+export function claudeSdkToolConfigForRole(
+  roleTools: readonly string[] | null | undefined,
+): ClaudeSdkToolConfig {
+  // DB/runtime "unrestricted" is JSON null; treat the same as undefined.
+  if (roleTools === undefined || roleTools === null) {
     const mcpTools = CPH_HUB_MCP_TOOL_IDS.map(claudeMcpToolName);
     return {
       tools: [...DEFAULT_CLAUDE_BUILT_IN_TOOLS],
@@ -77,13 +100,12 @@ export function claudeSdkToolConfigForRole(roleTools: readonly string[] | undefi
   const allowedTools: string[] = [];
   for (const roleTool of roleTools) {
     assertSupportedRoleTool(roleTool);
-    for (const tool of ROLE_TOOL_TO_CLAUDE_BUILT_INS.get(roleTool) ?? []) {
+    for (const tool of ROLE_TOOL_TO_CLAUDE_BUILT_INS[roleTool] ?? []) {
       pushUnique(builtIns, tool);
       pushUnique(allowedTools, tool);
     }
 
-    const mcpTool = ROLE_TOOL_TO_CPH_HUB_MCP_TOOL.get(roleTool);
-    if (mcpTool !== undefined) {
+    for (const mcpTool of ROLE_TOOL_TO_CPH_HUB_MCP_TOOLS[roleTool] ?? []) {
       pushUnique(allowedTools, claudeMcpToolName(mcpTool));
     }
   }
@@ -91,24 +113,37 @@ export function claudeSdkToolConfigForRole(roleTools: readonly string[] | undefi
   return { tools: builtIns, allowedTools };
 }
 
-export function cphHubMcpToolsForRole(roleTools: readonly string[] | undefined): readonly CphHubMcpToolId[] {
-  if (roleTools === undefined) return [...CPH_HUB_MCP_TOOL_IDS];
+export function cphHubMcpToolsForRole(
+  roleTools: readonly string[] | null | undefined,
+): readonly CphHubMcpToolId[] {
+  // Always expose hub-side todo_write so progress cards work even when the
+  // native Claude TodoWrite tool is not registered in headless agent mode.
+  if (roleTools === undefined || roleTools === null) {
+    return [...CPH_HUB_MCP_TOOL_IDS];
+  }
 
-  const tools: CphHubMcpToolId[] = [];
+  const tools: CphHubMcpToolId[] = ["todo_write"];
   for (const roleTool of roleTools) {
     assertSupportedRoleTool(roleTool);
-    const mcpTool = ROLE_TOOL_TO_CPH_HUB_MCP_TOOL.get(roleTool);
-    if (mcpTool !== undefined) pushUnique(tools, mcpTool);
+    for (const mcpTool of ROLE_TOOL_TO_CPH_HUB_MCP_TOOLS[roleTool] ?? []) {
+      pushUnique(tools, mcpTool);
+    }
   }
   return tools;
 }
 
-export function roleToolsAllow(roleTools: readonly string[] | undefined, roleTool: string): boolean {
-  if (roleTools === undefined) return true;
+export function roleToolsAllow(
+  roleTools: readonly string[] | null | undefined,
+  roleTool: string,
+): boolean {
+  if (roleTools === undefined || roleTools === null) return true;
   for (const configured of roleTools) {
     assertSupportedRoleTool(configured);
     if (configured === roleTool) return true;
-    if (ROLE_TOOL_TO_CPH_HUB_MCP_TOOL.get(configured) === roleTool) return true;
+    const mapped = ROLE_TOOL_TO_CPH_HUB_MCP_TOOLS[configured];
+    if (mapped !== undefined && mapped.includes(roleTool as CphHubMcpToolId)) return true;
+    // Umbrella: role tool "pbank" allows any pbank_* MCP or role tool.
+    if (configured === "pbank" && roleTool.startsWith("pbank")) return true;
   }
   return false;
 }

hub/src/agent/runner.ts

@@ -47,7 +47,7 @@ export type StreamEvent =
   | { readonly type: "thinking-delta"; readonly text: string }
   | { readonly type: "tool-start"; readonly toolName: string; readonly toolUseId: string }
   | { readonly type: "tool-end"; readonly toolName: string; readonly toolUseId: string; readonly input: unknown; readonly durationMs?: number }
-  | { readonly type: "tool-result"; readonly toolUseId: string; readonly toolName: string; readonly result: string; readonly isError: boolean; readonly durationMs?: number }
+  | { readonly type: "tool-result"; readonly toolUseId: string; readonly toolName: string; readonly result: string; readonly isError: boolean; readonly input?: unknown; readonly durationMs?: number }
   | { readonly type: "finish" };
 
 export type StreamCallback = (event: StreamEvent) => void;
@@ -140,7 +140,9 @@ export async function runAgent(req: RunRequest): Promise<RunResult> {
   let cleanupSecurity = async (): Promise<void> => {};
   try {
     await persistAgentMessage(req, "user", req.prompt);
-    const toolConfig = claudeSdkToolConfigForRole(req.tools);
+    // Role tools JSON null means the default single-agent tool set, not "deny all".
+    const roleToolIds = req.tools === null ? undefined : req.tools;
+    const toolConfig = claudeSdkToolConfigForRole(roleToolIds);
     const workspaceRoot = req.project.workspaceRoot?.trim();
     if (workspaceRoot === undefined || workspaceRoot === "") {
       throw new Error("Agent run requires the configured workspace root");
@@ -154,14 +156,42 @@ export async function runAgent(req: RunRequest): Promise<RunResult> {
     });
     cleanupSecurity = security.cleanup;
     const hasSkills = security.skillIds.length > 0;
-
     type QueryOptions = NonNullable<Parameters<typeof query>[0]["options"]>;
+    // Always use an explicit tool list — never the claude_code preset.
+    // The preset registers Agent/SendMessage/Task multi-agent machinery.
+    // Concurrent background agents abort with reason "background", and the
+    // Claude Agent SDK maps that to toolDenialKind "cancelled" with:
+    //   "The user doesn't want to take this action right now..."
+    // which freezes Bash mid-run while Read/Glob continue to work.
+    // Hub "unrestricted" means the default single-agent built-ins + MCP, not
+    // the full interactive Claude product surface.
+    const skillExtras = hasSkills ? (["Skill"] as const) : ([] as const);
+    const toolsOption: QueryOptions["tools"] = uniqueTools([
+      ...toolConfig.tools,
+      "TodoWrite",
+      ...skillExtras,
+    ]);
+    const allowedToolsOption = uniqueTools([
+      ...toolConfig.allowedTools,
+      "TodoWrite",
+      "mcp__cph_hub__todo_write",
+      ...skillExtras,
+    ]);
+    // Hard deny multi-agent orchestration even if a future preset/skills path
+    // reintroduces them — bypassPermissions would otherwise auto-allow them.
+    const disallowedToolsOption = [
+      "Agent",
+      "SendMessage",
+      "TeamCreate",
+      "Task",
+      "ScheduleWakeup",
+    ] as const;
+
     const options: QueryOptions = {
       cwd: security.cwd,
-      // `skills` controls discovery/allowlisting, but an explicit `tools`
-      // list still has to expose the Skill dispatcher itself.
-      tools: [...toolConfig.tools, ...(hasSkills ? ["Skill"] : [])],
-      allowedTools: [...toolConfig.allowedTools],
+      tools: toolsOption,
+      allowedTools: allowedToolsOption,
+      disallowedTools: [...disallowedToolsOption],
       maxTurns: cap,
       includePartialMessages: true,
       // ADR-0018: bypass interactive prompts (headless server); the sandbox
@@ -178,7 +208,16 @@ export async function runAgent(req: RunRequest): Promise<RunResult> {
       // The project workspace is untrusted input. Do not load user/project
       // settings that could widen tools, hooks, MCP servers, or sandbox paths.
       settingSources: [],
-      settings: { disableBundledSkills: true },
+      settings: {
+        disableBundledSkills: true,
+        todoFeatureEnabled: true,
+        // Sessions are resumed across runs (ADR-0017). Without auto-compact
+        // the SDK jsonl grows unboundedly — a long-lived project session hit
+        // 31 MB / 1995 lines, making every API call resend the entire history
+        // and inflating a "change a title" task to 22 minutes. Let the SDK
+        // compact automatically when the context window fills.
+        autoCompactEnabled: true,
+      },
       ...(hasSkills && security.skillPluginRoot !== undefined
         ? { plugins: [{ type: "local" as const, path: security.skillPluginRoot, skipMcpDiscovery: true }] }
         : {}),
@@ -198,13 +237,25 @@ export async function runAgent(req: RunRequest): Promise<RunResult> {
     if (req.abortController !== undefined) options.abortController = req.abortController;
     if (req.onSdkStderr !== undefined) options.stderr = req.onSdkStderr;
 
+    // When there is no provider session cursor to resume (first run, or after a
+    // role/skill/model config change invalidated claudeSessionId), re-seed the
+    // conversation from this Hub session's prior AgentMessage rows. This keeps
+    // the logical session continuous across config changes and restarts — the
+    // agent still "remembers" the earlier turns even though the SDK starts a
+    // fresh provider session. The resume path above is preferred when available
+    // (it carries tool calls/results natively and avoids re-sending tokens).
+    const promptForAgent = req.resumeSessionId === undefined
+      ? await withSessionHistory(req, req.prompt)
+      : req.prompt;
+
     const conversation = query({
-      prompt: req.prompt,
+      prompt: promptForAgent,
       options,
     });
 
-    // Track tool start timestamps for duration calculation
+    // Track tool start timestamps and names/inputs for duration + tool-result attribution.
     const toolStartTimestamps = new Map<string, number>();
+    const toolMetaByUseId = new Map<string, { readonly name: string; readonly input: unknown }>();
 
     for await (const message of conversation) {
       switch (message.type) {
@@ -225,6 +276,10 @@ export async function runAgent(req: RunRequest): Promise<RunResult> {
           if (evt.type === "content_block_start" && evt.content_block.type === "tool_use") {
             const toolUseId = evt.content_block.id;
             toolStartTimestamps.set(toolUseId, Date.now());
+            toolMetaByUseId.set(toolUseId, {
+              name: evt.content_block.name,
+              input: undefined,
+            });
             onStream?.({ type: "tool-start", toolName: evt.content_block.name, toolUseId });
           }
           if (evt.type === "content_block_stop") {
@@ -246,6 +301,7 @@ export async function runAgent(req: RunRequest): Promise<RunResult> {
               const durationMs = toolStartTimestamps.has(block.id)
                 ? Date.now() - (toolStartTimestamps.get(block.id) ?? 0)
                 : undefined;
+              toolMetaByUseId.set(block.id, { name: block.name, input: block.input });
               onStream?.({
                 type: "tool-end",
                 toolName: block.name,
@@ -279,12 +335,14 @@ export async function runAgent(req: RunRequest): Promise<RunResult> {
             const isError = block.is_error === true;
             const resultText = extractToolResultText(block.content);
             const durationMs = toolStartTimestamps.get(toolUseId);
+            const meta = toolMetaByUseId.get(toolUseId);
             onStream?.({
               type: "tool-result",
               toolUseId,
-              toolName: toolUseId,
+              toolName: meta?.name ?? toolUseId,
               result: resultText,
               isError,
+              ...(meta?.input !== undefined ? { input: meta.input } : {}),
               ...(durationMs !== undefined ? { durationMs: Date.now() - durationMs } : {}),
             });
           }
@@ -333,6 +391,39 @@ export async function runAgent(req: RunRequest): Promise<RunResult> {
   }
 }
 
+/**
+ * Re-seed a run's prompt with this Hub session's prior conversation when the
+ * SDK cannot resume a provider session (no `resumeSessionId`). Pulls prior
+ * `AgentMessage` rows for this session — excluding the current run's own user
+ * message, which was already persisted before `runAgent` called this — and
+ * frames them as `<session_history>` so the model treats them as prior turns,
+ * not new instructions. The current run's prompt follows as the live request.
+ *
+ * Best-effort: if the history query fails, the run proceeds with the bare
+ * prompt rather than aborting. A cap (`MAX_HISTORY_TURNS`) bounds token cost;
+ * older turns beyond the cap are dropped, preserving the most recent context.
+ */
+async function withSessionHistory(req: RunRequest, prompt: string): Promise<string> {
+  const MAX_HISTORY_TURNS = 40;
+  try {
+    const messages = await req.prisma.agentMessage.findMany({
+      where: { sessionId: req.sessionId, runId: { not: req.runId } },
+      orderBy: { createdAt: "asc" },
+      select: { role: true, content: true },
+      take: MAX_HISTORY_TURNS * 2, // user+assistant per turn
+    });
+    if (messages.length === 0) return prompt;
+    const turns: string[] = [];
+    for (const message of messages) {
+      const label = message.role === "assistant" ? "Assistant" : "User";
+      turns.push(`${label}: ${message.content}`);
+    }
+    return `<session_history>\nThis is the prior conversation in this session, replayed because the provider session could not be resumed. Treat these as earlier turns you produced or received.\n\n${turns.join("\n\n")}\n</session_history>\n\n${prompt}`;
+  } catch {
+    return prompt;
+  }
+}
+
 async function persistAgentMessage(req: RunRequest, role: string, content: string): Promise<void> {
   if (content === "") return;
   try {
@@ -361,3 +452,11 @@ function extractToolResultText(content: unknown): string {
   }
   return parts.join("\n");
 }
+
+function uniqueTools(tools: readonly string[]): string[] {
+  const out: string[] = [];
+  for (const tool of tools) {
+    if (!out.includes(tool)) out.push(tool);
+  }
+  return out;
+}

hub/src/agent/security.ts

@@ -1,4 +1,4 @@
-import { chmod, lstat, mkdir, realpath } from "node:fs/promises";
+import { chmod, cp, lstat, mkdir, readdir, realpath, rm } from "node:fs/promises";
 import { homedir } from "node:os";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import type { RoleSkillEntry } from "./models.js";
@@ -21,6 +21,20 @@ const SAFE_HOST_ENV_KEYS = [
   "LOGNAME",
   "SHELL",
   "CPH_BIN",
+  // Host egress is often only reachable via a local forward proxy. Without
+  // these, sandboxed Bash/curl times out on public HTTPS (ADR-0018: network
+  // open ≠ direct routing). Values come from the trusted service environment.
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "ALL_PROXY",
+  "NO_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "all_proxy",
+  "no_proxy",
+  "NODE_USE_ENV_PROXY",
+  "TYPST_PACKAGE_PATH",
+  "TYPST_PACKAGE_CACHE_PATH",
 ] as const;
 
 const SANDBOX_HIDDEN_ENV_KEYS = [
@@ -122,6 +136,7 @@ export async function createAgentSecurityPolicy(input: AgentSecurityInput): Prom
 
   const sensitiveReadPaths = hostSensitiveReadPaths(hostEnv);
   const runtimeReadPaths = hostRuntimeReadPaths(hostEnv);
+  const typstCacheWritePaths = hostTypstCacheWritePaths(hostEnv);
   const selectedSkills = input.skills ?? [];
   const skillPlugin = selectedSkills.length === 0
     ? null
@@ -130,6 +145,25 @@ export async function createAgentSecurityPolicy(input: AgentSecurityInput): Prom
         runId: input.runId,
         skills: selectedSkills,
       });
+  // Mirror selected skills under the workspace so the agent can Read SKILL.md
+  // without guessing the opaque host plugin UUID path. Workspace `.claude/` and
+  // `.mcp.json` are Claude sandbox stubs — not skill/MCP source of truth.
+  const runtimeSkillsRel = join(".cph", "runtime-skills");
+  const runtimeSkillsAbs = join(workspaceDir, runtimeSkillsRel);
+  await rm(runtimeSkillsAbs, { recursive: true, force: true });
+  await mkdir(runtimeSkillsAbs, { recursive: true, mode: 0o700 });
+  if (skillPlugin !== null) {
+    const pluginSkillsRoot = join(skillPlugin.root, "skills");
+    const skillNames = await readdir(pluginSkillsRoot);
+    for (const skillName of skillNames) {
+      await cp(join(pluginSkillsRoot, skillName), join(runtimeSkillsAbs, skillName), {
+        recursive: true,
+        force: true,
+      });
+    }
+    env.CPH_RUNTIME_SKILLS_DIR = runtimeSkillsAbs;
+    env.CPH_RUNTIME_SKILLS_REL = runtimeSkillsRel;
+  }
   return {
     cwd: workspaceDir,
     workspaceRoot,
@@ -143,7 +177,7 @@ export async function createAgentSecurityPolicy(input: AgentSecurityInput): Prom
       autoAllowBashIfSandboxed: true,
       allowUnsandboxedCommands: false,
       filesystem: {
-        allowWrite: [workspaceDir],
+        allowWrite: [...new Set([workspaceDir, ...typstCacheWritePaths])],
         // Reject every write path by default, then re-open only the canonical
         // workspace. This prevents bubblewrap's ordinary temp exceptions from
         // turning an unauthorized path into a successful ephemeral write.
@@ -213,9 +247,30 @@ function hostRuntimeReadPaths(env: Readonly<Record<string, string | undefined>>)
     if (!isAbsolute(cphBin)) throw new Error("CPH_BIN must be absolute for the Agent subprocess");
     platformPaths.push(resolve(cphBin));
   }
+  platformPaths.push(...configuredTypstPackagePaths(env, ["TYPST_PACKAGE_PATH", "TYPST_PACKAGE_CACHE_PATH"]));
   return [...new Set(platformPaths.map((path) => resolve(path)))];
 }
 
+function hostTypstCacheWritePaths(env: Readonly<Record<string, string | undefined>>): string[] {
+  return configuredTypstPackagePaths(env, ["TYPST_PACKAGE_CACHE_PATH"]);
+}
+
+function configuredTypstPackagePaths(
+  env: Readonly<Record<string, string | undefined>>,
+  names: readonly ("TYPST_PACKAGE_PATH" | "TYPST_PACKAGE_CACHE_PATH")[],
+): string[] {
+  const paths: string[] = [];
+  for (const name of names) {
+    const packagePath = env[name]?.trim();
+    if (packagePath === undefined || packagePath === "") continue;
+    if (!isAbsolute(packagePath)) throw new Error(`${name} must be absolute for the Agent subprocess`);
+    const canonical = resolve(packagePath);
+    if (canonical === "/") throw new Error(`${name} must not be the filesystem root`);
+    paths.push(canonical);
+  }
+  return paths;
+}
+
 function hostSensitiveReadPaths(env: Readonly<Record<string, string | undefined>>): string[] {
   const home = homedir();
   const paths = [

hub/src/agent/todoList.ts

@@ -0,0 +1,266 @@
+/**
+ * Parse agent checklist tools into a stable model for Feishu card progress.
+ *
+ * Supports:
+ * - Claude TodoWrite (and hub mcp todo_write): full-list replace
+ * - Claude TaskCreate / TaskUpdate tools used in headless agent mode
+ */
+
+export type AgentTodoStatus = "pending" | "in_progress" | "completed";
+
+export interface AgentTodoItem {
+  /** Present for Task* tools; optional for whole-list TodoWrite payloads. */
+  readonly id: string | undefined;
+  readonly content: string;
+  readonly status: AgentTodoStatus;
+  /** Present-tense label while the item is active, when the model supplies it. */
+  readonly activeForm: string | undefined;
+}
+
+const STATUSES = new Set<AgentTodoStatus>(["pending", "in_progress", "completed"]);
+
+/** True when the tool name is SDK TodoWrite or hub mcp todo_write. */
+export function isTodoWriteTool(toolName: string): boolean {
+  const lower = toolName.toLowerCase();
+  return (
+    toolName === "TodoWrite" ||
+    toolName.endsWith("__TodoWrite") ||
+    lower === "todo_write" ||
+    lower.endsWith("__todo_write")
+  );
+}
+
+export function isTaskChecklistTool(toolName: string): boolean {
+  const base = stripToolSuffix(toolName);
+  return (
+    base === "TaskCreate" ||
+    base === "TaskUpdate" ||
+    base === "TaskList" ||
+    base === "TaskGet" ||
+    base === "TaskStop" ||
+    base === "TaskOutput"
+  );
+}
+
+export function isChecklistProgressTool(toolName: string): boolean {
+  return isTodoWriteTool(toolName) || isTaskChecklistTool(toolName);
+}
+
+/**
+ * Extract the full todo list from a TodoWrite / todo_write tool_use input.
+ * Returns null when the payload is not a usable body.
+ */
+export function parseTodoWriteInput(input: unknown): readonly AgentTodoItem[] | null {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) return null;
+  if (!("todos" in input)) return null;
+  const rawTodos = (input as { todos?: unknown }).todos;
+  if (!Array.isArray(rawTodos) || rawTodos.length === 0) return null;
+
+  const todos: AgentTodoItem[] = [];
+  for (const raw of rawTodos) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) continue;
+    const record = raw as Record<string, unknown>;
+    const content = typeof record.content === "string" ? record.content.trim() : "";
+    if (content === "") continue;
+    const statusRaw = typeof record.status === "string" ? record.status : "pending";
+    const status: AgentTodoStatus = STATUSES.has(statusRaw as AgentTodoStatus)
+      ? (statusRaw as AgentTodoStatus)
+      : "pending";
+    const activeForm =
+      typeof record.activeForm === "string" && record.activeForm.trim() !== ""
+        ? record.activeForm.trim()
+        : undefined;
+    const id =
+      typeof record.id === "string" && record.id.trim() !== "" ? record.id.trim() : undefined;
+    todos.push({ id, content, status, activeForm });
+  }
+  return todos.length === 0 ? null : todos;
+}
+
+/**
+ * Fold a Task* / TodoWrite tool event into the running checklist.
+ * Returns null when the event does not change checklist state.
+ */
+export function applyChecklistToolEvent(
+  current: readonly AgentTodoItem[],
+  params: {
+    readonly toolName: string;
+    readonly input: unknown;
+    readonly result: unknown;
+    readonly toolUseId?: string | undefined;
+  },
+): readonly AgentTodoItem[] | null {
+  if (isTodoWriteTool(params.toolName)) {
+    return parseTodoWriteInput(params.input);
+  }
+
+  const baseName = stripToolSuffix(params.toolName);
+  if (baseName === "TaskCreate") {
+    return applyTaskCreate(current, params.input, params.result, params.toolUseId);
+  }
+  if (baseName === "TaskUpdate") {
+    return applyTaskUpdate(current, params.input);
+  }
+  return null;
+}
+
+export function todoProgressSummary(todos: readonly AgentTodoItem[]): {
+  readonly completed: number;
+  readonly total: number;
+  readonly inProgress: number;
+} {
+  let completed = 0;
+  let inProgress = 0;
+  for (const todo of todos) {
+    if (todo.status === "completed") completed += 1;
+    else if (todo.status === "in_progress") inProgress += 1;
+  }
+  return { completed, total: todos.length, inProgress };
+}
+
+function stripToolSuffix(toolName: string): string {
+  // SDK sometimes emits TaskCreate_0 sequential copies in the card title path.
+  const bare = toolName.includes("__") ? (toolName.split("__").pop() ?? toolName) : toolName;
+  return bare.replace(/_\d+$/, "");
+}
+
+function applyTaskCreate(
+  current: readonly AgentTodoItem[],
+  input: unknown,
+  result: unknown,
+  toolUseId: string | undefined,
+): readonly AgentTodoItem[] | null {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) return null;
+  const record = input as Record<string, unknown>;
+  const subject =
+    typeof record.subject === "string"
+      ? record.subject.trim()
+      : typeof record.description === "string"
+        ? record.description.trim()
+        : "";
+  if (subject === "") return null;
+  const activeForm =
+    typeof record.activeForm === "string" && record.activeForm.trim() !== ""
+      ? record.activeForm.trim()
+      : undefined;
+  const idFromResult = extractTaskIdFromResult(result);
+  const provisionalId = toolUseId ?? `task-${current.length + 1}`;
+  const id = idFromResult ?? provisionalId;
+
+  // Replace any provisional row for this tool use or same pending subject.
+  const without = current.filter(
+    (t) =>
+      t.id !== provisionalId &&
+      t.id !== toolUseId &&
+      !(t.content === subject && t.status === "pending" && t.id !== id),
+  );
+  const existing = without.find((t) => taskIdsMatch(t.id, id));
+  if (existing !== undefined) {
+    return without.map((t) =>
+      taskIdsMatch(t.id, id)
+        ? {
+            id,
+            content: subject,
+            status: existing.status,
+            activeForm: activeForm ?? existing.activeForm,
+          }
+        : t,
+    );
+  }
+  return [
+    ...without,
+    {
+      id,
+      content: subject,
+      status: "pending",
+      activeForm,
+    },
+  ];
+}
+
+function applyTaskUpdate(
+  current: readonly AgentTodoItem[],
+  input: unknown,
+): readonly AgentTodoItem[] | null {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) return null;
+  const record = input as Record<string, unknown>;
+  const taskId =
+    typeof record.taskId === "string"
+      ? record.taskId.trim()
+      : typeof record.id === "string"
+        ? record.id.trim()
+        : "";
+  if (taskId === "") return null;
+
+  const statusRaw = typeof record.status === "string" ? record.status : undefined;
+  if (statusRaw === "deleted") {
+    const next = current.filter((t) => !taskIdsMatch(t.id, taskId));
+    return next.length === current.length ? null : next;
+  }
+
+  const status: AgentTodoStatus | undefined =
+    statusRaw !== undefined && STATUSES.has(statusRaw as AgentTodoStatus)
+      ? (statusRaw as AgentTodoStatus)
+      : undefined;
+  const subject =
+    typeof record.subject === "string" && record.subject.trim() !== ""
+      ? record.subject.trim()
+      : undefined;
+  const activeForm =
+    typeof record.activeForm === "string" && record.activeForm.trim() !== ""
+      ? record.activeForm.trim()
+      : undefined;
+
+  if (status === undefined && subject === undefined && activeForm === undefined) return null;
+
+  let found = false;
+  const next = current.map((todo) => {
+    if (!taskIdsMatch(todo.id, taskId)) return todo;
+    found = true;
+    return {
+      id: todo.id ?? taskId,
+      content: subject ?? todo.content,
+      status: status ?? todo.status,
+      activeForm: activeForm ?? todo.activeForm,
+    };
+  });
+  if (found) return next;
+
+  // Update arrived before create (or id mismatch): synthesize a row so the
+  // teacher still sees lifecycle updates.
+  if (subject === undefined && status === undefined) return null;
+  return [
+    ...current,
+    {
+      id: taskId,
+      content: subject ?? `任务 ${taskId}`,
+      status: status ?? "pending",
+      activeForm,
+    },
+  ];
+}
+
+function extractTaskIdFromResult(result: unknown): string | undefined {
+  const text =
+    typeof result === "string"
+      ? result
+      : result !== null && typeof result === "object" && "content" in result
+        ? String((result as { content: unknown }).content)
+        : "";
+  if (text === "") return undefined;
+  const hash = text.match(/Task\s*#\s*([0-9A-Za-z_-]+)/i);
+  if (hash?.[1]) return hash[1];
+  const bare = text.match(/\bid\s*[:=]\s*["']?([0-9A-Za-z_-]+)/i);
+  if (bare?.[1]) return bare[1];
+  return undefined;
+}
+
+function taskIdsMatch(a: string | undefined, b: string): boolean {
+  if (a === undefined) return false;
+  return normalizeTaskId(a) === normalizeTaskId(b);
+}
+
+function normalizeTaskId(id: string | undefined): string {
+  if (id === undefined) return "";
+  return id.trim().replace(/^#/, "");
+}

hub/src/agent/tools.ts

@@ -107,7 +107,7 @@ export function feishuContextTool(
       inputSchema: z.object({
         chat_id: z.string().describe("The Feishu chat id to read from."),
         anchor: z.enum(["trigger_message", "status_card", "reply", "thread"]).describe("Which kind of anchor to read."),
-        id: z.string().describe("The anchor id (message id or run id)."),
+        id: z.string().describe("The anchor id: a message_id for trigger_message/status_card/reply, or a thread_id for thread."),
       }),
       execute: async (args): Promise<string> => {
         if (args.chat_id !== ctx.boundChatId) {

hub/src/capability/capabilityConnectionService.ts

@@ -10,22 +10,41 @@ import { randomUUID } from "node:crypto";
 import type { Prisma, PrismaClient } from "@prisma/client";
 import { lockActiveOrganization } from "../org/status.js";
 import { LocalSecretEnvelope } from "../security/secretEnvelope.js";
-import { probeDocmindCredential, type CapabilityReadinessProbe } from "./capabilityReadiness.js";
-import type { CapabilitySecretPayload } from "./types.js";
+import { probeCapabilityCredential, type CapabilityReadinessProbe } from "./capabilityReadiness.js";
+import {
+  CAPABILITY_IDS,
+  type CapabilitySecretPayload,
+  type DocmindCapabilitySecretPayload,
+  type PbankCapabilitySecretPayload,
+  secretKindForCapability,
+} from "./types.js";
 
 const CAPABILITY_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
-const KNOWN_CAPABILITY_IDS = new Set(["pdf_to_md_bundle", "audio_video_to_text"]);
+const KNOWN_CAPABILITY_IDS = new Set<string>(CAPABILITY_IDS);
 
-export interface CapabilityCredentialInput {
-  readonly accessKeyId: string;
-  readonly accessKeySecret: string;
-  readonly endpoint: string;
-}
+export type CapabilityCredentialInput =
+  | {
+      readonly kind: "docmind";
+      readonly accessKeyId: string;
+      readonly accessKeySecret: string;
+      readonly endpoint: string;
+    }
+  | {
+      readonly kind: "pbank";
+      readonly baseUrl: string;
+      readonly username: string;
+      readonly password: string;
+      readonly rightsStatus?: string;
+      readonly rightsHolder?: string;
+      readonly rightsScope?: string;
+      readonly rightsNote?: string;
+    };
 
-export interface RotateCapabilityInput extends CapabilityCredentialInput {
+export interface RotateCapabilityInput {
   readonly organizationId: string;
   readonly capabilityId: string;
   readonly actorUserId: string;
+  readonly credential: CapabilityCredentialInput;
 }
 
 export interface CapabilityConnectionMetadata {
@@ -45,25 +64,24 @@ export interface CapabilityConnectionWriteResult extends CapabilityConnectionMet
 export type CapabilitySecretPayloadV1 = CapabilitySecretPayload;
 
 export class CapabilityConnectionService {
+  private readonly readinessProbe: CapabilityReadinessProbe;
+
   constructor(
     private readonly prisma: PrismaClient,
     private readonly secrets: LocalSecretEnvelope,
-    private readonly readinessProbe: CapabilityReadinessProbe = probeDocmindCredential,
-  ) {}
-
+    readinessProbe: CapabilityReadinessProbe = probeCapabilityCredential,
+  ) {
+    this.readinessProbe = readinessProbe;
+  }
   async rotate(input: RotateCapabilityInput): Promise<CapabilityConnectionWriteResult> {
     if (!CAPABILITY_ID_PATTERN.test(input.capabilityId)) {
       throw new Error(`invalid capabilityId: ${input.capabilityId}`);
     }
-    const payload = validateCredential(input);
+    const payload = validateCredential(input.capabilityId, input.credential);
     await this.prisma.$transaction(async (tx) => {
       await requireCapabilityAdmin(tx, input);
     });
-    await this.readinessProbe({
-      endpoint: payload.endpoint,
-      accessKeyId: payload.accessKeyId,
-      accessKeySecret: payload.accessKeySecret,
-    });
+    await this.readinessProbe(payload);
 
     return this.prisma.$transaction(async (tx) => {
       await requireCapabilityAdmin(tx, input);
@@ -142,6 +160,7 @@ export class CapabilityConnectionService {
             status: "ACTIVE",
             secretVersion: version,
             keyId: envelope.keyId,
+            secretKind: payload.kind,
           },
         },
       });
@@ -209,14 +228,47 @@ export class CapabilityConnectionService {
   }
 }
 
-function validateCredential(input: RotateCapabilityInput): CapabilitySecretPayloadV1 {
-  if (!KNOWN_CAPABILITY_IDS.has(input.capabilityId)) {
-    throw new Error(`unsupported capabilityId: ${input.capabilityId}`);
+function validateCredential(
+  capabilityId: string,
+  input: CapabilityCredentialInput,
+): CapabilitySecretPayload {
+  if (!KNOWN_CAPABILITY_IDS.has(capabilityId)) {
+    throw new Error(`unsupported capabilityId: ${capabilityId}`);
   }
-  const accessKeyId = nonEmpty(input.accessKeyId, "accessKeyId");
-  const accessKeySecret = nonEmpty(input.accessKeySecret, "accessKeySecret");
-  const endpoint = nonEmpty(input.endpoint, "endpoint");
-  return { schemaVersion: 1, accessKeyId, accessKeySecret, endpoint };
+  const expectedKind = secretKindForCapability(capabilityId);
+  if (input.kind !== expectedKind) {
+    throw new Error(`capability ${capabilityId} requires kind=${expectedKind}, got ${input.kind}`);
+  }
+
+  if (input.kind === "docmind") {
+    return {
+      schemaVersion: 1,
+      kind: "docmind",
+      accessKeyId: nonEmpty(input.accessKeyId, "accessKeyId"),
+      accessKeySecret: nonEmpty(input.accessKeySecret, "accessKeySecret"),
+      endpoint: nonEmpty(input.endpoint, "endpoint"),
+    };
+  }
+
+  const baseUrl = normalizeBaseUrl(nonEmpty(input.baseUrl, "baseUrl"));
+  if (!baseUrl.startsWith("https://") && !baseUrl.startsWith("http://")) {
+    throw new Error("baseUrl must be an absolute http(s) URL");
+  }
+  const rightsStatus = optional(input.rightsStatus);
+  const rightsHolder = optional(input.rightsHolder);
+  const rightsScope = optional(input.rightsScope);
+  const rightsNote = optional(input.rightsNote);
+  return {
+    schemaVersion: 1,
+    kind: "pbank",
+    baseUrl,
+    username: nonEmpty(input.username, "username"),
+    password: nonEmpty(input.password, "password"),
+    ...(rightsStatus !== undefined ? { rightsStatus } : {}),
+    ...(rightsHolder !== undefined ? { rightsHolder } : {}),
+    ...(rightsScope !== undefined ? { rightsScope } : {}),
+    ...(rightsNote !== undefined ? { rightsNote } : {}),
+  };
 }
 
 function toMetadata(
@@ -264,3 +316,13 @@ function nonEmpty(value: string, label: string): string {
   if (trimmed === "") throw new Error(`${label} must not be empty`);
   return trimmed;
 }
+
+function optional(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  return trimmed === "" ? undefined : trimmed;
+}
+
+function normalizeBaseUrl(value: string): string {
+  return value.replace(/\/+$/, "");
+}

hub/src/capability/capabilityConnections.ts

@@ -12,17 +12,19 @@ import type { PrismaClient } from "@prisma/client";
 import { LocalSecretEnvelope, type SecretEnvelopeV1 } from "../security/secretEnvelope.js";
 import {
   CapabilityConnectionUnavailable,
+  normalizeCapabilitySecretPayload,
+  secretKindForCapability,
   type CapabilitySecretPayload,
   type CapabilityId,
 } from "./types.js";
 
 const CAPABILITY_PURPOSE = "capability";
 
-export interface ResolvedCapabilityCredential extends CapabilitySecretPayload {
+export type ResolvedCapabilityCredential = CapabilitySecretPayload & {
   readonly connectionId: string;
   readonly organizationId: string;
   readonly capabilityId: string;
-}
+};
 
 /**
  * Resolve the active capability credential for an organization. Throws
@@ -54,17 +56,19 @@ export async function resolveCapabilityCredential(
     connectionId: connection.id,
     secretVersionId: version.id,
   };
-  const payload = secrets.decryptJson<CapabilitySecretPayload>(binding, version.envelope as unknown as SecretEnvelopeV1);
-  if (payload.schemaVersion !== 1) {
-    throw new Error(`unsupported capability secret schemaVersion: ${payload.schemaVersion}`);
+  const payload = normalizeCapabilitySecretPayload(
+    secrets.decryptJson<unknown>(binding, version.envelope as unknown as SecretEnvelopeV1),
+  );
+  const expectedKind = secretKindForCapability(input.capabilityId);
+  if (payload.kind !== expectedKind) {
+    throw new Error(
+      `capability ${input.capabilityId} secret kind mismatch: expected ${expectedKind}, got ${payload.kind}`,
+    );
   }
   return {
     connectionId: connection.id,
     organizationId: connection.organizationId,
     capabilityId: connection.capabilityId,
-    schemaVersion: 1,
-    accessKeyId: payload.accessKeyId,
-    accessKeySecret: payload.accessKeySecret,
-    endpoint: payload.endpoint,
+    ...payload,
   };
 }

hub/src/capability/capabilityReadiness.ts

@@ -1,18 +1,11 @@
 /**
- * ADR-0027: Capability readiness probe. Validates the Alibaba Cloud docmind
- * credential by calling QueryDocParserStatus with a dummy id — a 400 (bad
- * request) means the credential is valid (the API accepted auth but rejected
- * the id); a 401/403 means the credential is bad.
+ * ADR-0027: Capability readiness probes. Validate credentials before
+ * activation. Docmind uses QueryDocParserStatus; PBank uses /login.
  */
 import { classifyNetworkFailure, type NetworkFailureCategory } from "../connections/networkFailure.js";
+import type { CapabilitySecretPayload, DocmindCapabilitySecretPayload, PbankCapabilitySecretPayload } from "./types.js";
 
-export interface CapabilityReadinessInput {
-  readonly endpoint: string;
-  readonly accessKeyId: string;
-  readonly accessKeySecret: string;
-}
-
-export type CapabilityReadinessProbe = (input: CapabilityReadinessInput) => Promise<void>;
+export type CapabilityReadinessProbe = (payload: CapabilitySecretPayload) => Promise<void>;
 
 export class CapabilityReadinessError extends Error {
   constructor(
@@ -33,7 +26,7 @@ export class CapabilityReadinessError extends Error {
  *   - 401/403 (InvalidAccessKey/Forbidden) → credential invalid → probe fails
  *   - network error → unreachable
  */
-export const probeDocmindCredential: CapabilityReadinessProbe = async (input) => {
+export async function probeDocmindCredentialPayload(input: DocmindCapabilitySecretPayload): Promise<void> {
   const url = `https://${input.endpoint}/?Action=QueryDocParserStatus&Id=probe-test&Version=2022-07-11`;
   const authHeader = makeBasicAuth(input.accessKeyId, input.accessKeySecret);
 
@@ -61,6 +54,75 @@ export const probeDocmindCredential: CapabilityReadinessProbe = async (input) =>
       response.status,
     );
   }
+}
+
+/** Probe PBank by logging in and ensuring a token is returned. */
+export async function probePbankCredentialPayload(input: PbankCapabilitySecretPayload): Promise<void> {
+  const baseUrl = input.baseUrl.replace(/\/+$/, "");
+  let response: Response;
+  try {
+    response = await fetch(`${baseUrl}/login`, {
+      method: "POST",
+      headers: { accept: "application/json", "content-type": "application/json" },
+      body: JSON.stringify({ username: input.username, password: input.password }),
+      redirect: "manual",
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch (error) {
+    throw new CapabilityReadinessError(
+      "capability_readiness_unreachable",
+      "PBank credential readiness check could not reach the API",
+      classifyNetworkFailure(error),
+    );
+  }
+  const data: unknown = await response.json().catch(() => null);
+  if (response.status === 401 || response.status === 403) {
+    throw new CapabilityReadinessError(
+      "capability_readiness_rejected",
+      `PBank credential rejected: status ${response.status}`,
+      "http",
+      response.status,
+    );
+  }
+  if (!response.ok) {
+    throw new CapabilityReadinessError(
+      "capability_readiness_rejected",
+      `PBank login failed: status ${response.status}`,
+      "http",
+      response.status,
+    );
+  }
+  if (
+    typeof data !== "object" ||
+    data === null ||
+    !("token" in data) ||
+    typeof data.token !== "string" ||
+    data.token.trim() === ""
+  ) {
+    throw new CapabilityReadinessError(
+      "capability_readiness_rejected",
+      "PBank login did not return a token",
+      "http",
+      response.status,
+    );
+  }
+}
+
+/** Default readiness probe: dispatch by secret kind. */
+export const probeCapabilityCredential: CapabilityReadinessProbe = async (payload) => {
+  if (payload.kind === "docmind") {
+    await probeDocmindCredentialPayload(payload);
+    return;
+  }
+  if (payload.kind === "pbank") {
+    await probePbankCredentialPayload(payload);
+    return;
+  }
+  throw new CapabilityReadinessError(
+    "capability_readiness_unsupported",
+    "unsupported capability secret kind",
+    "configuration",
+  );
 };
 
 function makeBasicAuth(accessKeyId: string, accessKeySecret: string): string {

hub/src/capability/docmindClient.ts

@@ -19,9 +19,10 @@ import $DocmindClient, {
   QueryDocParserStatusRequest,
 } from "@alicloud/docmind-api20220711";
 import { RuntimeOptions } from "@alicloud/tea-util";
-import { createReadStream } from "node:fs";
+import { createReadStream, type ReadStream } from "node:fs";
+import { once } from "node:events";
 import { basename } from "node:path";
-import type { CapabilitySecretPayload } from "./types.js";
+import type { DocmindCapabilitySecretPayload } from "./types.js";
 
 /** A single extracted image downloaded from the markdown's OSS image URLs. */
 export interface DocmindExtractedImage {
@@ -43,7 +44,7 @@ export interface DocmindParseOptions {
 }
 
 export interface CapabilityProviderClient {
-  parse(credential: CapabilitySecretPayload, options: DocmindParseOptions): Promise<DocmindParseResult>;
+  parse(credential: DocmindCapabilitySecretPayload, options: DocmindParseOptions): Promise<DocmindParseResult>;
 }
 
 export class DocmindClientError extends Error {
@@ -61,11 +62,33 @@ export class DocmindClientError extends Error {
 const COST_PER_PAGE_USD = 0.0056;
 const POLL_INTERVAL_MS = 10_000;
 const POLL_TIMEOUT_MS = 5 * 60_000;
+/**
+ * httpx (tea transport) defaults read/connect timeout to 3000ms when unset.
+ * SubmitDocParserJobAdvance uploads the PDF to OSS; multi-MB files routinely
+ * exceed 3s on the silo host (production: ReadTimeout(3000) on
+ * docmind-api-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com).
+ */
+export const DOCMIND_CONNECT_TIMEOUT_MS = 15_000;
+/** Allow slow / large PDF OSS uploads up to the same bound as job polling. */
+export const DOCMIND_READ_TIMEOUT_MS = POLL_TIMEOUT_MS;
+
+/** RuntimeOptions for Docmind SDK calls that may upload or wait on the wire. */
+export function createDocmindRuntimeOptions(): RuntimeOptions {
+  return new RuntimeOptions({
+    connectTimeout: DOCMIND_CONNECT_TIMEOUT_MS,
+    readTimeout: DOCMIND_READ_TIMEOUT_MS,
+  });
+}
 
 type DocmindConfig = ConstructorParameters<typeof $DocmindClient.default>[0];
 
 export class AliyunDocmindClient implements CapabilityProviderClient {
-  async parse(credential: CapabilitySecretPayload, options: DocmindParseOptions): Promise<DocmindParseResult> {
+  async parse(credential: DocmindCapabilitySecretPayload, options: DocmindParseOptions): Promise<DocmindParseResult> {
+    // Open first so missing local inputs fail closed before touching the SDK.
+    // Unhandled createReadStream('error') previously crashed the Hub process.
+    const fileName = basename(options.inputFilePath);
+    const fileStream = await openLocalFileStream(options.inputFilePath);
+
     const config: DocmindConfig = {
       endpoint: credential.endpoint,
       accessKeyId: credential.accessKeyId,
@@ -75,22 +98,21 @@ export class AliyunDocmindClient implements CapabilityProviderClient {
     } as DocmindConfig;
     const client = new $DocmindClient.default(config);
 
-    // 1. Submit job with local file as a ReadStream (not a Buffer — the SDK
-    //    serializes Buffers as JSON {type:"Buffer",data:[...]} which the API
-    //    can't read; a Stream is uploaded as multipart form data).
-    const fileName = basename(options.inputFilePath);
-    const fileStream = createReadStream(options.inputFilePath);
+    // Submit job with local file as a ReadStream (not a Buffer — the SDK
+    // serializes Buffers as JSON {type:"Buffer",data:[...]} which the API
+    // can't read; a Stream is uploaded as multipart form data).
     const advanceRequest = new SubmitDocParserJobAdvanceRequest({
       fileUrlObject: fileStream,
       fileName,
       outputFormat: ["markdown"],
       formulaEnhancement: true,
     });
-    const runtime = new RuntimeOptions({});
+    const runtime = createDocmindRuntimeOptions();
     let submitResponse;
     try {
       submitResponse = await client.submitDocParserJobAdvance(advanceRequest, runtime);
     } catch (e) {
+      fileStream.destroy();
       throw new DocmindClientError(
         e instanceof Error ? e.message : String(e),
         "docmind_unreachable",
@@ -229,3 +251,28 @@ function extractFilename(altText: string, url: string, index: number): string {
   if (base !== "" && base !== "/") return base;
   return `image_${index + 1}.png`;
 }
+
+/**
+ * Open a local file as a ReadStream only after the fd is successfully open.
+ * createReadStream() emits asynchronous 'error' for missing paths; without a
+ * listener that becomes an unhandled EventEmitter error and exits Node.
+ */
+async function openLocalFileStream(path: string): Promise<ReadStream> {
+  const stream = createReadStream(path);
+  try {
+    await once(stream, "open");
+  } catch (error) {
+    stream.destroy();
+    const err = error instanceof Error ? error : new Error(String(error));
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") {
+      throw new DocmindClientError(`input file not found: ${path}`, "docmind_rejected");
+    }
+    throw new DocmindClientError(err.message, "docmind_unreachable");
+  }
+  // After open, residual stream errors must not become unhandled and crash Hub.
+  stream.on("error", () => {
+    // The Aliyun SDK / destroy path owns consumption failures after open.
+  });
+  return stream;
+}

hub/src/capability/pbank.ts

@@ -0,0 +1,664 @@
+/**
+ * ADR-0027: pbank capability — Paradigm 题库 search/fetch tools for Agent runs.
+ *
+ * Invariants:
+ *   1. Credential isolation — org ACTIVE connection is resolved in Hub; credentials
+ *      never reach the Agent process (ADR-0024/0027).
+ *   2. Workspace containment — materialize path is always under the run workspace
+ *      (ADR-0018 AgentSurface).
+ *   3. Mandatory fact — each successful tool call writes ≥1 UsageFact with
+ *      kind=external_capability and unit=requests (cost unknown unless reported).
+ */
+import { inflateRawSync } from "node:zlib";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import type { PrismaClient } from "@prisma/client";
+import { LocalSecretEnvelope } from "../security/secretEnvelope.js";
+import { resolveCapabilityCredential } from "./capabilityConnections.js";
+import {
+  extractProblemId,
+  HttpPbankClient,
+  pbankRightsFromCredential,
+  type PbankClient,
+} from "./pbankClient.js";
+import {
+  CAPABILITIES,
+  asPbankSecret,
+  type PbankCapabilitySecretPayload,
+} from "./types.js";
+
+export const PBANK_CAPABILITY_ID = "pbank" as const;
+const PROVIDER_ID = "paradigm_pbank";
+const MAX_BATCH_SIZE = 20;
+const MAX_PROJECT_BYTES = 80 * 1024 * 1024;
+const MAX_PROJECT_TEXT_BYTES = 120 * 1024;
+const MAX_EXTRACTED_PROJECT_BYTES = 80 * 1024 * 1024;
+const MAX_INLINE_ASSET_BYTES = 1024 * 1024;
+const MAX_INLINE_ASSETS = 4;
+const CACHE_DIR_NAME = ".pbank-sources";
+
+export class CapabilityPathEscape extends Error {
+  constructor(readonly requested: string, readonly workspaceDir: string) {
+    super(`capability path escapes workspace: ${requested} (root ${workspaceDir})`);
+    this.name = "CapabilityPathEscape";
+  }
+}
+
+export interface PbankServiceDeps {
+  readonly prisma: PrismaClient;
+  readonly secrets: LocalSecretEnvelope;
+  readonly client?: PbankClient;
+}
+
+export interface PbankToolContext {
+  readonly organizationId: string;
+  readonly runId: string;
+  readonly workspaceDir: string;
+}
+
+export interface PbankSearchArgs {
+  readonly q?: string | undefined;
+  readonly keywords?: readonly string[] | undefined;
+  readonly pageNum?: number | undefined;
+  readonly pageSize?: number | undefined;
+}
+
+export interface PbankGetProblemArgs {
+  readonly urlOrId: string;
+  readonly includeProjects?: boolean | undefined;
+  readonly materializeProjects?: boolean | undefined;
+  readonly includeAssetImages?: boolean | undefined;
+  readonly includeOccurrences?: boolean | undefined;
+}
+
+export interface PbankGetManyArgs {
+  readonly urlsOrIds: readonly string[];
+  readonly includeProjects?: boolean | undefined;
+  readonly materializeProjects?: boolean | undefined;
+  readonly includeAssetImages?: boolean | undefined;
+  readonly includeOccurrences?: boolean | undefined;
+}
+
+export interface PbankToolResult {
+  readonly data: unknown;
+  readonly inlineImages: readonly { readonly data: string; readonly mimeType: string }[];
+}
+
+interface TokenCacheEntry {
+  readonly token: string;
+  readonly expiresAt: number;
+  readonly password: string;
+  readonly username: string;
+  readonly baseUrl: string;
+}
+export interface PbankService {
+  searchProblems(ctx: PbankToolContext, args: PbankSearchArgs): Promise<PbankToolResult>;
+  getProblem(ctx: PbankToolContext, args: PbankGetProblemArgs): Promise<PbankToolResult>;
+  getManyProblems(ctx: PbankToolContext, args: PbankGetManyArgs): Promise<PbankToolResult>;
+}
+
+export function createPbankService(deps: PbankServiceDeps): PbankService {
+  const client = deps.client ?? new HttpPbankClient();
+  const tokenCache = new Map<string, TokenCacheEntry>();
+
+  return {
+    async searchProblems(ctx: PbankToolContext, args: PbankSearchArgs): Promise<PbankToolResult> {
+      const credential = await resolvePbankCredential(deps, ctx.organizationId);
+      const token = await loginCached(client, tokenCache, credential);
+      const pageNum = clampInt(args.pageNum ?? 1, 1, 10_000);
+      const pageSize = clampInt(args.pageSize ?? 10, 1, 50);
+      const result = await client.searchProblems(credential, token, {
+        q: args.q,
+        keywords: args.keywords,
+        pageNum,
+        pageSize,
+      });
+      const data = {
+        rights: pbankRightsFromCredential(credential),
+        ...(typeof result === "object" && result !== null ? result : { result }),
+      };
+      await writeUsageFact(deps.prisma, ctx.runId, "search", 1);
+      return { data, inlineImages: [] };
+    },
+
+    async getProblem(ctx: PbankToolContext, args: PbankGetProblemArgs): Promise<PbankToolResult> {
+      const credential = await resolvePbankCredential(deps, ctx.organizationId);
+      const bundle = await getProblemBundle(client, tokenCache, credential, ctx.workspaceDir, args);
+      await writeUsageFact(deps.prisma, ctx.runId, extractProblemId(args.urlOrId), 1);
+      return toToolResult(bundle);
+    },
+
+    async getManyProblems(ctx: PbankToolContext, args: PbankGetManyArgs): Promise<PbankToolResult> {
+      if (args.urlsOrIds.length === 0) {
+        throw new Error("urlsOrIds must not be empty");
+      }
+      if (args.urlsOrIds.length > MAX_BATCH_SIZE) {
+        throw new Error(`urlsOrIds exceeds max batch size ${MAX_BATCH_SIZE}`);
+      }
+      const credential = await resolvePbankCredential(deps, ctx.organizationId);
+      const problems = [];
+      for (const urlOrId of args.urlsOrIds) {
+        problems.push(
+          await getProblemBundle(client, tokenCache, credential, ctx.workspaceDir, {
+            urlOrId,
+            includeProjects: args.includeProjects,
+            materializeProjects: args.materializeProjects,
+            includeAssetImages: args.includeAssetImages,
+            includeOccurrences: args.includeOccurrences,
+          }),
+        );
+      }
+      await writeUsageFact(deps.prisma, ctx.runId, "batch", problems.length);
+      return toToolResult({
+        count: problems.length,
+        rights: pbankRightsFromCredential(credential),
+        problems,
+      });
+    },
+  };
+}
+
+
+async function resolvePbankCredential(
+  deps: PbankServiceDeps,
+  organizationId: string,
+): Promise<PbankCapabilitySecretPayload & { connectionId: string }> {
+  const resolved = await resolveCapabilityCredential(deps.prisma, deps.secrets, {
+    organizationId,
+    capabilityId: PBANK_CAPABILITY_ID,
+  });
+  const secret = asPbankSecret(resolved);
+  return { ...secret, connectionId: resolved.connectionId };
+}
+
+async function loginCached(
+  client: PbankClient,
+  cache: Map<string, TokenCacheEntry>,
+  credential: PbankCapabilitySecretPayload & { connectionId: string },
+): Promise<string> {
+  const now = Date.now();
+  const cached = cache.get(credential.connectionId);
+  if (
+    cached !== undefined &&
+    cached.expiresAt - 60_000 > now &&
+    cached.username === credential.username &&
+    cached.password === credential.password &&
+    cached.baseUrl === credential.baseUrl
+  ) {
+    return cached.token;
+  }
+  const login = await client.login(credential);
+  cache.set(credential.connectionId, {
+    token: login.token,
+    expiresAt: login.expiresAt,
+    username: credential.username,
+    password: credential.password,
+    baseUrl: credential.baseUrl,
+  });
+  return login.token;
+}
+
+async function getProblemBundle(
+  client: PbankClient,
+  cache: Map<string, TokenCacheEntry>,
+  credential: PbankCapabilitySecretPayload & { connectionId: string },
+  workspaceDir: string,
+  args: PbankGetProblemArgs,
+): Promise<Record<string, unknown>> {
+  const id = extractProblemId(args.urlOrId);
+  const token = await loginCached(client, cache, credential);
+  const problem = await client.getProblem(credential, token, id);
+  const result: Record<string, unknown> = {
+    id,
+    source: `${credential.baseUrl.replace(/\/+$/, "")}/problem/${id}`,
+    rights: pbankRightsFromCredential(credential),
+    problem,
+  };
+
+  const includeProjects = args.includeProjects !== false;
+  const materializeProjects = args.materializeProjects !== false;
+  const includeAssetImages = args.includeAssetImages !== false;
+  if (includeProjects) {
+    const projects: Record<string, unknown> = {};
+    for (const target of ["problem", "answer"] as const) {
+      try {
+        projects[target] = await downloadAndMaterializeProject({
+          client,
+          credential,
+          token,
+          id,
+          target,
+          workspaceDir,
+          materialize: materializeProjects,
+          includeAssetImages,
+        });
+      } catch (error) {
+        projects[target] = {
+          target,
+          status: "error",
+          message: error instanceof Error ? error.message : String(error),
+        };
+      }
+    }
+    result.projects = projects;
+  }
+
+  if (args.includeOccurrences === true) {
+    try {
+      result.occurrences = await client.getOccurrences(credential, token, id);
+    } catch (error) {
+      result.occurrences = {
+        status: "error",
+        message: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  return result;
+}
+
+async function downloadAndMaterializeProject(input: {
+  readonly client: PbankClient;
+  readonly credential: PbankCapabilitySecretPayload;
+  readonly token: string;
+  readonly id: string;
+  readonly target: "problem" | "answer";
+  readonly workspaceDir: string;
+  readonly materialize: boolean;
+  readonly includeAssetImages: boolean;
+}): Promise<Record<string, unknown>> {
+  const downloaded = await input.client.downloadProject(
+    input.credential,
+    input.token,
+    input.id,
+    input.target,
+  );
+  if (downloaded.buffer.byteLength > MAX_PROJECT_BYTES) {
+    throw new Error(`project archive exceeds ${MAX_PROJECT_BYTES} bytes`);
+  }
+
+  if (!isZipBuffer(downloaded.buffer, downloaded.contentType)) {
+    const text = decodeUtf8IfText(downloaded.buffer);
+    if (text !== null) {
+      return {
+        target: input.target,
+        status: "text",
+        bytes: downloaded.buffer.byteLength,
+        content: text.slice(0, MAX_PROJECT_TEXT_BYTES),
+        omitted: text.length > MAX_PROJECT_TEXT_BYTES ? [{ reason: "text truncated" }] : [],
+      };
+    }
+    return {
+      target: input.target,
+      status: "binary",
+      bytes: downloaded.buffer.byteLength,
+      contentType: downloaded.contentType,
+    };
+  }
+
+  return readProjectZip(downloaded.buffer, {
+    id: input.id,
+    target: input.target,
+    workspaceDir: input.workspaceDir,
+    materialize: input.materialize,
+    includeAssetImages: input.includeAssetImages,
+  });
+}
+
+async function readProjectZip(
+  buffer: Buffer,
+  options: {
+    readonly id: string;
+    readonly target: string;
+    readonly workspaceDir: string;
+    readonly materialize: boolean;
+    readonly includeAssetImages: boolean;
+  },
+): Promise<Record<string, unknown>> {
+  // Pure Node unzip (store/deflate). Do not shell out to host `unzip` —
+  // silo service PATH/tooling must not gate 题库 materialize.
+  const entries = listZipEntries(buffer);
+  const cacheRoot = confineToWorkspace(CACHE_DIR_NAME, options.workspaceDir);
+  const cacheDir = join(cacheRoot, safePathSegment(options.id), safePathSegment(options.target));
+  const extractDir = options.materialize ? join(cacheDir, "source") : null;
+  const zipPath = options.materialize ? join(cacheDir, `${options.target}.zip`) : null;
+
+  if (options.materialize) {
+    await mkdir(cacheDir, { recursive: true });
+    if (extractDir !== null) {
+      await rm(extractDir, { recursive: true, force: true });
+      await mkdir(extractDir, { recursive: true });
+    }
+    if (zipPath !== null) await writeFile(zipPath, buffer);
+  }
+
+  const files: Array<Record<string, unknown>> = [];
+  const assets: Array<{
+    path: string;
+    localPath: string | null;
+    bytes: number;
+    mimeType: string;
+    inlineData?: string;
+  }> = [];
+  const extractedFiles: Array<Record<string, unknown>> = [];
+  const omitted: Array<Record<string, unknown>> = [];
+  let usedTextBytes = 0;
+  let usedExtractedBytes = 0;
+  let inlineAssetCount = 0;
+
+  for (const entry of entries) {
+    if (!safeZipPath(entry.name)) {
+      omitted.push({ path: entry.name, reason: "unsafe path" });
+      continue;
+    }
+    if (entry.name.endsWith("/") || entry.isDirectory) continue;
+    if (usedExtractedBytes >= MAX_EXTRACTED_PROJECT_BYTES) {
+      omitted.push({ path: entry.name, reason: "extracted byte limit reached" });
+      continue;
+    }
+    const maxEntryBytes = Math.max(
+      1,
+      Math.min(MAX_PROJECT_BYTES, MAX_EXTRACTED_PROJECT_BYTES - usedExtractedBytes),
+    );
+    try {
+      const entryBuffer = inflateZipEntry(buffer, entry, maxEntryBytes);
+      usedExtractedBytes += entryBuffer.length;
+      let localPath: string | null = null;
+      if (extractDir !== null) {
+        localPath = join(extractDir, ...entry.name.split(/[\\/]+/));
+        await mkdir(dirname(localPath), { recursive: true });
+        await writeFile(localPath, entryBuffer);
+        extractedFiles.push({
+          path: entry.name,
+          localPath: toWorkspaceRelative(options.workspaceDir, localPath),
+          bytes: entryBuffer.length,
+        });
+      }
+
+      const mimeType = assetMimeType(entry.name);
+      if (mimeType !== null) {
+        const asset: {
+          path: string;
+          localPath: string | null;
+          bytes: number;
+          mimeType: string;
+          inlineData?: string;
+        } = {
+          path: entry.name,
+          localPath: localPath === null ? null : toWorkspaceRelative(options.workspaceDir, localPath),
+          bytes: entryBuffer.length,
+          mimeType,
+        };
+        if (
+          options.includeAssetImages &&
+          isInlineImageMime(mimeType) &&
+          entryBuffer.length <= MAX_INLINE_ASSET_BYTES &&
+          inlineAssetCount < MAX_INLINE_ASSETS
+        ) {
+          asset.inlineData = entryBuffer.toString("base64");
+          inlineAssetCount += 1;
+        }
+        assets.push(asset);
+      }
+
+      if (isTextLikePath(entry.name)) {
+        if (usedTextBytes >= MAX_PROJECT_TEXT_BYTES) {
+          omitted.push({ path: entry.name, reason: "text byte limit reached" });
+          continue;
+        }
+        const content = decodeUtf8IfText(entryBuffer);
+        if (content === null) {
+          omitted.push({ path: entry.name, reason: "text decode failed" });
+          continue;
+        }
+        usedTextBytes += Buffer.byteLength(content, "utf8");
+        files.push({
+          path: entry.name,
+          localPath: localPath === null ? null : toWorkspaceRelative(options.workspaceDir, localPath),
+          content,
+        });
+      }
+    } catch (error) {
+      omitted.push({
+        path: entry.name,
+        reason: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return {
+    target: options.target,
+    status: "downloaded",
+    bytes: buffer.length,
+    zipPath: zipPath === null ? null : toWorkspaceRelative(options.workspaceDir, zipPath),
+    extractDir: extractDir === null ? null : toWorkspaceRelative(options.workspaceDir, extractDir),
+    extractedFiles,
+    files,
+    assets: assets.map(({ inlineData: _inlineData, ...asset }) => asset),
+    inlineAssets: assets
+      .filter((asset) => asset.inlineData !== undefined)
+      .map((asset) => ({
+        path: asset.path,
+        localPath: asset.localPath,
+        bytes: asset.bytes,
+        mimeType: asset.mimeType,
+        data: asset.inlineData,
+      })),
+    omitted,
+  };
+}
+
+interface ZipEntryMeta {
+  readonly name: string;
+  readonly method: number;
+  readonly compressedSize: number;
+  readonly uncompressedSize: number;
+  readonly localHeaderOffset: number;
+  readonly isDirectory: boolean;
+}
+
+/** Minimal ZIP central-directory reader (store + deflate). No external unzip binary. */
+function listZipEntries(buffer: Buffer): ZipEntryMeta[] {
+  let eocd = -1;
+  const minEocd = Math.max(0, buffer.length - (22 + 0xffff));
+  for (let i = buffer.length - 22; i >= minEocd; i -= 1) {
+    if (buffer.readUInt32LE(i) === 0x06054b50) {
+      eocd = i;
+      break;
+    }
+  }
+  if (eocd < 0) throw new Error("invalid zip: missing end of central directory");
+
+  const totalEntries = buffer.readUInt16LE(eocd + 10);
+  const centralSize = buffer.readUInt32LE(eocd + 12);
+  const centralOffset = buffer.readUInt32LE(eocd + 16);
+  if (centralOffset + centralSize > buffer.length) {
+    throw new Error("invalid zip: central directory out of range");
+  }
+
+  const entries: ZipEntryMeta[] = [];
+  let offset = centralOffset;
+  for (let i = 0; i < totalEntries; i += 1) {
+    if (offset + 46 > buffer.length || buffer.readUInt32LE(offset) !== 0x02014b50) {
+      throw new Error("invalid zip: bad central directory entry");
+    }
+    const method = buffer.readUInt16LE(offset + 10);
+    const compressedSize = buffer.readUInt32LE(offset + 20);
+    const uncompressedSize = buffer.readUInt32LE(offset + 24);
+    const nameLen = buffer.readUInt16LE(offset + 28);
+    const extraLen = buffer.readUInt16LE(offset + 30);
+    const commentLen = buffer.readUInt16LE(offset + 32);
+    const localHeaderOffset = buffer.readUInt32LE(offset + 42);
+    const nameStart = offset + 46;
+    const name = buffer.subarray(nameStart, nameStart + nameLen).toString("utf8");
+    entries.push({
+      name,
+      method,
+      compressedSize,
+      uncompressedSize,
+      localHeaderOffset,
+      isDirectory: name.endsWith("/"),
+    });
+    offset = nameStart + nameLen + extraLen + commentLen;
+  }
+  return entries;
+}
+
+function inflateZipEntry(buffer: Buffer, entry: ZipEntryMeta, maxBytes: number): Buffer {
+  if (entry.uncompressedSize > maxBytes) {
+    throw new Error(`zip entry exceeds ${maxBytes} bytes`);
+  }
+  const local = entry.localHeaderOffset;
+  if (local + 30 > buffer.length || buffer.readUInt32LE(local) !== 0x04034b50) {
+    throw new Error("invalid zip: bad local header");
+  }
+  const nameLen = buffer.readUInt16LE(local + 26);
+  const extraLen = buffer.readUInt16LE(local + 28);
+  const dataStart = local + 30 + nameLen + extraLen;
+  const dataEnd = dataStart + entry.compressedSize;
+  if (dataEnd > buffer.length) throw new Error("invalid zip: compressed data out of range");
+  const compressed = buffer.subarray(dataStart, dataEnd);
+
+  if (entry.method === 0) {
+    if (compressed.length > maxBytes) throw new Error(`zip entry exceeds ${maxBytes} bytes`);
+    return Buffer.from(compressed);
+  }
+  if (entry.method === 8) {
+    return Buffer.from(inflateRawSync(compressed, { maxOutputLength: maxBytes }));
+  }
+  throw new Error(`unsupported zip compression method ${entry.method}`);
+}
+
+
+async function writeUsageFact(
+  prisma: PrismaClient,
+  runId: string,
+  correlationId: string,
+  quantity: number,
+): Promise<void> {
+  const descriptor = CAPABILITIES[PBANK_CAPABILITY_ID];
+  await prisma.usageFact.create({
+    data: {
+      runId,
+      occurredAt: new Date(),
+      kind: "external_capability",
+      provider: PROVIDER_ID,
+      model: null,
+      inputTokens: null,
+      outputTokens: null,
+      quantity,
+      unit: descriptor.meteringUnit,
+      costUsd: null,
+      costSource: "unknown",
+      capabilityId: PBANK_CAPABILITY_ID,
+      correlationId,
+      metadata: {},
+    },
+  });
+}
+
+function toToolResult(data: unknown): PbankToolResult {
+  const inlineImages: Array<{ data: string; mimeType: string }> = [];
+  collectInlineAssets(data, inlineImages);
+  return { data, inlineImages };
+}
+
+function collectInlineAssets(
+  value: unknown,
+  out: Array<{ data: string; mimeType: string }>,
+): void {
+  if (typeof value !== "object" || value === null) return;
+  if (Array.isArray(value)) {
+    for (const item of value) collectInlineAssets(item, out);
+    return;
+  }
+  const record = value as Record<string, unknown>;
+  if (Array.isArray(record.inlineAssets)) {
+    for (const asset of record.inlineAssets) {
+      if (typeof asset !== "object" || asset === null) continue;
+      const item = asset as Record<string, unknown>;
+      if (typeof item.data === "string" && typeof item.mimeType === "string") {
+        out.push({ data: item.data, mimeType: item.mimeType });
+      }
+    }
+    delete record.inlineAssets;
+  }
+  if (record.projects !== undefined) collectInlineAssets(record.projects, out);
+  if (Array.isArray(record.problems)) {
+    for (const problem of record.problems) collectInlineAssets(problem, out);
+  }
+}
+
+function confineToWorkspace(requestedPath: string, workspaceDir: string): string {
+  const resolved = resolve(workspaceDir, requestedPath);
+  const rel = relative(workspaceDir, resolved);
+  if (rel.startsWith("..") || rel === "") {
+    throw new CapabilityPathEscape(requestedPath, workspaceDir);
+  }
+  return resolved;
+}
+
+function toWorkspaceRelative(workspaceDir: string, absolutePath: string): string {
+  const rel = relative(workspaceDir, absolutePath);
+  if (rel.startsWith("..")) {
+    throw new CapabilityPathEscape(absolutePath, workspaceDir);
+  }
+  return rel;
+}
+
+function decodeUtf8IfText(buffer: Buffer): string | null {
+  const text = buffer.toString("utf8");
+  const replacementRatio = (text.match(/\uFFFD/g) ?? []).length / Math.max(text.length, 1);
+  if (replacementRatio > 0.02) return null;
+  return text;
+}
+
+function isZipBuffer(buffer: Buffer, contentType: string): boolean {
+  if (contentType.includes("zip")) return true;
+  return buffer.length >= 4 && buffer[0] === 0x50 && buffer[1] === 0x4b;
+}
+
+function isTextLikePath(filePath: string): boolean {
+  const lower = filePath.toLowerCase();
+  return [".typ", ".md", ".txt", ".tex", ".json", ".yaml", ".yml", ".toml", ".csv"].some((ext) =>
+    lower.endsWith(ext),
+  );
+}
+
+function assetMimeType(filePath: string): string | null {
+  const lower = filePath.toLowerCase();
+  if (lower.endsWith(".png")) return "image/png";
+  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
+  if (lower.endsWith(".gif")) return "image/gif";
+  if (lower.endsWith(".webp")) return "image/webp";
+  if (lower.endsWith(".pdf")) return "application/pdf";
+  return null;
+}
+
+function isInlineImageMime(mimeType: string): boolean {
+  return mimeType.startsWith("image/") && mimeType !== "image/svg+xml";
+}
+
+function safeZipPath(entry: string): boolean {
+  if (entry.includes("\0")) return false;
+  const normalized = entry.replace(/\\/g, "/");
+  if (normalized.startsWith("/") || normalized.includes("://")) return false;
+  for (const part of normalized.split("/")) {
+    if (part === ".." || part === "") return false;
+  }
+  return true;
+}
+
+function safePathSegment(value: string): string {
+  const cleaned = value.replace(/[^a-zA-Z0-9._-]+/g, "_").replace(/^_+|_+$/g, "");
+  if (cleaned === "" || cleaned === "." || cleaned === "..") return "item";
+  return cleaned.slice(0, 80);
+}
+
+function clampInt(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) return min;
+  const n = Math.trunc(value);
+  if (n < min) return min;
+  if (n > max) return max;
+  return n;
+}

hub/src/capability/pbankClient.ts

@@ -0,0 +1,279 @@
+/**
+ * Paradigm PBank (题库) HTTP client.
+ *
+ * Credentials are injected per call from the org capability connection
+ * (ADR-0024/0027) — never read from process env and never passed to the Agent.
+ */
+import type { PbankCapabilitySecretPayload } from "./types.js";
+
+const DEFAULT_BASE_URL = "https://pbank.paradigm-edu.net/api";
+const POSITIVE_RIGHTS_STATUSES = new Set(["owned", "exclusive_license", "licensed_adapt"]);
+
+export interface PbankRights {
+  readonly status: string;
+  readonly holder: string;
+  readonly scope: string;
+  readonly note: string;
+  readonly derivativeUseAllowed: boolean;
+  readonly source: "operator_confirmed";
+}
+
+export interface PbankLoginResult {
+  readonly token: string;
+  readonly expiresAt: number;
+}
+
+export interface PbankSearchInput {
+  readonly q?: string | undefined;
+  readonly keywords?: readonly string[] | undefined;
+  readonly pageNum: number;
+  readonly pageSize: number;
+}
+
+export interface PbankProjectDownload {
+  readonly buffer: Buffer;
+  readonly contentType: string;
+}
+
+export class PbankClientError extends Error {
+  constructor(
+    message: string,
+    readonly code: "pbank_unreachable" | "pbank_rejected" | "pbank_invalid_response",
+    readonly upstreamStatus?: number,
+  ) {
+    super(message);
+    this.name = "PbankClientError";
+  }
+}
+
+export interface PbankClient {
+  login(credential: PbankCapabilitySecretPayload): Promise<PbankLoginResult>;
+  searchProblems(
+    credential: PbankCapabilitySecretPayload,
+    token: string,
+    input: PbankSearchInput,
+  ): Promise<unknown>;
+  getProblem(
+    credential: PbankCapabilitySecretPayload,
+    token: string,
+    id: string,
+  ): Promise<unknown>;
+  getOccurrences(
+    credential: PbankCapabilitySecretPayload,
+    token: string,
+    id: string,
+  ): Promise<unknown>;
+  downloadProject(
+    credential: PbankCapabilitySecretPayload,
+    token: string,
+    id: string,
+    target: "problem" | "answer",
+  ): Promise<PbankProjectDownload>;
+}
+
+export function pbankRightsFromCredential(credential: PbankCapabilitySecretPayload): PbankRights {
+  const status = normalizeRightsStatus(credential.rightsStatus ?? "unknown");
+  const holder = (credential.rightsHolder ?? "").trim() || "Paradigm Education";
+  const scope = (credential.rightsScope ?? "").trim() || "internal teaching-material production";
+  const note =
+    (credential.rightsNote ?? "").trim() ||
+    "All content returned by this capability is operator-confirmed as owned by Paradigm Education or sufficiently licensed for excerpting, rewriting, and adaptation within current teaching-material projects.";
+  return {
+    status,
+    holder,
+    scope,
+    note,
+    derivativeUseAllowed: POSITIVE_RIGHTS_STATUSES.has(status),
+    source: "operator_confirmed",
+  };
+}
+
+export function normalizePbankBaseUrl(value: string | undefined): string {
+  const raw = (value ?? "").trim();
+  if (raw === "") return DEFAULT_BASE_URL;
+  return raw.replace(/\/+$/, "");
+}
+
+export function extractProblemId(value: string): string {
+  const input = value.trim();
+  if (input === "") throw new PbankClientError("urlOrId is required", "pbank_invalid_response");
+
+  const uuidPattern = /[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/i;
+  const direct = input.match(uuidPattern);
+  if (direct !== null) return direct[0]!;
+
+  try {
+    const url = new URL(input);
+    for (const key of ["id", "problemId", "problem_id"] as const) {
+      const fromQuery = url.searchParams.get(key);
+      const match = fromQuery?.match(uuidPattern);
+      if (match !== null && match !== undefined) return match[0]!;
+    }
+  } catch {
+    // Not a URL.
+  }
+
+  throw new PbankClientError(`Could not find a problem UUID in: ${input}`, "pbank_invalid_response");
+}
+
+export class HttpPbankClient implements PbankClient {
+  async login(credential: PbankCapabilitySecretPayload): Promise<PbankLoginResult> {
+    const data = await this.requestJson(credential, "/login", {
+      method: "POST",
+      body: { username: credential.username, password: credential.password },
+      timeoutMs: 30_000,
+    });
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+      throw new PbankClientError("PBank login returned non-object", "pbank_invalid_response");
+    }
+    const record = data as Record<string, unknown>;
+    if (typeof record.token !== "string" || record.token.trim() === "") {
+      throw new PbankClientError("PBank login did not return a token", "pbank_invalid_response");
+    }
+    const expiresAt =
+      typeof record.expiresAt === "number" && Number.isFinite(record.expiresAt)
+        ? record.expiresAt
+        : Date.now() + 30 * 60_000;
+    return { token: record.token, expiresAt };
+  }
+
+  async searchProblems(
+    credential: PbankCapabilitySecretPayload,
+    token: string,
+    input: PbankSearchInput,
+  ): Promise<unknown> {
+    return this.requestJson(credential, "/problem/query", {
+      token,
+      query: {
+        q: input.q,
+        keywords: input.keywords !== undefined && input.keywords.length > 0 ? input.keywords.join(",") : undefined,
+        pageNum: input.pageNum,
+        pageSize: input.pageSize,
+      },
+    });
+  }
+
+  async getProblem(
+    credential: PbankCapabilitySecretPayload,
+    token: string,
+    id: string,
+  ): Promise<unknown> {
+    return this.requestJson(credential, `/problem/${encodeURIComponent(id)}`, { token });
+  }
+
+  async getOccurrences(
+    credential: PbankCapabilitySecretPayload,
+    token: string,
+    id: string,
+  ): Promise<unknown> {
+    return this.requestJson(credential, `/problem/${encodeURIComponent(id)}/occurrence`, {
+      token,
+      query: { pageNum: 1, pageSize: 20 },
+    });
+  }
+
+  async downloadProject(
+    credential: PbankCapabilitySecretPayload,
+    token: string,
+    id: string,
+    target: "problem" | "answer",
+  ): Promise<PbankProjectDownload> {
+    const url = buildUrl(credential.baseUrl, `/problem/${encodeURIComponent(id)}/project/${target}`);
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        headers: { authorization: `Bearer ${token}`, accept: "*/*" },
+        signal: AbortSignal.timeout(120_000),
+      });
+    } catch (error) {
+      throw new PbankClientError(
+        error instanceof Error ? error.message : String(error),
+        "pbank_unreachable",
+      );
+    }
+    if (!response.ok) {
+      throw new PbankClientError(
+        `PBank project download failed: ${response.status}`,
+        response.status === 401 || response.status === 403 ? "pbank_rejected" : "pbank_invalid_response",
+        response.status,
+      );
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    const arrayBuffer = await response.arrayBuffer();
+    return { buffer: Buffer.from(arrayBuffer), contentType };
+  }
+
+  private async requestJson(
+    credential: PbankCapabilitySecretPayload,
+    route: string,
+    options: {
+      readonly method?: string;
+      readonly token?: string;
+      readonly body?: unknown;
+      readonly query?: Record<string, string | number | undefined>;
+      readonly timeoutMs?: number;
+    },
+  ): Promise<unknown> {
+    const url = buildUrl(credential.baseUrl, route, options.query);
+    const headers: Record<string, string> = { accept: "application/json" };
+    if (options.token !== undefined) headers.authorization = `Bearer ${options.token}`;
+    if (options.body !== undefined) headers["content-type"] = "application/json";
+
+    const init: RequestInit = {
+      method: options.method ?? "GET",
+      headers,
+      signal: AbortSignal.timeout(options.timeoutMs ?? 30_000),
+    };
+    if (options.body !== undefined) init.body = JSON.stringify(options.body);
+
+    let response: Response;
+    try {
+      response = await fetch(url, init);
+    } catch (error) {
+      throw new PbankClientError(
+        error instanceof Error ? error.message : String(error),
+        "pbank_unreachable",
+      );
+    }
+    const data = await response.json().catch(() => null);
+    if (!response.ok) {
+      throw new PbankClientError(
+        extractErrorMessage(data, `PBank API request failed: ${response.status}`),
+        response.status === 401 || response.status === 403 ? "pbank_rejected" : "pbank_invalid_response",
+        response.status,
+      );
+    }
+    return data;
+  }
+}
+
+function buildUrl(
+  baseUrl: string,
+  route: string,
+  query?: Record<string, string | number | undefined>,
+): string {
+  const url = new URL(route.replace(/^\/+/, ""), `${normalizePbankBaseUrl(baseUrl)}/`);
+  if (query !== undefined) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === undefined || value === "") continue;
+      url.searchParams.set(key, String(value));
+    }
+  }
+  return url.toString();
+}
+
+function extractErrorMessage(data: unknown, fallback: string): string {
+  if (typeof data === "object" && data !== null) {
+    const record = data as Record<string, unknown>;
+    if (typeof record.message === "string" && record.message !== "") return record.message;
+    if (typeof record.error === "string" && record.error !== "") return record.error;
+  }
+  if (typeof data === "string" && data !== "") return data;
+  return fallback;
+}
+
+function normalizeRightsStatus(value: string): string {
+  const normalized = value.trim().toLowerCase().replace(/[\s-]+/g, "_");
+  if (normalized === "") return "unknown";
+  return normalized;
+}

hub/src/capability/pdfToMdBundle.ts

@@ -23,6 +23,7 @@ import { resolveCapabilityCredential } from "./capabilityConnections.js";
 import { DocmindClientError, type CapabilityProviderClient } from "./docmindClient.js";
 import {
   CAPABILITIES,
+  asDocmindSecret,
   type CapabilityAdapter,
   type CapabilityInvocationInput,
   type CapabilityInvocationResult,
@@ -63,6 +64,135 @@ export interface PdfToMdBundleDeps {
   readonly prisma: PrismaClient;
 }
 
+/** Default max concurrent Docmind jobs for one convert_pdf_to_md batch call. */
+export const DEFAULT_PDF_TO_MD_CONCURRENCY = 3;
+/** Hard ceiling for agent-requested concurrency (also clamps env). */
+export const MAX_PDF_TO_MD_CONCURRENCY = 8;
+/** Max PDFs accepted in one batch tool call. */
+export const MAX_PDF_TO_MD_BATCH_ITEMS = 32;
+
+export function clampPdfToMdConcurrency(value: number): number {
+  if (!Number.isFinite(value)) return DEFAULT_PDF_TO_MD_CONCURRENCY;
+  const n = Math.trunc(value);
+  if (n < 1) return 1;
+  if (n > MAX_PDF_TO_MD_CONCURRENCY) return MAX_PDF_TO_MD_CONCURRENCY;
+  return n;
+}
+
+/** Read HUB_PDF_TO_MD_MAX_CONCURRENT (default 3, max 8). */
+export function readPdfToMdConcurrency(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): number {
+  const raw = env["HUB_PDF_TO_MD_MAX_CONCURRENT"]?.trim();
+  if (raw === undefined || raw === "") return DEFAULT_PDF_TO_MD_CONCURRENCY;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 1) {
+    throw new Error(`HUB_PDF_TO_MD_MAX_CONCURRENT must be a positive integer, got ${raw}`);
+  }
+  return clampPdfToMdConcurrency(parsed);
+}
+
+export interface PdfToMdBatchItem {
+  readonly inputPath: string;
+  readonly outputDir: string;
+}
+
+export type PdfToMdBatchItemResult =
+  | {
+      readonly ok: true;
+      readonly inputPath: string;
+      readonly outputDir: string;
+      readonly result: CapabilityInvocationResult;
+    }
+  | {
+      readonly ok: false;
+      readonly inputPath: string;
+      readonly outputDir: string;
+      readonly error: string;
+    };
+
+/**
+ * Run worker over items with bounded parallelism. Order of results matches
+ * input order. Rejects in worker are not swallowed — caller should catch.
+ */
+export async function mapPool<T, R>(
+  items: readonly T[],
+  concurrency: number,
+  worker: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  if (items.length === 0) return [];
+  const limit = Math.max(1, Math.min(Math.trunc(concurrency), items.length));
+  const results = new Array<R>(items.length);
+  let next = 0;
+  async function runWorker(): Promise<void> {
+    for (;;) {
+      const index = next;
+      next += 1;
+      if (index >= items.length) return;
+      results[index] = await worker(items[index]!, index);
+    }
+  }
+  await Promise.all(Array.from({ length: limit }, () => runWorker()));
+  return results;
+}
+
+/**
+ * Convert multiple PDFs with bounded concurrency. Each item is attribute-
+ * independent (own paths + own UsageFact). Failures are per-item and do not
+ * cancel siblings; order matches `items`.
+ */
+export async function invokePdfToMdBatch(
+  adapter: CapabilityAdapter,
+  base: Omit<CapabilityInvocationInput, "inputPath" | "outputDir">,
+  items: readonly PdfToMdBatchItem[],
+  concurrency: number = DEFAULT_PDF_TO_MD_CONCURRENCY,
+): Promise<PdfToMdBatchItemResult[]> {
+  if (items.length === 0) {
+    throw new Error("pdf_to_md batch requires at least one item");
+  }
+  if (items.length > MAX_PDF_TO_MD_BATCH_ITEMS) {
+    throw new Error(
+      `pdf_to_md batch supports at most ${MAX_PDF_TO_MD_BATCH_ITEMS} items per call (got ${items.length})`,
+    );
+  }
+  const seenOutputDirs = new Set<string>();
+  for (const item of items) {
+    if (item.inputPath.trim() === "" || item.outputDir.trim() === "") {
+      throw new Error("pdf_to_md batch items require non-empty inputPath and outputDir");
+    }
+    const key = item.outputDir.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (seenOutputDirs.has(key)) {
+      throw new Error(
+        `pdf_to_md batch items must use distinct output_dir values; duplicate: ${item.outputDir}`,
+      );
+    }
+    seenOutputDirs.add(key);
+  }
+  const limit = clampPdfToMdConcurrency(concurrency);
+  return mapPool(items, limit, async (item) => {
+    try {
+      const result = await adapter.invoke({
+        ...base,
+        inputPath: item.inputPath,
+        outputDir: item.outputDir,
+      });
+      return {
+        ok: true as const,
+        inputPath: item.inputPath,
+        outputDir: item.outputDir,
+        result,
+      };
+    } catch (error) {
+      return {
+        ok: false as const,
+        inputPath: item.inputPath,
+        outputDir: item.outputDir,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  });
+}
+
 /** Build the pdf_to_md_bundle adapter. The client is injectable for testing. */
 export function createPdfToMdBundleAdapter(deps: PdfToMdBundleDeps): CapabilityAdapter {
   return {
@@ -83,7 +213,7 @@ export function createPdfToMdBundleAdapter(deps: PdfToMdBundleDeps): CapabilityA
       // 3. Call the backing service.
       let result;
       try {
-        result = await deps.client.parse(credential, { inputFilePath: absoluteInput });
+        result = await deps.client.parse(asDocmindSecret(credential), { inputFilePath: absoluteInput });
       } catch (e) {
         if (e instanceof DocmindClientError) throw e;
         throw new DocmindClientError(

hub/src/capability/types.ts

@@ -1,11 +1,11 @@
 /**
  * ADR-0027: External capability types shared across the adapter layer.
  *
- * A capability is a platform-registered, org-enabled document/media transform
+ * A capability is a platform-registered, org-enabled external service
  * invoked as a side effect of an AgentRun. The adapter resolves the org's
  * active capability connection, calls the backing service via an injectable
- * client, writes output into the run's workspace (AgentSurface, ADR-0018),
- * and records consumption on a UsageFact (ADR-0026).
+ * client, writes output into the run's workspace when applicable (AgentSurface,
+ * ADR-0018), and records consumption on a UsageFact (ADR-0026).
  */
 import type { PrismaClient, Prisma } from "@prisma/client";
 
@@ -13,6 +13,7 @@ import type { PrismaClient, Prisma } from "@prisma/client";
 export const CAPABILITY_IDS = [
   "pdf_to_md_bundle",
   "audio_video_to_text",
+  "pbank",
 ] as const;
 
 export type CapabilityId = (typeof CAPABILITY_IDS)[number];
@@ -27,6 +28,7 @@ export interface CapabilityDescriptor {
 export const CAPABILITIES: Readonly<Record<CapabilityId, CapabilityDescriptor>> = {
   pdf_to_md_bundle: { id: "pdf_to_md_bundle", meteringUnit: "pages" },
   audio_video_to_text: { id: "audio_video_to_text", meteringUnit: "audio_seconds" },
+  pbank: { id: "pbank", meteringUnit: "requests" },
 };
 
 /** Input passed to a capability adapter invocation. */
@@ -59,7 +61,7 @@ export interface CapabilityConsumption {
   readonly model: string | null;
   readonly inputTokens: number | null;
   readonly outputTokens: number | null;
-  /** Non-token meter (page count, audio seconds). */
+  /** Non-token meter (page count, audio seconds, request count). */
   readonly quantity: number;
   readonly unit: string;
   /** USD cost if the service reported one; null = unknown (ADR-0022). */
@@ -80,15 +82,39 @@ export interface CapabilityAdapter {
   invoke(input: CapabilityInvocationInput): Promise<CapabilityInvocationResult>;
 }
 
-/** Decrypted capability credential (CapabilitySecretPayloadV1, ADR-0027).
- * Alibaba Cloud Document Mind (docmind) uses AccessKey ID + Secret + endpoint. */
-export interface CapabilitySecretPayload {
+/** Alibaba Cloud Document Mind (docmind) AccessKey + endpoint. */
+export interface DocmindCapabilitySecretPayload {
   readonly schemaVersion: 1;
+  readonly kind: "docmind";
   readonly accessKeyId: string;
   readonly accessKeySecret: string;
   readonly endpoint: string;
 }
 
+/**
+ * Paradigm PBank (题库) login credentials.
+ * Rights fields are operator-confirmed license signals echoed to the agent;
+ * the credential secret itself never reaches the agent process (ADR-0024/0027).
+ */
+export interface PbankCapabilitySecretPayload {
+  readonly schemaVersion: 1;
+  readonly kind: "pbank";
+  readonly baseUrl: string;
+  readonly username: string;
+  readonly password: string;
+  readonly rightsStatus?: string;
+  readonly rightsHolder?: string;
+  readonly rightsScope?: string;
+  readonly rightsNote?: string;
+}
+
+/**
+ * Decrypted capability credential (CapabilitySecretPayloadV1, ADR-0027).
+ * Discriminated by `kind`. Legacy envelopes without `kind` are normalized to
+ * `docmind` when accessKey fields are present.
+ */
+export type CapabilitySecretPayload = DocmindCapabilitySecretPayload | PbankCapabilitySecretPayload;
+
 /** Thrown when an org has no ACTIVE capability connection (fail-closed, ADR-0024). */
 export class CapabilityConnectionUnavailable extends Error {
   constructor(readonly capabilityId: string, readonly organizationId: string) {
@@ -99,3 +125,93 @@ export class CapabilityConnectionUnavailable extends Error {
 
 /** Prisma transaction client type alias (for resolver signatures). */
 export type TxClient = Prisma.TransactionClient;
+
+/** Map capability id → expected secret kind. */
+export function secretKindForCapability(capabilityId: string): "docmind" | "pbank" {
+  switch (capabilityId) {
+    case "pdf_to_md_bundle":
+    case "audio_video_to_text":
+      return "docmind";
+    case "pbank":
+      return "pbank";
+    default:
+      throw new Error(`unsupported capabilityId: ${capabilityId}`);
+  }
+}
+
+/**
+ * Normalize a decrypted envelope payload into a full CapabilitySecretPayload.
+ * Accepts legacy docmind payloads that omit `kind`.
+ */
+export function normalizeCapabilitySecretPayload(raw: unknown): CapabilitySecretPayload {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error("invalid capability secret payload");
+  }
+  const payload = raw as Record<string, unknown>;
+  if (payload.schemaVersion !== 1) {
+    throw new Error(`unsupported capability secret schemaVersion: ${String(payload.schemaVersion)}`);
+  }
+
+  const kind =
+    payload.kind === "pbank" || payload.kind === "docmind"
+      ? payload.kind
+      : typeof payload.accessKeyId === "string"
+        ? "docmind"
+        : typeof payload.username === "string"
+          ? "pbank"
+          : null;
+  if (kind === null) throw new Error("capability secret payload missing kind");
+
+  if (kind === "docmind") {
+    return {
+      schemaVersion: 1,
+      kind: "docmind",
+      accessKeyId: requireString(payload.accessKeyId, "accessKeyId"),
+      accessKeySecret: requireString(payload.accessKeySecret, "accessKeySecret"),
+      endpoint: requireString(payload.endpoint, "endpoint"),
+    };
+  }
+
+  const rightsStatus = optionalString(payload.rightsStatus);
+  const rightsHolder = optionalString(payload.rightsHolder);
+  const rightsScope = optionalString(payload.rightsScope);
+  const rightsNote = optionalString(payload.rightsNote);
+  return {
+    schemaVersion: 1,
+    kind: "pbank",
+    baseUrl: requireString(payload.baseUrl, "baseUrl"),
+    username: requireString(payload.username, "username"),
+    password: requireString(payload.password, "password"),
+    ...(rightsStatus !== undefined ? { rightsStatus } : {}),
+    ...(rightsHolder !== undefined ? { rightsHolder } : {}),
+    ...(rightsScope !== undefined ? { rightsScope } : {}),
+    ...(rightsNote !== undefined ? { rightsNote } : {}),
+  };
+}
+
+export function asDocmindSecret(payload: CapabilitySecretPayload): DocmindCapabilitySecretPayload {
+  if (payload.kind !== "docmind") {
+    throw new Error(`expected docmind capability secret, got ${payload.kind}`);
+  }
+  return payload;
+}
+
+export function asPbankSecret(payload: CapabilitySecretPayload): PbankCapabilitySecretPayload {
+  if (payload.kind !== "pbank") {
+    throw new Error(`expected pbank capability secret, got ${payload.kind}`);
+  }
+  return payload;
+}
+
+function requireString(value: unknown, label: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${label} must not be empty`);
+  }
+  return value.trim();
+}
+
+function optionalString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed === "" ? undefined : trimmed;
+}

hub/src/database/README.md

@@ -1,157 +0,0 @@
-# src/database/
-
-`/database/*` HTTP 面。代码写在这个目录里，`hub.ts` 通过 `plugin.ts` 挂载它，
-所以服务器启动时能正确识别这些路由。
-
-**前后端分离**：页面全部在 SvelteKit 静态 SPA `hub/filelib-web/`（与 `hub/admin-web/`
-同一套框架）。**老师端 `/app` 与管理后台 `/database` 共用这一份工程和这一份构建产物** ——
-两个挂载前缀，一个 SPA。本目录的后端只保留三件事：鉴权透传、JSON 数据端点、
-以及把构建产物托管出去。服务端不渲染任何 HTML。
-
-后端路由：
-
-- `GET /database/config` —— 免鉴权。返回 `{ orgSlug, devLoginEnabled }`，
-  给 SPA 登录页拼飞书链接、决定是否显示 dev 按钮用。不含任何敏感数据。
-  （`/database/api/login-info` 是同形状的既有端点，由 `routes/teacherApp.ts` 注册。）
-- `GET /database/api/stats` —— 概览页统计。需登录 **且** 是 silo org OWNER/ADMIN。
-- `GET /database/dev-login` —— 仅开发。见下。
-- `GET /database`、`GET /database/*`、`GET /app`、`GET /app/*` —— SPA shell /
-  客户端路由 fallback（`static.ts` 的 `registerDatabaseSpa`）。
-- `GET /_filelib/*` —— 构建产物资源。SvelteKit 的 `appDir` 改名为 `_filelib`，
-  以避开 `admin-web` 在根上注册的 `/_app/*`（同名会让 Fastify 启动即抛重复路由）。
-
-SPA 页面（`filelib-web`，真 URL 路由、无 hash）：
-
-- `/app` —— 老师端文件库。未登录显示登录卡片。
-- `/database/admin` —— 管理员飞书登录页。按钮指向 `/auth/feishu/<orgSlug>`，
-  回调由 `src/admin/routes/authRoutes.ts` 处理并种 session cookie。
-- `/database/dashboard` —— 后台外壳（侧栏 + 权限门）。未登录跳登录页；
-  **登录但非 OWNER/ADMIN 显示无权提示**。六个 tab 都是子路由：
-  `/database/dashboard`（概览）、`/library`、`/users`、`/groups`、`/search`、`/settings`。
-
-> **注册顺序要点**：concrete 路由（`/database/config`、`/database/api/*`、
-> `/database/dev-login`、`/app/dev-login-teacher`）必须在 `registerDatabaseSpa` 的
-> `/database/*`、`/app/*` fallback 之前注册（已在 `plugin.ts` 保证），
-> 否则通配会 shadow 它们。
-
-## 开发模式：用环境变量开启一键登录
-
-本地开发没有真实飞书 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/config` 返回 `devLoginEnabled: true`，SPA 登录页据此显示
-  「⚡ 一键登录管理员」按钮
-- 后端注册 `/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` | `/database/config`、`/database/api/stats`、dev 旁路 + 各子路由装配点 |
-| `routes/filelibRoutes.ts` | 文件库 树/授权 API |
-| `routes/fileRoutes.ts` | 文件库 文件内容/导出 API |
-| `routes/memberGroupRoutes.ts` | 成员组管理 API + `/groups/search` + `/users/search`(ADR-0028) |
-| `routes/teacherApp.ts` | `/database/api/login-info` + 老师端 DEV 一键登录 |
-| `static.ts` | filelib-web 构建产物托管：`/_filelib/*` 资源 + `/app`、`/database` 两个 SPA 回退 |
-| `filelib/` | 文件库领域层(见下) |
-
-新增一类**数据**端点时：要么直接往 `databaseRoutes.ts` 加 `app.get("/database/api/...")`，
-要么新建 `routes/xxxRoutes.ts` 并在 `databaseRoutes.ts` 里 `registerXxxRoutes(app, {...})`
-注册一次。**不要在后端拼 HTML** —— 页面一律加在 `hub/filelib-web/src/routes/` 下。
-
-## 文件库(filelib/)
-
-独立文件库模块。代码注释里的 C/D 编号(契约 8.1、C2、C4、D11–D19 等)
-出自两份已删除的文档:《文件库-接口契约.md》与 `.omo/文件库-开工计划.md`,
-内容可从 git 历史取回。其中 D19(网站管理员 = silo org OWNER/ADMIN)
-另见 ADR-0028。**与 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 过渡实现,ADR-0028) |
-| `filelib/memberGroupResolver.ts` | **默认** C2 实现:读 in-hub MemberGroup 闭包(ADR-0028) |
-| `filelib/memberGroupService.ts` | 成员组 CRUD(含改名)+ 成员增删 + 闭包维护 + 搜索(ADR-0028) |
-| `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);**未配置时读 in-hub
-  MemberGroup 闭包**(ADR-0028 起的默认;此前是扁平 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

@@ -1,79 +0,0 @@
-/**
- * 文件库审计 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",
-  // ADR-0028:成员组内置进 hub,组动作在本地审计(契约 C3 §6.3 原委托外部 Group 服务)。
-  groupCreate: "group.create",
-  groupUpdate: "group.update",
-  groupDelete: "group.delete",
-  groupRestore: "group.restore",
-  groupMemberAdd: "group.member_add",
-  groupMemberRemove: "group.member_remove",
-} as const;
-
-export type FileLibAuditObjectType = "folder" | "project" | "file" | "grant" | "export_job" | "group";
-
-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

@@ -1,195 +0,0 @@
-/**
- * 导出(契约 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,
-  };
-}