@ktkid/kmh-codex-cli 0.0.0-stage → 0.1.1

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.
Files changed (87) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +295 -2
  3. package/bin/README.md +25 -0
  4. package/bin/codex +36 -0
  5. package/bin/runtime-receipt.json +9 -0
  6. package/bin/version +1 -0
  7. package/cordis.patch.yml +7 -0
  8. package/lib/browser-types/src/account-status.d.ts +9 -0
  9. package/lib/browser-types/src/client/ComposerQuota.d.ts +10 -0
  10. package/lib/browser-types/src/client/DetailCard.d.ts +12 -0
  11. package/lib/browser-types/src/client/LiveBall.d.ts +19 -0
  12. package/lib/browser-types/src/client/QuotaCard.d.ts +20 -0
  13. package/lib/browser-types/src/client/QuotaDisplaySettings.d.ts +6 -0
  14. package/lib/browser-types/src/client/index.d.ts +18 -0
  15. package/lib/browser-types/src/client/locales.d.ts +54 -0
  16. package/lib/browser-types/src/client/quota-store.d.ts +56 -0
  17. package/lib/browser-types/src/live-state.d.ts +31 -0
  18. package/lib/browser-types/src/quota-protocol.d.ts +135 -0
  19. package/lib/browser-types/src/quota-rules.d.ts +18 -0
  20. package/lib/browser-types/src/tool-switches.d.ts +63 -0
  21. package/lib/client.js +21396 -0
  22. package/lib/src/account-status.d.ts +9 -0
  23. package/lib/src/account-status.js +1 -0
  24. package/lib/src/account.d.ts +35 -0
  25. package/lib/src/account.js +173 -0
  26. package/lib/src/adapter.d.ts +22 -0
  27. package/lib/src/adapter.js +221 -0
  28. package/lib/src/approval.d.ts +48 -0
  29. package/lib/src/approval.js +235 -0
  30. package/lib/src/capabilities.d.ts +40 -0
  31. package/lib/src/capabilities.js +85 -0
  32. package/lib/src/config.d.ts +69 -0
  33. package/lib/src/config.js +75 -0
  34. package/lib/src/connection.d.ts +65 -0
  35. package/lib/src/connection.js +178 -0
  36. package/lib/src/cursor.d.ts +54 -0
  37. package/lib/src/cursor.js +325 -0
  38. package/lib/src/image-delivery.d.ts +36 -0
  39. package/lib/src/image-delivery.js +65 -0
  40. package/lib/src/imagegen.d.ts +21 -0
  41. package/lib/src/imagegen.js +132 -0
  42. package/lib/src/index.d.ts +141 -0
  43. package/lib/src/index.js +534 -0
  44. package/lib/src/isolation.d.ts +61 -0
  45. package/lib/src/isolation.js +298 -0
  46. package/lib/src/live-state.d.ts +31 -0
  47. package/lib/src/live-state.js +14 -0
  48. package/lib/src/models.d.ts +24 -0
  49. package/lib/src/models.js +98 -0
  50. package/lib/src/native-items.d.ts +59 -0
  51. package/lib/src/native-items.js +122 -0
  52. package/lib/src/native-tools/catalog.d.ts +29 -0
  53. package/lib/src/native-tools/catalog.js +197 -0
  54. package/lib/src/probe.d.ts +17 -0
  55. package/lib/src/probe.js +54 -0
  56. package/lib/src/protocol.d.ts +508 -0
  57. package/lib/src/protocol.js +511 -0
  58. package/lib/src/quota-protocol.d.ts +135 -0
  59. package/lib/src/quota-protocol.js +97 -0
  60. package/lib/src/quota-rules.d.ts +18 -0
  61. package/lib/src/quota-rules.js +49 -0
  62. package/lib/src/quota.d.ts +32 -0
  63. package/lib/src/quota.js +227 -0
  64. package/lib/src/session-store.d.ts +592 -0
  65. package/lib/src/session-store.js +275 -0
  66. package/lib/src/status.d.ts +19 -0
  67. package/lib/src/status.js +69 -0
  68. package/lib/src/tool-policy.d.ts +47 -0
  69. package/lib/src/tool-policy.js +454 -0
  70. package/lib/src/tool-registry.d.ts +42 -0
  71. package/lib/src/tool-registry.js +70 -0
  72. package/lib/src/tool-selection.d.ts +88 -0
  73. package/lib/src/tool-selection.js +60 -0
  74. package/lib/src/tool-switches-service.d.ts +24 -0
  75. package/lib/src/tool-switches-service.js +129 -0
  76. package/lib/src/tool-switches.d.ts +63 -0
  77. package/lib/src/tool-switches.js +43 -0
  78. package/lib/src/turn.d.ts +200 -0
  79. package/lib/src/turn.js +1012 -0
  80. package/lib/src/web.d.ts +9 -0
  81. package/lib/src/web.js +143 -0
  82. package/package.json +171 -4
  83. package/vendor/codex/LICENSE +201 -0
  84. package/vendor/codex/NOTICE +4 -0
  85. package/vendor/codex/models.json +1613 -0
  86. package/vendor/native-tools/0.162.0-alpha.17.2.json +143 -0
  87. package/vendor/native-tools/0.163.0-alpha.10.2.json +128 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 KtKID
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/README.md CHANGED
@@ -1,3 +1,296 @@
1
- # Temporary Holding Version
1
+ ---
2
+ description: 在 KMH 使用本机官方 Codex CLI 登录的模型:挂载配置、隔离开关、原生工具审批与逐项选择、生图展示、token 用量与会话连接状态小球,以及差分续聊与故障排查入口。
3
+ ---
2
4
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
5
+ # @ktkid/kmh-codex-cli
6
+
7
+ 本 npm 包使用 macOS arm64 的官方 Codex CLI 固定版依赖。插件沿用本机现有的 Codex 登录。
8
+
9
+ ## 概述
10
+
11
+ 在 KMH 里使用本机官方 Codex CLI 的模型对话:KMH 保留系统提示、工具权限与回合控制,Codex 承担模型推理与原生历史管理。工具以动态工具回调交回 KMH 执行;创建 KMH 会话时固定工具选择,后续回合恢复同一 Codex 会话和原工具,Codex 续用自己的历史。
12
+
13
+ 选择本包的代价与边界:共享用户 `~/.codex`(登录、配置、原生会话记录都在那边),用户配置的 MCP 设备对模型可见;一切隔离经进程 `-c` 参数注入,仅影响单次调用,不修改任何 Codex 配置文件。
14
+
15
+ ## 目录
16
+
17
+ - [使用本包](#use-this-package)
18
+ - [理解实现](#understand-the-implementation)
19
+ - [验证插件](#verify-the-plugin)
20
+ - [进一步探索](#further-exploration)
21
+ - [模型体验](#model-experience)
22
+ - [已知限制与延期工作](#known-limitations-and-deferred-work)
23
+ - [开发备注](#dev-note)
24
+
25
+ ---
26
+
27
+ <a id="use-this-package"></a>
28
+
29
+ ## 使用本包
30
+
31
+ ### 何时选择
32
+
33
+ 需要用已在本机 Codex 登录的 OpenAI 模型(gpt-6 系列等)且保持 KMH 主控时选择本包。模型凭据走 DeepSeek 官方 API 时改用上游 llm provider;需要 ZCode 侧模型时改用 `@kmh/zcode-cli`。
34
+
35
+ ### 工具选择
36
+
37
+ 工具选择由本包自行管理:profile Config 的 `toolSelection` 记录 KMH(harness)与原生(native)两列的逐项开关;本包读取该配置,在拉起官方 CLI 时只把选中的 KMH 工具交给 Codex,原生工具按选择经 `-c` 隔离参数注入。Codex 详情卡片当前展示原生技能开关并写回 `/api/codex-cli/config`;完整开关清单的可视化由独立的 `cli-tools-selector` 插件提供(优先适配本包),为后续工作。KMH 工具按名称识别:公开工具注册表不暴露插件来源,新写入的 harness 行 `source` 固定为 `harness`,旧配置中的其他来源 id 按名称回退匹配。
38
+
39
+ 首次使用会把已有 `codex-settings.json` 粗粒度工具选择导入 profile Config;原生技能保留原来的独立设置。配置中未出现的 KMH 工具默认开启(导入只覆盖当时可见的工具,缺行不关掉既有工具),未出现的原生工具默认关闭。工具开关仅对普通新建会话生效,已有会话保留创建时选择。准备失败或版本冲突明确报错;修正运行条件后可重试原会话,调整工具选择后普通新建会话。
40
+
41
+ ### 配置
42
+
43
+ 默认使用插件 [bin 目录中的固定官方 CLI](bin/README.md),每次启动精确核对完整版本号;当前部署版本为 `0.163.0-alpha.10.2`,平台为 macOS arm64。程序与配套资源由插件目录持有,现有 Codex 登录、配置与原生会话目录继续沿用。
44
+
45
+ 在 `profiles/<name>/cordis.patch.yml` 挂载(kmh-web 已内置):
46
+
47
+ ```yaml
48
+ - id: kmh-codex-cli
49
+ name: "@ktkid/kmh-codex-cli"
50
+ config:
51
+ # 默认使用插件自带启动器;显式 command 可指定其他经过验证的程序。
52
+ cwd: !!js process.cwd()
53
+ dataDir: !!js dshHomePath('codex-cli')
54
+ ```
55
+
56
+ | 配置键 | 默认值 | 含义 |
57
+ | ------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------- |
58
+ | `command` | `codex` | 官方 CLI 可执行文件;损坏或不在 PATH 时写绝对路径 |
59
+ | `cwd` | 必填 | 无会话身份时子进程的工作目录;会话请求跟随会话自身目录 |
60
+ | `dataDir` | 必填 | 绑定记录与裁剪目录的数据目录 |
61
+ | `model` | `""` | 空=模型目录首选;非空固定为该模型 |
62
+ | `nativeToolsEnabled` | `false` | 旧总开关:首次迁移的默认值;逐项选择以 profile Config 的 `toolSelection` 为准 |
63
+ | `toolSelection` | 首次导入 | `version: 1` 与 `harness`、`native` 选择数组;每项包含 `source`、`name`、`enabled`,由 Settings 写入 profile 的 `cordis.patch.yml` |
64
+ | `defaultMaxTokens` | `1000000` | 会话默认输出上限 |
65
+ | `reasoningSummary` | `auto` | 官方思考摘要模式:auto、concise、detailed、none;none 关闭可见摘要请求 |
66
+ | `startupTimeoutMs` | `20000` | 启动与 initialize 握手时限 |
67
+ | `requestTimeoutMs` | `360000` | 单次生成总时限,包含排队、启动与官方重试;主对话、标题及压缩评估共用此限制,收尾另有时限 |
68
+ | `cancelReceiptTimeoutMs` | `5000` | 停止后等待 interrupted 终止通知的时限 |
69
+ | `cleanupTimeoutMs` | `5000` | 进程干净退出的等待时限,超时强制回收 |
70
+ | `probeTimeoutMs` | `15000` | 测试连接、目录探针与官方额度读取时限 |
71
+ | `probeMaxTokens` | `1` | 测试连接请求传递的输出上限 |
72
+ | `loginTimeoutMs` | `1200000` | 官方授权页完成登录的等待时限 |
73
+ | `graceMs` | `1500` | 子进程托管终止宽限 |
74
+ | `env` | `{}` | 追加到 CLI 进程的环境变量 |
75
+
76
+ ### 会话能力
77
+
78
+ 每次开始 Codex 回合时,插件从 DSH 沙箱策略服务读取会话的生效模式,从审批服务读取会话覆盖或部署默认策略。精简组合缺少这些服务时采用 `workspace-write + ask`;进行中的回合保留开始时的权限。
79
+
80
+ - **流式正文与思考摘要**:正文、可提供的思考摘要随官方 CLI 增量返回。用户选择的推理等级传入每次官方回合;摘要内容以模型实际提供为准。
81
+ - **原生工具审批**:启用原生命令执行或文件修改后,「请求审批」使用工作区沙箱,额外权限申请在 KMH 弹出审批卡片;「帮我审批」对应官方 `--approve-for-me`,使用工作区沙箱与 Codex 自动审查,通过后执行、拒绝后返回结果;「完全权限」使用完整访问范围并跳过审批询问;「仅可查看」使用只读沙箱,额外权限申请交用户决定。设置在下一回合读取,KMH 工具继续遵循宿主权限策略。
82
+ - **图片直接入会话**:原生图片生成的产物作为图片块出现在对话里(附实际像素尺寸说明),可点击查看与保存原图。
83
+ - **发送图片**:Codex CLI 的模型目录声明支持图片时,可以在会话中附图发送。插件读取目录声明,无需在 KMH 中另行设置。目录缺少图片能力声明时按纯文本处理。
84
+ - **token 用量与会话状态**:每轮回复显示用量药丸(含缓存命中率);会话底部连接小球以绿、灰、红区分通信、停止与异常。官方重试期间直接显示“连接失败,正在重试”与原因,恢复输出后回绿;最终失败保留原因,用户可再次发送。等待首段响应和重试期间均可停止。超时返回 `CODEX_REQUEST_TIMEOUT`,随后中断与进程回收分别受收尾时限约束。官方已接纳的输入在确认停止或超时后仍计为已投递:用同一份历史再次发送返回 `CODEX_SESSION_HISTORY_MISMATCH: empty-increment`,用户追加新输入即可继续原会话,这一事实在重启后保留。
85
+
86
+ ### 详情页
87
+
88
+ Web 插件管理区提供 Codex CLI 卡片:CLI 版本(对照支持基线 0.160.0)、账号状态与凭据来源、默认模型、最近连接测试结果、原生能力逐项选择(命令执行、文件修改、查看图片、网络搜索与独立的原生技能,每项显示可用状态),以及登录/取消登录/退出账号/测试连接。工具调整立即保存,对之后普通新建的会话生效;原生技能独立调整,在下一回合生效。原生图片生成默认保留。账号状态按 `~/.codex/auth.json` 存在性判定,打开页面不发起模型请求;退出账号作用于本机官方 Codex CLI 的登录态。
89
+
90
+ ### 额度与显示设置
91
+
92
+ 现有插件详情页展示账号实际提供的额度周期、剩余进度、重置时间、额外 Credits、消费上限和可用重置卡。官方返回的零值保持为零,缺失值显示“账号暂未提供”;卡片只提供查看能力。Credits 的到期日期以官方数据为准,当前 CLI 未提供时标为未知。
93
+
94
+ 额度由官方 CLI 的 `account/read` 与 `account/rateLimits/read` 读取,详情页与输入框共用宿主缓存。自动更新、点击刷新和多个窗口共同遵守五分钟最短间隔,失败也保留冷却;刷新期间及失败后保留原数据和原成功时间。界面显示下次可刷新时间。浏览器读取最多等待 30 秒,超时显示“额度读取超时”并结束加载;成功记录继续保留。只有实际在途时显示“正在读取额度”,冷却中的空快照显示“状态待更新”。设置读取采用同一等待上限,重新连接后可恢复。账号状态变化清除旧账号数据。
95
+
96
+ 会话输入框通过公开模型目录订阅当前确认的选择。来源为 `codex-cli` 时默认显示百分比,切换来源或会话时随选择更新;普通模型复用主额度,Spark 和 Reserve 采用各自分组。窄输入框显示剩余最低的周期,悬浮、点击或键盘聚焦可查看全部周期与重置时间。
97
+
98
+ 详情页支持百分比、进度条、关闭,以及提醒开关和两个周期的独立阈值(1–100 整数,默认各 20%)。最近五分钟内且尚未到重置时间的结果,剩余严格低于阈值时在详情进度条与输入框同步变红。设置通过 DSH 共享配置镜像读取,由宿主配置持久化;命名空间就绪且宿主允许写入时可编辑。保存沿用编辑时的修订号,失败保留草稿与原文原因。远程只读浏览器采用宿主已接受的显示偏好,并展示保存限制。
99
+
100
+ 字段和分组规则参考 `dsh-codex-subscription` 的 `usage.js`、`sidebar-quota.js`,并核对官方 CLI 0.162 生成协议。参考版本为 `f73887098e75a8f1929b886a11b22470c1572dbd`。
101
+
102
+ ---
103
+
104
+ <a id="understand-the-implementation"></a>
105
+
106
+ ## 理解实现
107
+
108
+ <details>
109
+ <summary>实现细节——点击展开</summary>
110
+
111
+ 本节解释该包如何实现上述行为;可观察约定已在[使用本包](#use-this-package)中说明。
112
+
113
+ 数据流:Codex 在现有 `agent/created` 通知中保存创建时的工具选择、来源和完整声明,首条消息前也保留这份记录。只有选中的 Harness 工具进入请求:适配器发起请求时按会话快照准备本回合策略(`tool-policy.ts` 的 `prepare`),过滤 `options.tools` 后再交给 Codex;同一快照经公开的 `tools.guard` 控制直接、桥接和嵌套调用,参数漂移或未选中的调用返回 `TOOL_DISABLED`。默认选择修改后,已有会话继续读取自己的记录;普通新建会话读取新默认。`session-store.ts` 保存原工具、Codex 编号、消息处理位置和原生回合切点,收到编号后先保存再发送业务输入。记录损坏、原会话缺失或原工具信息缺失时明确报错并保留原记录。
114
+
115
+ 隔离在进程启动时经 `-c` 参数和按策略生成的模型目录注入。`0.162.0-alpha.17.2` 的 `exec_command`、`write_stdin`、`shell_command` 共用命令控制并联动;`apply_patch`、`view_image` 独立调整。`update_plan` 保持 CLI 固定状态,`web_search` 和 MCP 保留既有 CLI 控制并显示原因。其他版本的控制显示待核实,准备失败明确返回错误;任务重试使用原会话选择。
116
+
117
+ token 用量:`turn/completed` 的 turn 不携带用量(0.162 wire 实测),逐响应用量来自 `thread/tokenUsage/updated`(`last` 分项)。桥维护未消费样本队列,每个 step 收尾(工具挂起或回合终局)恰产出一条 usage chunk:队列空补零样本、终局合并全部剩余,保证各步样本之和恒等于回合总量且携带 `totalTokens`(KMH 折算校验必需)。
118
+
119
+ 会话底部状态由 `conversation.composer.dock` 公开槽位(order 2)注册的 `LiveBall` 展示,2 秒轮询 `GET /api/codex-cli/live`,按当前 sessionId 过滤。Host 与 Client 共用 `live-state.ts` 的响应校验;`retrying` 标记官方重试,`streaming` 在等待重试期间保持 true。宿主停止以 `AgentCancelCause` 对象经 `signal.reason` 传递;流等待监听中止信号并清理监听器。请求超时覆盖排队等待;取消排队项后,后继项仍等待当前消费方交还执行权。重试次数与退避由官方 CLI 管理。游标在官方确认接纳输入后立即推进并写入绑定文件,不等待本回合输出结束;确认中断时(用户停止或消费方提前结束流)把待投递摘要记为已投递,下一次差分不再包含该输入。差分切分允许真实用户输入后尾随 system/developer 运行时上下文并并入同一次投递,尾随 assistant 消息仍判定基线丢失。
120
+
121
+ 子 Agent 结算回报和跨会话转发都可以发起原生续轮。游标从用户角色消息中排除已知的被动上下文来源,例如运行时快照和技能目录。被动上下文可以随本轮输入投递。新增会唤醒 Agent 的来源可沿用这条路径。
122
+
123
+ 工具结果和子 Agent 回报同批到达时,适配器核对工具调用编号,把回报加入活跃原生回合的输入队列,再回传工具结果。原生回合已中断时,沿用原线程,将宿主已保存的工具结果和积压输入一并补交给下一回合。工具执行记录由宿主保留。
124
+
125
+ 图片生成结果的展示:Codex 原生 `image_gen.imagegen` 工具在默认隔离下即对模型可用(托管 API 调用,无本地执行与审批)。生成产物由 Codex 落盘到 `~/.codex/generated_images/<threadId>/`;桥在收到对应 `item/completed` 通知时读取落盘文件、经宿主附件服务(`ctx.attachments.saveImages`)落成 `ImageAttachmentRef`,并以 image 内容块送回 KMH,会话内直接展示该图片(2026-10-08 真机闭环:叙述块、image 块与尺寸附注并存渲染)。投影是展示增强:读取或入库失败时跳过并告警(落盘路径即恢复入口),生成与续推链路不受影响;同一生图项按 id 去重,一回合多张图片逐项展示。注意:image 块使用独立流块索引(`<id>:image`)——与叙述块共用 item id 的索引会让组装器按先关先赢丢弃 image 块。
126
+
127
+ 独立服务通过公开子路径 `@ktkid/kmh-codex-cli/imagegen` 导入 `Config`、`ImageRequest` 和 `generateImage`,复用本包的进程连接与隔离。执行器依赖调用方提供的 subprocess 服务,确认 ChatGPT 登录后创建一次性原生会话,返回 PNG 字节与实际尺寸,并在返回前等待进程回收。HTTP 服务、任务保存与中继配置由孔明主仓的图片生成服务维护。
128
+
129
+ | 模块 | 职责 |
130
+ | --------------------------------------------------- | ------------------------------------------------ |
131
+ | `src/connection.ts` | 行协议连接:进程、握手、双向请求分发、回收 |
132
+ | `src/cursor.ts` | 差分游标:前缀对齐与增量切分 |
133
+ | `src/turn.ts` | 回合状态机:挂起回执、续推、interrupt、原生 fork |
134
+ | `src/isolation.ts` | 工具/技能/钩子隔离的参数生成与核对 |
135
+ | `src/adapter.ts` | LlmAdapter:模型映射、流投影、会话驱动 |
136
+ | `src/approval.ts` | 审批桥:原生审批请求转 KMH 用户决定 |
137
+ | `src/tool-registry.ts` / `src/capabilities.ts` | kmh- 工具声明表与原生能力逐项选择 |
138
+ | `src/native-items.ts` / `src/image-delivery.ts` | 原生执行叙述与生图产物投影 |
139
+ | `src/session-store.ts` | 绑定与游标持久化 |
140
+ | `src/account.ts` / `src/probe.ts` / `src/status.ts` | 账号操作、测试连接、版本基线检查 |
141
+ | `src/web.ts` / `src/client/` | 详情页路由、详情卡片与状态小球 |
142
+
143
+ 额度详情、显示设置和输入框浮层遵循 [统一 Web 样式](https://github.com/deepseek-ai/deepseek-harness/blob/ce7073d51254c26cd63b22a60835b8f948deb447/docs/web-styling.md)。局部样式位于 `src/client/quota.module.css`,构建器将生成的样式嵌入 `lib/client.js`,插件卸载时一同释放。
144
+
145
+ ### 构建与验证
146
+
147
+ 在 Kongming 根目录运行:
148
+
149
+ ```sh
150
+ pnpm build:kmh
151
+ pnpm typecheck:kmh
152
+ pnpm lint
153
+ pnpm test
154
+ ```
155
+
156
+ 测试位于主仓 `tests/runtime/codex-cli.test.mjs`,含真实 CLI 冒烟(本机存在官方 Codex CLI 时执行,否则跳过):差分投递 → 工具挂起 → 回执续推 → 最终回复,并核对模型只声明 KMH 工具与已接受的 MCP 设备。运行中的排查入口:`~/.codex/sessions/<日期>/rollout-*.jsonl`(`originator: kmh_codex_cli` 标识插件的会话)、`/api/codex-cli/status` 与 `/api/codex-cli/live`(连接状态)路由、KMH 数据目录的 `codex-cli/`。Client 改动需要重新构建并在浏览器实际验证。
157
+
158
+ </details>
159
+
160
+ ---
161
+
162
+ <a id="verify-the-plugin"></a>
163
+
164
+ ## 验证插件
165
+
166
+ ### 测试代码规范
167
+
168
+ `test/` 的测试用例与配套夹具使用 TypeScript。类型检查、Lint 与格式检查覆盖测试目录。
169
+
170
+ ### 会话工具记录升级
171
+
172
+ `codex-bindings.json` 新增创建时工具信息和原生回合对应记录,首条消息前的记录可以暂时没有 `threadId`。已保存但缺少原工具信息的旧记录会报告 `CODEX_SESSION_STATE_INCOMPLETE`;损坏文件报告 `CODEX_SESSION_STATE_CORRUPT`。原文件和原生会话保留,插件不会用当前开关补造旧配置或自动创建替代会话;用户可普通新建 KMH 会话继续任务。改变读取行为与新增字段由本说明承接,DSH Session 格式代际保持原样。
173
+
174
+ 使用 Node.js 24.9+ 和 pnpm 11.7.0。独立仓使用 npm 发布的 DSH `0.2.2-rc.1` 开发依赖。GitHub CI 在 macOS arm64 执行完整回归,覆盖默认启动器和原生文件修改。测试默认使用[插件固定的官方 CLI](bin/README.md);`KMH_CODEX_BINARY` 可以指定经过版本验证的官方程序绝对路径。
175
+
176
+ 独立仓提供 `cordis.patch.yml`。DSH profile 可以在 `dsh.profile.bundles` 中引用 `@ktkid/kmh-codex-cli`,按需使用插件行 `kmh-codex-cli` 覆盖配置。
177
+
178
+ ```sh
179
+ pnpm install --frozen-lockfile
180
+ pnpm build
181
+ pnpm typecheck
182
+ KMH_CODEX_TEST_TMP=$(mktemp -d) pnpm test
183
+ pnpm lint
184
+ pnpm format:check
185
+ ```
186
+
187
+ 测试位于 [`test/`](test/stream-reasoning.test.ts)。思考等级与摘要回归经过真实 Profile Loader、Agent turn、插件 adapter 和官方 app-server,CLI 的模型地址指向本机 Responses 模拟服务。测试消息经过真实 CLI,模拟服务返回固定正文与摘要,模型请求使用隔离的测试凭据。新建、续聊和编辑后分叉分别核对 Agent 请求记录、CLI 参数、本轮生效设置、模型实际请求及 Agent 保存的回复;摘要开启与关闭各执行一轮完整流程。
188
+
189
+ 原生 session 的 `turn_context` 保存回合上下文快照,当前固定版 CLI 的摘要快照保留初始化默认值;本轮摘要模式由 `thread_settings_applied` 生效记录核对。续聊时设置记录可能先于本轮开始,测试按 turn 编号定位本轮上下文与完成事件,在上轮完成至本轮完成之间取最后一条生效设置,再检查所属 thread、思考等级和摘要模式。官方 `ultra` 在 session 中保留原值,在 Responses 请求中映射为 `max`。
190
+
191
+ 流式测试直接调用真实插件 adapter,完成门控制模型响应结束时机,分别核对官方通知与插件增量在完成前到达。[重试测试](test/retry-status.test.ts)覆盖真实 503、恢复、重试耗尽、首段前停止、重试期间停止,以及主请求和辅助请求超时(超时后同一份历史不再重跑,追加新输入才发起下一次请求);客户端 bundle 渲染测试检查中英文可见原因。[停止恢复测试](test/task-stop-recovery.test.ts)覆盖真实 Agent 在输入被接纳后停止、下一条输入不重复投递、重启后继续,以及消费方提前结束流后部分输出与绑定保留。生产模型访问与浏览器显示由真实环境验收。
192
+
193
+ `KMH_CODEX_TEST_TMP` 必须为绝对路径,省略时使用系统临时目录下的 `kmh-codex-cli-tests`。每项 smoke 建立独立子目录,并将 `CODEX_HOME` 指向其 `codex-home/`;测试保留这些目录,登录与响应服务使用隔离的测试配置。
194
+
195
+ | 记录 | 内容 |
196
+ | -------------------------------------------------- | ---------------------------------------------------------------------------------- |
197
+ | `codex-home/sessions/**/*.jsonl` | 官方原生 session,包含回合上下文、`thread_settings_applied` 生效设置与任务结束记录 |
198
+ | `upstream.jsonl` | 本地模型服务收到的实际请求 |
199
+ | `notifications.jsonl` | 官方 app-server 通知及接收时间 |
200
+ | `app-server.stdout.jsonl`、`app-server.stderr.log` | 原始通信与进程诊断 |
201
+ | `plugin-stream.jsonl` | 流式用例的插件输出、时间及当时上游是否完成 |
202
+
203
+ 维护者可以在复查结束后删除对应临时子目录。[会话工具回归](test/tool-policy.test.ts)覆盖真实配置编辑、原 ID 恢复、原生文件修改、持久化重启、原生分叉、长消息与缺失会话;[存储测试](test/session-store.test.ts)覆盖文件损坏、写入失败和串行保存。
204
+
205
+ 需求与实际验证记录见[流式与思考等级回归](https://github.com/KtKID/kongming-os/blob/main/docs/spec/codex-cli-provider/tasks/task-stream-reasoning-regression.md)、[重试、停止与超时](https://github.com/KtKID/kongming-os/blob/main/docs/spec/codex-cli-provider/tasks/task-retry-status.md)。
206
+
207
+ ---
208
+
209
+ <a id="further-exploration"></a>
210
+
211
+ ## 进一步探索
212
+
213
+ - [需求与验收场景](https://github.com/KtKID/kongming-os/blob/main/docs/spec/codex-cli-provider/spec.md)——功能行为的唯一事实源,任务拆解在其 tasks/ 下。
214
+ - [生效技术决策](https://github.com/KtKID/kongming-os/blob/main/docs/spec/codex-cli-provider/decisions.md)——执行归属、共享登录、隔离、审批、进度与图片交付的最终决策及依据。
215
+ - [运行记录](https://github.com/KtKID/kongming-os/blob/main/docs/kmh/runtime-records.md)——数据目录与日志路径的通用规则。
216
+ - [Kongming 的 DSH 底座](https://github.com/KtKID/kongming-os/blob/main/docs/kmh/README.md)——自有插件与 profile 的装配关系。
217
+ - [Kongming 插件索引](https://github.com/KtKID/kongming-os/blob/main/docs/kmh/plugin-index.md#kongming-自有包)提供 ZCode CLI 独立仓入口。
218
+
219
+ 官方协议:Codex app-server v2(`codex app-server --stdio` 行协议),支持基线为 0.160.0;包内测试核对本机指定版本的协议和原生会话行为。
220
+
221
+ ---
222
+
223
+ <a id="model-experience"></a>
224
+
225
+ ## 模型体验
226
+
227
+ ### 模型看到什么
228
+
229
+ 模型接收 KMH 组装的 system 提示与工具目录,两者在 thread 创建时一次性绑定。KMH 工具以动态工具回调声明,执行交回 KMH 的权限与审批链。默认隔离下原生 shell、改文件、多 agent 等工具不再声明;逐项开启的原生能力与 KMH 工具并存,其提权操作同样进入 KMH 审批。用户在 `~/.codex` 配置的 MCP 设备对模型可见;原生图片生成工具在默认隔离下即可用。
230
+
231
+ ### Token 影响
232
+
233
+ 同一 KMH 会话的后续回合恢复保存的 Codex thread,完整发送新增输入和工具回执;原生历史与压缩结果由 Codex 维护。每轮用量药丸报告实际 token 与缓存命中。辅助压缩评估和标题生成保留独立请求路径。
234
+
235
+ ### KV Cache 影响
236
+
237
+ 工具声明只在首次 `thread/start` 传入;后续 `thread/resume` 保持原编号、原工具及原生历史。详细原始执行事件受 CLI 恢复能力限制,界面按普通通知显示可提供的进度与结果。跨回合缓存命中由提供方决定。声明指纹包含来源、名称、完整参数、原生版本与所选控制。
238
+
239
+ ---
240
+
241
+ <a id="known-limitations-and-deferred-work"></a>
242
+
243
+ ## 已知限制与延期工作
244
+
245
+ 这些限制说明何时需要特别留意;它们是当前包约束,不是任务积压。
246
+
247
+ - **支持基线为官方 CLI 0.160.0**——vendored 模型目录随包分发;包内测试验证指定 CLI 的协议、流式与原生日志,真实模型服务由部署环境验收。
248
+ - **共享 `~/.codex` 的连带**——用户 MCP 设备可见(`-c` 无法压掉且清空覆盖会重置用户禁用状态,已拍板接受);用户与项目级钩子在每回合前经探针发现并逐键禁用,只覆盖当轮发现的键。
249
+ - **恢复时的记录能力**——部分 CLI 版本仅在新建时提供详细原始工具事件;恢复保持原会话,进度按实际通知展示。
250
+ - **登录状态按凭据存在性判定**——只检查 `~/.codex/auth.json` 存在与可解析,不校验有效性;「测试连接」才发起真实模型请求。
251
+ - **只读红线**——绝不写入或修改用户 `~/.codex`;一切注入经 `-c` 进程参数单次生效。
252
+ - **待验证**——真实压缩触发观察(需真模型长上下文)、分钟级工具挂起时 Codex 侧超时行为。
253
+
254
+ ---
255
+
256
+ <a id="dev-note"></a>
257
+
258
+ ## 开发备注
259
+
260
+ <details>
261
+ <summary>维护者的工作上下文——点击展开</summary>
262
+
263
+ - canonical namespace 注册的模型侧名称是无点拼接,已回退平铺真名。
264
+
265
+ </details>
266
+
267
+ <details>
268
+ <summary>额度分组规则参考许可</summary>
269
+
270
+ 参考 `dsh-codex-subscription/src/sidebar-quota.js` 的模型匹配规则,保留原 MIT 许可:
271
+
272
+ ```text
273
+ MIT License
274
+
275
+ Copyright (c) 2026 WSL043
276
+
277
+ Permission is hereby granted, free of charge, to any person obtaining a copy
278
+ of this software and associated documentation files (the "Software"), to deal
279
+ in the Software without restriction, including without limitation the rights
280
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
281
+ copies of the Software, and to permit persons to whom the Software is
282
+ furnished to do so, subject to the following conditions:
283
+
284
+ The above copyright notice and this permission notice shall be included in all
285
+ copies or substantial portions of the Software.
286
+
287
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
288
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
289
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
290
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
291
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
292
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
293
+ SOFTWARE.
294
+ ```
295
+
296
+ </details>
package/bin/README.md ADDED
@@ -0,0 +1,25 @@
1
+ ---
2
+ description: 插件固定 Codex CLI 运行包的位置、完整版本检查、当前平台与本地运行包的维护方法。
3
+ ---
4
+
5
+ # 固定 Codex CLI 运行包
6
+
7
+ 插件默认执行本目录的 `codex` 启动器。固定版本由 `version` 保存;当前为 `0.163.0-alpha.10.2`,已部署平台为 macOS arm64。聊天、登录、额度、模型目录与探针都通过插件同一个 `Config.command` 执行。
8
+
9
+ ## 目录与校验
10
+
11
+ 完整官方运行包位于 `0.163.0-alpha.10.2/darwin-arm64/`,保留 `codex-package.json`、`bin/`、`CodexCLI.app/`、`codex-path/` 和 `codex-resources/` 的原始相对位置。程序及配套资源共46个文件,340,775,935字节。复制来源为当前本机桌面应用随附的官方运行包;复制后逐文件 SHA-256 对比一致,主程序哈希记录在 [runtime-receipt.json](runtime-receipt.json)。
12
+
13
+ 启动器按 `version` 和当前平台定位运行包,先执行官方 `--version`,精确匹配完整版本字符串后以 `exec` 转交原参数、输入输出及退出状态。alpha 后缀参与匹配。版本失配返回 `CODEX_VERSION_MISMATCH`;运行包缺失返回 `CODEX_BUNDLED_RUNTIME_MISSING`;当前平台尚无部署支持时返回 `CODEX_BUNDLED_PLATFORM_UNSUPPORTED`,这些失败使用退出码78。
14
+
15
+ 官方原生工具清单继续位于 `vendor/native-tools/<实际版本>.json`。本次清单从固定程序发给隔离本地模型服务的真实请求采集,并以执行拒绝测试核对工具隔离。
16
+
17
+ ## 本地部署与升级
18
+
19
+ 完整运行包保留在 Git 忽略目录中;启动器、固定版本、复制收据和工具清单随源码维护。GitHub Release 包包含插件产物、启动器和版本记录。使用默认启动器时,在上述版本和平台目录部署完整运行包。也可通过 npm 安装 `@openai/codex` 的固定版本,再把 `Config.command` 或测试环境变量 `KMH_CODEX_BINARY` 指向该程序的绝对路径。
20
+
21
+ 升级时先准备目标官方运行包,核对实际版本与来源,再更新固定版本、复制收据和对应工具清单。执行插件工具隔离及会话回归,验证成功后切换版本;本机 Codex 登录、配置和原生会话目录继续由现有机制管理。目录只承载程序和资源。
22
+
23
+ ## 维护入口
24
+
25
+ `codex` 负责程序定位、版本检查和进程转交;`version` 是固定版本的权威值;`runtime-receipt.json` 保存本次复制来源、规模与主程序校验值。Config 从自身包目录解析本目录,显式 `command` 覆盖继续可用。
package/bin/codex ADDED
@@ -0,0 +1,36 @@
1
+ #!/bin/sh
2
+ # 固定 CLI 的统一入口:定位本平台运行包、核对完整版本,再转交参数与退出状态。
3
+ set -eu
4
+ bin_dir=$(CDPATH= cd -P -- "$(dirname -- "$0")" && pwd)
5
+ IFS= read -r version < "$bin_dir/version"
6
+ case "$(uname -s)/$(uname -m)" in
7
+ Darwin/arm64) platform=darwin-arm64 ;;
8
+ *) printf 'CODEX_BUNDLED_PLATFORM_UNSUPPORTED: %s/%s\n' "$(uname -s)" "$(uname -m)" >&2; exit 78 ;;
9
+ esac
10
+ executable="$bin_dir/$version/$platform/bin/codex"
11
+ # npm 将官方固定版 CLI 安装在插件可访问的依赖目录中。
12
+ if [ ! -x "$executable" ]; then
13
+ ancestor=$(dirname -- "$bin_dir")
14
+ while [ "$ancestor" != / ]; do
15
+ candidate="$ancestor/node_modules/@openai/codex-darwin-arm64/vendor/aarch64-apple-darwin/bin/codex"
16
+ if [ -x "$candidate" ]; then
17
+ executable="$candidate"
18
+ break
19
+ fi
20
+ ancestor=$(dirname -- "$ancestor")
21
+ done
22
+ fi
23
+ if [ ! -x "$executable" ]; then
24
+ printf 'CODEX_BUNDLED_RUNTIME_MISSING: %s\n' "$executable" >&2
25
+ exit 78
26
+ fi
27
+ actual=$("$executable" --version)
28
+ if [ "$actual" != "codex-cli $version" ]; then
29
+ printf 'CODEX_VERSION_MISMATCH: expected %s; actual %s\n' "$version" "$actual" >&2
30
+ exit 78
31
+ fi
32
+ if [ "$#" -eq 1 ] && [ "$1" = --version ]; then
33
+ printf '%s\n' "$actual"
34
+ exit 0
35
+ fi
36
+ exec "$executable" "$@"
@@ -0,0 +1,9 @@
1
+ {
2
+ "version": "0.163.0-alpha.10.2",
3
+ "platform": "darwin-arm64",
4
+ "files": 46,
5
+ "bytes": 340775935,
6
+ "executableSha256": "1afb28c01d7d49e892bd75f11076b10f1451e34e0ee308a95e5ab7f69f9c84fe",
7
+ "source": "ChatGPT.app bundled official Codex runtime",
8
+ "entrypoint": "bin/codex"
9
+ }
package/bin/version ADDED
@@ -0,0 +1 @@
1
+ 0.163.0-alpha.10.2
@@ -0,0 +1,7 @@
1
+ # 将 Codex 模型提供方挂载到已有的 DSH 会话和模型服务。
2
+ - insert:
3
+ - id: kmh-codex-cli
4
+ name: "@ktkid/kmh-codex-cli"
5
+ config:
6
+ cwd: !!js process.cwd()
7
+ dataDir: !!js dshHomePath('codex-cli')
@@ -0,0 +1,9 @@
1
+ /** 详情页与 Host 共享的账号状态类型(浏览器侧安全,不含凭据值)。 */
2
+ export interface AccountStatus {
3
+ login: "signed-in" | "idle" | "starting" | "waiting" | "failed";
4
+ /** 凭据来源说明(路径级,不含内容)。 */
5
+ credentialSource?: string;
6
+ /** 进行中登录的授权链接。 */
7
+ authorizeUrl?: string;
8
+ error?: string;
9
+ }
@@ -0,0 +1,10 @@
1
+ import type { ModelDirectory } from "@deepseek-ai/dsh-client-ui-model-selection/client";
2
+ import type { QuotaStore } from "./quota-store.ts";
3
+ import { type QuotaTranslate } from "./QuotaCard.tsx";
4
+ export interface ComposerQuotaProps {
5
+ directory: Pick<ModelDirectory, "store" | "load">;
6
+ quota: QuotaStore;
7
+ t: QuotaTranslate;
8
+ openSettings?: () => void;
9
+ }
10
+ export declare function ComposerQuota({ directory, quota, t, openSettings, }: ComposerQuotaProps): JSX.Element | null;
@@ -0,0 +1,12 @@
1
+ import type { PropsLocale, PropsRuntime } from "@deepseek-ai/dsh-client-ui-slots";
2
+ import type { QuotaStore } from "./quota-store.ts";
3
+ /** 组合 props:槽位运行时份额(`view`)与注册声明的 locale 注入(`t`)。 */
4
+ export type CodexCardProps = PropsRuntime<"plugins.item"> & PropsLocale<"settings.codex-cli">;
5
+ /**
6
+ * 拉取并按请求视图渲染:简介一句话或完整详情。
7
+ * @param props - 槽位传入的 `view` 与 locale 注入的 `t`。
8
+ * @returns 简介文本节点,或完整详情卡片。
9
+ */
10
+ export declare function CodexCard(props: CodexCardProps & {
11
+ quota?: QuotaStore;
12
+ }): JSX.Element;
@@ -0,0 +1,19 @@
1
+ import type { PropsLocale, SessionStandardProps } from "@deepseek-ai/dsh-client-ui-slots";
2
+ import { LiveSnapshot } from "../live-state.ts";
3
+ import type { z } from "zod";
4
+ import type { LocaleKey } from "./locales.ts";
5
+ /** /api/codex-cli/live 返回体(与宿主 SessionLiveState 对应)。 */
6
+ type LiveEntry = z.infer<typeof LiveSnapshot>["sessions"][number];
7
+ /** 小球及可读状态;重试和失败原因直接展示。 */
8
+ export declare function LiveBallView({ entry, t, }: {
9
+ entry: LiveEntry;
10
+ t: (key: LocaleKey) => string;
11
+ }): import("react").JSX.Element;
12
+ /**
13
+ * 轮询本会话的 CLI 连接状态并渲染状态小球:绿=通信已建立(进行中或进程
14
+ * 在线)、灰=已停止、红=停止未确认/回合异常中断。当前会话无记录(未用过
15
+ * codex-cli 或插件重启后尚未开始回合)时不渲染。
16
+ * 输入:GET /api/codex-cli/live 快照;取数失败保持上次内容。
17
+ */
18
+ export declare function LiveBall({ sessionId, t, }: PropsLocale<"settings.codex-cli"> & Pick<SessionStandardProps, "sessionId">): import("react").JSX.Element | null;
19
+ export {};
@@ -0,0 +1,20 @@
1
+ import type { TranslateNS } from "@deepseek-ai/dsh-client-ui-slots";
2
+ import type { QuotaStore, QuotaClientSnapshot } from "./quota-store.ts";
3
+ import type { QuotaWindow } from "../quota-protocol.ts";
4
+ export type QuotaTranslate = TranslateNS<"settings.codex-cli">;
5
+ export declare function periodLabel(window: QuotaWindow, t: QuotaTranslate): string;
6
+ export declare function resetLabel(window: QuotaWindow, now: number, t: QuotaTranslate): string;
7
+ export declare function QuotaWindows({ state, windows, t, }: {
8
+ state: QuotaClientSnapshot;
9
+ windows: readonly QuotaWindow[];
10
+ t: QuotaTranslate;
11
+ }): JSX.Element;
12
+ export declare function QuotaStatus({ state, t, retry, }: {
13
+ state: QuotaClientSnapshot;
14
+ t: QuotaTranslate;
15
+ retry: () => void;
16
+ }): JSX.Element | null;
17
+ export declare function QuotaCard({ store, t, }: {
18
+ store: QuotaStore;
19
+ t: QuotaTranslate;
20
+ }): JSX.Element;
@@ -0,0 +1,6 @@
1
+ import type { QuotaStore } from "./quota-store.ts";
2
+ import type { QuotaTranslate } from "./QuotaCard.tsx";
3
+ export declare function QuotaDisplaySettings({ store, t, }: {
4
+ store: QuotaStore;
5
+ t: QuotaTranslate;
6
+ }): JSX.Element;
@@ -0,0 +1,18 @@
1
+ /** Codex 详情卡片在插件管理区的挂载与文案。 */
2
+ import type { Context } from "@deepseek-ai/cordis";
3
+ import { LiveBall, LiveBallView } from "./LiveBall.tsx";
4
+ import { type LocaleKey } from "./locales.ts";
5
+ export { LiveBall, LiveBallView };
6
+ declare module "@deepseek-ai/dsh-client-ui-slots" {
7
+ interface LocaleNamespaceMap {
8
+ /** Codex account and connection copy. */
9
+ "settings.codex-cli": LocaleKey;
10
+ }
11
+ }
12
+ /** Services needed for the Plugins contribution. */
13
+ export declare const inject: string[];
14
+ /**
15
+ * Register the Codex detail card and dictionaries.
16
+ * @param ctx - Client plugin owner.
17
+ */
18
+ export declare function apply(ctx: Context): void;
@@ -0,0 +1,54 @@
1
+ /** 详情卡片文案(中英)。 */
2
+ type BaseLocaleKey = "title" | "liveTitle" | "liveGreen" | "liveGray" | "liveRed" | "liveRetrying" | "summary" | "loading" | "versionLabel" | "versionSupported" | "versionUnsupported" | "versionMissing" | "accountLabel" | "accountSignedIn" | "accountWaiting" | "accountStarting" | "accountFailed" | "accountSignedOut" | "credentialLabel" | "modelLabel" | "modelCatalogFirst" | "probeLabel" | "probeNever" | "probePass" | "probeFail" | "capabilitiesLabel" | "capabilityUnavailable" | "capabilityNextTurn" | "toolSelectionScope" | "openAuthorize" | "signIn" | "cancelLogin" | "signOut" | "probe" | "logoutNote";
3
+ declare const quotaZh: {
4
+ quotaTitle: string;
5
+ quotaShort: string;
6
+ quotaWeekly: string;
7
+ quotaPeriodUnknown: string;
8
+ quotaMinutes: string;
9
+ quotaRemaining: string;
10
+ quotaResetUnknown: string;
11
+ quotaResetPending: string;
12
+ quotaPending: string;
13
+ quotaSignIn: string;
14
+ quotaUnsupported: string;
15
+ quotaLoading: string;
16
+ quotaFailed: string;
17
+ quotaTimedOut: string;
18
+ quotaSettingsTimedOut: string;
19
+ quotaReadError: string;
20
+ quotaSectionError: string;
21
+ quotaRetry: string;
22
+ quotaUpdated: string;
23
+ quotaCredits: string;
24
+ quotaUnlimited: string;
25
+ quotaUnknown: string;
26
+ quotaBalanceUnknown: string;
27
+ quotaExpiryUnknown: string;
28
+ quotaSpend: string;
29
+ quotaResets: string;
30
+ quotaResetCard: string;
31
+ quotaDetailsUnknown: string;
32
+ quotaRefresh: string;
33
+ quotaFrequency: string;
34
+ quotaCooldown: string;
35
+ quotaSettings: string;
36
+ quotaMode: string;
37
+ quotaPercent: string;
38
+ quotaBar: string;
39
+ quotaOff: string;
40
+ quotaAlerts: string;
41
+ quotaShortThreshold: string;
42
+ quotaWeeklyThreshold: string;
43
+ quotaRange: string;
44
+ quotaSave: string;
45
+ quotaSaving: string;
46
+ quotaReadonly: string;
47
+ quotaSettingsLoading: string;
48
+ quotaClose: string;
49
+ quotaDetails: string;
50
+ };
51
+ export type LocaleKey = BaseLocaleKey | keyof typeof quotaZh;
52
+ export declare const zh: Record<LocaleKey, string>;
53
+ export declare const en: Record<LocaleKey, string>;
54
+ export {};
@@ -0,0 +1,56 @@
1
+ /** 每个客户端插件实例共享额度读取与宿主已接受配置;组件只登记可见需求。 */
2
+ import type { Context } from "@deepseek-ai/cordis";
3
+ import type { ConfigFormSnapshot } from "@deepseek-ai/dsh-client-ui-settings/client";
4
+ import { QuotaView, QuotaPreferences } from "../quota-protocol.ts";
5
+ export interface QuotaClientSnapshot {
6
+ view: QuotaView;
7
+ loading: boolean;
8
+ now: number;
9
+ error: string | null;
10
+ settings: ConfigFormSnapshot<QuotaPreferences> | null;
11
+ settingsError: string | null;
12
+ }
13
+ type Fetcher = typeof fetch;
14
+ export declare class QuotaStore {
15
+ private readonly fetcher;
16
+ private readonly clock;
17
+ private state;
18
+ private readonly listeners;
19
+ private consumers;
20
+ private generation;
21
+ private inFlight;
22
+ private aborter;
23
+ private contextAborter;
24
+ private timer;
25
+ private settingsDispose;
26
+ private mirrorDispose;
27
+ private contextDispose;
28
+ private namespace;
29
+ private context;
30
+ private disposed;
31
+ private retryAt;
32
+ private paused;
33
+ private bindingGeneration;
34
+ constructor(fetcher?: Fetcher, clock?: () => number);
35
+ getSnapshot: () => QuotaClientSnapshot;
36
+ subscribe: (listener: () => void) => (() => void);
37
+ private publish;
38
+ /** HTTP 截止覆盖响应头与正文;取消与超时均释放等待者,迟到回执失去提交资格。 */
39
+ private withDeadline;
40
+ private requestJson;
41
+ /** 绑定公开配置镜像;重绑与卸载使旧读取失去提交资格。 */
42
+ bind(ctx: Context): Promise<void>;
43
+ private bindSettings;
44
+ /** 保存只涉及四个额度显示键,使用用户开始编辑时的修订号。 */
45
+ save(value: QuotaPreferences, revision: number | undefined): Promise<void>;
46
+ /** 首个可见消费者启动读取;隐藏页面与最后一个消费者离开时暂停调度。 */
47
+ retain(): () => void;
48
+ private visible;
49
+ private visibility;
50
+ /** 回执代数隔离重连,某组件卸载保持其他消费者的共享请求。 */
51
+ reset(refresh?: boolean): void;
52
+ refresh: (force?: boolean) => Promise<void>;
53
+ private schedule;
54
+ dispose(): void;
55
+ }
56
+ export {};