dsh-agent-sdk-bridge 0.0.0-stage → 1.0.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 +122 -0
- package/FAQ.md +213 -0
- package/LICENSE +21 -0
- package/LICENSE.original +21 -0
- package/NOTICE +96 -0
- package/README.md +131 -2
- package/client.js +1802 -0
- package/cordis.patch.yml +7 -0
- package/lib/index.js +5589 -0
- package/lib/types/adapter.d.ts +244 -0
- package/lib/types/api.d.ts +48 -0
- package/lib/types/brand.d.ts +78 -0
- package/lib/types/catalog.d.ts +43 -0
- package/lib/types/cli.d.ts +111 -0
- package/lib/types/codebuddy-adapter.d.ts +76 -0
- package/lib/types/codebuddy-state.d.ts +72 -0
- package/lib/types/codebuddy.d.ts +278 -0
- package/lib/types/config.d.ts +304 -0
- package/lib/types/index.d.ts +163 -0
- package/lib/types/jsonschema.d.ts +29 -0
- package/lib/types/live.d.ts +50 -0
- package/lib/types/models.d.ts +74 -0
- package/lib/types/render.d.ts +79 -0
- package/lib/types/sdk.d.ts +44 -0
- package/lib/types/session.d.ts +680 -0
- package/lib/types/setup.d.ts +79 -0
- package/lib/types/tokens.d.ts +99 -0
- package/lib/types/usage.d.ts +58 -0
- package/package.json +103 -4
- package/scripts/setup-qodercli.bat +242 -0
- package/scripts/setup-qoderclicn.bat +242 -0
- package/src/adapter.ts +671 -0
- package/src/api.ts +322 -0
- package/src/brand.ts +135 -0
- package/src/catalog.ts +79 -0
- package/src/cli.ts +314 -0
- package/src/codebuddy-adapter.ts +294 -0
- package/src/codebuddy-state.ts +182 -0
- package/src/codebuddy.ts +1268 -0
- package/src/config.ts +423 -0
- package/src/index.ts +358 -0
- package/src/jsonschema.ts +85 -0
- package/src/live.ts +58 -0
- package/src/models.ts +204 -0
- package/src/render.ts +229 -0
- package/src/sdk.ts +89 -0
- package/src/session.ts +1606 -0
- package/src/setup.ts +239 -0
- package/src/tokens.ts +154 -0
- package/src/usage.ts +128 -0
package/DEVELOPMENT.md
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# 开发文档
|
|
2
|
+
|
|
3
|
+
实现要点与改这个仓库前必须知道的 DSH 行为。返回 [README](./README.md)。
|
|
4
|
+
|
|
5
|
+
## 实现要点
|
|
6
|
+
|
|
7
|
+
- **多 SDK**:品牌差异集中在 `src/brand.ts`(SDK 包、CLI 包、登录态目录、一键配置脚本、
|
|
8
|
+
登录区域),其余代码按 brand 参数化。CN Qoder SDK 静态引入;另两个 SDK 按需 `import()`,
|
|
9
|
+
没装时只有对应页面报错,插件照常加载。
|
|
10
|
+
- **品牌隔离**:各 provider 的 CLI 查找、模型目录缓存、会话池、账户读取、模型开关全部按 brand
|
|
11
|
+
分开。`QODERCLI_PATH` 若指向另一 Qoder 版本,对应版本会明确报错而不是借用那个 CLI 的账号。
|
|
12
|
+
- **CodeBuddy**:`src/codebuddy.ts` 自成一体会话(`unstable_v2_createSession` + 流式消息),
|
|
13
|
+
模型目录取自 `getAvailableModelsRaw()`,账户取自一次性 `query().accountInfo()`;登录走
|
|
14
|
+
`unstable_v2_authenticate`,`global`/`cn` 分别映射为 SDK 的 `external`/`internal`。
|
|
15
|
+
企业 `ioa`/`cloudhosted`/`selfhosted` 环境不暴露。SDK 自带 CLI,因此没有安装脚本。
|
|
16
|
+
登录点击会先 `unstable_v2_logout` 清掉该区域缓存的 token:SDK 的 `authenticate()` 发现
|
|
17
|
+
旧 token 时会静默返回、不回调 `onAuthUrl`,导致「切区域后点登录不弹浏览器」;清掉后
|
|
18
|
+
必定走完整浏览器授权。登录成功会关闭该区域所有热会话,避免继续复用旧凭据。
|
|
19
|
+
登录结果按区域写入 `~/.dsh/agent-sdk-bridge/codebuddy-state.json`(`src/codebuddy-state.ts`,
|
|
20
|
+
含账号、额度快照与 bearer token,权限 0600)。之后创建会话、读账号都用
|
|
21
|
+
`CODEBUDDY_AUTH_TOKEN` 环境变量把该区域的 token 注入 CLI,因此切区域和重启后恢复登录都
|
|
22
|
+
不需要再走浏览器;登出或配额 401 会清掉该区域的 token。无效 token 会让 CLI 以
|
|
23
|
+
`anonymous` 账号应答,`isUnauthenticatedAccount()` 将其判为未登录。未登录时
|
|
24
|
+
`listModels()` / `describeCatalog()` 直接返回空,`/models` 也不读取目录;账号读取与
|
|
25
|
+
会话创建都要求该区域有已保存的 token,绝不借用 CLI 里可能属于另一区域的单份登录。
|
|
26
|
+
切区域时页面先渲染本地快照,再用 `fresh=1` 在后台校验。
|
|
27
|
+
浏览器由 CLI 的登录流程自己打开;`onAuthUrl` 只记录 URL 供卡片显示「手动打开登录页」,
|
|
28
|
+
宿主不再调用系统打开方式,否则每次登录会出现两个相同标签页。
|
|
29
|
+
- **CodeBuddy 模型选择按区域**:`codebuddyGlobalDisabledModels` /
|
|
30
|
+
`codebuddyCnDisabledModels` 与 `codebuddyGlobalModelContextWindows` /
|
|
31
|
+
`codebuddyCnModelContextWindows` 是四个独立字段,`CodeBuddyAdapter` 按 region 读取,
|
|
32
|
+
模型页也按当前区域写入对应字段。`/models?brand=codebuddy®ion=cn|global` 显式选择区域,
|
|
33
|
+
页面切换下拉框时先画该区域的本地缓存表,再拉取;这样不依赖 `codebuddyRegion` 的写入提交
|
|
34
|
+
时序,也不会把另一区域的目录写进当前区域。
|
|
35
|
+
CLI 把「当前产品环境」记在自己的用户目录里,initialize 时才切换,而模型提供方在切换前
|
|
36
|
+
就已经选好了目录;两个区域共用 `~/.codebuddy` 时,换区后的读取会拿到上一个环境的列表,
|
|
37
|
+
再被缓存 5 分钟——模型列表、以及由它派生的开关状态都会串到另一个区域。
|
|
38
|
+
现在每个区域有独立的 `CODEBUDDY_CONFIG_DIR`
|
|
39
|
+
(`~/.dsh/agent-sdk-bridge/codebuddy-cli/global|cn`,见 `codeBuddyCliDir()`),环境因此
|
|
40
|
+
固定,进程启动后第一次读取就是本区域的目录。登录仍写用户自己的 CLI 目录,会话通过
|
|
41
|
+
`CODEBUDDY_AUTH_TOKEN` + 该目录启动。页面在切区域时用 `fresh=1` 绕开宿主缓存,并校验
|
|
42
|
+
`/models` 回显的 `region`。设置页的所有分支都渲染相同的 h2 / intro / 卡片前缀,避免切区时
|
|
43
|
+
卡片因子节点下标变化被重建、把下拉框弹回配置里的旧区域。
|
|
44
|
+
- **CodeBuddy 额度**:SDK 没有额度方法,`readQuotaWithToken()` 用登录 token 调
|
|
45
|
+
`POST /v2/billing/meter/get-user-resource`(国内与国际同协议),按积分包汇总实时余额;
|
|
46
|
+
额度读取优先用保存的 token,缺失时才静默 `authenticate`,不会拉起浏览器。
|
|
47
|
+
- **额度**:`QoderUsage` 起一个不跑模型轮次的短命 `query()`,调用 SDK 的 `getUsageInfo()`;
|
|
48
|
+
CLI 用自己的凭证查额度并返回与官方客户端一致的结构,插件只做展示与 1 分钟缓存。
|
|
49
|
+
- **版本开关**:`cnEnabled` / `intlEnabled` / `codebuddyEnabled` 是结构字段。宿主在
|
|
50
|
+
`loader/volatile-update` 时重新注册或释放对应 adapter 路由,并按启用状态重建 picker 目录;
|
|
51
|
+
浏览器半侧同步 `settings.section` 的注册与释放。关闭是「不存在」,不是「隐藏」。
|
|
52
|
+
- **快照优先**:设置页把上次成功的模型列表与额度写入 `localStorage`(同源、按版本分开),
|
|
53
|
+
首次渲染直接用快照,随后后台刷新并覆盖;读取失败时保留旧快照并标注。
|
|
54
|
+
- **warm 会话**:每个宿主 session id 对应一个常驻内层 `query()` 子进程,对话延续与工具轮次都
|
|
55
|
+
发生在会话内部,超出 `maxSessions` 按插入序 LRU 淘汰。
|
|
56
|
+
- **工具桥接**:宿主工具经进程内 MCP server 暴露给内层模型,qodercli 一次执行一个调用、宿主
|
|
57
|
+
一次回传整轮结果;配对状态(`ToolResultPairing`)由**会话**持有而不是轮次,因为 handler 可能在
|
|
58
|
+
它那一轮结束之后才触发。成对调用等待宿主的下一次请求并由该请求结算;只有未配上对的 handler
|
|
59
|
+
受 `toolResultTimeoutSeconds` 兜底。宿主**从未见过**的调用(工具块落在两次宿主请求之间被丢弃,
|
|
60
|
+
而 CLI 仍派发了 MCP 消息)不 park,立即返回取消结果——否则这一轮没人能解开。
|
|
61
|
+
- **旁路请求**:标题生成、压缩摘要走冷启动一次性调用,不占用 warm 会话。
|
|
62
|
+
- **真实计量**:CLI 默认把用量帧里的 token 计数清零,插件在启动子进程时带上它的
|
|
63
|
+
`EXPOSE_TOKEN_USAGE` 开关;总量、缓存命中与 tok/s 因此都是 provider 实测值,只有拿不到计量时才
|
|
64
|
+
按「context 比率 → 字符估算」兜底。占用样本只取自**每次请求结束**的那一帧(`requestUsageSample()`,
|
|
65
|
+
见 [常见问题](./FAQ.md)),内层整轮的合计值不参与上下文计算。
|
|
66
|
+
- **溢出可恢复**:内层上下文超限按 `CONTEXT_WINDOW_EXCEEDED` 上报,交给 harness 自动压缩,
|
|
67
|
+
而不是让整轮报废。
|
|
68
|
+
|
|
69
|
+
## 开发须知
|
|
70
|
+
|
|
71
|
+
改这个仓库前,有两点 DSH 行为必须先知道,否则会「毫无提示地坏掉」。
|
|
72
|
+
|
|
73
|
+
**1. 字段不 `.volatile()`,设置页就永远不出现。** DSH 用 `volatileForm(schema)` 构造表单,它
|
|
74
|
+
**只保留带 `meta.volatile` 的节点**;字段全是非 volatile 的 object 会塌缩成 `undefined`,
|
|
75
|
+
`describe()` 随即 `return []` 丢掉整个命名空间——插件照常加载、模型照常可用,但命名空间
|
|
76
|
+
**从未下发到客户端**。此外,DSH 的自动配置页渲染在「内置插件」分区内部,要独立顶层导航项就得
|
|
77
|
+
自带 `client.js` 注册 `settings.section`。
|
|
78
|
+
|
|
79
|
+
**2. `.volatile()` 的值必须在「用的时候」读,不能在挂载时读。** 一次只改 volatile 字段的写入,
|
|
80
|
+
loader 会把新值写进运行中插件**已经持有的那个 `Volatile` 引用**,然后**跳过重启**——`apply()`
|
|
81
|
+
不会再被调用(`cordis-plugin-loader` 的 `Entry.update` → `_commitVolatile`):
|
|
82
|
+
|
|
83
|
+
```js
|
|
84
|
+
const pending = volatileOnly && this._commitVolatile() ? [] : changes
|
|
85
|
+
if (!pending.length && !force) return // 不重启,不重新 apply
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
在 `apply()`(或构造函数)里把配置抄进自己的字段,就等于**永久冻结**。本插件的做法:
|
|
89
|
+
|
|
90
|
+
- [`src/live.ts`](./src/live.ts):`Live<T>`(值或 thunk)+ `readLive()`,选项既接受普通值,也
|
|
91
|
+
接受读取实时单元格的 thunk。
|
|
92
|
+
- [`src/config.ts`](./src/config.ts) 的 `liveConfig()`:每个字段返回 thunk,每次读取才从
|
|
93
|
+
`Volatile` 取值;`resolveConfig()` 在它之上实现,两者语义不会漂移。
|
|
94
|
+
- 适配器、会话池、模型目录一律按需读。`updateVolatile()` 只把新值写进**同一个**引用,所以
|
|
95
|
+
thunk 天然看到新值——不用重启,也不丢 warm 会话。
|
|
96
|
+
- 只有两个分组名(`displayName` / `intlDisplayName`)会被复制进选择器的分组目录,无法惰性化;
|
|
97
|
+
插件监听 `loader/volatile-update`,只在这些字段变化时用 `replace()` 就地重发。
|
|
98
|
+
|
|
99
|
+
[`test/live.test.ts`](./test/live.test.ts) 精确复现 loader 的就地提交并断言适配器**在不重新
|
|
100
|
+
`apply()` 的情况下**跟着变;用 0.5.0 的构建跑同一段代码会失败。
|
|
101
|
+
|
|
102
|
+
**本插件的读写链路。** 读走插件自建路由 `GET /api/llm-qoder-cn/models?brand=cn|global`(模型
|
|
103
|
+
目录来自 CLI,进不了配置表单);写走 `ctx.configForms`,与官方「模型」页共用带修订号的写入队列,
|
|
104
|
+
并发编辑会被拒绝而不是静默覆盖。宿主**提交完成后**才回应写入,页面因此先按新状态显示、随后核对,核对不
|
|
105
|
+
通过才报错;单次写入 20 秒未落定会放弃并解除控件禁用,避免一个卡住的调用锁死整页。
|
|
106
|
+
|
|
107
|
+
**构建与测试**
|
|
108
|
+
|
|
109
|
+
```sh
|
|
110
|
+
pnpm install # 首次会下载两个 SDK 的 CLI worker runtime
|
|
111
|
+
pnpm run build:clean # 清掉 lib/ 再构建;tsc 出 .d.ts,tsdown 出 lib/index.js
|
|
112
|
+
pnpm test # vitest
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
**别用 `pnpm build` 验证改动。** 它的命令是 `tsc && tsdown`:类型一错,`&&` 就短路,`tsdown`
|
|
116
|
+
根本不跑,于是 `lib/index.js` **保持旧内容**——而 `lib/` 才是 DSH 真正加载、npm 真正发布的东西。
|
|
117
|
+
如果只盯着源码或只跑测试,会误以为改动已生效。发布路径上的 `prepublishOnly` 用的是
|
|
118
|
+
`build:clean`(先删 `lib/` 再构建),所以类型错误会让发布失败而不是发出陈旧包。
|
|
119
|
+
|
|
120
|
+
注意 **`pnpm build` 与 `pnpm run build` 在 PowerShell 里可能给出不同的退出码**(前者经
|
|
121
|
+
`pnpm` 的内置脚本别名,后者经 `run`)。判断构建是否成功请直接看 `lib/index.js` 的时间戳,
|
|
122
|
+
或跑 `build:clean`——不要只信退出码。
|
package/FAQ.md
ADDED
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
# 常见问题
|
|
2
|
+
|
|
3
|
+
使用中遇到的问题与历史修复记录。返回 [README](./README.md)。
|
|
4
|
+
|
|
5
|
+
**国际版页面提示「QODERCLI_PATH 指向了另一版本的 CLI」?** 这是有意的隔离。部分 CN 安装会在
|
|
6
|
+
环境里设置 `QODERCLI_PATH`,而两个官方 SDK 都会在读取任何参数之前先看这个变量。如果放行,国际版
|
|
7
|
+
会话会启动 `qoderclicn`、拿 CN 账号作答——模型目录和额度都会串台。插件因此只在它不指向另一版本
|
|
8
|
+
时采用;国际版自己的覆盖变量是 `QODER_CLI_PATH`。要么装好 `qodercli`(插件会优先用它),要么把
|
|
9
|
+
该变量指向国际版 CLI。
|
|
10
|
+
|
|
11
|
+
**额度卡片显示「无法读取额度」?** 卡片里的文字就是原因:CLI 未安装 / 未登录 / 额度接口暂时
|
|
12
|
+
不可用。额度读取走的是 CLI 自己的凭证,所以先确认对应版本的 `status` 能列出用户名;点「刷新额度」
|
|
13
|
+
可重试。它失败不会影响模型列表和对话。
|
|
14
|
+
|
|
15
|
+
**CodeBuddy 页面显示「尚未登录」,但模型列表有内容?** 新版不会出现这种情况:未登录时页面只显示
|
|
16
|
+
登录卡片,模型目录根本不会被读取,模型选择器也不会列出 CodeBuddy 模型。请在页面顶部选择
|
|
17
|
+
「国际版」或「国内版」,点「登录」并在浏览器完成授权;登录成功后才会读取目录并显示账号与额度。
|
|
18
|
+
两个区域的账号与目录独立,各自的登录也会分别保留。
|
|
19
|
+
|
|
20
|
+
**切换国际版 / 国内版会卡很久吗?** 不会。下拉框会立即显示目标区域上次的账号、额度和模型表,
|
|
21
|
+
再在后台校验刷新;两个区域的登录凭据分别保存在 `~/.dsh/agent-sdk-bridge/codebuddy-state.json`
|
|
22
|
+
(文件权限 0600),切回已登录过的区域会直接恢复原账号,不需要重新走浏览器。该文件含明文
|
|
23
|
+
bearer token,只留在本机,请不要分享或提交到仓库。从旧版本升级后,旧版本没有保存 token,
|
|
24
|
+
需要给两个区域各登录一次,之后切换才会即时恢复。
|
|
25
|
+
|
|
26
|
+
**切换区域后模型开关和上下文窗口会串吗?** 不会。两边的模型目录不同,开关与窗口现在按区域
|
|
27
|
+
分别保存(`codebuddyGlobalDisabledModels` / `codebuddyCnDisabledModels` 与对应的窗口字段),
|
|
28
|
+
切回某个区域时会恢复该区域上次的选择。旧版本只有一个全局列表,升级后不再沿用;请在国内版和
|
|
29
|
+
国际版各设置一次,之后互不影响。
|
|
30
|
+
|
|
31
|
+
**切到国内版 / 国际版后,列表一开始还是另一个区域的?** 已修复。根因是 CodeBuddy CLI 把
|
|
32
|
+
「当前环境」记在共用的 `~/.codebuddy` 里,换区后的第一次目录读取会拿到上一个环境的列表,
|
|
33
|
+
插件又把它缓存了 5 分钟。现在国内版和国际版各用一套独立的 CLI 用户目录
|
|
34
|
+
(`~/.dsh/agent-sdk-bridge/codebuddy-cli/`),环境固定,启动后第一次读取就是自己的目录;
|
|
35
|
+
页面切区时也会强制重新读取并核对返回的区域。升级后请重启 DSH Web 并重新加载页面。
|
|
36
|
+
|
|
37
|
+
> 之前这个 bug 会把国际版的模型 ID 写进国内版的开关列表。升级后如果国内版的勾选看起来不对,
|
|
38
|
+
> 在**国内版**页面对应的模型设置里点一次「全不选」,再勾选你要用的模型即可;之后两个区域
|
|
39
|
+
> 互不影响。
|
|
40
|
+
|
|
41
|
+
**点了「登录」却没有弹出浏览器,或者弹出了两个?** CodeBuddy 的 CLI 在登录流程里会自己打开
|
|
42
|
+
浏览器,插件只把登录链接显示在卡片上作为兜底,不再额外打开,所以一次登录只会有一个标签页。
|
|
43
|
+
每次点击还会先清除该区域在 CLI 中缓存的旧凭据,再启动全新的授权流程;SDK 的 `authenticate()`
|
|
44
|
+
只要发现本地还有 token 就会静默返回、不发登录链接,先登出即可避免「点了没反应」。若浏览器
|
|
45
|
+
没有自动打开,点卡片里的「手动打开登录页」。
|
|
46
|
+
|
|
47
|
+
**CodeBuddy 额度从哪来?** 官方 SDK 没有额度方法,插件用登录后的 bearer token 调用 CodeBuddy
|
|
48
|
+
账号页同源的计费接口 `POST /v2/billing/meter/get-user-resource`,汇总各积分包的实时余额
|
|
49
|
+
(`CycleCapacityRemainPrecise`),并显示最近到期时间。该接口未公开、可能随上游变更;读取失败时
|
|
50
|
+
卡片会保留账号信息并显示原因,不影响对话。登录过期后重新登录即可;额度读取本身不会弹出浏览器。
|
|
51
|
+
|
|
52
|
+
**CodeBuddy 卡片上的「用量明细」打开什么?** 它会在新标签页打开当前登录区域的官网个人主页用量页
|
|
53
|
+
(国际版 `https://www.codebuddy.ai/profile/plans-usage`,国内版
|
|
54
|
+
`https://copilot.tencent.com/profile/plans-usage`),用浏览器里已有的官网登录态查看积分消耗明细。
|
|
55
|
+
|
|
56
|
+
**CodeBuddy 能用企业域名 / IOA 登录吗?** 不能。插件只暴露 `global`(codebuddy.ai)与 `cn`
|
|
57
|
+
(copilot.tencent.com)两种公共登录区域;SDK 里的 `ioa`、`cloudhosted`、`selfhosted` 需要企业
|
|
58
|
+
端点和额外凭据,不在本插件范围内。
|
|
59
|
+
|
|
60
|
+
**缓存命中一直显示 0%?** v1.0.5 已修。根因不在映射:CLI 每轮都算出了真实用量,但在把用量帧
|
|
61
|
+
送出来之前会**主动清零四个 token 计数**(`input_tokens` / `output_tokens` /
|
|
62
|
+
`cache_read_input_tokens` / `cache_creation_input_tokens`),只留 `credits` 与
|
|
63
|
+
`context_usage_ratio`;它自带一个开关(env 目录里的 `EXPOSE_TOKEN_USAGE`),打开后才原样送出。
|
|
64
|
+
[`src/cli.ts`](./src/cli.ts) 现在把这个开关随子进程环境一起交给 CLI——CN 包读
|
|
65
|
+
`QODERCN_EXPOSE_TOKEN_USAGE`,国际包读 `QODER_EXPOSE_TOKEN_USAGE`,两个都设,因为由哪个包应答
|
|
66
|
+
是查找决定的。
|
|
67
|
+
|
|
68
|
+
实测(本插件跑通,同一段前缀连续两轮):
|
|
69
|
+
|
|
70
|
+
| 轮 | CLI 报的 `input_tokens` | 其中 `cache_read` | 插件上报 | 界面 |
|
|
71
|
+
|---|---|---|---|---|
|
|
72
|
+
| 1 | 9 811 | 0 | 输入 9 811 / 输出 860 / 缓存 0 | 命中 0% |
|
|
73
|
+
| 2 | 10 686 | 9 805 | 输入 881 / 缓存读 9 805 / 输出 100 | 命中 92% |
|
|
74
|
+
|
|
75
|
+
第二轮那个 `input_tokens` 是**整个 prompt**(CLI 自己的 `context_usage_ratio` 就是
|
|
76
|
+
`input_tokens ÷ 窗口`),缓存的那部分含在里面,所以 [`meteredUsage()`](./src/session.ts) 把两个
|
|
77
|
+
cache 桶从 `inputTokens` 里减出去——DSH 的四个桶互不重叠,不减等于把缓存前缀算两遍。四个桶(含 0)
|
|
78
|
+
与 `totalTokens` 也必须齐全:harness 只在记账完整时展示每轮用量行,少一个桶又没有 `totalTokens`
|
|
79
|
+
佐证,整轮的用量详情都不显示。
|
|
80
|
+
|
|
81
|
+
**哪个用量帧能信?** CLI 会把用量记录挂在**好几个**帧上,
|
|
82
|
+
而只有一个是真的属于「这一次请求」:`message_delta`,即每次 provider 请求结束时发出的那一帧。
|
|
83
|
+
其余三个都是坑——`message_start` 与组装后的 `assistant` 消息里的四个计数**恒为 0**(请求没结束前
|
|
84
|
+
没有数);`result` 帧则是**内层整轮的总和**,把这个回合里每一次 provider 请求的用量全部相加。
|
|
85
|
+
|
|
86
|
+
一个宿主 step 只对应一次 provider 请求,但内层的一"轮"要等模型不再调用工具才结束——宿主工具每往返
|
|
87
|
+
一次就是一次新请求,全部发生在同一个内层回合里。所以 `result` 帧的数在长 agentic 运行后会是真实
|
|
88
|
+
prompt 的若干倍:实测一个让模型连调四次工具的回合,各请求分别用 608/705/771/837,`result` 帧报
|
|
89
|
+
**2 921**。若把这个数当成当前上下文,长跑结束后 DSH 的上下文计量会被顶到
|
|
90
|
+
`~9.8M / 1M`(100%)并一直挂着,直到下一次取样才回正(开发中确实这么踩过一次)。
|
|
91
|
+
|
|
92
|
+
现在占用样本只由 [`requestUsageSample()`](./src/session.ts) 提供:仅接受带真实计数(至少一个桶 > 0)
|
|
93
|
+
的 `stream_event` 帧,`assistant` 与 `result` 帧一律不采信。`contextUsageRatio` 仍是每请求的
|
|
94
|
+
prompt 比率,所以回退路径不受影响。
|
|
95
|
+
|
|
96
|
+
仍然退回估算的只有三种情况:CLI 版本早于这个开关、SDK 回退到进程内 worker transport(拿不到自定义
|
|
97
|
+
环境)、某一轮在结果帧之前就结束了。那时 `usage()` 按「真实用量帧 → CLI 的 context 比率 → 字符
|
|
98
|
+
估算」三级回退,上游一旦有数就立刻切过去。
|
|
99
|
+
|
|
100
|
+
**上下文占用是按什么算的?** 拿到真实计量时就是 provider 自己数的**最后一次请求**的 prompt:
|
|
101
|
+
`inputTokens + cacheRead + cacheWrite`,除以窗口。拿不到时,上游每帧仍带 `context_usage_ratio`
|
|
102
|
+
——它自己量出的「上下文用了多少」——本插件把它乘上窗口换成 token,再交给 DSH 的计量环。
|
|
103
|
+
|
|
104
|
+
这条回退路径上有个坑(v1.0.1 踩过、v1.0.2 修):**这个比率的分母是 CLI 实际运行的窗口,
|
|
105
|
+
不是你配置的窗口**。
|
|
106
|
+
CLI 只接受模型自己声明的窗口(见目录里的 `availableContextWindows`),配一个它不支持的窗口会被
|
|
107
|
+
**静默忽略**——例如给只支持 200K 的 `auto` 配 1M,CLI 仍按 200K 跑,若拿 1M 去乘就虚高 5 倍。
|
|
108
|
+
所以插件现在分两个窗口:给 DSH 的是你配置的值,给比率做分母的是 `cliContextWindow()`
|
|
109
|
+
(模型声明里匹配得上就用你的,匹配不上就用模型自己的)。同时窗口会经
|
|
110
|
+
`resolveModel.parameters.contextWindow` 真正下发给 CLI——在此之前它只告诉了 DSH,CLI 一直按默认
|
|
111
|
+
200K 跑,配了 1M 也白配。
|
|
112
|
+
|
|
113
|
+
比率本身是**可信的**:实测在 257/1007/2257 字符三档下,`比率 × 窗口` 与 CLI 自报的
|
|
114
|
+
`getContextUsage().usedPercentage` 在量化误差内一致,且随内容线性增长。注意 DSH 环上的总数
|
|
115
|
+
(`inputTokens + cacheRead + cacheWrite`)**包含 qodercli 自身的开销**——它自己的系统提示、skills
|
|
116
|
+
与工具定义,约 120–200 token。环里「系统提示词 / 工具定义 / 对话消息」三项是 DSH 自己按
|
|
117
|
+
`4 字符/token` 估的**本地分类**,合计会低于总数,这是正常的,不是虚高。
|
|
118
|
+
|
|
119
|
+
**tok/s 为什么偏低?** DSH 算 `tok/s = 输出 token ÷ 解码耗时`,而输出 token 由本插件上报。
|
|
120
|
+
v1.0.5 起这个数是 provider 自己数的 `output_tokens`(同一个计量开关),所以下面的估算修正只在拿不到
|
|
121
|
+
计量时生效——**凡是模型生成的内容都必须计入**,估算那一侧曾是两个原因,v1.0.3 与 v1.0.4 各修一个:
|
|
122
|
+
|
|
123
|
+
1. **换算率**(v1.0.3)。实测本后端的分词器:**中文 1.77 字符/token、英文 5.20 字符/token**,
|
|
124
|
+
而原先统一按 `4 字符/token` 估,中文因此被低估 **2.26 倍**。现在按字符集分别计价。
|
|
125
|
+
2. **工具调用参数**(v1.0.4)。原先只统计正文与思考,**工具调用的 name/arguments 一个字符都没算**,
|
|
126
|
+
而 agentic 回合里输出的大头正是它——实测一个三次工具调用的回合中占 **86%** 的字符。DSH 自己的
|
|
127
|
+
计量器是把工具调用计价为 `name + arguments` 的(`dsh-token-meter` 的 `estimateContent`),
|
|
128
|
+
漏掉它会让多步任务的 tok/s 低到十分之一量级。
|
|
129
|
+
|
|
130
|
+
实测效果:同一段中文回复 20.9 → 45.8 tok/s;一个工具调用回合 72.5 → 311.2 tok/s。
|
|
131
|
+
计数逻辑在 `src/tokens.ts` 的 `TurnOutputAccounting`,由 14 个单元测试钉住,其中一条专门断言
|
|
132
|
+
「工具参数必须计入」。
|
|
133
|
+
|
|
134
|
+
**设置点了没反应、一直「保存中」?** v0.6.0 已修。原因是 `.volatile()` 字段的改动**不会重启
|
|
135
|
+
插件**,而适配器在挂载时把配置抄进了自己的字段,于是永远按旧值作答——写入成功、磁盘正确、
|
|
136
|
+
插件读不到。详见 [开发须知](./DEVELOPMENT.md)。
|
|
137
|
+
|
|
138
|
+
**回答完模型的问题、或工具调用结束后,有时等好几秒才继续,有时干脆不再回复?** v1.0.6 已修。
|
|
139
|
+
根因是**工具结果的配对状态被当成了"每轮"的,而它其实是"每会话"的**。
|
|
140
|
+
|
|
141
|
+
qodercli 会用两个不同身份通知同一次工具调用:`canUseTool` 先拿到它自己的 `tool_use` id,而真正
|
|
142
|
+
需要宿主结果的那个 MCP `tools/call` handler **拿不到任何 id**。两者顺序一致,靠一个 FIFO 配对。
|
|
143
|
+
实测(真实 CLI,1.1.68)这个 handler 会在**它所属的那一轮已经结束之后**才触发——宿主一看到工具
|
|
144
|
+
调用块就立刻把结果交回来,而 CLI 过几毫秒才派发 MCP 消息:
|
|
145
|
+
|
|
146
|
+
```
|
|
147
|
+
6198ms [endTurn] kind=tool-calls
|
|
148
|
+
6198ms [host] 没有 parked handler -> 缓冲在 key=call_80d292a7…
|
|
149
|
+
6217ms [mcp handler] ENTER | shift 到 toolUseId=undefined
|
|
150
|
+
6217ms [mcp handler] PARK 在 key=anonymous-1
|
|
151
|
+
14226ms [mcp handler] TIMED OUT after 8009ms
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
而 `resetTurnState()` 恰恰在**每轮开始时**清空了那个 id 队列,于是把 handler 正要认领的 id 丢掉了:
|
|
155
|
+
handler 落到兜底键、park 满整个 `toolResultTimeoutSeconds`(默认 **120 秒**),宿主那条结果则永远
|
|
156
|
+
留在缓冲里没人读。**为什么是"有概率"**:宿主工具慢(`pwsh` 跑几秒)时 handler 在轮次结束前就
|
|
157
|
+
park 好了,走的是另一条路;工具快(`read`、`ask_user_question`)时才输掉这个竞态。所以"问模型
|
|
158
|
+
问题"和"工具刚结束"这两类操作最容易中招。而 120 秒远超人的耐心,表现就是"一直不回复",只能停掉
|
|
159
|
+
对话重发——重发后模型重新发一次调用,这次竞态恰好落在另一边,于是"好了",但修的是运气不是 bug。
|
|
160
|
+
|
|
161
|
+
现在配对状态由会话持有,只在**确实会取消派发**的地方丢弃:轮次被 abort / 失败时丢掉这一轮没能
|
|
162
|
+
认领的通知(否则会把下一轮的 handler 挤错一个位置),会话销毁时整体释放。逻辑抽成了
|
|
163
|
+
`ToolResultPairing`,由 7 条单元测试钉住;其中"快结果必须交给轮次结束后才到达的 handler"一条
|
|
164
|
+
是会分辨的那条——在它与 `claim` 之间插一次 `forgetUnclaimed()`(即旧 `resetTurnState()` 在轮次
|
|
165
|
+
边界做的事),它就会 park 满超时并拿到 `toolUseId=anonymous-1` 的取消文本,与线上实测的失败
|
|
166
|
+
形态逐字一致。
|
|
167
|
+
|
|
168
|
+
**同一个症状,换了一个原因?** v1.0.7 已修。v1.0.6 之后日志里仍能看到 120 秒超时,但这次不是配对
|
|
169
|
+
丢了,而是**超时用错了对象**。
|
|
170
|
+
|
|
171
|
+
宿主要等这一轮的**所有**工具执行完,才在下一次模型请求里一次性带回全部结果。所以只要有一个工具
|
|
172
|
+
跑得久(构建、目录扫描、自带 300 秒预算的 `pwsh`),同批里早已完成的调用也得一起等——它的结果
|
|
173
|
+
明明已经就绪,只等着随下一次请求送达。旧实现从 handler 进入时开始计 120 秒,到点就把这次调用当成
|
|
174
|
+
"宿主没回"取消掉:
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
10:07:53 [mcp handler] PARK call_00_QFqbaum… (write,结果其实立刻就有)
|
|
178
|
+
10:07:53 [host] pwsh 开始执行(自身预算 300 秒)
|
|
179
|
+
10:09:53 [mcp handler] TIMED OUT after 120s ← 把 write 误杀
|
|
180
|
+
10:10:38 [host] 第一次请求到达,带着全部三条结果
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
单工具同样会中:10-20 16:41 的一次 `pwsh` 超过 120 秒,16:43 被超时取消,而宿主当时还在执行它。
|
|
184
|
+
|
|
185
|
+
现在**成对调用不再有墙钟期限**:结果只可能随宿主的下一次请求到达,等多久取决于宿主工具,而不是
|
|
186
|
+
一个常数。真正能判定"这次调用没人会回答"的信号也正是那次请求本身——请求边界
|
|
187
|
+
(`beginHostRequest()`)会立即结算宿主没有带回结果的已 park 调用,并把尚未触发的通知标记为已作废
|
|
188
|
+
(handler 之后到达时直接拿到取消结果,而不是再 park 两分钟)。只有**完全没配上对**的 handler
|
|
189
|
+
(拿不到 `toolUseId`,无法把结果与调用对应)才继续用 `toolResultTimeoutSeconds` 兜底,默认仍是
|
|
190
|
+
120 秒。
|
|
191
|
+
|
|
192
|
+
**工具调用结束后整轮再也不回复?** v1.0.8 已修。v1.0.7 拿掉了成对调用的墙钟,但漏了一种**没人能
|
|
193
|
+
来救**的情况:请求边界只结算"它运行时已经 park 好"的 handler,而**边界之后**才到达的通知它管不
|
|
194
|
+
到——如果那次调用宿主压根没见过,就永远不会有人结算它,而唯一能结算它的下一次请求边界,偏偏要等
|
|
195
|
+
这一轮先结束,这一轮又正卡在这个 handler 上。
|
|
196
|
+
|
|
197
|
+
触发它的是一次**裸名工具调用**。内层模型偶尔不写限定名(`write` 而不是 `mcp__dsh-host__write`),
|
|
198
|
+
qodercli 自己解析不到,就地判错并**不等宿主**继续跑它自己的循环——内层循环因此比宿主的轮次边界跑
|
|
199
|
+
前面一轮;它随即带限定名重试,而重试的工具块落在**两次宿主请求之间的窗口**里,会话当时没有可投递
|
|
200
|
+
的宿主流,块被丢弃,宿主**从未见过这次调用**,但 CLI 照样把它派发给了 MCP handler:
|
|
201
|
+
|
|
202
|
+
```
|
|
203
|
+
22:38:49.444 [cli] 模型以裸名 write 调用 -> Error: Tool "write" not found(就地失败,不等宿主)
|
|
204
|
+
22:38:49.506 [host] 宿主照常执行 write,文件确实写出了;22:38:52.812 开下一轮
|
|
205
|
+
22:38:52.786 [cli] 带限定名重试的工具块到达 -> 此刻没有宿主流 -> 丢弃(宿主从未见到)
|
|
206
|
+
22:40:37.687 [mcp handler] PARK call_2b54e8a6… ← 没有任何请求会为它带回结果
|
|
207
|
+
22:48:24.594 [user] 点停止 -> CLI 取消挂起的工具调用,轮次才解开(实测静默 572 秒)
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
现在 `claim()` 在 park 之前先确认**这次调用宿主确实见过**(`hostVisible`:适配器真的把工具块投递
|
|
211
|
+
给宿主的那些 id)。宿主没见过的 id 立即拿到与请求边界相同的取消文本,不再空等;宿主见过的调用依旧
|
|
212
|
+
**没有墙钟**,`pwsh` 跑几分钟照样等它的真实结果。判别性的一条测试是「宿主从未见过的调用要立即失
|
|
213
|
+
败」——修复前它会 park 满 600 秒(测试超时失败),修复后立刻返回取消结果。
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 dsh-agent-sdk-bridge contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/LICENSE.original
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 dsh-llm-qodersdk contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/NOTICE
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# Notice / 致谢与出处
|
|
2
|
+
|
|
3
|
+
本仓库以 [MIT](./LICENSE) 许可发布。
|
|
4
|
+
|
|
5
|
+
## 上游项目
|
|
6
|
+
|
|
7
|
+
本插件是 **[JiamingZang/dsh-llm-qodersdk](https://github.com/JiamingZang/dsh-llm-qodersdk)**
|
|
8
|
+
(npm 包名 `@jiamingzang/dsh-llm-qoder`,MIT,版本 0.2.0)的衍生作品。
|
|
9
|
+
|
|
10
|
+
上游同样以 MIT 发布。MIT 允许使用、复制、修改、合并、发布、分发、再许可和销售副本,
|
|
11
|
+
唯一条件是**保留版权声明与许可声明**。本仓库据此:
|
|
12
|
+
|
|
13
|
+
- 完整保留上游 MIT 许可原文(见 `LICENSE.original`,即上游 `LICENSE` 的逐字副本);
|
|
14
|
+
- 在上方署名上游项目与作者;
|
|
15
|
+
- 以 MIT 继续发布本衍生作品。
|
|
16
|
+
|
|
17
|
+
MIT 不要求衍生作品沿用同一许可(无 copyleft 条款),但本项目选择继续使用 MIT,
|
|
18
|
+
以便与上游及 DSH 生态保持一致。
|
|
19
|
+
|
|
20
|
+
## 本仓库相对上游的改动
|
|
21
|
+
|
|
22
|
+
1. **同时接入两个官方 SDK**:上游只依赖 `@qoder-ai/qoder-agent-sdk`(国际版),其编译期品牌
|
|
23
|
+
硬编码为 `global`(`cliCommands: qodercli/qoder`、配置目录 `.qoder`、
|
|
24
|
+
`QODER_PERSONAL_ACCESS_TOKEN`),在只装了 `qoderclicn` 的机器上无法工作。本项目最初改用
|
|
25
|
+
官方 **CN** 包 `@qodercn-ai/qodercn-agent-sdk`(`brand: cn`、`cliCommands: qoderclicn/qodercn`、
|
|
26
|
+
配置目录 `.qoder-cn`、`QODERCN_*`);v1.1.0 起把国际版包也装了回来,作为**另一个独立
|
|
27
|
+
adapter** 与 CN 并行工作,而不是二选一。品牌差异集中在 `src/brand.ts`,其余代码按 brand
|
|
28
|
+
参数化。两个包的公开 API 一致,故共用同一套会话、目录与额度代码。
|
|
29
|
+
2. **三个 provider id**:注册 `qoder-cn`、`qoder-intl` 与 `codebuddy` 三条路由(上游为 `qoder`,
|
|
30
|
+
另有 `qoder-byok` 承载账号自己添加的自带 Key 模型)。本项目用不到那批自定义模型——DSH 只走
|
|
31
|
+
订阅自己的目录——因此在目录层丢弃上游标记为 `user`/`custom` 的条目。id 与上游不同,可在同一
|
|
32
|
+
profile 中共存而不冲突。
|
|
33
|
+
3. **可配置设置面**:新增 `src/config.ts`,声明带中文说明的配置项(CN 与国际版各一套模型开关 /
|
|
34
|
+
窗口 / 别名)。设置页由本插件
|
|
35
|
+
自带的 `client.js` 注册为**独立顶层导航项**(`settings.section`)——DSH 的自动配置页渲染在
|
|
36
|
+
「内置插件」分区内部,要独立入口就得自带浏览器半侧。两个前提缺一不可:每个字段必须
|
|
37
|
+
`.volatile()`(`volatileForm` 只保留 volatile 节点,否则整个命名空间不会下发到客户端),
|
|
38
|
+
且每个字段必须在**使用处**读取(见第 8 条)。上游仅暴露 `maxSessions` 与
|
|
39
|
+
`modelCacheTtlSeconds` 两项且未提供界面。
|
|
40
|
+
4. **上下文窗口按模型可选**:新增 `modelContextWindows`(Qoder 模型 id → token 数)。设置页
|
|
41
|
+
为每个模型提供下拉,列出上游为该模型声明的全部窗口(如 200K / 400K / 1M),默认档跟随
|
|
42
|
+
上游声明的**会话窗口**;上游固定使用 `defaultContextWindow`(通常 200K)。注意
|
|
43
|
+
`maxInputTokens` 不是替代品——它是单次请求的上限,常低于会话窗口。选大窗口会推迟
|
|
44
|
+
harness 的自动压缩阈值,取舍写在 `pickContextWindow` 的注释里。
|
|
45
|
+
5. **模型过滤与别名**:新增 `disabledModels` 拒绝清单与 `modelAliases` 别名映射。用拒绝清单
|
|
46
|
+
而非允许清单,是因为账号目录会变——允许清单会把上游后来新增的模型静默藏掉。
|
|
47
|
+
6. **超时可调**:`toolResultTimeoutSeconds`、`catalogFetchTimeoutSeconds`、
|
|
48
|
+
`abortGraceSeconds`、`coldMaxTurns` 由硬编码常量改为配置项。
|
|
49
|
+
7. **删除上游死代码**:上游 `render.ts` 导出了 `renderIdentityAppend`(一段指示内层模型否认
|
|
50
|
+
自身来源、自称宿主 Agent 的身份提示),但全仓库无调用点,构建产物中亦不存在(被
|
|
51
|
+
tree-shaking 移除)。本项目一度将其接入配置项 `identityOverride`,现已连同该配置项一并删除:
|
|
52
|
+
让助手否认自己的来源并不是本插件该做的产品决策,隐藏身份本身也没有必要。
|
|
53
|
+
8. **设置改动即时生效**:DSH 对「只改 volatile 字段」的写入**不重启插件**,而是把新值就地写进
|
|
54
|
+
运行中插件**已经持有的那个** `Volatile` 引用(`cordis-plugin-loader` 的 `Entry.update` →
|
|
55
|
+
`_commitVolatile`),`apply()` 不会再被调用。上游和本仓库 0.6.0 之前都在挂载时把配置抄进
|
|
56
|
+
自己的字段,于是设置页写成功、`cordis.patch.yml` 落盘也正确,插件却一直按挂载时的值作答
|
|
57
|
+
(表现为「点了没反应」)。本仓库改为全部按需读取(`src/live.ts` 的 `Live<T>` 与
|
|
58
|
+
`liveConfig()`),只对决定选择器分组名的 `displayName` 监听 `loader/volatile-update` 就地重发。
|
|
59
|
+
|
|
60
|
+
9. **一键配置 CLI(仅 Windows)**:随包发布 `scripts/setup-qoderclicn.bat` 与
|
|
61
|
+
`scripts/setup-qodercli.bat`——检查 node/npm、缺就 `npm install -g` 对应包、未登录就
|
|
62
|
+
`login`、最后校验版本 / 登录态 / 凭证目录 / 模型数量。设置页底部的分组通过
|
|
63
|
+
`POST /api/llm-qoder-cn/setup`(body 带 `brand`)让宿主
|
|
64
|
+
进程代跑它并实时回传输出(浏览器无法启动本地进程):面板只跟着这一次运行走,脚本结束 1 秒就
|
|
65
|
+
自动收起,需要再看用「查看输出」展开;模型列表为空时页面直接红字引导点一键配置。mode 只有两
|
|
66
|
+
个键的白名单,各自映射到一个字面 flag——`configure` → `--gui`(装 + 登录 + 校验),`login` →
|
|
67
|
+
`--login`(只重跑浏览器授权,用于换账号;`--check` 留给手动体检,界面不暴露);脚本路径来自包
|
|
68
|
+
自身布局,同一时刻只允许一个运行,插件卸载时杀掉未结束的子进程。批次文件有两个硬约束:
|
|
69
|
+
必须 CRLF(`cmd.exe` 解析不了 LF-only,故 `.gitattributes` 为 `*.bat` 单独设了
|
|
70
|
+
`eol=crlf`),且必须纯 ASCII——实测在**没有控制台**的方式下调用(`windowsHide` + 管道,
|
|
71
|
+
正是插件的调用方式)时,`cmd.exe` 会在含多字节字符的行上算错文件位置,把半行当命令执行;
|
|
72
|
+
同一份文件在真实控制台里则正常。上游与本仓库此前都不涉及本地进程执行。
|
|
73
|
+
|
|
74
|
+
10. **CodeBuddy 接入**:新增 `@tencent-ai/agent-sdk` 依赖与 `src/codebuddy*.ts`。该 SDK 随包
|
|
75
|
+
自带 CodeBuddy CLI,因此没有安装脚本;登录用 SDK 的 `unstable_v2_authenticate`,只暴露公共的
|
|
76
|
+
国际版(`external`)与国内版(`internal`)两种区域,企业 `ioa` / `cloudhosted` / `selfhosted`
|
|
77
|
+
不在范围内。模型目录取自 `getAvailableModelsRaw()`,账户取自一次性 `query().accountInfo()`;
|
|
78
|
+
额度走 CodeBuddy 账号页使用的计费接口 `POST /v2/billing/meter/get-user-resource`,按积分包
|
|
79
|
+
汇总实时余额(`CycleCapacity*Precise`),不使用口径过时的 `TotalDosage`。该接口未公开,
|
|
80
|
+
随上游变更可能失效;token 只保存在内存中,不写入配置或磁盘。
|
|
81
|
+
|
|
82
|
+
## 上游的原始文件
|
|
83
|
+
|
|
84
|
+
上游 `LICENSE` 的逐字副本保留在 [`LICENSE.original`](./LICENSE.original),以满足
|
|
85
|
+
MIT 的版权声明保留要求。
|
|
86
|
+
|
|
87
|
+
## 商标与免责声明
|
|
88
|
+
|
|
89
|
+
Qoder、Qoder CN、DeepSeek、DeepSeek Harness 等名称与商标归各自权利人所有,
|
|
90
|
+
此处仅作兼容性描述之用。本项目与 Qoder(通义云启)、DeepSeek 官方均无关联,
|
|
91
|
+
是非官方社区适配器。
|
|
92
|
+
|
|
93
|
+
**使用风险自负。** 本插件通过官方 Agent SDK 复用本机 `qoderclicn` / `qodercli`
|
|
94
|
+
登录态,不逆向协议、不伪造客户端身份、不自动化领取签到积分;额度只读展示,不发起任何
|
|
95
|
+
兑换或领取请求。但"以订阅额度驱动第三方宿主"是否符合你的 Qoder 服务条款,由你自行
|
|
96
|
+
判断。详见 README 的「合规与风险」一节。
|
package/README.md
CHANGED
|
@@ -1,3 +1,132 @@
|
|
|
1
|
-
#
|
|
1
|
+
# dsh-agent-sdk-bridge
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
把 **Qoder CN**、**Qoder 国际版**与 **CodeBuddy** 订阅接入
|
|
4
|
+
[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(DSH)的 LLM 适配器插件。
|
|
5
|
+
|
|
6
|
+
> 本仓库是 [dsh-qoder-link](https://github.com/k1-h2/dsh-qoder-link) 插件的后续维护地址;除 Qoder 外,同仓库还接入了腾讯 CodeBuddy。
|
|
7
|
+
|
|
8
|
+
- **官方 SDK**:Qoder 用 [`@qodercn-ai/qodercn-agent-sdk`](https://www.npmjs.com/package/@qodercn-ai/qodercn-agent-sdk)
|
|
9
|
+
与 [`@qoder-ai/qoder-agent-sdk`](https://www.npmjs.com/package/@qoder-ai/qoder-agent-sdk);
|
|
10
|
+
CodeBuddy 用 [`@tencent-ai/agent-sdk`](https://www.npmjs.com/package/@tencent-ai/agent-sdk)。
|
|
11
|
+
- **零凭据**:复用本机 CLI 登录态,不需要 API key。
|
|
12
|
+
- **额度可见**:Qoder 显示套餐、已用百分比、剩余 credits、加量包与到期时间;CodeBuddy 通过其
|
|
13
|
+
计费接口显示积分余额与各积分包(与官方账号页同源),卡片上的「用量明细」可直接打开当前区域
|
|
14
|
+
官网的用量页。
|
|
15
|
+
- **三套设置页**:Qoder CN / Qoder 国际版 / CodeBuddy,各自独立的模型开关、上下文窗口与登录面板。
|
|
16
|
+
|
|
17
|
+
## 为什么需要它
|
|
18
|
+
|
|
19
|
+
Qoder 两家发行版各有一个官方 SDK,品牌在编译期写死,一个包只能服务一边:CN 包找不到国际版的
|
|
20
|
+
登录态,国际版包也找不到 CN 的。上游插件只依赖国际版包,在只装了 `qoderclicn` 的机器上模型
|
|
21
|
+
列表永远为空。
|
|
22
|
+
|
|
23
|
+
CodeBuddy 的官方 SDK 则自带 CLI,但同样需要按账号登录。本插件把三种接入放进同一个 provider
|
|
24
|
+
层:各装各的 SDK、各起各的会话,账号、模型目录与登录态互不串台。
|
|
25
|
+
|
|
26
|
+
## 安装
|
|
27
|
+
|
|
28
|
+
### 1. 装插件
|
|
29
|
+
|
|
30
|
+
**插件 → 添加插件**,填 `dsh-agent-sdk-bridge` 并安装(npm);也可用
|
|
31
|
+
`github:k1-h2/dsh-agent-sdk-bridge` 或本地目录。
|
|
32
|
+
|
|
33
|
+
若提示**「需要允许安装脚本」**(SDK 下载自己的 worker runtime),点「允许这些脚本并重试」即可;
|
|
34
|
+
不授权也能用,SDK 会回退到 PATH 上的系统 CLI。装完按提示**重启 DSH**。
|
|
35
|
+
|
|
36
|
+
### 2. 登录
|
|
37
|
+
|
|
38
|
+
插件不持有凭据,内层会话直接复用对应 CLI 的登录态:
|
|
39
|
+
|
|
40
|
+
| 版本 | npm 包 | 登录方式 | 登录态目录 |
|
|
41
|
+
|---|---|---|---|
|
|
42
|
+
| Qoder CN | `@qodercn-ai/qoderclicn` | 页面「一键配置」或 `qoderclicn login` | `~/.qoder-cn/.auth` |
|
|
43
|
+
| Qoder 国际版 | `@qoder-ai/qodercli` | 页面「一键配置」或 `qodercli login` | `~/.qoder/.auth` |
|
|
44
|
+
| CodeBuddy | `@tencent-ai/agent-sdk`(已随插件安装) | 页面选择区域后点「登录」 | 由 CodeBuddy CLI 管理 |
|
|
45
|
+
|
|
46
|
+
**设置 → Qoder CN / Qoder 国际版** → 页面底部「一键配置」:缺 CLI 就装,未登录就拉起浏览器授权,
|
|
47
|
+
输出实时显示。**设置 → CodeBuddy** → 顶部选择「国际版(codebuddy.ai)」或「国内版
|
|
48
|
+
(copilot.tencent.com)」,点「登录」后在浏览器完成授权。两个区域的登录凭据分别保存在本机
|
|
49
|
+
(`~/.dsh/agent-sdk-bridge/codebuddy-state.json`,权限 0600),切换区域会立即恢复对应账号的
|
|
50
|
+
账号、额度与模型表,各自启用哪些模型和上下文窗口也按区域独立保存;未登录时不会读取或显示
|
|
51
|
+
模型目录。浏览器由 CodeBuddy CLI 打开,插件不再重复打开。企业域名 / IOA 登录不在支持范围内。
|
|
52
|
+
|
|
53
|
+
也可以手动执行 Qoder 的两步:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
npm install -g @qodercn-ai/qoderclicn && qoderclicn login # Qoder CN
|
|
57
|
+
npm install -g @qoder-ai/qodercli && qodercli login # 国际版
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
`qoderclicn status` / `qodercli status` 能列出 `Username` 即登录成功。Qoder 的一键配置只支持 Windows。
|
|
61
|
+
|
|
62
|
+
> `QODERCLI_PATH` 若指向另一版本的 CLI,对应版本会明确报错,而不是借用那个账号回答。国际版
|
|
63
|
+
> 专用覆盖变量是 `QODER_CLI_PATH`。更多见 [常见问题](./FAQ.md)。
|
|
64
|
+
|
|
65
|
+
## 设置页
|
|
66
|
+
|
|
67
|
+
**设置 → Qoder CN**、**设置 → Qoder 国际版**、**设置 → CodeBuddy** 是三个独立入口:
|
|
68
|
+
|
|
69
|
+
- **额度 / 登录卡片**:Qoder 显示套餐、已用百分比进度、套餐 / 加量包 / 组织资源包剩余量、到期时间,
|
|
70
|
+
以及官方用量与升级链接;CodeBuddy 显示登录区域、账号、积分余额、已用百分比、各积分包与最近到期
|
|
71
|
+
(通过其账号页使用的计费接口读取)。
|
|
72
|
+
- **模型清单**:来自账号实时目录,逐个启用 / 关闭、指定上下文窗口;倍率取自上游报价。
|
|
73
|
+
- **高级设置**:并发会话数、目录缓存、超时、默认思考档位、模型别名、分组名称等,可折叠。
|
|
74
|
+
- **CLI 分组**:Qoder 页面有一键配置 / 重新登录 / 卸载 CLI(卸载前确认,保留登录凭证),附实时输出。
|
|
75
|
+
- 再次打开页面时**先显示上次快照**,模型与账户在后台更新,不再每次都停在「正在读取」。
|
|
76
|
+
|
|
77
|
+
每个 provider 只注册一条路由(`qoder-cn` / `qoder-intl` / `codebuddy`),只服务订阅自带的模型;
|
|
78
|
+
BYOK 自定义模型会被过滤掉。
|
|
79
|
+
|
|
80
|
+
三个入口是否出现,在**插件 → Agent SDK Bridge → 启用的版本**里控制。关闭后对应的设置页、模型
|
|
81
|
+
列表、选择器分组与 provider 路由一起移除;已保存的模型选择保留,重新打开即可恢复。
|
|
82
|
+
|
|
83
|
+
## 用 YAML 配置
|
|
84
|
+
|
|
85
|
+
设置页之外,也可以直接写进 profile 的 `cordis.patch.yml`:
|
|
86
|
+
|
|
87
|
+
```yaml
|
|
88
|
+
- id: llm-qoder-cn
|
|
89
|
+
name: dsh-agent-sdk-bridge
|
|
90
|
+
config:
|
|
91
|
+
cnEnabled: true
|
|
92
|
+
intlEnabled: false # 关闭国际版:设置页与模型分组一起移除
|
|
93
|
+
displayName: Qoder CN (工作号)
|
|
94
|
+
intlDisplayName: Qoder (Global)
|
|
95
|
+
maxSessions: 4
|
|
96
|
+
disabledModels: [mmodel] # CN:关闭的模型
|
|
97
|
+
modelContextWindows:
|
|
98
|
+
qmodel_38max: 1000000 # CN:按模型指定窗口(token)
|
|
99
|
+
intlDisabledModels: [auto] # 国际版:独立的关闭清单
|
|
100
|
+
intlModelContextWindows:
|
|
101
|
+
dmodel: 1000000
|
|
102
|
+
intlModelAliases:
|
|
103
|
+
claude-sonnet: dmodel
|
|
104
|
+
codebuddyRegion: cn # global(国际版)或 cn(国内版)
|
|
105
|
+
codebuddyDisplayName: CodeBuddy
|
|
106
|
+
codebuddyDisabledModels: [glm-5.2]
|
|
107
|
+
codebuddyModelContextWindows:
|
|
108
|
+
glm-5.3: 1000000
|
|
109
|
+
codebuddyModelAliases:
|
|
110
|
+
cb-fast: fast-model
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
各个 provider 的模型开关、窗口和别名是**分开的字段**;并发会话数、超时、思考档位等运行参数共享。
|
|
114
|
+
|
|
115
|
+
## 更多
|
|
116
|
+
|
|
117
|
+
- 问题排查与历史修复记录:[常见问题](./FAQ.md)
|
|
118
|
+
- 实现要点、开发须知与构建说明:[开发文档](./DEVELOPMENT.md)
|
|
119
|
+
|
|
120
|
+
## 合规与风险
|
|
121
|
+
|
|
122
|
+
本插件通过官方 Agent SDK 复用**你自己**的 Qoder / CodeBuddy 账号登录态:不逆向私有协议、
|
|
123
|
+
不伪造客户端身份或请求头、不自动化领取签到积分,也不向任何第三方域名发送数据。
|
|
124
|
+
|
|
125
|
+
但请自行判断:「以订阅额度驱动第三方宿主」是否符合对应服务的条款,本项目无法替你解释,
|
|
126
|
+
也不保证账号不被限制;上游接口与 SDK 可能变更,届时插件可能失效。请仅用于你自己的账号。
|
|
127
|
+
|
|
128
|
+
## 许可
|
|
129
|
+
|
|
130
|
+
MIT。本仓库是 [JiamingZang/dsh-llm-qodersdk](https://github.com/JiamingZang/dsh-llm-qodersdk)
|
|
131
|
+
(MIT)的衍生作品,上游许可与版权声明保留在 [`LICENSE.original`](./LICENSE.original),出处与
|
|
132
|
+
改动清单见 [`NOTICE`](./NOTICE)。
|