문서 로드와 콘텐츠 작업

AI Agent의 최소 콘텐츠 작업 흐름

각 콘텐츠 명령에서 업무 CLI가 대상 Unit을 로드하고 최신 내용을 동기화합니다. AI Agent 관점의 일반적인 흐름은 다음과 같습니다.

api find / api show, 읽기 모드, 최종 검토는 모두 조건에 따라 사용합니다. AI Agent는 다음 경계로 기능을 선택합니다.

예제: Sheet 범위 업데이트

‘book-1의 Data!A2:B2를 [["East", 128000]]로 변경’하는 작업을 가정합니다. 이 장의 뒤에서 설명할 업무 CLI 구성이 끝났다면 AI Agent는 다음 흐름을 사용합니다.

1. Inspection으로 워크북과 대상 범위를 이해합니다.

UNIT_ID="book-1"my-cli inspect workbook --unit "$UNIT_ID" --jsonmy-cli inspect range A1:B2 --worksheet name:Data --unit "$UNIT_ID" --json

2. API Reference를 보여주기 위해 AI Agent가 setValues를 모른다고 가정하고 검색·시그니처 확인을 합니다.

my-cli api find setValues --unit sheetmy-cli api show FWorkbook.getSheetByName FWorksheet.getRange FRange.setValues

3. 쓰기 모드로 Facade 코드를 실행합니다. 커밋은 애플리케이션 execute 명령이 담당합니다.

my-cli execute --unit "$UNIT_ID" --mode write \  --code 'const sheet = workbook.getSheetByName("Data");if (!sheet) throw new Error("Worksheet Data not found");sheet.getRange("A2:B2").setValues([["East", 128000]]);'

4. 작업 위험에 따라 검토 여부를 결정합니다. Inspection이 범위 값을 지원하므로 다시 읽습니다.

my-cli inspect range A2:B2 --worksheet name:Data --unit "$UNIT_ID" --json

이 작업은 쓰기 전후 범위를 Inspection으로 읽을 수 있어 읽기 모드가 필요 없습니다. Inspection이 다루지 않는 내용에만 사용하세요. 조건부 서식과 차트 설정 예제는 아래에 있습니다.

업무 CLI에 기능 구성

이 장은 @univer-cli/univer-collaboration-runtime부터 시작해 Inspection, API Reference, Content Execution을 추가합니다. 코드는 핵심 인터페이스를 보여주며 서버 설정, 신원, 오류 표시, 명령 인수는 업무 애플리케이션이 추가합니다.

모든 단계를 같은 Commander 루트 프로그램에 추가합니다.

import { Command } from "commander";const program = new Command("my-cli");// Register the inspect, execute, and api commands introduced below here.// Parse CLI arguments only after every command has been registered.await program.parseAsync();

1. 협업 Unit 로드

Collaboration Runtime은 Node.js의 AI Agent용 Unit¹ 실행 환경과 협업 클라이언트입니다. Runtime² 하나는 수명 주기 전체에서 Unit 하나에 바인딩됩니다.

import {  createCollaborationServerAdapter,  createUniverCollaborationRuntimeFactory,} from "@univer-cli/univer-collaboration-runtime";import { UniverInstanceType } from "@univerjs/core";const factory = createUniverCollaborationRuntimeFactory({  backend: createCollaborationServerAdapter({    snapshotServerUrl,    collabSubmitChangesetUrl,    collabWebSocketUrl,    wsSessionTicketUrl,  }),  createUniver: headlessUniverFactory,});const unitId = "book-1";const runtime = await factory.load(unitId, UniverInstanceType.UNIVER_SHEET);

애플리케이션은 headlessUniverFactory를 주입합니다. @univer-cli/headless-univer 표준 구현이나 자체 구성을 사용하며 초기화 세부는 여기서 생략합니다. 서버 설정, 신원, 대상 Unit을 어댑터가 요구하는 프로토콜 주소로 매핑합니다. Runtime은 스냅샷을 로드하고 리비전·변경 집합을 유지하며 Facade 실행을 제공합니다.

Runtime 핵심 API:

2. Inspection으로 내용 이해

AI Agent는 일반 읽기 작업마다 Facade 코드를 다시 작성할 필요가 없습니다. @univer-cli/content-inspection은 안정적이고 구조화된 읽기 전용 결과를 반환합니다.

