@james_sww/metaform-asset-distribution 0.1.2 → 0.1.4

package/README.md

@@ -2,14 +2,44 @@
 
 这个包提供源码资产 CLI，并携带独立 `@james_sww/metaform-codebase-template` 的版本快照。基础模板工程与外壳维护源是独立 `metaform-codebase/`；其中基础 UI、主题和语义骨架按明确来源派生，不建立第二份人工维护源。业务组件按需复制，源码归应用维护；生成工程不依赖 Metaform workspace 或该 CLI 才能运行。
 
-本版为 `0.1.2`，包含独立资产库迁移与模板侧栏、间距和 cobalt 默认主题更新。资产源码及 CLI 已独立迁入 `metaform-asset-library`；本轮仅分发两个岗位任务组件、语义骨架及真实依赖，外壳随模板交付。
+本版为 `0.1.4`，包含当前组件装配流程、模板区域边界、层级导航，模板不携带历史资产源码副本。资产源码及 CLI 已独立迁入 `metaform-asset-library`。当前源码的 `prepare:release` 会将已验证的各来源资产统一登记到发行中；外壳仍随模板交付。CLI 发行与线上 MCP 分别更新；远程版本与验证结果以发行记录为准。
+
+## 统一 add 入口
+
+通过 `search` 和 `inspect` 确认组件后，统一使用 `add` 或 `plan add`，无需根据来源切换命令：
+
+```sh
+metaform-assets add shadcn.accordion
+metaform-assets add accordion
+metaform-assets add tremor.accordion
+metaform-assets add quality.inspection-evidence-workspace
+metaform-assets add npm.react-flow
+metaform-assets inspect shadcn.button#radix --json
+metaform-assets plan add shadcn.button --variant radix --json
+```
+
+短名称优先选择同名 shadcn 条目；其他来源请使用完整 ID。有多个实现时默认选择 `current`、`new-york-v4`、`raw` 或 `package`，可通过 `ID#variant` 或 `--variant` 明确指定；歧义、未知变体和不支持的条目会报错。
+
+`inspect` 的 `installation` 返回交付方式、实际入口、原始版本和适配要求：
+
+| mode | add 的结果 |
+| --- | --- |
+| `component` | 写入组件源码和依赖。Metaform 通用组件使用应用源码目录；shadcn 与 Tremor 使用 `src/components/vendor/` 下独立目录，改写本地导入，保留许可证。 |
+| `reference` | 业务源码写入 `references/metaform/`，保留原始内容，不注入其运行依赖或自动挂载。AI 根据当前应用本体取用、组合或改写。 |
+| `package` | 添加固定 npm 依赖并保留来源资料。运行时样式、容器和业务数据由应用接入。 |
+
+已有三个 Metaform 发行入口仍使用原路径。新增条目的来源与文件摘要记录于 `references/manifests/`、`assets.lock.json` 和原有基线目录。`installable=true` 表示此发行能按声明方式交付，不代表业务已接通或无需视觉适配。Tremor 需要旧版 API 时使用固定 npm 别名依赖，避免替换宿主已有日历或图表版本。
+
+源码缺失、未解析导入或需要上游专用转换器的条目保留在目录中，`installation.supported=false` 给出具体 `reason/details`；执行 `add` 时拒绝写入。`official add` 仅保留为兼容命令，仍调用独立官方工具；统一入口消费固定发行，不因某条目不支持而自动改用在线最新源码。
+
+资源刷新脚本会将同一发行的 `metadata.installation`、`installId`、摘要和安装资格同步到资源目录，保留原始 reference 字节与交付方式。MCP 消费固定快照，须另行刷新、验证并部署后才会显示新状态；本地 CLI 打包不会自动更新线上服务。
 
 ## npm 使用与沙箱接入
 
 发布版本使用 Node 24.18.0、pnpm 10.18.2。CLI 自带固定版本模板与源码 Registry，无需平台仓库或本机桌面目录。私有包需有下载权限；沙箱凭据由运行环境注入，不写入应用源码。
 
 ```sh
-npm install -g @james_sww/metaform-asset-distribution@0.1.2
+npm install -g @james_sww/metaform-asset-distribution@0.1.4
 metaform-assets init --project ./my-app
 cd my-app
 corepack pnpm install --frozen-lockfile
@@ -18,7 +48,7 @@ corepack pnpm install --frozen-lockfile
 不安装全局工具也可运行：
 
 ```sh
-npm exec --yes --package=@james_sww/metaform-asset-distribution@0.1.2 -- metaform-assets init --project ./my-app
+npm exec --yes --package=@james_sww/metaform-asset-distribution@0.1.4 -- metaform-assets init --project ./my-app
 ```
 
 Agent 根据应用本体和 skill 形成 `ApplicationDesign` JSON 后，在已初始化的应用目录执行：
@@ -31,9 +61,11 @@ metaform-assets prepare --plan /tmp/application-plan.json
 corepack pnpm dev
 ```
 
+新应用的页面、区域、动作和业务流程必须来自当前应用本体；历史演示、岗位菜单及 archive 不作为默认设计输入。初始化只交付基础底座，排除 `src/components/business/`、`src/examples/` 和 `src/layouts/legacy-role-workspace/`，排除清单记录在 `.metaform/codebase.json`。完整模板来源仍先校验，不修改上游快照或历史基线。
+
 CLI 负责按底稿确定性装配；读取线上本体并作语义转译由 Agent 完成。匹配组件安装为应用内源码，未匹配区域保留语义骨架。模板初始化、安装成功不代表真实业务数据已绑定或平台 S7 已自动接通。
 
