@locode2/harness 0.1.0-preview.1

package/bin/restore-assets.mjs

@@ -0,0 +1,40 @@
+// npm/pacote changes .gitignore to .npmignore while extracting a package.
+// Restore exactly the two first-party asset names during installation; this
+// neither builds code nor creates user data or changes global configuration.
+import { createHash } from "node:crypto";
+import { readFile, lstat, rename, unlink } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const DOTFILES = [
+  "bundled-plugins/fast-frontend/.gitignore",
+  "bundled-plugins/fast-frontend/templates/antd-admin/.gitignore",
+];
+
+export async function restoreAssets(root) {
+  const integrity = JSON.parse(await readFile(join(root, "release-integrity.json"), "utf8"));
+  const verified = async (path, expected) => {
+    const info = await lstat(path).catch(() => undefined);
+    if (!info) return false;
+    if (!info.isFile() || info.isSymbolicLink() || createHash("sha256").update(await readFile(path)).digest("hex") !== expected) {
+      throw new Error(`安装资产内容不匹配：${path}`);
+    }
+    return true;
+  };
+  for (const file of DOTFILES) {
+    const expected = integrity.files[file];
+    if (!/^[a-f0-9]{64}$/u.test(expected)) throw new Error(`安装资产缺少哈希：${file}`);
+    const target = join(root, file);
+    const renamed = join(dirname(target), ".npmignore");
+    const present = await verified(target, expected);
+    const npmRenamed = await verified(renamed, expected);
+    if (present) {
+      if (npmRenamed) await unlink(renamed);
+    } else if (npmRenamed) await rename(renamed, target);
+    else throw new Error(`安装资产缺失：${file}`);
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await restoreAssets(fileURLToPath(new URL("../", import.meta.url)));
+}

package/bundled-plugins/fast-frontend/.gitignore

@@ -0,0 +1,2 @@
+!templates/antd-admin/.harness/
+!templates/antd-admin/.harness/template.json

package/bundled-plugins/fast-frontend/README.md

@@ -0,0 +1,29 @@
+# 快速前台插件
+
+Runtime 2.0.8 在 Harness 页面预览中支持“视觉圈改”：按住 Ctrl/⌘ 可临时画圈，也可通过预览工具栏锁定连续圈选。绘制过程直接跟随鼠标轨迹，识别后会自动吸附到目标元素边界并按其圆角规范显示；标注摘要可悬停查看详情、编辑或删除。标注经 Host 验签、校验当前源码哈希后可批量追加到 AI 助手草稿，且不会自动发送；静态导出不会包含检查器或内部源码标记。
+
+这是 Harness Studio 的第一方静态插件。它没有 Host 或 UI 入口，贡献：
+
+- `antd-admin-runtime` Runtime 2.0 共享运行时；
+- `fast-frontend` Runtime 2.0 助手模式；
+- `antd-admin` 旧项目模板，仅用于识别并继续运行已有 `.harness/template.json` 项目。
+
+模板安装器应递归复制 `templates/antd-admin` 到目标项目，将
+`.harness/template.json` 中的安装占位符替换为真实插件内容哈希与安装时间，并在复制
+完成后把每个受保护文件的 SHA-256 写入 `protectedFiles`。标记文件自身不加入哈希映射，
+避免自引用哈希。业务目录保持可编辑；模板升级只能修改基线未发生变化的受保护文件。
+
+模板预览使用 `pnpm exec vite`，Host 应把 `--host`、`--port` 和 `--strictPort`
+参数直接追加在其后。
+
+新应用直接使用所选项目根目录。初始化不要求目录为空，也不再限制为仅含 README；已有
+文件会原样保留，只有 Runtime 声明的业务源码和生成资源会参与预览、校验及静态导出。
+`.harness/**` 是 Host 保留目录，存在非受管内容时仍会拒绝初始化，避免覆盖元数据。
+Runtime 不会复制共享框架，也不会生成或改写项目级 `package.json`、`node_modules` 或 Vite
+配置。Host 根据 `frontendRuntimes[].root` 安装并缓存只读 Runtime，根据 `entry` 启动
+shell，并把 `@harness/frontend-runtime` 映射到 `sdkEntry`。Runtime 的公开业务契约见
+`runtimes/antd-admin/PUBLIC_CONTRACT.md`。
+
+生成资源统一放在 `public/generated/**`：应用清单和 TSX/JSX 使用
+`./generated/<文件>`，`src/styles.css` 使用 `/generated/<文件>`；Host 在静态导出时
+将 CSS URL 改写为可部署到任意子路径的相对地址。

package/bundled-plugins/fast-frontend/harness.plugin.json

@@ -0,0 +1,123 @@
+{
+  "schemaVersion": 1,
+  "apiVersion": "0.1",
+  "id": "harness.fast-frontend",
+  "name": "快速前台",
+  "version": "2.0.8",
+  "publisher": "Harness Studio",
+  "dependencies": {},
+  "permissions": [],
+  "contributes": {
+    "projectTemplates": [
+      {
+        "id": "antd-admin",
+        "version": "1.1.0",
+        "title": "Ant Design 管理后台",
+        "description": "开箱即用的 React、TypeScript、Vite 与 Ant Design 管理后台模板，路由和菜单由页面元数据统一生成。",
+        "assets": [
+          {
+            "source": "templates/antd-admin",
+            "target": "."
+          }
+        ],
+        "editablePaths": [
+          "src/pages/**",
+          "src/features/**",
+          "src/mocks/**",
+          "src/shared/components/business/**",
+          "public/generated/**"
+        ],
+        "protectedPaths": [
+          ".harness/template.json",
+          ".gitignore",
+          "index.html",
+          "package.json",
+          "pnpm-lock.yaml",
+          "pnpm-workspace.yaml",
+          "tsconfig.json",
+          "tsconfig.app.json",
+          "tsconfig.node.json",
+          "vite.config.ts",
+          "scripts/**",
+          "src/main.tsx",
+          "src/vite-env.d.ts",
+          "src/app/**",
+          "src/layouts/**",
+          "src/routes/**",
+          "src/styles/**"
+        ],
+        "commands": {
+          "install": {
+            "command": "pnpm",
+            "args": ["install", "--frozen-lockfile", "--prefer-offline", "--ignore-scripts"],
+            "cwd": "."
+          },
+          "preview": {
+            "command": "pnpm",
+            "args": ["exec", "vite", "--config", "vite.config.ts"],
+            "cwd": "."
+          },
+          "validate": {
+            "command": "pnpm",
+            "args": ["run", "validate"],
+            "cwd": "."
+          }
+        }
+      }
+    ],
+    "frontendRuntimes": [
+      {
+        "id": "antd-admin-runtime",
+        "version": "2.0.8",
+        "abiVersion": "1",
+        "title": "Ant Design 管理后台 Runtime",
+        "description": "由 Harness 托管的 React、TypeScript、Vite 与 Ant Design 共享运行时，业务项目只保存页面和业务源码。",
+        "root": "runtimes/antd-admin",
+        "entry": "src/main.tsx",
+        "sdkEntry": "src/sdk/index.ts",
+        "publicContract": "PUBLIC_CONTRACT.md",
+        "typeDeclarations": "types/runtime.d.ts",
+        "dependencies": {
+          "@ant-design/charts": "2.6.7",
+          "@ant-design/icons": "6.3.2",
+          "@types/node": "24.13.3",
+          "@types/react": "19.2.18",
+          "@types/react-dom": "19.2.5",
+          "@vitejs/plugin-react": "6.1.0",
+          "antd": "6.6.1",
+          "dayjs": "1.11.23",
+          "react": "19.2.8",
+          "react-dom": "19.2.8",
+          "react-router-dom": "7.18.2",
+          "typescript": "5.9.2",
+          "vite": "8.2.2"
+        },
+        "readablePaths": [
+          "README.md",
+          "src/**",
+          "public/generated/**"
+        ],
+        "editablePaths": [
+          "src/app.json",
+          "src/app/providers.tsx",
+          "src/pages/**",
+          "src/features/**",
+          "src/mocks/**",
+          "src/shared/**",
+          "src/styles.css",
+          "public/generated/**"
+        ]
+      }
+    ],
+    "assistantModes": [
+      {
+        "id": "fast-frontend",
+        "title": "快速前台",
+        "description": "使用 Harness 共享 Ant Design Runtime，只生成业务页面、业务状态、模拟数据与声明式路由。",
+        "runtimeId": "antd-admin-runtime",
+        "instructions": "你处于快速前台 Runtime 2.0。无需也不得扫描、复制或修改框架源码；Host 已注入 Runtime 公共契约和 README。项目根不含 package.json、node_modules、Vite 配置或框架入口。只读 README.md、src/**、public/generated/**，只改 Runtime 的 editablePaths。页面写入 src/pages/<id>/page.tsx 并默认导出 React 组件；同目录 route.json 声明 id、path、title、icon、order、parentId、hidden，Host 据此生成路由和菜单。src/app.json 配置名称和主题；src/app/providers.tsx 放全局 Provider；业务逻辑、模拟数据、共享代码、样式和资源分别放 src/features/**、src/mocks/**、src/shared/**、src/styles.css、public/generated/**。可使用 React、Ant Design、@ant-design/icons、React Router、dayjs、@ant-design/charts、@harness/frontend-runtime；禁止 Node 内置模块、远程导入及其他依赖。禁止直接访问 localStorage 或 sessionStorage；同步存储使用 getFrontendStorage(namespace?)。不要执行安装、构建或开发服务器命令。依据当前请求决定是否实现页面，普通对话不需要编译验证。修改业务源码后调用 frontend_validate，并如实报告结果；失败时修复相关问题，无法修复时说明原因后结束，不宣称检查通过。源码未变不要重复检查。框架或依赖需变更时提示关闭快速前台。",
+        "fallbackDirectory": "."
+      }
+    ]
+  }
+}

package/bundled-plugins/fast-frontend/runtimes/antd-admin/PUBLIC_CONTRACT.md

@@ -0,0 +1,139 @@
+# Harness Ant Design Runtime 公共契约
+
+ABI：`1`。业务应用只保存需求、业务源码和生成资源；不得创建 `package.json`、
+`node_modules`、Vite 配置、框架入口或路由注册中心。Runtime 源码由 Host 隔离，Agent
+不需要也不能读取它。
+
+## 业务目录
+
+```text
+README.md
+src/app.json
+src/app/providers.tsx
+src/pages/<页面标识>/page.tsx
+src/pages/<页面标识>/route.json
+src/features/**
+src/mocks/**
+src/shared/**
+src/styles.css
+public/generated/**
+```
+
+- `page.tsx` 默认导出无必填属性的 React 页面组件。
+- `route.json` 必须符合 `contracts/route.schema.json`。`id` 和 `path` 在应用内唯一；
+  `parentId` 必须引用其他路由且不得形成循环。`path` 支持 React Router 动态参数。
+- `route.json` 的最小形式是
+  `{ "id": "dashboard", "path": "/dashboard", "title": "仪表盘" }`；可选字段为
+  `order`（整数）、`parentId`、`hidden` 和 `icon`。`icon` 只能取
+  `AppstoreOutlined`、`BarChartOutlined`、`DashboardOutlined`、`FileTextOutlined`、
+  `FormOutlined`、`HomeOutlined`、`SettingOutlined`、`TeamOutlined`、
+  `UnorderedListOutlined`；不需要图标时请省略该字段。
+- `src/app.json` 可选，符合 `contracts/app.schema.json`；未提供时使用 Runtime 默认值。
+  Logo 只能使用 `./generated/**` 形式引用本地资源，不能使用根路径或远程 URL。
+  支持的完整结构是
+  `{ "name": "应用名称", "logo": "./generated/logo.svg", "theme":
+  { "colorPrimary": "#1677ff", "borderRadius": 8, "compact": false } }`，各字段均可省略。
+- `src/app/providers.tsx` 可选，默认导出一个接收 `children` 的 React Provider。Host 将其
+  放入虚拟注册表的 `providers` 数组。`children` 必须保持可选；全局操作、当前用户和用户
+  切换器必须通过 `FrontendShellProvider` 注册到 Runtime 已有 Header，不得再创建第二个
+  `Layout.Header`。Ant Design 中文环境可按以下方式组合：
+
+  ```tsx
+  import type { ReactNode } from "react";
+  import { ConfigProvider, Select } from "antd";
+  import zhCN from "antd/locale/zh_CN";
+  import { FrontendShellProvider } from "@harness/frontend-runtime";
+
+  export default function Providers({ children }: { children?: ReactNode }) {
+    return (
+      <ConfigProvider locale={zhCN}>
+        <FrontendShellProvider
+          currentUser={{ name: "张三", description: "管理员" }}
+          userSwitcher={<Select aria-label="切换用户" options={[]} />}
+        >
+          {children}
+        </FrontendShellProvider>
+      </ConfigProvider>
+    );
+  }
+  ```
+- `src/styles.css` 可选，只作用于当前业务应用。生成图片等资源放入
+  `public/generated/**`。`src/app.json` 和 TSX/JSX 运行时字符串使用
+  `./generated/<文件>`；CSS 的 `url(...)` 使用 `/generated/<文件>`，Host 在静态导出时
+  会改写为相对路径，二者都兼容任意子路径部署。Runtime 已固定视口高度并让内容区独立
+  滚动；业务样式不得重设 `html`、`body`、`#root` 或 `.harness-runtime-*` 的高度与
+  `overflow`，也不得覆盖 Runtime Shell 的布局规则。
+
+## 可用依赖
+
+业务源码只可导入 React、React DOM、Ant Design、Ant Design Icons、React Router、
+dayjs、Ant Design Charts 和 `@harness/frontend-runtime`。Runtime 保证 React、Router
+与 Ant Design 为单例。禁止 Node 内置模块、远程 URL/资源、项目外路径和其他 npm 包；
+Runtime CSP 仅允许同源、`data:` 图片和 `blob:` 图片。
+
+Ant Design 原生组件始终可以直接使用，不要求把页面改写成 Runtime 组件。下面的 Runtime
+原语只是可选的高质量默认实现，用来减少重复样板代码和页面间视觉漂移。
+
+`@harness/frontend-runtime` 公开：
+
+- `useFrontendRuntime()`：读取应用信息、路由元数据、当前路径并执行导航；
+- `defineFrontendProviders()`：为多个全局业务 Provider 提供类型检查；
+- `getFrontendStorage(namespace?)`：同步、按命名空间隔离的存储；预览经 Host 桥接持久化，
+  不可用时降级为内存；
+- `FrontendShellProvider` / `useFrontendShell()`：把 `headerActions`、`currentUser`、
+  `userSwitcher` 注册到 Runtime 唯一的顶栏；
+- `PageContainer` / `useFrontendPage()`：把页面标题、说明、标题操作和
+  `standard | wide | full` 内容宽度注册到 Runtime；`PageContainer` 本身不会再渲染一套
+  标题或 Header；
+- `MetricGrid`、`DataTable`、`CrudDrawer`、`StatusTag`：可选的 Ant Design 统计卡、
+  表格卡、表单抽屉和状态标签原语；它们的属性仍基于对应 Ant Design 类型；
+- `createFrontendStore(initialState)`：小型、无额外依赖的同步业务状态容器，提供
+  `getState`、`setState`、`update`、`reset`、`subscribe` 和选择器式 `useStore`；
+- `usePersistentFrontendState(key, initialState, options?)`：与 `useState` 相同的同步接口，
+  通过安全 Storage 适配器持久化；
+- `FrontendBusinessAppManifest`、`FrontendRouteMetadata`、`FrontendRuntimeProvider` 等类型。
+
+推荐的页面根节点如下。Runtime 已负责应用 Header、侧边菜单、面包屑和页面标题；业务页
+不得重复渲染这些框架元素：
+
+```tsx
+import { Button, Space } from "antd";
+import { DataTable, PageContainer, StatusTag } from "@harness/frontend-runtime";
+
+export default function TaskListPage() {
+  return (
+    <PageContainer
+      title="待办事项"
+      description="查看并处理当前待办"
+      width="wide"
+      titleActions={<Space><Button type="primary">新建事项</Button></Space>}
+    >
+      <DataTable
+        rowKey="id"
+        dataSource={[]}
+        columns={[{ title: "状态", render: () => <StatusTag status="进行中" /> }]}
+      />
+    </PageContainer>
+  );
+}
+```
+
+预览 iframe 无 `allow-same-origin`，业务源码禁止直接访问 `localStorage` 或
+`sessionStorage`；同步存储必须使用 `getFrontendStorage(namespace?)`。
+
+## Host 虚拟模块
+
+Host 生成 `virtual:harness-business-registry`，固定导出：
+
+```ts
+export const routes: readonly {
+  metadata: FrontendRouteMetadata;
+  Component: React.LazyExoticComponent<React.ComponentType<Record<string, never>>>;
+}[];
+export const appManifest: FrontendBusinessAppManifest;
+export const providers: readonly FrontendRuntimeProvider[];
+export const stylesUrl: string | undefined;
+```
+
+业务代码不得直接导入这个 Host 内部模块。页面源码或 `route.json` 改动由 Host 转换为
+虚拟模块更新；页面模块使用 Fast Refresh，路由结构变化触发整页刷新。

package/bundled-plugins/fast-frontend/runtimes/antd-admin/contracts/app.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness.local/schemas/frontend-business-app-v1.json",
+  "title": "Harness Frontend Business App",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "name": { "type": "string", "minLength": 1, "maxLength": 160 },
+    "logo": {
+      "type": "string",
+      "pattern": "^\\./generated/(?:[^./][^/]*/)*[^./][^/]*$",
+      "maxLength": 2048
+    },
+    "theme": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "colorPrimary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+        "borderRadius": { "type": "integer", "minimum": 0, "maximum": 24 },
+        "compact": { "type": "boolean" }
+      }
+    }
+  }
+}

