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

用于 DeepSeek Harness 的 Sprites

CI
Latest tag
License: MIT

在 DeepSeek Harness 中使用 Sprites：用于构建、测试、实验和长时间运行服务的隔离、持久化 Linux 环境。

本仓库是一个 Harness bundle。其 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。因此，本 bundle 使用 Harness 支持的 stdio 传输和 mcp-remote 来完成标准浏览器 OAuth 流程，而无需 Sprites API 令牌。

安装

将 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 的情况下验证已安装的 bundle 和组合行：

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

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

首批提示词

- “列出我的 sprites。”
- “为此实验创建一个 sprite，并在其中运行 uname -a。”
- “创建一个检查点，然后在我的 sprite 中运行测试套件。”
- “在我的 sprite 中启动 Web 服务，并给我它的 URL。”

空的 sprite 列表是成功的已认证响应。

身份验证和访问
托管端点为 https://sprites.dev/mcp，并使用 OAuth 2.1。mcp-remote 将其 OAuth 状态存储在其常规的本地凭据目录中；此仓库不包含任何凭据。

Sprites 同意屏幕通常会创建一个受限的连接器令牌。其默认名称前缀通常是 mcp-，并且可能会限制该连接器可以创建的 sprite 数量。自定义的非空前缀仍然受限。选择 Full access 会移除前缀限制，但会授予对组织中每个 sprite 的访问权限。

对于 agent 工作，优先使用受限访问。如果 create 调用报告了必需的前缀，Harness 应使用该确切前缀重试一次，并报告实际名称。

工作原理

cordis.patch.yml 贡献两行：

1. sprites-mcp 通过 Harness MCP 客户端启动 mcp-remote。该桥接处理 OAuth，并通过 ctx.tools 将服务器工具暴露为 mcp__sprites__。
2. sprites-skill-filesystem 加载此包的 index.js。该入口从 import.meta.url 解析 skills/，然后将 @deepseek-ai/dsh-skill-filesystem 挂载为隔离的 provider。这是有意用 JavaScript 完成的：bundle patch 求值时使用的 baseUrl 是 profile 目录，而不是已安装的包目录。

MCP 子进程还会发送固定的、隐私安全的客户端归属标头：

| 标头 | 值 |
|---|---|
| Fly-Client-Agent | deepseek-harness |
| Fly-Client-Interactive | false |

不会发送任何用户、机器、仓库或会话特定的归属信息。这些标头仅用于咨询性分析，不用于授权或速率限制。

mcp-remote 在其 OAuth 缓存键中同时包含服务器 URL 和序列化标头。因此，更改任一归属标头都会使现有的缓存授权失效，并要求用户重新进行身份验证。

安全

- 将通过 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 内部的网络故障

在更改 sprite 的网络策略之前，请让 Harness 检查该策略。一个可访问的 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

支持与反馈

- 使用缺陷报告表单报告可复现的插件缺陷。
- 使用功能请求表单提出工作流或集成改进建议。
- 在查看 Sprites 文档后，可在 Fly.io 社区中提出一般性的 Sprites 问题。
- 按照 SECURITY.md 中所述的方式私下报告安全问题。切勿在 issue 中包含凭据或生产数据。

项目政策

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

许可证

MIT © Fly.io, Inc.