-基础模板也单独按 `@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 版本用于沙箱重放；初始化后的源码和基线存入项目快照。
+基础模板也单独按 `@james_sww/metaform-codebase-template@0.1.3` 分发，可安装到工具目录后用 `--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 版本用于沙箱重放；初始化后的源码和基线存入项目快照。
 
 ## 维护仓库
 
@@ -51,7 +83,7 @@ pack 前从独立基础模板包生成 `codebase/` 快照，再生成 CLI 和资
 
 `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`。
 
-当前可安装资产：role-workspace-shell、quality.role-task-overview、quality.role-task-groups、common.semantic-region-scaffold，以及真实传递依赖。不猜测任意资产或 npm 版本。所有直接、重导出、字面量动态 import 使用 AST 改写为应用内相对路径；UI aliases 由应用自由配置。未枚举动态 import、未知 npm 依赖、越界路径、软链接、同目标所有权冲突均拒绝。标准 Registry 本轮只接收 UTF-8；二进制资源明确报错。
+`source-map.ts` 保留 quality.role-task-overview、quality.role-task-groups、common.semantic-region-scaffold 三个既有发行入口及其依赖；其余来源由资源适配层生成相同格式的安装条目，共享原有计划和事务写入器。外壳仅由 Code Base 提供，不作为业务资产安装。不猜测任意资产或 npm 版本。组件源码的直接、重导出、字面量动态 import 使用 AST 改写；参考资料保留原始字节。未枚举动态 import、未知 npm 依赖、越界路径、软链接、同目标所有权冲突均拒绝。标准 Registry 只接收 UTF-8；二进制资源明确报错。
 
 ## 独立应用使用
 
@@ -66,7 +98,7 @@ metaform-assets search 岗位任务 --json
 metaform-assets inspect quality.role-task-groups --json
 metaform-assets plan add quality.role-task-overview quality.role-task-groups --json > /tmp/metaform-assets-plan.json
 metaform-assets add --plan /tmp/metaform-assets-plan.json
-metaform-assets official add accordion
+metaform-assets add shadcn.accordion
 metaform-assets reconcile
 metaform-assets diff
 metaform-assets doctor --recover