package/bundled-plugins/fast-frontend/runtimes/antd-admin/contracts/route.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness.local/schemas/frontend-route-v1.json",
+  "title": "Harness Frontend Route",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "path", "title"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:-]*$",
+      "maxLength": 160
+    },
+    "path": {
+      "type": "string",
+      "pattern": "^/",
+      "maxLength": 1024
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 160
+    },
+    "icon": {
+      "type": "string",
+      "enum": [
+        "AppstoreOutlined",
+        "BarChartOutlined",
+        "DashboardOutlined",
+        "FileTextOutlined",
+        "FormOutlined",
+        "HomeOutlined",
+        "SettingOutlined",
+        "TeamOutlined",
+        "UnorderedListOutlined"
+      ]
+    },
+    "order": {
+      "type": "integer",
+      "default": 0
+    },
+    "parentId": {
+      "type": "string",
+      "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:-]*$",
+      "maxLength": 160
+    },
+    "hidden": {
+      "type": "boolean",
+      "default": false
+    }
+  }
+}

package/bundled-plugins/fast-frontend/runtimes/antd-admin/examples/app.json

@@ -0,0 +1,9 @@
+{
+  "name": "示例业务平台",
+  "logo": "./generated/logo.svg",
+  "theme": {
+    "colorPrimary": "#1677ff",
+    "borderRadius": 8,
+    "compact": false
+  }
+}

