writing-univer-plans

编写 Univer 计划

在编写任何 SaC 断言或迁移源代码之前，先编写工作簿领域的成功标准和计划。成功标准将目标结果锁定为一份检查清单。计划是以源码为先的编写产物，而不只是聊天记录。

这不是通用的软件规划。该计划旨在明确电子表格行为：Excel 领域含义、区域角色、公式、格式、验证、保留边界和断言门槛。

如果涉及复杂的 SaC 工作簿行为，编写 `assertions.ts` 或编辑 Migration Packs 之前，必须先编写或更新工作区计划。

如果此技能适用，必须先编写成功标准，其次是计划，然后是断言，最后是迁移源代码。

规则

在执行之前，先在源文件中确定工作簿行为。

digraph writing_univer_plans {
    "SaC workbook task received" [shape=doublecircle];
    "Write success criteria checklist" [shape=box];
    "Read workbook evidence" [shape=box];
    "Classify range roles" [shape=box];
    "Resolve workbook behavior decisions" [shape=box];
    "Decompose Migration Packs" [shape=box];
    "Define assertion gates" [shape=box];
    "Write plan file" [shape=box];
    "Plan self-review" [shape=box];
    "Ready for executing-univer-plans" [shape=doublecircle];

    "SaC workbook task received" -> "Write success criteria checklist";
    "Write success criteria checklist" -> "Read workbook evidence";
    "Read workbook evidence" -> "Classify range roles";
    "Classify range roles" -> "Resolve workbook behavior decisions";
    "Resolve workbook behavior decisions" -> "Decompose Migration Packs";
    "Decompose Migration Packs" -> "Define assertion gates";
    "Define assertion gates" -> "Write plan file";
    "Write plan file" -> "Plan self-review";
    "Plan self-review" -> "Ready for executing-univer-plans";
}

不要在编写或更新成功标准之前编写计划。 不要在计划之前编写 assertions.ts。 不要在基于计划的断言完成之前编辑 Migration Packs。 如果已经有步骤顺序错误，请停下来，根据当前工作簿证据编写缺失的成功标准和计划，然后从计划开始重新执行。

先编写成功标准

在编写工作区计划之前，创建或更新：

<package.univer>/success-criteria/<topic>.md

此文件应是一份简短的检查清单，而不是计划。它应在开始深入分析工作簿之前，将用户任务转化为通过条件。

使用以下格式：

# <Feature Name> Success Criteria

**Task:** <one-sentence restatement of the user task>
**Source:** <workbook/package, user prompt, files, or commands that define the task>

## Success Checklist

- [ ] <user-visible outcome>
- [ ] <preservation or negative constraint>
- [ ] <required deliverable or output>
- [ ] <validation signal>

## Explicit Non-Goals

- [ ] <out-of-scope behavior>

## Ambiguities To Resolve In Plan

- <question the plan must resolve with evidence, probes, or an explicit assumption>

成功标准可以列出可见结果、保留约束、所需交付物、验证信号、明确的非目标和待澄清事项。

• 不要包含 Migration Packs。
• 不要包含 assertions.ts 的设计。
• 不要包含 TDD 步骤。
• 不要包含应用／验证修复策略。
• 不要包含需要工作簿证据才能确定的公式／区域映射决策；应将这些列为计划中的待澄清事项。

硬性门槛

只有在计划足以指导断言优先的实现时，计划才算完整。

• 不要只在聊天记录中保留工作簿含义。
• 不要凭对“电子表格通常如何工作”的直觉着手编写 Migration Packs。
• 不要将示例、答案区域或预览窗口视为目标输出，除非已记录其依据。
• 不要将有歧义的领域决策当作已证实的事实；如果它们只是假设，就应明确标注。
• 如果有任何变更的 pack 缺少断言门槛，不要移交执行。
• 复杂行为的工作簿行为契约选项尚未在计划中明确之前，不要移交执行。

范围检查

编写 pack 任务之前，检查请求涉及的是一种连贯的工作簿行为，还是多个独立的工作簿交付物。

如果任务包含可以分别验证和交付的独立工作表、源模型、报告系列或工作流，请拆分为单独的计划。只有当这些 pack 具有一个共同的、在工作簿中可见的目标，并且可以通过一条连贯的验证命令进行验证时，才保留为一个计划。

