@qlzt/dsh-tool-fs 0.2.1-alpha.2 → 0.2.1-rc.2

package/README.i18n.yaml

@@ -24,8 +24,8 @@
   en: 29a1d47e9677f2a3
   zh: 0ae3c794cc7c54db
 /deepseek-ai-dsh-tool-fs/use-this-package/configuration:
-  en: 7eb705e3b132fcba
-  zh: 883207b13d381f9e
+  en: 6903a9ca39cb9a71
+  zh: a078377d02c3ab6f
 /deepseek-ai-dsh-tool-fs/use-this-package/policy-and-sandbox-behavior:
   en: 53d4ac2db089ef39
   zh: 214ea051ed56f500
@@ -57,8 +57,8 @@
   en: cf78b9dd5596495f
   zh: bd44560f8c2435e8
 /deepseek-ai-dsh-tool-fs/model-experience/system-prompt/what-the-model-sees:
-  en: b09ee4be5e522c29
-  zh: ffd30b57d7fc96e8
+  en: f715f25f411d50f5
+  zh: 4063a0499dc47466
 /deepseek-ai-dsh-tool-fs/model-experience/system-prompt/what-the-model-sees/read-guidance:
   en: f8961df3f3a6a671
   zh: 85c7bd418b40b089

package/README.md

@@ -54,10 +54,14 @@ Field names are snake_case to match Claude Code and existing harness tool schema
 
 ### Configuration
 
-All keys are optional; the defaults are the shipped read caps.
+All keys are optional. The `read`, `readImage`, `write`, and `edit` switches default to `true`; set a switch to `false` to omit that tool and its guidance. All four may be disabled. Enabling `readImage` still requires an attachment store and an image-capable model. Read caps remain validated when `read` is disabled.
 
 | Key | Default | Meaning |
 |---|---|---|
+| `read` | `true` | Register `read` and its guidance |
+| `readImage` | `true` | Register `read_image` while an attachment store is mounted |
+| `write` | `true` | Register `write` and its guidance |
+| `edit` | `true` | Register `edit` and its guidance |
 | `readLimit` | `2000` | Default and maximum lines returned by one `read` call |
 | `readMaxLineLength` | `2000` | Characters kept per line before truncation |
 | `readMaxBytes` | `51200` | Byte cap on one `read` call's selected lines; overflow ends the window with a capped footer |
@@ -65,6 +69,8 @@ All keys are optional; the defaults are the shipped read caps.
 
 The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tool-fs) is the exhaustive source for every accepted field and its JSDoc.
 
+With `fs-observation-policy` mounted and `read` disabled, `write` can still create files, and successful writes or edits record the versions needed for later mutations in that session. Existing unobserved files remain protected; disabling `read` does not relax the policy. Another filesystem reader must emit `fs/observed` for an existing file to become observed.
+
 ### Policy and sandbox behavior
 
 Path authorization for `read` and `read_image` belongs entirely to `ctx.fs`; media-type declarations and file signatures only decide whether `read_image` accepts the bytes returned by that backend.
@@ -136,7 +142,7 @@ Read these pages when the package-level contract is not enough. They move from t
 
 #### What the model sees
 
-At assembly time, each guidance section checks `ctx.tools.get(name, scope)` and renders only while its tool is visible to that agent. The write paragraph recommends edit only while edit is visible. The text below is unchanged when all three tools are available; restrictions, their removal, and tool registration changes take effect on the next assembly. The same check works for direct agent restrictions and subagent `toolFilter`, including PTC capabilities behind `run_code`. The read-before-mutation sentences in write/edit describe the observation policy, not a requirement to invoke the tool named `read`. They remain when `read` is hidden: the policy still guards mutations, and another observing operation, such as `str_replace_editor` with `command: view`, can establish the same file observation. Tool visibility does not disable that precondition.
+At assembly time, each guidance section checks `ctx.tools.get(name, scope)` and renders only while its tool is visible to that agent. The write paragraph recommends edit only while edit is visible. The text below is unchanged when all three tools are available; restrictions, their removal, and tool registration changes take effect on the next assembly. The same check works for direct agent restrictions and historical subagent filters restored from descriptors, including PTC capabilities behind `run_code`. The read-before-mutation sentences in write/edit describe the observation policy, not a requirement to invoke the tool named `read`. They remain when `read` is hidden: the policy still guards mutations, and another observing operation, such as `str_replace_editor` with `command: view`, can establish the same file observation. Tool visibility does not disable that precondition.
 
 ##### Read guidance
 

package/README.zh.md

@@ -54,10 +54,14 @@ kind: "package-reference"
 
 ### 配置
 
-所有键均为可选；默认值是随产品交付的读取上限。
+所有键均为可选。`read`、`readImage`、`write` 和 `edit` 开关默认为 `true`；将开关设为 `false` 可省略对应工具及其指导文本。允许关闭全部四个工具。启用 `readImage` 仍需要附件存储和支持图片输入的模型。关闭 `read` 时仍会校验读取上限。
 
 | 键 | 默认值 | 含义 |
 |---|---|---|
