READMESource: master@1909637a
dsh-plugin-agentos
把「谁在什么时候能打模型上游」从模型手里收回来。 DeepSeek Harness (dsh) host 侧 LLM 调度网关：并发信号量 + 三队列公平调度 + 透明重试 + 预算闸门，外加一块 Windows 任务管理器风格的实时面板，和一条把 dsh 已配置模型导入为 可调度上游的混合通道。
Take back control of when and who hits your model upstreams — the host-side LLM scheduling gateway for DeepSeek Harness: concurrency semaphores, three-queue fair scheduling, transparent retries, budget gates, a Windows-Task-Manager-style live panel, and a hybrid channel that turns your configured dsh providers into schedulable upstreams.
纯 TypeScript，零运行时依赖（网关面仅 node: 内置模块；混合通道面唯一依赖
@deepseek-ai/dsh-llm，缺席 fail-open）。设计文档 DESIGN.md（v2.4，
唯一语义事实来源）、代码对照 设计说明.md 在源码仓库（npm 包内不含
这两份内部文档）；发行史 CHANGELOG.md，legacy 实现发行史存档
docs/CHANGELOG-legacy.md。
装完你会看到什么
插件挂载重启 dsh 桌面端后，两个入口：
- 会话输入区左侧多一枚「AgentOS」chip——点开即右侧栏任务管理器面板（0.12.0 修通
的 keyed slot 挂载 + 入场引导页），三个 tab：
- 概览：KPI 行（聚合 tok/s + 核心占用率 + 在途/排队/活跃会话）+ 处理器卡—— 每核 = 网关并发信号量一个 slot，忙/闲实时填充 + 绑定会话 + 该会话 tok/s；AIMD 降容/扩容徽章（扩容核虚线边）+ 利用率滚动图 + 三队列（high/normal/batch）深度卡；
- 会话：活跃会话四态过滤，每会话在途/排队/tok/s/累计 token（已归档会话不进任何视图）；
- 设置：tok/s 窗口、图表历史、核心列数、动画开关 + 网关与七子模块运行时开关 + 处理器信息（配置并发/AIMD 区间/上游数/mode/端口/版本，只读）。
- 模型选择器出现「AgentOS 混合通道」分组（混合通道启用时）：
auto= 智能调度 （在启用上游间按余量选源，会话绑定优先）；选具体模型 = 把当前会话绑定到该上游（TTL 6h）。 - 不挂插件也能用：standalone 模式起一个
agentos-gateway进程 + HTTP 端点，任何能发 HTTP 的程序都能排在它后面。
效果图
真机截图（桌面端实拍）：概览处理器矩阵 / 会话台账 / 模型选择器混合通道分组。
功能
| 模块 | 做什么 |
|---|---|
| 调度内核 | 全局并发信号量 + high/normal/batch 三队列 DRR 公平调度 + starve-aging 防饿死 + 自适应 deadline + watchdog 判 504 |
| 透明重试 | Gate1 语义级重试决策 + Gate2 终态帧；429 吸收/搁置/透传三态协调（Retry-After 头优先）；错误契约 11 码（HTTP 状态 + X-AgentOS-Error 头/指纹回声双面） |
| 自适应容量 | AIMD 三通道（错误/延迟/成功）+ 429 归因（头优先+启发式）+ 熔断器（三态/时间+样本双窗/half-open 单探针）+ 令牌桶 RPM 限速（AIMD 对称小罚） |
| 预算闸门 | 日/任务两级 token 限额（加权记账：cacheRead×0.1、cacheWrite×1.25）+ 影子告警与 enforce 硬拦（503 BUDGET_BLOCKED）两态 + admin 热调 + 当日台账重启续账 |
| 混合通道（v0.20.0） | 把 dsh 已配置的模型 provider 一键导入为可调度上游：进程内委托 ctx.llm.stream，协议转换与重试全复用 dsh 既有链路，密钥不出 dsh credentials |
| 任务管理器 | 实时面板：处理器核心矩阵、利用率/tok/s 滚动图、队列深度、会话台账、网关开/关、七子模块独立启停（agentos-modules.json 跨重启保持） |
| 工具面 | mem_* 内存池八工具（按会话 cwd 惰性建池）+ console_* 异步托管四工具 + steer 回投 + AGENTS 纪律段 + C7 哨兵巡检（60s 防抖/去重/恢复） |
| 池路由 | 绑定键 sess:/pfx:+盐子键 / pow2+有界负载+θ 选择 / CACHE_MIGRATE 四类迁移 / big.LITTLE 池升级 / work-steal 谓词 / 池持久化 |
| 零依赖纪律 | 网关面零 npm 运行时依赖（纯 node: 内置）；shellcheck 机检 lib 零 @deepseek-ai/* import；缺 webServer 无服务得 undefined 而非炸宿主 |
实测数据
- 单测 843 用例 / 60 文件全绿（
node --test），外加断言面四件套： selfcheck 15 + smoke 29 + shellcheck 21 + mix-shell-check 23； - agentos-sim 测试床 E2-a 信号量场景 PASS：16/16 成功、mock 在途峰值 = 信号量 设定值（排队生效）、交互空闲档 P95 附加延迟 193ms（判据 2000ms）；
- 真机 GLM（账号并发上限 ≈5）十并发实测全链调度语义（排队 / 429 吸收 / AIMD 降容 /
池迁移 / 面板口径），修复批分析见
reports/预发布总校验-2026-11-06.md； - 诚实口径：最新两批修复（v0.20.1/v0.20.2）经全量单测 + 四路独立审查，desktop 挂载副本尚停在 0.20.0，真机复验待重启激活——见「已知边界」。
node D:/dsh/agentos-sim/loadgen.mjs --run scenarios/E2a_semaphore.mjs \
--target http://127.0.0.1:9001 --gateway http://127.0.0.1:8391/deepseek-main \
--out reports/E2a-ts-report.json
node D:/dsh/agentos-sim/assert.mjs --exp E2-a --mock http://127.0.0.1:9001 \
--gateway http://127.0.0.1:8391/deepseek-main --report reports/E2a-ts-report.json
（2026-10-09 记录；测试床位于作者本机 D:/dsh/agentos-sim/，产物为本地 reports/ 文件。）
安装与接入
- 宿主版本要求：dsh 0.2.1-rc.x（混合通道面依赖
@deepseek-ai/dsh-llm 0.2.1-rc.5精确锁 + peer@deepseek-ai/cordis ^4.0.4；网关面在 0.2.0-rc.2 实测可用，混合通道面 未在 0.2.0 验证）。 - 插件挂载：profile 依赖加入本包（
file:/npm 均可）后，dsh.profile.bundles加"dsh-plugin-agentos"——挂载配置由插件自带cordis.patch.yml自动应用（中性缺省 + 上游示例）。个人化配置在 profile 层cordis.patch.yml写- id: dsh-plugin-agentos+config:覆盖条目（⚠️ 语义 = 整体替换不是深合并， 须写全所需键）。严禁在 profile 层再 insert 同 id（双挂载即崩）。 - standalone：
DS_KEY=x node dist/gateway/index.js --config agentos.config.json（全局安装后亦可用 binagentos-gateway；示例配置为 agentos-sim mock 形态）。
# 源码挂载（发布 npm 前）
git clone https://github.com/Pasumao/dsh-plugin-agentos.git
# 发布后（一条命令，具体形态以 dsh 版本为准）
npm i -g dsh-plugin-agentos && agentos-gateway --config agentos.config.json
给 AI 的安装说明
dsh 用户的默认姿势就是让 agent 装插件——下面这段可直接复制给你的 coding agent：
请阅读 https://github.com/Pasumao/dsh-plugin-agentos 仓库根的 AGENTS.md，
按其中「安装与挂载」一节把 dsh-plugin-agentos 挂进我的 dsh profile：
1. 先确认我的 dsh 版本 ≥ 0.2.1-rc.x（不满足则只承诺网关面能力并说明差异）；
2. 把插件以 link:/file: 依赖装进 profile 的 node_modules，
并在 dsh.profile.bundles 里加 "dsh-plugin-agentos"（严禁再 insert 同 id）；
3. 在插件目录跑 npm install && npm run build && npm run shellcheck 自检通过；
4. 重启 dsh 后验证：会话输入区左侧出现「AgentOS」chip，点开面板三 tab 可见；
5. 帮我把我的模型 provider 配置成可调度 upstream（凭据走 credentials 引用，不要明文）。
混合通道（v0.20.0）
- 上游 = dsh 已配置的模型 provider：面板「上游」页一键「从 dsh 模型配置导入 / 刷新」，
现读
ctx.llm.listProviders()快照进<logDir>/agentos-mix.json（启用/并发/调度模型 为用户决策，随刷新保留）；密钥不出 dsh credentials——执行走进程内委托ctx.llm.stream（仅改写 provider/model），协议转换与重试全复用 dsh 既有链路。 - 会话入口：虚拟 provider
agentos-mix经ctx.llm.registerAdapter注册，模型选择器 自动出现「AgentOS 混合通道」分组：auto= 智能调度（启用上游间按余量选源，会话绑定优先）；<route>/<模型>= 选中即把当前会话绑定到该上游（TTL 6h，绑定上游禁用自动回退）。 - 并发归属上游：每上游独立并发信号量（1–64，面板热改即生效）；网关直连通道 （HTTP upstream，agentos.config.json 手填 baseUrl+凭据）的并发仍在设置页，两面平行互不影响。
配置
挂载配置由插件自带 cordis.patch.yml 自动应用（中性缺省，上游占位为 example.invalid
形态——对解析不到凭据的 upstream 按 §14.2 拒绝启用，调度端点 503 响亮失败，不炸宿主）。
个人化在 profile 层 cordis.patch.yml 写 - id: dsh-plugin-agentos + config: 覆盖
条目（整体替换语义，须写全所需键）。关键键一览（「预置」= 随包 patch 出厂值）：
| 键 | 预置/缺省 | 说明 |
|---|---|---|
port |
8391 | 网关监听端口 |
usageInjection（顶层键） |
内建缺省 off，随包预置 off（v0.20.8 起） | auto = 流式请求注入 stream_options.include_usage（上游须支持，否则身份台账 tokens 恒 0、面板 tok/s 全零）；⚠️ 放 gateway: 块内会被静默忽略。随包值收敛回 'off'（中性缺省），确需注入在 profile 层 config 覆盖条目写 usageInjection: 'auto' |
upstreams.<alias>.baseUrl |
— | 上游端点 origin |
upstreams.<alias>.apiKeyEnv |
— | 凭据引用名（ctx.credentials ref 或同名环境变量），推荐；经 credentials 按请求解析，插件不经手明文 |
upstreams.<alias>.apiKey |
— | 内联明文，仅本地测试便捷，⚠️ 随配置落盘 |
upstreams.<alias>.rewrite |
— | 路径改写。GLM 例：/v1 → /api/coding/paas/v4（编码计划端点）或 /api/paas/v4（普通 key），装反会 401/403 |
upstreams.<alias>.defaultPriority / class |
normal / big | 入队优先级 / big.LITTLE 池类 |
gateway.mode |
随包预置 enforce | enforce = 真调度（影子/降级形态见 npm run shellcheck 覆盖） |
gateway.policy |
guardian | guardian = AIMD 自适应伸缩；filler = 填泵人（AIMD 不乘减、初始即填满、队列内 WFQ——适合把临界资源钉满的单账号压测/长跑） |
gateway.concurrency |
4 | 并发 slot 数；临界资源 = 上游账号真实并发上限，按自家套餐改（v0.18.0 起可经 admin 热切键 gateway.concurrency 免重启调整） |
gateway.admissionTimeoutMs |
随包预置 30000 | 准入等待上限 |
gateway.queueHardCapMs |
随包预置 600000 | T1 队列硬顶；queueDeadlineMode: adaptive = 位置感知精细豁免 |
gateway.watchdogMs / drainMs |
随包预置 60000 / 5000 | watchdog 判 504 窗 / 优雅停机排水窗 |
retry.gate1MaxAttempts / maxTotalAttempts / absorb429Max |
随包预置 3 / 6 / 3 | 重试三层上限 |
budget.dayLimitTokens / taskLimitTokens / weights |
不限 | 日/任务限额与记账权重；热调 POST /scheduler/admin/config（免重启，重启后回配置值；weights 刻意不可热切） |
budgetEnforce |
false | true/'true' = 超限真拦（503 BUDGET_BLOCKED）；false/'false' = 影子告警不拦；其余值响亮忽略（stderr 一行告警后按 false，v0.20.8 起）。超限唯一恢复路径 = 本地时区日切 |
logDir |
不配 = 纯内存 | 落盘目录（scheduler.ndjson / budget-day.json / agentos-mix.json / agentos-upstreams.json / agentos-modules.json / gateway-token.txt） |
单账号纪律：单 upstream = 单账号一个插槽——并发是 per-upstream 信号量，同账号开两个 alias 会各自 N 并发、合计翻倍顶爆账号上限。批次优先级在同一 alias 内的 high/normal/batch 三级子队列照常生效，无需第二个 alias。
快速开始（开发与验证）
npm install # devDeps
npm run build # tsc → dist/
npm run selfcheck # 15 项断言（§14 机检 / 注入三守卫 / 身份四档 / 自健康）
npm run smoke # 29 项断言（排队/在途上限/Gate1/429 吸收/watchdog/直通/drain/单例）
npm run shellcheck # 21 项断言（插件壳：cordis 代理假宿主/路由注册/status 诊断/effect 停机/配置机检/desktop 无 webServer 形态/降级）
node scripts/mix-shell-check.mjs # 23 项断言（混合通道全链：注册/导入/热改/委托/晚挂急挂）
node --test "tests/**/*.test.mjs" # 全量单测（60 文件 / 843 用例；tests/mix/ 为混合通道 18 例）
# standalone 网关（示例配置 = agentos-sim mock 形态，随包分发）
DS_KEY=x node dist/gateway/index.js --config agentos.config.json
单元测试分布：核心调度族 tests/sched/（三队列/watchdog/absorb429）、池族 tests/p2c/
（PoolManager 18）+ tests/poolpersist/、熔断与桶 tests/p2a/（熔断器+令牌桶 40）、
AIMD tests/p2b/（36）、网关集成 tests/gateway/、身份 tests/identity/、面板路由
tests/p5/、预算 tests/p8/、混合通道 tests/mix/（18 例）、配置面 tests/midbatch/、
壳接入 tests/e-gates/ 等（全目录以 tests/ 实际为准）。
结构
v0.20.7 起按域分目录（kernel 调度内核 / upstream 上游池 / governance 治理记账 / gateway 网关 / taskmgr·console·mem·mix·tools 功能域 / util 共享叶子层 / shell 壳层件）， 顶层仅留 types/errors/version.gen 三个基础契约件与 index.ts 壳入口。
| 文件 | 内容（设计条款） |
|---|---|
src/types.ts |
跨模块唯一接口契约（ambient declarations） |
src/errors.ts |
错误契约 11 码 → HTTP + X-AgentOS-Error 码头/指纹回声（§5.12/B5） |
src/upstream/routes.ts |
alias 注册表 / 路径寻址 / 凭据引用纪律（§5.1/B6、§14.2） |
src/kernel/retry.ts |
Gate1 全语义决策 + Gate2 终态帧（§5.13/B7） |
src/kernel/scheduler.ts |
三队列 DRR / starve-aging / 自适应 deadline / watchdog / 回声窗 / 放行双闸门（熔断→令牌桶）（§5.2/5.3/5.5/5.6/5.7） |
src/kernel/proxy.ts |
forwardOnce / slot 内自旋重试 / SseTap / injectUsage 三守卫（§5.13/5.11/§6） |
src/kernel/circuit.ts |
熔断器：三态惰性翻转 / 时间+样本双窗 / half-open 单探针 / 429-4xx 不反馈（§5.7） |
src/kernel/tokenbucket.ts |
令牌桶：rate=RPM/60/1000（tokensPerMs）、burst=C、对称小 AIMD 罚与恢复窗校准面（§5.6/F13） |
src/kernel/aimd.ts |
AIMD 三通道：错误/延迟（TTFT median 双条件门控）/成功 + 429 归因（头优先+启发式）（§5.5；自含纪律：零 import） |
src/upstream/pool.ts |
PoolManager：绑定键 sess:/pfx:+盐子键 / pow2+有界负载+θ（绑定命中同样复查） / CACHE_MIGRATE 四类 / big.LITTLE 升级 / work-steal 谓词 / 池持久化（§5.8/P2.5） |
src/upstream/upstream-admin.ts |
HTTP 网关直连 upstream 的面板覆盖面：候选对象先验证后落内存、agentos-upstreams.json 原子持久化（0600）、status 明细（凭据值不出门） |
src/governance/ |
治理记账域：budget（§29.4 日/任务限额 + msUntilLocalDayReset）/ reconcile（§29.4-4 三事实对账）/ stats（AuditLog ndjson + SelfHealth）/ sentinel（C7 哨兵）/ discipline（AGENTS 纪律段）/ events（AgentosBus 总线）/ modules（七模块开关板 + agentos-modules.json 原子持久化） |
src/mix/ |
混合通道：store（覆盖文件持久化 + 导入合并保留旧值）/ scheduler（per-upstream 并发信号量 + 会话绑定 TTL 6h + auto 选源）/ adapter（虚拟 provider agentos-mix，进程内委托 ctx.llm.stream，外层零重试防叠乘）/ types |
src/gateway/core.ts |
网关启动与请求协调：单例二次探活 / 429 吸收循环 / 归因喂送 / 反馈升级 / 池路由 / fail-open / drain / admin（§5.4/5.8/5.9/12/13/14）；再导出 config 件保 API 面 |
src/gateway/config.ts |
§14 配置归一：normalizeConfig / defaultConfig / 响亮忽略通道（拆自 core，可独立加载） |
src/gateway/index.ts |
standalone CLI |
src/shell/ |
壳层件（拆自 index.ts）：budget-gates（§29.4-2 预算闸门全套）/ task-actions（面板 11 动作派发链，显式 deps 注入） |
src/util/ |
共享叶子层：num（数值归一族）/ err（errText）/ timer（sleep/sleepUnref）/ http（eqConstantTime）/ atomic-fs（FsIo + temp+rename 原子写） |
src/index.ts |
dsh 插件壳：webServer 可选探测（ctx.get('webServer')，无服务得 undefined）+ /agentos/status 诊断路由（GET/HEAD 之外的 method 405；subsystems.mounts 披露 tools/webServer/systemPrompt 三急挂面挂载态）+ effect 优雅停机 + §12.4 降级（npm run shellcheck 21 项） |
出网透明表
| 行为 | 出网目标 | 携带凭据 |
|---|---|---|
| 调度转发（核心功能） | 仅你在配置里填写的 upstream baseUrl（自选模型服务商） | 该 upstream 配置的凭据（credentials ref/环境变量按请求解析，或内联明文） |
| 容量探测（默认关） | 同上（探测开关显式开启才发；默认只 GET /models 测 RTT，不发 chat 请求） |
同上 |
| 混合通道执行 | 不出网——进程内委托 dsh 自身 provider 链路（ctx.llm.stream） |
密钥不出 dsh credentials，本插件不经手 |
| 单例探活 / 面板数据 / 审计落盘 | 127.0.0.1 loopback + 本地日志目录 | 无 |
上表即为本插件全部出网目标：无遥测上传、无版本检查、无硬编码第三方端点（源码可
grep 复核）。凭据处理细则见 SECURITY.md。
已知边界（诚实条款）
- 宿主版本：混合通道面仅在 dsh 0.2.1-rc.x 验证（
@deepseek-ai/dsh-llm 0.2.1-rc.5精确锁），未在 0.2.0 验证；网关面在 0.2.0-rc.2 实测可用。 - 激活状态：v0.20.1/v0.20.2 修复批经全量单测（843/843）+ 四路独立审查，desktop 挂载副本尚停在 0.20.0——真机复验待重启激活。
- 会话身份：网关侧会话盐身份靠
x-agentos-session头；pi-ai provider 直连暂不带头 ⇒ 该路径按身份键记（账号域公平不受影响，会话域公平降级为尽力）。 - forwardOnce signal 语义：客户端断开只标记 clientGone、不中断上游（§6 原子性）， watchdog 由协调器 Promise.race 判 504。
- 同 profile 多实例：两个 AgentOS 实例默认同端口 8391 且互认对方为 foreign
（PLUGIN_ID 相同则互认为自身——单例探活按 PLUGIN_ID 识别），后启动者按 §5.9 拒绝
接管、降级 503。要多实例并存请改
port。 - pnpm
file:副本不自动刷新：源码 rebuild 后须删 profilenode_modules副本再pnpm install。 - GLM 双端点：编码计划 key 与普通 key 各自只在自家端点有效，
rewrite.to装反会 401/403（详见cordis.patch.yml头注释与docs/host-differences.md）。 - cordis 4 ctx 代理、
dsh.clientexports 连带、Desktop webServer 提供方等宿主差异 实测备忘：docs/host-differences.md。
与 legacy 版已声明的语义差异
见 docs/INTEGRATION.md 集成清单与各文件头注释；要点：
INTERNAL 归并 UPSTREAM_FAILED、parsePath 不可寻址抛 UnknownRouteError(404)、
AuditLog.write 单参形态、identityOf 返回前缀键、/scheduler/stats 只读无鉴权
（写操作 /drain 才要 loopback+Bearer）。本插件是 dsh-plugin-agentos 名下的唯一在
维护实现（旧 legacy 实现已于 2026-10-11 退役删除）。
文档导航
| 文档 | 内容 |
|---|---|
DESIGN.md |
总设计 v2.4——唯一语义事实来源（§5 网关语义 / §27 验收矩阵 / §29–30 规划） |
设计说明.md |
设计 ↔ 代码对照 |
docs/README.md |
docs/ 编号导读（设计 → 规格 → 实现笔记 → 验收 → 史档，按序阅读） |
docs/INTEGRATION.md |
集成与验收手册（TS 重写版） |
CHANGELOG.md |
发行史（逐版：修了什么 / 为什么 / 怎么验证） |
AGENTS.md |
给 coding agent 的仓库说明书（构建/自检/挂载/纪律） |
相关插件
本插件是 DeepSeek Harness (dsh) 生态的 host 侧调度网关，与下列 已发布插件均无依赖关系、互不冲突、可同时挂载共存：它们各自解决通知、开发知识、图片、 表格、Windows 防坑与会话门控问题，而本插件专注 LLM 请求的并发调度层——装上它们之后 再装本插件，agent 打模型上游的排队、限速与开销就有了统一的收口。以下均为 GitHub 用户 Pasumao 发布的 dsh 插件：
- dsh-notify · GitHub — Windows 停机通知：agent 停止运行（完成/中止/出错/等待选择/会话关闭）时弹原生 toast，零依赖零构建。
- dsh-plugin-dev-kb · GitHub — 插件开发知识库：dsh 官方文档站完整 Markdown 镜像（中英双语）+ 仓库补充参考 + 全量搜索索引。
- dsh-plugin-image-tools · GitHub — 图片三件套：ask_user_choice 图片选择卡 / show_images 回复内嵌图片 / save_received_images 收图存文件。
- dsh-plugin-table-zoom · GitHub — 表格浮窗：markdown 表格过长/过宽时弹出可拖拽、缩放、平移的浮窗完整查看，一键复制 Markdown。
- dsh-plugin-windows-guard · GitHub — Windows 防坑：编码/路径/进程防坑 skill + 乱码检测、危险命令拦截、编码诊断修复工具。
- dsh-plugin-context-trim · GitHub — 会话注入门控：按会话取消/恢复插件贡献的 skill、tool、系统提示词段落，零依赖零配置。
- dsh-plugin-future-session · GitHub — 现实/未来会话：工具调用 fork 未来会话代执行，只回蒸馏结论（或原文并入），客户端实时同步转录。
AI 生成声明
代码与文档由 AI 辅助生成（DeepSeek Harness coding agent），均经人工审查与实机验证
（设计决策、验收记录与修复回写见 DESIGN.md 与
reports/预发布总校验-2026-11-06.md）；
docs/banner.svg 为 AI 生成素材。
No comments yet. Be the first to write one.