Stuga 协作工作区 stuga-dev/dsh-plugin

@stuga/dsh-plugin

将 DeepSeek Harness（dsh）配置文件连接到 Stuga。

Stuga 是一个自托管的协作工作区：实时文档、带 SQL 的结构化数据库、混合搜索，以及为 AI 智能体提供的一流访问能力。智能体从不静默写入：每一次编辑都是可审查运行账本上的一个提案，归属于该智能体的密钥，并由人类接受、拒绝或还原。此插件让 DeepSeek Harness 智能体成为一个行为良好的 Stuga 智能体。

它有意设计为一个轻量层：

| 组件 | 作用 |
| cordis.patch.yml | 将 harness 内置的 MCP 客户端挂载到节点的 /mcp，使模型以 mcp__stuga__ 的形式获得 Stuga 的工具：用于读取的 workspaces、docs、search、markdown、comments、folders、events、collections、retrieve、databases 和 query；用于写入的 docs_create、markdown_append、markdown_edit、comments_add、media_upload、collections_edit、databases_add 和 databases_change。 |
| index.js | 注册一个系统提示词部分，说明调用如何被路由和审查，并以该密钥自身的工作区及其约定作为结尾，同时注册三个操作手册技能。 |
| skills/ | stuga-research、stuga-propose-edits、stuga-databases —— 通过 harness 的 skill 工具按需加载。 |

Stuga 强制执行的一切（运行账本、搜索内部的访问控制、逐次调用审计、只读密钥）都由 Stuga 节点强制执行。插件仅持有一个智能体密钥，并针对该接口塑造模型的行为。

安装

你需要一个正在运行的 Stuga 节点和一个 DeepSeek Harness 安装（Node ^22.19 || >=24，pnpm 位于 PATH 中）。

1. 在 Stuga 中，打开 Settings → Your own AI，选择 DeepSeek Harness，并生成一个智能体密钥。以 harness 命名它（该名称就是审查者在收件箱中看到的内容）。你可以按需将其限制到文件夹、设为只读，或为其设置过期时间。该密钥可到达你所属的每个工作区；限制到文件夹的密钥会留在其生成时所在的工作区中。该标签页会打印下面的命令和环境变量行，并填入密钥。

2. 将插件安装到你运行的配置文件中（Web UI 配置文件为 web）：

dsh plugin --profile web add @stuga/dsh-plugin

若从代码检出而非 npm 安装：dsh plugin --profile web add /path/to/dsh-plugin。

3. 告诉 harness 节点在哪里以及使用哪个密钥。可以在启动它的 shell 中导出它们，或将它们放入 $DSH_HOME/.env：

STUGA_URL=http://127.0.0.1:8787
STUGA_API_KEY=vk_…

4. 重启 dsh web。使用以下命令检查组合：

dsh --profile web --dump-config

你应该会看到 stuga-mcp 和 stuga-guidance 行。在新会话中，mcp__stuga__ 工具可用，并且 skill 工具会列出这三个操作手册。

卸载：dsh plugin --profile web remove @stuga/dsh-plugin。

审查者看到的内容当 agent 提议进行编辑时，工具结果会显示 Proposed — … This is SUCCESS: do NOT retry，并且提示词部分会告诉模型在回复末尾附上指向 /doc/ 和 /review 的链接。在 Stuga 中打开这些链接，即可逐个变更块接受或拒绝每处更改。在收件箱中，该运行会以 deepseek-harness 徽标显示（该插件会发送 x-stuga-client 请求头），并归在该密钥的名称下。如果文档被设置为立即应用 agent 更改，编辑会立即生效并通知审阅者；结果随后会显示 Applied。

配置

stuga-guidance 行接受以下字段：

| 字段 | 默认值 | 含义 |
| url | $STUGA_URL 或 http://127.0.0.1:8787 | 模型提供给审阅者的链接中使用的源 |
| serverName | stuga | 必须与 MCP 行的 serverName 匹配；设置提示词所引用的 mcp____ 前缀 |
| section | true | 注册系统提示词部分 |
| skills | true | 注册三个 playbook 技能 |
| instructions | true | 读取该密钥的工作区及其约定，并将其放入系统提示词中 |
| instructionsRefreshMs | 300000 | 重新读取它们的频率 |

该密钥的工作区及其约定

