@kanyun-ai-infra/band-cli 0.1.0 → 0.2.0

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

@@ -0,0 +1,38 @@
+# 先找现成的、Agent 怎么选
+
+> 什么时候读：动手写代码之前，判断要不要写新插件、该用哪个官方插件或哪一档 Agent 时。
+
+顺序：**先用官方插件，再找别的工坊共享的插件，都不合适才写新的**。官方插件在 `workshop.yaml` 的 `views` 里按 id 选用，不用写代码：查看器写在 `artifactTypes.<类型>.viewer`，面板写在 `panels` 的区里，要换掉某个官方面板写 `replace`。
+
+| 种类 | id（`views` 里写的） | 管什么 |
+|---|---|---|
+| 查看器 | `web` | 网页类产物：预览、元素标注、实时预览、直接编辑（`band-viewer-web`） |
+| 查看器 | `text` | Markdown 与纯文本，按段落、选中文字提意见（`band-viewer-text`） |
+| 查看器 | `image` | 图片与候选网格，框选提意见，版本并排对比（`band-viewer-image`） |
+| 查看器 | `media` | 音频与视频，按时间点提意见（`band-viewer-media`） |
+| 查看器 | `shots` | 分镜的镜头表：逐镜看静帧、时长、画面说明与旁白，和上一版按镜头 id 对比（`band-viewer-storyboard`） |
+| 查看器 | `web-app` | Web 应用走查：内嵌打开加了走查 SDK 的真实页面，按设备尺寸看、点元素提意见（`band-viewer-web-app`） |
+| 查看器 | `tool-pack` | 教具包：直接体验（投屏、平板、手机），调试指令（换示例、按指令集生成参数表单、看状态与事件记录），意见挂画面元素或某条指令（`band-viewer-tool`） |
+| 查看器 | `entity` | 实体集合（角色表这类结构化条目），按条目提意见（`band-viewer-entity`） |
+| 查看器 | `external` | 外部文档的快照，按文档块提意见（`band-viewer-external`） |
+| 查看器 | `material-text` | 素材的某个版本当文档看（Markdown、纯文本、网页源码），只读、不带阶段来源（`band-viewer-text`） |
+| 查看器 | `material-image` | 素材的某个版本当图片看，只读、不带阶段来源（`band-viewer-image`） |
+| 查看器 | `material-media` | 素材的某个版本当音频/视频看，只读、不带阶段来源（`band-viewer-media`） |
+| 面板 | `stages` | 阶段列表与进度，`{ stages: { compact: true } }` 收成流程条（`band-stages`） |
+| 面板 | `artifacts` | 产物列表，点一个切换主区（`band-artifacts`） |
+| 面板 | `threads` | 意见栏（`band-threads`） |
+| 面板 | `chat` | 和 Agent 的对话流（`band-chat`） |
+| 面板 | `activity` | 项目动态（`band-activity`） |
+| 面板 | `turn-trace` | 回合轨迹：一回合的步骤、流水、在做什么与用时（`band-turn-trace`） |
+| 面板 | `members` | 成员与角色（`band-members`） |
+| 面板 | `params-form` | 阶段参数表单（`band-params-form`） |
+
+完整目录（说明、关键词、在用的工坊数）在 Band 的 `GET /api/plugins`，每个插件的详情（README、版本、对外面、资源权限、谁在用）在 `GET /api/plugins/<作用域>/<名>`，人看插件页（`/plugins`）。别的工坊共享的插件在 `views.plugins` 里钉精确版本（`'@rush-site/rush-db@1.2.0'`）或写 `^` 兼容区间（`'@rush-site/rush-db@^1.2.0'`，解析成区间内最大的可用版本）引用，发布工坊时由服务端从插件登记处解析；`band check` 配了登记处才核对，没配逐条标「未校验」；`band dev` 不装载，只在页面上列出来。写了新插件、别的工坊也用得上时，去掉 `package.json` 的 `"private": true` 就是共享。
+
+Agent 写在工坊级（`workshop.yaml` 顶层的 `agent`），作所有 agent 阶段的缺省；某个阶段确实要另一个 Agent 时，在那个阶段上写 `agent` 覆盖。按这个顺序选：
+
+1. 先用 Rondo（缺省，不用写）。
+2. 不够时扩展 Rondo：在 `band/agent/` 写工坊说明（`instructions.md`，按阶段写 `stages/<阶段>.md`）；项目记忆由 Agent 自己积累；要特殊系统环境时选 Band 维护的环境档 `runtime`，没有合适的档先向 Band 申请。
+3. 还不够，比如要 MCP、自己的模型服务或密钥，或者申请不到合适的环境档，才写 `agenthub/agents/<名字>/` 定制 Agent，在工坊级 `agent` 写它的名字。
+
+按阶段的差异优先写进 `stages/<阶段>.md`；只有某个阶段确实要另一套插件、环境或提示词时才给它单独写 `agent`。

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

