refactor: simplify example commands

Author: OTime-Coder

README.md

@@ -19,7 +19,8 @@ so it can be copied and run independently.
 cd examples/01-content-operations
 pnpm install
 pnpm build
-pnpm server
+pnpm link-cli
+pnpm start-server
 ```
 
 After the Server starts, install the skill from another terminal in the same directory:
@@ -40,14 +41,15 @@ Use univer-content to create a sales spreadsheet with 10 sample records.
 cd examples/02-visual-inspection
 pnpm install
 pnpm build
-pnpm server
+pnpm link-cli
+pnpm start-server
 ```
 
 Use another terminal in the same `02-visual-inspection` directory:
 
 ```bash
-pnpm start create sheet --name "Visual Demo"
-pnpm start screenshot --unit <unit-id> --sheet Data --range A1:B2 --out output
+UNIT_ID=$(univer-example-cli create sheet --name "Visual Demo")
+univer-example-cli screenshot --unit "$UNIT_ID" --sheet Data --range A1:B2 --out output
 ```
 
 See each example README for its complete command sequence and verification steps.

README.zh-CN.md

@@ -18,7 +18,8 @@
 cd examples/01-content-operations
 pnpm install
 pnpm build
-pnpm server
+pnpm link-cli
+pnpm start-server
 ```
 
 Server 启动后，在同一个目录的另一个终端安装 skill：
@@ -39,14 +40,15 @@ pnpm skill:install
 cd examples/02-visual-inspection
 pnpm install
 pnpm build
-pnpm server
+pnpm link-cli
+pnpm start-server
 ```
 
 另开终端，仍在 `02-visual-inspection` 目录：
 
 ```bash
-pnpm start create sheet --name "Visual Demo"
-pnpm start screenshot --unit <unit-id> --sheet Data --range A1:B2 --out output
+UNIT_ID=$(univer-example-cli create sheet --name "Visual Demo")
+univer-example-cli screenshot --unit "$UNIT_ID" --sheet Data --range A1:B2 --out output
 ```
 
 完整命令和验证方式见各 example 的 README。

examples/01-content-operations/README.md

@@ -22,25 +22,27 @@ After entering this example, run every command from the current directory:
 ```bash
 pnpm install
 pnpm build
-pnpm server
+pnpm link-cli
+pnpm start-server
 ```
 
-Use another terminal in the same directory:
+Use another terminal in the same directory. `create` prints the new short Unit ID, so the remaining
+commands can capture and reuse it directly:
 
 ```bash
-pnpm start create sheet --name "Demo"
+UNIT_ID=$(univer-example-cli create sheet --name "Demo")
 
-pnpm start inspect range A1:B2 --worksheet index:1 \
-  --unit <unit-id> --json
+univer-example-cli inspect range A1:B2 --worksheet index:1 \
+  --unit "$UNIT_ID" --json
 
-pnpm start execute --unit <unit-id> \
+univer-example-cli execute --unit "$UNIT_ID" \
   --code 'workbook.getActiveSheet().getRange("A2:B2").setValues([["Updated", 2]])'
 
-pnpm start open --unit <unit-id>
+univer-example-cli open --unit "$UNIT_ID"
 
-# An Agent queries the Facade API before generating execution code
-pnpm start api find setValues --unit sheet
-pnpm start api show FRange.setValues
+# Simulate an Agent querying the Facade API before generating execution code
+univer-example-cli api find setValues --unit sheet
+univer-example-cli api show FRange.setValues
 ```
 
 ## Use it with an Agent
@@ -63,6 +65,7 @@ finished, run:
 
 ```bash
 pnpm skill:uninstall
+pnpm unlink-cli
 ```
 
 ## Source order

examples/01-content-operations/README.zh-CN.md

@@ -20,25 +20,26 @@ Web ──┘
 ```bash
 pnpm install
 pnpm build
-pnpm server
+pnpm link-cli
+pnpm start-server
 ```
 
-另开终端，仍在当前目录操作：
+另开终端，仍在当前目录操作。`create` 会输出新建 Unit 的短 ID，后续命令可以直接保存并复用：
 
 ```bash
-pnpm start create sheet --name "Demo"
+UNIT_ID=$(univer-example-cli create sheet --name "Demo")
 
-pnpm start inspect range A1:B2 --worksheet index:1 \
-  --unit <unit-id> --json
+univer-example-cli inspect range A1:B2 --worksheet index:1 \
+  --unit "$UNIT_ID" --json
 
-pnpm start execute --unit <unit-id> \
+univer-example-cli execute --unit "$UNIT_ID" \
   --code 'workbook.getActiveSheet().getRange("A2:B2").setValues([["Updated", 2]])'
 
-pnpm start open --unit <unit-id>
+univer-example-cli open --unit "$UNIT_ID"
 
-# Agent 在生成执行代码前查询 Facade API
-pnpm start api find setValues --unit sheet
-pnpm start api show FRange.setValues
+# 模拟 Agent 在生成执行代码前查询 Facade API
+univer-example-cli api find setValues --unit sheet
+univer-example-cli api show FRange.setValues
 ```
 
 ## 交给 Agent 使用