@@ -104,7 +136,7 @@ metaform-assets plan prepare --design /path/to/application-design.json --json >
 metaform-assets prepare --plan /tmp/application-plan.json
 ```
 
-底稿结构由 src/application-design.ts 定义，区域契约来自 layout 的唯一维护源；CLI 构建前生成纯契约快照，发布后只读取其本地模块。匹配区域指定固定 asset/version/exportName、JSON props 与已声明事件；其余使用 common.semantic-region-scaffold。当前生成页面按区域顺序装配，复杂布局与真实业务能力由后续打造实现。
+底稿结构由 src/application-design.ts 定义，区域契约来自 packages/asset-internals 的唯一维护源；CLI 构建前生成纯契约快照，发布后只读取其本地模块。匹配区域指定固定 asset/version/exportName、JSON props 与已声明事件；其余使用 common.semantic-region-scaffold。当前生成页面按区域顺序装配，复杂布局与真实业务能力由后续打造实现。
 
 生成结果保留 docs/application-design.json、.metaform/application-baselines.json，以及原有 assets.lock.json／资产基线。相同底稿重复准备会保留用户已改文件；新底稿需变更已编辑源码时形成冲突。后续真实替换单独记录区域实现与源码摘要，初始底稿不冒充最终实现。
 
@@ -117,3 +149,6 @@ metaform-assets prepare --plan /tmp/application-plan.json
 底稿支持 `roles[].workspaceRoutes`，将 `value-panorama`、`my-value`、`inbox`、`enterprise-tasks` 显式映射到当前角色的页面 ID，禁止跨角色映射。未映射入口由模板中的平台语义骨架承接；不将平台占位页面伪造为应用本体页面。映射页面不重复显示在扩展菜单，业务页面和区域保留原本体 ID。
 
 本地已验证模板拆分、源码资产装配和入口衔接；npm 发布状态以 Registry 为准，线上 S7 接入单独完成。已有桌面应用不会被强制覆盖，新模板需在新工程初始化或显式审阅升级。
+
+
+当前骨架安装到 `src/asset-internals/semantic-region/`，生成区域显式将其挂入 RegionSlot。模板自带 fallback 文件随 Code Base 交付，新模板的资产锁初始为空，不继承旧资产所有权。显式使用历史模板时仍保留其原摘要、基线及 templateAssetAliases 兼容记录。旧项目若涉及路径迁移仍返回 upgrade_requires_review，不自动转换其 lock。完整使用流程与来源分层见仓库根 README“从继承本体到独立应用”。

package/codebase/codebase.json

@@ -1,43 +1,31 @@
 {
   "schemaVersion": 1,
   "name": "@james_sww/metaform-codebase-template",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "files": {
     "_gitignore": "184ad45835c68a6d3fd5100366678797c5fe4d2a2aa6548749039912376faf54",
     ".env.example": "602ae0c89a09593ef560b5d1f7010439e228c7fb0dd7bbc69c9655cf82a8944f",
-    ".metaform/asset-baselines/0551d7ee067550cd2757cf693414c5e180adbb5efe3af4f5f9b1242aa9cd788e": "0551d7ee067550cd2757cf693414c5e180adbb5efe3af4f5f9b1242aa9cd788e",
-    ".metaform/asset-baselines/0e7bb494140c2c4118b919496a4246b26935367453282bd654fedecd2b16f1a5": "0e7bb494140c2c4118b919496a4246b26935367453282bd654fedecd2b16f1a5",
-    ".metaform/asset-baselines/3d1a9a8a1f7ed83eaf3422d1497cac02b643fe1c470b5c5f357f3bd26c585a0f": "3d1a9a8a1f7ed83eaf3422d1497cac02b643fe1c470b5c5f357f3bd26c585a0f",
-    ".metaform/asset-baselines/4acbc7165a8d54738ff62b51414e772c08fe78434e524e6d8770180d3ba2925f": "4acbc7165a8d54738ff62b51414e772c08fe78434e524e6d8770180d3ba2925f",
-    ".metaform/asset-baselines/4b8ea69ef28a9699c0c3b28e12590a7521f91aa1a4a3d618fc0778455d39cbcc": "4b8ea69ef28a9699c0c3b28e12590a7521f91aa1a4a3d618fc0778455d39cbcc",
-    ".metaform/asset-baselines/567f039384fb23a20a4cd5e1d4fda56255abda6fc04d80b36c4bb6f6c040691b": "567f039384fb23a20a4cd5e1d4fda56255abda6fc04d80b36c4bb6f6c040691b",
-    ".metaform/asset-baselines/5f56cd15afc07567f7b80b8b4d9e89da405e070a562583bbbc2414fd981af324": "5f56cd15afc07567f7b80b8b4d9e89da405e070a562583bbbc2414fd981af324",
-    ".metaform/asset-baselines/7b725132bcc0688429adae31cb0ba872421d87eab5ae118fab88292e2c6e3fd3": "7b725132bcc0688429adae31cb0ba872421d87eab5ae118fab88292e2c6e3fd3",
-    ".metaform/asset-baselines/89d01af0d566e2f42b4653d75be97356896ade09dbfb8de2865d941ade16b398": "89d01af0d566e2f42b4653d75be97356896ade09dbfb8de2865d941ade16b398",
-    ".metaform/asset-baselines/8d4794e5500b7f577ad5c5676d27a7796cdb32984b40ec41a25acbba17c7a425": "8d4794e5500b7f577ad5c5676d27a7796cdb32984b40ec41a25acbba17c7a425",
-    ".metaform/asset-baselines/92cd18a919b549b4827f611c3a4157652c4a6ae034850da1254ca422693c759d": "92cd18a919b549b4827f611c3a4157652c4a6ae034850da1254ca422693c759d",
-    ".metaform/asset-baselines/b48c73f51ff3e148f20ad2c9dbd2847235e4fdf1cdb304d5e2feec9c2febd65e": "b48c73f51ff3e148f20ad2c9dbd2847235e4fdf1cdb304d5e2feec9c2febd65e",
-    ".metaform/asset-baselines/b9e31158082ce71a2b3bdb904d9462619e3690735e73e138b1ce57f8f036347f": "b9e31158082ce71a2b3bdb904d9462619e3690735e73e138b1ce57f8f036347f",
-    ".metaform/asset-baselines/bcc48c05cd912dad5373242ff699cdbec032c8ebb2de45a9df5de79a6daec59c": "bcc48c05cd912dad5373242ff699cdbec032c8ebb2de45a9df5de79a6daec59c",
-    ".metaform/asset-baselines/bf9e1bbb252c1fa5da20a17eeee1ac163c7d3a0b6deff817d30ba04b766fb8a1": "bf9e1bbb252c1fa5da20a17eeee1ac163c7d3a0b6deff817d30ba04b766fb8a1",
-    ".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",
+    "assets.lock.json": "427bc853754c83bccc1baa0275170692c65b512c29978ce7d0407037b3409aed",
     "components.json": "bf8e563e20f684aad29b2b7671b3327effd62dc2cb3bd944fcd1ccb7d581217e",
     "eslint.config.js": "05a1c2fbaca8ec2c04985ca14e7da9ecf7b6722a5d9e27313e814de4b0393ccd",
+    "examples/navigation.html": "d4c5f4f52acf12ead806253d2d2947819181e32debc3dbb3d6f8c166abdaada9",
     "index.html": "b0615e4fc6fdf82a768f44c818b3bf280897882ffc72c949c8a3ab5cd78ca37b",
     "LICENSES/NOTICE.md": "dc2bd63b6bcdf6007dcc823ae145828ae0fc3ff2768950a2899e752c1016e0b2",
     "package.json": "7b256b3982d5683f6279e75ee86280498b7ef444a4262158f8d622f77361f64f",
     "pnpm-lock.yaml": "46912c695ef4a2f351a7469aa26ab1312ccf6347b4d0aa2b075bf3a96632782b",
-    "README.md": "d738a1bfbe9e9221f15e2bdcb46af9fae112afd0c1354bd9d45bdf3ae5205e38",
+    "README.md": "99790ff5b5de2d840c2fa8d70297f5adc92bb5e193729d792c4aa942b1eb3941",
     "role-targets.json": "37517e5f3dc66819f61f5a7bb8ace1921282415f10551d2defa5c3eb0985b570",
+    "src/components/business/analytics/contribution-list.tsx": "5a9cd9e8eed906a08a09666c071653f1da278199102d50ace17b0b36773eae63",
+    "src/components/business/analytics/index.ts": "c6ce4e0dc0d1ab759db4b0757ebc7e1a73a78750067d31f3933f3ad30dbe72b2",
+    "src/components/business/analytics/metric-card.tsx": "421de7b8782c85447c8ffc9b2e1115c3268f69f2eb690203256697320f8ee78f",
+    "src/components/business/quality/index.ts": "d50ac52d0a574f16666a543da02843a085d96f8f7dfa33f780d1dfe542aa820b",
+    "src/components/business/quality/task-card.tsx": "6181431b56169678a938ddeb5c559661344f93efce9366168d3524d88901a7d1",
+    "src/components/business/README.md": "d1672330dce395e96ce89e9d0e5072fd78e036e755011ca42012811c5996ef63",
     "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/common/semantic-region/semantic-region-scaffold.tsx": "062e024ed4f9a22464ff329ba38b7a27625a990970a77277ede92b66ff09d3ef",
     "src/components/ui/alert.tsx": "9c380bb1703ba96fe873d5b3094153fa3402d305719e60aa733e4ab202ffddaa",
     "src/components/ui/avatar.tsx": "e9d4784c2ad5bceccdc4f2f19f367fdc37537a10e3f99f510e42c0226adfbf8f",
     "src/components/ui/badge.tsx": "bf9e1bbb252c1fa5da20a17eeee1ac163c7d3a0b6deff817d30ba04b766fb8a1",
@@ -61,21 +49,37 @@
     "src/components/ui/tabs.tsx": "e1df6e2f95ece373ca909c1d54b8ba8cf4c47dd425c1784bbb9a01c38dd0936b",
     "src/components/ui/tooltip.tsx": "5f56cd15afc07567f7b80b8b4d9e89da405e070a562583bbbc2414fd981af324",
     "src/contexts/toast-context.tsx": "a3af91f8915d7753ef15888997ba941d07459d4df3e3e6d58e25365143bf336f",
+    "src/examples/component-examples.tsx": "71ffb083e0bff1e763ee4613f30107877c94f797a0c2f8e9714d9cbfb94e44fb",
+    "src/examples/navigation-example-data.ts": "31398d891f55f5a793ac77e10b327181466a7248132d398ac9b720885240567d",
+    "src/examples/navigation-example.tsx": "76eb9311078a8c62bcb2dc9ed3fc0c4675b246e581044a786b9a2b1ed004d5c9",
     "src/hooks/index.ts": "ddfe80f0fc8b0b49c0b31f27d9aadc4a54715b5ccee40996a205ecec36958b79",
     "src/integrations/platform.ts": "6edb9755c91f6bf1f16815911739f64c4f45405948eaf0d7bbd5cd2fa939dbe9",
+    "src/layouts/legacy-role-workspace/README.md": "3020935ddc821bc07057b11f9063e3aaa882cbf92acd451b22563cf4952f4b48",
+    "src/layouts/legacy-role-workspace/role-workspace-account.tsx": "1156add3b27e6c66e94852514480235277c42a66fd3a9bfc84f7f630c2ed8ac7",
+    "src/layouts/legacy-role-workspace/role-workspace-icons.tsx": "4b8ea69ef28a9699c0c3b28e12590a7521f91aa1a4a3d618fc0778455d39cbcc",
+    "src/layouts/legacy-role-workspace/role-workspace-routes.ts": "0551d7ee067550cd2757cf693414c5e180adbb5efe3af4f5f9b1242aa9cd788e",
+    "src/layouts/legacy-role-workspace/role-workspace-shell.tsx": "375a44af5a3a5285c329e2f9ca6df1de446d181e0c8fef126f6efe88c68e67ff",
+    "src/layouts/legacy-role-workspace/role-workspace-types.ts": "b9e31158082ce71a2b3bdb904d9462619e3690735e73e138b1ce57f8f036347f",
     "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": "ab0c50c655d759643c77f634337b070807a601580f554796f50284f87c8fd100",
-    "src/layouts/role-workspace-types.ts": "b9e31158082ce71a2b3bdb904d9462619e3690735e73e138b1ce57f8f036347f",
+    "src/layouts/role-workspace-shell.tsx": "b7b28831e0853f98075699171993f127b519c3bfedfc0a620d3a4d3d25f65aa1",
+    "src/layouts/role-workspace-types.ts": "e1aebd03abf747ef894acb89eac9cb1a6335fa906aa496cc37263884b6389bde",
+    "src/layouts/workspace-breadcrumbs.tsx": "b7aa06f871bc257893462237c19c834c176e7ec64e1dfb4aef5d08db78e9fca8",
+    "src/layouts/workspace-navigation-model.ts": "448e8521063168d29955e049d58aa22a53bc34e0d54bc5655566549ac526bb0d",
+    "src/layouts/workspace-navigation.tsx": "763fe03c06aed5136ec6861f6a7299e59af2167c203148b73da3d5144a67d075",
     "src/lib/http-client.ts": "a284532dd0bcc18aaf444b92e883ec77750515c1ba01626d8fa96c3e540d2e37",
     "src/lib/utils.ts": "4acbc7165a8d54738ff62b51414e772c08fe78434e524e6d8770180d3ba2925f",
     "src/main.tsx": "6fa2b2eb510ef94ca04b894c573a041419191f6896043f227eb160ab49bd6efa",
+    "src/platform/region/region-boundary.tsx": "6cee0fc2482f2a41dcf7a475e39fb037bb591c892046df42862f5b1e39774c9d",
+    "src/platform/region/region-slot.tsx": "cfeae0da0ea3dda8d1614aea8dd6ce5acf6158895a1e66af63ac1ef42e3f5b4c",
     "src/styles/index.css": "72f8f255c56d117bab6f2aaa53ce5a37aa9b2d5d085b321b9fcb4b4b983e15eb",
     "src/styles/styles.css": "b48c73f51ff3e148f20ad2c9dbd2847235e4fdf1cdb304d5e2feec9c2febd65e",
     "src/styles/theme-tokens.css": "0e7bb494140c2c4118b919496a4246b26935367453282bd654fedecd2b16f1a5",
-    "src/workspace/default-workspace.tsx": "083313a2e0d61e5eb7f2ee1c2d4dda3243bfdce6204249df85fef7acd751f19d",
+    "src/styles/workspace-shell.css": "7b24fe20ae54c58b27188e58445b694d6aace0867fb76aa548acf4052785a236",
+    "src/workspace/default-workspace.tsx": "977fbade436fb2bfaf71ebdc2a4a4772c8138e00015ea5fe3e3ed8080ab08dc2",
     "src/workspace/routes.ts": "94275cc4d44abcfa672e7d56ac1abc7ecd9f5caf656aa54d3e3ef68eaa7e2085",
+    "tests/workspace-navigation.test.mjs": "72f059730874f9c91befcca675c8cde7e60681d40b218db84e6f55240e08bd93",
     "tests/workspace.test.mjs": "daf930b4db33de45eeecf8431663540ecd54aa90c3ba3dd1e683b539cbb8bf5d",
     "tooling/contracts.d.ts": "9ce9d9ac8e59c11c89aa41881b6e8d6edfc84fb4da115970b9f4a2c1e7486ba8",
     "tooling/contracts.js": "8d539db86dd27573de87c494ae15d7f702d67f24300bce995c7e733619fff630",

package/codebase/template/README.md

@@ -10,8 +10,22 @@ role-targets 每项含 `roleKey`、`entry`（如 `operator/index.html`）、`pat
 
 基础能力通过打造前确认的设计接入 `src/integrations/platform.ts`，业务数据仍连接平台。不要把服务端凭据写进 Vite 环境变量或前端源码。
 
