using-univer-cli

使用 Univer CLI

这是处理工作簿和电子表格任务的入门技能。如果任务涉及工作簿文件、工作表、单元格、区域、公式、格式、图表、预览或 SaC 工作簿行为，请先加载此技能，再选择工具或编写代码。

如果任务有哪怕 1% 的可能涉及工作簿、电子表格、Excel 文件、工作表、单元格、区域、公式、图表、格式、预览或 SaC 工作簿行为，你就必须先使用此技能。

如果此技能适用，请勿先选择电子表格库。必须优先使用 Univer CLI 路径。

规则

在接触工作簿内容之前，先确定工作流。

digraph using_univer_cli {
    "Workbook task received" [shape=doublecircle];
    "Ordinary workbook-visible work?" [shape=diamond];
    "Load univer-cli" [shape=box];
    "Use workbook-visible verification" [shape=box];
    "SaC source or complex behavior?" [shape=diamond];
    "Load writing-univer-plans" [shape=box];
    "Success criteria then plan" [shape=box];
    "Load executing-univer-plans" [shape=box];
    "Execute the plan" [shape=box];
    "Load test-driven-univer-development" [shape=box];
    "TDD each pack from the plan" [shape=box];
    "Implement only after the assertion gate exists" [shape=box];
    "Verify and repair" [shape=box];

    "Workbook task received" -> "Ordinary workbook-visible work?";
    "Ordinary workbook-visible work?" -> "Load univer-cli" [label="yes"];
    "Load univer-cli" -> "Use workbook-visible verification";
    "Ordinary workbook-visible work?" -> "SaC source or complex behavior?" [label="no"];
    "SaC source or complex behavior?" -> "Load writing-univer-plans" [label="yes"];
    "Load writing-univer-plans" -> "Success criteria then plan";
    "Success criteria then plan" -> "Load executing-univer-plans";
    "Load executing-univer-plans" -> "Execute the plan";
    "Execute the plan" -> "Load test-driven-univer-development";
    "Load test-driven-univer-development" -> "TDD each pack from the plan";
    "TDD each pack from the plan" -> "Implement only after the assertion gate exists";
    "Implement only after the assertion gate exists" -> "Verify and repair";
}

SaC 源码编写必须遵循以下顺序：

1. 先确定成功标准，再制定计划：加载 writing-univer-plans，编写或更新 <package.univer>/success-criteria/<topic>.md，检查足够的工作簿可见证据， 并编写或更新 <package.univer>/plans/<topic>.md。
2. 执行计划：加载 executing-univer-plans，严格审查计划，并一次执行一个 Migration Pack。
3. 对照计划对每个 Pack 进行 TDD：加载 test-driven-univer-development，根据计划推导 assertions.ts 覆盖范围，并确认断言因预期的工作簿可见原因而失败。
4. 仅在断言门槛就绪后实施：只有在计划和基于计划的断言就绪后，才能编辑 Migration Pack。
5. 验证并修复：使用 univer sac verify <package.univer> --json，并依据返回的断言 证据进行修复，然后再声称已完成。

请勿在编写成功标准清单之前编写计划。 请勿在编写计划之前编写 assertions.ts。 请勿在编写基于计划的断言之前编辑 Migration Pack。 如果已按错误顺序执行任何步骤，请停止，根据当前证据补齐缺少的成功标准和计划，然后从该计划重新开始 TDD 循环。

硬性门槛

请勿将工作簿任务视为通用文件解析任务。请使用 Univer 技能体系和 univer CLI 作为工作簿引擎。

• 请勿导入或安装 exceljs、xlsx、pandas 或 LibreOffice 自动化等电子表格库来替代 Univer CLI。
• 请勿读取或修改 .univer 包内部内容。
• 如果任务可以通过 univer import、univer inspect、univer pipe、univer run、univer export 或 SaC 工作流处理，请勿直接解析 .xlsx 文件。
• 对 univer 生成的文本或 JSON 流（例如 pipe out 输出或命令 JSON），可以使用 Shell 工具。但它们不能替代工作簿引擎。
• 只有在加载相关 Univer 技能、确认 CLI 路径无法满足需求，并且用户同意使用替代方案后，才可考虑非 Univer 方案。

