@ycodium-ai/plugin-office 0.2.3510 → 0.2.3576

package/README.md

@@ -1,99 +1,108 @@
 # @ycodium-ai/plugin-office
 
-Lets agents create, check, and render Word, PowerPoint, and Excel files on this
-Ycodium machine, and lets the app preview Office files. Nothing is downloaded
-until you start an install from the plugin's settings card.
-
-## What it installs
-
-Each install runs from the settings card, downloads only what is pinned in
-`src/lock.ts`, checks every file against its pinned checksum before unpacking
-it, and discards it on a mismatch. Everything lands in the plugin data
-directory under `runtime/`; system files and fonts are not changed.
-
-- **Engine**: `@deepseek-ai/libreoffice-kit` 0.1.5 and its platform package from
-  npm (a LibreOffice build, MPL-2.0). Windows and macOS run the native engine;
-  Linux runs its WebAssembly build, which needs more memory and starts more
-  slowly. Windows needs the Microsoft Visual C++ 2015–2022 runtime for the
-  machine's architecture.
-- **Python**: Python 3.12 from python-build-standalone with python-docx,
-  python-pptx, openpyxl, XlsxWriter, pandas, Pillow, and lxml, installed from
-  pinned wheels without contacting an index. Windows on ARM has no build.
-- **Chinese fonts**: Noto Sans CJK SC and Noto Serif CJK SC, regular and bold
-  (SIL OFL). Only the engine uses them. Windows and macOS already have Chinese
-  fonts; on Linux without them, Chinese text renders as boxes.
-
-**Check** reports whether the engine starts, the document libraries load, and
-Chinese fonts are available. **Delete engine** removes all three.
-
-Downloads follow the Ycodium server's proxy settings. The settings
-card can point them elsewhere: an npm registry mirror for the engine, a prefix
-put in front of GitHub addresses for Python and fonts, a PyPI files mirror for
-the wheels, and a local folder holding files downloaded ahead of time. Files
-from any source are checked against the same checksums.
-
-## Tools and skills
-
-The plugin gives agents five MCP tools. They run in the conversation's project
-folder, and paths are relative to it.
-
-| Tool                 | What it does                                                                 |
-| -------------------- | ---------------------------------------------------------------------------- |
-| `office_python`      | Tells the agent where the installed Python is, for its own document scripts. |
-| `office_check`       | Checks a document's structure, expected text, and slide or sheet count.      |
-| `office_render`      | Renders pages, slides, or a sheet range to PNG files.                        |
-| `office_convert`     | Converts between formats, such as DOCX to PDF or XLSX to CSV.                |
-| `office_recalculate` | Recalculates a workbook's formulas and saves the values.                     |
-
-The three skills `office-docx`, `office-pptx`, and `office-xlsx` tell agents how
-to write each kind of file with these tools. The result of `office_render`
-shows the rendered pages in the conversation.
-
-## Preview
+Agents can create, edit, check, render, convert, and recalculate Word,
+PowerPoint, and Excel files on the connected Ycodium machine. The app also
+previews Office files. The complete Ycodium installation includes the engine,
+isolated document libraries, and Chinese fonts for offline use.
+
+## What it does
+
+The five tools `office_python`, `office_check`, `office_render`,
+`office_convert`, and `office_recalculate` run in the conversation's project
+folder. The three bundled skills explain document creation and editing.
+`office_render` returns page images and missing-font diagnostics; the app
+shows the images in the conversation.
+
+`office_python` returns the shared Ycodium Python executable together with
+required arguments and environment entries. Run the executable with every
+returned argument, followed by the workspace script path and its arguments.
+These arguments load this plugin's isolated python-docx, python-pptx,
+openpyxl, XlsxWriter, pandas, Pillow, and lxml libraries. Using only the
+executable path does not load the document libraries.
 
 The app previews `.doc`, `.docx`, `.odt`, `.ppt`, `.pptx`, `.odp`, `.xls`,
-`.xlsx`, and `.ods` files by asking this plugin to convert them to PDF. The
-converted file is cached in the plugin's cache directory; changing the source
-converts it again. Until the engine is installed, the preview says the plugin
-is not set up yet and links to plugin settings.
+`.xlsx`, and `.ods` through the plugin's PDF converter. Converted files go
+into the writable plugin cache. Documents and authoring scripts remain in
+the project folder; installed resources are read-only.
+
+## Requirements
+
+Use a complete Ycodium installation that supplies the shared Node and Python
+runtimes and this plugin's platform payload. The plugin uses public plugin
+API version 39 with `host:node`, `host:python`, `process.workspace`, and
+`workspace.read` permissions. It does not look for a system Python,
+LibreOffice, or Node executable.
+
+Windows and macOS use a native LibreOffice engine; Linux uses WebAssembly,
+which needs more memory and starts more slowly. Engine targets are Windows,
+macOS, and Linux on x64 and ARM64. The pinned Python libraries have no
+Windows ARM64 build, so document authoring and Python checks are unavailable
+on that target. LibreOffice pagination can differ from Microsoft Office.
 
 ## Install
 
