@james_sww/metaform-asset-distribution 0.1.0 → 0.1.2

package/README.md

@@ -1,13 +1,15 @@
 # Metaform 源码资产分发（P1）
 
-这个包提供源码资产 CLI，并携带独立 `@james_sww/metaform-codebase-template` 的版本快照。基础模板唯一维护源已迁到桌面 `metaform-codebase/`，包含 RoleWorkspaceShell、设计系统原语、完整主题与语义骨架。业务组件按需复制，源码归应用维护；生成工程不依赖 Metaform workspace 或该 CLI 才能运行。
+这个包提供源码资产 CLI，并携带独立 `@james_sww/metaform-codebase-template` 的版本快照。基础模板工程与外壳维护源是独立 `metaform-codebase/`；其中基础 UI、主题和语义骨架按明确来源派生，不建立第二份人工维护源。业务组件按需复制，源码归应用维护；生成工程不依赖 Metaform workspace 或该 CLI 才能运行。
+
+本版为 `0.1.2`，包含独立资产库迁移与模板侧栏、间距和 cobalt 默认主题更新。资产源码及 CLI 已独立迁入 `metaform-asset-library`；本轮仅分发两个岗位任务组件、语义骨架及真实依赖，外壳随模板交付。
 
 ## npm 使用与沙箱接入
 
 发布版本使用 Node 24.18.0、pnpm 10.18.2。CLI 自带固定版本模板与源码 Registry，无需平台仓库或本机桌面目录。私有包需有下载权限；沙箱凭据由运行环境注入，不写入应用源码。
 
 ```sh
-npm install -g @james_sww/metaform-asset-distribution@0.1.0
+npm install -g @james_sww/metaform-asset-distribution@0.1.2
 metaform-assets init --project ./my-app
 cd my-app
 corepack pnpm install --frozen-lockfile
@@ -16,7 +18,7 @@ corepack pnpm install --frozen-lockfile
 不安装全局工具也可运行：
 
 ```sh
-npm exec --yes --package=@james_sww/metaform-asset-distribution@0.1.0 -- metaform-assets init --project ./my-app
+npm exec --yes --package=@james_sww/metaform-asset-distribution@0.1.2 -- metaform-assets init --project ./my-app
 ```
 
 Agent 根据应用本体和 skill 形成 `ApplicationDesign` JSON 后，在已初始化的应用目录执行：
@@ -31,11 +33,11 @@ corepack pnpm dev
 
 CLI 负责按底稿确定性装配；读取线上本体并作语义转译由 Agent 完成。匹配组件安装为应用内源码，未匹配区域保留语义骨架。模板初始化、安装成功不代表真实业务数据已绑定或平台 S7 已自动接通。
 
-基础模板也单独按 `@james_sww/metaform-codebase-template@0.1.0` 分发，可安装到工具目录后用 `--codebase /path/to/node_modules/@james_sww/metaform-codebase-template` 指定。初始化底稿的完整类型随 CLI 发布在 `dist/application-design.d.ts`，语义区域类型在 `dist/generated/semantic-region-contract.d.ts`。固定 CLI、模板和 Registry 版本用于沙箱重放；初始化后的源码和基线存入项目快照。
+基础模板也单独按 `@james_sww/metaform-codebase-template@0.1.2` 分发，可安装到工具目录后用 `--codebase /path/to/node_modules/@james_sww/metaform-codebase-template` 指定。初始化底稿的完整类型随 CLI 发布在 `dist/application-design.d.ts`，语义区域类型在 `dist/generated/semantic-region-contract.d.ts`。固定 CLI、模板和 Registry 版本用于沙箱重放；初始化后的源码和基线存入项目快照。
 
 ## 维护仓库
 
-在 frontend 目录使用 pnpm 10.18.2：
+在独立 `metaform-asset-library` 根目录使用 pnpm 10.18.2：
 
 ```sh
 corepack pnpm --filter @james_sww/metaform-asset-distribution test