-`assets.lock.json` 与 `.metaform/asset-baselines/` 必须随 Git、下载与快照一起保存；来源丢失会阻止自动升级判断。CLI add 在临时工程安装后逐文件写回，保留原工程根目录和未改文件；可直接在本工程内运行。中断后用 doctor --recover。无显式升级命令时不会自动覆盖本地源码。
+模板以交付清单记录来源，初始 `assets.lock.json` 为空，不携带历史资产源码副本。后续通过 CLI 安装的资产会记录实际来源，相关记录随 Git、下载与快照保存。CLI add 在临时工程安装后逐文件写回，保留原工程根目录和未改文件；可直接在本工程内运行。中断后用 doctor --recover。无显式升级命令时不会自动覆盖本地源码。
 
 CLI 可直接在工程内执行 init/add/official add/doctor --recover；也可用 --project 指定其他工程。临时目录只负责准备，实际应用只更新本次涉及的源码、依赖声明、锁文件和来源记录，根目录不会替换。只有依赖变更或缺失时切换已安装完成的 node_modules。成功备份只含本次触及文件，开发者确认后可清理；不保留整工程备份。
 
 基础模板来自独立 `@metaform/codebase-template`；`.metaform/codebase.json` 记录版本和交付摘要。固定入口通过设计底稿 `roles[].workspaceRoutes` 映射到业务页面；未绑定入口展示平台语义骨架。已映射的页面不重复出现在扩展菜单。
