dsh-agent-sdk-bridge 1.2.3 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/DEVELOPMENT.md CHANGED
@@ -35,10 +35,12 @@
35
35
  页面就一直要你「再装一次」。
36
36
  - **退出登录要清凭据并关会话**:Qoder CLI 没有 `logout` 子命令,登录态只保存在加密的
37
37
  `~/.qoder-cn/.auth/user`(国际版 `~/.qoder/.auth/user`);`machine_id` 属于机器而不是账号,保留。
38
- 两个 `setup-*.bat` 的 `--logout` 删除该文件后再跑一次 `status`,确认不再打印 `Username`;
39
- `POST /setup {mode:'logout'}` 成功后调用 `closeSessions()`,因为热会话里的 CLI 进程在启动时
40
- 已加载旧凭据,不关掉就会继续以刚退出的账号作答。页面同时清空额度缓存(`resetSignal`),
41
- 避免旧账号的积分继续显示。
38
+ 两个 `setup-*.bat` 的 `--logout` 删除该文件后再跑一次 `status`,确认不再打印 `Username`。
39
+ **登录和退出都必须调 `resetAccount()`**:它关掉热会话、清空目录与额度缓存,并且
40
+ `discardSdk()` 停掉当前 daemon 后强制下一读加载新实例。daemon 的凭据不在
41
+ `configurationSignature()` 里(`auth.type === 'qodercli'` 恒等),所以换号后签名不变;
42
+ 只关会话不换 daemon,额度卡和后续回合仍会以旧账号作答,直到进程重启。页面的
43
+ `resetSignal` 只在退出时清掉本地额度快照,登录后的正确性依赖服务端这次重读。
42
44
  - **卸载要清干净**:npm 只删包,会留下空的 `node_modules/@qoder-ai`(或 `@qodercn-ai`)目录和
43
45
  `qodercli.cmd`/`.ps1` 之类 shim,而 CLI 查找和页面的「已安装」徽标读的正是这些。两个
44
46
  `setup-*.bat` 的 `--uninstall` 会在 `npm uninstall -g` 之后删掉 shim 与空 scope 目录,
@@ -75,6 +77,18 @@
75
77
  切区域时页面先渲染本地快照,再用 `fresh=1` 在后台校验。
76
78
  浏览器由 CLI 的登录流程自己打开;`onAuthUrl` 只记录 URL 供卡片显示「手动打开登录页」,
77
79
  宿主不再调用系统打开方式,否则每次登录会出现两个相同标签页。
80
+ - **空目录是「账号的回答」,不是「读失败」**:CLI 1.1.81 在**未登录**时,`accountInfo()` 抛
81
+ `Authentication required`,但 `getAvailableModels()` 返回**成功的空数组**——连 `cache` /
82
+ `live` 两种 `fetchStrategy` 也是空数组(即使 `~/.qoder-cn/.models` 里有上一账号的
83
+ `catalog-v6/v7`,目录按 uid 分目录存放,所以读不到上一账号的表)。因此「空」是账号在说话。
84
+ 以前 `models()` 只看 `live.length === 0` 就当作「CLI 读不到」并回落到静态 `QODER_MODELS`,
85
+ 于是**退出登录后聊天选择器仍然列满 Qoder 模型**(设置页读 `describeCatalog()`、只看 live,
86
+ 所以设置页是空的,两个界面就此不一致)。现在回落到静态表只有一种情况:**本机装了 CLI,
87
+ 且这次读取还没得到过任何回答**;`emptyCatalogFallback()` 是这条规则的唯一实现,
88
+ 由 `answeredCatalogs`(进程级、**不随 `invalidate()` 清空**)记录「成功读过一次」。
89
+ 记录不清空是刻意的:退出登录后紧接着一次网络失败,否则又会退化成「CLI 从没读到过」。
90
+ CodeBuddy 与 MiniMax 本来就没这个问题——它们的 `listModels()` 先 `isSignedIn()` 再读目录,
91
+ 而且没有静态表可泄;Qoder 是唯一缺这道闸的。
78
92
  - **CodeBuddy 的宿主工具**:宿主工具通过进程内 MCP server 挂入,`CodeBuddySession` 必须