@@ -0,0 +1,13 @@
+# 规矩
+
+> 什么时候读：写完代码自查，或不确定某个写法能不能做（异步、样式、凭据、错误边界）时。
+
+- **不碰协作状态**：评论、批准、队列、回合、版本只有锁定插件能改。工坊插件要提意见就 `openAt`，要批准就 `gate.open`。
+- **异步要防乱序**：换版本、切环境时旧请求的结果可能晚到。每次加载记一个序号，结果回来时对不上就丢掉；读不到新数据时清空界面，不留旧数据（尤其是带「删除」按钮的表格）。
+- **读不到不抛错**：版本里可能没有你要的文件、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、连接串。
+- **渲染出错只坏自己那一块**：用 React 就用 `@kanyun-ai-infra/band-plugin-react` 的 `reactMount` 挂，它给每个挂载面包了错误边界，渲染期抛错显示插件名、原因和「重试」。自己 `createRoot` 或用别的框架的，要自己包错误边界；不包的话那一块只剩空白，没有说明也没有重试，宿主管不到。挂载函数同步抛错由宿主画错误卡。

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

@@ -0,0 +1,17 @@
+# 先定形态与 band new plugin
+
+> 什么时候读：已经决定要写新插件，要选模板、选往哪个插槽贡献时。
+
+| 想做 | 模板 | 往这个插槽贡献 |
+|---|---|---|
+| 页面四周的一块面板（分镜墙、时间轴） | `panel` | `@kanyun-ai-infra/band-project/panels`，写 `title` |
+| 某种产物的显示方式 | `viewer` | `@kanyun-ai-infra/band-project/viewers`，写 `title` |
+| 某个阶段的专属界面（发布进度） | `stage-view` | `@kanyun-ai-infra/band-project/stage-views`，写 `stage` |
+| 查看器工具栏上的按钮 + 停靠位（数据库、环境变量） | 用 `panel` 起步改 | `@kanyun-ai-infra/band-viewer-web/toolbar`（写 `label`、`dock`）+ `@kanyun-ai-infra/band-project/docks`（写 `title`） |
+| 项目之外的整页（看板、报表、素材总览） | 用 `panel` 起步改 | `@kanyun-ai-infra/band-shell/pages`，写 `route: /w/:workshop/x/<页面>` 与 `title`；`peerDependencies` 加 `@kanyun-ai-infra/band-shell`（见用户文档「给工坊加页面」） |
+
+```bash
+band new plugin <名> --template panel|viewer|stage-view [--stage <阶段>] [--title <标题>]
+```
+
+它生成 `band/views/<名>/package.json`、`plugin.yaml` 与 `index.ts`，并把 `./views/<名>` 加进 `workshop.yaml` 的 `views.plugins`。插件名用小写 kebab-case，不能和平台插件重名（comment、approval、threads、stages……）。

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

