Metaform 独立 Code Base 基础模板

@james_sww/metaform-codebase-template 是独立维护、按版本分发的应用基础模板。template/ 是可独立运行、将被复制到应用工程的完整基础源码。

包含内容

• React/Vite/TypeScript 工程、固定依赖与锁文件。
• 升级后的 RoleWorkspaceShell：价值全景、我的价值、待办事项、企业任务总览和我的任务五个入口，以及账户、搜索和工具面板插槽。
• 设计系统基础 UI、主题、语义区域骨架、独立角色入口构建工具。
• 业务组件预置：
  • Analytics 分析组件：MetricCard（指标卡片）、ContributionList（价值贡献列表）
  • Quality 质量组件：TaskCard（任务卡片）
  • 详见 template/src/components/business/README.md
• 模板交付摘要与空资产锁文件，不携带历史资产源码副本；不预置业务角色、项目业务数据或服务端凭据；公共身份适配器消费宿主或同源 BFF 的真实身份。

通过 npm CLI 初始化

发布版本可使用下列指令。私有包需先登录获授权的 npm 账号，或由沙箱注入下载凭据。

npm install -g @james_sww/[email protected]
metaform-assets init --project ./my-app
cd my-app
corepack pnpm install --frozen-lockfile
corepack pnpm dev

也可使用 npm exec --yes --package=@james_sww/[email protected] -- metaform-assets init --project ./my-app，无需全局安装。CLI 内置此模板的固定版本快照。

该版本完成 npm 发行后，在工具目录执行 npm install --ignore-scripts @james_sww/[email protected]，然后把该目录下 node_modules/@james_sww/metaform-codebase-template 传给 CLI 的 --codebase。CLI 的内置旧快照不会因模板单独发行自动更新。应用输出目录必须为空，不要把工具依赖安装进待初始化的应用目录。

维护与分发

npm run seal
npm pack --pack-destination releases

codebase.json 固定模板版本及全部交付文件的 SHA256。修改 template/ 后先 seal，再打包。_gitignore 在安装进应用时还原为 .gitignore。

CLI 默认携带这个包的版本快照；也可直接使用本目录或 npm 包解压后的 package 目录：

metaform-assets init --codebase /path/to/codebase-template-package --project ./my-app

初始化只复制模板，不隐式联网安装依赖。随后在应用目录执行 corepack pnpm install --frozen-lockfile。应用使用 Node 24.18.0、pnpm 10.18.2；可直接 pnpm dev。

CLI 维护仓库打包时读取 codebase-source.json，或用 METAFORM_CODEBASE_SOURCE=/path/to/package 指定版本来源。发布后的 CLI 已携带快照，不需要平台仓库或这个桌面目录。独立源码目录可以迁入自己的 Git 仓库，不改变应用内源码消费方式。

本体到应用

1. Agent 依据继承的本体和 skill 形成应用设计底稿，明确角色、页面、区域、动作、数据指向与待确认事项。
2. 初始化底座；CLI 按底稿安装匹配资产，并为未匹配区域保留语义骨架。
3. 底稿 roles[].workspaceRoutes 显式把固定入口映射到本体页面；未绑定入口使用平台框架骨架，不冒充应用本体已有页面。
4. docs/application-design.json、区域契约和应用源码使用相同页面／区域／动作 ID，进入 S7 后沿同一工程打造。

{
  "roleKey": "inspector",
  "label": "质检员",
  "entryPageId": "work-tasks",
  "workspaceRoutes": { "my-value": "work-tasks", "inbox": "related-items" }
}

资产库独立维护在同级 metaform-asset-library/，通过 Registry/CLI 安装源码。它与本模板分别维护；模板内外壳、UI、骨架随模板版本交付，初始化时不继承历史资产所有权。后续按需安装的资产保留其来源与本地修改，不强制覆盖。

线上 S7 自动调用和在线应用本体完整覆盖核验尚未接入。本地底稿来源待确认的状态照常保留。

区域边界与平台打造

src/platform/region/region-boundary.tsx 保留稳定的区域／页面 ID、完整语义契约及实现／契约源码路径。RegionSlot 通过 children 承载已安装资产或应用自写组件；没有实现时展示默认携带的轻量语义骨架。替换内部实现时保留边界、ID 和契约。

受控设计预览通过 HostRegionAuthoring 与平台桥交换当前映射、模式和执行状态，支持区域边界、字段／按钮／表格列标注及来源查看；Agent 任务和发送校验由平台负责。.metaform/page-mappings.json 随源码保存页面、区域、字段和动作映射，.metaform/region-evidence.json 记录验证候选。普通运行保留业务点击；mock 必须显式启用，不能作为真实数据来源或就绪证据。

本源码版本为 0.1.6，包含默认模板内的区域交互、细粒度标注、字段与运行来源、公共身份及当前应用角色空间接入；npm 是否已发行以 registry 记录为准。

身份适配器消费真实会话和 AoBase 当前用户在当前应用的可见页面并集，再与生成应用的稳定 roleKey 和精确 canonical 路径求交。唯一可访问角色空间自动进入并隐藏角色栏；多个空间显示授权范围内的切换栏，合法深链优先；零空间拒绝进入，不默认首角色。可信宿主可返回 development 模式，在应用发布前按实际页面范围访问；该模式禁止 releaseId 和业务 permissions，不转为 preview 通配访问。缺少 access 时仍显示未配置状态，业务权限由服务端逐请求校验。

平台开发宿主读取项目 application-workspace/identity，正式宿主 SDK 通过已验证的 capability 读取身份；发布目录桥可从生成 manifest 的 workspacePages 冻结逻辑角色目录。既有旧应用没有该 manifest 时不会自动获得角色，需保留人工修改进行精确迁移并按正常流程重新发布。独立 HTTP 接口仍须由部署方的同源 BFF 提供，并配置受信任 OIDC 回调与服务端会话；前端不保存 AoBase 令牌。模板发行、平台部署和旧工程迁移分别验收。

公共登录逻辑以已验收沙箱行为回收：模板 0.1.6 拒绝旧 preview 通配授权，生成入口复用 resolveApplicationRoleWorkspace，以实际页面 ID、角色键和 canonical 路由判定零／单／多角色。模板不携带项目、用户、具体角色配置或令牌。