@vectorx/function-debugger

本包提供一个基于 Vite + React + Monaco 的“函数调试器”，用于在浏览器中读取本地云函数代码并进行快速在线调试。

核心组成：

• bin/vfd.js：命令行入口，仅负责解析参数并委托服务启动。
• src/App.ts：基于 Express + WebSocket + Node vm 的调试服务，负责文件读取/写入、目录树推送与沙盒执行。
• src/webview-ui：前端界面，通过 WebSocket 同步文件更新，并通过 HTTP 调用 Node 沙盒。

CLI 启动调试

# 将 /path/to/functions 目录挂载到调试器
pnpm --filter @vectorx/function-debugger exec vfd start -s /path/to/functions

命令会启动：

• API 服务（默认随机端口）：提供 GET /api/file、POST /api/save、POST /sandbox/run 等接口。
• WebSocket 服务（/ws）：承载目录树、文件读写同步以及本地文件变更推送。
• Vite Dev Server（默认 5175 端口）：承载 Web UI，同时通过 define 注入 __VFD_WS_URL__、__VFD_WORKSPACE__ 等变量。

控制台会输出三个地址，分别对应 API、WebSocket 与前端 UI；若指定 -o/--open 会自动打开浏览器。

开发

pnpm --filter @vectorx/function-debugger dev

开发模式下，Vite 会挂载与 CLI 同步的调试接口，默认读取仓库中的 playground/doc-file-agent/src/index.js。若希望调试真实函数目录，可直接运行上方 CLI，并在浏览器访问 CLI 输出的 UI 地址。

浏览器沙箱模式不支持 require；若函数依赖外部包，可切换到 Node 沙箱或在真实运行环境验证。

布局说明

• 左侧：函数列表（来自工作目录实时生成的目录树）
• 中间：代码编辑器（Monaco）
• 右侧：请求参数与调试结果（状态码、Body、日志、错误）

调试原理与架构（含 mermaid）

参考抖音云“控制面调试”能力，本项目将“UI 展示”和“调试执行”解耦：

• 前端 UI：负责代码展示、参数录入与结果渲染；不直接执行 Node 代码。
• Debugger Server（Node 沙箱）：负责读取/保存文件、在受控沙箱内执行用户函数、收集日志并返回结果。

交互时序（mermaid 时序图）

sequenceDiagram
  participant U as User(点击调试)
  participant FE as Frontend(UI)
  participant DS as Debugger Server(Node vm)
  participant VM as Node vm Context

  U->>FE: 选择运行时(Node/Browser)、填写 Body
  FE->>DS: POST /sandbox/run { code, payloadText }
  DS->>VM: 创建 vm.Context (console/module/exports/require stub/context)
  VM-->>DS: 运行用户代码，定位导出函数(main 或 module.exports)
  DS->>VM: 调用导出函数(payload, context)
  VM-->>DS: 返回 result，收集 console 日志
  DS-->>FE: { ok,status,durationMs,body,logs,error }
  FE-->>U: 渲染“运行结果/日志”

端到端流程（mermaid 流程图）

flowchart LR
  A[编辑器代码] -->|保存/刷新| B[/api/file /api/save/]
  A --> C{运行时选择}
  C -->|Browser| D[浏览器轻量沙箱 new Function]
  C -->|Node 沙箱| E[/sandbox/run Node vm/]
  D --> G[结果/日志]
  E --> G[结果/日志]

Debugger Server 说明

• 服务位置：
  • CLI/生产：src/App.ts 导出 startFunctionDebugger，封装 Express + WebSocket + chokidar。
  • 开发：vite.config.js 插件注入等价路由，便于前端独立运行。
• API 能力：
  • GET /api/file?path= 读取工作区内的文件内容
  • POST /api/save 保存文件，带简易版本冲突检测（mtime）
  • POST /sandbox/run 在 Node vm 中执行用户代码，返回 { ok, status, durationMs, body, logs, error }
  • WebSocket /ws：支持 tree（目录树）、read、write、fsEvent、ping 等消息
• 沙箱策略（/sandbox/run）：
  • 使用 vm.createContext 创建隔离上下文，注入：
    • console：采集日志（log/info/warn/error）
    • module/exports：兼容 CommonJS 导出
    • require：默认禁止（抛出错误），后续可加入白名单
    • context：注入 { requestId } 等轻量上下文
  • 导出函数约定：
    • module.exports = async (params, context) => any
    • 或 exports.main = async (event, context) => any
  • 资源约束：
    • 超时限制（默认 2s，可在 App.ts 调整）
    • 禁止任意 require、文件系统与网络访问（可按需放开）

生产形态建议把 Debugger Server 独立为服务，以支持更强的沙箱隔离、资源限额、白名单依赖、持久日志与鉴权审计等能力。

前端 UI 职责

• 负责：
  • 代码展示与编辑（Monaco）
  • 参数录入（Method/Body/端形态等）
  • 调试发起（调用 /sandbox/run）与结果渲染
  • 监听 WebSocket 事件以保持文件与目录树同步
• 不负责：
  • Node 依赖的装载执行
  • 任何越权的文件或网络访问

与“控制面调试”的映射

• 方法/Body/Headers/Query：右侧面板逐步补齐输入能力；目前 Method + Body 已支持。
• 运行结果与日志：已对齐返回结构与 console 日志呈现。
• 草稿代码 vs 线上代码：
  • 草稿：前端编辑后可直接调用 /sandbox/run
  • 线上：调用真实云端接口，不走本地沙箱（后续在调试模式切换里提供）