如果范围过于宽泛，请停下来询问应先规划哪个工作簿交付物。不要创建一份掩盖独立断言门槛的庞大计划。

源文件映射

定义 pack 任务之前，先映射计划预期执行时会涉及的文件：

• 成功标准：<package.univer>/success-criteria/<topic>.md
• 计划：<package.univer>/plans/<topic>.md
• 断言：<package.univer>/migrations/<pack>/assertions.ts
• Migration Packs：<package.univer>/migrations/<pack>/
• 固定测试数据或只读探查：用作证据的确切工作簿路径、工作表、区域或命令

说明每个文件的职责。这样可以在开始执行之前，明确工作簿意图、断言、迁移源代码和证据之间的边界。

输出位置

在 SaC 工作区中创建或更新成功标准和计划文件：

<package.univer>/success-criteria/<topic>.md
<package.univer>/plans/<topic>.md

如果项目已有命名约定，请沿用。成功标准应靠近计划，以便后续 Agent 能区分目标检查清单与推理和执行设计。

计划文档标题

每份计划都必须以以下标题开头：

# <Feature Name> Univer Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use `executing-univer-plans` to
> execute this plan pack-by-pack. Each non-trivial changed Migration Pack needs
> plan-derived assertions before implementation.

**Goal:** <one sentence describing the workbook-visible outcome>

Success Criteria: <package.univer>/success-criteria/<topic>.md

**Workbook Contract:** <2-3 sentences describing the spreadsheet behavior, not code structure>

**Execution Scope:** <Migration Packs, assertions, and verify command involved>

---

必需的计划结构

## Workbook Intent

- User-visible outcome:
- Explicit non-goals:

## Baseline Evidence

- Source already read:
- Readonly probes:
- Unknowns:

## Source File Map

- Success Criteria:
- Plan:
- Assertions:
- Migration Packs:
- Fixtures/probes:

## Range Roles

- Source data:
- Target output:
- Helper/control input:
- Lookup/reference:
- Example/demo:
- Existing output:
- Preserve-only:

## Workbook Behavior Contract

- Visible target/state:
- Source/input dependency:
- Shape/layout boundary:
- Ordering/grouping/mapping policy:
- Value/formula semantics:
- Formatting/presentation semantics:
- Interaction/validation/protection behavior:
- Preservation and negative constraints:
- Example/demo/answer-range handling:

## Contract Decision Evidence

| Decision | Chosen rule | Plausible wrong rule | Discriminating evidence | Evidence strength | Assertions/probes |
| --- | --- | --- | --- | --- | --- |
|  |  |  |  |  |  |

## Migration Packs

1. `<pack-id>`: durable workbook intent
   - reads:
   - writes:
   - must preserve:
   - rollback/verify boundary:
   - assertion gate:

## TDD Gates

- Assertions to write or update first:
- Allowed bootstrap/probe:
- Completion verify command:

## Pack Tasks

### Task 1: `<pack-id>`

**Files:**
- Plan: `<package.univer>/plans/<topic>.md`
- Test: `<package.univer>/migrations/<pack>/assertions.ts`
- Migration: `<package.univer>/migrations/<pack>/`

- [ ] **Step 1: Write the failing assertion**
- [ ] **Step 2: Run verify and confirm expected failure**
- [ ] **Step 3: Implement the minimal Migration Pack change**
- [ ] **Step 4: Run verify and confirm pass**
- [ ] **Step 5: Commit or prepare handoff**

范围角色规则

对于每个相关的范围角色，都要说明迁移可以读取、写入或替换该范围，还是必须保留该范围。

范围角色包括源数据、目标输出、辅助/控制输入、查找/参考、示例/演示、现有输出和仅供保留区域。

除非用户明确要求更改，否则源数据、辅助/控制输入、查找/参考、示例/演示、现有输出和仅供保留的范围都不是目标输出。如果使用示例/演示范围来推断公式、布局或行为，应在计划中记录该推理，并添加断言门控，以区分实际目标输出与示例。

答复范围和输出范围是约束和证据窗口。它们不能证明左上角单元格就是输出起始位置，也不能证明该范围包含完整契约。

