@kanyun-ai-infra/band-cli 0.1.1 → 0.2.1

package/bundled/official/workshops/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@kanyun-ai-infra/band-workshops",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "description": "工坊目录、工坊详情、新建项目、新建与复制工坊、工坊设置与对话改工坊九个页面",
   "type": "module",
   "exports": {
     ".": "./dist/index.js"
   },
   "peerDependencies": {
-    "@kanyun-ai-infra/band-plugin-sdk": "^1.222.0",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
+    "@kanyun-ai-infra/band-plugin-sdk": "^2.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "@kanyun-ai-infra/band-shell": "*"
   }
 }

package/bundled/official/workshops/plugin.yaml

@@ -1,4 +1,4 @@
-# 官方插件：工坊目录、工坊详情、新建项目、新建与复制工坊、工坊设置（v8 §7）。往外壳的 pages 贡献九页：/workshops 目录，
+# 官方插件：工坊目录、工坊详情、新建项目、新建工坊与基于已有工坊新建、工坊设置（v8 §7）。往外壳的 pages 贡献九页：/workshops 目录，
 # /w/<工坊>/about 详情（工坊轻应用的「关于工坊」），/w/<工坊>/new 用这个工坊新建项目，/workshops/new 新建工坊，
 # /workshops/<工坊>/copy 复制这个工坊（不放在 /w/ 下：那一层的第二段是项目短名），/w/<工坊>/about/model 工坊设置 ·
 # 模型，/w/<工坊>/about/secrets 工坊设置 · 密钥，/w/<工坊>/new/resume 从「我的模型与凭据」配好回来后接着新建。旧地址写在 aliases，打开时改写成新地址。
@@ -39,7 +39,7 @@ contributes:
   - slot: "@kanyun-ai-infra/band-shell/pages"
     id: copy
     route: /workshops/:workshop/copy
-    title: 复制工坊
+    title: 基于已有工坊新建
     frame: shell
   # 工坊设置 · 模型（建工坊的第 2 步也是这一页）：/w/<工坊>/about/model，比 about 更具体；部署没开代建时页面写明没有这一步
   - slot: "@kanyun-ai-infra/band-shell/pages"

package/bundled/skills/band-plugin/references/code.md

