自动化与编程模型

Impulse、Formula、Expo 和 Nu 共用同一种在文档中放置代码并运行它的方式，无论是哪个应用程序、哪种语言。本页面是概述；其下的各页面介绍细节。

• 脚本——Scripts 窗格及其编辑器、即时模式、四个应用程序的对象模型，以及从命令行运行脚本。
• Python——Python Command、=PY.NAME() 函数和智能对象，以及带 pip 的 Python 环境。
• Divooka 图——作为 Function、Command 和事件处理程序的可视化程序，以及图编辑器。
• 工作表函数——你自己的 Formula 函数：=LUA.NAME()、=CS.NAME()、=PY.NAME() 和 =DVK.NAME()。
• 智能对象——Impulse 文档中或 Expo 幻灯片上的文本、表格和图片，其内容来自工作簿、表达式、图或 Data Source。
• Data Source——来自 Web API、SQLite 文件或 ODBC 数据库的实时表格、Data Sources 选项卡，以及按列名设置格式的智能表格。
• Document Parameters 与文档会话——文档共享的值，以及同一个图如何在 Methodox Office 和 Divooka Compute 中处理文档。
• 依赖关系——文档中各部分之间数据流向的示意。
• 命令行与转换——mos、与 LibreOffice 兼容的开关，以及在没有窗口的情况下转换文档。
• 版本——文档的代码在 Standard 版和 Compute 版中可以使用什么，以及如何找到 Divooka Compute。
• 扩展——为所有人安装、而非由某个文档携带的命令、函数和库。
• 助手——一个 AI 助手，可在 Start Centre 中或通过 mos mcp 在任何 MCP 客户端中读取和编辑文档，并编写其自动化。

Command、Function 和事件处理程序

文档中的每段代码都扮演以下三种角色之一。

• Command 在有人运行它时更改文档：从 Scripts 窗格或命令行运行的脚本，或从脚本中按名称调用的应用程序自身的某个菜单命令。Command 作为一个事务运行：它更改的所有内容都是 Edit ▸ Undo 中的一个步骤；如果失败，它所做的所有更改都会回滚。
• Function 根据其输入计算出一个值，不更改任何内容。由应用程序决定何时运行它：工作表函数在其读取的单元格发生变化时运行，智能对象在文档刷新时运行。由于 Function 无法更改文档，重新计算或刷新它始终是安全的，并且相同的输入总是得到相同的结果。
• 事件处理程序是文档在发生某些事情时运行的 Command：打开、保存、某个区域发生更改、工作簿完成计算、某个参数发生更改、智能对象刷新、幻灯片放映开始、翻页或结束。每个处理程序作为一个事务运行；由其自身更改所引发的事件不会再传递给它，撤消和重做不会引发任何事件，而一秒钟内超过 64 个事件的大量涌入会暂停处理程序。事件处理程序以 Divooka 图的形式编写。

智能对象是 Function，而不是宏：Impulse 智能对象之于文档，就如同公式之于单元格。Formula 的 SQL.VIEW 会在网格中让 SQL 查询的结果保持最新，它在同样的意义上也是一个 Function。

数据源 Function 是从网络获取数据或读取文件的 Function。它们只在你请求时获取数据——Formula 中的 Data ▸ Refresh Data（Ctrl+Shift+F5）、Impulse 和 Expo 中的 Refresh All（Ctrl+Shift+F9），或某个 Command——或者在它们读取的参数发生变化时获取，并把获取到的内容保存在文档中；因此在两次刷新之间，以及在离线打开的文档中，它们会以上次刷新的结果作答。函数通过在图中使用获取数据的节点，或通过在脚本中获取数据，而成为数据源 Function。Data Source 是同一思路的无代码版本：在编辑器中构建的、针对 Web API 或数据库的查询，其结果是一张表格。

语言

语言	文件	运行方式
Lua	.lua	在沙箱中运行：自身没有文件或进程访问权限（没有 io 和 os.execute）；只能通过宿主访问文件和网络。
C#	.csx	在运行时针对同一对象模型编译，并进行类型检查。
Python	.py	在套件自带的 SteelPython 上运行；在 Standard 版中受防护机制限制，只允许计算类模块。参见 Python。
Divooka 图	.dvj，即 Divooka .dvk 的文本形式	Function 图、Routine 图和 Events 图，由 Divooka 的 No-Reflection Interpreter 运行；参见 Divooka 图。

对象模型在每种语言中都相同：Lua 和 Python 中为 app、doc 和 session，C# 中为 App、Doc 和 Session；名称在 Lua 中使用 lowerCamel 形式（sheet.usedRange），在 Python 中使用 snake_case（sheet.used_range），在 C# 中使用 PascalCase（sheet.UsedRange）。在这三种语言中，位置都从 1 开始计数。参见脚本。

代码保存在哪里

携带代码的文档保留其常用扩展名 .docx、.xlsx 和 .pptx；没有单独的启用宏的格式。工作簿的工作表函数和文档的智能对象都存储在文件内部，位于 Office 会保留的自定义 XML 部件中（参见文件格式）。

每个脚本和图也都存储在文档内部，同时存储的还有文档的参数以及其数据源 Function 上次获取的数据：Scripts 窗格中的 Save 把编辑作为可撤消的更改保存在文档中（通过 File ▸ Save 写入磁盘），Export 把一份普通副本写入你选择的文件；而早期版本中位于文档旁边的脚本文件夹（Report.scripts\）会在文档打开时被纳入文档。

