dsh-office-tools 1.0.0 → 1.0.2

package/README.md

@@ -6,6 +6,8 @@ Eight model-facing Office file tools for DeepSeek Harness, running entirely in t
 
 > Install: `dsh plugin --profile web add github:kw78/dsh-office-tools`
 
+> DSH Store lists a fixed Commit; verify the installed source against it: `ae1ddd40f98debf4b1430748d287951f35faaf36` (tag `v1.0.0`). Later commits on `main` carry test/doc additions only unless the version bumps.
+
 Eight model-facing Office file tools for DeepSeek Harness, running entirely in the plugin host half — dependency-free since 1.0.0: every package is generated and parsed by this plugin's own OOXML engine, and every byte crosses the official DSH filesystem service (`ctx.fs`), never the raw file system.
 
 | Tool | Purpose |

package/README.zh.md

@@ -4,6 +4,8 @@
 
 > 安装：`dsh plugin --profile web add github:kw78/dsh-office-tools`
 
+> DSH Store 固定 Commit 校验源：`ae1ddd40f98debf4b1430748d287951f35faaf36`（tag `v1.0.0`）。其后的 `main` 提交仅为测试/文档补充，除非版本号提升。
+
 为 DeepSeek Harness 提供 8 个模型可调用的 Office 文件工具，全部运行在 host 半 —— 1.0.0 起零运行时依赖：所有文件由插件自带的 OOXML 引擎生成与解析，所有字节都经由官方文件服务 `ctx.fs` 传输，插件自身不直接触碰文件系统。
 
 | 工具 | 作用 |

package/lib/index.js

@@ -357,6 +357,15 @@ import { extname, isAbsolute, join, relative, resolve } from "node:path";
 var MAX_TEXT_CHARS = 2e5;
 var MAX_READ_CELLS = 2e5;
 var MAX_WRITE_CELLS = 2e5;
+async function resolveWritePolicy(ctx, exec) {
+  if (ctx.fs.sandboxMode === void 0) return void 0;
+  const service = typeof ctx.get === "function" ? ctx.get("sandboxPolicy") : void 0;
+  if (service === void 0 || service === null) {
+    throw new Error("office tools: the mounted filesystem confines but ctx.sandboxPolicy is missing");
+  }
+  if (typeof service.resolve !== "function") return void 0;
+  return service.resolve(exec.agent === void 0 ? {} : { session: exec.agent.session });
+}
 function workspaceRootOf(exec) {
   const cwd = exec.agent?.session.header.cwd;
   if (cwd === void 0 || cwd === "") {
@@ -374,19 +383,20 @@ function assertLexicallyWithin(root, candidate) {
     throw new Error(`path "${candidate}" escapes the session workspace "${root}"`);
   }
 }
-async function resolveOfficePath(exec, ctx, rawPath, allowedExts, mustExist) {
+async function resolveOfficePath(exec, ctx, rawPath, allowedExts, mustExist, writePolicy) {
   exec.signal.throwIfAborted();
   if (rawPath.trim() === "") throw new Error("path must be a non-empty string");
   const root = workspaceRootOf(exec);
-  const candidate = resolve(isAbsolute(rawPath) ? rawPath : join(root, rawPath));
-  assertLexicallyWithin(root, candidate);
+  const effectiveRoot = writePolicy?.workspaceRoot ? resolve(writePolicy.workspaceRoot) : root;
+  const candidate = resolve(isAbsolute(rawPath) ? rawPath : join(effectiveRoot, rawPath));
+  assertLexicallyWithin(effectiveRoot, candidate);
   const ext = extname(candidate).toLowerCase();
   if (!allowedExts.includes(ext)) {
     throw new Error(`expected ${allowedExts.join(" or ")} file, got extension "${ext || "(none)"}"`);
   }
   const fs = ctx.fs;
-  const rootTarget = await fs.resolve(".", { cwd: root, signal: exec.signal });
-  const target = await fs.resolve(rawPath, { cwd: root, signal: exec.signal });
+  const rootTarget = await fs.resolve(".", { cwd: effectiveRoot, signal: exec.signal });
+  const target = await fs.resolve(rawPath, { cwd: effectiveRoot, signal: exec.signal });
   if (!fs.contains(rootTarget, target)) {
     throw new Error(`path "${rawPath}" escapes the session workspace "${root}"`);
   }
@@ -412,9 +422,9 @@ async function readOfficeBytes(exec, ctx, target) {
   exec.signal.throwIfAborted();
   return { bytes, sizeBytes: bytes.byteLength };
 }
-async function saveOfficeText(exec, ctx, target, text) {
+async function saveOfficeText(exec, ctx, target, text, writePolicy) {
   exec.signal.throwIfAborted();
-  await ctx.fs.writeText(target, text, void 0, exec.signal);
+  await ctx.fs.writeText(target, text, void 0, exec.signal, writePolicy);
   exec.signal.throwIfAborted();
   return Buffer.byteLength(text, "utf-8");
 }
@@ -854,7 +864,8 @@ function registerExcelCreate(ctx) {
       locations: [{ path: args.path }]
     }),
     async execute(args, exec) {
-      const target = await resolveOfficePath(exec, ctx, args.path, [".xlsx"], false);
+      const writePolicy = await resolveWritePolicy(ctx, exec);
+      const target = await resolveOfficePath(exec, ctx, args.path, [".xlsx"], false, writePolicy);
       await assertMayCreate(exec, ctx, target.target, args.overwrite ?? false);
       validateSheetSpecs(args.sheets);
       exec.signal.throwIfAborted();
@@ -879,7 +890,7 @@ function registerExcelCreate(ctx) {
       });
       const text = buildXlsxText(models);
       exec.signal.throwIfAborted();
-      const sizeBytes = await saveOfficeText(exec, ctx, target.target, text);
+      const sizeBytes = await saveOfficeText(exec, ctx, target.target, text, writePolicy);
       return { path: target.display, sizeBytes, sheets: summaries };
     }
   }));
