Excel 业务本体 Agent

1.46 的正式运行分发为原生 E + 独立 Agent Assets A：E 自带 Python 和全部执行资源，A 只有说明性资料。Excel 与已授权业务数据库共享公开 Query/来源证据入口；临时探索可明确保存为隔离、不可变的本地分析快照。安装布局与平台边界见 INSTALL.md。源码目录保留 Python 实现，它们随 E 私有运行时发运，不再要求 Agent 直接执行脚本。

这是一个面向业务人员的 Excel 业务知识分析与交付 Agent。它帮助组织把个人 Excel 中的隐性知识，转化为人可交接、Agent 可理解、计算可验证的组织语义资产。

你可以继续使用自然语言和 Excel，不需要学习数据库、SQL、Schema 或命令行。只要告诉 Agent 文件在哪里、希望解决什么问题，以及你已经知道的业务事实，Agent 会先理解使用者和预期行动；这些信息在项目范围确认后会随本次任务复用，不要求你在抽取、判断、查询时反复说明。信息不足以决定处理方式时，Agent 会提出最少的业务问题或候选方案，再选择合适的能力完成工作；没有额外背景也可以直接开始。

产品以助手而不是技术操作台的方式工作：能通过只读探索补足的信息由 Agent 主动取得，只有确实会改变处理路径或业务结论时才请你判断；完成后直接用业务语言说明形成了什么、仍有哪些边界和风险，并主动给出下一项最有价值的帮助，不要求业务人员理解内部状态、数据库或产物目录。

如果产品已经安装，请直接从“第一次使用”开始。安装、产品原理和 CLI 位于本文后半部分，普通业务用户可以跳过。

产品价值收敛为三个层次：

• 发现知识：通过 Excel 业务体检、可信度说明、差异归因、未来风险识别和修改影响预答，帮助使用者发现原本不知道、但已经存在于自身数据和公式中的问题与规律；
• 沉淀知识：把公式、批注、工作簿结构和个人经验恢复为可追溯、可确认、可持续维护的组织业务定义，使知识不再只存在于某位表格作者的记忆中；
• 交付知识：面向人生成可以接手和继续维护的业务交接包，面向 Agent 和知识系统生成 RDF/OWL 机器语义包，让已确认知识能够被后续使用，而不是停留在当前工作区。

这三个层次不是三套互相独立的功能：发现提供证据，沉淀形成组织定义，交付让经过确认的知识离开个人、服务后续人员和 Agent。

它能为业务人员做什么

1. 看懂一套陌生或复杂的 Excel

Agent 可以梳理：

• 这套工作簿服务什么业务用途；
• 有哪些业务对象、指标、维度、分类和业务规则；
• 指标由哪些输入组成，经过什么计算、映射或汇总；
• 工作簿、Sheet 和公式之间如何依赖；
• 哪些结论来自 Excel 直接证据，哪些仍是候选解释；
• 哪些问题必须由业务专家确认。

你可以说：

请分析这个目录中的Excel，说明每个工作簿和Sheet的业务用途，
并梳理主要指标、维度、计算关系、跨表依赖和待确认问题。

2. 给 Excel 做业务体检

在业务本体尚未确认时，也可以先做不依赖正式口径的结构体检，例如发现：

• 公式链中间断裂、局部缺公式或异常返回零；
• 外部依赖不可达，导致结果无法验证；
• 同名列的定义不同，或者当前数值相同但条件变化后会分歧；
• 汇总值写回明细行，继续求和会重复计算；
• 没有表头但被大量下游公式依赖的关键列；
• 硬编码在公式中的比例、阈值和政策常量；
• 文本、数字、空值混用造成的潜在计算风险；
• 需要作者或业务专家补充说明的知识缺口。

你可以说：

请对这个工作区做一次Excel业务体检。
先用业务语言告诉我最值得关注的三件事，
再给完整清单、影响范围和可以追溯的工作簿、Sheet、单元格及公式。
不要把风险候选说成已经发生的损失。

3. 构建并确认业务本体

Agent 会从 Excel 证据中形成业务对象、指标、维度、分类、计算、映射、规则和数据关系候选；遇到竞争解释时组织成业务问题，由专家确认后再形成正式口径。

它不会因为名称相同就自动合并两个指标，也不会因为当前数值相等就判定它们是同一口径。

业务定义也可以先于 Excel 建立。如果你已经有指标目录、指标定义表、制度材料或经过确认的业务说明，可以先交给 Agent 整理指标、维度、关系和计算定义；即使暂时没有对应工作簿和数据，这些内容仍可作为“已有定义、尚无数据映射”的候选知识保存。以后 Excel 到达时，Agent 会核对名称、单位、粒度和适用范围，只补充能够明确匹配的实现与观察证据；不兼容内容会保留为竞争解释并请业务人员确认，不会覆盖既有正式口径。

定义确认与数据可用是两件事。完整定义可以在没有 Excel、Binding 或观察值时由业务人员接受、批准或发布；查询和交接会继续明确显示“定义已存在、实现未绑定、当前无数据”。Excel 后到时，只有定义质量、业务命名空间、名称或别名、单位和声明粒度全部闭合且兼容，才会自动补充本地 Binding。任何缺失项、冲突项或计划人口不足都会保留为候选或不可用状态，不会把未知当作兼容，也不会把一条局部 Binding 说成数据已经完整可用。

你可以说：

这里有一份指标定义表，请先建立指标、维度、业务关系和计算定义。
暂时没有对应Excel的数据不要补猜，也不要把“已有定义”说成“已有数值”。
以后工作簿进入项目时，再核对哪些定义能够匹配并补充数据证据。

到达业务判断点时，Agent 不需要手工填写坐标、候选人口、运行身份、Brief 摘要或数据库结构。完整冷启动构建由程序生成覆盖业务代表性范围、维度、计算和未建模边界的候选 Semantic Profile；Agent 默认只审会改变业务含义的不确定项，没有新增业务证据时不通读或重写完整草案。发现反证时也只提交判断项、所选候选和业务理由，当前运行与证据基线由程序绑定。局部确认或后续增量修订只提交本次实际业务判断，由程序与已提取证据重新核对。尚未判断、证据不足或存在冲突的部分逐项保留，但局部候选不会被表述为完整本体。处理被中断时，Agent 会用业务语言说明已经保留了哪些结果、只需补做哪一步，不会默认重新抽取全部 Excel。构建完成后的第一屏先告诉你形成了哪些业务知识、还有哪些重要问题和下一项最值得做的帮助；内部命令、数据库表名和运行编号默认不展示。

当多张 Sheet 的结构证据和候选解释相同时，产品会把它们整理成一个可审查的判断族，让 Agent 先说明共同业务含义，再单独列出不适用成员和异常。业务人员不需要重复回答同一个问题；底层每张 Sheet 的来源判断仍逐项保留，存在反证的成员不会被共同结论覆盖，也不会因为归组而变成已确认口径。

你可以说：

请根据当前Excel证据形成业务本体候选。
把无法确定的指标身份、维度、粒度、计算口径和跨表关系整理成待确认问题，
不要自行补充企业规则。

4. 形成标准数据、核对结果和可继续使用的业务工作簿

