@kanyun-ai-infra/band-cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,12 @@
-# Temporary Holding Version
+# @kanyun-ai-infra/band-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`band`：写 Band 工坊和插件用的命令行。新建工坊与插件、`band dev` 本地起项目页调试、`band check` 校验、`band preview` / `band publish` 预览与发布工坊。
+
+```bash
+npm install -g @kanyun-ai-infra/band-cli
+band --help
+band new workshop ~/my-workshop --example video
+band dev ~/my-workshop
+```
+
+要 Node 22.19 以上。官方插件、示例工坊和给 Claude Code 用的 `band-plugin` skill 随包安装，版本跟着命令行走。用法见 Band 用户文档的「快速开始」与「band 命令行」两页。

package/bundled/examples/aitutor-tool/band/agent/instructions.md

@@ -0,0 +1,12 @@
+# 教具工坊说明
+
+这个工坊生产 1v1 课堂教具：一次迭代把一个教具从需求走到能过验收的新版本。流程是 规格 → 策略 → 研发 → 自动检查 → 验收 → 发布 → 回填；回合输入的 `stage` 说明当前在哪一步，开工前先读本阶段说明（`.agent/workshop/stages/<阶段>.md`）。
+
+## 按仓库里的 skill 干活
+
+规格、策略、工程的具体模板和检查项在教具仓库自带的 skill 里（`develop-tool-strategy`、`develop-tool-engineering`）。仓库里没有对应 skill 时，停下来在回执里说明缺什么，不自己发明格式。
+
+## 处理意见
+
+- 意见挂在教具元素上时，锚点带源码戳（`src`，形如 `src/renderer/Tree.vue:6`）：先看那一行再改。
+- 只改意见要的东西。对外指令有增删改时，同步更新变更声明（`变更声明.json`），备课侧靠它判断要不要迁移。

package/bundled/examples/aitutor-tool/band/agent/stages/backfill.md

@@ -0,0 +1,3 @@
+# 回填阶段
+
+本阶段挂内容仓库：把发布版本装进专题，照内容仓库的 `refresh-teaching-tools`——装到 `产出/assets/teaching-tools/<教具>/<版本>/`，登记进专题的 componentRegistry。专题里已有别的版本时，迁移要老师确认（本阶段门禁由教研批准），不悄悄改专题。

package/bundled/examples/aitutor-tool/band/agent/stages/engineering.md

@@ -0,0 +1,3 @@
+# 研发阶段
+
+按指令集写 Model 与 Renderer 源码，构建出 bundle，照 `develop-tool-engineering`。bundle 是构建产物（不进仓库，直接交 store 产物）：IIFE 构建包、`manifest.json`、场景用例 `cases/*.json` —— 把配置说明里的示例场景转成用例放进去，格式是 `initData` 加逐步指令。评审用的预览只读这一版的文件，意见都落在它上面。

package/bundled/examples/aitutor-tool/band/agent/stages/spec.md

@@ -0,0 +1,5 @@
+# 规格阶段（Gate R2）
+
+本阶段只写规格：实体、交互、状态模型、设计契约，照教具仓库 `_spec/` 的模板与 `develop-tool-strategy` 的第一段。写完就停，在回执里说明规格在哪：规格要过 Gate R2（教研与研发都批准），批准前不写指令集和代码。
+
+规格里带「验收看什么」一节，写要人判断的（设计判断、生命周期与体量、操作、与板书共存）；能自动查的（入口体量、资源声明、E2E、性能、设计规范）归检查阶段，不写给人看。

package/bundled/examples/aitutor-tool/band/agent/stages/strategy.md

@@ -0,0 +1,10 @@
+# 策略阶段
+
+按批准的规格写四份文档，照 `develop-tool-strategy` 的第二段：
+
+- 原子指令集（对外 API 契约，一条指令一件事，参数与错误码写全）；
+- 使用手册（给备课 Agent 读）；
+- 配置说明（工程配置与模型上下文的 schema，至少两个示例场景）；
+- 变更声明（对外指令相对上一版的增删改）。
+
+指令集是备课与课件的依赖，改动要在变更声明里看得出来。