工作簿行为契约规则

对于复杂的工作簿行为，在编辑迁移源之前，先填写相关的工作簿行为契约字段。契约应将工作簿中可见的模糊行为转化为明确的计划选择，以便通过断言进行验证。

对于输出密集型转换，应记录形状、映射、排序、分组、截断以及值/公式语义。对于格式、验证、保护、图表、批注、布局或工作表结构的更改，应记录可见状态、呈现或交互语义、保留规则以及负向约束。

合同决策证据规则

对于每一项高风险或不明显的工作簿行为决策，在编辑迁移源文件之前记录证据。

高风险决策包括：优先顺序、分组和截断顺序、源到目标的映射、正负号到列的映射、单复数标签措辞、空白与零与错误的处理策略、日期窗口的边界是否包含端点、格式错误的颜色处理、文本大小写或空白字符的保留、表头或分节边界的处理、公式与静态值的策略，以及任何可能有多种合理解读的行为。

精确保留工作簿中可见的值本身就是一项行为决策。当文本、空格、标点、标识符、日期值、布尔值、数字/文本类型、空白、零或错误占位符可见时，计划必须说明是精确保留它们，还是有意进行转换。不要仅仅因为规范化后的形式看起来更整洁或更符合惯例，就规范化这些值。

• 如果某项决策依赖领域直觉、含糊的措辞、不完整的预览数据，或未经核实的示例/参考模式，请勿写 Unknowns: none。
• 如果存在多种合理解读，请列出被排除的解读及其未被采纳的原因。
• 如果所选规则基于工作簿中可见的证据，请注明来源区域或单元格。
• 如果所选规则仅基于指令措辞，请在计划中引用起决定作用的短语。
• 如果没有决定性证据，请将该决策标记为假设，并选择最符合最终目标/输出措辞的规则。
• 每项高风险决策都必须至少有一条断言或只读探查；如果采用相反的解读，该断言或探查应会失败。
• 不要仅凭源侧符号或业务惯例推断借/贷、流入/流出、正/负或类似语义标签；应将映射关联到目标标签、示例、指令措辞或明确声明的假设。
• 写入表头、类别、状态、部门和名称时，保留工作簿中可见的标签文本。仅规范化用于匹配的标签，除非指令明确要求重命名、改为单数或复数、清理或重新格式化写入的标签。
• 现有目标值或答案区域中的值属于证据，而非权威依据。当任务要求计算、填充、修复、替换、重塑、转置、合并该区域，或在其中输入公式时，在指令和工作簿证据证实这些值是预期最终值之前，应将它们视为可能的示例、过期状态或部分输出。
• 如果现有目标值与从指令推导出的规则冲突，请在 Contract Decision Evidence 中记录这两种解读，并依据有区分作用的指令措辞以及已检查的源/目标证据作出选择。
• 将空白、零、#N/A、n/a、空格和 NBSP 视为不同的输出。计划必须说明预期输出是哪一种；在相关情况下，还应引用至少一个空白/错误/零边界案例的证据。
• 对于日期窗口或期间逻辑，请记录边界是否包含端点，并探查首个计算行、边界前后各一行、中间一行和最后一行。
• 对于工作簿样式，应用颜色前，应先将格式错误或简写的颜色规范化为有效的 #RRGGBB 或安全的 rgb(r, g, b)。除非 API 明确说明支持，否则不要将格式错误的十六进制颜色或命名颜色直接传递给样式 API。

证据充分性规则

高风险决策需要有区分力的证据，而不只是相容的证据。

只有当证据能让至少一种合理解释变得不太可能时，它才具有区分力。既符合所选规则、又符合被否决规则的证据属于相容证据，而非证明。

将观察到的工作簿事实与语义标签分开。某个源值改变了余额，可以证明源数据的符号行为，但仅凭这一点无法证明该符号应对应哪个目标标签。分区边界可以证明数据从何处开始改变形态，但仅凭这一点无法证明应复制、跳过还是重写标题。

除非领域直觉、相邻行算术、源端模式或惯常业务含义能直接关联到工作簿中可见的目标标签、示例、指令措辞或现有输出，否则不要将它们视为决定性的目标映射证据。

使用 Evidence strength 字段，将每项高风险决策标记为以下其中一项：