+
+## 通用多级导航
+
+`src/layouts/workspace-navigation.tsx` 导出 `WorkspaceNavigation` 与 `WorkspaceNavigationItem`，可在任意导航区域复用，不依赖工作空间的固定分组。每项使用唯一 `id`、`label`、`availability`，可选 `icon`、`count` 与递归的 `children`；空 `children` 视为末级。父级只展开／收起，末级通过 `onSelect(id)` 导航；`planned` 分支及其后代不可进入。
+
+传入 `items`、`activeId`、`onSelect` 即可使用。默认同级互斥展开：打开一个分组会收起其兄弟分组，祖先保持展开；切换末级或异步加载菜单时自动展开对应祖先。传入 `multiple` 可允许同级多开；可通过 `expandedIds`、`onExpandedIdsChange` 接管展开状态。受控模式下，展开状态由消费者提供，切换路由时也由消费者更新。`collapsed` 模式使用图标入口与多级浮出菜单。
+
+现阶段 `RoleWorkspaceShell` 仍将 `model.themes` 的扩展菜单放在“协作空间”之后，旧单层数据无需修改。扩展项及其后代的 ID 不与四个固定入口重复；通过 `state.expandedThemeIds` 与 `commands.onExpandedThemeIdsChange` 可统一控制桌面和手机菜单的展开状态；`model.navigationMultiple` 可显式启用同级多开。模板不预置业务树，具体菜单由当前应用提供。
+
+开发时打开 `/examples/navigation.html` 可测试内置示例：协作空间下方的三级业务树、数量角标、禁用项、末级切换、收起后的浮出菜单和手机主题菜单。示例数据位于 `src/examples/navigation-example-data.ts`，使用 `example-` 前缀，与默认工作空间隔离；该 HTML 不在默认生产构建入口中。
+
+主内容区顶部默认显示通用面包屑：固定入口显示其名称，扩展入口按菜单树展示完整祖先路径，随 `activeThemeId` 更新。有独立页面的菜单节点可提供 `href`，面包屑上级显示为可返回的链接；没有页面地址的祖先显示为带“分组”标识的文字，待开放路径不可返回。当前页始终是不可点击的高亮文字。“工作空间”根入口返回固定的价值全景。传入 `slots.breadcrumbs` 可完全替换；显式传 `null` 可隐藏；未知路由不生成路径。`WorkspaceBreadcrumbs` 也可独立接收 `{ id, label, href?, disabled? }[]` 展示其他页面路径。
+
+面包屑位于正文 `main` 上方的独立导航条，与正文分别成块；`slots.breadcrumbs` 的替换和隐藏规则不变。菜单 `href` 只为面包屑提供真实上级页面地址，父菜单点击仍只展开／收起。示例中的“我的任务”可返回示例总览，“检验准备”仅分组，末级仅显示当前状态。

