FomoGoMan/dsh-serena-guide

dsh-serena-guide

一个用于 DeepSeek Harness 的插件，它让 Harness 的智能体在处理代码工作时优先使用 Serena 的 LSP 支持的符号化工具，而非内置的 Read/Glob/Grep/Edit。

对于每个智能体，它会：

- 启动一个绑定到该智能体工作目录的 serena MCP 服务器（serena start-mcp-server --context dsh --project ），并将其工具以 mcp__serena__ 的形式注册到该智能体的作用域上；
- 添加一个 serena:guide 提示词章节，声明对于代码文件，Serena 工具为 PRIMARY（主要），内置代码工具为 SECONDARY（次要），在两者冲突时取代内置工具指引；
- 添加一个拒绝防护，阻止一连串从未触及任何 serena 工具的内置 glob/grep/代码文件 read 调用，促使模型回到 mcp__serena__。

项目绑定是确定性的——它是一个进程参数，而非模型指令——因此活动项目始终是会话的工作区，模型永远不必调用 activate_project。

Serena 是一个 MCP 服务器，暴露由语言服务器支持、感知符号的工具（find_symbol、rename_symbol、replace_symbol_body、get_symbols_overview 等）。你必须安装 serena CLI，并拥有一个多项目 serena 上下文（参见要求）。

要求

- 一个 DeepSeek Harness 安装（harness CLI 从某个 profile 加载此插件）。@deepseek-ai/ 对等包由宿主安装提供——请勿自行安装它们。
- PATH 上有 serena CLI（按照 Serena 的文档，通过 uv tool install serena-agent 安装）。
- 为此插件准备一个 serena 上下文。没有 single_project 的上下文会暴露多项目激活；该插件按会话使用 --project，因此需要多项目上下文。Serena 的上下文 schema 要求一个 prompt 字段（没有默认值——缺少该字段的文件会加载失败），因此上下文文件需要包含以下全部内容。示例 ~/.serena/contexts/dsh.yml：

description: DeepSeek Harness agent context (per-session --project binding)
prompt: |
You have access to Serena's symbolic code-intelligence tools
(mcp__serena__), bound to your current working directory. Prefer them
over built-in grep/read for code work.
excluded_tools:
- create_text_file
- read_file
- execute_shell_command
- find_file
- list_dir

excluded_tools 会隐藏那些与 harness 内置工具重复的 serena 工具（read_file→read、find_file→glob、execute_shell_command→bash、create_text_file→write、list_dir）。prompt 是一个 Jinja2 模板，serena 会将其渲染进它的 Instructions Manual，模型通过 initial_instructions 读取它；请保持简短——插件自身的 serena:guide 章节承载完整的偏好规则。

挂载

1. 将该包安装到你的 profile 中：

dsh plugin --profile web add dsh-serena-guide

（在 harness 发布且包上架 npm 之前，请改为从这个 checkout 安装：dsh plugin --profile web add /path/to/dsh-serena-guide。）

2. 将其挂载到 profile 的 patch 层——添加到 ~/.dsh/profiles/web/cordis.patch.yml：

- insert:
- id: serena-guide
name: dsh-serena-guide
config:
context: dsh      # your multi-project serena context

3. 重启 profile（dsh --profile web）。当 agent 的第一轮开始时，会为该会话的工作区生成一个 serena 服务器；第一个提示词已经携带了 mcp__serena__ 工具和指南部分。

其他 profile 以相同方式配合 --profile  使用。

配置

| 字段 | 默认值 | 含义 |
|---|---|---|
| serverName | serena | MCP 服务器名称；工具前缀变为 mcp____ |
| command | serena | 启动 serena MCP 服务器的可执行文件 |
| context | dsh | Serena 上下文名称或路径（用户安装的多项目上下文） |
| env | — | 为生成的 serena 进程提供的额外环境变量 |
| toolCallTimeoutMs | 60000 | 每次 callTool 的超时时间 |
| startupTimeoutMs | 15000 | 在第一个请求之前，等待初始 serena 连接的有界时长 |
| failOnStartupError | false | 当初始 serena 连接失败时，拒绝 agent 安装 |

模型体验

工具偏好部分