+| `read` | `true` | 注册 `read` 及其指导文本 |
+| `readImage` | `true` | 附件存储挂载时注册 `read_image` |
+| `write` | `true` | 注册 `write` 及其指导文本 |
+| `edit` | `true` | 注册 `edit` 及其指导文本 |
 | `readLimit` | `2000` | 一次 `read` 调用返回的默认和最大行数 |
 | `readMaxLineLength` | `2000` | 每行截断前保留的字符数 |
 | `readMaxBytes` | `51200` | 一次 `read` 调用所选行的字节上限；溢出时以「已达上限」footer 结束窗口 |
@@ -65,6 +69,8 @@ kind: "package-reference"
 
 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-tool-fs)是每个受支持字段及其 JSDoc 的穷尽式真源。
 
+挂载 `fs-observation-policy` 且关闭 `read` 时，`write` 仍可创建文件，成功写入或编辑会记录本会话后续修改所需的版本。未观察过的已有文件仍受保护；关闭 `read` 不会放宽策略。其他文件系统读取方必须发出 `fs/observed`，已有文件才会成为已观察状态。
+
 ### 策略与沙箱行为
 
 `read` 与 `read_image` 的路径授权完全由 `ctx.fs` 负责；媒体类型声明和文件签名只决定 `read_image` 是否接受该后端返回的字节。
@@ -136,7 +142,7 @@ kind: "package-reference"
 
 #### 模型看到的内容
 
-组装时，每个指导段落通过 `ctx.tools.get(name, scope)` 检查对应工具，仅在该 agent 可见时输出。write 段落仅在 edit 可见时推荐 edit。三个工具都可用时，下方原文保持不变；限制的施加、解除和工具注册变化在下次组装时生效。同一检查适用于直接限制 agent 和 subagent 的 `toolFilter`，也适用于通过 `run_code` 暴露的 PTC 能力。 write/edit 中的先读后改句子描述观察策略，并非要求调用名为 `read` 的工具。隐藏 `read` 时仍保留这些句子：策略继续保护修改操作，其他产生观察记录的操作（例如 `str_replace_editor` 的 `command: view`）也能建立同一文件观察记录。工具可见性不会禁用该前置条件。
+组装时，每个指导段落通过 `ctx.tools.get(name, scope)` 检查对应工具，仅在该 agent 可见时输出。write 段落仅在 edit 可见时推荐 edit。三个工具都可用时，下方原文保持不变；限制的施加、解除和工具注册变化在下次组装时生效。同一检查适用于直接限制 agent 和从历史 descriptor 恢复的 subagent 过滤器，也适用于通过 `run_code` 暴露的 PTC 能力。 write/edit 中的先读后改句子描述观察策略，并非要求调用名为 `read` 的工具。隐藏 `read` 时仍保留这些句子：策略继续保护修改操作，其他产生观察记录的操作（例如 `str_replace_editor` 的 `command: view`）也能建立同一文件观察记录。工具可见性不会禁用该前置条件。
 
 ##### Read 指导
 

package/lib/index.js