业务本体确认后，Agent 可以把不同工作簿中的观察值按统一指标、维度和粒度整理成标准数据，并执行全量核对。

你会得到：

• 可追溯的标准数据；
• 标准数据工作簿；
• Excel 保存值与规范重算值的核对结果；
• 机器检查通过、失败、警告、无法验证等状态；
• 仍需要业务确认的问题。

如果你不只是要查看标准结果，而是希望得到一份可以继续填报、试算或交付的 Excel，可以直接说明工作簿的业务用途、使用者、输入信息、输出指标、业务范围，以及是否需要在 Excel 中实时计算。Agent 会据此生成以下三种互不混用的工作簿：

• 业务快照：只读展示当前已经治理和核对的业务结果；
• 标准输入模板：提供明确的输入区域，用于规范采集或预填基础事实；
• 实时计算模型：在输入变化后由 Excel 公式实时计算已确认的输出指标。

业务人员不需要指定 Sheet 布局、单元格坐标或编写公式。生成的工作簿会按用途组织说明、输入、参考、计算、输出和核对内容，并清楚标出可编辑区域与受保护区域。

你可以说：

请基于已经确认的业务本体生成标准数据并执行全量核对。
通过门禁后生成标准数据工作簿和核对工作簿；
未通过时说明阻断原因，不要把候选数据说成正式可用数据。

如果需要一份可继续使用的工作簿，可以说：

请基于已经确认并通过核对的业务数据，为月度经营复盘生成一份业务工作簿。
使用者是经营负责人；允许调整计划输入，输出收入、成本和利润；
范围是当前选择的业务单元和期间，并且需要在Excel中实时试算。

请先确认输入、输出和适用范围；不要让我填写单元格位置或Excel公式。

实时计算模型只有在规范计算能够完整转换为 Excel 公式，并且本次文件经过真实 Microsoft Excel 重算核对后才会发布。如果公式不受支持、依赖不完整、重算结果不一致，或者当前环境没有可用的 Excel，Agent 会说明原因，并让你选择业务快照、输入模板或停止，不会用近似公式冒充正式模型。

工作簿中的可编辑输入只影响该文件内的本地试算，不会自动修改源 Excel、业务本体、标准数据或正式 What-if 结果。

5. 查询一个指标、数值或计算来源

你可以查询指标定义、分类位置、计算构成、适用维度、观察值、公式和上下游证据。

你可以说：

请查询“目标指标A”：
1. 它的定义和分类位置；
2. 业务计算构成；
3. 适用维度和已观察到的成员；
4. 满足指定业务单元和期间的数值；
5. 该数值对应的工作簿、Sheet、单元格、公式和直接上游。

如果存在多个候选，请先说明差异，不要自行合并。

即使当前还没有生成或确认正式本体，Agent 也可以从已经入库的来源标签、单元格、公式、引用和版式证据中寻找候选，说明候选是什么、位于哪个工作簿/Sheet/单元格、如何计算，以及还缺少哪些业务确认。此类结果只用于理解、排查和本体确认准备，不会被冒充为稳定对象、正式企业口径或受治理数值。跨对象、跨来源或临时聚合问题会采用当前案例库的只读探索；已有正式对象、取值或可信度判断仍优先使用确定性查询能力。

一次问题涉及多个指标时，Agent 会复用同一案例和同一记录身份批量取值或判断可信度；个别指标缺失或歧义时，已取得的结果仍会交付，并把需要补充的业务条件逐项说明，不会因一项失败丢掉整批结果。Build 或 Standardize 交给 Query 的任务说明会绑定当前本体代次；本体发生更新后，旧查询上下文会提示刷新，不会静默读取新旧混合状态。多个来源目录中存在同名工作簿时，Agent 会先让你按业务来源组确认范围；后续抽取和查询都沿用该范围，不会因文件名相同而把另一来源的数据混入。

如果同一类来源存在多个文件版本，例如预算_V1.xlsx、预算_V2.xlsx，Agent会先把它们作为可能的“预算”版本家族提交确认。确认后可以说：

请从年度预算的最新批准版本读取收入，并说明实际用了哪个文件、版本状态和来源位置。

程序会区分“最新观察”“最新批准”和“明确固定版本”，按数值版本序号选择（因此V10晚于V2），并把本次实际使用的物理工作簿与源修订固定下来。文件名和修改时间只能帮助发现候选，不能自动证明某个文件已经批准；版本关系或顺序不唯一时，Agent会列出候选并请业务人员确认。正式版本变化后，依赖旧选择的标准数据和分析结果会失效，不能静默沿用。

如果工作区已经构建完成，之后又加入预算_V3.xlsx，可以直接说明“把新增预算文件纳入现有工作区”。Agent会走Build的增量盘点：沿用同一业务本体库，只抽取新增或发生变化的来源；工作簿内未变化的Sheet直接复用既有证据，发生变化的Sheet才重新抽取。结构稳定、记录身份完整且差异较小时，程序会保存可精确重建的记录增量；身份不可靠、结构变化或差异过大时自动回退完整Sheet检查点，不让业务人员选择技术存储方式。旧版本保持只读可追溯，不会被新文件覆盖。

面向业务人员的处理顺序是：新增或替换文件时先更新证据；询问“最新预算”时先确定本次实际使用的来源版本；如果还要形成正式标准数据，再基于该固定版本继续标准化和稽核。Agent会自行组合Build、Query和Standardize，用户不需要选择Skill或编写内部契约。来源版本尚未确认、最新顺序不唯一或正式状态不足时，Agent会先列出实际候选和差异，不会直接给出正式值。

同一工作区可以保留当前版、历史版和草稿版。业务定义只维护一份，来源版本、对应Binding和本体代次分别冻结；查询或分析包会明确绑定实际使用的版本，不会把“最新”解释为可随时间漂移的隐式选择。

6. 解释两个数字为什么对不上

业务人员需要的通常不是差额清单，而是差异属于哪一层。Agent 会按证据依次判断：

1. 源数据是否缺失或不可达；
2. 粒度或维度是否不同；
3. 映射关系是否不同；
4. 聚合方式是否不同；
5. 计算公式是否漂移；
6. 调整、规则或适用范围是否不同；
7. 是否仍存在无法解释的证据缺口。

你可以说：

请解释指标A和指标B为什么对不上。
不要只给差额，请说明最可能的原因层、受影响范围和直接证据。
如果当前本体或标准数据还不满足正式核对条件，请明确说明缺少什么。

7. 在修改前预判影响

正式修改指标、计算、映射或数据绑定前，可以先询问会影响哪些对象、期间、工作簿和核对结果。预判本身不会修改现有定义或数据。

你可以说：

如果把成本中心A从R&D调整为PSO，会影响哪些指标、期间、工作簿和核对结果？
先做影响预判，不要提交修改。

8. 做 What-if 情景推演

What-if 用于回答“如果改变一个条件，结果会怎样”。它在隔离环境中运行，不修改基准数据。

你可以进行：

• 参数或比例调整；
• 指标值覆盖；
• 维度成员之间的金额转移；
• 对已有成员构成的新业务组合进行推演；
• 比较两个历史情景的假设和结果。
• 在两个来源版本上应用同一组假设，并比较各自影响与版本差异。