79
93
  在 CLI 启动前完成注册——`ensureTools()` 会保存 schema,`ensureStarted()` 创建 MCP server
80
94
  后立即重放,然后才 `createSession`(MCP SDK 拒绝连接后再注册)。早返回会让首个 turn
@@ -83,6 +97,19 @@
83
97
  仍会丢弃任何非宿主前缀的 tool_use,防止模型臆造工具名。CodeBuddy 会把 MCP server 名里的
84
98
  非字母数字字符规范成 `_`(`dsh-host` → `mcp__dsh_host__<tool>`),Qoder CLI 保留连字符,
85
99
  因此 `isHostTool()` / `hostToolName()` 同时接受两种拼写。
100
+ - **MCP 工具集必须在连接前声明能力,并按名字对账**:MCP SDK 的 `McpServer` 只在**第一次**
101
+ `registerTool` 时安装 `tools/list` + `tools/call` 处理器并登记 `tools: { listChanged: true }`;
102
+ 连上去之后再改能力会抛 `Cannot register capabilities after connecting to transport`,而空表
103
+ 连上去的 server 连 `tools/list` 都只会回 `Method not found (-32601)`。本插件的首轮常常是空
104
+ 工具表(宿主还没发布工具),因此 `HostToolRegistry.prepare()` 在 `connect()` 之前显式调用
105
+ `setToolRequestHandlers()`,把能力先声明出来。
106
+ 注册本身也从「只增」改成按名字**对账**:新增注册、schema/描述变了的 `update()` 就地更新
107
+ (MCP SDK 对同名第二次 `registerTool` 直接抛 `Tool X is already registered`)、宿主撤下的
108
+ `remove()`,变化后 `sendToolListChanged()`。这正对应用户看到的
109
+ `Tool "mcp__dsh_host__ops_edit" does not exist in the current tool set.`——那是
110
+ **CodeBuddy CLI** 的措辞,含义是模型调了一个 server 里没有的名字;工具注册失败被 `catch`
111
+ 吞掉正是它的来源,所以现在失败了会 `console.warn` 打出来,绝不静默。
112
+ Qoder 路径同样适用(`session.ts` 共用 `HostToolRegistry`)。
86
113
  - **切换模型读缓存**:`resolveModel` 与 `capture()` 走 `cachedModels()`
87
114
  (`src/model-cache.ts`):有快照就先返回快照,刷新在后台跑;只有从未读到过目录时才等待。