@@ -1192,6 +1192,10 @@ const inject = [
 	"workingDirectory"
 ];
 const Config = z.object({
+	read: z.boolean().default(true),
+	readImage: z.boolean().default(true),
+	write: z.boolean().default(true),
+	edit: z.boolean().default(true),
 	readLimit: z.number().default(READ_LIMIT),
 	readMaxLineLength: z.number().default(READ_MAX_LINE_LENGTH),
 	readMaxBytes: z.number().default(READ_MAX_BYTES),
@@ -1201,25 +1205,27 @@ const Config = z.object({
 function assertPositiveInteger(name, value) {
 	if (!Number.isInteger(value) || value < 1) throw new Error(`tool-fs: ${name} must be a positive integer`);
 }
-/** Register the full `read`/`write`/`edit` filesystem tool suite, plus `read_image` while `attachments` is mounted. */
+/** Register the selected filesystem tools; `read_image` additionally requires a mounted attachment store. */
 function apply(ctx, config) {
 	const resolved = config;
 	assertPositiveInteger("readLimit", resolved.readLimit);
 	assertPositiveInteger("readMaxLineLength", resolved.readMaxLineLength);
 	assertPositiveInteger("readMaxBytes", resolved.readMaxBytes);
 	assertPositiveInteger("readStreamMinSize", resolved.readStreamMinSize);
-	applyReadTool(ctx, {
+	if (resolved.read) applyReadTool(ctx, {
 		limit: resolved.readLimit,
 		maxLineLength: resolved.readMaxLineLength,
 		maxBytes: resolved.readMaxBytes,
 		streamMinSize: resolved.readStreamMinSize
 	});
-	ctx.inject(["attachments"], (imageCtx) => {
+	if (resolved.readImage) ctx.inject(["attachments"], (imageCtx) => {
 		applyReadImageTool(imageCtx);
 	});
-	const sandbox = new FsSandboxController(ctx);
-	applyWriteTool(ctx, sandbox);
-	applyEditTool(ctx, sandbox);
+	if (resolved.write || resolved.edit) {
+		const sandbox = new FsSandboxController(ctx);
+		if (resolved.write) applyWriteTool(ctx, sandbox);
+		if (resolved.edit) applyEditTool(ctx, sandbox);
+	}
 }
 //#endregion
 export { Config, apply, inject, name };

package/lib/types/index.d.ts

@@ -12,6 +12,14 @@ export declare const name = "tool-fs";
 export declare const inject: string[];
 /** Plugin config (all optional — `Config` supplies the defaults). */
 export interface Config {
+    /** Register `read` and its guidance. Defaults to true. */
+    read?: boolean;
+    /** Register `read_image` while an attachment store is mounted. Defaults to true. */
+    readImage?: boolean;
+    /** Register `write` and its guidance. Defaults to true. */
+    write?: boolean;
+    /** Register `edit` and its guidance. Defaults to true. */
+    edit?: boolean;
     /** Default and maximum number of lines returned by one `read` call. */
     readLimit?: number;
     /** Maximum characters returned for a single line before truncation. */
@@ -22,6 +30,6 @@ export interface Config {
     readStreamMinSize?: number;
 }
 export declare const Config: z<Config>;
-/** Register the full `read`/`write`/`edit` filesystem tool suite, plus `read_image` while `attachments` is mounted. */
+/** Register the selected filesystem tools; `read_image` additionally requires a mounted attachment store. */
 export declare function apply(ctx: Context, config: Config): void;
 //# sourceMappingURL=index.d.ts.map

package/locale/en.json

@@ -0,0 +1,5 @@
+{
+  "meta": {
+    "title": "tool-fs"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "文件读写工具",
+    "description": "让 AI 读取、创建和编辑工作文件。"
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qlzt/dsh-tool-fs",
   "description": "Model-facing filesystem tools (read, write, edit) over the DeepSeek Harness filesystem seam (ctx.fs)",
-  "version": "0.2.1-alpha.2",
+  "version": "0.2.1-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -19,53 +19,55 @@
       "default": "./lib/index.js"
     },
     "./src/*": "./src/*",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
   },
   "files": [
+    "locale/*.json",
     "lib/index.js",
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
   "dependencies": {
     "diff": "^9.0.0",
-    "@deepseek-ai/schemastery": "~3.18.5-alpha.1",
-    "@qlzt/dsh-util-code-language": "0.2.1-alpha.2"
+    "@deepseek-ai/schemastery": "~3.18.5",
+    "@qlzt/dsh-util-code-language": "0.2.1-rc.2"
   },
   "peerDependencies": {
-    "@qlzt/dsh-attachment": "0.2.1-alpha.2",
-    "@qlzt/dsh-fs": "0.2.1-alpha.2",
-    "@qlzt/dsh-llm": "0.2.1-alpha.2",
-    "@qlzt/dsh-sandbox": "0.2.1-alpha.2",
-    "@qlzt/dsh-sandbox-policy": "0.2.1-alpha.2",
-    "@qlzt/dsh-session": "0.2.1-alpha.2",
-    "@qlzt/dsh-system-prompt": "0.2.1-alpha.2",
-    "@qlzt/dsh-tools": "0.2.1-alpha.2",
-    "@qlzt/dsh-user-approval": "0.2.1-alpha.2",
-    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
-    "@qlzt/dsh-working-directory": "0.2.1-alpha.2"
+    "@qlzt/dsh-attachment": "0.2.1-rc.2",
+    "@qlzt/dsh-fs": "0.2.1-rc.2",
+    "@qlzt/dsh-llm": "0.2.1-rc.2",
+    "@qlzt/dsh-sandbox": "0.2.1-rc.2",
+    "@qlzt/dsh-sandbox-policy": "0.2.1-rc.2",
+    "@qlzt/dsh-session": "0.2.1-rc.2",
+    "@qlzt/dsh-system-prompt": "0.2.1-rc.2",
+    "@qlzt/dsh-tools": "0.2.1-rc.2",
+    "@qlzt/dsh-user-approval": "0.2.1-rc.2",
+    "@deepseek-ai/cordis": "~4.0.5",
+    "@qlzt/dsh-working-directory": "0.2.1-rc.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-agent-loop": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-agent-loop-testkit": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-attachment": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-fs": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-fs-local": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-fs-observation-policy": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-llm": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-llm-deepseek": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-llm-deepseek-api-key": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-sandbox": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-sandbox-policy": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-session": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-tools": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-user-approval": "0.2.1-alpha.2",
-    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
-    "@deepseek-ai/dsh-session-projection": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-scope": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-ptc-runtime": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-working-directory": "0.2.1-alpha.2"
+    "@deepseek-ai/dsh-agent": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-agent-loop": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-agent-loop-testkit": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-attachment": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-fs": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-fs-local": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-fs-observation-policy": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm-deepseek": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm-deepseek-api-key": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-sandbox": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-user-approval": "0.2.1-rc.2",
+    "@deepseek-ai/cordis": "~4.0.5",
+    "@deepseek-ai/dsh-session-projection": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-scope": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-ptc-runtime": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-working-directory": "0.2.1-rc.2"
   },
   "dsh": {}
 }