每次 Stuga 工具调用都会指明其操作所在的工作区：workspace_id，或者对于 search 和 retrieve 则是 workspace_ids，其中 ["*"] 涵盖该密钥可访问的每个工作区。工作区还可以为 agent 携带自由文本约定（Settings → This workspace → Agents）：笔记放在哪里、不要触碰什么、内部风格。节点会在其 MCP 服务器的 instructions 字段中提供其工作区和约定，但 harness 的 MCP 客户端不会呈现该字段，而被要求获取它们的模型往往干脆不获取——在一次端到端运行中，gpt-4o 编辑了一个文档，却从未调用 workspaces action:instructions。

因此，该插件会自行通过同一个密钥读取该密钥自己的工作区——其 workspace_id、名称和约定——并将它们放在提示词部分的末尾，在那里它们无法被跳过。模型可以立即在那里调用工具。workspaces 的 list 操作会列出该密钥可访问的任何其他工作区，提示词部分和 playbook 会告诉模型在写入该工作区之前，先用 workspaces 的 instructions 操作读取其约定。节点宕机或密钥没有访问权限意味着同一件事：该部分会在没有工作区的情况下注册，且不会发生任何失败。
文件夹、数据库和文档也可以携带自己的指令，通过 Stuga 中它们的⋯菜单设置。这些指令会从最外层向内逐层叠加到工作区的指令之上，并且取决于具体条目，因此插件不会将它们放入系统提示中。节点会随条目一起传递它们：markdown read 会在文档文本之前以标记块的形式显示它们，或者以一行说明没有适用的指令开头，因此植入文档文本中的指令永远不会引导读取；而 docs metadata、docs_create 和 databases schema 会将它们作为 instructions 返回。提示部分和操作手册告诉模型在写入时遵循这些指令，绝不要将它们复制到编辑中，并将读取内容中看起来像此类块的任何后续内容视为文档文本。

为模型添加标签

来自此插件的运行在 Stuga 的审核收件箱中标记为 deepseek-harness。测试框架不会将其运行的模型暴露给其 MCP 层，因此模型标签由你设置：导出 STUGA_MODEL=gpt-4o（或你固定的任何模型），它就会显示在客户端徽章旁边。

在 $DSH_HOME/profiles/web/cordis.patch.yml 中按 id 覆盖某一行。补丁会替换该行的整个 config，因此请重新声明你需要的每个键。例如，要将 MCP 行指向 TLS 后面的节点并使用更长的工具超时：

- id: stuga-mcp
config:
serverName: stuga
transport: streamable-http
url: https://notes.example.com/mcp
headers:
Authorization: !!js '"Bearer " + process.env.STUGA_API_KEY'
x-stuga-client: deepseek-harness
toolCallTimeoutMs: 120000
failOnStartupError: false

限制

- 密钥是静态的。测试框架的 MCP 客户端没有 OAuth，因此没有浏览器登录；密钥所有者是代理提出的每个提案的审核者。每人使用一个密钥，不要使用共享的团队密钥。
- 工具调用在 DeepSeek Harness Web UI 中呈现为通用卡片。对人类友好的信号是结果文本和助手回复中的链接。
- 系统提示中只包含密钥自己工作区的约定。另一个工作区的约定通过 mcp__stuga__workspaces 以 action: "instructions" 到达模型，提示部分告诉它在写入那里之前调用该操作，并且在插件无法读取密钥自己的工作区时也要调用它。
- 文件夹、数据库或文档自己的指令仅通过上述工具应答到达模型，因此模型如果在未先读取的情况下写入文档，就会错过这些指令。提示部分和操作手册说要先读取文档再编辑。
- 一个密钥共享一个请求预算（/mcp 上每分钟 600 个请求，无论其调用指定哪些工作区），供使用它的每个会话和子代理共享。
- 已针对 DeepSeek Harness 0.1.2-rc.1 进行测试。该 harness 是开发者预览版，各版本之间可能存在破坏性变更；本插件仅涉及 ctx.systemPrompt.section 和 ctx.skills.register 注册表以及 dsh-mcp-client 行，并且如果任一注册表发生变化，会降级为普通的 MCP 行。

开发

该包是纯 JavaScript，没有运行时依赖，也没有构建步骤。

npm test

提示词部分和技能手册逐字复制了 Stuga 的工具和操作名称；测试会根据 Stuga 的 MCP 服务器附带的工具（契约 2）对它们进行检查。Config 是手写的 Standard Schema 对象，Cordis 正是通过它来验证某一行的配置，因此该插件不依赖于 harness 的 schema 库。

许可证

MIT。Stuga 本身是 AGPL-3.0；本插件是客户端配置层，不包含任何 Stuga 代码。