• explicit：指令或工作簿中可见的现有目标／示例直接指定
• inferred：有工作簿中可见且具有区分力的证据支持
• underdetermined assumption：现有证据无法排除其他合理解释

对于证据不足的决策：

• 在交互式任务中，执行前先询问用户。
• 在非交互式任务中，仅在有必要时继续；选择最贴合指令和目标布局的尽力而为规则，并在计划和交接说明中明确保留不确定性。
• 不要将假设说成是由工作簿证明的证据。

包拆分

按持久的工作簿意图拆分：

• 创建或重塑工作表
• 加载或规范化数据模型
• 添加公式系列
• 生成审核或汇总输出
• 添加呈现或验证行为

不要按单个单元格、单次 Facade 调用或偶然的实现步骤拆分。一个包大小合适的标准是：有一个明确的工作簿意图、合理的回滚边界，并有自己的断言关卡。

包任务结构

每个非平凡迁移包都必须包含可供执行者遵循、无需猜测的复选框任务。使用准确的文件路径、准确的命令和预期结果。

### Task N: <pack-id> - <workbook intent>

**Files:**
- Plan: `<package.univer>/plans/<topic>.md`
- Test: `<package.univer>/migrations/<pack>/assertions.ts`
- Migration: `<package.univer>/migrations/<pack>/`

- [ ] **Step 1: Write the failing assertion**

Add or update the assertion that proves the current pack's workbook-visible behavior.

- [ ] **Step 2: Run verify and confirm expected failure**

Run: `univer sac verify <package.univer> --json`
Expected: FAIL for the intended workbook-visible reason, not setup or typo failure.

- [ ] **Step 3: Implement the minimal Migration Pack change**

Edit only `migrations/<pack>.ts` and any pack-local helper required by the current assertion.

- [ ] **Step 4: Run verify and confirm pass**

Run: `univer sac verify <package.univer> --json`
Expected: PASS with this pack's assertion checked in returned assertion evidence.

- [ ] **Step 5: Commit or prepare handoff**

Record the plan path, assertion evidence, migration file, and verify command.

不要写“与任务 N 类似”；请重复列出详细信息，因为不同 Agent 可能会按不同顺序执行各个包的任务。

不留占位符

以下情况均属于计划失败：

• TBD、TODO、“稍后实现”或必填部分留空
• 没有说明工作簿中可见行为的“添加适当断言”
• 没有说明范围或作用的“保留现有数据”
• 对另一个包写“同上”
• 缺少读取、写入、保留边界或断言关卡的迁移包
• 未注明证据强度的决策行
• 缺少复选框步骤、准确文件、验证命令以及预期失败／通过结果的包任务

计划自查

交接前，在线审查计划：

1. 工作簿覆盖范围： 每项用户可见的需求都映射到一个契约字段和一个包。
2. 范围角色覆盖范围： 每个相关的源、目标、辅助、示例、现有输出和仅保留范围都有读取／写入／保留规则。
3. 决策覆盖范围： 每项高风险 Excel 领域决策都有证据强度，以及具有区分力的断言或探查。
4. 执行覆盖范围： 每个有实质变更的包都有从计划推导出的断言关卡。
5. 包任务覆盖范围： 每个非平凡包都有可执行的复选框步骤，其中包含准确的文件、命令和预期结果。
6. 占位符扫描： 清除占位符、含糊的断言和未明确说明的保留要求。

危险信号

出现以下想法时，意味着应当停止并完善计划：

想法	实际情况
“工作簿的意图一目了然。”	电子表格的行为会隐藏领域规则。请写明约定。
“我会先编写断言，之后再写文档。”	断言必须源自计划，而不是凭记忆编写。
“这个答案区域证明了输出起始位置。”	答案区域是证据窗口，不是完整的约定。
“迁移可以保留所有内容。”	要保留内容，必须明确指定区域的作用并进行否定检查。
“源符号告诉我目标标签是什么。”	映射需要目标标签、示例、措辞或明确说明的假设。

执行交接

计划通过自我审查后，交接给 executing-univer-plans。交接内容应注明：

• 计划路径
• pack 顺序
• 要编写的第一个断言关卡
• 验证命令
• 尚未解决的假设（如有）