@@ -44,7 +44,7 @@ export default definePlugin({
 
 - `ctx.version`：`current()` 当前版本（可能是 null），`subscribe` 换版本，`list(artifactId)` 一份产物的全部版本（从旧到新），`readFile(path)`、`objectUrl(path)` 读当前版本的文件（可传 `{ versionId }` 读别的版本）。查看器的 `ctx.version` 钉在正在看的版本上，换版本时整个重挂。
 - `ctx.selection`：本项目里插件共享的选中，`get` / `set` / `subscribe`。五种：`{ kind: "artifact", artifactId }`、`{ kind: "entity", entityType, id, artifactId? }`、`{ kind: "timecode", seconds, end?, artifactId?, path? }`、`{ kind: "anchor", anchor }`、`{ kind: "stage", stage }`。`subscribe` 收到 `{ value, source }`，`source === ctx.plugin` 是自己的回声，跳过；不认识的 `kind` 当作与己无关。插件之间联动只靠它，不要互相 import 状态。
-- `ctx.anchors.make(kind, payload, snapshot?)`：在当前版本上造锚点。内置类型直接写；自己注册的写短名，内核补成 `plugin:<包名>/<kind>`。内置类型的 payload 都要带 `label`，内容在文件里的还要带 `path`，多写字段也算不合写法（1.x 只在控制台警告，2.0 起报错；`shot` 现在就抛错）。自己注册的类型也把 `label` 写进 payload：线程里显示的位置文字取它，`AnchorType.label` 现在没人调用。形状：`entity` 是 `{ path, label, entityType, id, hash?, point? }`，`text-range` 是 `{ path, label, quote: { exact, prefix?, suffix? }, pos?, lines? }`，`region` 是 `{ path, label, rect: { x, y, w, h }, page? }`（0–1 比例），`timecode` 是 `{ path, label, seconds, end?, rect? }`，`shot` 是 `{ path: "storyboard.json", label, shotId, takeId? }`。
+- `ctx.anchors.make(kind, payload, snapshot?)`：在当前版本上造锚点。内置类型直接写；自己注册的写短名，内核补成 `plugin:<包名>/<kind>`。内置类型的 payload 都要带 `label`，内容在文件里的还要带 `path`，多写字段也算不合写法（当前只在控制台警告，以后的协议大版本会改成报错；`shot` 现在就抛错）。自己注册的类型也把 `label` 写进 payload：线程里显示的位置文字取它，`AnchorType.label` 现在没人调用。形状：`entity` 是 `{ path, label, entityType, id, hash?, point? }`，`text-range` 是 `{ path, label, quote: { exact, prefix?, suffix? }, pos?, lines? }`，`region` 是 `{ path, label, rect: { x, y, w, h }, page? }`（0–1 比例），`timecode` 是 `{ path, label, seconds, end?, rect? }`，`shot` 是 `{ path: "storyboard.json", label, shotId, takeId? }`。
 - `ctx.threads.list(filter)` 读线程；`ctx.threads.openAt(anchor, { draft, handToAgent, intent })` 请锁定的评论框在锚点上打开（`intent` 只有 `"pick"`：镜头候选上「用这条」，锚点是带 `takeId` 的 `shot`）；`ctx.threads.open(id)` 打开已有线程。插件不能自己建线程。
 - 引用：`ctx.threads.quote(threadId, commentId)` 把一条消息、`ctx.threads.quoteAnchor(anchor)` 把一处位置作为引用放进发送框，都不发送。
 - `ctx.gate.open(stage, key?)` 请批准面板打开；`ctx.stages.list / get / start / rerun / rerunWith` 读写阶段运行。
@@ -55,4 +55,4 @@ export default definePlugin({
 - `ctx.events.subscribe("thread.*", fn)`：按类型或前缀订阅事件。事件名以 `EVENT_TYPES`（`@kanyun-ai-infra/band-plugin-sdk` 导出）为准；关心意见就订 `EVENT_GROUPS.threads`（含评论、改动请求、回合），关心流程就订 `EVENT_GROUPS.stages`，别只订 `thread.*`。
 - 打开停靠位：`(ctx.services.get("@kanyun-ai-infra/band-project/dock") as { open(key: string): void }).open("<包名>/<停靠位 id>")`。工具栏按钮写了 `dock` 的，查看器替你开。
 - `ctx.member`（`can("comment")` 判能不能提意见）、`ctx.params`、`ctx.plugin`（本插件的包名）。
-- 只给官方插件、工坊插件拿到 `undefined` 的：`notify`、`approvalSettings`、`memberSettings`、`visibilitySettings`、`artifactShares`、`version.archiveUrl`、`turns.requestStop`、`project.shared`、`project.notices`、`project.upgrade`、`project.remove`；`app.data.write.workshopArchive` 只给部署方案插件。不要写依赖它们的功能。
+- 只给官方插件、工坊插件拿到 `undefined` 的：`notify`、`approvalSettings`、`memberSettings`、`visibilitySettings`、`artifactShares`、`version.archiveUrl`、`turns.requestStop`、`project.shared`、`project.notices`、`project.upgrade`、`project.remove`；`app.data.write.workshopArchive`、`people`（人员目录）只给部署方案插件。不要写依赖它们的功能。

package/bundled/skills/band-plugin/references/manifest.md

@@ -13,7 +13,7 @@
   "keywords": ["数据库", "表格"],
   "type": "module",
   "peerDependencies": {
-    "@kanyun-ai-infra/band-plugin-sdk": "^1.0.0",
+    "@kanyun-ai-infra/band-plugin-sdk": "^2.0.0",
     "@kanyun-ai-infra/band-project": "*",
     "@kanyun-ai-infra/band-viewer-web": "*"
   },
@@ -23,7 +23,7 @@
 
 - 包名带作用域，工坊插件用工坊名（`band new plugin` 取工坊仓库的目录名，去掉 `band-` 前缀）；`@kanyun-ai-infra/band-` 前缀只留给官方插件。
 - `description`（一句话说明）与 `keywords` 显示在插件目录里，人和 Rondo 靠它们挑插件，写上。`"private": true` 表示只在本工坊用；工坊插件不发 npm 包。
-- `peerDependencies` 必须有 `@kanyun-ai-infra/band-plugin-sdk`（协议版本，`^1.0.0`）。往谁的插槽贡献、用谁的服务，就把谁写进来；官方插件还没有对外版本号，写 `"*"`。
+- `peerDependencies` 必须有 `@kanyun-ai-infra/band-plugin-sdk`（协议版本，`^2.0.0`）。往谁的插槽贡献、用谁的服务，就把谁写进来；官方插件还没有对外版本号，写 `"*"`。
 
 `plugin.yaml`：Band 的声明，不写 `name`（顶层写了 `name` 的是已废弃的 0.x 清单，`band check` 直接报错）。
 

package/bundled/skills/band-plugin/references/rules.md

@@ -6,6 +6,7 @@
 - **异步要防乱序**：换版本、切环境时旧请求的结果可能晚到。每次加载记一个序号，结果回来时对不上就丢掉；读不到新数据时清空界面，不留旧数据（尤其是带「删除」按钮的表格）。
 - **读不到不抛错**：版本里可能没有你要的文件、JSON 可能坏了。界面显示「这个版本没有……」，锚点解析返回 null。
 - **路径参数要编码**：`ctx.resources.fetch` 的 path 里拼进去的 id 用 `encodeURIComponent`。
+- **选人/选产物、标签、列表筛选、回执用现成组件**：`@kanyun-ai-infra/band-plugin-react` 导出 `Combobox`（可搜索单选/多选，受控 `items`/`value`/`onChange`，`label` 必写）、`TagInput`（字符串数组，回车或逗号确认、粘贴拆开、重复提示）、`FilterMenu` + `filterRows`（按几个单值维度筛，带计数）、`toast()`（一次性回执，只调不挂 `ToastHost`；失败用 `kind: "bad"` 带「重试」）。不要手写下拉搜索、标签输入、临时提示条。设置与表单里的保存反馈不弹 toast。详见用户文档「用 React 写插件」与 Band Design 站「组件」。
 - **样式只用 Band Design token**：页面提供 `--panel`、`--ink`、`--muted`、`--accent`、`--r-lg` 等 CSS 变量，插件里不写死颜色，类名带插件名前缀。琥珀色（`--warn*`）只给部署方案装的插件（锁定插件、应用级页面）用，工坊插件不用。
 - **工坊页面跟工坊最新发布走，项目页跟项目钉住的版本走**：同一工坊里两者可能是不同版本的插件代码。页面里不要假设项目页的面板、服务是同一版；页面只读本工坊的应用数据（`ctx.app.data` 已固定在本工坊，没有 `write`）。路由只写 `/w/:workshop/x/<页面>`，不写 `aliases`、`opens`。
 - **不放凭据**：接口身份由 Band 代理注入，插件代码和仓库里都不出现 token、连接串。

package/bundled/skills/band-plugin/references/testing-publish.md

@@ -32,4 +32,4 @@ bed.dispose();
 
 `band publish <工坊仓库目录> --url <Band 服务地址> --workshop <id>` 先校验并要求工作区干净，用作者的 git 凭据推送远端同名分支（须与工坊发布分支一致），再用 `BAND_TOKEN` 的 Bearer 身份只调一次 POST releases，不调用工坊 GET。`--workshop` 必填，id 从工坊页地址 `/w/<id>` 获取。可 `--no-push` 跳过推送。不要将 token 写进工坊仓库或命令文本；真实服务发布依赖平台 token 功能，缺少鉴权时继续用页面。构建命令与带依赖预设在生产隔离端口未装配前仍关闭。
 
-`band preview [分支] --workshop <id> [--project <项目 id>]`：把已 push 的分支建成预览快照（只读工坊仓库、不发新版本），带 `--project` 时打印 `?preview=` 的项目链接，只有工坊管理员能打开；token 要 `workshops:preview` scope。预览页的写入会落到真实项目。
+`band preview [分支] --workshop <id> [--project <项目 id>]`：把已 push 的分支建成预览快照（只读工坊仓库、不发新版本），带 `--project` 时打印 `?preview=` 的项目链接，只有工坊管理员能打开；token 要 `workshops:preview` scope。预览页的写入会落到打开的那个项目（试用项目就落在试用项目里）。

package/bundled/skills/band-plugin/templates/panel/package.json

@@ -6,7 +6,7 @@
   "keywords": ["示例"],
   "type": "module",
   "peerDependencies": {
-    "@kanyun-ai-infra/band-plugin-sdk": "^1.0.0",
+    "@kanyun-ai-infra/band-plugin-sdk": "^2.0.0",
     "@kanyun-ai-infra/band-project": "*"
   }
 }

package/bundled/tokens/components.css

@@ -210,7 +210,7 @@ input.field[type="number"] { font-variant-numeric: tabular-nums; }
 /* 输入框下面一行：提示、出错、计数。计数靠右，超了写 .over（DESIGN.md「控件」） */
 .field-note { display: flex; align-items: center; gap: 6px; margin: 0; min-height: 16px; font-size: var(--fs-badge); color: var(--muted); }
 .field-note.err { color: var(--bad); }
-.field-count { font-family: var(--mono); }
+.field-count { font-family: var(--mono); white-space: nowrap; }
 .field-note > .field-count { margin-left: auto; }
 .field-count.over { color: var(--bad); }
 

package/dev-host/app.tsx

@@ -34,6 +34,8 @@ import "./host.css";
 import * as dev from "virtual:band-dev";
 import { useEffect, useRef, useState } from "react";
 import { createRoot } from "react-dom/client";
+import { devManagers } from "../src/dev-managers.ts";
+import { inspectorOpenByDefault } from "../src/inspector-default.ts";
 import { DEV_HOST_PLUGIN } from "../src/inspector-plugins.ts";
 import { loadPlugins } from "../src/load-plugins.ts";
 import { Inspector } from "./Inspector.tsx";
@@ -117,11 +119,14 @@ async function boot() {
         }
       : base;
   const fixture = withStageDefs(withArtifacts(dev.fixture));
-  const transport = createFixtureTransport(fixture, {
-    actor: { kind: "human", id: member.id },
-    defaultAgent: dev.agent,
-    resources: dev.resources,
-  });
+  const transport = createFixtureTransport(
+    { ...fixture, managers: devManagers(roleParam, dev.roles, member.id) },
+    {
+      actor: { kind: "human", id: member.id },
+      defaultAgent: dev.agent,
+      resources: dev.resources,
+    },
+  );
 
   // 插件入口并行导入；一个失败只让它进「没加载的插件」
   const official: LoadedPlugin[] = [];
@@ -312,6 +317,10 @@ function focusOf(s: Selection | null): string | undefined {
 }
 
 function App() {
+  // 夹具栏占 300px：视口不到 1600 默认收起，免得挤坏项目页右栏；收起时仍挂着，事件与诊断照常记
+  const [inspectorOpen, setInspectorOpen] = useState(() =>
+    inspectorOpenByDefault(window.innerWidth),
+  );
   return (
     <div className="dev-page">
       <header className="dev-bar">
@@ -341,16 +350,27 @@ function App() {
         ) : (
           <span className="chip plain">{member.displayName}</span>
         )}
+        <button
+          type="button"
+          className="btn"
+          aria-expanded={inspectorOpen}
+          aria-controls="dev-inspector-slot"
+          onClick={() => setInspectorOpen((v) => !v)}
+        >
+          夹具
+        </button>
       </header>
       <div className="dev-body">
         <ProjectPage />
-        <Inspector
-          ctx={hostCtx}
-          view={view}
-          transport={transport}
-          problems={problems}
-          stageViews={stageViews}
-        />
+        <div id="dev-inspector-slot" className="dev-inspector-slot" hidden={!inspectorOpen}>
+          <Inspector
+            ctx={hostCtx}
+            view={view}
+            transport={transport}
+            problems={problems}
+            stageViews={stageViews}
+          />
+        </div>
       </div>
     </div>
   );

package/dev-host/host.css

@@ -63,6 +63,13 @@ body {
 .dev-project > .band-react-surface {
   display: contents;
 }
+/* 夹具栏的槽：展开时不占自己的盒子（让 aside 直接当 .dev-body 的子项），收起时整块不显示 */
+.dev-inspector-slot {
+  display: contents;
+}
+.dev-inspector-slot[hidden] {
+  display: none;
+}
 /* 锁定插件替身只标位置 */
 .dev-inspector {
   width: 300px;

package/dist/bin.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   main
-} from "./chunk-VTAJX7NN.js";
+} from "./chunk-FGPWXAOA.js";
 import "./chunk-CL3FV65M.js";
-import "./chunk-JWZU3NOD.js";
-import "./chunk-TQHHHXXU.js";
+import "./chunk-XPLYTHNX.js";
+import "./chunk-LGYGWMSY.js";
 
 // src/bin.ts
 process.exitCode = await main(process.argv.slice(2));

package/dist/build-plugin.d.ts

@@ -1,5 +1,5 @@
 export { SHARED_MODULES } from '@kanyun-ai-infra/band-plugin-sdk';
-export { W as WORKSHOP_FORBIDDEN_IMPORTS, c as checkPlugin, a as checkPluginSources } from './workshop-repo-Uq6blxyt.js';
+export { W as WORKSHOP_FORBIDDEN_IMPORTS, c as checkPlugin, a as checkPluginSources } from './workshop-repo-DqoVdcGu.js';
 import '@kanyun-ai-infra/band-contracts';
 import 'zod';
 

package/dist/build-plugin.js

@@ -2,7 +2,7 @@ import {
   WORKSHOP_FORBIDDEN_IMPORTS,
   checkPlugin,
   checkPluginSources
-} from "./chunk-TQHHHXXU.js";
+} from "./chunk-LGYGWMSY.js";
 
 // src/build-plugin.ts
 import { mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from "fs";

package/dist/{chunk-VTAJX7NN.js → chunk-FGPWXAOA.js}

@@ -10,7 +10,7 @@ import {
   officialProfilePath,
   resolvePluginRepo,
   workshopNameOf
-} from "./chunk-JWZU3NOD.js";
+} from "./chunk-XPLYTHNX.js";
 import {
   IMPLICIT_STAGE,
   SELF_CONTAINED_EXTENSIONS,
@@ -29,7 +29,7 @@ import {
   rolePermissions,
   selfContainedProblems,
   workshopFileReader
-} from "./chunk-TQHHHXXU.js";
+} from "./chunk-LGYGWMSY.js";
 
 // src/index.ts
 import { execFileSync } from "child_process";
@@ -310,6 +310,8 @@ function newPlugin(root, name, opts) {
     description: title,
     type: "module",
     peerDependencies: {
+      react: "^19.0.0",
+      "react-dom": "^19.0.0",
       "@kanyun-ai-infra/band-plugin-sdk": `^${BAND_PROTOCOL_VERSION}`,
       [PROJECT]: "*"
     }
@@ -432,6 +434,8 @@ ${t.manifest}`,
         // 不带 --passWithNoTests：收不到测试要红，不吞成绿（band#456）
         scripts: { check: "tsc -p tsconfig.json", test: "vitest run" },
         peerDependencies: {
+          react: "^19.0.0",
+          "react-dom": "^19.0.0",
           "@kanyun-ai-infra/band-plugin-sdk": "workspace:*",
           [PROJECT]: "workspace:*"
         },
@@ -642,7 +646,7 @@ import { parse } from "yaml";
 // package.json
 var package_default = {
   name: "@kanyun-ai-infra/band-cli",
-  version: "0.1.1",
+  version: "0.2.1",
   description: "band \u547D\u4EE4\u884C\uFF1A\u65B0\u5EFA\u3001\u672C\u5730\u8C03\u8BD5\u3001\u6821\u9A8C\u4E0E\u53D1\u5E03 Band \u5DE5\u574A\u548C\u63D2\u4EF6",
   license: "UNLICENSED",
   type: "module",
@@ -657,7 +661,8 @@ var package_default = {
     },
     "./build": {
       types: "./dist/build-plugin.d.ts",
-      import: "./dist/build-plugin.js"
+      import: "./dist/build-plugin.js",
+      default: "./dist/build-plugin.js"
     },
     "./catalog": {
       types: "./dist/plugin-entry.d.ts",
@@ -692,8 +697,8 @@ var package_default = {
     "@kanyun-ai-infra/band-plugin-react": "workspace:^",
     "@kanyun-ai-infra/band-plugin-sdk": "workspace:^",
     "es-module-lexer": "^2.3.2",
-    react: "^18.3.1",
-    "react-dom": "^18.3.1",
+    react: "^19.3.1",
+    "react-dom": "^19.3.1",
     semver: "^7.8.5",
     vite: "^6.0.7",
     yaml: "^2.6.1",
@@ -705,8 +710,8 @@ var package_default = {
     "@kanyun-ai-infra/band-tokens": "workspace:*",
     "@kanyun-ai-infra/band-workshop": "workspace:*",
     "@types/node": "^22.10.0",
-    "@types/react": "^18.3.12",
-    "@types/react-dom": "^18.3.1",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     tsup: "^8.4.0",
     typescript: "5.9.3",
     vitest: "^4.0.17"
@@ -737,11 +742,13 @@ function newPluginRepo(parentDir, packageName, opts) {
   const title = opts.title ?? name;
   const dir = join2(resolve2(parentDir), name);
   if (existsSync2(dir)) throw new NewPluginError(`${dir} \u5DF2\u7ECF\u5B58\u5728`);
+  const react = opts.react === true;
+  const entryFile = react ? "src/index.tsx" : "src/index.ts";
   const rendered = renderPluginTemplate(opts.template, {
     title,
     ...opts.stage ? { stage: opts.stage } : {},
     id: name,
-    entry: "./src/index.ts"
+    entry: `./${entryFile}`
   });
   const workshop = fixtureWorkshop(packageName, opts.template, name, opts.stage);
   try {
@@ -752,14 +759,16 @@ function newPluginRepo(parentDir, packageName, opts) {
     );
   }
   const files = {
-    "package.json": `${JSON.stringify(packageJson(packageName, title), null, 2)}
+    "package.json": `${JSON.stringify(packageJson(packageName, title, react), null, 2)}
+`,
+    "tsconfig.json": `${JSON.stringify(tsconfig(react), null, 2)}
 `,
     "plugin.yaml": rendered.manifest,
-    "src/index.ts": rendered.code,
+    [entryFile]: react ? reactSource(opts.template, title, opts.stage, name) : rendered.code,
     "dev/workshop.yaml": workshop,
     "dev/fixture.ts": fixtureSource(opts.template, opts.stage),
     ".gitlab-ci.yml": CI(packageName),
-    "README.md": readme(packageName, title, opts.template, name, parsed.scope),
+    "README.md": readme(packageName, title, opts.template, name, parsed.scope, react),
     ".gitignore": "node_modules/\ndist/\n"
   };
   for (const [f, body] of Object.entries(files)) {
@@ -773,7 +782,8 @@ function newPluginRepo(parentDir, packageName, opts) {
     hints: [
       `cd ${dir} && npm install\uFF1A\u88C5\u4E0A band \u547D\u4EE4\u884C\u4E0E\u63D2\u4EF6 SDK\uFF08devDependencies\uFF09`,
       "npx band dev .\uFF1A\u7528 dev/ \u5939\u5177\u5DE5\u574A\u8D77\u9875\u9762\uFF0C\u672C\u4ED3\u5E93\u7684\u63D2\u4EF6\u81EA\u52A8\u88C5\u4E0A",
-      "npx band check .\uFF1A\u6821\u9A8C\u63D2\u4EF6\u4E0E\u5939\u5177\u5DE5\u574A\u7684\u88C5\u914D",
+      "npx band check .\uFF1A\u6821\u9A8C\u63D2\u4EF6\u4E0E\u5939\u5177\u5DE5\u574A\u7684\u88C5\u914D\uFF08\u4E0D\u67E5\u7C7B\u578B\uFF09",
+      "npm run typecheck\uFF1A\u8DD1 tsc --noEmit \u67E5\u7C7B\u578B\uFF08band check \u4E0D\u67E5\uFF09",
       placementHint(opts.template, packageName, name, opts.stage),
       "\u53D1\u5E03\u8FD8\u6CA1\u63A5\u4E0A\uFF08\u63D2\u4EF6\u7531 Band \u6253\u5305\u5206\u53D1\uFF0C\u4E0D\u7ECF npm \u53D1\u5305\uFF09\uFF1A\u73B0\u5728 CI \u6A21\u677F\u53EA\u8DD1 band check"
     ]
@@ -786,7 +796,7 @@ function placementHint(template, packageName, name, stage) {
   return `\u9636\u6BB5 ${String(stage)} \u7684\u754C\u9762\u4F1A\u51FA\u73B0\u5728\u5F15\u7528\u5B83\u7684\u5DE5\u574A\u7684\u9636\u6BB5\u8BE6\u60C5\u91CC`;
 }
 var PROJECT2 = "@kanyun-ai-infra/band-project";
-function packageJson(packageName, title) {
+function packageJson(packageName, title, react) {
   return {
     name: packageName,
     version: "0.1.0",
@@ -794,18 +804,46 @@ function packageJson(packageName, title) {
     license: "UNLICENSED",
     type: "module",
     files: ["src", "plugin.yaml", "README.md"],
-    scripts: { dev: "band dev .", check: "band check ." },
+    scripts: { dev: "band dev .", check: "band check .", typecheck: "tsc --noEmit" },
     peerDependencies: {
+      react: "^19.0.0",
+      "react-dom": "^19.0.0",
       "@kanyun-ai-infra/band-plugin-sdk": `^${BAND_PROTOCOL_VERSION2}`,
       [PROJECT2]: "*"
     },
     peerDependenciesMeta: { [PROJECT2]: { optional: true } },
     devDependencies: {
       "@kanyun-ai-infra/band-cli": `^${CLI_VERSION}`,
-      "@kanyun-ai-infra/band-plugin-sdk": `^${BAND_PROTOCOL_VERSION2}`
+      "@kanyun-ai-infra/band-plugin-sdk": `^${BAND_PROTOCOL_VERSION2}`,
+      typescript: "^5.9.3",
+      // 用 React 写才要：宿主与 band dev 提供运行时的 React，这些只给类型检查与编辑器提示
+      ...react ? {
+        "@kanyun-ai-infra/band-plugin-react": `^${PLUGIN_REACT_RANGE}`,
+        "@types/react": "^19.0.0",
+        "@types/react-dom": "^19.0.0",
+        react: "^19.0.0",
+        "react-dom": "^19.0.0"
+      } : {}
     }
   };
 }
+var PLUGIN_REACT_RANGE = "0.2.1";
+function tsconfig(react) {
+  return {
+    compilerOptions: {
+      target: "ES2022",
+      module: "ESNext",
+      moduleResolution: "bundler",
+      lib: ["ES2023", "DOM", "DOM.Iterable"],
+      strict: true,
+      noUncheckedIndexedAccess: true,
+      skipLibCheck: true,
+      noEmit: true,
+      ...react ? { jsx: "react-jsx" } : {}
+    },
+    include: ["src", "dev"]
+  };
+}
 function fixtureWorkshop(packageName, template, name, stage) {
   const head = `# \u72EC\u7ACB\u63D2\u4EF6 ${packageName} \u7684\u672C\u5730\u5939\u5177\u5DE5\u574A\uFF1Aband dev \u8D77\u9879\u76EE\u9875\u3001band check \u67E5\u88C5\u914D\u7528\uFF0C\u4E0D\u53D1\u5E03\u3001\u4E0D\u8FDB\u4EFB\u4F55\u771F\u5B9E\u5DE5\u574A\u3002
 # \u672C\u4ED3\u5E93\u7684\u63D2\u4EF6\u7531\u547D\u4EE4\u76F4\u63A5\u88C5\u4E0A\uFF0C\u4E0D\u7528\u5199\u8FDB views.plugins\u3002
@@ -849,6 +887,85 @@ views:
 `;
 }
 var q2 = (s) => JSON.stringify(s);
+function reactSource(template, title, stage, id) {
+  const head = (what) => `/**
+ * ${what.replace(/\*\//g, "* /").replace(/[\r\n]+/g, " ")}
+ * \u53EA\u7528\u516C\u5F00 ctx\uFF1B\u672C\u5730 \`band dev\` \u8FB9\u5199\u8FB9\u770B\uFF0C\`npm run typecheck\` \u67E5\u7C7B\u578B\uFF0C\u63D0\u4EA4\u524D \`band check\`\u3002
+ */
+`;
+  const imports = `import { reactMount, useCtxData } from "@kanyun-ai-infra/band-plugin-react";
+import { type ProjectCtx, definePlugin } from "@kanyun-ai-infra/band-plugin-sdk";
+import { useState } from "react";
+`;
+  if (template === "panel")
+    return `${head(`${title}\uFF1A\u4E00\u4E2A\u9762\u677F\u3002\u663E\u793A\u5F53\u524D\u7248\u672C\u7684\u6587\u4EF6\u6570\u3002`)}${imports.replace('import { useState } from "react";\n', "")}
+function Panel({ ctx }: { ctx: ProjectCtx }) {
+  const { data, error } = useCtxData(ctx, async () => ctx.version.current(), [], "version.*");
+  if (error) return <p>{error}</p>;
+  if (data === undefined) return <p>\u8BFB\u53D6\u4E2D\u2026</p>;
+  return <p>{data ? \`\u7248\u672C \${data.id}\uFF1A\${data.entries.length} \u4E2A\u6587\u4EF6\` : "\uFF08\u8FD8\u6CA1\u6709\u7248\u672C\uFF09"}</p>;
+}
+
+export default definePlugin({
+  surfaces: {
+    main: reactMount((ctx: ProjectCtx) => <Panel ctx={ctx} />),
+  },
+});
+`;
+  if (template === "viewer")
+    return `${head(`${title}\uFF1A\u4E00\u4E2A\u67E5\u770B\u5668\u3002\u5217\u51FA\u5F53\u524D\u7248\u672C\u7684\u6587\u4EF6\uFF0C\u70B9\u4E00\u4E2A\u770B\u5185\u5BB9\u3002`)}${imports}
+function Viewer({ ctx }: { ctx: ProjectCtx }) {
+  const { data: version, error } = useCtxData(ctx, async () => ctx.version.current(), [], "version.*");
+  const [body, setBody] = useState("");
+  if (error) return <p>{error}</p>;
+  return (
+    <>
+      <ul>
+        {(version?.entries ?? []).map((e) => (
+          <li key={e.path}>
+            <button
+              type="button"
+              onClick={async () => setBody(new TextDecoder().decode(await ctx.version.readFile(e.path)))}
+            >
+              {e.path}
+            </button>
+          </li>
+        ))}
+      </ul>
+      <pre>{body}</pre>
+    </>
+  );
+}
+
+export default definePlugin({
+  surfaces: {
+    ${JSON.stringify(id)}: reactMount((ctx: ProjectCtx) => <Viewer ctx={ctx} />),
+  },
+});
+`;
+  const st = JSON.stringify(stage ?? "");
+  return `${head(`${title}\uFF1A\u9636\u6BB5 ${stage ?? ""} \u7684\u754C\u9762\u3002\u663E\u793A\u9636\u6BB5\u72B6\u6001\uFF0C\u53EF\u4EE5\u542F\u52A8\u3002`)}${imports.replace('import { useState } from "react";\n', "")}
+const STAGE = ${st};
+
+function StageView({ ctx }: { ctx: ProjectCtx }) {
+  const { data, error } = useCtxData(ctx, () => ctx.stages.get(STAGE), [], "stage.*");
+  return (
+    <>
+      <p>{error ?? (data ? \`\${data.stage}\uFF1A\${data.status}\` : "\u8BFB\u53D6\u4E2D\u2026")}</p>
+      <button type="button" onClick={() => void ctx.stages.start(STAGE)}>
+        \u542F\u52A8
+      </button>
+    </>
+  );
+}
+
+export default definePlugin({
+  surfaces: {
+    main: reactMount((ctx: ProjectCtx) => <StageView ctx={ctx} />),
+  },
+});
+`;
+}
 function fixtureSource(template, stage) {
   const stages = template === "stage-view" ? `  stages: [{ stage: ${q2(stage ?? "")}, status: "ready" }],
 ` : "";
@@ -909,7 +1026,8 @@ band-check:
     - npx band check .
 `;
 }
-function readme(packageName, title, template, name, scope) {
+function readme(packageName, title, template, name, scope, react) {
+  const entry = react ? "src/index.tsx" : "src/index.ts";
   const place = template === "panel" ? `\`views.panels\`\uFF08\u672C\u4ED3\u5E93\u7684\u5939\u5177\u653E\u5728\u53F3\u680F\uFF1A\`${packageName}/main\`\uFF09` : template === "viewer" ? `\`views.artifactTypes.<\u4EA7\u7269\u7C7B\u578B>.viewer\`\uFF08\u672C\u4ED3\u5E93\u7684\u5939\u5177\u628A \`demo\` \u7ED1\u5230 \`${packageName}/${name}\`\uFF09` : "\u5F15\u7528\u5B83\u7684\u5DE5\u574A\u7684\u6D41\u7A0B\u9636\u6BB5\u8BE6\u60C5\u91CC";
   return `# ${packageName}
 
@@ -921,7 +1039,8 @@ ${title}\uFF1A\u4E00\u4E2A\u72EC\u7ACB\u7684 Band \u63D2\u4EF6\uFF08\u4E0D\u5C5E
 |---|---|
 | \`package.json\` | \u8EAB\u4EFD\u4E0E\u7248\u672C\uFF1A\u5305\u540D\u3001\u534F\u8BAE\u8303\u56F4\uFF1BdevDependencies \u5E26 band \u547D\u4EE4\u884C\u4E0E\u63D2\u4EF6 SDK |
 | \`plugin.yaml\` | \u89C6\u56FE\u9762\u6E05\u5355\uFF1A\u5F80\u54EA\u4E9B\u63D2\u69FD\u8D21\u732E |
-| \`src/index.ts\` | \u5165\u53E3\uFF0C\u9ED8\u8BA4\u5BFC\u51FA \`definePlugin({ surfaces })\` |
+| \`${entry}\` | \u5165\u53E3\uFF0C\u9ED8\u8BA4\u5BFC\u51FA \`definePlugin({ surfaces })\`${react ? "\uFF0C\u7528 `reactMount` \u6302 React \u7EC4\u4EF6" : ""} |
+| \`tsconfig.json\` | \`npm run typecheck\`\uFF08\`tsc --noEmit\`\uFF09\u7528\uFF1B\`band check\` \u4E0D\u67E5\u7C7B\u578B |
 | \`dev/workshop.yaml\` | \u672C\u5730\u5939\u5177\u5DE5\u574A\uFF1A\u6700\u5C0F\u5B9A\u4E49\uFF0C\u53EA\u7ED9 \`band dev\` / \`band check\` \u7528\uFF0C\u4E0D\u53D1\u5E03 |
 | \`dev/fixture.ts\` | \u5939\u5177\uFF1A\u793A\u4F8B\u4EA7\u7269\u3001\u7248\u672C\u4E0E\u6587\u4EF6 |
 | \`.gitlab-ci.yml\` | CI \u6A21\u677F\uFF1A\u73B0\u5728\u8DD1 \`band check\`\uFF1B\u5355\u6D4B\u3001\u9632\u6CC4\u9732\u626B\u63CF\u4E0E\u53D1\u5E03\u8FDB\u884C\u4E2D |
@@ -933,7 +1052,8 @@ ${title}\uFF1A\u4E00\u4E2A\u72EC\u7ACB\u7684 Band \u63D2\u4EF6\uFF08\u4E0D\u5C5E
 \`\`\`bash
 npm install          # \u88C5\u4E0A devDependencies \u91CC\u7684 band \u547D\u4EE4\u884C\u4E0E\u63D2\u4EF6 SDK
 npx band dev .       # \u7528 dev/ \u5939\u5177\u5DE5\u574A\u8D77\u9879\u76EE\u9875\uFF0C\u672C\u4ED3\u5E93\u7684\u63D2\u4EF6\u81EA\u52A8\u88C5\u4E0A
-npx band check .     # \u6821\u9A8C package.json\u3001plugin.yaml \u4E0E\u5939\u5177\u5DE5\u574A\u7684\u88C5\u914D
+npx band check .     # \u6821\u9A8C package.json\u3001plugin.yaml \u4E0E\u5939\u5177\u5DE5\u574A\u7684\u88C5\u914D\uFF08\u4E0D\u67E5\u4EE3\u7801\u548C\u7C7B\u578B\uFF09
+npm run typecheck    # tsc --noEmit \u67E5\u7C7B\u578B
 \`\`\`
 
 ## \u53D1\u5E03\uFF08\u8FDB\u884C\u4E2D\uFF09
@@ -1063,9 +1183,19 @@ var PUBLISH_LABELS = {
   404: "\u5DE5\u574A\u4E0D\u5B58\u5728\uFF0C\u8BF7\u68C0\u67E5 --workshop id",
   409: "\u53D1\u5E03\u51B2\u7A81\uFF0C\u8BF7\u786E\u8BA4\u5DE5\u574A\u53D1\u5E03\u5206\u652F\u7684\u63D0\u4EA4\u4E0E\u672C\u5730 HEAD \u4E00\u81F4"
 };
+async function hasCredentialsFile() {
+  try {
+    await readFile(join5(homedir(), ".config", "band", "credentials.json"), "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function connectBand(urlOption, failureLabels = PUBLISH_LABELS, needScope = "workshops:publish") {
   let url = urlOption ?? process.env.BAND_URL;
   let token = process.env.BAND_TOKEN;
+  if (!url && !token && !await hasCredentialsFile())
+    throw new PublishError("\u7F3A\u5C11\u670D\u52A1\u5730\u5740\uFF1A\u7528 --url <\u5730\u5740>\uFF08\u6216\u8BBE BAND_URL\uFF09\uFF0C\u5E76\u914D\u7F6E BAND_TOKEN");
   if (!token) {
     let saved;
     try {
@@ -1087,11 +1217,11 @@ async function connectBand(urlOption, failureLabels = PUBLISH_LABELS, needScope
     }
     if (requestedOrigin && requestedOrigin !== savedOrigin)
       throw new PublishError("\u76EE\u6807\u670D\u52A1\u4E0E\u7528\u6237\u51ED\u636E\u6587\u4EF6\u4E0D\u5339\u914D\uFF0C\u8BF7\u4E3A\u76EE\u6807\u670D\u52A1\u63D0\u4F9B BAND_TOKEN");
-    url ??= saved.url;
+    if (!url) url = saved.url;
     token = saved.token;
   }
-  if (!url || !token || /\s/.test(token))
-    throw new PublishError("\u8BF7\u914D\u7F6E\u5408\u6CD5\u7684 BAND_URL \u4E0E BAND_TOKEN");
+  if (!url) throw new PublishError("\u7F3A\u5C11\u670D\u52A1\u5730\u5740\uFF1A\u7528 --url <\u5730\u5740> \u6216\u8BBE BAND_URL");
+  if (!token || /\s/.test(token)) throw new PublishError("\u8BF7\u914D\u7F6E\u5408\u6CD5\u7684 BAND_TOKEN");
   let base;
   try {
     base = new URL(url);
@@ -1813,7 +1943,7 @@ var USAGE_BASE = `\u7528\u6CD5\uFF1A
   band preview [\u5206\u652F\u6216\u63D0\u4EA4] [--url <Band \u670D\u52A1\u5730\u5740>] --workshop <id> [--project <\u9879\u76EE id>]
   band dev [\u5DE5\u574A\u4ED3\u5E93\u76EE\u5F55 | \u72EC\u7ACB\u63D2\u4EF6\u4ED3\u5E93\u76EE\u5F55] [--port 5310] [--host 127.0.0.1]
   band new plugin <\u540D> --template panel|viewer|stage-view [--stage <\u9636\u6BB5>] [--title <\u6807\u9898>] [--dir <\u5DE5\u574A\u4ED3\u5E93\u76EE\u5F55>]
-  band new plugin-repo @<\u56E2\u961F>/<\u540D> --template panel|viewer|stage-view [--stage <\u9636\u6BB5>] [--title <\u6807\u9898>] [--dir <\u7236\u76EE\u5F55>]
+  band new plugin-repo @<\u56E2\u961F>/<\u540D> --template panel|viewer|stage-view [--react] [--stage <\u9636\u6BB5>] [--title <\u6807\u9898>] [--dir <\u7236\u76EE\u5F55>]
   band new workshop <\u76EE\u5F55> [--example video]
   band new skill [--dir <\u4ED3\u5E93\u76EE\u5F55>]
   band --version`;
@@ -1942,7 +2072,11 @@ async function main(argv) {
       return 0;
     }
     if (cmd === "new") {
-      const { args, flags } = parseArgs(rest, ["template", "stage", "title", "dir"], ["official"]);
+      const { args, flags } = parseArgs(
+        rest,
+        ["template", "stage", "title", "dir"],
+        ["official", "react"]
+      );
       const [kind, name] = args;
       if (kind !== "plugin" && kind !== "plugin-repo" || !name) {
         console.error(usage());
@@ -1953,6 +2087,10 @@ async function main(argv) {
         console.error(`--template \u53EA\u80FD\u662F ${PLUGIN_TEMPLATES.join(" | ")}`);
         return 2;
       }
+      if (kind === "plugin" && flags.react) {
+        console.error("--react \u53EA\u7528\u4E8E band new plugin-repo\uFF08\u5DE5\u574A\u4ED3\u5E93\u91CC\u7684\u63D2\u4EF6\u81EA\u5DF1\u5199 .tsx \u5165\u53E3\uFF09");
+        return 2;
+      }
       if (kind === "plugin-repo") {
         if (flags.official) {
           console.error("--official \u53EA\u7528\u4E8E band new plugin\uFF1A\u72EC\u7ACB\u63D2\u4EF6\u4ED3\u5E93\u4E0D\u751F\u6210\u5B98\u65B9\u63D2\u4EF6");
@@ -1961,7 +2099,8 @@ async function main(argv) {
         const r2 = newPluginRepo(flags.dir ?? ".", name, {
           template,
           ...flags.stage ? { stage: flags.stage } : {},
-          ...flags.title ? { title: flags.title } : {}
+          ...flags.title ? { title: flags.title } : {},
+          ...flags.react ? { react: true } : {}
         });
         for (const f of r2.files) console.log(`\u2713 ${relative(flags.dir ?? ".", join7(r2.dir, f))}`);
         for (const h of r2.hints) console.log(`\u4E0B\u4E00\u6B65\uFF1A${h}`);
@@ -1980,7 +2119,7 @@ async function main(argv) {
     if (cmd === "dev") {
       const { args, flags } = parseArgs(rest, ["port", "host"]);
       const port = flags.port === void 0 ? void 0 : parsePort(flags.port);
-      const { startDevServer } = await import("./dev-server-SB5FMSVP.js");
+      const { startDevServer } = await import("./dev-server-IBR3PKDE.js");
       const server = await startDevServer(args[0] ?? ".", {
         ...port !== void 0 ? { port } : {},
         ...flags.host ? { host: flags.host } : {}