@@ -45,7 +47,7 @@ corepack pnpm --filter @james_sww/metaform-asset-distribution pack --pack-destin
 corepack pnpm --filter @james_sww/metaform-asset-distribution test:standalone
 ```
 
-pack 前从独立基础模板包生成 `codebase/` 快照，再生成 CLI 和资产发布快照。`codebase-source.json` 固定模板名称、版本及本地来源；可用 `METAFORM_CODEBASE_SOURCE` 指向其他包目录（包括已安装或解压的 npm 包）。修改模板后先在模板包运行 `npm run seal`。CLI 发行包不依赖桌面路径。`prepare:release` 只写本地 registry 目录，不发布在线服务。默认 Registry URL 是本机验收地址；正式托管前显式设置 `METAFORM_REGISTRY_BASE=https://...`。每个 release 目录以完整内容摘要命名；同摘要的条目、依赖 URL 和 Catalog 不可改写。更换部署 URL 时使用新的输出目录，不能覆盖已发布版本。
+pack 前从独立基础模板包生成 `codebase/` 快照，再生成 CLI 和资产发布快照。`codebase-source.json` 固定模板名称、版本、清单摘要及库内快照来源。更新上游时按根目录 README 显式刷新固定来源；可用 `METAFORM_CODEBASE_SOURCE` 指向其他包目录（包括已安装或解压的 npm 包）。修改模板后先在模板包运行 `npm run seal`。CLI 发行包不依赖桌面路径。`prepare:release` 只写本地 registry 目录，不发布在线服务。默认 Registry URL 是本机验收地址；正式托管前显式设置 `METAFORM_REGISTRY_BASE=https://...`。每个 release 目录以完整内容摘要命名；同摘要的条目、依赖 URL 和 Catalog 不可改写。更换部署 URL 时使用新的输出目录，不能覆盖已发布版本。
 
 `registry/<digest>/registry.json`、`r/*.json` 遵守 shadcn Registry schema；`release.json` 是 Metaform 的原始字节和来源 sidecar。schema 校验 fixture 来自 [官方 registry-item schema](https://ui.shadcn.com/schema/registry-item.json)，2026-10-17 固定入库。Catalog 分开保留 component 与 asset 两种粒度，候选不会自动变成推荐。可发现但不在首批源码范围内的条目显示 `installable: false`。
 

package/codebase/codebase.json

@@ -1,10 +1,10 @@
 {
   "schemaVersion": 1,
   "name": "@james_sww/metaform-codebase-template",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "files": {
     "_gitignore": "184ad45835c68a6d3fd5100366678797c5fe4d2a2aa6548749039912376faf54",
-    ".env.example": "5c15c4f0187d52019398f42ced14c7e6d54211ddb554c2142c4b8a9d250573c0",
+    ".env.example": "602ae0c89a09593ef560b5d1f7010439e228c7fb0dd7bbc69c9655cf82a8944f",
     ".metaform/asset-baselines/0551d7ee067550cd2757cf693414c5e180adbb5efe3af4f5f9b1242aa9cd788e": "0551d7ee067550cd2757cf693414c5e180adbb5efe3af4f5f9b1242aa9cd788e",
     ".metaform/asset-baselines/0e7bb494140c2c4118b919496a4246b26935367453282bd654fedecd2b16f1a5": "0e7bb494140c2c4118b919496a4246b26935367453282bd654fedecd2b16f1a5",
     ".metaform/asset-baselines/3d1a9a8a1f7ed83eaf3422d1497cac02b643fe1c470b5c5f357f3bd26c585a0f": "3d1a9a8a1f7ed83eaf3422d1497cac02b643fe1c470b5c5f357f3bd26c585a0f",
@@ -23,20 +23,22 @@
     ".metaform/asset-baselines/e9d4784c2ad5bceccdc4f2f19f367fdc37537a10e3f99f510e42c0226adfbf8f": "e9d4784c2ad5bceccdc4f2f19f367fdc37537a10e3f99f510e42c0226adfbf8f",
     ".metaform/asset-baselines/f3ce568d1ede383d9cb0d11dcc2acb6ce7984cbef8e2db0feec310df76303ccd": "f3ce568d1ede383d9cb0d11dcc2acb6ce7984cbef8e2db0feec310df76303ccd",
     ".metaform/asset-baselines/fc763d53079b51a789c1cfff23d40e00f844a9a093a2ad112f0ac68ab46fe080": "fc763d53079b51a789c1cfff23d40e00f844a9a093a2ad112f0ac68ab46fe080",
+    ".metaform/template-overrides.json": "4c9c16d05caf34c4ee4c76fd296c3cc94a07a1fa1db2b8c8ec1ff9af28115722",
     "application.json": "832c19243f16e38c7a6e100e995675d995537ea0d53da7df9cc1b239782b3ca0",
     "assets.lock.json": "cad385719b1d3b2ccbb56343ca5305d862b813a1e0013d2c12c827423ca47db4",
     "components.json": "bf8e563e20f684aad29b2b7671b3327effd62dc2cb3bd944fcd1ccb7d581217e",
     "eslint.config.js": "05a1c2fbaca8ec2c04985ca14e7da9ecf7b6722a5d9e27313e814de4b0393ccd",
-    "index.html": "0c8ce9649128d2ebbe282b1eee040524b78896b9df13f3ca1481c3965f66b823",
+    "index.html": "b0615e4fc6fdf82a768f44c818b3bf280897882ffc72c949c8a3ab5cd78ca37b",
     "LICENSES/NOTICE.md": "dc2bd63b6bcdf6007dcc823ae145828ae0fc3ff2768950a2899e752c1016e0b2",
     "package.json": "7b256b3982d5683f6279e75ee86280498b7ef444a4262158f8d622f77361f64f",
     "pnpm-lock.yaml": "46912c695ef4a2f351a7469aa26ab1312ccf6347b4d0aa2b075bf3a96632782b",
     "README.md": "d738a1bfbe9e9221f15e2bdcb46af9fae112afd0c1354bd9d45bdf3ae5205e38",
     "role-targets.json": "37517e5f3dc66819f61f5a7bb8ace1921282415f10551d2defa5c3eb0985b570",
-    "src/components/common/error-boundary.tsx": "990d7a72a5634dc854f3acbe9b9d4aac8f13540ca0901be8dbc2f27d77a76f3e",
+    "src/components/common/empty-state.tsx": "6008a3193b715c5453eee3dba6ee20608fca3e6cf8bba9af774ba898a1890fea",
+    "src/components/common/error-boundary.tsx": "1fef1c92e27d8206448cb0e1840bfe81826a95fc58b1ec4c1e2f14462293bf5b",
     "src/components/common/semantic-region/contract.ts": "92cd18a919b549b4827f611c3a4157652c4a6ae034850da1254ca422693c759d",
     "src/components/common/semantic-region/semantic-region-scaffold.tsx": "567f039384fb23a20a4cd5e1d4fda56255abda6fc04d80b36c4bb6f6c040691b",
-    "src/components/ui/alert.tsx": "d03dcae5cdb63c381c1144ca9a0c49ba0e46466967d7deb94662034042acb034",
+    "src/components/ui/alert.tsx": "9c380bb1703ba96fe873d5b3094153fa3402d305719e60aa733e4ab202ffddaa",
     "src/components/ui/avatar.tsx": "e9d4784c2ad5bceccdc4f2f19f367fdc37537a10e3f99f510e42c0226adfbf8f",
     "src/components/ui/badge.tsx": "bf9e1bbb252c1fa5da20a17eeee1ac163c7d3a0b6deff817d30ba04b766fb8a1",
     "src/components/ui/breadcrumb.tsx": "c75fcd3d9e8470188bc0dd4b27a2b26fff3ad42b9c9c534a953dc090ae2cba33",
@@ -59,20 +61,20 @@
     "src/components/ui/tabs.tsx": "e1df6e2f95ece373ca909c1d54b8ba8cf4c47dd425c1784bbb9a01c38dd0936b",
     "src/components/ui/tooltip.tsx": "5f56cd15afc07567f7b80b8b4d9e89da405e070a562583bbbc2414fd981af324",
     "src/contexts/toast-context.tsx": "a3af91f8915d7753ef15888997ba941d07459d4df3e3e6d58e25365143bf336f",
-    "src/hooks/index.ts": "31e5708e471dbeb44413632535b8f846686de9be28c8ad18e2d930761de8b73b",
-    "src/integrations/platform.ts": "2deb59e0f2938342cb66600b7310da0a67f8754ed291330a18034e819b448c4e",
+    "src/hooks/index.ts": "ddfe80f0fc8b0b49c0b31f27d9aadc4a54715b5ccee40996a205ecec36958b79",
+    "src/integrations/platform.ts": "6edb9755c91f6bf1f16815911739f64c4f45405948eaf0d7bbd5cd2fa939dbe9",
     "src/layouts/role-workspace-account.tsx": "3d1a9a8a1f7ed83eaf3422d1497cac02b643fe1c470b5c5f357f3bd26c585a0f",
     "src/layouts/role-workspace-icons.tsx": "4b8ea69ef28a9699c0c3b28e12590a7521f91aa1a4a3d618fc0778455d39cbcc",
     "src/layouts/role-workspace-routes.ts": "0551d7ee067550cd2757cf693414c5e180adbb5efe3af4f5f9b1242aa9cd788e",
-    "src/layouts/role-workspace-shell.tsx": "bcc48c05cd912dad5373242ff699cdbec032c8ebb2de45a9df5de79a6daec59c",
+    "src/layouts/role-workspace-shell.tsx": "ab0c50c655d759643c77f634337b070807a601580f554796f50284f87c8fd100",
     "src/layouts/role-workspace-types.ts": "b9e31158082ce71a2b3bdb904d9462619e3690735e73e138b1ce57f8f036347f",
-    "src/lib/http-client.ts": "da19f0a16d8be3672573346d59c7242aa87440fc8b97b68a35867291f4da6af7",
+    "src/lib/http-client.ts": "a284532dd0bcc18aaf444b92e883ec77750515c1ba01626d8fa96c3e540d2e37",
     "src/lib/utils.ts": "4acbc7165a8d54738ff62b51414e772c08fe78434e524e6d8770180d3ba2925f",
-    "src/main.tsx": "60221d67b63e9e685f2669f8deea9e4e56d5f285ea248d399e87fa69134b191f",
+    "src/main.tsx": "6fa2b2eb510ef94ca04b894c573a041419191f6896043f227eb160ab49bd6efa",
     "src/styles/index.css": "72f8f255c56d117bab6f2aaa53ce5a37aa9b2d5d085b321b9fcb4b4b983e15eb",
     "src/styles/styles.css": "b48c73f51ff3e148f20ad2c9dbd2847235e4fdf1cdb304d5e2feec9c2febd65e",
     "src/styles/theme-tokens.css": "0e7bb494140c2c4118b919496a4246b26935367453282bd654fedecd2b16f1a5",
-    "src/workspace/default-workspace.tsx": "0239a9926ab2bc6aa6a0c4923a1af03d618bc245483b114c74b017a4a2051737",
+    "src/workspace/default-workspace.tsx": "083313a2e0d61e5eb7f2ee1c2d4dda3243bfdce6204249df85fef7acd751f19d",
     "src/workspace/routes.ts": "94275cc4d44abcfa672e7d56ac1abc7ecd9f5caf656aa54d3e3ef68eaa7e2085",
     "tests/workspace.test.mjs": "daf930b4db33de45eeecf8431663540ecd54aa90c3ba3dd1e683b539cbb8bf5d",
     "tooling/contracts.d.ts": "9ce9d9ac8e59c11c89aa41881b6e8d6edfc84fb4da115970b9f4a2c1e7486ba8",

package/codebase/template/.env.example

@@ -1 +1,11 @@
-# 在打造前完成基础能力接入设计后填写；默认不配置业务服务地址。
+# 应用配置
+VITE_APP_TITLE=Metaform 应用
+
+# API 配置
+VITE_API_BASE_URL=/api
+
+# 开发模式配置
+VITE_USE_MOCK_API=true
+
+# 环境标识
+VITE_ENV=development

package/codebase/template/.metaform/template-overrides.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 1,
+  "previousTemplateVersion": "0.1.1",
+  "files": {
+    "index.html": {
+      "previousTemplateSha256": "0c8ce9649128d2ebbe282b1eee040524b78896b9df13f3ca1481c3965f66b823",
+      "currentSha256": "b0615e4fc6fdf82a768f44c818b3bf280897882ffc72c949c8a3ab5cd78ca37b",
+      "owner": "codebase-template",
+      "reason": "保留用户现有侧栏、间距及 cobalt 默认主题修改；不是原资产版本的未修改副本"
+    },
+    "src/layouts/role-workspace-shell.tsx": {
+      "previousTemplateSha256": "a9f11ecd7a83647859085f75b6d2ba98760240d474aeb38b9c9c2c8174bff31a",
+      "currentSha256": "ab0c50c655d759643c77f634337b070807a601580f554796f50284f87c8fd100",
+      "owner": "codebase-template",
+      "reason": "保留用户现有侧栏、间距及 cobalt 默认主题修改；不是原资产版本的未修改副本"
+    },
+    "src/workspace/default-workspace.tsx": {
+      "previousTemplateSha256": "0239a9926ab2bc6aa6a0c4923a1af03d618bc245483b114c74b017a4a2051737",
+      "currentSha256": "083313a2e0d61e5eb7f2ee1c2d4dda3243bfdce6204249df85fef7acd751f19d",
+      "owner": "codebase-template",
+      "reason": "保留用户现有侧栏、间距及 cobalt 默认主题修改；不是原资产版本的未修改副本"
+    }
+  }
+}

package/codebase/template/index.html

@@ -1,5 +1,5 @@
 <!doctype html>
-<html lang="zh-CN"
+<html lang="zh-CN" data-accent="cobalt"
   ><head
     ><meta charset="UTF-8" /><meta
       name="viewport"

package/codebase/template/src/components/common/empty-state.tsx

@@ -0,0 +1,52 @@
+import { type ReactNode } from 'react';
+import { InboxIcon } from 'lucide-react';
+
+import { cn } from '../../lib/utils';
+import { Button } from '../ui/button';
+
+export interface EmptyStateProps {
+  icon?: ReactNode;
+  title: string;
+  description?: string;
+  action?: {
+    label: string;
+    onClick: () => void;
+  };
+  className?: string;
+}
+
+/**
+ * 空状态组件
+ * 当列表、表格或其他数据容器没有内容时显示
+ */
+export function EmptyState({
+  icon,
+  title,
+  description,
+  action,
+  className,
+}: EmptyStateProps) {
+  return (
+    <div
+      className={cn(
+        'flex min-h-[400px] flex-col items-center justify-center gap-4 rounded-lg border border-dashed border-border bg-muted/30 p-8 text-center',
+        className,
+      )}
+    >
+      <div className="flex size-20 items-center justify-center rounded-full bg-muted text-muted-foreground">
+        {icon || <InboxIcon className="size-10" />}
+      </div>
+      <div className="space-y-2">
+        <h3 className="text-lg font-semibold text-foreground">{title}</h3>
+        {description && (
+          <p className="max-w-md text-sm text-muted-foreground">{description}</p>
+        )}
+      </div>
+      {action && (
+        <Button onClick={action.onClick} className="mt-2">
+          {action.label}
+        </Button>
+      )}
+    </div>
+  );
+}

package/codebase/template/src/components/common/error-boundary.tsx

@@ -1,7 +1,7 @@
 import React, { Component, type ErrorInfo, type ReactNode } from 'react';
 
-import { Button } from '../components/ui/button';
-import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from '../components/ui/card';
+import { Button } from '../ui/button';
+import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from '../ui/card';
 
 interface ErrorBoundaryProps {
   children: ReactNode;

package/codebase/template/src/components/ui/alert.tsx

@@ -1,65 +1,63 @@
-import * as React from "react"
-import { cva, type VariantProps } from "class-variance-authority"
-import { cn } from "cn"
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "../../lib/utils";
 
 const alertVariants = cva(
-  "relative grid w-full grid-cols-[0_1fr] items-start gap-y-0.5 rounded-lg border px-4 py-3 text-sm has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] has-[>svg]:gap-x-3 [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current",
+  "relative w-full rounded-lg border p-4 [&>svg~*]:pl-7 [&>svg+div]:translate-y-[-3px] [&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4 [&>svg]:text-foreground",
   {
     variants: {
       variant: {
-        default: "bg-card text-card-foreground",
+        default: "bg-background text-foreground",
+        success:
+          "border-semantic-success/50 bg-semantic-success-soft text-semantic-success-foreground [&>svg]:text-semantic-success",
+        warning:
+          "border-semantic-warning/50 bg-semantic-warning-soft text-semantic-warning-foreground [&>svg]:text-semantic-warning",
         destructive:
-          "bg-card text-destructive *:data-[slot=alert-description]:text-destructive/90 [&>svg]:text-current",
+          "border-semantic-danger/50 bg-semantic-danger-soft text-semantic-danger-foreground [&>svg]:text-semantic-danger",
       },
     },
     defaultVariants: {
       variant: "default",
     },
-  }
-)
+  },
+);
 
-function Alert({
-  className,
-  variant,
-  ...props
-}: React.ComponentProps<"div"> & VariantProps<typeof alertVariants>) {
-  return (
-    <div
-      data-slot="alert"
-      role="alert"
-      className={cn(alertVariants({ variant }), className)}
-      {...props}
-    />
-  )
-}
+const Alert = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof alertVariants>
+>(({ className, variant, ...props }, ref) => (
+  <div
+    ref={ref}
+    role="alert"
+    className={cn(alertVariants({ variant }), className)}
+    {...props}
+  />
+));
+Alert.displayName = "Alert";
 
-function AlertTitle({ className, ...props }: React.ComponentProps<"div">) {
-  return (
-    <div
-      data-slot="alert-title"
-      className={cn(
-        "col-start-2 line-clamp-1 min-h-4 font-medium tracking-tight",
-        className
-      )}
-      {...props}
-    />
-  )
-}
+const AlertTitle = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLHeadingElement>
+>(({ className, ...props }, ref) => (
+  <h5
+    ref={ref}
+    className={cn("mb-1 font-medium leading-none tracking-tight", className)}
+    {...props}
+  />
+));
+AlertTitle.displayName = "AlertTitle";
 
-function AlertDescription({
-  className,
-  ...props
-}: React.ComponentProps<"div">) {
-  return (
-    <div
-      data-slot="alert-description"
-      className={cn(
-        "col-start-2 grid justify-items-start gap-1 text-sm text-muted-foreground [&_p]:leading-relaxed",
-        className
-      )}
-      {...props}
-    />
-  )
-}
+const AlertDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("text-sm [&_p]:leading-relaxed", className)}
+    {...props}
+  />
+));
+AlertDescription.displayName = "AlertDescription";
 
