dsh-workbuddy-files 0.1.0

package/src/client/lib/transfer.ts

@@ -0,0 +1,113 @@
+import type { DropsItem, DropsStat, TreeFile, UploadJob } from '../types'
+
+/** 引用文本格式：无空格直接 @path；含空格/引号用 @"path"；目录保留尾斜杠 */
+export function mentionFor(path: string, isDir: boolean): string {
+  let p = String(path)
+  if (isDir) p = p.replace(/[\\/]+$/, '') + '/'
+  if (/\s|"/.test(p)) return '@"' + p + '"'
+  return '@' + p
+}
+
+/** 从用户消息文本中提取 @ 文件引用（消息发送后的序列化形式） */
+export function extractRefs(content: ReadonlyArray<{ type: string; text?: string }>): string[] {
+  const out: string[] = []
+  for (const b of content) {
+    if (b !== null && b !== undefined && b.type === 'text' && typeof b.text === 'string') {
+      const re = /@"([^"]+)"|@([^\s"@]+)/g
+      let m: RegExpExecArray | null
+      while ((m = re.exec(b.text)) !== null) {
+        const p = (m[1] !== undefined ? m[1] : m[2]).trim()
+        if (p !== '' && !out.includes(p)) out.push(p)
+      }
+    }
+  }
+  return out.slice(0, 40)
+}
+
+/**
+ * 后台上传任务队列：逐个落盘（目录任务先遍历），不阻塞输入。
+ * 交付物版本走 webServer 二进制路由（/workbuddy-drops），无 base64、无 JSON 体积上限。
+ * @returns 成功数量与失败清单（文件名 + 原因）
+ */
+export async function runUploadJobs(jobs: UploadJob[], batch: string, maxFileBytes = 256 * 1048576): Promise<{ ok: number; failed: string[] }> {
+  let ok = 0
+  const failed: string[] = []
+  for (const j of jobs) {
+    const files: TreeFile[] = j.kind === 'dir' ? await walkEntry(j.entry, '') : [{ rel: j.rel, name: j.name, size: j.file.size, file: j.file }]
+    for (const f of files) {
+      if (f.file.size > maxFileBytes) { failed.push(f.name + '（超过大小上限）'); continue }
+      const url = '/workbuddy-drops/save?batch=' + encodeURIComponent(batch) + '&rel=' + encodeURIComponent(f.rel)
+      const res = await fetch(url, { method: 'POST', body: f.file })
+      if (res.ok) {
+        const body = await res.json() as { ok?: boolean; error?: string }
+        if (body.ok === true) { ok += 1; continue }
+        failed.push(f.name + '（' + (body.error ?? '写入失败') + '）')
+      } else {
+        failed.push(f.name + '（HTTP ' + res.status + '）')
+      }
+    }
+  }
+  return { ok, failed }
+}
+
+/** 缓存根目录（~/.dsh-drops） */
+export async function dropsHome(): Promise<string | null> {
+  try {
+    const res = await fetch('/workbuddy-drops/home')
+    const body = await res.json() as { ok?: boolean; root?: string }
+    if (body.ok === true && typeof body.root === 'string') return body.root
+    return null
+  } catch {
+    return null
+  }
+}
+
+export function walkEntry(entry: FileSystemEntry, rel: string): Promise<TreeFile[]> {
+  return new Promise((resolve2) => {
+    if (entry.isFile) {
+      const fe = entry as FileSystemFileEntry
+      fe.file(
+        (f) => resolve2([{ rel: rel === '' ? entry.name : rel + '/' + entry.name, name: entry.name, size: f.size, file: f }]),
+        () => resolve2([]),
+      )
+      return
+    }
+    if (entry.isDirectory) {
+      const de = entry as FileSystemDirectoryEntry
+      const reader = de.createReader()
+      const found: FileSystemEntry[] = []
+      const readBatch = () => reader.readEntries((ents) => {
+        if (ents.length === 0) {
+          Promise.all(found.map((e) => walkEntry(e, rel === '' ? entry.name : rel + '/' + entry.name)))
+            .then((rs) => resolve2(rs.flat()))
+            .catch(() => resolve2([]))
+          return
+        }
+        found.push(...ents)
+        readBatch()
+      }, () => resolve2([]))
+      readBatch()
+      return
+    }
+    resolve2([])
+  })
+}
+
+export async function dropsList(query: string): Promise<DropsItem[]> {
+  try {
+    const res = await fetch('/workbuddy-drops/list?query=' + encodeURIComponent(query))
+    const body = await res.json() as { items?: DropsItem[] }
+    return body.items ?? []
+  } catch {
+    return []
+  }
+}
+
+export async function dropsStat(path: string): Promise<DropsStat> {
+  try {
+    const res = await fetch('/workbuddy-drops/stat?path=' + encodeURIComponent(path))
+    return await res.json() as DropsStat
+  } catch {
+    return { ok: false, path }
+  }
+}