Document Parameter

Function 无法更改文档，因此多个 Function 共享的值——本金、城市、地区、利率——保存在 Document Parameter 中：它们是命名值，每个都是数字、文本、逻辑值或日期，存储在文档中，并在侧栏的 Parameters 面板（Tools ▸ Parameters）中编辑。公式以 =PARAM("Region") 的形式读取它们，脚本和 Data Source 以 param.Region 的形式读取，并且只有 Command 才能设置参数。更改参数会精确地重新计算读取它的内容。

参数是文档的成员，Divooka 图通过 This Document 节点访问文档：在 Methodox Office 中，该节点对应打开的文档；在 Divooka Compute 中，则对应发送给它的副本或它打开的文件。因此同一个图在两者中的运行方式相同。Document Parameters 与文档会话对此有完整说明，包括如何更新早期版本中的图。

信任

打开文档绝不会运行其代码。 携带代码的文档打开时，上方会显示一个黄色栏，写着 Scripts disabled，并带有一个 Enable 按钮；将鼠标悬停在该栏上会列出文档携带的代码。在启用之前，其工作表函数显示 #BLOCKED!，其 Lua、C#、Python 和图智能对象不会刷新；读取工作簿的智能对象以及 Data Source 属于数据而非代码，无论如何都会刷新。

信任会被记住。每个人都有一个信任存储，即 Methodox Office 设置文件夹中的 trust.json，它针对文档中所有会运行的内容的哈希值，记录此人启用过的每个文档。再次打开同一文档时无需再次确认；而只要更改其代码中的一个字符，无论是在 Methodox Office 中还是在其他任何地方更改，都会再次询问。参数和获取的数据不是代码，不计入其中。

授予的访问权限

在 Standard 版中，文档的代码只能通过宿主访问网络和文件，并且只能访问用户允许的位置：

语言	调用
Lua	host.get(url)、host.getJson(url)、host.getImage(url)、host.readText(path)、host.url(...)
C#	Host.Get、Host.GetJson、Host.GetImage、Host.ReadText、Host.Url
Python	相同的调用，使用 snake_case：host.get_json(url)
Divooka 图	HTTP Get、HTTP Get Bytes 和 Read Text File 节点
Data Source	其 Web API、SQLite 文件或 ODBC 连接

当代码或 Data Source 请求尚未被授予的内容时，一个橙色栏会说明请求的是什么，例如 Needs GET api.open-meteo.com 或 Needs Connect Sales.db，并带有一个 Allow 按钮。Enable 和 Allow 会继续执行正在等待的操作：在脚本被禁用期间更改的参数，会在你按下 Enable 后生效；每次 Allow 都会让刷新继续进行，并请求它所需的下一项，因此需要多项授权的文档会逐一请求，而无需重新打开。每个网站、文件和数据库都按文档单独允许，并与启用一样，针对文档的代码哈希值记录在信任存储中。当出现故障时，一个红色栏会说明原因；当故障发生在图的某个节点上时，其按钮会打开该图并选中该节点。

两个版本

受信任文档的代码可以使用什么，由 Methodox Office 的版本决定：Methodox Office（Standard）运行 Lua、C#、受防护的 Python，以及由经过审核的 Office 节点和 Divooka 标准库中的纯例程构成的图，且只能通过宿主授予的调用访问网络和文件；Methodox Office + Divooka Compute 还会运行使用其旁边已安装的 Divooka 包的图，以及使用文档 Python 环境中的包的完整 Python，在用户信任该文档后以完全信任方式运行。两个版本都不包含 Divooka Compute 本身，Office 会在它已安装时找到它。参见版本。

如果图使用了其版本不允许的节点，则会在任何内容运行之前被拒绝，消息中会指出该图和该节点。

SQL

Formula 的 SQL Workbench、SQL.VIEW 和 SQL.STORED 使用 SQLite 的 SQL 以只读方式查询工作簿的表格、命名区域和工作表；SQL.STORED 按名称运行保存在 Workbench 中的查询，并将值绑定到其参数。承载该引擎的 .NET 程序可通过 Divooka.Office.Calc.Sql 包中的 WorkbookSql.Query(workbook, sql) 访问同一层。脚本的对象模型中尚未提供该功能。要查询工作簿之外的数据库，请使用 Data Source。

扩展

应当对每个文档都可用、而非由某个文档携带的代码，就是扩展：Tools ▸ Extensions 上的命令、工作表函数和脚本库，从 Start Centre 安装，并按照与文档代码相同的规则运行。

无窗口运行

每个应用程序都可以从命令行运行脚本、转换文档和打印为 PDF，而无需打开窗口；mos 则可以为整个套件完成所有这些操作。参见命令行与转换。

示例

套件的 Examples\Automation 文件夹包含这些页面中使用的脚本和文档：Lua、C# 和 Python 示例脚本，绑定到预算工作簿的智能报告，由图和参数驱动的贷款计算器和贷款信函，带有事件处理程序的工作簿，以及图编辑器的工作簿。Weather Report、Market Dashboard、Data Sources 工作簿和 Nu 的三角形圆环位于各自应用程序的文件夹中。参见示例。