@@ -1018,7 +1029,8 @@ function registerExcelUpdate(ctx) {
       locations: [{ path: args.path }]
     }),
     async execute(args, exec) {
-      const target = await resolveOfficePath(exec, ctx, args.path, [".xlsx"], true);
+      const writePolicy = await resolveWritePolicy(ctx, exec);
+      const target = await resolveOfficePath(exec, ctx, args.path, [".xlsx"], true, writePolicy);
       if ((args.sheets?.length ?? 0) === 0 && (args.cell_updates?.length ?? 0) === 0) {
         throw new Error("excel_update needs at least one entry in sheets or cell_updates");
       }
@@ -1062,7 +1074,7 @@ function registerExcelUpdate(ctx) {
       exec.signal.throwIfAborted();
       const orderedModels = names.map((name2) => models.get(name2)).filter((model) => model !== void 0).map((model, index) => ({ ...model, part: `worksheets/sheet${index + 1}.xml` }));
       const text = buildXlsxText(orderedModels);
-      const sizeBytes = await saveOfficeText(exec, ctx, target.target, text);
+      const sizeBytes = await saveOfficeText(exec, ctx, target.target, text, writePolicy);
       return {
         path: target.display,
         sizeBytes,
@@ -1743,7 +1755,8 @@ ${sketchSlide(value.slideWidthInches, value.slideHeightInches, slide.elements)}`
       locations: [{ path: args.path }]
     }),
     async execute(args, exec) {
-      const target = await resolveOfficePath(exec, ctx, args.path, [".pptx"], false);
+      const writePolicy = await resolveWritePolicy(ctx, exec);
+      const target = await resolveOfficePath(exec, ctx, args.path, [".pptx"], false, writePolicy);
       await assertMayCreate(exec, ctx, target.target, args.overwrite ?? false);
       if ((args.slides?.length ?? 0) > 0) validateSlideSpecs(args.slides);
       if (args.title === void 0 && (args.slides?.length ?? 0) === 0) {
@@ -1752,7 +1765,7 @@ ${sketchSlide(value.slideWidthInches, value.slideHeightInches, slide.elements)}`
       exec.signal.throwIfAborted();
       const { text, layout } = await buildPptxText(args, exec, ctx, target);
       exec.signal.throwIfAborted();
-      const sizeBytes = await saveOfficeText(exec, ctx, target.target, text);
+      const sizeBytes = await saveOfficeText(exec, ctx, target.target, text, writePolicy);
       const result = {
         path: target.display,
         sizeBytes,
@@ -1937,7 +1950,8 @@ function registerWordUpdate(ctx) {
       locations: [{ path: args.path }]
     }),
     async execute(args, exec) {
-      const target = await resolveOfficePath(exec, ctx, args.path, [".docx"], true);
+      const writePolicy = await resolveWritePolicy(ctx, exec);
+      const target = await resolveOfficePath(exec, ctx, args.path, [".docx"], true, writePolicy);
       const { paragraphs: paragraphCount, cells } = wordCreateCounts(args);
       if ((args.paragraphs?.length ?? 0) === 0 && (args.bullets?.length ?? 0) === 0 && args.table === void 0) {
         throw new Error("word_update needs at least one of paragraphs, bullets, or table");
@@ -1966,7 +1980,7 @@ function registerWordUpdate(ctx) {
       }
       const text = buildAsciiZip(parts);
       exec.signal.throwIfAborted();
-      const sizeBytes = await saveOfficeText(exec, ctx, target.target, text);
+      const sizeBytes = await saveOfficeText(exec, ctx, target.target, text, writePolicy);
       return {
         path: target.display,
         sizeBytes,
@@ -2220,7 +2234,8 @@ function registerWordCreate(ctx) {
       locations: [{ path: args.path }]
     }),
     async execute(args, exec) {
-      const target = await resolveOfficePath(exec, ctx, args.path, [".docx"], false);
+      const writePolicy = await resolveWritePolicy(ctx, exec);
+      const target = await resolveOfficePath(exec, ctx, args.path, [".docx"], false, writePolicy);
       await assertMayCreate(exec, ctx, target.target, args.overwrite ?? false);
       const { paragraphs: paragraphCount, cells } = wordCreateCounts(args);
       if (paragraphCount > 1e4) throw new Error("too many paragraphs/bullets/table rows (maximum 10000)");
@@ -2230,7 +2245,7 @@ function registerWordCreate(ctx) {
       }
       const text = buildDocxText(args);
       exec.signal.throwIfAborted();
-      const sizeBytes = await saveOfficeText(exec, ctx, target.target, text);
+      const sizeBytes = await saveOfficeText(exec, ctx, target.target, text, writePolicy);
       const result = {
         path: target.display,
         sizeBytes,

package/lib/types/fschannel.d.ts

@@ -8,8 +8,12 @@
  * never touches the file system directly: workspace containment, symlink
  * resolution, and atomic publication all belong to the backend, and this
  * module only adds the Office-tool path policy on top (extension allow-lists,
- * size caps, overwrite refusal, display paths).
+ * size caps, overwrite refusal, display paths). Writes carry the per-call
+ * sandbox policy (`ctx.sandboxPolicy.resolve({ session })` when a confining
+ * backend is mounted) so sandboxing backends fence them by the session's
+ * effective policy rather than the deployment default.
  */
+import type { Context } from '@deepseek-ai/cordis';
 import type { FileSystem, FsTarget } from '@deepseek-ai/dsh-fs';
 import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
 /** Cap for text materialized into a single tool result. */
@@ -22,6 +26,22 @@ export declare const MAX_WRITE_CELLS = 200000;
 export interface FsContext {
     fs: FileSystem;
 }
+/**
+ * The per-call sandbox execution policy `ctx.fs.writeText` accepts as its
+ * fifth parameter (`SandboxExecutionPolicy` from `@deepseek-ai/dsh-sandbox`):
+ * a sandboxing backend fences the write by it, the bare backend ignores it,
+ * and omitting it leaves the backend its deployment default — whose writable
+ * roots need not include this session's workspace. Derived from the official
+ * `writeText` signature so the plugin never depends on `@deepseek-ai/dsh-sandbox`
+ * directly.
+ */
+export type OfficeWritePolicy = NonNullable<Parameters<FileSystem['writeText']>[4]>;
+/**
+ * Resolve the per-call write policy the way the official fs tool layer does:
+ * skip when the mounted backend does not confine (`fs.sandboxMode` undefined),
+ * otherwise ask the shared `sandboxPolicy` service for the calling session.
+ */
+export declare function resolveWritePolicy(ctx: Context & FsContext, exec: ToolRunContext): Promise<OfficeWritePolicy | undefined>;
 export interface ResolvedOfficePath {
     /** The path exactly as the model passed it. */
     input: string;
@@ -41,8 +61,12 @@ export interface ResolvedOfficePath {
  * @param rawPath - the model-supplied path string.
  * @param allowedExts - acceptable lowercased extensions WITH dots (e.g. `.docx`).
  * @param mustExist - when true, stat the target and refuse anything but a regular file.
+ * @param writePolicy - the per-call write policy, when a sandbox controller is
+ *   mounted; its `workspaceRoot` is the authoritative workspace the write is
+ *   fenced to, so relative paths resolve against it exactly like the official
+ *   fs tools do. Omitted (reads, bare backends) keeps the session cwd.
  */
-export declare function resolveOfficePath(exec: ToolRunContext, ctx: FsContext, rawPath: string, allowedExts: readonly string[], mustExist: boolean): Promise<ResolvedOfficePath>;
+export declare function resolveOfficePath(exec: ToolRunContext, ctx: FsContext, rawPath: string, allowedExts: readonly string[], mustExist: boolean, writePolicy?: OfficeWritePolicy): Promise<ResolvedOfficePath>;
 /**
  * Read a bounded Office file through the backend, observing tool-call
  * cancellation and refusing files above the hard cap before any transfer.
@@ -54,9 +78,11 @@ export declare function readOfficeBytes(exec: ToolRunContext, ctx: FsContext, ta
 /**
  * Publish one generated package: the text is pure ASCII (asserted by the zip
  * planner), so the backend's atomic UTF-8 write lands it on disk
- * byte-identical. Returns the on-disk size.
+ * byte-identical. The per-call write policy rides along as `writeText`'s
+ * fifth parameter so a sandboxing backend fences the write by the session's
+ * effective policy instead of its deployment default. Returns the on-disk size.
  */
-export declare function saveOfficeText(exec: ToolRunContext, ctx: FsContext, target: FsTarget, text: string): Promise<number>;
+export declare function saveOfficeText(exec: ToolRunContext, ctx: FsContext, target: FsTarget, text: string, writePolicy?: OfficeWritePolicy): Promise<number>;
 /**
  * Reject an overwrite when `overwrite` is false and the target already
  * exists. Callers use this BEFORE doing expensive generation so the model

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-office-tools",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "DSH model-facing Office tools: create, read, and update Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) files inside the session workspace, entirely through the official DSH filesystem service.",
   "license": "MIT",
   "type": "module",
@@ -114,5 +114,47 @@
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "pnpm@11.7.0"
+  "packageManager": "pnpm@10.34.5",
+  "dshWorkshop": {
+    "schema": "omdsh-workshop-package/v1",
+    "type": "plugin",
+    "integration": {
+      "protocol": "harness-profile",
+      "artifact": "cordis.patch.yml"
+    },
+    "install": {
+      "mode": "transactional",
+      "adapter": "profile-bundle",
+      "failurePolicy": "generation-rollback",
+      "touchesCurrentBeforeActivation": false
+    },
+    "lifecycle": {
+      "activation": "restart-profile",
+      "dispose": "supported"
+    },
+    "permissions": [
+      "files:workspace-read",
+      "files:workspace-write"
+    ],
+    "compatibility": {
+      "dshVersions": [
+        "0.1.1-rc.2",
+        "0.1.2-alpha.4",
+        "0.1.2-alpha.5",
+        "0.1.2-rc.1"
+      ]
+    },
+    "capability": {
+      "id": "word_create",
+      "kind": "tool",
+      "invocation": "word_create({\"path\": \"hub-check.docx\", \"paragraphs\": [\"dsh-hub intake check\"]}) in a session with workspace cwd",
+      "expected": "a real .docx (first two bytes PK) exists at the workspace path; the result reports sizeBytes > 0; word_read returns 'dsh-hub intake check'"
+    },
+    "evidence": {
+      "install": null,
+      "failureIsolation": null,
+      "hotReload": null,
+      "remove": null
+    }
+  }
 }