你可以说：

如果把业务单元A的一项费用调整到业务单元B，
会影响哪些指标、汇总和核对结果？
这只是推演，不修改基准。
请保存本次分析，标题为“费用归属调整影响”。

每次推演保存在输出目录的 analysis/ 下，目录名只包含时间和短ID；业务标题、问题、假设、结果、当前性和说明保存在目录内及可重建索引中。普通查询只返回当次答案，不默认保存文件。你可以继续说：

列出最近一个月做过的What-if分析。
打开“费用归属调整影响”。
比较上周两次费用调整分析。
删除“费用归属调整影响”及其全部结果。

删除整个分析目录即可删除该次推演；主业务数据库不会隐藏保存场景结果。

版本比较与双基线What-if会先核对粒度、单位、记录人口和可比范围。不能直接比较时仍交付已证实的部分，并说明缺少的业务条件；不会为了给出数字而静默合并不同口径。What-if只创建可逆覆盖层，不修改任何来源版本。

9. 生成业务交接包

交接包面向下一位维护者，帮助组织把只存在于原作者记忆中的知识沉淀下来，包括：

• 工作簿在业务链中的用途和位置；
• 上游来源和下游使用者；
• 关键指标、计算链和聚合口径；
• 政策常量、参数和临时处理；
• 高风险位置和当前未解决问题；
• 仍需原作者回答的 QuestionSet；
• 关键结论的证据位置。

你可以说：

请为当前工作区生成业务交接包，
供下一位维护者理解这套Excel的用途、依赖、关键指标、计算、政策常量、风险和待确认问题。

10. 导出供其他 Agent 理解的 RDF/OWL

已批准或已发布的本体可以单向导出为 RDF/OWL，使其他 Agent 或知识系统在不连接当前主数据库的情况下读取稳定对象、关系、来源和可重建的计算语义。导出包同时包含公开词汇、SHACL Shapes 和合规报告；系统会真实解析 Turtle/OWL，并在发布前验证必需属性、对象/数据类型、基数和受控取值，未通过约束的包不会发布。

你可以说：

请把当前已经批准的业务本体导出为RDF/OWL语义包，供后续Agent读取。
不要导出尚未确认的候选口径，也不要修改当前工作区。

RDF/OWL 是单向投影，不是第二套本体，也不能反向覆盖当前业务工作区。SHACL约束的是公开导出Profile，不复制SQLite中的来源选择、计算执行或治理算法。

第一次使用

第一步：确认项目、输入文件和输出目录

你至少需要告诉 Agent：

• 输入目录：原始 Excel 所在目录；
• 项目目录：这批文件所属的业务项目；加入既有项目会复用已有本体，新建项目则完全隔离；
• 输出目录：本次工作区的保存位置；
• 文件处置：引用原位置、复制到项目，或移动到项目。复制保留原文件，移动会改变原位置。

来源容器按文件内容识别，不按扩展名猜测。除标准 .xlsx/.xlsm 和 CSV 外，Excel 导出的 HTML-as-XLS 也可作为受控来源读取；原始 HTML 表格坐标、跨行跨列和未翻译公式会保留独立来源定位。真正的旧版 BIFF .xls 当前会明确返回不支持，不会把它误当 HTML 或 OOXML。矩阵型 Sheet 的完整行列轴人口由确定性程序从已确认表头和行标签物化；当表头同时提供业务编码与名称时，还可显式生成对应业务对象及代码、名称属性。名称缺失或同一编码存在多个名称时，产品保留编码对象和全部名称候选，降低结论强度并进入业务判断，不因局部语义不确定而打死整次构建。Agent 只提交业务覆盖、排除和复用判断，不手工抄写成千上万个成员。

如果没有指定输出目录，产品会在已确认的项目目录下创建工作区容器，并按本次来源集合隔离工作区：

<项目目录>/.business-ontology/workspace-<来源短标识>

.business-ontology只是工作区容器，不是一个共享数据库。Agent收到尚未归属项目的新文件时，会在用户授权范围内列出现有项目，并让用户选择新建、加入某个项目或指定其他项目；发现零个、一个或多个候选都不会自动归属。未取得本次项目、处置方式和目标位置对应的确认令牌前，程序不会移动、复制、登记、抽取或入库。用户指定输出目录时严格使用指定目录，不再额外嵌套.business-ontology。选择move时，程序先复制并校验，成功登记工作区后才删除原位置；中断后可幂等补做。选择reference或copy不会修改原始工作簿。

项目和文件处置确认后，产品只用确定性读取器列出工作簿与 Sheet，不创建任务契约、数据库或抽取任务。业务人员确认精确 Sheet，或明确选择全部 Sheet 后，才生成最终构建任务并开始处理；“尚未选择”不会被解释成“全部处理”。如果业务人员已经给出精确 Sheet 名称，产品会在全部已批准工作簿中直接展开命中范围，不把数百张 Sheet 清单送入模型。来源文件或 Sheet 人口在确认期间发生变化时，旧选择自动失效并重新展示候选。

如果目标是完整构建一个新项目，Agent 会直接建议分析全部 Sheet；只有业务人员明确要求局部范围时才逐项选择。普通业务答复只展示工作簿、Sheet、业务影响和可选动作，工作区路径、内部来源标识、继续令牌与诊断信息只供 Agent 续接或获批排障使用。

读取复制自其他机器的工作区时，不沿用旧TaskContract中的绝对路径。Agent只在用户指定目录内进行有限发现；找到多个候选时列出工作区、来源人口和数据库状态，由用户选择后生成当前机器的新TaskContract和runId。

如果整个工作区被移动到新目录，Agent可在没有活动任务时执行一次受控重绑定：核对工作区身份和主数据库后，只改写根路径及当前恢复指针，历史契约继续只读。运行目录中的临时文件可先预览再清理；来源、当前或历史检查点、专家决定、分析结果和正式交付物始终受保护。产品不会为每个单元格、公式或Binding生成小文件。

Windows 下产品生成的原子临时文件统一使用固定短名，不再重复长产物名；任务开始前还会核对工作区与已知内部产物的路径预算。输出位置过深时会在抽取和权威写入前提示改用更靠近磁盘根目录的位置，来源文件无需移动。

第二步：说明范围和已知事实

你可以按需要补充：

• 只处理哪些工作簿或 Sheet；
• 跳过哪些说明页、临时页或归档页；
• 文件名、Sheet 名、表头、颜色、缩进或命名规则的已知含义；
• 同名 Sheet 在不同工作簿中是否代表同一种业务模型；
• 超出处理范围的引用，是只记录引用端点，还是允许继续展开；
• 重点关注的指标、公式、粒度、映射或核对问题；
• 已经获得专家确认的事实，以及明确禁止 Agent 假设的内容。

不必一次说完。Agent 会先从证据形成候选，无法判断时再向你提出业务问题。

第三步：用自然语言启动

请分析 D:\业务案例\案例A 下的 Excel，结果保存到
D:\业务案例\案例A\工作输出。