serena:guide 部分位于顺序 110（工具指导带，在顺序 0 的 persona 和顺序 99 的文件引用上下文之后，在顺序 105 的 tool-bash 和顺序 150 的 SDK 部分之前），按 agent 注册，并且仅在该 agent 的 serena 工具可见时存在。启动门控从第一个提示词起就将其置于该位置：会话的第一次 assemble 最多等待 startupTimeoutMs 让 serena 连接，并重新 assemble，而不是与生成过程竞争并导致到达时没有指南，因此模型在第一次选择工具之前就读到了偏好。它声明 Serena 工具对于代码文件是 PRIMARY，内置的 Read/Glob/Grep/Edit 是 SECONDARY，声明冲突的内置工具指令被 SUPERSEDED，给出任务→工具映射表、必需的编辑前工作流、允许的例外，以及每次调用内置工具前的自检。当没有注册 serena 工具时，模型不会从该部分看到任何内容。

拒绝守卫

一个按 agent 注册的 ctx.tools.guard，当自上次 serena 调用或拒绝以来，内置 glob、grep 或代码文件 read 调用的连续次数超过阈值（三次调用）时，返回一个拒绝原因。工具运行时将该原因作为被阻止的工具结果显示出来——Error: You were using many grep/glob/read calls without Serena's symbolic tools. Consider using mcp__serena__find_symbol / get_symbols_overview instead…——模型会读取并对此做出反应。一次 serena 调用会重置该连续计数；一次拒绝也会重置它，并且两分钟内不会触发第二次拒绝。非跟踪工具（edit、write、bash……）和非代码 read 目标保持中性。

Token 影响
条件式且固定长度。serena 工具不存在时为零 token；存在时为稳定的约 30 行块。没有无界或依赖 agent 的内容。deny 仅在触发时产生工具结果，在允许的调用上从不产生。

KV 缓存影响

在其存在状态不变时前缀稳定：静态文本，在各轮次和 agent 之间完全相同，因此它加入共享前缀而不会逐轮漂移。在 profile 重新组合时切换 serena 的开启或关闭会改变整个 section 是否存在，从而使此前缀从该点起失效——这是组合时事件，而非逐轮事件。

工作原理

Serena 是一个外部 stdio MCP 服务器。该插件是承载 harness 三个扩展接缝的桥梁：

- MCP 接缝 — @deepseek-ai/dsh-mcp-client 的 startConnection 启动 serena 进程，并将其工具注册到 agent 的作用域（mcp__serena__）。--project  固定会话的工作区。
- system-prompt 接缝 — ctx.systemPrompt.section() 以顺序 110 注册该指南，仅在 mcp__serena__find_symbol 哨兵可见时渲染。
- tools 接缝 — ctx.tools.guard() 拒绝 glob/grep/read 突发。

由于 harness 在 turn/start 之后立即同步组装第一个提示（早于 serena 启动可能完成），该插件同步注册到 agent 上下文（而非通过延迟的 ctx.inject fiber），并将第一次 system-prompt/assemble 门控在 serena 连接上，重新组装以使第一个请求已经携带 serena。连接失败或超时会回退到普通的内置工具会话。

开发

该插件导入尚未发布的 @deepseek-ai/ 包；package.json 将它们列为 peerDependencies（由宿主 harness 安装满足）以及 devDependencies，后者通过 link: 指向本地 ../deepseek-harness 检出以进行类型检查和测试。在该路径上有 harness 检出的情况下：

pnpm install
pnpm run typecheck
pnpm run test
pnpm run build

已知限制与推迟的工作

- 每 agent 一个 serena 实例 — 每个 agent 都会启动自己的 serena 进程，绑定到其工作目录；不同工作区上的两个会话完全隔离，代价是每个会话一次 serena 启动（约 1–3 秒，会话的第一个请求会等待它）。按工作区共享一个实例被推迟：startConnection 将工具注册到传给它的 ctx 上，因此共享连接无法用当前 API 服务多个 agent 作用域。
- 整个 section 门控于单个哨兵 — 单个 mcp____find_symbol 存在性检查会按 agent 同时开启或关闭两种机制。如果 serena 服务器以不同的 serverName 注册，该 section 将保持静默，guard 也将保持惰性。
- 强制执行以单次运行为范围，而非绝对——该守卫仅在上一次 serena 调用之后发生三次 glob/grep/read 调用后才拒绝；单次调用、两次调用或非代码的 read 每次都会通过，而在一次拒绝之后，模型可以在两分钟内自由使用内置工具。这与 Serena 自身的 remind 钩子一致，并避免阻塞合法使用，但它无法阻止仅仅是切换较慢的模型。