@@ -0,0 +1,35 @@
+# 提交前与发布
+
+> 什么时候读：提交前自检、写插件测试，或要 `band publish` / `band preview` 时。
+
+- `band check`：校验 `workshop.yaml`、每个插件的 `package.json` 与 `plugin.yaml`，再拼一遍装配（插槽在不在、字段对不对、声明者写没写进 `peerDependencies`）。
+- 在 `band dev` 里走一遍：换版本、联动选中、提意见、资源读写（看「夹具」栏的审计）。
+- 插件逻辑能抽成纯函数的（解析文件、时间点落在哪个镜头），给它写单测。
+- 要测挂载后的行为，用 `@kanyun-ai-infra/band-kernel/testing` 的测试台，不用自己拼内核。它要从 `node_modules` 装官方插件（外壳、项目页），这些不发 npm，所以**只在 Band 仓库里能用**；工坊仓库里挂载后的行为在 `band dev` 里走。Band 仓库里的写法：
+
+```ts
+// @vitest-environment jsdom
+import { createTestbed, loadPluginPackage } from "@kanyun-ai-infra/band-kernel/testing";
+const bed = await createTestbed({
+  plugins: [
+    // 插槽的声明者要一起装，和真实宿主一样
+    await loadPluginPackage("@kanyun-ai-infra/band-shell", import.meta.url),
+    await loadPluginPackage("@kanyun-ai-infra/band-project", import.meta.url),
+    { packageJson, manifest, module: plugin }, // 被测插件
+  ],
+  data: fixture,
+});
+const root = bed.mount("@kanyun-ai-infra/band-project/panels", {
+  key: "@<工坊>/checklist/main", // 插件全名 / 贡献 id
+  owner: { projectId: fixture.projectId },
+});
+await bed.settle();
+// 断言 root 的 DOM、bed.requests（开线程等发给锁定插件的请求）、bed.ctx("@<工坊>/checklist").selection.get()
+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。预览页的写入会落到打开的那个项目（试用项目就落在试用项目里）。

package/bundled/skills/band-plugin/references/viewer-comments.md

@@ -0,0 +1,25 @@
+# 查看器接评论
+
+> 什么时候读：做的是查看器、要让用户在内容上提意见（意见编号、锚点宿主、标注模式）时。
+
+查看器回答「意见在哪」，意见编号、评论框、孤儿列表、标注模式的开关都归锁定的评论插件。查看器里不画意见编号，也不自己画评论框。完整例子见用户文档「自定义查看器接评论」，示例工坊 `aitutor-tool` 的 `band/views/tool-preview` 是完整的工坊查看器。
+
+1. 提意见：把点的地方 `ctx.anchors.make(...)` 成锚点，`ctx.threads.openAt(anchor)`。能用内置类型就用内置类型（条目、卡片用 `entity`，视频镜头用 `shot`）：自己注册的 `plugin:*` 类型现在评论框不贴着内容弹，只贴在按钮下。
+2. 挂载时登记锚点宿主，评论插件按它画意见编号：
+
+   ```ts
+   const off = ctx.anchors.host({
+     kinds: ["entity"],          // 内置类型名；自己注册的写 register 的返回值
+     locate,                     // (anchor) => AnchorPlace，必须同步
+     reveal,                     // async (anchor) => boolean，用 band-plugin-react/scroll 的 scrollIntoPanel 滚到它；做不到返回 false
+     onLayout(fn) {              // 内容重画、换文件、图片撑高时调 fn（页面滚动、挂载点尺寸评论插件自己跟）
+       listeners.add(fn);
+       return () => listeners.delete(fn);
+     },
+   });
+   ```
+
+   `locate` 返回 `{ at: "rects", rects: [{ x, y, width, height }], status? }`（相对挂载点，文字跨行多个矩形，宽高为 0 是一个点）、`{ at: "track", x, y, w? }`（音视频时间轴）、`{ at: "elsewhere" }`（这一版里有、不在视口）、`{ at: "pending" }`（布局没好，等 `onLayout`）或 `{ at: "none" }`（孤儿）。`status` 是跨版本结果：不写是原位，`"changed"` 内容改过，`"moved"` 挪了位置。要读文件才判得出的先异步算好，`locate` 里只取结果。
+3. 点击本身有含义的内容（图片、网页、iframe）：宿主写 `annotate: true`（评论插件因此接 C 进、Esc 出），`ctx.anchors.annotating.subscribe` 跟着开关，只在模式开着时把点击变成锚点。文字、清单类查看器可以不写，不开模式也能提意见。
+4. Esc 一次只关一样，先后是评论框 > 标注模式 > 浮层。查看器自己也接 Esc 时，先看 `e.defaultPrevented`，已被处理过的不再处理，处理了就 `preventDefault`。
+5. 可选：音视频给 `candidates()` 报锚点小标，视觉类给 `thumbnail(anchor)` 附截图。

package/bundled/skills/band-plugin/templates/dev/fixture.ts

@@ -0,0 +1,15 @@
+// band/dev/fixture.ts —— band dev 必须有；形状以 @kanyun-ai-infra/band-cli/fixture 的 FixtureData 为准。
+import type { FixtureData } from "@kanyun-ai-infra/band-cli/fixture";
+
+export const fixture: FixtureData = {
+  projectId: "prj_demo",
+  runId: "run_demo_1",
+  versions: [
+    /* Version；打开时看第一个版本所在的产物 */
+  ],
+  artifacts: [{ id: "art_storyboard", name: "分镜", artifactType: "storyboard" }],
+  files: {
+    /* "<versionId>": { "storyboard.json": "{...}" } */
+  },
+  stages: [{ stage: "deploy", status: "ready" }],
+};

package/bundled/skills/band-plugin/templates/dev/resources.ts

@@ -0,0 +1,6 @@
+// band/dev/resources.ts —— 插件用了 plugin.yaml 的 resources 时写；键是清单里的资源名。
+import type { ProxyRequest } from "@kanyun-ai-infra/band-cli/fixture";
+
+export const resources = {
+  database: (req: ProxyRequest) => new Response(JSON.stringify([]), { status: 200 }),
+};

package/bundled/skills/band-plugin/templates/panel/index.ts

@@ -0,0 +1,24 @@
+import { type ProjectCtx, definePlugin } from "@kanyun-ai-infra/band-plugin-sdk";
+
+// 面板：显示当前版本与共享选中。plugin.yaml 里的贡献 id（main）就是 surfaces 的键。
+export default definePlugin({
+  surfaces: {
+    main(ctx: ProjectCtx, mount: unknown) {
+      const root = mount as HTMLElement;
+      const text = root.ownerDocument.createElement("p");
+      root.append(text);
+      const draw = () => {
+        const v = ctx.version.current();
+        const sel = ctx.selection.get();
+        text.textContent = `版本 ${v?.id ?? "（无）"}；选中 ${sel ? JSON.stringify(sel) : "（无）"}`;
+      };
+      const offVersion = ctx.version.subscribe(draw);
+      const offSelection = ctx.selection.subscribe(draw);
+      draw();
+      return () => {
+        offVersion();
+        offSelection();
+      };
+    },
+  },
+});

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

@@ -0,0 +1,12 @@
+{
+  "name": "@my-workshop/example",
+  "version": "0.1.0",
+  "private": true,
+  "description": "一句话说明插件做什么（显示在插件目录里）",
+  "keywords": ["示例"],
+  "type": "module",
+  "peerDependencies": {
+    "@kanyun-ai-infra/band-plugin-sdk": "^2.0.0",
+    "@kanyun-ai-infra/band-project": "*"
+  }
+}

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

@@ -0,0 +1,5 @@
+entry: ./index.ts
+contributes:
+  - slot: "@kanyun-ai-infra/band-project/panels"
+    id: main
+    title: 示例面板

package/bundled/skills/band-plugin/templates/toolbar-dock/plugin.yaml

@@ -0,0 +1,11 @@
+# 查看器工具栏上的一个按钮 + 一个停靠位。peerDependencies 要加 band-viewer-web（optional）与 band-project。
+entry: ./index.ts
+contributes:
+  - slot: "@kanyun-ai-infra/band-viewer-web/toolbar"
+    id: open-db
+    optional: true                      # 工坊没用网页查看器时静默不生效
+    label: 数据库
+    dock: db                            # 点了打开本插件的停靠位 db
+  - slot: "@kanyun-ai-infra/band-project/docks"
+    id: db
+    title: 数据库

package/dev-host/Inspector.tsx

@@ -1,8 +1,14 @@
 /** 「夹具」栏：插件调了什么一眼看清。数据都来自夹具 transport 与运行时，不经插件。 */
 import type { BandEvent } from "@kanyun-ai-infra/band-contracts";
 import type { FixtureTransport } from "@kanyun-ai-infra/band-kernel/fixture";
-import type { AssemblyView, ProjectCtx, Selection } from "@kanyun-ai-infra/band-plugin-sdk";
+import type {
+  AssembledPlugin,
+  AssemblyView,
+  ProjectCtx,
+  Selection,
+} from "@kanyun-ai-infra/band-plugin-sdk";
 import { useEffect, useReducer, useState } from "react";
+import { splitInspectorPlugins } from "../src/inspector-plugins.ts";
 
 export function Inspector({
   ctx,
@@ -38,6 +44,7 @@ export function Inspector({
   // 运行时的诊断（插件激活、挂载失败）有新的就重画
   useEffect(() => ctx.app.subscribeDiagnostics(refresh), [ctx]);
   const threads = transport.threads();
+  const plugins = splitInspectorPlugins(view.plugins);
   // 同一个挂载面每次重挂失败都会再记一条：按内容去重
   const failures = [
     ...new Map(
@@ -65,15 +72,12 @@ export function Inspector({
       )}
       <section>
         <h2>插件</h2>
-        <ul>
-          {view.plugins.map((p) => (
-            <li key={p.name}>
-              <code>{p.name}</code>
-              {p.roles.length > 0 ? `（锁定：${p.roles.join("、")}）` : ""}
-              {p.name in view.failed ? " · 没装上" : ""}
-            </li>
-          ))}
-        </ul>
+        {/* 作者自己的插件在上；三十来个官方插件默认折起，免得把选中、线程、审计挤出首屏 */}
+        <PluginList plugins={plugins.own} view={view} />
+        <details className="dev-inspector-official">
+          <summary>官方插件 {plugins.official.length} 个</summary>
+          <PluginList plugins={plugins.official} view={view} />
+        </details>
       </section>
       {stageViews.length > 0 && (
         <section>
@@ -138,3 +142,17 @@ export function Inspector({
     </aside>
   );
 }
+
+function PluginList({ plugins, view }: { plugins: AssembledPlugin[]; view: AssemblyView }) {
+  return (
+    <ul>
+      {plugins.map((p) => (
+        <li key={p.name}>
+          <code>{p.name}</code>
+          {p.roles.length > 0 ? `（锁定：${p.roles.join("、")}）` : ""}
+          {p.name in view.failed ? " · 没装上" : ""}
+        </li>
+      ))}
+    </ul>
+  );
+}

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 { DEV_HOST_PLUGIN } from "../src/inspector-plugins.ts";
 import { loadPlugins } from "../src/load-plugins.ts";
 import { Inspector } from "./Inspector.tsx";
 
@@ -41,7 +43,7 @@ import { Inspector } from "./Inspector.tsx";
  * 宿主自己在运行时里的身份：不贡献任何东西，只为拿一份项目作用域的 ctx（读诊断、顶栏的「产物」改选中），
  * 选中的来源、诊断里写的是它，不冒用别的插件。
  */
-const HOST_PLUGIN = "@kanyun-ai-infra/band-dev-host";
+const HOST_PLUGIN = DEV_HOST_PLUGIN;
 const hostPlugin: LoadedPlugin = {
   input: {
     packageJson: {
@@ -116,11 +118,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[] = [];

package/dev-host/host.css

@@ -87,6 +87,17 @@ body {
   gap: 4px;
   overflow-wrap: anywhere;
 }
+.dev-inspector-official {
+  margin-top: 4px;
+}
+.dev-inspector-official summary {
+  cursor: pointer;
+  color: var(--muted);
+  font-size: 12px;
+}
+.dev-inspector-official ul {
+  margin-top: 4px;
+}
 .dev-inspector pre {
   margin: 0;
   font-family: var(--mono);

package/dev-host/main.tsx

@@ -22,6 +22,11 @@ function showFailure() {
   root.replaceChildren(pre);
 }
 
+// 预览 ingress 会断掉空闲约 180 秒的 WebSocket：页面也定时发一条，两个方向都有流量（服务端的在 dev-server.ts）
+if (import.meta.hot) {
+  const hot = import.meta.hot;
+  setInterval(() => hot.send("band:heartbeat", {}), 60_000);
+}
 import.meta.hot?.on("vite:error", (payload: { err: { message: string } }) => {
   viteErrors.push(payload.err.message);
   showFailure();

package/dist/bin.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   main
-} from "./chunk-VVJNG5GV.js";
+} from "./chunk-Q2XJXNVH.js";
 import "./chunk-CL3FV65M.js";
-import "./chunk-RAD6MMSL.js";
-import "./chunk-TN7Z3OF6.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-CO6YMDee.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-TN7Z3OF6.js";
+} from "./chunk-LGYGWMSY.js";
 
 // src/build-plugin.ts
 import { mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from "fs";

package/dist/{chunk-TN7Z3OF6.js → chunk-LGYGWMSY.js}

@@ -442,7 +442,7 @@ var ROLE_PERMISSIONS = [
   "confirm",
   "approve",
   "publish",
-  /** @deprecated 管理权限由服务端的工坊与项目成员管理角色决定（`workshop_members`、`members.role`），这里照常校验但不起作用，`band check` 告警；2.0 起拒绝。 */
+  /** @deprecated 管理权限由服务端的工坊与项目成员管理角色决定（`workshop_members`、`members.role`），这里照常校验但不起作用，`band check` 告警；以后的协议大版本会改成拒绝。 */
   "admin"
 ];
 var RolePermissions = z2.array(z2.enum(ROLE_PERMISSIONS));
@@ -539,7 +539,7 @@ var WorkshopSchema = z2.object({
    * 工坊的缺省 agent（1.11.0），缺省 `rondo`；agent 阶段写了 `agent` 就用阶段的（owner 11-02 启用阶段级 agent，
    * [note](../../../.agents/notes/proposed/architecture/2026-10-27-single-agent-per-flow.md) 的部分取代头）。
    * 写工坊项目里的 agent slug；阶段级 `agent` 覆盖它。`{ hubProject, slug }`（1.18.0）已弃用：1.x 照收并给告警，
-   * 解析出同一个 agent，2.0 起报错。
+   * 解析出同一个 agent，以后的协议大版本会改成报错。
    */
   agent: z2.union([Name, AgentRefSchema]).optional(),
   /**
@@ -555,9 +555,9 @@ var WorkshopSchema = z2.object({
    * 决定 3）。这里只认字段；发布检查与派发在服务端读它。
    */
   userModelKey: z2.enum(["off", "allow", "require"]).optional(),
-  /** 已弃用：工坊只复制、不继承。1.x 照旧合并并给警告，2.0 起报错；`overrides` 同。 */
+  /** 已弃用：工坊只复制、不继承。1.x 照旧合并并给警告，以后的协议大版本会改成报错；`overrides` 同。 */
   extends: z2.string().min(1).optional(),
-  /** 已弃用：迭代方式写在 `repos.<名>.iteration` 上。1.x 只在没写 `repos` 时接受并给警告（不再起作用），2.0 起报错。 */
+  /** 已弃用：迭代方式写在 `repos.<名>.iteration` 上。1.x 只在没写 `repos` 时接受并给警告（不再起作用），以后的协议大版本会改成报错。 */
   iteration: IterationSchema.optional(),
   repos: recordSchema2(Name, RepoSchema).optional(),
   connectors: recordSchema2(Name, WorkshopConnectorSchema).optional(),
@@ -847,17 +847,17 @@ function inferConcept(s, kind, at, warnings) {
     case "human":
       if (s.gate !== void 0) return "check";
       warnings.push(
-        `${at}: human \u9636\u6BB5\u65E2\u6CA1\u5199 produces \u4E5F\u6CA1\u5199\u95E8\u7981\uFF0C\u65E0\u4E8B\u53EF\u505A\uFF1B\u8981\u4EBA\u4EA4\u4E1C\u897F\u5199 produces\uFF08type: collect\uFF09\uFF0C\u8981\u4EBA\u9A8C\u5199\u95E8\u7981\uFF08type: review\uFF09\u30022.0 \u8D77\u62A5\u9519`
+        `${at}: human \u9636\u6BB5\u65E2\u6CA1\u5199 produces \u4E5F\u6CA1\u5199\u95E8\u7981\uFF0C\u65E0\u4E8B\u53EF\u505A\uFF1B\u8981\u4EBA\u4EA4\u4E1C\u897F\u5199 produces\uFF08type: collect\uFF09\uFF0C\u8981\u4EBA\u9A8C\u5199\u95E8\u7981\uFF08type: review\uFF09\u3002\u4EE5\u540E\u7684\u534F\u8BAE\u5927\u7248\u672C\u4F1A\u6539\u6210\u62A5\u9519`
       );
       return "produce";
     case "agent":
       warnings.push(
-        `${at}: agent \u9636\u6BB5\u6CA1\u5199 produces\uFF0C1.x \u5F53\u4EA7\u51FA\u9636\u6BB5\u5904\u7406\uFF0C\u4EA7\u7269\u7C7B\u578B\u7B49\u4EA4\u4ED8\u65F6\u5B9A\uFF1B\u8865\u4E0A produces\uFF0C\u6216\u5199 type\uFF08\u4EA7\u51FA\u5199 generate\uFF09\u30022.0 \u8D77\u62A5\u9519`
+        `${at}: agent \u9636\u6BB5\u6CA1\u5199 produces\uFF0C\u5F53\u524D\u5F53\u4EA7\u51FA\u9636\u6BB5\u5904\u7406\uFF0C\u4EA7\u7269\u7C7B\u578B\u7B49\u4EA4\u4ED8\u65F6\u5B9A\uFF1B\u8865\u4E0A produces\uFF0C\u6216\u5199 type\uFF08\u4EA7\u51FA\u5199 generate\uFF09\u3002\u4EE5\u540E\u7684\u534F\u8BAE\u5927\u7248\u672C\u4F1A\u6539\u6210\u62A5\u9519`
       );
       return "produce";
     case "external":
       warnings.push(
-        `${at}: external \u9636\u6BB5\u6CA1\u5199 produces\uFF0C1.x \u5F53\u4EA7\u51FA\u9636\u6BB5\u5904\u7406\uFF0C\u4EA7\u7269\u7C7B\u578B\u7B49\u5916\u90E8\u56DE\u8C03\u65F6\u5B9A\uFF1B\u8865\u4E0A produces\uFF0C\u6216\u5199 type\uFF08\u4EA7\u51FA\u5199 generate\uFF0C\u53D1\u5E03\u5199 publish\uFF0C\u68C0\u6D4B\u5199 check\uFF09\u30022.0 \u8D77\u62A5\u9519`
+        `${at}: external \u9636\u6BB5\u6CA1\u5199 produces\uFF0C\u5F53\u524D\u5F53\u4EA7\u51FA\u9636\u6BB5\u5904\u7406\uFF0C\u4EA7\u7269\u7C7B\u578B\u7B49\u5916\u90E8\u56DE\u8C03\u65F6\u5B9A\uFF1B\u8865\u4E0A produces\uFF0C\u6216\u5199 type\uFF08\u4EA7\u51FA\u5199 generate\uFF0C\u53D1\u5E03\u5199 publish\uFF0C\u68C0\u6D4B\u5199 check\uFF09\u3002\u4EE5\u540E\u7684\u534F\u8BAE\u5927\u7248\u672C\u4F1A\u6539\u6210\u62A5\u9519`
       );
       return "produce";
   }
@@ -1388,12 +1388,12 @@ function compileWorkshop(input, options = {}) {
   checkConnectors(def, options.connectors, issues, warnings);
   if (isPlainObject(input) && (input.extends !== void 0 || input.overrides !== void 0))
     warnings.push(
-      "extends / overrides: \u5DF2\u5F03\u7528\uFF0C\u5DE5\u574A\u53EA\u590D\u5236\u3001\u4E0D\u7EE7\u627F\uFF1B\u8981\u5728\u522B\u7684\u5DE5\u574A\u4E0A\u6539\uFF0C\u5230\u5B83\u7684\u8BE6\u60C5\u9875\u70B9\u300C\u590D\u5236\u4E00\u4EFD\u300D\uFF0C\u4E4B\u540E\u4E24\u8FB9\u5404\u6539\u5404\u7684\u30022.0 \u8D77\u62A5\u9519"
+      "extends / overrides: \u5DF2\u5F03\u7528\uFF0C\u5DE5\u574A\u53EA\u590D\u5236\u3001\u4E0D\u7EE7\u627F\uFF1B\u8981\u5728\u522B\u7684\u5DE5\u574A\u4E0A\u6539\uFF0C\u5230\u5B83\u7684\u8BE6\u60C5\u9875\u70B9\u300C\u590D\u5236\u4E00\u4EFD\u300D\uFF0C\u4E4B\u540E\u4E24\u8FB9\u5404\u6539\u5404\u7684\u3002\u4EE5\u540E\u7684\u534F\u8BAE\u5927\u7248\u672C\u4F1A\u6539\u6210\u62A5\u9519"
     );
   for (const [name, role] of Object.entries(def.roles ?? {}))
     if (permissionsOf(role).includes("admin"))
       warnings.push(
-        `roles.${name}: admin \u6743\u9650\u5DF2\u5F03\u7528\uFF0C\u5199\u4E86\u4E0D\u8D77\u4F5C\u7528\uFF1B\u7BA1\u7406\u6743\u9650\u6539\u7531\u5DE5\u574A\u4E0E\u9879\u76EE\u7684\u7BA1\u7406\u89D2\u8272\u7ED9\uFF08\u5DE5\u574A\u6210\u5458 workshop_members\u3001\u9879\u76EE\u6210\u5458 members.role\uFF09\u30022.0 \u8D77\u62A5\u9519`
+        `roles.${name}: admin \u6743\u9650\u5DF2\u5F03\u7528\uFF0C\u5199\u4E86\u4E0D\u8D77\u4F5C\u7528\uFF1B\u7BA1\u7406\u6743\u9650\u6539\u7531\u5DE5\u574A\u4E0E\u9879\u76EE\u7684\u7BA1\u7406\u89D2\u8272\u7ED9\uFF08\u5DE5\u574A\u6210\u5458 workshop_members\u3001\u9879\u76EE\u6210\u5458 members.role\uFF09\u3002\u4EE5\u540E\u7684\u534F\u8BAE\u5927\u7248\u672C\u4F1A\u6539\u6210\u62A5\u9519`
       );
   const types = def.artifactTypes ?? {};
   const repos = compileRepos(def, options, issues, warnings);
@@ -1492,14 +1492,14 @@ function compileWorkshop(input, options = {}) {
         const reservedFor = d.artifactType ? reservedTypeUse(d.artifactType) : void 0;
         if (d.artifactType && d.artifactType !== PASS_ARTIFACT_TYPE && reservedFor !== void 0) {
           warnings.push(
-            `${at}.needs: ${d.stage}:${d.artifactType} \u6307\u5411\u5E73\u53F0\u4FDD\u7559\u540D\uFF08${reservedFor}\uFF09\uFF1B\u7ED9\u5DE5\u574A\u7684\u4EA7\u7269\u7C7B\u578B\u6362\u4E2A\u540D\u5B57\u30022.0 \u8D77\u62A5\u9519`
+            `${at}.needs: ${d.stage}:${d.artifactType} \u6307\u5411\u5E73\u53F0\u4FDD\u7559\u540D\uFF08${reservedFor}\uFF09\uFF1B\u7ED9\u5DE5\u574A\u7684\u4EA7\u7269\u7C7B\u578B\u6362\u4E2A\u540D\u5B57\u3002\u4EE5\u540E\u7684\u534F\u8BAE\u5927\u7248\u672C\u4F1A\u6539\u6210\u62A5\u9519`
           );
         }
       }
       for (const w of bypasses(stages, st)) warnings.push(`${at}.needs: ${w}`);
       if (st.concept === "check" && st.deps.length === 0) {
         warnings.push(
-          `${at}: \u68C0\u67E5\u9636\u6BB5\u6CA1\u5199 needs\uFF0C\u6CA1\u6709\u4E1C\u897F\u53EF\u9A8C\uFF0C\u4E0D\u51FA\u5019\u9009\u4E5F\u4E0D\u53D1\u4EFB\u52A1\uFF1B\u5199\u4E0A\u8981\u9A8C\u7684\u4E0A\u6E38\u9636\u6BB5\u30022.0 \u8D77\u62A5\u9519`
+          `${at}: \u68C0\u67E5\u9636\u6BB5\u6CA1\u5199 needs\uFF0C\u6CA1\u6709\u4E1C\u897F\u53EF\u9A8C\uFF0C\u4E0D\u51FA\u5019\u9009\u4E5F\u4E0D\u53D1\u4EFB\u52A1\uFF1B\u5199\u4E0A\u8981\u9A8C\u7684\u4E0A\u6E38\u9636\u6BB5\u3002\u4EE5\u540E\u7684\u534F\u8BAE\u5927\u7248\u672C\u4F1A\u6539\u6210\u62A5\u9519`
         );
       }
       if (st.concept === "check" && st.fanOut !== void 0) {
@@ -1639,7 +1639,7 @@ function compileWorkshop(input, options = {}) {
   warnNonAgentStageAgent(workflows, warnings);
   if (typeof def.agent === "object")
     warnings.push(
-      `agent: { hubProject, slug } \u5199\u6CD5\u5DF2\u5F03\u7528\uFF1B\u5DE5\u574A\u7EA7 agent \u76F4\u63A5\u5199\u5DE5\u574A\u9879\u76EE\u91CC\u7684 agent slug\uFF08agent: ${def.agent.slug}\uFF09\uFF0C\u9636\u6BB5\u7EA7 agent \u8986\u76D6\u5B83\u3002\u6539\u5199\u540E\u8FD9\u4E2A agent \u8981\u5728 agents \u91CC\u58F0\u660E\uFF0C\u4E14\u4E0D\u518D\u6309\u539F hubProject \u6D3E\u53D1\u30022.0 \u8D77\u62A5\u9519`
+      `agent: { hubProject, slug } \u5199\u6CD5\u5DF2\u5F03\u7528\uFF1B\u5DE5\u574A\u7EA7 agent \u76F4\u63A5\u5199\u5DE5\u574A\u9879\u76EE\u91CC\u7684 agent slug\uFF08agent: ${def.agent.slug}\uFF09\uFF0C\u9636\u6BB5\u7EA7 agent \u8986\u76D6\u5B83\u3002\u6539\u5199\u540E\u8FD9\u4E2A agent \u8981\u5728 agents \u91CC\u58F0\u660E\uFF0C\u4E14\u4E0D\u518D\u6309\u539F hubProject \u6D3E\u53D1\u3002\u4EE5\u540E\u7684\u534F\u8BAE\u5927\u7248\u672C\u4F1A\u6539\u6210\u62A5\u9519`
     );
   const agents = compileAgents(
     def,
@@ -1777,7 +1777,7 @@ function compileRepos(def, options, issues, warnings) {
       issues.push("iteration: \u8FED\u4EE3\u65B9\u5F0F\u5199\u5728 repos.<\u540D>.iteration \u4E0A\uFF0C\u5DE5\u574A\u7EA7\u7684 iteration \u5220\u6389");
     } else {
       warnings.push(
-        "iteration: \u5DF2\u5F03\u7528\uFF0C\u4E0D\u518D\u8D77\u4F5C\u7528\uFF08\u5DE5\u574A\u4ED3\u5E93\u4E0D\u653E\u4EA7\u7269\uFF0C\u4E5F\u6CA1\u6709\u9879\u76EE\u5206\u652F\uFF09\uFF1B\u8981\u63D0\u4EA4\u4EE3\u7801\u7684\u4EA7\u7269\u5199\u5230 repos \u58F0\u660E\u7684\u76EE\u6807\u4ED3\u5E93\uFF0Citeration \u5199\u5728 repos.<\u540D> \u4E0A\u30022.0 \u8D77\u62A5\u9519"
+        "iteration: \u5DF2\u5F03\u7528\uFF0C\u4E0D\u518D\u8D77\u4F5C\u7528\uFF08\u5DE5\u574A\u4ED3\u5E93\u4E0D\u653E\u4EA7\u7269\uFF0C\u4E5F\u6CA1\u6709\u9879\u76EE\u5206\u652F\uFF09\uFF1B\u8981\u63D0\u4EA4\u4EE3\u7801\u7684\u4EA7\u7269\u5199\u5230 repos \u58F0\u660E\u7684\u76EE\u6807\u4ED3\u5E93\uFF0Citeration \u5199\u5728 repos.<\u540D> \u4E0A\u3002\u4EE5\u540E\u7684\u534F\u8BAE\u5927\u7248\u672C\u4F1A\u6539\u6210\u62A5\u9519"
       );
     }
   }
@@ -1819,7 +1819,9 @@ function compileRepos(def, options, issues, warnings) {
 function checkSurfaces(def, warnings) {
   const surfaces = def.views?.surfaces;
   if (surfaces === void 0) return;
-  warnings.push("views.surfaces: 1.x \u91CC\u8FD8\u6CA1\u6709\u6E32\u67D3\uFF0C\u5199\u4E86\u4E0D\u8D77\u4F5C\u7528\uFF1B\u5F62\u72B6\u5F85\u5B9A\uFF0C2.0 \u8D77\u6309 schema \u6821\u9A8C");
+  warnings.push(
+    "views.surfaces: \u5F53\u524D\u8FD8\u6CA1\u6709\u6E32\u67D3\uFF0C\u5199\u4E86\u4E0D\u8D77\u4F5C\u7528\uFF1B\u5F62\u72B6\u5F85\u5B9A\uFF0C\u4EE5\u540E\u7684\u534F\u8BAE\u5927\u7248\u672C\u4F1A\u6309 schema \u6821\u9A8C"
+  );
   for (const [name, fields] of Object.entries(surfaces)) {
     const at = `views.surfaces.${name}`;
     if (!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(name))
@@ -1877,7 +1879,7 @@ function checkArtifactTypes(def, repos, issues, warnings) {
     const reservedFor = reservedTypeUse(name);
     if (reservedFor !== void 0) {
       warnings.push(
-        `${at}: ${name} \u662F\u5E73\u53F0\u4FDD\u7559\u7684\u4EA7\u7269\u7C7B\u578B\u540D\uFF08${reservedFor}\uFF09\uFF0C\u6362\u4E2A\u540D\u5B57\u30022.0 \u8D77\u62A5\u9519`
+        `${at}: ${name} \u662F\u5E73\u53F0\u4FDD\u7559\u7684\u4EA7\u7269\u7C7B\u578B\u540D\uFF08${reservedFor}\uFF09\uFF0C\u6362\u4E2A\u540D\u5B57\u3002\u4EE5\u540E\u7684\u534F\u8BAE\u5927\u7248\u672C\u4F1A\u6539\u6210\u62A5\u9519`
       );
     }
     if (t.role === "process" && t.storage !== void 0 && t.storage !== "store") {
@@ -1901,7 +1903,7 @@ function checkArtifactTypes(def, repos, issues, warnings) {
     }
     if (t.repo === void 0 && t.paths === void 0) {
       warnings.push(
-        `${at}: storage: git \u8981\u5199 repo\uFF08repos \u91CC\u7684\u540D\u5B57\uFF09\u4E0E paths\uFF1B\u6CA1\u5199\u7684\u4EA7\u7269\u6CA1\u6709\u76EE\u6807\u4ED3\u5E93\uFF0C2.0 \u8D77\u62A5\u9519`
+        `${at}: storage: git \u8981\u5199 repo\uFF08repos \u91CC\u7684\u540D\u5B57\uFF09\u4E0E paths\uFF1B\u6CA1\u5199\u7684\u4EA7\u7269\u6CA1\u6709\u76EE\u6807\u4ED3\u5E93\uFF0C\u4EE5\u540E\u7684\u534F\u8BAE\u5927\u7248\u672C\u4F1A\u6539\u6210\u62A5\u9519`
       );
       continue;
     }
@@ -2094,7 +2096,7 @@ function checkPlugin(manifestPath, spec, within) {
   const entry = resolve(dirname(manifestPath), r.data.entry);
   const rel = relative(resolve(within), entry);
   if (rel.startsWith("..") || isAbsolute(rel)) {
-    return { spec, reason: `\u5165\u53E3 ${r.data.entry} \u8DF3\u51FA\u4E86 ${within}` };
+    return { spec, reason: `\u5165\u53E3 ${r.data.entry} \u8DF3\u51FA\u4E86\u4ED3\u5E93\u76EE\u5F55\uFF08\u5165\u53E3\u8981\u6307\u5411\u4ED3\u5E93\u91CC\u7684\u6587\u4EF6\uFF09` };
   }
   return {
     spec,