sazzadursiam/dsh-setup

dsh + Figma

CI

让 DeepSeek Harness 与 Figma 对话——从你的 agent 创建、编辑和读取设计。

安装脚本、可用的 MCP 配置，以及记录下来的死胡同，这样你就不必重蹈覆辙。

完整指南： SETUP.md —— 安装、故障排除、维护。较长的话题有各自的页面：Figma 集成、项目设置与工作流。

这能为你带来什么

- 使用你自己的 API 密钥在本地运行 dsh
- 从 agent 对 Figma 进行读取和写入：创建画板、组件和变量，或读取设计并生成代码
- 在任何 dsh 会话中可用的 125 个 Figma 工具

适用于 Windows 和 macOS。在 Linux 上，你可以获得 dsh 和只读的 Figma 访问权限——Figma 没有 Linux 桌面应用，而写入路径需要它。

快速开始

Windows —— 在命令提示符（不是 PowerShell）中：

git clone https://github.com/sazzadursiam/dsh-setup.git
cd dsh-setup
setup.bat

macOS / Linux：

git clone https://github.com/sazzadursiam/dsh-setup.git
cd dsh-setup
./setup.sh

还没有 Git？ 这些命令以 git clone 开头，但 Git 正是脚本会安装的东西之一——所以在全新的机器上，请先通过以下任一方式获取代码：

- 从仓库页面下载 ZIP（Code → Download ZIP）并解压，或
- 在 Windows 上运行 winget install Git.Git / 在 macOS 上运行 brew install git，打开一个新终端，然后按上述方式克隆。

放在哪里。 任何文件夹、任何驱动器都可以——它不需要与你的项目放在一起，你的项目也可以位于其他驱动器，因为这里没有任何东西会读取或写入项目文件夹。路径中有空格也没问题。有一个限制：不要让检出路径中包含 ( 和 )。pnpm 无法从这样的文件夹安装 dsh 插件，因此 setup 和 update 会跳过该步骤并说明原因。

该脚本会安装 Node.js、Git 和 dsh。它会询问一次是否也设置 Figma 集成（默认：否——如果跳过，则只安装 dsh 和编码工具），然后打印剩余的手动步骤。

在 Windows 上，如果脚本安装了 Node 或 Git，它会停止并要求你重新打开终端——Windows 只会在新终端中识别新的 PATH 条目。

只想要 dsh，不要 Figma？ 在该提示处按 Enter（或不传 --with-figma），它就会被跳过——没有 MCP 服务器，没有额外工具。之后随时可以从 dsh web → Settings → General → "Add Figma integration" 添加它，无需终端——也可以用同样的方式再次移除它，token 字段旁边有一个 "Remove Figma integration" 按钮。

手动步骤

1. 运行 dsh web，然后在 Settings → General → "Figma token" 下设置你的 Figma token（无需终端——保存后重启 dsh）。将其设置为环境变量也仍然有效（参见 .env.example）。如果你在设置期间跳过了 Figma，请先点击 "Add Figma integration"。
2. 添加 API 密钥，在 设置 → 模型 下 — DeepSeek 或 Anthropic
3. 将桥接插件导入 Figma Desktop

完整细节见 SETUP.md。

代理规则

dsh 会将 ~/.dsh/AGENTS.md 加载到每个项目的每个会话中，先于任何
项目自己的 AGENTS.md。因此，共享规则——如何回复、如何研究、
不要碰什么、何时升级模型——每台机器都存放在那一个文件里。不会复制到你的项目中，因此不会有任何东西过时。

setup 会为你写入它。之后要更改它：

agents.bat --role=figma,design-to-code     # Windows
./agents.sh --role=figma,design-to-code    # macOS / Linux
./agents.sh --lang=Bengali                 # 回复语言
./agents.sh --show                         # 当前已安装的内容

语言默认为英语。要使用其他语言，请设置 --lang——它会像角色一样被记住，而且当你输入罗马化形式时，这是在脚本中获得回复的方式。（在 agents.bat 中，--lang 会占用该行的其余部分，所以把它放在最后。）

角色决定你会获得哪些额外的规则块，因为一台用于 Photoshop 工作的机器不应该在每个会话开始时都读取 Figma 工具规则：

| 角色 | 用途 |
| ------------------ | ---------------------------------------------- |
| figma            | 通过桥接插件读写 Figma |
| design-to-code   | 根据 Figma 设计构建前端代码       |
| visual-assets    | Photoshop 和 Illustrator 工作                  |