-```
+The plugin ships enabled with Ycodium as `core.office`. Its npm package can
+also be added to a compatible Ycodium installation:
+
+```text
 ycodium plugin add @ycodium-ai/plugin-office
 ```
 
-The plugin ships enabled with Ycodium as `core.office`. Uninstalling it leaves
-its data directory, including anything it downloaded; **Delete engine** first
-if you want that space back.
+The installed plugin must include the matching platform payload; copying only
+its JavaScript entry does not provide document operations. No engine, font,
+or Python package installation occurs when tools run.
 
-## Requirements
+## Read this before installing
 
-A Ycodium server with plugin API version 3, including `process.spawn` for
-`host:node`, `tar`, `fc-list`, and the installed Python (at most six processes
-at once), `process.workspace`, and `workspace.read`. Supported engine
-platforms: Windows x64/arm64, macOS x64/arm64, Linux x64/arm64.
+Settings → Plugins → Office → **Check** reports the engine backend and
+version, shared Python and document-library availability, and Chinese-font
+version. The check works offline and reports missing, incomplete, or damaged
+components. Restore those files by reinstalling the complete Ycodium package
+from an offline installer.
+
+The bundled Noto Sans SC and Noto Serif SC fonts are private to the engine.
+System fonts are unchanged. Disabling or uninstalling the plugin removes its
+tools and preview converter; documents and saved plugin data remain. Shared
+runtimes belong to Ycodium and are not removed by plugin actions.
+
+## Upgrading
+
+Upgrade the complete Ycodium installation so the plugin and its platform
+payload stay at matching versions. Artifact construction verifies downloads
+against `src/lock.ts`; user machines do not download or run pip to prepare
+document libraries.
 
 ## Developing
 
-```
+```text
 vp run --filter @ycodium-ai/plugin-office build
 vp run --filter @ycodium-ai/plugin-office test
+vp run --filter @ycodium-ai/plugin-office typecheck
 ```
 
-The package builds its own code into `dist/index.js` and the result view into
-`ui/ui.js`. The host supplies the shared `@ycodium-ai/plugin-api` and React at
-runtime. Language catalogs live in `locales/`.
+The package builds `dist/index.js` and `ui/ui.js`; the host supplies the
+shared plugin API and React. Runtime assets live in `runtime/<target>`.
+Build and release scripts stage the platform payload and retain its source,
+license, and font notice files.
 
-`test/checker.test.ts` runs the checker's Python tests and is skipped when no
-Python 3 is found; point `YCODIUM_OFFICE_TEST_PYTHON` at one to run it.
+`test/checker.test.ts` runs Python checker tests when a test interpreter is
+available; `YCODIUM_OFFICE_TEST_PYTHON` selects that interpreter. This test
+setting does not change product runtime discovery.
+
+To check a complete staged artifact, use a new output directory:
+
+```text
+node plugins/office/scripts/remote-check.ts <shared-runtime-target-dir> <office-plugin-dir> <new-output-dir>
+```
 
-To move to other versions, regenerate the whole of `src/lock.ts`; do not edit
-single entries. Then run `scripts/remote-check.ts` on a real Linux and macOS
-machine: it installs and runs everything outside Ycodium, and its header says how
-to bundle it, which steps exist, and how to simulate a machine without Chinese
-fonts.
+This check uses only the supplied executables with an empty PATH and disabled
+network proxy. It creates and edits all three document types, checks their
+structure, renders Chinese text, converts PDFs and CSV, and verifies cached
+formula results after recalculation. It also checks a controlled failing
+content assertion. Run it on each release platform; a pass on one platform
+does not establish compatibility on another.
 
 ## License
 
-UNLICENSED.
+UNLICENSED. Third-party runtime resources retain their own licenses and
+notices in the distributed payload.

package/assets/check_runtime.py

@@ -0,0 +1,8 @@
+"""通过隔离入口验证随包 Office 创作库。"""
+import docx
+import pptx
+import openpyxl
+import pandas
+import PIL
+import lxml
+import xlsxwriter

package/assets/run_office.py

@@ -0,0 +1,34 @@
+"""用此插件隔离的文档库运行工作区脚本。"""
+import pathlib
+import runpy
+import sys
+
+
+def library_search_path(libraries):
+    value = str(libraries)
+    if sys.platform != "win32" or value.startswith("\\\\?\\"):
+        return value
+    if value.startswith("\\\\"):
+        return "\\\\?\\UNC\\" + value[2:]
+    return "\\\\?\\" + value
+
+
+def main():
+    if len(sys.argv) < 5 or sys.argv[1] != "--libraries" or sys.argv[3] != "--":
+        raise SystemExit("Expected --libraries <bundled site-packages> -- <script.py> [args...]")
+    libraries = pathlib.Path(sys.argv[2]).resolve(strict=True)
+    script = pathlib.Path(sys.argv[4]).resolve(strict=True)
+    if not libraries.is_dir():
+        raise SystemExit("The bundled Office document libraries are missing")
+    # -I 排除用户 site-packages 与环境变量；仅此插件的业务依赖进入搜索路径。
+    # 原生扩展的 DLL 加载不继承 Python 的长路径支持，必须显式使用 Windows 扩展路径。
+    sys.path.insert(0, library_search_path(libraries))
+    sys.path.insert(1, str(script.parent))
+    sys.argv = [str(script), *sys.argv[5:]]
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+    runpy.run_path(str(script), run_name="__main__")
+
+
+if __name__ == "__main__":
+    main()