Add filesystem capability seam and tools

2026-06-22 10:48:41 +08:00
parent 6b4dc48fbd
commit 5e01564afb
36 changed files with 3515 additions and 1 deletions
@@ -0,0 +1,82 @@
+/**
+ * The model-facing `edit` tool: update an existing UTF-8 text file by replacing
+ * literal text, requiring a unique match by default. Execution goes through
+ * `ctx.fs`, which enforces prior observation and the stale-version guard and
+ * owns the literal-match semantics.
+ *
+ * @module @deepseek-ai/dsh-tool-fs/edit
+ */
+
+import type { Context } from 'cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { FsEditOutcome } from '@deepseek-ai/dsh-fs'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+
+/** Validated `edit` arguments after defaulting. */
+interface EditInput {
+  filePath: string
+  oldString: string
+  newString: string
+  replaceAll: boolean
+}
+
+/** Validate value constraints the schema DSL can't express. */
+export function parseEditArgs(args: { file_path: string; old_string: string; new_string: string; replace_all?: boolean }): EditInput {
+  if (args.file_path.trim().length === 0) throw new Error('file_path must be a non-empty string')
+  if (args.old_string.length === 0) throw new Error('old_string must be a non-empty string')
+  if (args.old_string === args.new_string) throw new Error('old_string and new_string must differ')
+  return {
+    filePath: args.file_path,
+    oldString: args.old_string,
+    newString: args.new_string,
+    replaceAll: args.replace_all ?? false,
+  }
+}
+
+/** Format an edit outcome as a Claude-style model-facing success message. */
+export function formatEditOutput(displayPath: string, outcome: FsEditOutcome): string {
+  return outcome.replaceAll
+    ? `The file ${displayPath} has been updated. All occurrences were successfully replaced.`
+    : `The file ${displayPath} has been updated successfully.`
+}
+
+/** Register the `edit` tool and its system-prompt guidance. */
+export function apply(ctx: Context): void {
+  ctx.systemPrompt.section({
+    name: 'tool:edit',
+    order: 102,
+    text: 'Use the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true.',
+  })
+
+  ctx.tools.register(defineTool({
+    name: 'edit',
+    description: 'Edit an existing UTF-8 text file by replacing literal text.',
+    parameters: {
+      file_path: { type: 'string', required: true, description: 'Path to edit, resolved by the filesystem backend.' },
+      old_string: { type: 'string', required: true, description: 'Literal text to replace. Must match exactly.' },
+      new_string: { type: 'string', required: true, description: 'Literal replacement text. Use an empty string to delete the match.' },
+      replace_all: { type: 'boolean', description: 'Replace all matches. Defaults to false; when false, old_string must appear exactly once.' },
+    },
+    async execute(args, exec): Promise<ContentBlock[]> {
+      const input = parseEditArgs(args)
+      const target = await ctx.fs.resolve(input.filePath)
+      const outcome = await ctx.fs.edit(
+        target,
+        { oldString: input.oldString, newString: input.newString, replaceAll: input.replaceAll },
+        exec,
+        exec.signal,
+      )
+      return [{ type: 'text', text: formatEditOutput(target.displayPath, outcome) }]
+    },
+  }))
+}
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'fs-edit'
+
+/** Services required by the `edit` tool plugin. */
+export const inject = ['tools', 'fs', 'systemPrompt']
+
+/** Named helper for direct registration in the root plugin and tests. */
+export const applyEditTool = apply
@@ -0,0 +1,35 @@
+/**
+ * The model-facing filesystem tool suite (`read`, `write`, `edit`) over the
+ * `ctx.fs` seam. This root plugin registers all three tools by composing the
+ * per-tool registration helpers; each tool is also exposed as a subpath plugin
+ * (`@deepseek-ai/dsh-tool-fs/read`, `/write`, `/edit`) for focused deployments.
+ *
+ * The package owns model-facing concerns only — tool names, JSON schemas,
+ * argument validation, prompt sections, result formatting. All filesystem
+ * execution goes through `ctx.fs`; this package never imports `node:fs`,
+ * `node:path`, or an `@deepseek-ai/dsh-fs-local` implementation.
+ *
+ * @module @deepseek-ai/dsh-tool-fs
+ */
+
+import type { Context } from 'cordis'
+import { applyReadTool } from './read.ts'
+import { applyWriteTool } from './write.ts'
+import { applyEditTool } from './edit.ts'
+
+export { READ_LIMIT, applyReadTool, formatReadOutput, parseReadArgs } from './read.ts'
+export { applyWriteTool, formatWriteOutput, parseWriteArgs } from './write.ts'
+export { applyEditTool, formatEditOutput, parseEditArgs } from './edit.ts'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'tool-fs'
+
+/** Services required by the filesystem tool suite. */
+export const inject = ['tools', 'fs', 'systemPrompt']
+
+/** Register the full `read`/`write`/`edit` filesystem tool suite. */
+export function apply(ctx: Context): void {
+  applyReadTool(ctx)
+  applyWriteTool(ctx)
+  applyEditTool(ctx)
+}
@@ -0,0 +1,95 @@
+/**
+ * The model-facing `read` tool: inspect a UTF-8 text file and return
+ * line-numbered content with pagination guidance. Execution goes through
+ * `ctx.fs` — this module owns only the model-facing schema, argument
+ * validation, and result formatting, never filesystem I/O.
+ *
+ * @module @deepseek-ai/dsh-tool-fs/read
+ */
+
+import type { Context } from 'cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { FsReadOutcome } from '@deepseek-ai/dsh-fs'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+
+/** Default and maximum number of lines returned by one `read` call. */
+export const READ_LIMIT = 2000
+
+/** Validated `read` arguments after defaulting. */
+interface ReadInput {
+  filePath: string
+  offset: number
+  limit: number
+}
+
+function parsePositiveInteger(value: number, name: string): number {
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1) {
+    throw new Error(`${name} must be a positive integer`)
+  }
+  return value
+}
+
+/** Validate value constraints the schema DSL can't express. */
+export function parseReadArgs(args: { file_path: string; offset?: number; limit?: number }): ReadInput {
+  if (args.file_path.trim().length === 0) throw new Error('file_path must be a non-empty string')
+  const offset = args.offset === undefined ? 1 : parsePositiveInteger(args.offset, 'offset')
+  const limit = args.limit === undefined ? READ_LIMIT : parsePositiveInteger(args.limit, 'limit')
+  if (limit > READ_LIMIT) throw new Error(`limit must be less than or equal to ${READ_LIMIT}`)
+  return { filePath: args.file_path, offset, limit }
+}
+
+/** Format a read outcome as one OpenCode-style line-numbered text block body. */
+export function formatReadOutput(displayPath: string, outcome: FsReadOutcome): string {
+  const endLine = outcome.lines.at(-1)?.number ?? Math.max(0, outcome.offset - 1)
+  let footer: string
+  if (outcome.truncatedByBytes) {
+    footer = `(Output capped. Showing lines ${outcome.offset}-${endLine}. Use offset=${endLine + 1} to continue.)`
+  } else if (endLine < outcome.totalLines) {
+    footer = `(Showing lines ${outcome.offset}-${endLine} of ${outcome.totalLines}. Use offset=${endLine + 1} to continue.)`
+  } else {
+    footer = `(End of file - total ${outcome.totalLines} lines)`
+  }
+  const body = outcome.lines.length > 0
+    ? `${outcome.lines.map(line => `${line.number}: ${line.text}`).join('\n')}\n\n${footer}`
+    : footer
+  return `<path>${displayPath}</path>
+<type>file</type>
+<content>
+${body}
+</content>`
+}
+
+/** Register the `read` tool and its system-prompt guidance. */
+export function apply(ctx: Context): void {
+  ctx.systemPrompt.section({
+    name: 'tool:read',
+    order: 100,
+    text: 'Use the read tool to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.',
+  })
+
+  ctx.tools.register(defineTool({
+    name: 'read',
+    description: 'Read a UTF-8 text file and return line-numbered content.',
+    parameters: {
+      file_path: { type: 'string', required: true, description: 'Path to read, resolved by the filesystem backend.' },
+      offset: { type: 'number', description: '1-based first line to return. Defaults to 1.' },
+      limit: { type: 'number', description: `Maximum number of lines to return. Defaults to ${READ_LIMIT}.` },
+    },
+    async execute(args, exec): Promise<ContentBlock[]> {
+      const input = parseReadArgs(args)
+      const target = await ctx.fs.resolve(input.filePath)
+      const outcome = await ctx.fs.read(target, { offset: input.offset, limit: input.limit }, exec, exec.signal)
+      return [{ type: 'text', text: formatReadOutput(target.displayPath, outcome) }]
+    },
+  }))
+}
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'fs-read'
+
+/** Services required by the `read` tool plugin. */
+export const inject = ['tools', 'fs', 'systemPrompt']
+
+/** Named helper for direct registration in the root plugin and tests. */
+export const applyReadTool = apply
@@ -0,0 +1,63 @@
+/**
+ * The model-facing `write` tool: create or fully replace a UTF-8 text file.
+ * Execution goes through `ctx.fs`, which enforces the read-before-overwrite
+ * policy (updating an existing file requires a prior read in the same
+ * execution context; creating a new file does not).
+ *
+ * @module @deepseek-ai/dsh-tool-fs/write
+ */
+
+import type { Context } from 'cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { FsWriteOutcome } from '@deepseek-ai/dsh-fs'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+
+/** Validate value constraints the schema DSL can't express. */
+export function parseWriteArgs(args: { file_path: string; content: string }): { filePath: string; content: string } {
+  if (args.file_path.trim().length === 0) throw new Error('file_path must be a non-empty string')
+  return { filePath: args.file_path, content: args.content }
+}
+
+/** Format a write outcome as one model-facing text block body. */
+export function formatWriteOutput(displayPath: string, outcome: FsWriteOutcome): string {
+  const verb = outcome.operation === 'create' ? 'Created' : 'Updated'
+  return `<path>${displayPath}</path>
+<type>file</type>
+<content>
+${verb} file
+</content>`
+}
+
+/** Register the `write` tool and its system-prompt guidance. */
+export function apply(ctx: Context): void {
+  ctx.systemPrompt.section({
+    name: 'tool:write',
+    order: 101,
+    text: 'Use the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the backend requires it) and prefer edit for targeted changes.',
+  })
+
+  ctx.tools.register(defineTool({
+    name: 'write',
+    description: 'Create or fully replace a UTF-8 text file.',
+    parameters: {
+      file_path: { type: 'string', required: true, description: 'Path to write, resolved by the filesystem backend.' },
+      content: { type: 'string', required: true, description: 'Full UTF-8 text content to write.' },
+    },
+    async execute(args, exec): Promise<ContentBlock[]> {
+      const input = parseWriteArgs(args)
+      const target = await ctx.fs.resolve(input.filePath)
+      const outcome = await ctx.fs.write(target, input.content, exec, exec.signal)
+      return [{ type: 'text', text: formatWriteOutput(target.displayPath, outcome) }]
+    },
+  }))
+}
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'fs-write'
+
+/** Services required by the `write` tool plugin. */
+export const inject = ['tools', 'fs', 'systemPrompt']
+
+/** Named helper for direct registration in the root plugin and tests. */
+export const applyWriteTool = apply