你只会被询问一次，之后会被记住，所以直接运行 ./agents.sh 会使用相同的角色重新生成。对 ~/.dsh/AGENTS.md 的编辑会在下次更新时被覆盖——
要更改共享规则，请编辑 templates/core.md 或 templates/roles/.md。

对于适用于你的机器或账户的规则——你实际付费使用的提供商、内部代理、项目之外的文件夹——请将
templates/local.example.md 复制到仓库根目录下的 local.md（已被 git 忽略）。它会原样追加到 ~/.dsh/AGENTS.md，并在每次更新后保留。模板保持提供商中立，以便对所有人都有用；local.md 是你进行具体定制的地方。不要在其中放置凭据——它会进入每个会话的上下文中。

项目特定的规则放在该项目自己的 AGENTS.md 中，并提交到该项目的仓库。本仓库永远不会碰它。从
templates/project.example.md 开始，并保持简短——它会在每个会话开始时被读取。一个项目*必须遵守的规则属于那里，而不是全局文件：全局文件是按机器区分的，不会随克隆一起传播。

更新

一条命令即可拉取此仓库、使用正确的 --allow-scripts 允许列表更新 dsh、将你的 Figma MCP（如果你安装了它）移动到
plugins/figma-bridge/cordis.patch.yml 中固定的版本，并重写你的代理规则。如果你在设置期间跳过了 Figma，更新会保持跳过状态——它永远不会替你安装它；请使用 设置 中的“添加 Figma 集成”按钮：

update.bat          # Windows
./update.sh         # macOS / Linux

第一次在较旧的克隆上使用？ 这些脚本是在 v0.3.0 中引入的，因此在那之前创建的克隆还没有它们。先手动拉取一次以获取它们，然后从此以后就可以使用它们了：

cd dsh-setup
git pull
./update.sh          # Windows 上为 update.bat

有两件事任何脚本都无法为你完成：重启你的会话（更改后的规则只会对之后启动的会话生效——没有文件监视器），以及更新 ~/.dsh/settings.yaml——模型选择、推理强度和 API 密钥是按机器配置的，存放在此仓库之外。

自动更新（可选）

你的团队不需要你告诉他们你已经发布了某些内容。check 会静默地获取，与共享仓库进行比较，当检出已经是最新时不做任何操作。当有新的提交时，它会告知并提议运行更新：

check.bat           # Windows
./check.sh          # macOS / Linux

要让它自己在登录时运行：

- Windows —— setup.bat 和 update.bat 现在会为你完成这件事：它们会在你的启动文件夹中放置一个指向 check.bat 的快捷方式，并最小化，这样它永远不会占据屏幕。当没有新内容时，它会在任务栏中打开并关闭而不被察觉；当有更新时，点击任务栏条目即可看到提示。无需手动运行——但如果你需要重新执行（例如移动了检出位置之后），enable-autoupdate.bat 仍然存在。
- macOS / Linux —— 手动运行 ./check.sh，或者直接调度 update.sh 以实现完全静默的更新。两者都在 SETUP.md 的第 11 部分中。

check 涵盖此仓库——共享规则和脚本。dsh 本身有自己的按钮：setup 和 update 会将 plugins/team-updater 插件添加到你的 dsh 配置文件中，这会在设置 → 通用下放置一行“dsh updates”，为你安装 dsh 并重启。它安装的是 DSH_VERSION 中的版本——与 setup 和 update 使用的相同——而不是 npm 所称的最新版本。因此，新的 dsh 会在有人提升 DSH_VERSION 并拉取更改时到达团队，而不是在它发布的那一刻。

Figma MCP 服务器以相同的方式安装，作为 plugins/figma-bridge——setup 和 update 通过 dsh plugin --profile web add 添加它，因此无需手动复制。此仓库中的版本提升会在下次 update 运行时到达已安装的配置文件。

有什么不工作吗？

在翻阅文档之前先运行验证器——它会告诉你缺少哪一部分：

verify.bat          # Windows
./verify.sh         # macOS / Linux

它还会报告你的代理规则是否已安装且是最新的。

为什么不使用官方 Figma MCP 服务器

Figma 的远程 MCP（https://mcp.figma.com/mcp）无法与 dsh 配合使用：

- 它只接受 OAuth——不支持个人访问令牌
- 它不允许动态客户端注册，因此只有预先注册的客户端（VS Code、Cursor、Claude Code、Codex）才能连接
- 支持 OAuth 的社区插件和 mcp-remote 桥接在 registerClient 时都会失败，报 HTTP 403 Forbidden