只处理“业务明细”和“汇总分析”；跳过“填报说明”和名称包含“临时”的Sheet。
已知文件名末尾是业务单元缩写。
请重点判断业务对象、指标、维度、计算关系、跨表依赖、汇总粒度和核对规则。
未确认的业务判断保留为候选和待确认问题。

第四步：查看进度并参与关键判断

批量处理开始时，Agent 会说明工作簿和 Sheet 总量。长时间运行时，主 Agent 会按业务可理解阶段更新进度，例如：

• 正在读取和整理哪个工作簿；
• 已完成多少个 Sheet；
• 哪些 Sheet 正在等待写入；
• 是否正在提交结果；
• 是否遇到失败、重试或需要业务判断的分叉。

确定性的读取、公式解析、证据入库和校验由程序连续完成。Agent 只在业务用途、指标身份、粒度、维度、计算角色或竞争解释无法自动裁决时介入，不会逐条分析全部公式。

指标分类体系不是公式依赖边界。一个计算即使引用了其他指标体系中的收入、成本或控制项，产品也会保留原始 Excel 公式及全部操作数、运算符、函数和常量；公式输入名称来自被引用行或列的具体指标载体，父级分类和区块标题只用于说明层级与语境。只有业务表达与实现公式完整等价时才显示完整业务等式。存在未解析或竞争输入时，会醒目标记“公式投影不完整”，保留候选和来源位置，不再把缺少一侧输入的部分等式展示成已经形成的业务计算；多个来源项暂时指向同一身份也只进入待区分状态，不自动报告重复计算。

确定性抽取、编译、物化和校验完成后，运行会结束并释放写入者；同名身份、分类归属或公式口径仍待判断，不会让数据库长期保持 running。这些候选进入独立业务确认状态，业务人员可以稍后确认。决定回写会绑定候选组和当时的本体代次；若期间证据或本体已经变化，产品要求重新比较，而不是把旧决定强行写入新基线。

一次完整业务流程

正式定义与数据交付的主线如下，业务体检是证据形成后的可选分支，不是每次构建、查询或标准化的前置环节：

首次读取Excel
→ 候选本体
→ 专家确认
→ 标准数据与全量稽核
→ 查询、溯源和差异归因
→ What-if、影响预答、交接或语义导出

已有当前证据 ──（用户需要发现整体结构风险或评估工作区可信度）──→ 业务体检

各能力按业务意图组合：

• 只想发现 Excel 结构风险，可以停在业务体检；
• 普通定义查询、取值、血缘、核对或 What-if 不会自动运行业务体检；
• 只想了解候选定义，可以停在本体确认前；
• 正式取数、核对和推演必须满足对应的本体确认与数据可用门禁；
• 交接包可同时包含已确认知识和明确标识的待确认问题；
• RDF/OWL 正式导出只包含获得授权状态的本体内容。

如何理解结果能不能直接使用

Agent 会区分以下状态，业务人员不需要根据“能不能返回一个数字”自行判断可靠性：

• 源证据：Excel 中实际存在的单元格、公式、批注或缓存值；
• 系统候选：由结构和公式推断出的可能解释，尚未获得业务确认；
• 待确认：存在冲突、证据不足或多种合理解释；
• 已批准/已发布本体：已经经过业务确认，可作为当前语义权威；
• 机器验证通过：结构、人口和计算检查通过，不等于业务口径已确认；
• 标准数据可用：本体、范围、稽核和发布门禁均满足当前用途；
• 无法验证：缺少依赖、规则、维度或必要证据，不能猜测结论。

如果业务本体尚未确认，Agent 会明确提醒：当前回答来自源证据和系统候选，只适合理解、排查和专家确认，不能冒充正式企业口径或受治理数值。

输出在哪里

<输出目录>/
├─ data/
│  └─ business-ontology.sqlite       源证据、当前本体和标准数据的主事实库
├─ runs/
│  └─ <一次运行>/
│     ├─ logs/                        运行日志和进度
│     ├─ workbooks/                   标准数据与核对工作簿
│     ├─ workbook-projections/        按业务用途生成的受控业务工作簿
│     │  └─ <一次生成>/
│     │     ├─ README.md              用途、边界和使用说明
│     │     ├─ *.xlsx                 业务快照、输入模板或实时模型
│     │     ├─ projection-manifest.json 生成范围和文件清单
│     │     └─ *-receipt.json         生成及重算核对收据
│     └─ artifacts/
│        └─ validation/
│           ├─ validation-report.json 机器验证总报告
│           └─ question-set.json      冲突、缺口和专家问题
├─ analysis/
│  ├─ index.json                      可重建的What-if历史索引
│  └─ <时间_短ID>/                    单次推演的说明、假设和结果
└─ exports/                            交接包、RDF/OWL等按需导出

主数据库是源证据、当前本体和标准数据的唯一机器权威。Markdown、工作簿、交接包和 RDF/OWL 都是面向特定使用者的可重建输出，不会成为相互冲突的第二套定义。

常见问题

可以只处理指定 Sheet，或者跳过指定 Sheet 吗？

可以。启动前直接说明包含或跳过规则。范围外 Sheet 默认不会被整体建模；若被范围内公式直接引用，可只保存引用端点和值。

原始 Excel 会被修改吗？

不会。构建、体检、标准化和 What-if 都在独立工作区处理。生成的新工作簿也保存在输出目录。

为什么实时工作簿需要安装 Microsoft Excel？

普通业务快照和输入模板不依赖 Excel 实时计算。实时计算模型包含由已确认业务定义生成的公式，发布前需要使用真实 Microsoft Excel 完整重算并核对结果。仅仅生成一个可以打开的 .xlsx 文件，不能证明 Excel 能正确接受和执行其中的公式。

产品会在独立进程中调用 Excel 完成重算、另存和结果核对，不会要求业务人员手工打开文件。当前环境没有可用 Excel 时，仍可生成业务快照或输入模板，但不会把未经真实重算的文件标为实时计算模型。

没有业务专家确认，也能使用吗？

可以做盘点、结构体检、候选本体、公式血缘和待确认问题整理；不能把候选口径当作正式定义，也不能把候选标准值用于正式业务决策。

同名指标会自动合并吗？

不会。产品会为每个来源位置保留独立 occurrence，并形成身份复用或独立身份的竞争候选；Agent 会比较父级指标、所在区块、业务语境、公式角色、粒度、维度和适用范围。证据不足时列出候选差异，继续处理不冲突的人口，留待业务人员后期确认。

运行很久时我如何知道是否还在工作？

主 Agent 会监控工作簿、Sheet 和处理阶段。只有状态变化、异常、重试或到达业务判断点时才更新，不会反复发送含义不明的“仍在处理”。

中断后必须从头开始吗？

不一定。构建和分批标准化会保存已提交工作单元，恢复时从受支持的断点继续。正常构建发现上次执行被宿主取消、失败或中断后，会在能够证明没有活动执行者时由下一次普通运行自动续接；已经提交的 Sheet 不会重新抽取，也不要求业务人员理解状态码或单独执行恢复命令。若仍有活动执行，则只报告正在处理，不启动第二个 Writer。大工作簿会在独占内存窗口中处理，普通工作簿仍可并发；调度变化不减少公式、引用、版式、批注或来源人口。若相邻版本升级了 SQLite Schema，旧运行须先受控停止并释放 lease；新版随后可以迁移同一数据库、建立新的 reuse run，并只复用已提交证据继续编译与物化，不必重新打开 Excel。真正活动的 Writer、残留 lease 或不兼容契约仍会被拒绝，不能以恢复为名绕过一致性门禁。

