title: “把个人编码 Agent 放到 Cloudflare 边缘：dsh-edge 的持久工作区、两种 Shell 与能力边界”

slug: dsh-edge-cloudflare-worker-persistent-coding-agent

把个人编码 Agent 放到 Cloudflare 边缘：dsh-edge 的持久工作区、两种 Shell 与能力边界

把编码 Agent 部署到云端，常见的难点并不在模型接口，而在「会话和工作目录怎样跨请求保存」。传统做法会准备一台 VPS、容器或 CI Runner：要维护操作系统、网络入口、密钥和升级流程。dsh-edge 选择了另一条路线：它把 DeepSeek Harness 的 Web 体验放进 Cloudflare Workers，并把一个个人实例的状态收敛到一个 Durable Object 中。

这个项目适合想获得浏览器可访问的个人编码工作台、但不想维护常驻服务器的开发者。它是由 pawaca 维护的独立社区项目，明确说明自己并不隶属于 DeepSeek；上游 DeepSeek Harness 负责 Agent 循环、Web UI、模型选择和会话协议，dsh-edge 负责 Cloudflare 运行时、持久化工作区、单所有者登录和安装器。仓库采用 MIT 许可证；npm 当前稳定版为 0.5.3，仓库中的开发版本可能更高，二者不能混为已发布能力。

先理解：它不是「把 Linux 服务器搬进 Worker」

dsh-edge 的核心结构是「一个认证所有者对应一个固定 Durable Object」。工作目录 /workspace 映射到 Durable Object 的 SQLite 支撑虚拟文件系统；会话事件也经过上游的持久化协调器写入 Durable Object 存储。这样，浏览器刷新、Worker 请求结束甚至对象休眠后，工作区和会话仍有机会恢复，而不是依赖单个 HTTP 请求的内存。

这也决定了能力边界。默认的 Direct Shell 在 Durable Object 内运行 just-bash，可在同一虚拟文件系统上处理命令，但它不是 Linux 容器：没有任意原生二进制、后台进程、PTY，也不应期待任意 Linux 行为。文档还说明该直接模式没有命令网络访问。对于需要隔离执行的场景，项目提供 Isolated — Dynamic Worker 目标：它使用 Cloudflare Computer 的 Worker Shell 后端，但需要 Workers Paid。两种模式复用同一个 UI、会话、工作区和工具接口；差别主要在命令执行环境，而不是另起一套 Agent 协议。

因此，最合适的任务是：编辑和检查工作区内的文本、让 Agent 维护项目草稿、执行受限 Shell 操作、在浏览器继续一段已有会话。需要 Docker、编译本地依赖、启动长期服务、调试交互式 TTY 或依赖内网的工程，则应留在传统开发机、容器平台或专用沙箱中。

最短安装路径：让安装器完成 Cloudflare 配置

项目要求 Node.js 22.14 或更高版本，并需要开发者自己的 DeepSeek API Key。公开 CLI 的安装入口是：

npx dsh-edge install

安装器会引导部署 Worker。文档把路径分成两类：Try now 可以先体验、但需要在 60 分钟内认领才能保留；Keep it 面向长期使用，需要一个启用了 R2 的 Cloudflare 账户。长期部署时，数据和凭据由自己的 Cloudflare 账户承载，而不是交给项目维护者托管。

升级也不要求检出仓库或接入 Git 仓库：

npx dsh-edge upgrade

升级器会寻找已有 Worker，并尝试原地升级、保留持久数据。即便如此，升级前仍建议导出关键工作成果。应用层「持久化」不等于任意版本升级都不会产生兼容性风险，尤其当项目仍处于快速迭代阶段。

凭据与单人边界：部署方便不等于多租户平台

dsh-edge 设计为单所有者实例，并不提供注册、角色或多租户路由。所有者通过高熵访问密钥登录，部署把密钥作为 Worker secret；文档指出，登录后会换取带 HttpOnly 与 SameSite=Strict 属性的 30 天 cookie。DeepSeek 凭据优先从 Durable Object 的设置存储读取，未设置时才回退到 Worker 环境变量；已解析的值保持在请求范围内，不写入会话事件或响应。

本地开发可用 .dev.vars 放置配置。下面的变量名来自项目运行时文档，值应自行替换，且不要提交到版本库：

DSH_EDGE_ACCESS_KEY=replace-with-at-least-32-random-bytes
DEEPSEEK_API_KEY=replace-with-your-key
DEEPSEEK_MODEL=deepseek-v4-flash
DEEPSEEK_REASONING_EFFORT=high
DSH_EDGE_DEFAULT_COMMAND_TIMEOUT_MS=120000