Collaboration Runtime은 Inspection의 읽기 전용 실행 인터페이스에 직접 연결할 수 있습니다.

import { inspectContent } from "@univer-cli/content-inspection";const workbook = await inspectContent(  {    unitId: runtime.unitId,    unitType: "sheet",    execute: async (input) => {      const result = await runtime.execute(input);      return { value: result.value };    },  },  { kind: "workbook" },);

inspectContent()는 unitId로 읽기 전용 Facade 프로그램을 만들고 univerAPI.getWorkbook(unitId)로 대상 워크북을 찾습니다. unitType으로 쿼리와 Unit 유형 일치를 검증합니다.

개요 쿼리로 구조·주요 내용을 파악한 뒤 worksheet, range, paragraph, slide 선택자로 표준 내용을 읽습니다. 전체 조건부 서식 규칙이나 차트 설정처럼 필요한 세부가 Inspection 결과에 없을 때만 execute({ mode: "read" })로 최소한의 집중 쿼리를 실행합니다.

기본 Commander 상호작용에는 inspect preset을 추가합니다. 업무 애플리케이션은 Runtime lease만 제공합니다.

import type { ContentInspectionLease } from "@univer-cli/content-inspection-command";import { createContentInspectionCommand } from "@univer-cli/content-inspection-command";program.addCommand(  createContentInspectionCommand({    async acquireRuntime({ unitId }) {      const runtime = await factory.load(unitId, UniverInstanceType.UNIVER_SHEET);      await runtime.pull();      const lease: ContentInspectionLease = {        unitId,        unitType: "sheet",        execute: async (input) => {          const result = await runtime.execute(input);          return { value: result.value };        },        invalidate: () => runtime.close(),        release: () => runtime.close(),      };      return lease;    },  }),);

acquireRuntime은 preset의 공개 의존 필드이며 결과는 ContentInspectionLease를 따릅니다. 이 예제는 pool 없이 invalidate()와 release() 모두 전용 Runtime을 직접 닫습니다. preset은 선택자 파싱, 텍스트·JSON 출력, lease 해제를 담당합니다. 대상 매핑, Runtime 초기화, 인증, 원격 로드는 애플리케이션 책임입니다. 자체 AI Agent 프로토콜은 inspectContent()를 직접 호출하세요.

3. Facade API 검색과 이해

AI Agent가 작업은 알지만 API를 모르면 @univer-cli/api-reference를 사용합니다. 현재 SDK와 함께 배포되며 Unit 로드나 온라인 문서 서비스 접근이 필요 없습니다.

import { createStandardApiReference } from "@univer-cli/api-reference";const reference = createStandardApiReference();const matches = reference.find({  terms: ["setValues", "conditional formatting"],  unit: "sheet",  limit: 20,});const details = reference.show(["FRange", "FRange.setValues", "ICellData.v"]);

• find()는 작업 중심 용어로 후보 심벌을 검색합니다.
• show()는 클래스·멤버·타입·열거형의 정확한 정보를 반환합니다.
• @univer-cli/api-reference-command는 선택적인 api find, api show preset을 제공합니다.

같은 reference를 Commander에 직접 추가합니다.

import { createApiCommand } from "@univer-cli/api-reference-command";program.addCommand(createApiCommand({ reference }));

API Reference는 실행을 돕습니다. AI Agent는 현재 내용을 Inspect하고 관련 API를 Find/Show한 뒤 Facade 코드를 생성·실행할 수 있습니다.

4. Facade 읽기·쓰기 실행

유연한 조회와 수정에는 Runtime의 execute()를 사용합니다. @univer-cli/content-execution은 Facade JavaScript를 명시적 Unit에 바인딩하고 해당 유형의 안정적 바인딩을 주입할 수 있습니다.

import { prepareContentExecutionProgram } from "@univer-cli/content-execution";const executionProgram = prepareContentExecutionProgram({  unitId,  unitType: "sheet",  code: 'workbook.getActiveSheet().getRange("A1").setValue("done");',});const execution = await runtime.execute({  mode: "write",  code: executionProgram,});

• mode: "read"는 유연한 읽기 전용 쿼리이며 mutation을 금지합니다.
• mode: "write"는 Facade mutation을 수집하여 Runtime 로컬 대기 상태에 추가합니다.
• 실행 성공은 코드 실행을 뜻하며 서버에 변경 집합이 제출되었다는 뜻은 아닙니다.