What-if 结果会不会悄悄留在主数据库？

不会。每次 What-if 保存在独立分析目录；大型分析需要局部结果库时，也只位于该分析目录内。删除该目录即可完整删除这次分析。

Agent、Skill、程序和数据库如何分工

普通业务用户不需要理解内部实现。以下说明用于产品维护者和高级用户：

| 组成 | 负责什么 | 不负责什么 | |---|---|---| | Agent | 理解业务问题、选择能力、裁决竞争语义、解释结果、组织专家问题 | 逐单元格搬运数据、无证据猜测企业规则 | | Build Skill | 规定证据抽取、本体构建、判断时点和停止条件 | 写死某个企业或案例的业务答案 | | Standardize Skill | 将已确认定义应用到观察数据，形成标准数据并执行稽核 | 修改本体定义或把候选值冒充正式值 | | Query Skill | 负责体检、查询、溯源、归因、What-if、交接和RDF/OWL导出 | 绕过本体自由修改数据库 | | 企业本体库管理 Skill | 管理本地企业 T-box 候选、修订、交换和项目采用 | 读取 Excel、处理项目事实或操作 GitHub | | 企业本体 Git Skill | 处理 GitHub 分支、PR、Merge、正式 Release、发现和下载 | 解释语义、写 SQLite 或静默升级项目 | | Python | 执行范围盘点、Excel读取、公式解析、批量写入、计算和完整性检查 | 替代业务专家裁决语义 | | SQLite | 保存源证据、当前本体、数据映射和标准数据 | 代替 Agent 做业务判断 |

flowchart LR
    U["业务人员：自然语言问题"] --> A["Agent：理解意图与业务判断"]
    A --> B["六个本地Skill：选择正确工作方法"]
    B --> P["Python：确定性处理与验证"]
    P --> S["SQLite：统一证据和业务语义"]
    S --> O["体检、标准数据、查询、推演与交付"]
    O --> U

产品内部由 AGENT_CORE.md 管理稳定岗位、价值原则和路由边界；Excel构建、数据库构建、标准化、查询、本地企业本体库和GitHub协作由各自主Skill管理，并由共享契约与数据库定义保证使用同一套规则。企业本体库、数据库来源和远端均不是普通Excel项目的必选项；缺失时Build、Standardize、Query保持原路径。

安装

npm / Agent CLI

包内提供轻量 Node.js CLI，用于版本检查、产品验证和转发到六个本地能力入口：

npm install -g excel-business-ontology
excel-business-ontology --version
excel-business-ontology consistency
excel-business-ontology verify

不想全局安装时可以使用：

npx excel-business-ontology --version
npx excel-business-ontology consistency
npx excel-business-ontology build preflight
npx excel-business-ontology query preflight
npx excel-business-ontology standardize --help
npx excel-business-ontology enterprise --help
npx excel-business-ontology ontology-git --help

Build、Query 和 Standardize 的正式运行均以 TaskContract 为入口；企业本体库管理使用独立的 EnterpriseOperationRequest，GitHub 协作使用独立的 OntologyGitOperationRequest，不给 TaskContract 增加新的任务种类。CLI 不替代 Agent 的业务判断。运行前需安装 Python 3 和 requirements.lock 中的依赖；如需指定 Python，可设置 EXCEL_BUSINESS_ONTOLOGY_PYTHON=/path/to/python。

稳定版与预览版通道

产品源码及本地分发包版本为 1.62.5（以本目录的 VERSION / package.json 为准），源码升级不等于已经发布到 npm。公共版本应以安装时的 npm view excel-business-ontology version dist-tags --json 查询结果为准。使用本次 1.62.5 版本需安装对应版本包（1.62.3、1.62.4 的 ebo next 对还没迁移、停在判断点的旧 Schema 库交回一条会被 MIGRATION_BLOCKED_BY_UNFINISHED_RUN 拒掉的判断交接，#957；1.62.3 及以前在 EUC_CN 等非 UTF-8 编码的 PostgreSQL 库上，执行计划含中文表名、列名或非 ASCII 过滤值的受控查询会报 DATABASE_CONNECTOR_QUERY_FAILED；1.62.1、1.62.2 在 MySQL、PostgreSQL 来源上带文本 equal / one_of 条件的 analysis 问法会把整张表读回本地再筛，#945；1.57.0 至 1.62.1 在 MySQL 来源上 analysis 的汇总问法、在 PostgreSQL 来源上分组汇总问法都没有在库里算，退回按行读回后本地汇总，#941；1.62.0 在 MySQL 来源上带文本条件的 analysis 问法会报 SQL 语法错误，#938）；旧库迁到 Schema 41 之前应先用旧版结束旧运行。回退基线仍按 compatibility.json 的 releasePolicy.stableRollbackBaseline 保留 1.35.0 的 main@963d0e76a87a759e7e5dd3b0cc649594cf77083b。

历史预览候选 1.36.0-preview.2 在 compatibility.json 里登记为 superseded（它对应的正式源码版本是 1.36.0），预览制品只能通过显式版本或 preview dist-tag 安装，不会进入稳定更新：

npm install -g [email protected]

⚠️ 上面这条只说明通道规则，别照着装：同日实测 npm view excel-business-ontology versions 共 19 个版本，没有一个带预发布后缀，dist-tags 里也没有 preview 这一档——这个预览候选从未发布到 npm 公共仓库，装不到。

正式版本发布范围为已验证的公共入口、来源中立分析和构建/查询交接。网络连接器继续要求显式启用实验能力；现有业务实例通过不等于完整 C4、安装态 Agent L3 或所有数据库版本认证。历史预览候选的 releaseReady=false 和外部门禁记录不回填为已通过，也不将这些尚未宣称正式支持的能力新增为本次发布依赖。实际版本、通道及回退基线由 VERSION、package.json 与 compatibility.json 对齐；最终验收使用一致性、完整产品回归和发布/安装冒烟。当前版本不声明未验证的进行中 Build 跨版本续跑，旧任务应使用其原版本完成。

安装到 Codex

Codex 支持项目级 .agents/skills/<skill-name>/SKILL.md 和用户级 $HOME/.agents/skills/<skill-name>/SKILL.md。六个 Skill 共享 shared/，源码安装时必须保留完整产品目录，再把包含 build-database-business-ontology 在内的六个 Skill 目录链接到发现目录，不能只复制单个 Skill。

Windows 用户级安装示例：

$ProductRoot = 'D:\path\to\excel-business-ontology'
$SkillRoot = Join-Path $env:USERPROFILE '.agents\skills'
New-Item -ItemType Directory -Force -Path $SkillRoot | Out-Null

