前言¶
在 DeepSeek Harness（dsh）里跑智能体时，模型往往只能改本地文件或调用你单独配置的 MCP；若协作平台要求「每次写入都是可审阅的 proposal、挂在 run ledger 上、由人 accept / reject」，还要遵守工作区里的 conventions，就需要在 harness profile 与节点之间加一层薄适配。
Stuga 是自托管协作工作区：实时文档、可 SQL 查询的结构化库、混合检索，并对 AI 智能体有一等公民访问；智能体不会静默落盘，编辑以 proposal 形式进入可审阅账本。@stuga/dsh-plugin（维护者 stuga-dev，社区目录分类为工作流）做的事，就是把某个 dsh profile 连到 Stuga 节点：挂载 Stuga 的 MCP 工具、把密钥所属工作区及其 conventions 写进 system prompt，并注册三个按需加载的 playbook skill，让 harness 里的模型按 Stuga 的审阅与权限模型行事。
这是什么¶
一句话：@stuga/dsh-plugin 是 Stuga 与 DeepSeek Harness 之间的薄连接层。npm 包名 @stuga/dsh-plugin，当前资料中的版本为 0.2.0，许可证 MIT。Stuga 侧强制执行的 run ledger、检索内访问控制、逐调用审计、只读密钥等，均由 Stuga 节点负责；插件只持有 agent key，并塑造模型在该 API 面上的行为。
核心组成与能力¶
插件刻意保持轻薄，主要三块（见仓库 README 表格）：
| 部分 | 作用 |
|---|---|
cordis.patch.yml |
把 harness 内置 MCP 客户端挂到节点的 /mcp，模型侧工具名为 mcp__stuga__* |
index.js |
注册 system-prompt 段落（说明调用如何路由与审阅），末尾附上密钥所属工作区及其 conventions；并注册三个 playbook skill |
skills/ |
stuga-research、stuga-propose-edits、stuga-databases，通过 harness 的 skill 工具按需加载 |
读类 MCP 工具（资料列举）：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。在 Stuga 语义下，写操作产生 proposal，由人在审阅界面处理，而非模型侧「写成功即结束」。
工作区 conventions：节点会在 MCP instructions 里提供各工作区说明，但 harness 的 MCP 客户端不暴露该字段，模型也常不会去调 workspaces 的 instructions。插件因此用同一密钥自行读取「密钥所属工作区」的 workspace_id、名称与 conventions，并固定在 prompt 段落末尾。写入其他可达工作区前，prompt 与 playbook 要求先 workspaces action instructions。文件夹、数据库、文档级说明不在 system prompt 里汇总，而通过 markdown read、docs metadata 等工具结果带给模型；prompt 要求编辑前先 read 文档。
审阅侧可见性：proposal 的工具结果会出现 Proposed — … This is SUCCESS: do NOT retry；prompt 要求助手回复末尾给出 <STUGA_URL>/doc/<doc_id> 与 <STUGA_URL>/review 链接。收件箱里 run 带 deepseek-harness 徽章（插件发送 x-stuga-client 头），名称来自你在 Stuga mint 密钥时起的名字。若文档配置为立即应用智能体变更，结果会显示 Applied。可通过环境变量 STUGA_MODEL 设置模型标签（与 client 徽章并列）。
安装与启用¶
前提：已有运行中的 Stuga 节点，以及 DeepSeek Harness 安装（Node ^22.19 || >=24，且 pnpm 在 PATH 上）。
1、在 Stuga 打开 Settings → Your own AI，选择 DeepSeek Harness，mint 一个 agent key。名称会出现在审阅收件箱；可按文件夹收窄、只读或设置过期。密钥可达你所属的全部工作区；若按文件夹收窄，则限定在 mint 时所在工作区。该页会打印已填入密钥的安装命令与环境变量行。
2、把插件装进你实际使用的 profile（Web UI 常用 profile 名为 web）：
dsh plugin --profile web add @stuga/dsh-plugin
若从本地检出安装而非 npm：dsh plugin --profile web add /path/to/dsh-plugin。
3、告诉 harness 节点地址与密钥。可在启动 harness 的 shell 里 export，或写入 $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 工具应列出上述三个 playbook。
卸载：dsh plugin --profile web remove @stuga/dsh-plugin。
配置项（stuga-guidance）¶
stuga-guidance 行支持字段（资料原文默认值如下）：
| 字段 | 默认 | 含义 |
|---|---|---|
url |
$STUGA_URL 或 http://127.0.0.1:8787 |
模型给审阅者链接时使用的 origin |
serverName |
stuga |
须与 MCP 行的 serverName 一致，决定 prompt 中的 mcp__<serverName>__ 前缀 |
section |
true |
是否注册 system-prompt 段落 |
skills |
true |
是否注册三个 playbook skill |
instructions |
true |
是否读取密钥工作区 conventions 并写入 system prompt |
instructionsRefreshMs |
300000 |
conventions 重新拉取间隔（毫秒） |
需要改 MCP 传输、TLS、超时等时，可在 $DSH_HOME/profiles/web/cordis.patch.yml 按 id 覆盖整行 config（patch 会替换该行全部 config，需写全所需键）。README 给出了将 stuga-mcp 指向 https://notes.example.com/mcp、Bearer 鉴权、toolCallTimeoutMs: 120000 等的 YAML 示例。
典型用法与审阅流程¶
1、完成安装与环境变量后，在 harness Web 会话中让模型使用 Stuga 工具检索或读文档（可配合 skill 加载 stuga-research）。
2、需要改文档或库表时，模型应走写类 MCP 工具；结果以 proposal 形式返回，助手应在回复中附上 doc 与 review 链接，而不是因「未直接写入」而重复调用。
3、你在 Stuga 打开 review 链接，按 hunk accept 或 reject；收件箱中可识别来源为 deepseek-harness 与密钥名称。
DeepSeek Harness Web UI 里工具调用会显示为通用卡片；对人友好的信号主要是工具返回文案与助手回复中的链接。
适用场景与限制¶
适合：已在用或计划用 Stuga 做团队文档与结构化数据，并希望用 DeepSeek Harness 作为前端智能体，且接受「写入皆 proposal、密钥持有者为审阅责任方」的工作流。
运行与信任：插件以当前 dsh 进程权限运行，安装前应阅读 GitHub 源码 与 MIT 许可证，并理解 agent key 的权限范围。
资料中明确列出的限制：
- 密钥是静态的；harness MCP 客户端无 OAuth，无浏览器登录；应用「一人一钥」，不要共用团队钥。
- 仅密钥所属工作区的 conventions 固定在 system prompt；其他工作区须模型主动
workspacesinstructions。 - 文档/文件夹/数据库级说明只在 read/metadata 等结果中出现；不 read 就 edit 可能漏掉约束。
- 一钥在同一 refresh 周期内共享 conventions 的重新拉取（README 截断处起笔为「One key shares one re…」，完整句以仓库 README 为准）。
DeepSeek Harness 生态强调「一切皆插件」；SkillHub 目录页 是社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
@stuga/dsh-plugin 不重复实现 Stuga 的审阅与权限，而是把 MCP 工具、工作区 conventions 与三个 playbook 接到指定 dsh profile，让 harness 智能体在 Stuga 上按 proposal 流程协作。安装命令以 README 为准：dsh plugin --profile web add @stuga/dsh-plugin。
- 目录页：https://www.skillhub.cn/plugins/stuga-dev/dsh-plugin
- GitHub：https://github.com/stuga-dev/dsh-plugin