本仓库改用 figma-console-mcp 的本地模式。它完全绕开了 OAuth：一个桥接插件运行在 Figma Desktop 内——你已经在其中登录——并通过本地 WebSocket 与 MCP 服务器通信。写入操作经由 Figma 的 Plugin API，这就是为什么变量在 Free 和 Pro 计划上也能正常工作。

已知问题

截图工具在本地模式下无法使用。 figma_capture_screenshot 和 figma_take_screenshot 会失败，报 Cannot read properties of undefined (reading 'bytes')。更糟的是，一次失败的调用会污染整个会话——之后每一轮都会抛出同样的错误，即使没有工具调用，唯一的解决办法是新建一个会话。

这是上游问题：这些工具所依赖的 CDP 传输已从本地模式中移除。figma 角色块会让 agent 远离它们，所以如果你会接触 Figma，把它放进你的规则中是值得的。

Linux 上没有 Figma 写入权限。 没有桌面应用就没有桥接插件。请使用 Windows 或 macOS 进行设计工作。

文件

| 文件                          | 用途                                                    |
| ----------------------------- | ---------------------------------------------------------- |
| SETUP.md                    | 指南（英文）——在每个操作系统上安装、故障排除、维护 |
| docs/figma.md               | Figma 集成：token、配置文件、桥接插件       |
| docs/workflow.md            | 按项目设置、agent 规则所在位置、Figma → 代码    |
| setup.bat / setup.sh      | 安装脚本                                            |
| update.bat / update.sh    | 更新现有安装                                   |
| check.bat / check.sh      | 检查更新，仅在你确认后才应用             |
| enable-autoupdate.bat       | 添加登录时更新检查（Windows）                  |
| ensure-npm-path.bat         | 如果找不到 dsh，将 npm 的全局文件夹加入 PATH——由 setup.bat 和 update.bat 调用（Windows） |
| agents.bat / agents.sh    | 将共享 agent 规则写入 ~/.dsh/AGENTS.md         |
| verify.bat / verify.sh    | 检查已设置和缺失的内容                   |
| plugins/team-updater/       | 应用内更新按钮——由 setup 添加到你的 dsh 配置 |
| plugins/figma-bridge/       | Figma MCP 服务器配置——由 setup 添加到你的 dsh 配置，类似 plugins/team-updater/ |
| templates/core.md           | 共享规则，应用于每个项目                 |
| templates/roles/            | 可选规则块——Figma、设计到代码、视觉资源 |
| templates/project.example.md| 项目自身 AGENTS.md 的起点             |
| templates/local.example.md  | local.md 的起点——你机器特定的规则 |
| .env.example                | 你需要哪些环境变量                       |
| VERSION                     | 这个检出是什么版本                              |
| DSH_VERSION                 | setup 和 update 安装哪个 dsh 版本 — 固定版本，而非 latest |
| DSH_ALLOW_SCRIPTS           | 安装该 dsh 时，npm 可以为哪些包运行安装脚本 |
| CHANGELOG.md                | 改了什么以及为什么                                       |
| LICENSE                     | MIT                                                        |

密钥

此仓库中不存放任何令牌。Figma 令牌可以设置为系统环境变量，或粘贴到 dsh UI 的 Settings → General 中（见 plugins/figma-bridge/）；提供商 API 密钥（DeepSeek 或 Anthropic）在 dsh UI 中输入。

在 UI 中输入密钥并不等同于加密它：dsh 会将每个提供商密钥以明文写入 ~/.dsh/.credentials.yaml，而通过 Settings → General 设置的 Figma 令牌会以明文写入 ~/.dsh/profiles/web/node_modules/dsh-figma-bridge/cordis.patch.yml。切勿将这些文件或 .dsh/ 文件夹复制到另一台机器、仓库或同步备份中，也切勿将其内容粘贴到任何地方。详情见 SETUP.md 第 1 部分第 4 步。

如果令牌曾被提交，仅删除文件是不够的——它会留在 git 历史中。请在 figma.com → Settings → Security 撤销它，并签发一个新的。

状态

dsh 是开发者预览版，会发布破坏性变更。如果这里的某些内容不再符合实际情况，请提交 issue 或发送 PR——这正是它保持有用的方式。具体做法见 CONTRIBUTING.md；安全问题请通过 SECURITY.md 处理，而不是公开 issue。

作者

Sazzadur Rahman

许可证

MIT — 见 LICENSE。