-export { Alert, AlertTitle, AlertDescription }
+export { Alert, AlertTitle, AlertDescription };

package/codebase/template/src/hooks/index.ts

@@ -166,8 +166,8 @@ export function useMediaQuery(query: string): boolean {
  */
 export function useClickOutside<T extends HTMLElement = HTMLElement>(
   handler: () => void,
-): React.RefObject<T> {
-  const ref = useRef<T>(null);
+): React.RefObject<T | null> {
+  const ref = useRef<T | null>(null);
 
   useEffect(() => {
     const listener = (event: MouseEvent | TouchEvent) => {

package/codebase/template/src/integrations/platform.ts

@@ -1,6 +1,70 @@
-// 基础能力设计的扩展点；不提供默认登录流程或虚构 API。
+import { httpClient } from '../lib/http-client';
+
+/**
+ * 平台集成接口
+ * 提供统一的认证、查询和操作能力
+ */
 export interface PlatformIntegration {
   getSession(): Promise<{ actorId: string } | null>;
   query<T>(operation: string, input: unknown): Promise<T>;
   execute<T>(operation: string, input: unknown): Promise<T>;
 }
+
+/**
+ * 默认平台集成实现
+ * 使用 HTTP 客户端与后端通信
+ */
+class DefaultPlatformIntegration implements PlatformIntegration {
+  async getSession(): Promise<{ actorId: string } | null> {
+    try {
+      const response = await httpClient.get<{ actorId: string }>('/auth/session');
+      return response.data;
+    } catch (error) {
+      console.warn('Failed to get session:', error);
+      return null;
+    }
+  }
+
+  async query<T>(operation: string, input: unknown): Promise<T> {
+    const response = await httpClient.post<T>('/query', {
+      operation,
+      input,
+    });
+    return response.data;
+  }
+
+  async execute<T>(operation: string, input: unknown): Promise<T> {
+    const response = await httpClient.post<T>('/execute', {
+      operation,
+      input,
+    });
+    return response.data;
+  }
+}
+
+/**
+ * Mock 平台集成(用于开发和测试)
+ */
+class MockPlatformIntegration implements PlatformIntegration {
+  async getSession(): Promise<{ actorId: string } | null> {
+    // 模拟已登录用户
+    return { actorId: 'mock-user-001' };
+  }
+
+  async query<T>(operation: string, input: unknown): Promise<T> {
+    console.log('[Mock Query]', operation, input);
+    // 返回模拟数据
+    return {} as T;
+  }
+
+  async execute<T>(operation: string, input: unknown): Promise<T> {
+    console.log('[Mock Execute]', operation, input);
+    return {} as T;
+  }
+}
+
+// 根据环境变量选择实现
+const useMock = (import.meta as { env?: { VITE_USE_MOCK_API?: string } }).env?.VITE_USE_MOCK_API === 'true';
+export const platform: PlatformIntegration = useMock
+  ? new MockPlatformIntegration()
+  : new DefaultPlatformIntegration();

package/codebase/template/src/layouts/role-workspace-shell.tsx

@@ -67,10 +67,33 @@ function NavigationItem({
       variant="ghost-neutral"
       data-route-id={theme.id}
       className={cn(
-        'h-9 w-full justify-start gap-2.5 rounded-md px-2.5 text-sm font-medium text-foreground/80 has-[>svg]:px-2.5',
-        collapsed && 'justify-center px-0 has-[>svg]:px-0',
-        theme.availability === 'planned' && 'text-muted-foreground disabled:opacity-100',
-        active && 'bg-muted font-semibold text-foreground hover:bg-muted hover:text-foreground',
+        // 基础样式
+        'group relative h-auto w-full justify-start gap-3 rounded-lg px-3 py-2.5 text-sm font-medium transition-all duration-200',
+        
+        // 激活状态
+        active && [
+          'bg-gradient-to-r from-[var(--theme-accent-soft)] via-[var(--theme-accent-soft)]/50 to-transparent',
+          'shadow-sm',
+          'border-l-2 border-[var(--theme-accent)]',
+          'font-semibold text-[var(--theme-accent)]',
+          'hover:from-[var(--theme-accent-soft)] hover:via-[var(--theme-accent-soft)]/60',
+        ],
+        
+        // 非激活状态
+        !active && [
+          'text-foreground/80',
+          'hover:bg-accent/50 hover:text-foreground',
+          'hover:translate-x-0.5 hover:shadow-sm',
+        ],
+        
+        // 计划中状态
+        theme.availability === 'planned' && [
+          'cursor-not-allowed opacity-50',
+          'hover:translate-x-0 hover:bg-transparent',
+        ],
+        
+        // 折叠状态
+        collapsed && 'justify-center px-2 border-l-0',
       )}
       aria-label={collapsed ? theme.label : undefined}
       aria-current={active ? 'page' : undefined}
@@ -80,25 +103,33 @@ function NavigationItem({
       <span
         aria-hidden="true"
         className={cn(
-          'flex w-6 shrink-0 justify-center',
-          active ? 'text-foreground' : 'text-foreground/70',
+          'relative flex size-5 shrink-0 items-center justify-center transition-transform duration-200',
+          active ? 'scale-110 text-[var(--theme-accent)]' : 'text-muted-foreground group-hover:scale-105 group-hover:text-foreground',
         )}
       >
         {theme.icon ?? <Layers3 className="size-4" />}
+        {/* 激活状态的微妙发光效果 */}
+        {active && (
+          <span className="absolute inset-0 animate-pulse rounded-full bg-[var(--theme-accent-soft)] blur-sm" />
+        )}
       </span>
-      {!collapsed ? <span className="truncate">{theme.label}</span> : null}
-      {!collapsed && theme.count !== undefined ? (
+      {!collapsed ? <span className="flex-1 truncate text-left">{theme.label}</span> : null}
+      {!collapsed && theme.count !== undefined && theme.count > 0 ? (
         <span
           className={cn(
-            'rounded-md px-1.5 py-0.5 text-xs leading-4 tabular-nums',
-            active ? 'bg-background text-foreground' : 'bg-muted text-muted-foreground',
+            'flex h-5 min-w-[20px] items-center justify-center rounded-full px-1.5 text-[11px] font-semibold shadow-sm transition-all duration-200',
+            active
+              ? 'bg-primary text-primary-foreground ring-1 ring-primary/20'
+              : 'bg-muted text-muted-foreground group-hover:bg-primary/10 group-hover:text-primary'
           )}
         >
-          {theme.count}
+          {theme.count > 99 ? '99+' : theme.count}
         </span>
       ) : null}
       {!collapsed && theme.availability === 'planned' ? (
-        <span className="ml-auto text-xs font-normal text-muted-foreground">待开放</span>
+        <span className="ml-auto text-[10px] font-medium uppercase tracking-wide text-muted-foreground/60">
+          即将推出
+        </span>
       ) : null}
     </Button>
   );
@@ -140,42 +171,99 @@ function ThemeNavigation({
   const extensions = themes.filter((theme) => !isWorkspaceRouteId(theme.id));
   return (
     <TooltipProvider delayDuration={200}>
-      <nav aria-label="角色工作主题" className="px-3">
-        {(['value', 'inbox', 'enterprise'] as const).map((group) => (
-          <div
-            key={group}
-            data-navigation-group={group}
-            className={cn('grid gap-0.5', group !== 'value' && 'mt-2 border-t border-border pt-2')}
-          >
-            {DEFAULT_WORKSPACE_ROUTES.filter((route) => route.group === group).map((route) => (
-              <NavigationItem
-                key={route.id}
-                theme={{
-                  ...route,
-                  availability: 'implemented',
-                  icon: <WorkspaceRouteIcon id={route.id} />,
-                  count: route.id === 'inbox' ? count : undefined,
-                }}
-                activeThemeId={activeThemeId}
-                onSelect={onSelect}
-                collapsed={collapsed}
-              />
-            ))}
-          </div>
-        ))}
-        {extensions.length ? (
-          <div data-navigation-group="extensions" className="mt-2.5 grid gap-[3px]">
-            {extensions.map((theme) => (
-              <NavigationItem
-                key={theme.id}
-                theme={theme}
-                activeThemeId={activeThemeId}
-                onSelect={onSelect}
-                collapsed={collapsed}
-              />
-            ))}
-          </div>
-        ) : null}
+      <nav aria-label="角色工作主题" className="space-y-1 px-3">
+        {/* 核心视图组 */}
+        <div className="space-y-1">
+          {!collapsed && (
+            <p className="mb-2 px-3 text-[11px] font-medium uppercase tracking-wider text-muted-foreground/70">
+              核心视图
+            </p>
+          )}
+          {DEFAULT_WORKSPACE_ROUTES.filter((route) => route.group === 'value').map((route) => (
+            <NavigationItem
+              key={route.id}
+              theme={{
+                ...route,
+                availability: 'implemented',
+                icon: <WorkspaceRouteIcon id={route.id} />,
+              }}
+              activeThemeId={activeThemeId}
+              onSelect={onSelect}
+              collapsed={collapsed}
+            />
+          ))}
+        </div>
+
+        {/* 渐变分隔线 */}
+        <div className="my-3 h-px bg-gradient-to-r from-transparent via-border to-transparent" />
+
+        {/* 待办事项组 */}
+        <div className="space-y-1">
+          {!collapsed && (
+            <p className="mb-2 px-3 text-[11px] font-medium uppercase tracking-wider text-muted-foreground/70">
+              工作台
+            </p>
+          )}
+          {DEFAULT_WORKSPACE_ROUTES.filter((route) => route.group === 'inbox').map((route) => (
+            <NavigationItem
+              key={route.id}
+              theme={{
+                ...route,
+                availability: 'implemented',
+                icon: <WorkspaceRouteIcon id={route.id} />,
+                count: route.id === 'inbox' ? count : undefined,
+              }}
+              activeThemeId={activeThemeId}
+              onSelect={onSelect}
+              collapsed={collapsed}
+            />
+          ))}
+        </div>
+
+        {/* 企业协作组 */}
+        {DEFAULT_WORKSPACE_ROUTES.some((route) => route.group === 'enterprise') && (
+          <>
+            <div className="my-3 h-px bg-gradient-to-r from-transparent via-border to-transparent" />
+            <div className="space-y-1">
+              {!collapsed && (
+                <p className="mb-2 px-3 text-[11px] font-medium uppercase tracking-wider text-muted-foreground/70">
+                  协作空间
+                </p>
+              )}
+              {DEFAULT_WORKSPACE_ROUTES.filter((route) => route.group === 'enterprise').map((route) => (
+                <NavigationItem
+                  key={route.id}
+                  theme={{
+                    ...route,
+                    availability: 'implemented',
+                    icon: <WorkspaceRouteIcon id={route.id} />,
+                  }}
+                  activeThemeId={activeThemeId}
+                  onSelect={onSelect}
+                  collapsed={collapsed}
+                />
+              ))}
+            </div>
+          </>
+        )}
+
+        {/* 扩展功能 */}
+        {extensions.length > 0 && (
+          <>
+            <div className="my-3 h-px bg-gradient-to-r from-transparent via-border to-transparent" />
+            <div className="space-y-1">
+              {extensions.map((theme) => (
+                <NavigationItem
+                  key={theme.id}
+                  theme={theme}
+                  activeThemeId={activeThemeId}
+                  onSelect={onSelect}
+                  collapsed={collapsed}
+                />
+              ))}
+            </div>
+          </>
+        )}
       </nav>
     </TooltipProvider>
   );