Sprites 远程沙箱 superfly/sprites-deepseek-plugin

适用于 DeepSeek Harness 的 Sprites

在 DeepSeek Harness 里使用 Sprites：隔离、持久的 Linux 环境，适合构建、测试、实验和长期运行的服务。

这个仓库是一个 Harness 捆绑包。它的 cordis.patch.yml 挂载了：

- @deepseek-ai/dsh-mcp-client，连接到托管的 Sprites MCP 服务器。
- 本包的 index.js 入口，它把 @deepseek-ai/dsh-skill-filesystem 挂载到打包好的 Sprites 工作流技能上。

最终得到的是一个原生 Cordis 组合：Sprites 工具以 mcp__sprites__* 的形式出现，Sprites 技能则可以通过 Harness 常规的技能系统发现。

要求

- Node.js 20.19 或更新版本。打包的文件系统服务商目前依赖 Chokidar 5，其引擎下限是 Node 20.19。
- DeepSeek Harness 开发者预览版。
- 首次 Sprites OAuth 授权需要浏览器访问。
- npx 需要网络访问，才能运行固定版本的 mcp-remote@0.1.38 OAuth 桥接。

Harness 当前的 Streamable HTTP MCP 传输接受静态请求头，但不执行 MCP OAuth。因此这个捆绑包使用 Harness 支持的 stdio 传输和 mcp-remote，完成标准的浏览器 OAuth 流程，无需 Sprites API token。

安装

把 GitHub 检出安装到你使用的配置档里。以内置的 Web 配置档为例：

npx @deepseek-ai/dsh plugin --profile web add github:superfly/sprites-deepseek-plugin

然后启动该配置档：

npx @deepseek-ai/dsh --profile web

首次连接时，完成浏览器 OAuth 流程，选择 Fly.io 组织，并查看连接器访问策略。如果在你授权期间首次工具同步超时了，重启一次 Harness。

从本仓库进行本地开发：

npx @deepseek-ai/dsh plugin --profile web add .
npx @deepseek-ai/dsh --profile web

想在不安装到配置档的情况下试用这一层：

npx @deepseek-ai/dsh web --patch ./cordis.patch.yml

不启动 UI，直接验证已安装的捆绑包和组合后的行：

npx @deepseek-ai/dsh --profile web --dump-config

输出里应该包含 dsh-sprites-plugin 层、sprites-mcp 和 sprites-skill-filesystem。

首批提示词

- "List my sprites."
- "Create a sprite for this experiment and run uname -a in it."
- "Create a checkpoint, then run the test suite in my sprite."
- "Start the web service in my sprite and give me its URL."

Sprites 列表为空，就是一次成功的已认证响应。

认证与访问

托管端点是 https://sprites.dev/mcp，使用 OAuth 2.1。mcp-remote 把 OAuth 状态存在它自己的本地凭据目录里；这个仓库不含任何凭据。

Sprites 授权页通常会创建一个受限的连接器 token。它的默认名前缀一般是 mcp-，并且可能限制连接器能创建的 sprite 数量。自定义一个非空前缀，仍然受限。选择 Full access 会去掉前缀限制，但会授予访问组织内所有 sprite 的权限。

智能体干活时，优先用受限访问。如果某次创建调用报出必需的前缀，Harness 应该用那个确切前缀重试一次，并报告实际名称。

工作原理

cordis.patch.yml 贡献两行：

1. sprites-mcp 通过 Harness MCP 客户端启动 mcp-remote。这个桥接负责处理 OAuth，并通过 ctx.tools 把服务端工具暴露为 mcp__sprites__<tool>。
2. sprites-skill-filesystem 加载本包的 index.js。入口从 import.meta.url 解析出 skills/，然后把 @deepseek-ai/dsh-skill-filesystem 挂载为隔离的服务商。这一步刻意用 JavaScript 完成：bundle 补丁求值时，baseUrl 是配置档目录，而不是已安装包的目录。

MCP 子进程还会发送固定的、不涉及隐私的客户端归属头：

| Header | Value |
| Fly-Client-Agent | deepseek-harness |
| Fly-Client-Interactive | false |

不发送任何与用户、机器、仓库或会话相关的归属信息。这些头只用于分析参考，不参与授权，也不参与限流。

mcp-remote 把服务端 URL 和序列化后的头一起算进 OAuth 缓存键。所以改动任意一个归属头，都会让已缓存的授权失效，用户需要重新认证。

安全

- 把通过 sprite URL 暴露的服务，都当作可能可从公网访问。
- 绝不发布密钥、环境变量转储、任意文件、调试端点或未过滤的日志。
- 做有风险的改动文件系统、升级依赖或迁移之前，先建检查点。
- 销毁 sprite 不可逆。只有用户明确要求删除、销毁或移除，或者批准清理时，才销毁。
- 改动出站网络策略之前，先检查它。

故障排查

工具不见了

确认 bundle 出现在 --dump-config 里，并且两行 Cordis 都在。Harness 的 MCP 客户端会记录连接、发现和工具注册的失败。原生工具名以 mcp__sprites__ 开头。

OAuth 没走完

完成浏览器流程期间，让 Harness 进程保持运行。如果初次同步超时，先完成授权再重启 Harness；mcp-remote 会复用已存的 OAuth 会话。

如果 mcp-remote 的认证状态反复出问题，按它上游的故障排查指引处理。清空它的凭据目录会让所有 mcp-remote 连接器退出登录，所以别随手这么干。

npx 无法启动

确保启动 Harness 的环境里有 Node.js 20.19+ 和 npx。MCP 客户端刻意使用参数数组，不做 shell 插值。

sprite 内部网络故障

改网络策略之前，先让 Harness 检查 sprite 的网络策略。MCP 服务器可达，不代表 sprite 内部出口不受限。

仓库结构

package.json Harness bundle manifest (dsh.bundle)
cordis.patch.yml Cordis rows for MCP and packaged skills
index.js Package-relative Sprites skill provider entry
skills/sprites/ DeepSeek Harness Sprites skill and references
scripts/check_repository.py Static repository validation
tests/test_repository.py Bundle contract tests

开发

python -m pip install -r requirements-dev.txt
npm install --ignore-scripts --package-lock=false
ruff check .
ruff format --check .
python scripts/check_repository.py
python -m unittest discover -s tests -v
node scripts/check_skill_entry.mjs

相关链接

- DeepSeek Harness 插件开发
- DeepSeek Harness 打包与安装指南
- Sprites 远程 MCP 文档
- Sprites MCP 服务器仓库
- mcp-remote

支持与反馈

- 用 bug 报告表单提交可复现的插件 bug。
- 用 功能请求表单提出工作流或集成改进建议。
- 先查 Sprites 文档，再到 Fly.io 社区问 Sprites 的通用问题。
- 安全问题按 SECURITY.md 里的说明私下报告。issue 里绝不要放凭据或生产数据。

项目政策

见 CONTRIBUTING.md、CODE_OF_CONDUCT.md、SECURITY.md、SUPPORT.md 和 CHANGELOG.md。

许可证

MIT © Fly.io, Inc.