警示信号

出现以下想法时，请停止并改用 Univer CLI：

想法	实际情况
“这只是个 Excel 文件，我用 exceljs 就行。”	工作簿文件应优先使用 Univer CLI 处理。
“我只需要检查几个单元格。”	请使用 univer inspect、search、pipe out 或只读 run。
“我会直接解压或修改工作簿包。”	包内部内容不是编辑入口。
“我会通过包元数据或命令是否成功来验证。”	应验证工作簿可见状态。
“SaC apply 已通过，所以功能已经完成。”	完成 SaC 任务需要由测试驱动的 Univer 断言证据。

首要步骤

1. 确认工作簿制品和目标结果。
2. 在接触工作簿内容之前，将任务交由相应的 Univer 技能处理。
3. 使用路径优先的 univer 命令或 SaC 源码工作流；避免接触工作簿包内部内容。
4. 在声称任务已完成之前，使用工作簿可见证据进行验证。

路由详情

任务类型	使用方式
由 Harness 提供、带有专属本地约定、已准备好的包或必需交接产物的工作簿任务	首先遵循任务本地 Harness 约定，然后使用 univer-cli 和下方适用的工作簿或 SaC 路由
常规的工作簿可见操作，包括检查、搜索、导入、导出、管道、有限范围编辑、公式审查、预览、评论、提交、拉取或同步	univer-cli
SaC 源码编写、Facade Migration Pack 工作、assertions.ts、univer sac 或复杂工作簿行为开发	writing-univer-plans、executing-univer-plans，然后是 test-driven-univer-development
现有或旧版工作簿没有 SaC 源码，用户希望将其行为转换为 SaC 源码	使用 univer-cli 进行只读基线探测，然后使用 writing-univer-plans、executing-univer-plans 和 test-driven-univer-development

除非用户要求编写 SaC 源码或持久化的工作簿行为，否则常规的工作簿可见操作不应进入 SaC TDD 工作流。

对于常规的工作簿可见任务，加载 univer-cli，并通过工作簿可见方式进行验证。

SaC TDD 路由

对于 SaC 源码编写或复杂工作簿行为：

1. 在编辑迁移源码前，加载 writing-univer-plans。
2. 在 <package.univer>/success-criteria/ 下编写或更新包内成功标准， 然后在 <package.univer>/plans/ 下编写计划。
3. 加载 executing-univer-plans，逐个审查并执行计划包。
4. 加载 test-driven-univer-development，完成断言覆盖、应用／验证、修复 和交接门槛。

简而言之：加载 writing-univer-plans，定义成功标准并规划工作簿行为； 加载 executing-univer-plans，执行计划；加载 test-driven-univer-development，实现并 验证每个计划包。

复杂的 SaC 行为不得跳过 writing-univer-plans。计划是明确范围角色、计划包边界和断言门槛的地方。

旧版工作簿引导

当用户提供没有 SaC 源码的旧版工作簿时，使用 univer-cli 进行只读基线探测，例如检查、搜索、管道输出或只读运行脚本。在继续之前，将有用的信息记录到 SaC 计划、迁移源码或断言中。

只读基线探测不能作为完成凭证。SaC TDD 的完成凭证来自 test-driven-univer-development：已更改的计划包需要有断言覆盖，并且需要相关的 univer sac verify <package.univer> --json 运行通过。

完成凭证

• 常规工作簿任务需要通过 univer-cli 进行工作簿可见验证，例如 inspect、search、pipe out、有限范围 run、预览、评论或导出／导入检查。
• SaC TDD 任务需要 test-driven-univer-development 的凭证：断言覆盖，以及相关的 univer sac verify <package.univer> --json 运行通过。
• 不要将命令摘要、包元数据、univer sac apply 成功或只读探测视为最终 SaC TDD 证明。
• 如果任务类型不明确，请询问用户要进行常规工作簿编辑，还是编写持久化的 SaC 源码行为。