这里有两个实践重点。第一，访问密钥和模型密钥职责不同：前者保护你的个人 Worker，后者用于模型调用，不能用一个弱口令同时承担两种职责。第二，若要把实例交给团队共用，先不要用共享同一访问密钥的方式绕过设计；它既无法获得成员级审计，也会让会话和工作区的所有权变得模糊。

数据与交互的取舍：为何 Durable Object 比「无状态聊天页」更适合这类工具

项目把上游的会话历史、事件流、工具调用和恢复流程接到 Durable Object。浏览器端通过 HTTP 与可休眠 WebSocket 获得事件；冷启动时持久化协调器负责准备恢复。这种设计的价值不是无限存储，而是把「下一次请求还能看到上一轮 Agent 的工作上下文」变成运行时的基本能力。

为了防止一个长会话拖垮边缘实例，文档给出了一系列明确上限：会话列表默认最多 50 条，事件重放默认 128 条、最高 256 条；浏览器历史会拒绝超过 8,192 个事件或 8 MiB 的窗口，而非悄悄截断。这些限制值得正面看待：它们把容量问题暴露成可处理的产品边界。使用时应把可长期复用的结论写回 /workspace 中的 README、任务清单或设计文档，而不是期望所有知识永久躺在聊天上下文里。

附件也有类似取舍。新建的长期部署可使用私有 R2；临时部署或特定升级路径会使用受限的 Durable Object 附件后端。项目对 PNG/JPEG 附件保留上游的引用与授权机制，但这不代表它已经把所有宿主机工具都移植到了 Worker：MCP、技能、工作流、作业和子代理等能力在兼容矩阵中仍被列为需要逐项适配，不能当成已完整支持的功能。

上线前的工程检查：把边界写进团队约定

如果把它用于日常开发，建议在第一次部署时就建立一份最小运行手册。先记录 Node.js、dsh-edge 和上游 Harness 的版本；再记录 Worker 所属账户、R2 是否启用、访问密钥轮换方式，以及 Direct Shell 与 Isolated Shell 的选择。这样，之后出现「模型能回答但文件不存在」「升级后会话没有恢复」等问题时，可以区分是凭据、持久化后端还是运行时能力差异，而不是笼统地归咎于 Agent。

还应把命令执行看作高风险接口。即使 Direct Shell 没有网络命令，Agent 仍可能修改工作区内的文件；上线前可以先使用无关紧要的测试目录，观察超时、取消、空输出和大文件处理。项目文档明确给出了默认命令超时和调用者可选择的上限，但这些参数不是性能保证：一个耗时任务被切断后，应该由上层工作流保存中间状态并允许重试，而不是假设进程会像 VPS 上的后台服务一样继续运行。

对于代码仓库，推荐让 Agent 先生成变更说明，再执行写操作；关键提交仍由人检查 diff。对于团队共享，最稳妥的方式是把 dsh-edge 当作个人工作台，把协作放到 Git、代码评审和现有身份系统中。它的单所有者模型简单、攻击面较小，却不适合直接承担组织级权限管理。

curl -c /tmp/dsh-edge-cookie -X POST \
  -H 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'accessKey=replace-with-your-random-key' \
  http://localhost:8787/api/auth/login

curl -b /tmp/dsh-edge-cookie -X PUT --data 'hello from the edge' \
  'http://localhost:8787/api/workspace/file?path=/workspace/hello.txt'

curl -b /tmp/dsh-edge-cookie -X POST \
  -H 'content-type: application/json' \
  --data '{"command":"cat /workspace/hello.txt"}' \
  http://localhost:8787/api/workspace/exec

这组命令对应本地 Worker 的诊断 API：先取得 cookie，再写入 /workspace/hello.txt，最后通过工作区执行接口读取它。在线上环境应把 localhost:8787 替换为自己的 Worker 域名，并只在受控环境中使用诊断接口。验证成功后，再测试浏览器会话的创建、刷新后的文件可见性，以及超时与失败时的恢复行为。

dsh-edge 的价值不在于宣称边缘运行时能替代完整开发服务器，而在于把个人 Agent 的会话、工作区和访问边界收紧到自己的 Cloudflare 账户中。若任务符合受限 Shell 和单人工作台的模型，它能减少服务器运维；若任务需要完整 Linux、多人权限或无限制后台执行，承认边界并换用更合适的执行平台，反而是更稳妥的工程选择。

若准备长期使用，也应定期检查 Worker 日志、R2 用量和模型账单，把访问密钥轮换纳入日常运维，而不是只在首次安装时关注安全。边缘部署减少了主机维护，却没有消除备份、权限和成本控制责任。

相关链接

• [dsh-edge GitHub 仓库](https://github.com/pawaca/dsh-edge)
• [dsh-edge npm 包](https://www.npmjs.com/package/dsh-edge)
• [DeepSeek Harness 上游仓库](https://github.com/deepseek-ai/deepseek-harness)