New-Item -ItemType Junction -Path (Join-Path $SkillRoot 'build-excel-business-ontology') `
  -Target (Join-Path $ProductRoot 'skills\build-excel-business-ontology')
New-Item -ItemType Junction -Path (Join-Path $SkillRoot 'build-database-business-ontology') `
  -Target (Join-Path $ProductRoot 'skills\build-database-business-ontology')
New-Item -ItemType Junction -Path (Join-Path $SkillRoot 'standardize-business-data') `
  -Target (Join-Path $ProductRoot 'skills\standardize-business-data')
New-Item -ItemType Junction -Path (Join-Path $SkillRoot 'query-business-ontology') `
  -Target (Join-Path $ProductRoot 'skills\query-business-ontology')
New-Item -ItemType Junction -Path (Join-Path $SkillRoot 'manage-enterprise-ontology') `
  -Target (Join-Path $ProductRoot 'skills\manage-enterprise-ontology')
New-Item -ItemType Junction -Path (Join-Path $SkillRoot 'enterprise-ontology-git') `
  -Target (Join-Path $ProductRoot 'skills\enterprise-ontology-git')

# 解释器要跟 ebo 挑的那一个一致——别用裸的 python（见下面那段说明）
$EboPy = ((ebo doctor | ConvertFrom-Json).answer.values | Where-Object { $_.name -eq 'pythonExecutable' }).value
& $EboPy -m pip install -r (Join-Path $ProductRoot 'requirements.lock')
& $EboPy (Join-Path $ProductRoot 'tools\consistency.py')
& $EboPy (Join-Path $ProductRoot 'tools\verify.py')

⚠️ 上面那三条必须走 ebo 会挑中的那个解释器，所以第一行先问 ebo doctor：它的公共结果里 answer.values 有一项名为 pythonExecutable，就是那个解释器的绝对路径（1.46.0 的 doctor 漏报了这一项，1.46.1 起恢复）； ebo 还没在 PATH 上时，就手动把那个绝对路径填进 $EboPy。包装器挑解释器的顺序是： 设了 EXCEL_BUSINESS_ONTOLOGY_PYTHON 就只用它、不回退；没设才按 PATH 试 （macOS / Linux 是 python3 再 python，Windows 反过来），并且只接受 3.11+ （bin/excel-business-ontology.mjs 的 findPython()）。装进别的解释器时 预检会一直报缺依赖，而你已经「装过了」。

再按 adapters/codex/adapter.json 的托管块标记，将 AGENT_CORE.md 合并到生效范围内的 AGENTS.md，不要覆盖已有内容。官方发现规则见 Codex Skills。

安装到 Claude Code

Claude Code 支持项目级 .claude/skills/<skill-name>/SKILL.md 和用户级 ~/.claude/skills/<skill-name>/SKILL.md。同样保留完整产品目录，再建立包含 build-database-business-ontology 在内的六个 Skill 链接。

Windows 用户级安装示例：

$ProductRoot = 'D:\path\to\excel-business-ontology'
$SkillRoot = Join-Path $env:USERPROFILE '.claude\skills'
New-Item -ItemType Directory -Force -Path $SkillRoot | Out-Null

New-Item -ItemType Junction -Path (Join-Path $SkillRoot 'build-excel-business-ontology') `
  -Target (Join-Path $ProductRoot 'skills\build-excel-business-ontology')
New-Item -ItemType Junction -Path (Join-Path $SkillRoot 'build-database-business-ontology') `
  -Target (Join-Path $ProductRoot 'skills\build-database-business-ontology')
New-Item -ItemType Junction -Path (Join-Path $SkillRoot 'standardize-business-data') `
  -Target (Join-Path $ProductRoot 'skills\standardize-business-data')
New-Item -ItemType Junction -Path (Join-Path $SkillRoot 'query-business-ontology') `
  -Target (Join-Path $ProductRoot 'skills\query-business-ontology')
New-Item -ItemType Junction -Path (Join-Path $SkillRoot 'manage-enterprise-ontology') `
  -Target (Join-Path $ProductRoot 'skills\manage-enterprise-ontology')
New-Item -ItemType Junction -Path (Join-Path $SkillRoot 'enterprise-ontology-git') `
  -Target (Join-Path $ProductRoot 'skills\enterprise-ontology-git')

# 解释器要跟 ebo 挑的那一个一致——别用裸的 python（见下面那段说明）
$EboPy = ((ebo doctor | ConvertFrom-Json).answer.values | Where-Object { $_.name -eq 'pythonExecutable' }).value
& $EboPy -m pip install -r (Join-Path $ProductRoot 'requirements.lock')
& $EboPy (Join-Path $ProductRoot 'tools\consistency.py')
& $EboPy (Join-Path $ProductRoot 'tools\verify.py')

⚠️ 上面那三条必须走 ebo 会挑中的那个解释器，所以第一行先问 ebo doctor：它的公共结果里 answer.values 有一项名为 pythonExecutable，就是那个解释器的绝对路径（1.46.0 的 doctor 漏报了这一项，1.46.1 起恢复）； ebo 还没在 PATH 上时，就手动把那个绝对路径填进 $EboPy。包装器挑解释器的顺序是： 设了 EXCEL_BUSINESS_ONTOLOGY_PYTHON 就只用它、不回退；没设才按 PATH 试 （macOS / Linux 是 python3 再 python，Windows 反过来），并且只接受 3.11+ （bin/excel-business-ontology.mjs 的 findPython()）。装进别的解释器时 预检会一直报缺依赖，而你已经「装过了」。

再按 adapters/claude-code/adapter.json 的托管块标记，将 AGENT_CORE.md 合并到生效范围内的 CLAUDE.md，不要覆盖已有内容。

客户端能发现 Skill 只证明安装完成；在各目标客户端分别运行一次真实冒烟，才能声明触发和行为有效。

CLI：仅用于高级调试和自动化

新探索与恢复

明确的新探索使用 Session；同一来源重复 new 也会创建独立实例，不复用上次的数据库。--directory 是工作目录容器，实例创建在其 .ebo-sessions/ 下；只指定目录时先盘点并选择来源，不自动授权全部文件或 Sheet。

ebo session new --directory 'D:\探索' --file 'D:\材料\销售.xlsx' --file 'D:\材料\成本.xlsx'
ebo session open '<返回的 sessionRoot>'
ebo query ask --session '<返回的 sessionRoot>' --question '当前可查询哪些指标？'
ebo next --session '<返回的 sessionRoot>'

按公共结果完成范围确认和专业操作。恢复不重新初始化；next 用于观察/恢复，不是每次提问的前置。没有当前任务时，用 session bind 选择产品生成的准确合同并提供当前 revision；不能寻找 latest 或手写合同。具体参数以该操作的 --help 为准。

创建中断与业务恢复不同：仅当公共结果指出创建未完成时，执行返回的 session new --resume <sessionRoot>；创建已完成则 open 原实例。默认引用原文件，需保留独立输入副本时显式使用 --source-mode copy，不移动原件。

Session 顶层仅保存 session.json、内部状态 .ebo/、按需输出的 outputs/，显式复制输入才增加 inputs/。项目本体、SQLite 和任务随该 Session 保留。已有 TaskContract 和旧工作区入口继续有效，不搬迁旧文件。首版探索不开放外部企业库绑定、采用和修改。