@@ -60,6 +61,7 @@ Agent 会创建、填充、提交和校验 Unit，并返回 Web 地址。Skill 
 
 ```bash
 pnpm skill:uninstall
+pnpm unlink-cli
 ```
 
 ## 源码顺序

examples/01-content-operations/package.json

@@ -3,21 +3,22 @@
   "version": "0.0.0",
   "private": true,
   "bin": {
-    "content-operations": "./dist/cli/main.js"
+    "univer-example-cli": "./dist/cli/main.js"
   },
   "type": "module",
   "scripts": {
     "build": "vite build && tsc -p tsconfig.node.json",
     "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm test",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
+    "link-cli": "pnpm link --global",
     "lint": "oxlint .",
     "skill:install": "node scripts/skill.mjs install",
     "skill:uninstall": "node scripts/skill.mjs uninstall",
-    "server": "node dist/server/main.js",
-    "start": "node dist/cli/main.js",
+    "start-server": "node dist/server/main.js",
     "test": "pnpm build && vitest run --root . test",
-    "typecheck": "tsc -p tsconfig.node.json --noEmit && tsc -p tsconfig.web.json --noEmit"
+    "typecheck": "tsc -p tsconfig.node.json --noEmit && tsc -p tsconfig.web.json --noEmit",
+    "unlink-cli": "pnpm remove --global @univer-cli-example/content-operations"
   },
   "dependencies": {
     "@univer-cli/api-reference": "1.0.0-insiders.20260822-0c0c0dd",

examples/01-content-operations/skills/univer-content/SKILL.md

@@ -5,19 +5,20 @@ description: Create and edit a collaborative Univer Sheet, Doc, or Slide when th
 
 # Work with Univer Content
 
-Use `pnpm start <command>` from the current `01-content-operations` directory. The user starts the
-Server separately with `pnpm server`.
+Use `univer-example-cli <command>`. The user starts the Server separately with
+`pnpm start-server` from the current `01-content-operations` directory.
 
 ## Workflow
 
 1. Choose `sheet`, `doc`, or `slide` from the request. Run
-   `pnpm start create <type> --name <name>` and retain the returned `unitId`.
+   `univer-example-cli create <type> --name <name>` and retain the returned `unitId`.
 2. Inspect the new Unit with the matching overview target: `workbook`, `document`, or
    `presentation`.
-3. Before using an unfamiliar Facade API, query it with `api find` and `api show`. Execution code
-   receives `workbook` for a Sheet, `doc` for a Doc, and `presentation` for a Slide.
-4. Run `pnpm start execute` once with the complete trusted Facade JavaScript change.
+3. Before using an unfamiliar Facade API, query it with `univer-example-cli api find` and
+   `univer-example-cli api show`. Execution code receives `workbook` for a Sheet, `doc` for a Doc,
+   and `presentation` for a Slide.
+4. Run `univer-example-cli execute` once with the complete trusted Facade JavaScript change.
 5. Require `commit: "confirmed"`, retain the returned revision, and do not retry a failed commit.
 6. Inspect the changed range, paragraph, or slide with `--json` and verify the requested content.
-7. Run `pnpm start open --no-launch` and return the Unit type, name, `unitId`, revision, and URL.
-   Open the browser only when the user asks.
+7. Run `univer-example-cli open --no-launch` and return the Unit type, name, `unitId`, revision, and
+   URL. Open the browser only when the user asks.

examples/01-content-operations/src/cli/features/unit.ts

@@ -23,7 +23,8 @@ export function createUnitCommand(): Command {
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ name: options.name, type }),
       });
-      process.stdout.write(`${JSON.stringify(await response.json(), undefined, 2)}\n`);
+      const { unitId } = (await response.json()) as { readonly unitId: string };
+      process.stdout.write(`${unitId}\n`);
     });
   return command;
 }

examples/01-content-operations/src/cli/program.ts