88
115
  三家的目录获取都很贵(Qoder 冷启动 CLI,最长等于 fetch 超时;CodeBuddy 要启进程;MiniMax
@@ -204,7 +231,13 @@
204
231
  它那一轮结束之后才触发。成对调用等待宿主的下一次请求并由该请求结算;只有未配上对的 handler
205
232
  受 `toolResultTimeoutSeconds` 兜底。宿主**从未见过**的调用(工具块落在两次宿主请求之间被丢弃,
206
233
  而 CLI 仍派发了 MCP 消息)不 park,立即返回取消结果——否则这一轮没人能解开。
207
- - **旁路请求**:标题生成、压缩摘要走冷启动一次性调用,不占用 warm 会话。
234
+ - **旁路请求**:标题生成、压缩摘要走冷启动一次性调用,不占用 warm 会话。**它们不是「继续
235
+ 对话」**:DSH 在请求上标 `purpose: 'compaction' | 'session-title'`,并把真正的指令作为
236
+ **最后一条 user 消息**追加(压缩那条是 `Condense the conversation ABOVE …`)。这类请求必须用
237
+ `renderSideChannelFeed()` 组 prompt(角色=执行末条指令,结尾=「请执行最后一条用户消息给出的
238
+ 任务」),不能用 `renderInitialFeed()`:后者开头写「你只输出"下一条助手回复"」,结尾又写
239
+ 「输出下一条助手回复」,模型于是把上一条回复复述一遍,摘要位置就变成了复述。三家共用这份
240
+ 渲染,判据在 `test/side-channel.test.ts`。
208
241
  - **真实计量**:CLI 默认把用量帧里的 token 计数清零,插件在启动子进程时带上它的
209
242
  `EXPOSE_TOKEN_USAGE` 开关;总量、缓存命中与 tok/s 因此都是 provider 实测值,只有拿不到计量时才
210
243
  按「context 比率 → 字符估算」兜底。占用样本只取自**每次请求结束**的那一帧(`requestUsageSample()`,
package/FAQ.md CHANGED
@@ -26,8 +26,9 @@ scope 目录;页面上的「已安装」也改成每次现查机器,所以
26
26
 
27
27
  **想换账号或退出登录?** Qoder 页面在已安装 CLI 时会显示「退出登录」。Qoder CLI 本身没有 `logout`
28
28
  子命令,插件改为删除该版本加密保存的凭据(国内版 `~/.qoder-cn/.auth/user`,国际版
29
- `~/.qoder/.auth/user`;`machine_id` 保留),并在成功后关闭已打开的会话、清空额度缓存。因此旧账号
30
- 不会继续作答,旧积分也不会挂在卡片上;CLI 保持安装,点「重新登录」即可换号。
29
+ `~/.qoder/.auth/user`;`machine_id` 保留)。登录和退出的成功回调都会关闭已打开的会话、清空目录与额度
30
+ 缓存,并重启 SDK daemon——daemon 在启动时就把凭据读进内存,不换掉它就会继续用上一个账号作答。
31
+ 因此换号后不会读到旧账号的额度、模型和回答;CLI 保持安装,点「重新登录」即可换号。
31
32
 
32
33
  **点「重新登录」后关掉了浏览器,页面就一直转圈?** 已修复,并新增「取消」。`qodercli login`
33
34
  会一直等浏览器回调,关掉标签页就没有返回值。现在运行中会出现「取消」按钮:点它会终止这次
@@ -41,6 +42,12 @@ scope 目录;页面上的「已安装」也改成每次现查机器,所以
41
42
  不可用。额度读取走的是 CLI 自己的凭证,所以先确认对应版本的 `status` 能列出用户名;点「刷新额度」
42
43
  可重试。它失败不会影响模型列表和对话。
43
44
 
45
+ **Qoder 退出登录后,聊天里的模型选择器还列着一堆模型?** 已修复。CLI 未登录时会**成功返回一个空
46
+ 目录**(不是报错),旧代码把「空」当成「CLI 读不到」并回落到内置的 CN 套餐表,于是退出登录后选择器
47
+ 仍列满模型,选了只会失败;设置页看的是另一次读取,所以只显示空,两边不一致。现在回落到内置表只
48
+ 有一种情况:**本机装着 CLI、且这次读取还没拿到过任何回答**。CLI 没装、或账号已经明确回答过(哪怕
49
+ 回答是空),选择器就保持空。CodeBuddy 和 MiniMax 本来就有登录闸,不受影响。
50
+
44
51
  **CodeBuddy 页面显示「尚未登录」,但模型列表有内容?** 新版不会出现这种情况:未登录时页面只显示
45
52
  登录卡片,模型目录根本不会被读取,模型选择器也不会列出 CodeBuddy 模型。请在页面顶部选择
46
53
  「国际版」或「国内版」,点「登录」并在浏览器完成授权;登录成功后才会读取目录并显示账号与额度。
@@ -73,6 +80,75 @@ bearer token,只留在本机,请不要分享或提交到仓库。从旧版
73
80
  `tools: []` 禁用 CLI 内置工具,只保留宿主通过 MCP 挂入的工具;CodeBuddy 把 MCP server 名
74
81
  规范成 `dsh_host` 的写法也已兼容。升级后重启 DSH Web 即可。
75
82
 
83
+ **CodeBuddy 用着用着报 `Tool "mcp__dsh_host__ops_edit" does not exist in the current tool set.`?**
84
+ 已修复。这句是 **CodeBuddy CLI 自己的**话(由它的 `Tool X not found in agent Y` 改写而来),
85
+ 不是宿主说的:模型调了一个 MCP server 里并不存在的工具名。根因在本插件一边,有两层:
86
+
87
+ 1. **MCP server 连接时没有 `tools` 能力**。MCP SDK 的 `McpServer` 只在**第一次**
88
+ `registerTool` 时才安装 `tools/list` / `tools/call` 处理器并登记 `tools` 能力(带
89
+ `listChanged`)。本插件在 `ensureTools()` 里注册工具,而首轮宿主还没给出工具表时会以空表
90
+ 连接——于是 server 带着「没有 tools 能力」连上去,`tools/list` 对客户端直接
91
+ `Method not found (-32601)`;之后模型用到的 `ops_*` 工具再来注册时,SDK 抛
92
+ `Cannot register capabilities after connecting to transport`,旧代码 `catch { continue }`
93
+ 把它吞掉,工具就永远没进 `tools/list`。模型照着宿主系统提示和 `tool-addition` 块去调,
94
+ 自然得到上面那句。现在两条 SDK 路径都在 `connect()` 之前调用
95
+ `setToolRequestHandlers()` 先把能力声明出来,工具于是可以随时增删。
96
+ 2. **注册只会「加」,不会「改」和「删」**。MCP SDK 对同名工具第二次 `registerTool` 直接抛
97
+ `Tool X is already registered`,所以切换 `dsh-ops` 模式后 schema 变了却留在旧定义上,
98
+ 宿主撤下的工具也注销不掉。现在 `HostToolRegistry` 按名字对账:新增的注册、变了的
99
+ `update()` 就地更新、撤下的 `remove()`,每次变化都 `sendToolListChanged()` 通知客户端。
100
+ 注册失败不再静默——会以 `[dsh-agent-sdk-bridge] 宿主工具 X 未能注册进 MCP server:…`
101
+ 打到日志,因为「工具从模型世界里消失、宿主却以为还在提供」正是这句话的来源。
102
+
103
+ 判据是 `test/tool-registry.test.ts`:它用真实的 `@modelcontextprotocol/sdk` 跑一个真实的
104
+ client/server 对,钉住连接前的能力声明、以及工具集的增/改/删。
105
+
106
+ **Qoder 有没有同样的问题?** 有,只是平时看不出来。Qoder 的 SDK 工厂同样是
107
+ `createSdkMcpServer({ name, tools: [] })`,能力声明写的是
108
+ `tools: tools.length > 0 ? {} : undefined`——空表首轮连上去同样是「没有 tools 能力」。
109
+ 它侥幸没出事只因为调用顺序:`ensureTools()` 在 CLI 启动**之前**跑,首轮只要有任意一个工具,
110
+ SDK 就会在安装处理器时顺手把能力声明补上。第二层缺陷(只增不改不删)则一直都在:模式切换后
111
+ schema 停在旧定义、宿主撤下的工具仍然可调,只是表现成「参数不认」和「unknown tool」,而不是
112
+ CodeBuddy 那句显眼的报错。现在两条路径共用 `HostToolRegistry`,`prepare()` 在 `connect()`
113
+ 之前无条件声明能力。判据是 `test/qoder-session-tools.test.ts`:它构造真实的 `QoderSession`,
114
+ 在 spawn 时刻用真实 MCP client 读 `tools/list`,并在摘掉 `prepare()` 的树上验证过是红的
115
+ (「空首轮 + 之后才出现的工具」那条尤其依赖它)。
116
+
117
+ **CodeBuddy 报 `unknown tool "mcp__dsh_host__edit"` 后又说 `Tool "mcp__dsh_host__mcp__dsh_host__edit" does not exist in the current tool set.`?**
118
+ 已修复。这两句其实是**同一个 bug 的两面**,出自两个不同的地方:第一句是 **DSH** 的
119
+ `dsh-tools`(`ToolNotFoundError`,宿主的工具表里没有这个名字),第二句是 **CodeBuddy CLI**
120
+ 自己合成的(MCP server 里没有这个名字)。模型就是在两个错误之间来回猜拼写。
121
+
122
+ 根因是工具名前缀只剥了**一层**。模型偶尔会发出一个已经带前缀的名字,CLI 又加了一层前缀,
123
+ 于是处理器收到 `mcp__dsh_host__mcp__dsh_host__edit`;旧实现 `slice` 一次后交给宿主
124
+ `mcp__dsh_host__edit`——宿主的工具叫 `edit`,所以 DSH 回 `unknown tool "mcp__dsh_host__edit"`;
125
+ 模型照着这个错误改成双重拼写重试,CLI 又不认,回第二句。**一个名字剥到底就都对了。**
126
+
127
+ 现在 `src/mcp-naming.ts` 的 `stripMcpNamespace()` 会把每一层前缀都剥掉(并设有 8 层上限,
128
+ 纯粹由前缀组成的名字返回 null 而不是把前缀当工具名),CodeBuddy / Qoder / MiniMax 三条路径
129
+ 共用它,不再各写一份一层 `slice`。判据是 `test/mcp-naming.test.ts`,其中「双层前缀剥到
130
+ `edit`」和「三家一致」两条在单层剥离下确认过是红的。
131
+
132
+ 顺带一提:同一张截图里的 `cannot modify "…": file has not been read — read the file, then retry`
133
+ 是**另一回事**——那是 DSH 的 `dsh-tool-fs` 观测策略(`FS_NOT_OBSERVED`),要求改之前先读;
134
+ 它属于宿主侧的正常门禁,跟工具注册无关。模型当时也注意到了这一点(它说「要先 read」)。
135
+
136
+ **压缩对话之后,摘要位置显示的是「上一条回复」的原文?** 已修复。压缩请求和普通对话走同一个
137
+ LLM 接口,DSH 只是给它标上 `purpose: 'compaction'`,并在消息末尾追加一条**用户消息**作为指令
138
+ (`Condense the conversation ABOVE into a structured checkpoint…`),期望模型执行它。
139
+
140
+ 三家适配器过去都用 `renderInitialFeed()` 组这条 prompt,而那是给「继续对话」用的:开头写
141
+ 「你只输出"下一条助手回复"本身」,结尾写「以上是背景。输出下一条助手回复」。于是真正的压缩
142
+ 指令被埋进「背景」,模型却收到了两次「继续对话」的指示——它就照做,把上一条助手回复又说了一遍,
143
+ 摘要位置于是成了复述。
144
+
145
+ 现在旁路请求统一走 `renderSideChannelFeed()`:角色说明改成「最后一条用户消息就是你要执行的
146
+ 任务」,结尾改成「请执行最后一条用户消息给出的任务」。Qoder / CodeBuddy / MiniMax 三条路径
147
+ 共用这份渲染,所以三家一起修好(MiniMax 另有一句「你只是标题与摘要助手」的 system prompt,
148
+ 曾经缓解、但没能修正自相矛盾的结尾)。判据是 `test/side-channel.test.ts`:它直接断言压缩
149
+ prompt 里出现指令、且**不出现**「下一条助手回复」,并逐家检查适配器确实走了共享渲染。
150
+ 旧渲染下其中 4 条会红。
151
+
76
152
  **Qoder 的上下文环为什么也会小幅跳一下(比如从 60% 掉到 20% 又涨回来)?** 因为分母曾经会
77
153
  短暂变成 200K。Qoder 的 `context_usage_ratio` 按「CLI 实际运行的窗口」算,DSH 又用适配器上报的
78
154
  窗口当分母;目录里 `dfmodel` 等模型其实声明了 `[200K, 400K, 1M]`,你选 1M 是上游支持的。旧代码