package/src/client/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Client 半侧共享类型。
+ * 线上运行期这些类型来自宿主提供的 peer 依赖包；此处仅声明插件内部使用的形状。
+ */
+
+/** 一次拖拽/粘贴/选择后待插入输入框的引用项 */
+export interface InsertItem {
+  label: string
+  reference: {
+    source: 'workbuddy'
+    ref: string
+    label: string
+    appearance: 'file' | 'folder'
+    clipboardText: string
+  }
+}
+
+/** 目录树遍历得到的文件条目 */
+export interface TreeFile {
+  /** 相对路径（'/' 分隔，含顶层目录名；松散文件时就是文件名） */
+  rel: string
+  name: string
+  size: number
+  file: File
+}
+
+/** 后台上传任务：松散文件，或待遍历的目录 entry */
+export type UploadJob = {
+  kind: 'file'
+  file: File
+  rel: string
+  name: string
+} | {
+  kind: 'dir'
+  entry: FileSystemEntry
+}
+
+/** drops.stat / drops.list 等 RPC 的返回形状 */
+export interface DropsStat {
+  ok: boolean
+  exists?: boolean
+  path: string
+  type?: string
+  size?: number | null
+  error?: string
+}
+
+export interface DropsItem {
+  name: string
+  path: string
+  type: string
+  size: number | null
+}
+
+/** 拖拽/粘贴总线状态 */
+export interface BusState {
+  active: boolean
+  count: number
+  toast: { text: string; level: 'info' | 'error' } | null
+}

package/src/host/index.ts