生成业务交接包须明确目标目录：

ebo query prepare-handover --task-contract '<正式 Query 交接>' --output '<sessionRoot>\outputs\本次交接'

使用返回的准确 handover 命令生成包；原 Query 合同不会被修改为可输出。仅支持可证明覆盖全项目的 Excel 来源观察范围，局部范围不会被自动扩大，已有目标不覆盖。包内候选与确认结果仍分别标识。

已有工作区与专业入口

普通业务用户不需要使用 CLI。它只适合自动化流水线、查看或恢复运行、单步复现确定性阶段和定位故障。

构建入口：

ebo build init --case-root 'D:\业务案例\案例A' --source 'D:\业务案例\案例A\预算.xlsx'
ebo build init --case-root 'D:\业务案例\案例A' --source 'D:\业务案例\案例A\预算.xlsx' --output-root 'D:\业务案例\案例A\工作输出'
ebo build discover-workspaces --search-root 'D:\收到的第三方案例'
ebo build preflight
ebo build run --task-contract 'D:\业务案例\案例A\工作输出\task-contract.json'
ebo build status --task-contract 'D:\业务案例\案例A\工作输出\task-contract.json'
ebo build resume --task-contract 'D:\业务案例\案例A\工作输出\task-contract.json'

数据库只读构建与受控查询入口（SQLite为首个参考连接器）：

ebo database connect --task-contract '<database-task-contract.json>' --registration '<database-source-registration-v2.json>' --build-request '<database-build-request-v2.json>'
ebo database register-source --task-contract '<database-task-contract.json>' --registration '<database-source-registration-v2.json>' --build-request '<database-build-request-v2.json>'
ebo database build --task-contract '<database-task-contract.json>'
ebo database resume --task-contract '<database-task-contract.json>'
ebo database stop --task-contract '<database-task-contract.json>'
ebo database confirm --task-contract '<database-task-contract.json>' --request '<database-semantic-confirmation-request-v1.json>'
ebo database query --task-contract '<database-task-contract.json>' --request '<database-query-request-v1.json>'
ebo database simulate --task-contract '<database-task-contract.json>' --request '<database-whatif-request-v1.json>'
ebo database test-source --task-contract '<database-task-contract.json>'
ebo database catalog --task-contract '<database-task-contract.json>'
ebo database status --task-contract '<database-task-contract.json>'

在面向Agent的正常接入流程中，“把这个数据库接入EBO”已经同时表达构建意图；项目、只读范围和策略闭合后，Agent应自动选择数据库构建Skill并启动Catalog及策略允许的后续语义探索，用户不需要再选择Skill或重复说“开始探索”。仅测试连接或仅保存凭据不会触发扫描。

1.35.0正式回退基线已开放受治理的catalog_only、自动semantic_bootstrap、targeted_query_ready、resume/stop与固定Source Release上的数据库query。catalog_only不读取业务值、不调用AI；语义模式只经Context Gateway向模型提供当前决策所需证据。目标Binding只有在请求的本体定义与唯一最高分字段Claim精确对应时生成，否则失败关闭；查询允许返回技术可执行但业务口径仍为candidate的Q2，只有覆盖、粒度、单位、新鲜度与核对证据闭合后才能成为Q3。targeted_whatif_ready在缺少完整Fact Contract、参数和边界时明确拒绝，不能把query-ready冒充What-if-ready。

每个封存Release在同一事务内生成可删除重建的Database Semantic Retrieval Projection。它只加速精确/FTS/BM25召回及关系、表族、Binding、Readiness、Query Case邻域，不成为第二事实源；查询Evidence Event只增量刷新候选索引，不自动提升Claim权威。设计与边界见docs/database-support/DBRET-500-database-semantic-retrieval-projection-v1.0.md。

查询入口：

ebo query preflight
ebo query search --task-contract '<query-task-contract.json>' --text '目标指标A'
ebo query get --task-contract '<query-task-contract.json>' --object-id '<metric-id>'
ebo query value --task-contract '<query-task-contract.json>' --metric-id '<metric-id>' --dimensions '{"维度1":"成员A"}'
ebo query trace --task-contract '<query-task-contract.json>' --object-id '<metric-id>' --direction upstream
ebo query health --task-contract '<query-task-contract.json>'
ebo query attribution --task-contract '<query-task-contract.json>' --audit-run-id '<audit-run-id>'
ebo query handover --task-contract '<query-task-contract.json>'
ebo query export-rdf-owl --task-contract '<query-task-contract.json>'

标准化入口：

ebo standardize --contract '<standardize-task-contract.json>'

企业本体携带与语义维护入口：

ebo init
ebo init --confirm-initialize
ebo enterprise export --enterprise-database '<company.ebo.sqlite>' --enterprise-store-id '<enterprise-store-id>' --enterprise-revision 1 --output-directory '<交付目录>'
ebo /做个梦 --workspace-root '<明确的workspace目录>'
ebo enterprise execute --request '<enterprise-operation-request.json>' --output-directory '<收据目录>'
ebo ontology-git status
ebo ontology-git inspect --enterprise-store-id '<enterprise-store-id>' --local-enterprise-revision 1
ebo ontology-git download-release --enterprise-store-id '<enterprise-store-id>' --release-tag '<正式Release tag>'
ebo build adopt-enterprise --task-contract '<task-contract.json>' --handoff '<project-adoption-handoff.json>' --confirm-project-semantic-write
ebo host probe
ebo host config --capture-reason startup

ebo init 是全局运行环境的轻量入口：默认只检查安装版本、产品目录、固定配置位置、运行目录和已配置企业本体；只有缺少运行目录时才返回唯一的确认命令，明确执行 --confirm-initialize 后也只创建这些目录。它不创建配置、项目、企业库或初始化标记，不读取 Excel、不联网；ebo build init 仍只负责具体项目。

/做个梦（或 /dream）一次只消费当前项目的一条学习事件。无待处理事件时不创建配置或企业库；从未建库且确有事件时，在统一运行目录创建只含 shared_candidate 的 candidate-only 企业库，并把实际路径写入 %USERPROFILE%\.dabaige\config.toml。配置中的既有库失联时只提示恢复，不另建身份；该入口不读取 Excel、不发布企业 revision。旧 ebo learn drain --candidate-admission 继续作为兼容入口，并转到同一候选准入能力。

本地正式企业发布仍由企业本体库管理生成发布收据和 Project Adoption Handoff；需要 GitHub 评审时，企业本体库管理先在隔离副本生成 Release Candidate，本地 current 不前移，再由企业本体 Git 分别执行 Commit/Push、PR、Merge 和正式 Release。Git Tag 不是 Release；下载只落运行缓存，不覆盖正在使用的 SQLite，导入仍需企业本体库管理预览和确认。项目库只由 Build 消费采用 Handoff，因此发现或下载新版不会静默改变当前项目语义。

企业本体 Git 仓库采用生成者无关的 releases/r000N/：每代必须包含 RELEASE_NOTES.md、Release Candidate 和 Canonical Exchange，并同步保留最新 ontology/ 可读投影。更新可以由大表哥、其他应用或人员生成，但都先执行 ebo ontology-git validate-release-package --package-directory <目录>，再进入同一 PR／Merge／Release 链；正式发布只读取已合并 Commit 中的包，并在合并后生成绑定 Commit 与 Tag 的 Manifest。完整规则见 企业本体 Git 仓库与 Release 发布规范。