package/bundled-plugins/fast-frontend/runtimes/antd-admin/examples/route.json

@@ -0,0 +1,8 @@
+{
+  "id": "dashboard",
+  "path": "/dashboard",
+  "title": "数据概览",
+  "icon": "DashboardOutlined",
+  "order": 10,
+  "hidden": false
+}

package/bundled-plugins/fast-frontend/runtimes/antd-admin/index.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="light" />
+    <meta
+      http-equiv="Content-Security-Policy"
+      content="default-src 'self'; base-uri 'none'; object-src 'none'; frame-src 'none'; form-action 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self' ws://127.0.0.1:* ws://localhost:*"
+    />
+    <title>Harness 快速前台</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/bundled-plugins/fast-frontend/runtimes/antd-admin/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@harness/bundled-antd-admin-runtime",
+  "version": "2.0.8",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "smoke:build": "node scripts/smoke-build.mjs",
+    "validate": "pnpm run typecheck && pnpm run smoke:build"
+  },
+  "dependencies": {
+    "@ant-design/charts": "2.6.7",
+    "@ant-design/icons": "6.3.2",
+    "antd": "6.6.1",
+    "dayjs": "1.11.23",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "react-router-dom": "7.18.2"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.5",
+    "@vitejs/plugin-react": "6.1.0",
+    "typescript": "5.9.2",
+    "vite": "8.2.2"
+  }
+}

package/bundled-plugins/fast-frontend/runtimes/antd-admin/scripts/smoke-build.mjs

@@ -0,0 +1,40 @@
+import path from "node:path";
+
+import react from "@vitejs/plugin-react";
+import { build } from "vite";
+
+const virtualId = "virtual:harness-business-registry";
+const resolvedVirtualId = `\0${virtualId}`;
+
+await build({
+  root: process.cwd(),
+  base: "./",
+  configFile: false,
+  plugins: [
+    react(),
+    {
+      name: "harness-runtime-contract-smoke",
+      resolveId(id) {
+        return id === virtualId ? resolvedVirtualId : null;
+      },
+      load(id) {
+        if (id !== resolvedVirtualId) return null;
+        return [
+          "export const routes = [];",
+          "export const appManifest = { name: 'Runtime smoke test' };",
+          "export const providers = [];",
+          "export const stylesUrl = undefined;",
+        ].join("\n");
+      },
+    },
+  ],
+  resolve: {
+    alias: {
+      "@harness/frontend-runtime": path.resolve("src/sdk/index.ts"),
+    },
+  },
+  build: {
+    outDir: "node_modules/.cache/runtime-smoke-build",
+    emptyOutDir: true,
+  },
+});