@@ -0,0 +1,253 @@
+/**
+ * dsh-workbuddy-files · Host 半侧
+ *
+ * 职责：
+ *  1. 文件落地缓存 `~/.dsh-drops/`（保留拖入目录树结构），通过 webServer 路由
+ *     `/workbuddy-drops` 接收浏览器 fetch 的二进制 POST（无需 base64，支持大文件）；
+ *  2. 注册 `read_document` 模型工具：解析 `@"path"` / `@path` 引用并返回内容。
+ *
+ * 真实插件包的 Host 半侧运行在 DSH 的 Node 进程里（非沙箱），可以直接使用
+ * node:fs —— 这也是 dsh-pet 等第三方插件的标准写法（参考其 src/host/index.ts）。
+ */
+import { homedir } from 'node:os'
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises'
+import { dirname, join, normalize, resolve, sep } from 'node:path'
+import { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+/** 插件行 id（与 cordis.patch.yml 的 id 一致） */
+export const name = 'workbuddy-files'
+/** 硬依赖：Web 服务器路由注册表 */
+export const inject = ['webServer']
+
+export interface WorkbuddyConfig {
+  /** 拖拽/粘贴文件的落地目录（默认 '~/.dsh-drops'，支持 '~' 前缀） */
+  dropsDir?: string
+  /** 单文件大小上限（字节，默认 256MB；0 = 不限） */
+  maxFileBytes?: number
+}
+
+interface ResolvedConfig {
+  dropsDir: string
+  maxFileBytes: number
+}
+
+function resolveConfig(config: WorkbuddyConfig = {}): ResolvedConfig {
+  return {
+    dropsDir: config.dropsDir ?? '~/.dsh-drops',
+    maxFileBytes: config.maxFileBytes ?? 256 * 1048576,
+  }
+}
+
+function expandHome(dir: string): string {
+  if (dir === '~' || dir.startsWith('~/')) return join(homedir(), dir.slice(1))
+  return dir
+}
+
+/** 规范化相对路径：拒绝 `..`、绝对路径与控制字符（防目录穿越） */
+function normRel(rel: string): string | null {
+  const parts = String(rel).replace(/\\/g, '/').split('/')
+  const out: string[] = []
+  for (const p of parts) {
+    if (p === '' || p === '.') continue
+    if (p === '..') return null
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u001f"\r\n]/.test(p)) return null
+    out.push(p)
+  }
+  return out.join('/')
+}
+
+/** 校验最终路径仍位于 drops 根目录内（第二道防线） */
+function resolveDrops(root: string, rel: string): string | undefined {
+  const candidate = normalize(join(root, rel))
+  const rootWithSep = root.endsWith(sep) ? root : root + sep
+  if (candidate !== root && !candidate.startsWith(rootWithSep)) return undefined
+  return candidate
+}
+
+function sendJson(res: any, status: number, obj: unknown): void {
+  const body = JSON.stringify(obj)
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'content-length': Buffer.byteLength(body) })
+  res.end(body)
+}
+
+/** 收集请求体原始字节（流式，不设上限；上限检查在写盘前按 maxFileBytes 执行） */
+function readBody(req: any): Promise<Buffer> {
+  return new Promise((resolve2, reject) => {
+    const chunks: Buffer[] = []
+    let total = 0
+    req.on('data', (c: Buffer) => { chunks.push(c); total += c.length })
+    req.on('end', () => resolve2(Buffer.concat(chunks, total)))
+    req.on('error', reject)
+  })
+}
+
+/** UTF-8 可解码性 / 二进制探测（NUL 字节即二进制） */
+function looksBinary(buf: Buffer): boolean {
+  if (buf.includes(0)) return true
+  try {
+    new TextDecoder('utf-8', { fatal: true }).decode(buf)
+    return false
+  } catch {
+    return true
+  }
+}
+
+export function apply(ctx: Context, config: WorkbuddyConfig = {}) {
+  const resolved = resolveConfig(config)
+  const dropsDir = resolve(expandHome(resolved.dropsDir))
+  const webServer = (ctx as unknown as {
+    webServer: {
+      register(route: { kind: 'prefix'; path: string; handler: (req: any, res: any) => void | Promise<void> }): () => void
+    }
+  }).webServer
+
+  // ---------------- /workbuddy-drops 路由 ----------------
+  ctx.effect(() => webServer.register({
+    kind: 'prefix',
+    path: '/workbuddy-drops',
+    handler: async (req: any, res: any) => {
+      const url = new URL(req.url ?? '/', 'http://localhost')
+      const action = url.pathname.slice('/workbuddy-drops'.length).replace(/^\/+/, '')
+      try {
+        if (action === 'home') {
+          sendJson(res, 200, { ok: true, root: dropsDir })
+          return
+        }
+        if (action === 'stat') {
+          const path = url.searchParams.get('path') ?? ''
+          if (path === '') { sendJson(res, 200, { ok: true, exists: false, path }); return }
+          const info = await stat(path)
+          sendJson(res, 200, { ok: true, exists: true, path, type: info.isDirectory() ? 'directory' : info.isFile() ? 'file' : 'other', size: info.isFile() ? info.size : null })
+          return
+        }
+        if (action === 'list') {
+          const q = (url.searchParams.get('query') ?? '').toLowerCase()
+          const items: Array<{ name: string; path: string; type: string; size: number | null }> = []
+          const add = (p: string, name: string, type: string, size?: number) => {
+            if (items.length >= 200) return
+            if (q === '' || p.toLowerCase().includes(q) || name.toLowerCase().includes(q)) items.push({ name, path: p, type, size: size ?? null })
+          }
+          const rootInfo = await stat(dropsDir).catch(() => null)
+          if (rootInfo === null) { sendJson(res, 200, { ok: true, items: [] }); return }
+          const batches = await readdir(dropsDir, { withFileTypes: true })
+          for (const b of batches) {
+            if (items.length >= 200) break
+            if (b.name === '.tmp' || b.name.charAt(0) === '.') continue
+            const bp = join(dropsDir, b.name)
+            if (b.isFile()) {
+              const s = await stat(bp).catch(() => null)
+              add(bp, b.name, 'file', s?.size)
+              continue
+            }
+            if (!b.isDirectory()) continue
+            const children = await readdir(bp, { withFileTypes: true }).catch(() => [])
+            for (const c of children) {
+              if (items.length >= 200) break
+              const cp = join(bp, c.name)
+              const isDir = c.isDirectory()
+              const s = isDir ? null : await stat(cp).catch(() => null)
+              add(cp, c.name, isDir ? 'directory' : 'file', s?.size ?? undefined)
+              if (isDir) {
+                const sub = await readdir(cp, { withFileTypes: true }).catch(() => [])
+                for (const s2 of sub) {
+                  if (items.length >= 200) break
+                  const s2p = join(cp, s2.name)
+                  const s2dir = s2.isDirectory()
+                  const st2 = s2dir ? null : await stat(s2p).catch(() => null)
+                  add(s2p, s2.name, s2dir ? 'directory' : 'file', st2?.size ?? undefined)
+                }
+              }
+            }
+          }
+          sendJson(res, 200, { ok: true, items })
+          return
+        }
+        if (action === 'save' && req.method === 'POST') {
+          const rel = normRel(url.searchParams.get('rel') ?? '')
+          const batch = normRel(url.searchParams.get('batch') ?? '') || 'misc'
+          if (rel === null || rel === '') { sendJson(res, 400, { ok: false, error: '目标路径非法' }); return }
+          const dst = resolveDrops(dropsDir, batch + '/' + rel)
+          if (dst === undefined) { sendJson(res, 400, { ok: false, error: '目标路径越界' }); return }
+          const body = await readBody(req)
+          if (resolved.maxFileBytes > 0 && body.length > resolved.maxFileBytes) {
+            sendJson(res, 413, { ok: false, error: '文件超过大小上限 ' + Math.floor(resolved.maxFileBytes / 1048576) + 'MB' })
+            return
+          }
+          await mkdir(dirname(dst), { recursive: true })
+          await writeFile(dst, body)
+          sendJson(res, 200, { ok: true, path: dst, rel: batch + '/' + rel, root: dropsDir })
+          return
+        }
+        sendJson(res, 404, { ok: false, error: 'unknown action: ' + action })
+      } catch (err) {
+        sendJson(res, 500, { ok: false, error: String((err as Error)?.message ?? err) })
+      }
+    },
+  }), 'workbuddy: /workbuddy-drops route')
+
+  // ---------------- read_document 模型工具 ----------------
+  const readDocumentTool = defineTool({
+    name: 'read_document',
+    description:
+      '解析并读取用户消息中拖拽/粘贴/@ 产生的文件引用（支持 @"C:\\path\\file.pdf"、@path 或裸绝对路径）。' +
+      '文本类文件（代码、文档、数据）直接返回内容；文件夹引用返回目录树；图片、二进制与超大文件返回元数据与读取建议。',
+    parameters: {
+      reference: { type: 'string', required: true, description: '文件引用：消息中的 @"..." 或 @... 令牌，或直接给出绝对路径' },
+      max_chars: { type: 'number', description: '文本内容返回上限（默认 60000 字符）' },
+    },
+    output: {
+      schema: { type: 'object', additionalProperties: true } as any,
+      render: (_args: unknown, value: unknown) => [{ type: 'text', text: JSON.stringify(value) }],
+    },
+    execute: async (args: { reference: string; max_chars?: number }, _exec: unknown): Promise<any> => {
+      const maxChars = typeof args.max_chars === 'number' && args.max_chars > 0 ? Math.floor(args.max_chars) : 60000
+      const raw = String(args.reference ?? '').trim()
+      if (raw === '') return { ok: false, error: 'reference 为空' }
+      if (raw.startsWith('dsh-drop://')) {
+        return { ok: false, error: '该引用是浏览器端零上传直引（FS Access API 句柄），发送消息时已物化到本地缓存。请用消息中的真实路径重新读取。' }
+      }
+      let path = raw
+      if (path.charAt(0) === '@') path = path.slice(1).trim()
+      if (path.length >= 2 && path.charAt(0) === '"' && path.charAt(path.length - 1) === '"') path = path.slice(1, -1)
+      path = path.replace(/\/+$/, '')
+      try {
+        const info = await stat(path)
+        const base = path.split(/[\\/]/).pop()
+        if (info.isDirectory()) {
+          const entries = await readdir(path, { withFileTypes: true })
+          const tree = entries.slice(0, 300).map(async (e) => {
+            const st = e.isFile() ? await stat(join(path, e.name)).catch(() => null) : null
+            return { name: e.name, type: e.isDirectory() ? 'directory' : 'file', size: st?.size ?? null }
+          })
+          return { ok: true, path, name: base, kind: 'directory', entries: await Promise.all(tree), truncated: entries.length > 300 }
+        }
+        if (!info.isFile()) return { ok: false, error: '目标不是普通文件: ' + path }
+        const size = info.size
+        if (/\.(png|jpe?g|gif|webp|bmp|svg|ico)$/i.test(base ?? '')) {
+          return { ok: true, path, name: base, kind: 'image', size, hint: '图片文件：请使用 read_image 工具以该路径直接查看。' }
+        }
+        if (size > 1500000) {
+          return { ok: true, path, name: base, kind: 'large', size, hint: '文件过大，未内联内容；可请用户拆分，或用支持分块读取的工具处理。' }
+        }
+        const buf = await readFile(path)
+        if (looksBinary(buf)) {
+          return { ok: true, path, name: base, kind: 'binary', size, hint: '二进制文件。若为常见格式，可询问用户或用宿主工具转换后读取。' }
+        }
+        let content = buf.toString('utf8')
+        const truncated = content.length > maxChars
+        if (truncated) content = content.slice(0, maxChars)
+        return { ok: true, path, name: base, kind: 'text', size, content, truncated }
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') return { ok: false, error: '路径不存在: ' + path }
+        return { ok: false, error: String((err as Error)?.message ?? err) }
+      }
+    },
+    presentCall: (args: { reference?: string }) => ({ card: 'generic', title: '读取引用文件', kind: 'read', rawInput: String(args.reference ?? '') }),
+  })
+  const tools = ctx.get('tools')
+  ctx.effect(() => (tools !== undefined ? tools.register(readDocumentTool) : (() => {})), 'workbuddy: read_document tool')
+
+  console.log('[workbuddy-files] host 就绪：drops 缓存 ' + dropsDir + '（/workbuddy-drops 路由）+ read_document 工具')
+}