package/codebase/template/assets.lock.json

@@ -1,149 +1,4 @@
 {
   "schemaVersion": 1,
-  "assets": [
-    {
-      "id": "layouts.role-workspace-types",
-      "version": "0.1.0",
-      "releaseDigest": "ff84eb9a229a362050c3262110942d6ba6acac9b4f4694db1d496ee39bfba9d3",
-      "files": {
-        "src/layouts/role-workspace-types.ts": "b9e31158082ce71a2b3bdb904d9462619e3690735e73e138b1ce57f8f036347f"
-      }
-    },
-    {
-      "id": "lib.utils",
-      "version": "0.1.0",
-      "releaseDigest": "ff84eb9a229a362050c3262110942d6ba6acac9b4f4694db1d496ee39bfba9d3",
-      "files": {
-        "src/lib/utils.ts": "4acbc7165a8d54738ff62b51414e772c08fe78434e524e6d8770180d3ba2925f"
-      }
-    },
-    {
-      "id": "ui.avatar",
-      "version": "0.1.0",
-      "releaseDigest": "ff84eb9a229a362050c3262110942d6ba6acac9b4f4694db1d496ee39bfba9d3",
-      "files": {
-        "src/components/ui/avatar.tsx": "e9d4784c2ad5bceccdc4f2f19f367fdc37537a10e3f99f510e42c0226adfbf8f"
-      }
-    },
-    {
-      "id": "ui.button",
-      "version": "0.1.0",
-      "releaseDigest": "ff84eb9a229a362050c3262110942d6ba6acac9b4f4694db1d496ee39bfba9d3",
-      "files": {
-        "src/components/ui/button.tsx": "8d4794e5500b7f577ad5c5676d27a7796cdb32984b40ec41a25acbba17c7a425"
-      }
-    },
-    {
-      "id": "ui.dropdown-menu",
-      "version": "0.1.0",
-      "releaseDigest": "ff84eb9a229a362050c3262110942d6ba6acac9b4f4694db1d496ee39bfba9d3",
-      "files": {
-        "src/components/ui/dropdown-menu.tsx": "7b725132bcc0688429adae31cb0ba872421d87eab5ae118fab88292e2c6e3fd3"
-      }
-    },
-    {
-      "id": "ui.skeleton",
-      "version": "0.1.0",
-      "releaseDigest": "ff84eb9a229a362050c3262110942d6ba6acac9b4f4694db1d496ee39bfba9d3",
-      "files": {
-        "src/components/ui/skeleton.tsx": "89d01af0d566e2f42b4653d75be97356896ade09dbfb8de2865d941ade16b398"
-      }
-    },
-    {
-      "id": "layouts.role-workspace-account",
-      "version": "0.1.0",
-      "releaseDigest": "ff84eb9a229a362050c3262110942d6ba6acac9b4f4694db1d496ee39bfba9d3",
-      "files": {
-        "src/layouts/role-workspace-account.tsx": "3d1a9a8a1f7ed83eaf3422d1497cac02b643fe1c470b5c5f357f3bd26c585a0f"
-      }
-    },
-    {
-      "id": "layouts.role-workspace-icons",
-      "version": "0.1.0",
-      "releaseDigest": "ff84eb9a229a362050c3262110942d6ba6acac9b4f4694db1d496ee39bfba9d3",
-      "files": {
-        "src/layouts/role-workspace-icons.tsx": "4b8ea69ef28a9699c0c3b28e12590a7521f91aa1a4a3d618fc0778455d39cbcc"
-      }
-    },
-    {
-      "id": "layouts.role-workspace-routes",
-      "version": "0.1.0",
-      "releaseDigest": "ff84eb9a229a362050c3262110942d6ba6acac9b4f4694db1d496ee39bfba9d3",
-      "files": {
-        "src/layouts/role-workspace-routes.ts": "0551d7ee067550cd2757cf693414c5e180adbb5efe3af4f5f9b1242aa9cd788e"
-      }
-    },
-    {
-      "id": "styles.theme-tokens",
-      "version": "0.1.0",
-      "releaseDigest": "ff84eb9a229a362050c3262110942d6ba6acac9b4f4694db1d496ee39bfba9d3",
-      "files": {
-        "src/styles/theme-tokens.css": "0e7bb494140c2c4118b919496a4246b26935367453282bd654fedecd2b16f1a5"
-      }
-    },
-    {
-      "id": "styles.styles",
-      "version": "0.1.0",
-      "releaseDigest": "ff84eb9a229a362050c3262110942d6ba6acac9b4f4694db1d496ee39bfba9d3",
-      "files": {
-        "src/styles/styles.css": "b48c73f51ff3e148f20ad2c9dbd2847235e4fdf1cdb304d5e2feec9c2febd65e"
-      }
-    },
-    {
-      "id": "ui.sheet",
-      "version": "0.1.0",
-      "releaseDigest": "ff84eb9a229a362050c3262110942d6ba6acac9b4f4694db1d496ee39bfba9d3",
-      "files": {
-        "src/components/ui/sheet.tsx": "fc763d53079b51a789c1cfff23d40e00f844a9a093a2ad112f0ac68ab46fe080"
-      }
-    },
-    {
-      "id": "ui.tooltip",
-      "version": "0.1.0",
-      "releaseDigest": "ff84eb9a229a362050c3262110942d6ba6acac9b4f4694db1d496ee39bfba9d3",
-      "files": {
-        "src/components/ui/tooltip.tsx": "5f56cd15afc07567f7b80b8b4d9e89da405e070a562583bbbc2414fd981af324"
-      }
-    },
-    {
-      "id": "role-workspace-shell",
-      "version": "0.1.0",
-      "releaseDigest": "ff84eb9a229a362050c3262110942d6ba6acac9b4f4694db1d496ee39bfba9d3",
-      "files": {
-        "src/layouts/role-workspace-shell.tsx": "bcc48c05cd912dad5373242ff699cdbec032c8ebb2de45a9df5de79a6daec59c"
-      }
-    },
-    {
-      "id": "components.common.semantic-region.contract",
-      "version": "0.1.0",
-      "releaseDigest": "ff84eb9a229a362050c3262110942d6ba6acac9b4f4694db1d496ee39bfba9d3",
-      "files": {
-        "src/components/common/semantic-region/contract.ts": "92cd18a919b549b4827f611c3a4157652c4a6ae034850da1254ca422693c759d"
-      }
-    },
-    {
-      "id": "ui.badge",
-      "version": "0.1.0",
-      "releaseDigest": "ff84eb9a229a362050c3262110942d6ba6acac9b4f4694db1d496ee39bfba9d3",
-      "files": {
-        "src/components/ui/badge.tsx": "bf9e1bbb252c1fa5da20a17eeee1ac163c7d3a0b6deff817d30ba04b766fb8a1"
-      }
-    },
-    {
-      "id": "ui.collapsible",
-      "version": "0.1.0",
-      "releaseDigest": "ff84eb9a229a362050c3262110942d6ba6acac9b4f4694db1d496ee39bfba9d3",
-      "files": {
-        "src/components/ui/collapsible.tsx": "f3ce568d1ede383d9cb0d11dcc2acb6ce7984cbef8e2db0feec310df76303ccd"
-      }
-    },
-    {
-      "id": "common.semantic-region-scaffold",
-      "version": "0.1.0",
-      "releaseDigest": "ff84eb9a229a362050c3262110942d6ba6acac9b4f4694db1d496ee39bfba9d3",
-      "files": {
-        "src/components/common/semantic-region/semantic-region-scaffold.tsx": "567f039384fb23a20a4cd5e1d4fda56255abda6fc04d80b36c4bb6f6c040691b"
-      }
-    }
-  ]
+  "assets": []
 }