@@ -4,7 +4,7 @@ import { executeCommand, inspectCommand } from "./features/unit-content.js";
 import { createUnitCommand, openUnitCommand } from "./features/unit.js";
 
 export function createProgram(): Command {
-  const program = new Command("content-operations").description(
+  const program = new Command("univer-example-cli").description(
     "Create, inspect, edit, and view collaborative Univer content",
   );
   program.addCommand(createUnitCommand());

examples/01-content-operations/src/server/server.ts

@@ -46,7 +46,7 @@ export async function startServer(
 
   const app = express();
   app.post("/api/units", express.json(), async (request, response) => {
-    const unitId = randomUUID();
+    const unitId = randomUUID().slice(0, 8);
     const unitType = parseUnitType(request.body.type);
     const name = String(request.body.name ?? `Untitled ${unitTypeLabel(unitType)}`);
     const result = await service.createUnitFromData(createUnitInput(unitType, unitId, name), {

examples/01-content-operations/test/smoke.test.ts

@@ -16,10 +16,7 @@ afterEach(async () => await server?.close());
 
 it("creates, inspects, executes, and opens Sheet, Doc, and Slide units", async () => {
   server = await startServer(":memory:");
-  const created = JSON.parse(await run("create", "sheet", "--name", "Demo Sheet")) as {
-    readonly unitId: string;
-  };
-  const sheetId = created.unitId;
+  const sheetId = (await run("create", "sheet", "--name", "Demo Sheet")).trim();
 
   const before = await run(
     "inspect",
@@ -53,55 +50,51 @@ it("creates, inspects, executes, and opens Sheet, Doc, and Slide units", async (
   ) as Record<string, unknown>;
   expect(execution).toMatchObject({ commit: "confirmed", revision: 2, value: "done" });
 
-  const document = JSON.parse(await run("create", "doc", "--name", "Demo Doc")) as {
-    readonly unitId: string;
-  };
+  const documentId = (await run("create", "doc", "--name", "Demo Doc")).trim();
   expect(
-    JSON.parse(await run("inspect", "document", "--unit", document.unitId, "--json")),
+    JSON.parse(await run("inspect", "document", "--unit", documentId, "--json")),
   ).toMatchObject({ kind: "document", title: "Demo Doc" });
   expect(
     JSON.parse(
       await run(
         "execute",
         "--unit",
-        document.unitId,
+        documentId,
         "--code",
         'await api.executeCommand("doc.mutation.rename-doc", { unitId: doc.getId(), name: "Updated Doc" }); return doc.getName();',
       ),
     ),
   ).toMatchObject({ commit: "confirmed", revision: 2, value: "Updated Doc" });
   expect(
-    JSON.parse(await run("inspect", "document", "--unit", document.unitId, "--json")),
+    JSON.parse(await run("inspect", "document", "--unit", documentId, "--json")),
   ).toMatchObject({ title: "Updated Doc" });
 
-  const presentation = JSON.parse(await run("create", "slide", "--name", "Demo Slide")) as {
-    readonly unitId: string;
-  };
+  const presentationId = (await run("create", "slide", "--name", "Demo Slide")).trim();
   expect(
-    JSON.parse(await run("inspect", "presentation", "--unit", presentation.unitId, "--json")),
+    JSON.parse(await run("inspect", "presentation", "--unit", presentationId, "--json")),
   ).toMatchObject({ kind: "presentation", name: "Demo Slide" });
   expect(
     JSON.parse(
       await run(
         "execute",
         "--unit",
-        presentation.unitId,
+        presentationId,
         "--code",
         'presentation.setName("Updated Slide"); return presentation.getName();',
       ),
     ),
   ).toMatchObject({ commit: "confirmed", revision: 2, value: "Updated Slide" });
 
-  for (const unitId of [sheetId, document.unitId, presentation.unitId]) {
+  for (const unitId of [sheetId, documentId, presentationId]) {
     const url = await run("open", "--unit", unitId, "--no-launch");
     const page = await (await fetch(url.trim())).text();
     expect(page).toContain('id="sidebar"');
     expect(page).toContain('id="app"');
   }
   expect(await (await fetch(`${server.origin}/api/units`)).json()).toMatchObject([
     { name: "Demo Sheet", unitId: sheetId, unitType: "sheet" },
-    { name: "Demo Doc", unitId: document.unitId, unitType: "doc" },
-    { name: "Demo Slide", unitId: presentation.unitId, unitType: "slide" },
+    { name: "Demo Doc", unitId: documentId, unitType: "doc" },
+    { name: "Demo Slide", unitId: presentationId, unitType: "slide" },
   ]);
   expect(await run("api", "find", "setValues", "--unit", "sheet")).toContain("FRange.setValues");
   expect(await run("api", "show", "FRange.setValues")).toContain("setValues");
@@ -112,19 +105,18 @@ it("restores the file list and Unit from SQLite", async () => {
   const databaseFile = join(directory, "content.sqlite");
   try {
     server = await startServer(databaseFile);
-    const created = JSON.parse(await run("create", "sheet", "--name", "Persistent")) as {
-      readonly unitId: string;
-    };
+    const unitId = (await run("create", "sheet", "--name", "Persistent")).trim();
     await server.close();
     server = undefined;
 
     server = await startServer(databaseFile);
     expect(await (await fetch(`${server.origin}/api/units`)).json()).toMatchObject([
-      { name: "Persistent", unitId: created.unitId, unitType: "sheet" },
+      { name: "Persistent", unitId, unitType: "sheet" },
     ]);
-    expect(
-      JSON.parse(await run("inspect", "workbook", "--unit", created.unitId, "--json")),
-    ).toMatchObject({ name: "Persistent", unitId: created.unitId });
+    expect(JSON.parse(await run("inspect", "workbook", "--unit", unitId, "--json"))).toMatchObject({
+      name: "Persistent",
+      unitId,
+    });
   } finally {
     await server?.close();
     server = undefined;