package/bundled/examples/aitutor-tool/band/dev/fixture.ts

@@ -0,0 +1,500 @@
+/**
+ * `band dev` 用的教具夹具：一个教具「植树问题线段图」的一次迭代，走到验收。
+ * - 需求单是 GitLab Issue 的快照（外部产物），规格、指令集、使用手册、配置说明、变更声明、源码是 git 产物，
+ *   构建产物（bundle）两版：1.0.3 的棵数编号压在段长标注上，设计在预览里点了那个数字提意见，Rondo 改出 1.0.4。
+ * - 验收阶段：#1 已改好、设计确认过；#2、#3 还开着，所以教研和设计都还没批，发布阶段等验收。
+ * 所有内容都是为示例写的，不是业务仓库里的文件；教具源码见 tool-bundle.ts。当前成员是教研。
+ */
+import type { FixtureData } from "@kanyun-ai-infra/band-kernel/fixture";
+import type { Comment, ThreadView, Version } from "@kanyun-ai-infra/band-plugin-sdk";
+import { bundleFiles } from "./tool-bundle.ts";
+
+const PROJECT = "prj_tree_line";
+const RUN = "run_tree_line_2";
+const EXTERNAL = "application/vnd.band.external+json";
+
+type Entry = Version["entries"][number];
+
+const entry = (
+  path: string,
+  c: string,
+  mime: string,
+  storage: Entry["storage"] = "git",
+): Entry => ({
+  path,
+  sha256: c.repeat(64),
+  size: 800,
+  mime,
+  storage,
+  ref: storage === "git" ? `c${c}` : `store:${c}`,
+});
+
+const version = (
+  id: string,
+  artifactId: string,
+  c: string,
+  at: string,
+  label: string,
+  entries: Entry[],
+  author: Version["author"] = { kind: "agent", id: "rondo" },
+): Version => ({
+  id,
+  artifactId,
+  meta: { label },
+  hash: c.repeat(64),
+  entries,
+  provenance: [{ inputs: [], at }],
+  author,
+  createdAt: at,
+});
+
+const mimeOf = (path: string) =>
+  path.endsWith(".json")
+    ? "application/json"
+    : path.endsWith(".js")
+      ? "text/javascript"
+      : path.endsWith(".md")
+        ? "text/markdown"
+        : path.endsWith(".yaml")
+          ? "application/yaml"
+          : "text/plain";
+
+const bundle = (id: string, c: string, at: string, v: "1.0.3" | "1.0.4") => {
+  const files = bundleFiles(v);
+  return {
+    version: version(
+      id,
+      "art_bundle",
+      c,
+      at,
+      `v${v}`,
+      Object.keys(files).map((p) => entry(p, c, mimeOf(p), "store")),
+    ),
+    files,
+  };
+};
+
+const REQUIREMENT = JSON.stringify({
+  source: {
+    platform: "gitlab-issue",
+    url: "https://gitlab.example.com/aitutor/teaching-tools/-/issues/218",
+    title: "【需求】植树问题线段图（三年级 · 植树问题）",
+    fetchedAt: "2026-10-19T02:00:00Z",
+  },
+  blocks: [
+    { id: "h1", kind: "heading", text: "植树问题线段图" },
+    { id: "p1", kind: "paragraph", text: "课程：三年级 · 植树问题。优先级：P1。" },
+    {
+      id: "p2",
+      kind: "paragraph",
+      text: "老师边讲边在线段上分段、种树，学生看清「段数」和「棵数」的关系：两端都种、两端都不种、只种一端三种情况。",
+    },
+    { id: "l1", kind: "list-item", text: "老师能指定全长和间隔，间隔除不尽时要提示" },
+    { id: "l2", kind: "list-item", text: "能高亮某一段，讲「一段对应一棵树」" },
+    { id: "l3", kind: "list-item", text: "整行占位，放在例题下面" },
+  ],
+});
+
+const SPEC = `# 植树问题线段图 · 规格
+
+## 实体
+- 线段：全长（整数，单位随初始数据）
+- 段：由间隔切出，间隔必须整除全长
+- 树：按端点规则种在分点上，带编号
+
+## 交互
+- 老师一句话对应一条指令；分段、种树、高亮分开下发
+
+## 状态
+\`{ total_length, interval_length, ends, trees, highlighted }\`，每条指令后提交一次
+
+## 设计契约
+- 颜色全部取宿主下发的设计变量，深色下可读
+- 编号、标注互不重叠
+
+## 验收看什么
+验收人在教具预览里把场景用例都跑一遍，有问题直接在那一步或那个元素上标注；意见都确认后再批准。
+- 讲的是板书讲不清的点，一个教具只服务一个知识点
+- 同一份初始数据重进得到同样画面，回退一步不残留状态
+- 老师一句话最多两条指令，指令名能读懂，非法参数报出可读的错误码
+- 占位与清单声明一致，文字不压线、不重叠，深色下可读
+- 入口体量、资源声明、E2E 由自动检查阶段覆盖（业务 CI 里要有对应检查），不用人再看
+`;
+
+const INSTRUCTIONS = `# 原子指令集（对外契约）
+show:
+  attrs: { total_length: { type: integer, min: 1 } }
+mark_intervals:
+  attrs: { interval_length: { type: integer, min: 1 } }
+  errors: [NOT_SHOWN, INTERVAL_NOT_DIVISIBLE]
+plant_trees:
+  attrs: { ends: { enum: [both, none, one] } }
+  errors: [NO_INTERVALS]
+highlight_segment:
+  attrs: { index: { type: integer, min: 0 } }
+`;
+
+const MANUAL = `# 植树问题线段图 · 使用手册
+
+给备课 Agent 读。
+
+1. 先 \`show\` 出全长，再 \`mark_intervals\` 分段，最后 \`plant_trees\`。
+2. 讲「一段对应一棵树」时用 \`highlight_segment\`，一次只高亮一段。
+3. 间隔要能整除全长，否则教具报 \`INTERVAL_NOT_DIVISIBLE\`，课件里不要出现这种组合。
+`;
+
+const CONFIG = `# 配置说明
+
+- initData.title：线段上方的题目
+- initData.unit：长度单位，默认「米」
+
+示例场景见构建产物的 cases/：两端都种、两端都不种。
+`;
+
+const CHANGE_DECL = `${JSON.stringify(
+  {
+    version: "1.0.4",
+    previous: "1.0.3",
+    instructions: { added: [], removed: [], changed: [] },
+    notes: "只改渲染：棵数编号挪到树上方，指令不变，备课侧无需迁移",
+  },
+  null,
+  2,
+)}\n`;
+
+const TREE_SRC = `<template>
+  <g :data-tool-id="'tree-' + n">
+    <rect class="trunk" />
+    <circle class="crown" />
+    <text :y="NUMBER_Y" class="no">{{ n }}</text>
+  </g>
+</template>
+`;
+
+const b1 = bundle("ver_bundle_1", "3", "2026-10-21T06:10:00.000Z", "1.0.3");
+const b2 = bundle("ver_bundle_2", "4", "2026-10-22T03:30:00.000Z", "1.0.4");
+
+const human = (id: string) => ({ kind: "human" as const, id });
+
+const thread = (
+  id: string,
+  mark: number,
+  at: string,
+  status: ThreadView["status"],
+  by: string,
+  anchor: ThreadView["anchor"],
+  excerpt: string,
+): ThreadView => ({
+  id,
+  projectId: PROJECT,
+  runId: RUN,
+  artifactId: "art_bundle",
+  anchorId: anchor.id,
+  mark,
+  status,
+  createdBy: human(by),
+  createdAt: at,
+  updatedAt: at,
+  anchor,
+  excerpt,
+});
+
+const comment = (
+  id: string,
+  threadId: string,
+  at: string,
+  by: string,
+  body: string,
+  receipt?: Comment["receipt"],
+): Comment => ({
+  id,
+  threadId,
+  kind: receipt ? "receipt" : "comment",
+  author: receipt ? { kind: "agent", id: "rondo" } : human(by),
+  body,
+  mentions: [],
+  ...(receipt ? { receipt } : {}),
+  createdAt: at,
+});
+
+export const fixture: FixtureData = {
+  projectId: PROJECT,
+  runId: RUN,
+  versions: [
+    version(
+      "ver_req_1",
+      "art_req",
+      "1",
+      "2026-10-19T02:00:00.000Z",
+      "#218",
+      [
+        {
+          ...entry("issue.json", "1", EXTERNAL, "external"),
+          ref: "gitlab-issue:aitutor/teaching-tools#218",
+          sourceRevision: "2026-10-19T02:00:00Z",
+        },
+      ],
+      human("liuyan"),
+    ),
+    version("ver_spec_1", "art_spec", "2", "2026-10-19T08:00:00.000Z", "v1", [
+      entry("_spec/tree-planting-line-spec.md", "2", "text/markdown"),
+    ]),
+    version("ver_instr_1", "art_instr", "5", "2026-10-20T03:00:00.000Z", "v1", [
+      entry("原子指令集.yaml", "5", "application/yaml"),
+    ]),
+    version("ver_manual_1", "art_manual", "6", "2026-10-20T03:00:00.000Z", "v1", [
+      entry("使用手册.md", "6", "text/markdown"),
+    ]),
+    version("ver_config_1", "art_config", "7", "2026-10-20T03:00:00.000Z", "v1", [
+      entry("配置说明/README.md", "7", "text/markdown"),
+    ]),
+    version("ver_decl_1", "art_decl", "8", "2026-10-22T03:30:00.000Z", "v1.0.4", [
+      entry("变更声明.json", "8", "application/json"),
+    ]),
+    version("ver_src_1", "art_src", "9", "2026-10-22T03:30:00.000Z", "v1.0.4", [
+      entry("src/renderer/Tree.vue", "9", "text/plain"),
+    ]),
+    b1.version,
+    b2.version,
+  ],
+  files: {
+    ver_req_1: { "issue.json": REQUIREMENT },
+    ver_spec_1: { "_spec/tree-planting-line-spec.md": SPEC },
+    ver_instr_1: { "原子指令集.yaml": INSTRUCTIONS },
+    ver_manual_1: { "使用手册.md": MANUAL },
+    ver_config_1: { "配置说明/README.md": CONFIG },
+    ver_decl_1: { "变更声明.json": CHANGE_DECL },
+    ver_src_1: { "src/renderer/Tree.vue": TREE_SRC },
+    ver_bundle_1: b1.files,
+    ver_bundle_2: b2.files,
+  },
+  artifacts: [
+    { id: "art_req", name: "需求单", artifactType: "requirement" },
+    { id: "art_spec", name: "规格", artifactType: "spec" },
+    { id: "art_instr", name: "原子指令集", artifactType: "instructions" },
+    { id: "art_manual", name: "使用手册", artifactType: "manual" },
+    { id: "art_config", name: "配置说明", artifactType: "config" },
+    { id: "art_decl", name: "变更声明", artifactType: "change-decl" },
+    { id: "art_src", name: "教具源码", artifactType: "tool-src" },
+    { id: "art_bundle", name: "植树问题线段图", artifactType: "bundle" },
+  ],
+  threads: [
+    thread(
+      "thr_1",
+      1,
+      "2026-10-21T07:02:00.000Z",
+      "resolved",
+      "chenxi",
+      {
+        id: "anc_thr_1",
+        versionId: "ver_bundle_1",
+        kind: "plugin:@aitutor/tool-preview/element",
+        payload: {
+          caseId: "both-ends",
+          step: 3,
+          selector: '[data-tool-id="tree-no-2"]',
+          toolId: "tree-no-2",
+          src: "src/renderer/Tree.vue:6",
+          label: "两端都种 · 第 3 步后 · 「2」",
+        },
+        snapshot: "2",
+      },
+      "棵数编号压在段长标注上了，挪到树上方。",
+    ),
+    thread(
+      "thr_2",
+      2,
+      "2026-10-22T05:40:00.000Z",
+      "open",
+      "liuyan",
+      {
+        id: "anc_thr_2",
+        versionId: "ver_bundle_2",
+        kind: "plugin:@aitutor/tool-preview/step",
+        payload: {
+          caseId: "no-ends",
+          step: 3,
+          action: "mark_intervals",
+          label: "两端都不种 · 第 4 步 mark_intervals",
+        },
+        snapshot: "mark_intervals(interval_length: 7)",
+      },
+      "报错文案老师看不懂，改成「间隔要能整除全长」，错误码保留。",
+    ),
+    thread(
+      "thr_3",
+      3,
+      "2026-10-22T06:15:00.000Z",
+      "open",
+      "chenxi",
+      {
+        id: "anc_thr_3",
+        versionId: "ver_bundle_2",
+        kind: "plugin:@aitutor/tool-preview/element",
+        payload: {
+          caseId: "both-ends",
+          step: 3,
+          selector: '[data-tool-id="tree-1"]',
+          toolId: "tree-1",
+          src: "src/renderer/Tree.vue:2",
+          label: "两端都种 · 第 3 步后 · 第 1 棵树",
+        },
+        snapshot: "第 1 棵树",
+      },
+      "深色模式下树干颜色发灰，跟背景分不开。",
+    ),
+  ],
+  comments: [
+    comment(
+      "cmt_1",
+      "thr_1",
+      "2026-10-21T07:02:00.000Z",
+      "chenxi",
+      "棵数编号压在段长标注上了，挪到树上方。",
+    ),
+    comment(
+      "cmt_2",
+      "thr_1",
+      "2026-10-22T03:30:00.000Z",
+      "",
+      "编号从树右下方挪到树冠正上方，不再和段长标注挤在一行，其余不变。",
+      {
+        turnId: "turn_3",
+        outcome: "changed",
+        files: ["src/renderer/Tree.vue"],
+        versionId: "ver_bundle_2",
+      },
+    ),
+    comment(
+      "cmt_3",
+      "thr_2",
+      "2026-10-22T05:40:00.000Z",
+      "liuyan",
+      "报错文案老师看不懂，改成「间隔要能整除全长」，错误码保留。",
+    ),
+    comment(
+      "cmt_4",
+      "thr_3",
+      "2026-10-22T06:15:00.000Z",
+      "chenxi",
+      "深色模式下树干颜色发灰，跟背景分不开。",
+    ),
+  ],
+  stages: [
+    { stage: "intake", name: "提需", kind: "human", status: "approved", versionId: "ver_req_1" },
+    {
+      stage: "spec",
+      name: "规格（Gate R2）",
+      kind: "agent",
+      gated: true,
+      status: "approved",
+      versionId: "ver_spec_1",
+    },
+    { stage: "strategy", name: "策略", kind: "agent", gated: true, status: "approved" },
+    {
+      stage: "engineering",
+      name: "研发",
+      kind: "agent",
+      status: "approved",
+      versionId: "ver_bundle_2",
+    },
+    { stage: "checks", name: "自动检查", kind: "job", status: "approved" },
+    { stage: "acceptance", name: "验收", kind: "human", gated: true, status: "in_review" },
+    { stage: "publish", name: "发布", kind: "job", status: "blocked" },
+  ],
+  gates: [
+    {
+      stage: "spec",
+      name: "规格（Gate R2）",
+      status: "approved",
+      approvedBy: ["liuyan", "wanglei"],
+      approveBy: ["research", "dev"],
+      mode: "all",
+    },
+    {
+      stage: "strategy",
+      name: "策略",
+      status: "approved",
+      approvedBy: ["liuyan"],
+      approveBy: ["research"],
+    },
+    {
+      stage: "acceptance",
+      name: "验收",
+      status: "in_review",
+      approvedBy: [],
+      approveBy: ["research", "design"],
+      mode: "all",
+    },
+  ],
+  members: [
+    {
+      actor: human("liuyan"),
+      displayName: "刘妍",
+      roles: ["research"],
+      roleLabels: { research: "教研" },
+    },
+    {
+      actor: human("wanglei"),
+      displayName: "王磊",
+      roles: ["dev"],
+      roleLabels: { dev: "教具研发" },
+    },
+    {
+      actor: human("chenxi"),
+      displayName: "陈曦",
+      roles: ["design"],
+      roleLabels: { design: "设计" },
+    },
+    { actor: { kind: "agent", id: "rondo" }, displayName: "Rondo", roles: [] },
+  ],
+  turn: {
+    current: null,
+    last: { number: 3, summary: "棵数编号挪到树上方", at: "2026-10-22T03:30:00.000Z" },
+    queue: [],
+  },
+  activity: [
+    {
+      id: "act_5",
+      at: "2026-10-22T06:15:00.000Z",
+      actor: human("chenxi"),
+      action: "thread.create",
+      text: "陈曦 在「第 1 棵树」上提了意见 #3",
+      threadId: "thr_3",
+      artifactId: "art_bundle",
+    },
+    {
+      id: "act_3",
+      at: "2026-10-22T05:40:00.000Z",
+      actor: human("liuyan"),
+      action: "thread.create",
+      text: "刘妍 在指令「mark_intervals」上提了意见 #2",
+      threadId: "thr_2",
+      artifactId: "art_bundle",
+    },
+    {
+      id: "act_2",
+      at: "2026-10-22T04:05:00.000Z",
+      actor: { kind: "agent", id: "rondo" },
+      action: "stage.approved",
+      text: "自动检查通过：结构校验、入口体量、资源声明、增量 E2E、性能、设计规范",
+      stage: "checks",
+    },
+    {
+      id: "act_1",
+      at: "2026-10-22T03:30:00.000Z",
+      actor: { kind: "agent", id: "rondo" },
+      action: "version.created",
+      text: "Rondo 交付 植树问题线段图 v1.0.4 · 编号挪到树上方",
+      artifactId: "art_bundle",
+      versionId: "ver_bundle_2",
+    },
+  ],
+};
+
+export const member = {
+  id: "liuyan",
+  displayName: "教研 · 刘妍",
+  roles: ["research"],
+  permissions: ["comment", "submit-change", "confirm", "approve"],
+};