package/codebase/template/examples/navigation.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN" data-accent="cobalt">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>多级菜单交互示例</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/examples/navigation-example.tsx"></script>
+  </body>
+</html>

package/codebase/template/src/components/business/README.md

@@ -0,0 +1,107 @@
+# 业务组件
+
+模板预置了一些常用的业务组件，可以直接使用。
+
+## Analytics 分析组件
+
+位于 `src/components/business/analytics/`
+
+### MetricCard - 指标卡片
+
+展示关键业务指标，支持趋势显示和色调区分。
+
+```tsx
+import { MetricCard } from '@/components/business/analytics';
+
+<MetricCard 
+  value="97"
+  unit="%"
+  label="检验任务准时完成率"
+  trend="up"
+  trendValue="提升 6 个百分点"
+  tone="success"
+/>
+```
+
+**Props:**
+- `value` - 主指标值
+- `label` - 指标标签
+- `unit` - 单位（可选）
+- `trend` - 趋势方向：`'up' | 'down' | 'flat'`（可选）
+- `trendValue` - 趋势变化描述（可选）
+- `tone` - 色调：`'default' | 'success' | 'warning' | 'danger'`（可选）
+- `icon` - 自定义图标（可选）
+- `description` - 额外描述信息（可选）
+
+### ContributionList - 价值贡献列表
+
+展示个人工作贡献和影响，支持点击查看详情。
+
+```tsx
+import { ContributionList } from '@/components/business/analytics';
+
+<ContributionList 
+  title="我的价值贡献"
+  items={[
+    {
+      id: '1',
+      title: '检验任务审批完成率',
+      impact: '提升 6 个百分点',
+      taskDescription: '提升审批效率',
+      category: '生产计划'
+    }
+  ]}
+/>
+```
+
+**ContributionItem Props:**
+- `id` - 唯一标识
+- `title` - 标题
+- `impact` - 影响/变化描述
+- `taskDescription` - 工作任务描述（可选）
+- `suggestion` - 建议描述（可选）
+- `category` - 分类标签（可选）
+- `onClick` - 点击事件（可选）
+
+## Quality 质量组件
+
+位于 `src/components/business/quality/`
+
+### TaskCard - 任务卡片
+
+展示任务信息和操作按钮，支持状态标签、优先级、元信息。
+
+```tsx
+import { TaskCard } from '@/components/business/quality';
+
+<TaskCard 
+  title="批次出厂检"
+  status="pending"
+  priority="high"
+  meta="QC-2025-001 · 检验日期 240mm"
+  actions={[
+    { id: 'notify', label: '发通知' },
+    { id: 'continue', label: '继续处理', variant: 'primary' }
+  ]}
+  onActionClick={(id) => console.log(id)}
+/>
+```
+
+**Props:**
+- `title` - 任务标题
+- `status` - 任务状态：`'pending' | 'processing' | 'completed' | 'rejected'`
+- `description` - 任务描述（可选）
+- `priority` - 优先级：`'high' | 'normal' | 'low'`（可选）
+- `meta` - 元信息（可选）
+- `actions` - 操作按钮列表（可选）
+- `onActionClick` - 点击操作按钮的回调（可选）
+- `onClick` - 点击卡片的回调（可选）
+
+**TaskAction Props:**
+- `id` - 唯一标识
+- `label` - 按钮文本
+- `variant` - 按钮样式：`'default' | 'primary' | 'destructive' | 'outline' | 'ghost'`（可选）
+
+## 示例
+
+查看完整示例：`src/examples/component-examples.tsx`

