自動化與程式設計模型

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 的三角形圓環位於各自應用程式的資料夾中。參見示例。