package/bundled/examples/aitutor-tool/band/dev/resources.ts

@@ -0,0 +1,40 @@
+/**
+ * `band dev` 用的内容平台模拟接口（只读）：`GET /by-project/{projectId}` 给出教具的正式版、测试版，
+ * 以及引用它的专题各装到了哪一版。只在内存里，不连任何真实接口。
+ */
+import type { ProxyRequest } from "@kanyun-ai-infra/band-kernel";
+import type { ToolRelease } from "../views/release/index.ts";
+
+const RELEASES: Record<string, ToolRelease> = {
+  prj_tree_line: {
+    toolId: "tree-planting-line",
+    online: { version: "1.0.2", at: "2026-10-12T09:00:00.000Z" },
+    beta: { version: "1.0.4-beta.1", at: "2026-10-22T04:20:00.000Z" },
+    topics: [
+      { topic: "三年级 · 植树问题（一）", version: "1.0.2" },
+      { topic: "三年级 · 植树问题（二）", version: "1.0.2" },
+      { topic: "四年级 · 间隔问题综合", version: "1.0.1" },
+    ],
+  },
+};
+
+export interface MockTeachingTools {
+  (req: ProxyRequest): Promise<Response>;
+  readonly calls: ProxyRequest[];
+}
+
+export function mockTeachingTools(): MockTeachingTools {
+  const calls: ProxyRequest[] = [];
+  const handler = async (req: ProxyRequest): Promise<Response> => {
+    calls.push(req);
+    const m = /^\/by-project\/([^/?]+)$/.exec(req.path);
+    const r = m?.[1] ? RELEASES[decodeURIComponent(m[1])] : undefined;
+    if (req.method === "GET" && r) {
+      return new Response(JSON.stringify(r), { headers: { "content-type": "application/json" } });
+    }
+    return new Response(JSON.stringify({ error: "not found" }), { status: 404 });
+  };
+  return Object.assign(handler, { calls });
+}
+
+export const resources = { "teaching-tools": mockTeachingTools() };