config.toml 可整体省略；宿主只在重新启动、开启新对话或明确重载时读取。已有 git_remote 且宿主支持并行预检时可以轻量检查最新正式 Release：无更新不提示，检查失败不阻塞当前任务，有更新只提示。未配置企业库、未配置远端或路径失联不会使普通 Build、Query、Standardize 判错。

enterprise export 只导出当前已发布修订，文件名固定为 <store>-r<revision>.ebo.sqlite。它不会带出 Excel、数值、项目 Binding 或绝对路径；只有这一正式跨机器文件的收据记录内容 SHA。另一项目通过 ebo build bind-enterprise 固定该 Store 与修订后只读复用定义，不会继承原项目数据和结论。

以上顶层命令是安装后的公开执行入口。Skill 内部 Python 脚本属于产品实现与测试资产，Agent 和业务用户不应根据 Skill、源码或安装目录推导脚本路径。

可选运行诊断

三个公开入口都接受同一个运行时开关，不需要重新安装或打包：

--diagnostics=off       # 默认；不生成性能诊断
--diagnostics=receipt   # 生成结构化运行收据
--diagnostics=trace     # 额外保存stdout、stderr和阶段事件

通过 Agent 执行时可直接说明“本次使用 receipt 诊断”或“本次使用 trace 定位”，Agent 只把对应开关附加到本次目标命令；诊断模式不会成为后续调用的默认值。

启用后，每次TaskContract绑定调用写入<runPath>/diagnostics/<invocationId>/run-receipt.json，并重建diagnostics/index.json供跨调用分析空档。收据记录Python墙钟与CPU时间、进程内存可见值、命令和版本身份、数据库页/WAL元数据、运行产物增删改、阶段耗时、输出流字节与完整性边界。trace模式额外启用 Python 内存追踪，并保存events.jsonl、stdout.log、stderr.log和运行产物前后快照，因此只用于定位热点；性能 A/B 使用 receipt，不能把 trace 墙钟当作正常运行基线。模型Token、客户端排队、Agent实际读取资产和用户等待只有宿主显式提供时才能记录；纯Python运行会明确标记not_exposed_by_python_runtime，不会把缺失数据推断为零。

需要就当前任务请求产品支持时，可运行 ebo diagnostics export --task-contract '<当前task-contract.json>' --output '<当前runPath>/diagnostics/support-summary.json'；省略 --output 时使用该默认位置。它只读同一项目 SQLite 和由 diagnostics/index.json 明确绑定到当前 Run 的原收据，导出白名单化的版本、阶段、公开错误码、完成计数和相对收据引用，不包含原始正文、参数、环境、单元格或凭据，不连接来源数据库、模型或上传服务，也不覆盖已有文件。缺少收据会在摘要中明确标记；安装、入口或依赖问题先按 INSTALL.md 运行 ebo doctor。摘要只保存在本地，预览、合包或上报由宿主在另行取得授权后处理。

可选交互学习收据

宿主能够把本轮业务问句作为已校验的 interaction-context-v1 文件提供时，Build、Query 和 Standardize 的实际业务命令可以附加：

--interaction-context <interaction-context.json>

产品会在业务结果已经确定后保存命令级 InteractionEpisode。它只用于分析常见问题、路由、歧义、查询覆盖和后续产品改进，不是业务本体、ExpertDecision、标准数据或回答证据；捕获失败也不会改变业务结果。没有宿主提供的问句上下文时不生成 Episode，不要求 Agent 手工转抄用户问题，也不增加一次模型调用或默认运行开销。

当前收据只覆盖产品实际看到的命令与结果。纯 CLI 无法读取 Agent 最终答复和用户下一轮反馈，因此这两项会明确标为 not_exposed_by_host / not_provided，不会伪装成完整对话。业务人员的普通答复不显示 Episode ID、内部路径或捕获状态。

需要显式导出已脱敏的命令收据用于评测或领域场景整理时，可以运行：

python tools/export_interaction_dataset.py \
  --run-path <runPath> \
  --output interaction-dataset.jsonl

默认导出 redacted/metadata-only 数据；full-text 必须额外使用 --include-full-text。导出是只读操作，不会把问句或 Agent 分析提升为业务真理。

诊断开关只控制性能与运行轨迹，不关闭工作流状态、来源证据、业务决定和审计记录。正常业务运行默认关闭；复现慢任务时针对单次命令开启。抽取摘要会区分 OOXML 扫描、兼容装载、证据编组、Writer 排队和事务体，并明确并发 Sheet 的分段求和不能当成墙钟；构建完成后的紧凑质量收据已包含来源、本体、Binding、数据库完整性和外键状态，Agent 不需要再查数据库确认同一事实。

大而稀疏的 OOXML Sheet 会在候选坐标人口可闭合时跳过空白矩形。公式密集且达到适用条件的超大 Sheet 会在一次 OOXML 流式读取后，把公式证据准备交给两个有界进程 Worker；普通 Sheet 继续走直接路径，不承担进程启动成本。并行只改变证据准备方式，完整单元格、公式 occurrence、重复引用、版式、批注和来源身份不减少，Region、跨 Sheet 端点、本体与 Binding 仍在全局边界统一收敛。

普通旧式批注可以在 OOXML 快速路径中保留坐标、作者、完整正文和来源修订；标准伴生 VML 只承载当前未声明支持的视觉框、大小和显示态，不再单独触发整本回退。批注部件或关系损坏、threaded comments、超链接、表格及其他未闭合载体仍使用兼容路径，避免为了速度静默丢失业务语境。

大批量导入仍由单一 Writer 按 Sheet 原子提交，失败或宿主中断后只重做未提交单元。诊断人口使用启动基线与已提交事务的精确增量，不再在每个 Sheet 后扫描全库；Binding 也复用一次对象身份集合和既有维度元组权威。上述优化不关闭外键、人口闭合、冲突检查或回滚能力。

正式版本变化见 CHANGELOG.md。

CLI 的精确契约、状态和错误码以构建 Skill、标准化 Skill、查询 Skill、企业本体库管理 Skill和企业本体 Git Skill为准。不得通过 CLI 绕过 Agent 的业务门禁或直接修改 SQLite。

当前能力边界

• 自动验证证明产品机械链路可运行，不证明复杂业务语义已经正确；
• 业务体检可以发现结构风险和候选问题，但不会在缺少证据时量化业务损失；
• Agent 裁决形成的是有证据的候选或专家提交，不自动等于企业正式批准；
• 正式计算、核对和推演必须具备所需维度、聚合、映射和源事实；
• Action、审批、自动调账和写回外部系统不属于当前能力；
• 产品不作为常驻查询平台，不承载多租户、调度或外部权限系统；
• Codex、Claude Code 和其他客户端的装载方式不同，内容一致不等于行为完全等价。

更多技术边界见 INSTALL.md、compatibility.json 和六个本地 Skill 的说明。