diff --git a/.agents/notes/implemented/architecture/2026-10-26-cross-deployment-office-kit.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-26-cross-deployment-office-kit.i18n.yaml index 7c305a1d85..05d9a1f575 100644 --- a/.agents/notes/implemented/architecture/2026-10-26-cross-deployment-office-kit.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-10-26-cross-deployment-office-kit.i18n.yaml @@ -15,5 +15,5 @@ en: dbf6832a4ba0107d zh: b707f4c3bef6a7bc /agent-note-office-skills-in-every-deployment-with-one-office-kit-package/consequences: - en: 5f8235651c7055c1 - zh: 925853e1bdff3f1a + en: ecac32671521722b + zh: 5822cc8b5db316ac diff --git a/.agents/notes/implemented/architecture/2026-10-26-cross-deployment-office-kit.md b/.agents/notes/implemented/architecture/2026-10-26-cross-deployment-office-kit.md index d003886bb0..4a56dd1707 100644 --- a/.agents/notes/implemented/architecture/2026-10-26-cross-deployment-office-kit.md +++ b/.agents/notes/implemented/architecture/2026-10-26-cross-deployment-office-kit.md @@ -34,7 +34,7 @@ An absent Kit degrades instead of failing a load. The conversion service registe ## Consequences -Ordinary Web and SDK sessions without a bundled environment list the four Office skills, which adds their summaries to the first context. Deployments without Kit see `unavailable` previews and an `office` tool that reports the missing Kit instead of failing at startup; skill loading does not check for Kit; a later Kit installation takes effect for conversion without reloading the provider. External compositions migrate from the `office-to-pdf` row, `ctx.officeToPdf`, and the `officeToPdf/*` Remote methods to the `office-kit` package. +Ordinary Web and SDK sessions without a bundled environment list the four Office skills, which adds their summaries to the first context. Deployments without Kit see `unavailable` previews and an `office` tool that reports the missing Kit instead of failing at startup; skill loading does not check for Kit; a later Kit installation takes effect for conversion without reloading the provider. External compositions migrate from the `office-to-pdf` row, `ctx.officeToPdf`, and the `officeToPdf/*` Remote methods to the `office-kit` package through the [upgrade guide](../../../../docs/upgrade-guide/v0.2.2-alpha.2/office-kit-package/guide.md). Processes launched from the Desktop built-in terminal inherit `DSH_BUNDLED_PRIMARY_RUNTIME`, so the SDK uses its bundled environment. The shell publishes no Kit location; child applications resolve their own Kit. diff --git a/.agents/notes/implemented/architecture/2026-10-26-cross-deployment-office-kit.zh.md b/.agents/notes/implemented/architecture/2026-10-26-cross-deployment-office-kit.zh.md index f12f556067..65f41c0f47 100644 --- a/.agents/notes/implemented/architecture/2026-10-26-cross-deployment-office-kit.zh.md +++ b/.agents/notes/implemented/architecture/2026-10-26-cross-deployment-office-kit.zh.md @@ -34,7 +34,7 @@ Kit 缺失时降级,而不是加载失败。转换服务照常注册,以代 ## 影响 -没有内置环境的普通 Web 和 SDK 会话会列出四个 Office 技能,首个上下文因此增加它们的摘要。没有 Kit 的部署看到的是 `unavailable` 预览和报告 Kit 缺失的 `office` 工具,而不是启动失败;加载技能时不检查 Kit;之后安装的 Kit 无需重新加载提供方即可用于转换。外部组合需从 `office-to-pdf` 配置行、`ctx.officeToPdf` 和 `officeToPdf/*` Remote 方法迁移到 `office-kit` 包。 +没有内置环境的普通 Web 和 SDK 会话会列出四个 Office 技能,首个上下文因此增加它们的摘要。没有 Kit 的部署看到的是 `unavailable` 预览和报告 Kit 缺失的 `office` 工具,而不是启动失败;加载技能时不检查 Kit;之后安装的 Kit 无需重新加载提供方即可用于转换。外部组合按[升级指南](../../../../docs/upgrade-guide/v0.2.2-alpha.2/office-kit-package/guide.zh.md)从 `office-to-pdf` 配置行、`ctx.officeToPdf` 和 `officeToPdf/*` Remote 方法迁移到 `office-kit` 包。 从 Desktop 内置终端启动的进程会继承 `DSH_BUNDLED_PRIMARY_RUNTIME`,因此 SDK 使用其内置环境。Desktop 壳不发布 Kit 位置;子应用自行解析自己的 Kit。 diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/office-kit-package/guide.i18n.yaml b/docs/upgrade-guide/v0.2.2-alpha.2/office-kit-package/guide.i18n.yaml new file mode 100644 index 0000000000..32676207d8 --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/office-kit-package/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading +# section, a hash of its English and Chinese blocks outside code blocks and generated regions. +# After editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-alpha.2/office-kit-package/guide.md +/: + en: 0e3fae218b0fe86f + zh: 31fa1f4ac5cfffe6 +/deepseek-ai-dsh-office-kit-replaces-deepseek-ai-dsh-office-to-pdf: + en: 905ef2a0e635d288 + zh: 7a661f303ee0f2bb +/deepseek-ai-dsh-office-kit-replaces-deepseek-ai-dsh-office-to-pdf/change: + en: bab98293da85a9d2 + zh: 2c1d60e0f7c52a28 +/deepseek-ai-dsh-office-kit-replaces-deepseek-ai-dsh-office-to-pdf/migration: + en: 9871a035772e8bbd + zh: 53f05c66de3ceb0e diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/office-kit-package/guide.md b/docs/upgrade-guide/v0.2.2-alpha.2/office-kit-package/guide.md new file mode 100644 index 0000000000..1e7b5676fb --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/office-kit-package/guide.md @@ -0,0 +1,34 @@ +--- +kind: upgrade-guide +description: "`@deepseek-ai/dsh-office-kit` replaces `@deepseek-ai/dsh-office-to-pdf`, renaming its service, Remote methods, exported types, and configuration row." +--- + +# `@deepseek-ai/dsh-office-kit` replaces `@deepseek-ai/dsh-office-to-pdf` + +English | [中文](guide.zh.md) + +## Change + +The Office conversion provider moved from `@deepseek-ai/dsh-office-to-pdf` to `@deepseek-ai/dsh-office-kit`. The new package also exports LibreOffice Kit location functions from `@deepseek-ai/dsh-office-kit/locate`. Compositions, plugins, and Clients that name the old package, service, Remote methods, or exported symbols are affected: + +| Old | New | +|---|---| +| `cordis.yml` row `id: office-to-pdf`, `name: '@deepseek-ai/dsh-office-to-pdf'` | `id: office-kit`, `name: '@deepseek-ai/dsh-office-kit'`; configuration keys are unchanged | +| `ctx.officeToPdf` | `ctx.officeKit` | +| Remote `officeToPdf/render`, `officeToPdf/generation` | `officeKit/render`, `officeKit/generation` | +| `OfficeToPdf` | `OfficeKit` | +| `OfficeToPdfError`, `OfficeToPdfErrorCode` | `OfficeKitError`, `OfficeKitErrorCode` | +| `OfficeToPdfGeneration` | `OfficeKitGeneration` | +| `OfficeToPdfRequest`, `OfficeToPdfResult`, `OfficeToPdfPriority`, `OfficeToPdfKey` | `OfficeKitRequest`, `OfficeKitResult`, `OfficeKitPriority`, `OfficeKitKey` | + +The `document-render/failed` Remote error, `RenderedDocumentBytes`, `OfficeSourceKey`, and `OfficeExtension` keep their names. The `/types` and `/remote` entries remain. + +The provider previously failed to load when LibreOffice Kit was absent. It now registers without Kit; each conversion that needs a converter rejects with `OfficeKitError` code `unavailable` and locates Kit again, so installing Kit later takes effect without reloading the provider. + +## Migration + +1. In `cordis.yml`, patches, and overlays, change the row `id: office-to-pdf` to `id: office-kit` and its `name` to `'@deepseek-ai/dsh-office-kit'`. Keep its `config` block unchanged. +2. Replace the dependency `@deepseek-ai/dsh-office-to-pdf` with `@deepseek-ai/dsh-office-kit` in `package.json`, and update import specifiers, including `/types` and `/remote`. +3. Rename `ctx.officeToPdf`, Remote method names, and the exported symbols listed above. +4. Code that treated a load failure of the conversion row as "Kit absent" now checks for `OfficeKitError` with code `unavailable` from conversion instead. +5. Confirm the migration by searching the project for `office-to-pdf`, `officeToPdf`, and `OfficeToPdf`, then opening a DOCX file in the Web document preview. diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/office-kit-package/guide.zh.md b/docs/upgrade-guide/v0.2.2-alpha.2/office-kit-package/guide.zh.md new file mode 100644 index 0000000000..0b5a2a333d --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/office-kit-package/guide.zh.md @@ -0,0 +1,34 @@ +--- +kind: upgrade-guide +description: "`@deepseek-ai/dsh-office-kit` 取代 `@deepseek-ai/dsh-office-to-pdf`,其服务、Remote 方法、导出类型和配置行随之改名。" +--- + +# `@deepseek-ai/dsh-office-kit` 取代 `@deepseek-ai/dsh-office-to-pdf` + +[English](guide.md) | 中文 + +## 变更 + +Office 转换提供方从 `@deepseek-ai/dsh-office-to-pdf` 移到 `@deepseek-ai/dsh-office-kit`。新包还从 `@deepseek-ai/dsh-office-kit/locate` 导出 LibreOffice Kit 定位函数。引用旧包、服务、Remote 方法或导出符号的组合、插件和 Client 受到影响: + +| 旧名 | 新名 | +|---|---| +| `cordis.yml` 行 `id: office-to-pdf`、`name: '@deepseek-ai/dsh-office-to-pdf'` | `id: office-kit`、`name: '@deepseek-ai/dsh-office-kit'`;配置项不变 | +| `ctx.officeToPdf` | `ctx.officeKit` | +| Remote `officeToPdf/render`、`officeToPdf/generation` | `officeKit/render`、`officeKit/generation` | +| `OfficeToPdf` | `OfficeKit` | +| `OfficeToPdfError`、`OfficeToPdfErrorCode` | `OfficeKitError`、`OfficeKitErrorCode` | +| `OfficeToPdfGeneration` | `OfficeKitGeneration` | +| `OfficeToPdfRequest`、`OfficeToPdfResult`、`OfficeToPdfPriority`、`OfficeToPdfKey` | `OfficeKitRequest`、`OfficeKitResult`、`OfficeKitPriority`、`OfficeKitKey` | + +Remote 错误 `document-render/failed`、`RenderedDocumentBytes`、`OfficeSourceKey` 和 `OfficeExtension` 保持原名。`/types` 和 `/remote` 入口仍然保留。 + +原先 LibreOffice Kit 缺失时提供方加载失败。现在没有 Kit 时提供方照常注册;每次需要转换器的转换都以代码为 `unavailable` 的 `OfficeKitError` 拒绝,并重新定位 Kit,因此之后安装的 Kit 无需重新加载提供方即可生效。 + +## 迁移 + +1. 在 `cordis.yml`、patch 和 overlay 中,把 `id: office-to-pdf` 行改为 `id: office-kit`,并把其 `name` 改为 `'@deepseek-ai/dsh-office-kit'`。`config` 块保持不变。 +2. 在 `package.json` 中用 `@deepseek-ai/dsh-office-kit` 替换依赖 `@deepseek-ai/dsh-office-to-pdf`,并更新导入路径,包括 `/types` 和 `/remote`。 +3. 按上表重命名 `ctx.officeToPdf`、Remote 方法名和导出符号。 +4. 原先把转换行加载失败视为“Kit 缺失”的代码,改为检查转换返回的、代码为 `unavailable` 的 `OfficeKitError`。 +5. 在项目中搜索 `office-to-pdf`、`officeToPdf` 和 `OfficeToPdf` 确认已无残留,然后在 Web 文档预览中打开一个 DOCX 文件,确认迁移完成。 diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/office-tool/guide.i18n.yaml b/docs/upgrade-guide/v0.2.2-alpha.2/office-tool/guide.i18n.yaml new file mode 100644 index 0000000000..8db04b4d4f --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/office-tool/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading +# section, a hash of its English and Chinese blocks outside code blocks and generated regions. +# After editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-alpha.2/office-tool/guide.md +/: + en: f0d0ff45b1a6e1ba + zh: ebba4868e2b8b524 +/office-operations-use-the-office-tool: + en: 23561ffd67a7f731 + zh: 5c04aeac11f2c529 +/office-operations-use-the-office-tool/change: + en: 67675730e02895ce + zh: c5dfcc9d2df35c64 +/office-operations-use-the-office-tool/migration: + en: 91150015dc40719f + zh: 74536832842a7da5 diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/office-tool/guide.md b/docs/upgrade-guide/v0.2.2-alpha.2/office-tool/guide.md new file mode 100644 index 0000000000..a49edd19bc --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/office-tool/guide.md @@ -0,0 +1,43 @@ +--- +kind: upgrade-guide +description: "Office operations move from shell-run Kit CLI paths to the Host-run office tool; renders save no image files, skill-office loses node and cli and gains pythonEnvironment, and Web and SDK mount Office skills." +--- + +# Office operations use the `office` tool + +English | [中文](guide.zh.md) + +## Change + +Office rendering, conversion, and recalculation no longer run the LibreOffice Kit CLI through the shell. The [`@deepseek-ai/dsh-tool-office`](../../../../packages/document/tool-office/README.md) package registers a resident `office` tool. The shipped SDK profile and the `standard` and `ptc` presets of the Web and Desktop profiles mount it, so their requests declare it; `minimal` does not. Configurations and plugins that used the CLI path are affected: + +| Removed | Replacement | +|---|---| +| `skill-office` configuration keys `node` and `cli` | None; the Office skills direct operations to the `office` tool | +| Node/CLI paths in the Office skills | The `office` tool; [removed operation skills](../office-operation-skills/guide.md) | +| `DSH_BUNDLED_OFFICE_CLI` and `DSH_BUNDLED_OFFICE_NODE` | None; no component reads them | + +`DSH_BUNDLED_OFFICE_SKILLS`, `DSH_PRIMARY_RUNTIME`, and `DSH_BUNDLED_PRIMARY_RUNTIME` keep their meaning. The `office-kit` row gains `outputDirectory`, `outputRetentionMs`, and `maxOutputStoreBytes`. + +`render` returns page images only for the model to view and saves no PNG or other image file. Converted and recalculated files return as temporary paths under `$DSH_HOME/office-kit/outputs` for the model to copy with the shell. A request to export pages as images gets an offer of a PDF export; for a file, call `office` with `operation: "convert"` and `format: "pdf"`. + +The tool runs model-started Office work in the native LibreOffice Kit engine inside the Host process through `ctx.officeKit`, outside the shell sandbox and PTC permissions; inputs remain subject to the filesystem backend's read authority. The native parser processes untrusted documents with the Host user's permissions, affecting deployments that relied on the shell sandbox for document parsing. + +`skill-office` gains `pythonEnvironment`. Its default, `'workspace-dependencies'`, directs the Python skills to `load_workspace_dependencies`; a composition without `@deepseek-ai/dsh-tool-workspace-dependencies` must set `'user'`. + +The Web and SDK profiles mount the Office skills by default, including without a primary runtime; a new Session lists them in its first request context and the `/` menu. + +## Migration + +1. Remove `node` and `cli` from every `skill-office` row in `cordis.yml`, patches, and overlays. +2. Compositions that mount `@deepseek-ai/dsh-skill-office` without the shipped bundles also mount `@deepseek-ai/dsh-office-kit` and `@deepseek-ai/dsh-tool-office`, and set `pythonEnvironment: user` unless they mount `@deepseek-ai/dsh-tool-workspace-dependencies`. +3. Stop setting `DSH_BUNDLED_OFFICE_CLI` and `DSH_BUNDLED_OFFICE_NODE` in launchers. +4. Update expected first request contexts and `/` menus of Web or SDK Sessions to include the Office skills. +5. A `standard` or `ptc` preset saved from the Agent Preset editor replaces the shipped plugin list for that preset id, so its sessions lack the `office` tool. Add this row to the saved list in the editor, or to `config.plugins` of the `preset-standard` or `preset-ptc` row in `$DSH_HOME/profiles//cordis.patch.yml` (``: `web` or `desktop`), then start a new session: + + ```yaml + - id: tool-office + name: '@deepseek-ai/dsh-tool-office' + ``` + +6. Confirm: a new `standard` or `ptc` Session declares `office`, and `office` with `operation: "convert"` and `format: "pdf"` returns a temporary PDF path or the `unavailable` message. diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/office-tool/guide.zh.md b/docs/upgrade-guide/v0.2.2-alpha.2/office-tool/guide.zh.md new file mode 100644 index 0000000000..279704ab93 --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/office-tool/guide.zh.md @@ -0,0 +1,43 @@ +--- +kind: upgrade-guide +description: "Office 操作从经 shell 执行的 Kit CLI 路径改为在 Host 内运行的 office 工具;渲染不保存图片文件,skill-office 删除 node 和 cli 并新增 pythonEnvironment,Web 和 SDK 默认挂载 Office 技能。" +--- + +# Office 操作改用 `office` 工具 + +[English](guide.md) | 中文 + +## 变更 + +Office 渲染、转换和重算不再通过 shell 运行 LibreOffice Kit CLI。[`@deepseek-ai/dsh-tool-office`](../../../../packages/document/tool-office/README.zh.md) 包注册常驻的 `office` 工具。随发行版提供的 SDK profile,以及 Web 和 Desktop profile 的 `standard`、`ptc` 预设挂载该工具,因此其请求会声明它;`minimal` 不挂载。使用过 CLI 路径的配置和插件受到影响: + +| 已删除 | 替代 | +|---|---| +| `skill-office` 配置键 `node` 和 `cli` | 无;Office 技能让模型调用 `office` 工具执行操作 | +| Office 技能中的 Node/CLI 路径 | `office` 工具;[已删除的操作技能](../office-operation-skills/guide.zh.md) | +| `DSH_BUNDLED_OFFICE_CLI` 和 `DSH_BUNDLED_OFFICE_NODE` | 无;不再有组件读取它们 | + +`DSH_BUNDLED_OFFICE_SKILLS`、`DSH_PRIMARY_RUNTIME` 和 `DSH_BUNDLED_PRIMARY_RUNTIME` 含义不变。`office-kit` 行新增 `outputDirectory`、`outputRetentionMs` 和 `maxOutputStoreBytes`。 + +`render` 只返回供模型查看的页面图片,不保存 PNG 或其他图片文件。转换和重算的文件以 `$DSH_HOME/office-kit/outputs` 下的临时路径返回,由模型用 shell 复制。把页面导出为图片的请求会得到导出 PDF 的建议;需要文件时,以 `operation: "convert"` 和 `format: "pdf"` 调用 `office`。 + +该工具通过 `ctx.officeKit` 在 Host 进程内用原生 LibreOffice Kit 引擎执行由模型发起的 Office 操作,不受 shell 沙箱和 PTC 权限约束;输入仍受文件系统后端读取权限的约束。原生解析器以 Host 用户的权限处理不可信的文档,依赖 shell 沙箱约束文档解析的部署因此受到影响。 + +`skill-office` 新增 `pythonEnvironment`。默认值 `'workspace-dependencies'` 让 Python 技能调用 `load_workspace_dependencies`;没有挂载 `@deepseek-ai/dsh-tool-workspace-dependencies` 的组合必须设为 `'user'`。 + +Web 和 SDK profile 默认挂载 Office 技能,没有 primary runtime 时也挂载;新 Session 会在首条请求上下文和 `/` 菜单中列出它们。 + +## 迁移 + +1. 从 `cordis.yml`、patch 和 overlay 的所有 `skill-office` 行中删除 `node` 和 `cli`。 +2. 不使用随发行版 bundle、自行挂载 `@deepseek-ai/dsh-skill-office` 的组合,同时挂载 `@deepseek-ai/dsh-office-kit` 和 `@deepseek-ai/dsh-tool-office`;除非挂载了 `@deepseek-ai/dsh-tool-workspace-dependencies`,否则设置 `pythonEnvironment: user`。 +3. 不再在启动器中设置 `DSH_BUNDLED_OFFICE_CLI` 和 `DSH_BUNDLED_OFFICE_NODE`。 +4. 把 Web 或 SDK Session 首条请求上下文和 `/` 菜单的预期结果更新为包含 Office 技能。 +5. 在 Agent 预设编辑器中保存过的 `standard` 或 `ptc` 预设会按预设 id 替换随发行版提供的插件列表,因此其 Session 没有 `office` 工具。请在编辑器中把下面这一行加入已保存的列表,或加入 `$DSH_HOME/profiles//cordis.patch.yml` 中 `preset-standard` 或 `preset-ptc` 行的 `config.plugins`(``:`web` 或 `desktop`),然后新建 Session: + + ```yaml + - id: tool-office + name: '@deepseek-ai/dsh-tool-office' + ``` + +6. 确认:`standard` 或 `ptc` 的新 Session 声明了 `office`;以 `operation: "convert"` 和 `format: "pdf"` 调用 `office` 会返回临时 PDF 路径或 `unavailable` 消息。