package/codebase/template/src/components/business/analytics/contribution-list.tsx

@@ -0,0 +1,134 @@
+import type { ReactNode } from 'react';
+
+import { cn } from '@/lib/utils';
+import { ChevronRight } from 'lucide-react';
+
+export interface ContributionItem {
+  /**
+   * 唯一标识
+   */
+  id: string;
+  
+  /**
+   * 标题，如 "检验任务审批完成率"
+   */
+  title: ReactNode;
+  
+  /**
+   * 影响/变化描述，如 "提升 6 个百分点"
+   */
+  impact: ReactNode;
+  
+  /**
+   * 工作任务描述
+   */
+  taskDescription?: ReactNode;
+  
+  /**
+   * 建议描述
+   */
+  suggestion?: ReactNode;
+  
+  /**
+   * 分类标签，如 "生产计划"
+   */
+  category?: string;
+  
+  /**
+   * 点击事件
+   */
+  onClick?: () => void;
+}
+
+export interface ContributionListProps {
+  /**
+   * 贡献项列表
+   */
+  items: readonly ContributionItem[];
+  
+  /**
+   * 列表标题
+   */
+  title?: ReactNode;
+  
+  className?: string;
+}
+
+/**
+ * 价值贡献列表
+ * 
+ * 用于展示个人工作贡献和影响，支持点击查看详情
+ * 
+ * @example
+ * ```tsx
+ * <ContributionList 
+ *   title="我的价值贡献"
+ *   items={[
+ *     {
+ *       id: '1',
+ *       title: '检验任务审批完成率',
+ *       impact: '提升 6 个百分点',
+ *       taskDescription: '提升审批效率',
+ *       category: '生产计划'
+ *     }
+ *   ]}
+ * />
+ * ```
+ */
+export function ContributionList({ items, title, className }: ContributionListProps) {
+  if (items.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className={cn('space-y-3', className)} data-asset="analytics.contribution-list">
+      {title && <h3 className="text-sm font-medium text-foreground">{title}</h3>}
+      
+      <div className="space-y-2">
+        {items.map((item) => (
+          <div
+            key={item.id}
+            className={cn(
+              'group rounded-lg border border-border bg-card p-4',
+              'transition-colors hover:bg-accent',
+              item.onClick && 'cursor-pointer',
+            )}
+            onClick={item.onClick}
+          >
+            <div className="flex items-start justify-between gap-4">
+              <div className="min-w-0 flex-1 space-y-1">
+                {/* 分类标签 */}
+                {item.category && (
+                  <div className="text-xs text-muted-foreground">{item.category}</div>
+                )}
+                
+                {/* 标题 */}
+                <div className="font-medium text-foreground">{item.title}</div>
+                
+                {/* 任务描述 */}
+                {item.taskDescription && (
+                  <div className="text-sm text-muted-foreground">{item.taskDescription}</div>
+                )}
+                
+                {/* 建议 */}
+                {item.suggestion && (
+                  <div className="text-sm text-muted-foreground">{item.suggestion}</div>
+                )}
+              </div>
+              
+              <div className="flex shrink-0 items-center gap-2">
+                {/* 影响/变化 */}
+                <div className="text-sm font-medium text-success">{item.impact}</div>
+                
+                {/* 箭头图标 */}
+                {item.onClick && (
+                  <ChevronRight className="h-4 w-4 text-muted-foreground transition-transform group-hover:translate-x-0.5" />
+                )}
+              </div>
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

package/codebase/template/src/components/business/analytics/index.ts

@@ -0,0 +1,2 @@
+export { MetricCard, type MetricCardProps, type MetricTone, type TrendDirection } from './metric-card';
+export { ContributionList, type ContributionListProps, type ContributionItem } from './contribution-list';