content-execution은 실행 프로그램만 만듭니다. Runtime 획득, 변경 집합 제출, 공개 execute 명령 preset 패키지는 제공하지 않습니다. 따라서 업무 CLI가 애플리케이션 Commander 명령으로 감쌉니다.

const executeCommand = new Command("execute")  .requiredOption("--unit <id>")  .requiredOption("--code <javascript>")  .option("--mode <read|write>", "execute without or with mutations", "write")  .action(async ({ unit, code, mode }) => {    if (mode !== "read" && mode !== "write") {      throw new Error("--mode must be read or write");    }    const runtime = await factory.load(unit, UniverInstanceType.UNIVER_SHEET);    try {      await runtime.pull();      const executionProgram = prepareContentExecutionProgram({        unitId: unit,        unitType: "sheet",        code,      });      const execution = await runtime.execute({ mode, code: executionProgram });      if (mode === "read") {        process.stdout.write(`${JSON.stringify(execution.value, null, 2)}\n`);        return;      }      let committed = await runtime.commit();      if (committed.status === "pull-required") {        await runtime.pull();        committed = await runtime.commit();      }      if (committed.status !== "confirmed") {        throw new Error(`Commit failed: ${committed.status}`);      }      process.stdout.write(        `${JSON.stringify(          {            commit: committed.status,            mutations: execution.mutations.length,            revision: committed.state.baseRevision,            value: execution.value,          },          null,          2,        )}\n`,      );    } finally {      await runtime.close();    }  });program.addCommand(executeCommand);

이 명령의 기본값은 쓰기 모드입니다. 읽기는 Facade 반환값만 출력하며 mutation 생성이나 commit() 호출을 하지 않습니다. 쓰기는 커밋 확정 후 mutation 수, 리비전, 반환값을 출력하여 AI Agent가 제출 결과를 명확히 판단하게 합니다. Commander는 인수·명령 수명 주기를, 애플리케이션은 Runtime 획득, 커밋 재시도, 오류 표시, 권한 정책을 담당합니다. 이 최소 예제는 Sheet 고정입니다. Doc, Slide, Base, Board 지원 시 CLI Unit 유형에서 UniverInstanceType으로 명시적으로 매핑하세요.

Inspection이 다루지 않는 내용에만 읽기 모드 사용

Inspection은 워크시트의 조건부 서식 규칙 수를 알려주지만 각 규칙의 전체 설정은 포함하지 않습니다. 필요할 때 AI Agent는 API를 확인한 후 최소 Facade 코드를 읽기 모드로 실행합니다.

my-cli api find getConditionalFormattingRules --unit sheetmy-cli api show FWorksheet.getConditionalFormattingRulesmy-cli execute --unit "$UNIT_ID" --mode read \  --code 'const sheet = workbook.getSheetByName("Data");if (!sheet) throw new Error("Worksheet Data not found");return sheet.getConditionalFormattingRules();'

Inspection은 차트 개수도 알려줍니다. 전체 차트 설정이 필요하면 집중 쿼리에서 sheet.getCharts().map((chart) => chart.getInfo())를 반환합니다. 읽기 모드는 mutation을 금지하며 Inspection 미지원 내용을 보완합니다. 기본적으로 Inspection을 대체하지 않습니다.

정리

같은 Commander 프로그램에 Runtime, Inspection, API Reference, Content Execution이 구성되었습니다. Runtime은 로드·동기화·실행·수동 커밋, Inspection은 구조화된 읽기, API Reference는 AI Agent의 API 검색을 담당하며 Commander가 일관된 CLI 진입점으로 묶습니다.

일반 작업은 inspect로 구조·주요 내용·지원되는 표준 세부를 이해하며 시작합니다. API가 불명확하면 api find / api show를 사용합니다. Inspection 미지원 설정만 읽기 모드로 조회하고 쓰기 모드로 편집·커밋합니다. 검토에도 같은 Inspection 경계를 적용합니다.

다음 단계

Office 파일 가져오기·내보내기를 추가하여 파일을 UnitData로 바꿔 같은 작업 흐름에 사용하거나 최신 UnitData를 Office 파일로 내보냅니다.