# dsh-preflight-estimate **Repository Path**: xiaooge/dsh-preflight-estimate ## Basic Information - **Project Name**: dsh-preflight-estimate - **Description**: dsh-plugin,出发前先报一句:这个任务大概要多久、花多少钱、分几步。跑完再对一次账。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-10 - **Last Updated**: 2026-11-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: dsh-plugin ## README # dsh-preflight-estimate **这是早期版本(0.5.x),接口、事件字段和账本格式都还会变,请按「能用、但不保证稳定」预期。** 0.5.0 重做了金额口径:一轮任务按「每步一次请求」累加、缓存命中单独计价(旧版只记最后一步,实测少记约 20 倍)。现在能给你三样东西:出发前一句话估算、结束后一笔真实账、干活途中它给自己列的路线。遇到问题请到 [Gitee 仓库的 Issues](https://gitee.com/xiaooge/dsh-preflight-estimate/issues) 留言,附上 DSH 版本号与 `/dsh-preflight-estimate-api/debug` 的输出,排查会快很多。 出发前先报一句:这个任务大概要多久、花多少钱、分几步。跑完再对一次账。 DSH 里一个任务从提问到收尾,往往要走十几步、烧掉一堆 token,但**动手之前你完全不知道代价**。这个插件只做三件事: 1. **出发前一句话** —— 会话头部出现一枚小 chip:`约 3–6 分钟 · ¥0.3–0.6 · 4 步`。点开看明细(四段步骤、耗时区间、花费区间、估算依据)。不往对话上下文里塞任何消息。 2. **结束后对账** —— 同一个 chip 变成绿色,显示这次实际花了多久、多少步、多少钱;设置页多一个「出发账本」tab,按月份列出全部记录和当月汇总。 3. **中途的路线** —— 干活的时候它会自己列一份步骤清单,chip 直接显示「走到第几步」;点开能看到完整清单(哪步做完了、哪步正在做),走岔了或者比预计多走了几步,也会当场说一声。 路线是从它自己的待办清单(`todo_write`)里读的,只读不改;没有待办清单的时候,chip 就退回显示「大概这么走」的四段式流程。 v1 刻意不做预算闸门、不做中断拦截、不做实时进度推送 —— 先把「知道自己花了多少」这件事做成。 > **第三方社区插件,非官方项目**,与 DeepSeek 无隶属或背书关系。数值均为估算,不构成报价;一切以官方账单为准。完整条款见 [DISCLAIMER.md](./DISCLAIMER.md)(责任声明 / 隐私 / 商标)。 ## 装上 从插件市场装(发布后): ```bash dsh plugin --profile desktop add dsh-preflight-estimate ``` 或者用本地 tgz: ```bash dsh plugin --profile desktop add C:\path\to\dsh-preflight-estimate-0.5.0.tgz ``` 装完重启 DSH。会话头部出现 chip 即生效;设置页 → 插件 → 出发账本可查看账本。 想从源码自己构建,见文末「开发」。 ## 数据放在哪 - 账本:`~/.dsh/profiles/desktop/preflight-ledger/YYYY-MM.jsonl`(一行一个 turn,纯本地,不上传) - 单价(可选):`~/.dsh/profiles/desktop/preflight-ledger/prices.json` ```json { "deepseek-flash": { "input": 2, "output": 8, "cacheRead": 0.04, "cacheWrite": 2 }, "deepseek-v4-pro": { "input": 9, "output": 27, "cacheRead": 0.3, "cacheWrite": 9 }, "*": { "input": 2, "output": 8, "cacheRead": 0.04, "cacheWrite": 2 } } ``` 单位是**元 / 百万 token**,`input` 指未命中缓存的输入,`cacheRead` / `cacheWrite` 是缓存命中与缓存写入的单价(不写就按 `input` 计)。模型名从会话首个 `request/header` 事件里读(`data.header.config.model`),用「模型名包含这个 key」的方式匹配,所以写短一点也能命中;`"*"` 是兜底单价,认不出的模型名也按它出金额。文件不存在时插件不会猜价格:花费显示 `—`,但耗时和步数照常估算、照常记账。 ## 估算怎么来的 一轮任务**不是一次请求**:模型每走一步都要重发整个上下文,钱是按步数累加的。0.5.0 起按这个结构算: - **上下文**:新会话从系统提示 + 工具 schema 起算(约 9k token);接着上一轮聊的,就把上一轮的上下文一起算进去(续轮首步常见 10 万–26 万 token)。 - **每步**:第一步的上下文按未命中价 + 缓存价拆开算;从第二步起,99% 以上的上下文是缓存命中,只有新出现的工具输出按未命中价算;输出每步 400–520 token 叠加。 - **步数**:先给一个宽区间。实测「提示词长度」几乎不预测步数(r≈0.08),所以区间故意给宽(提示词越长,中值越高;冷启动约 2–21 步),有历史后改用历史的 p25–p75。 - **历史校准**:同模型、`v: 2` 的历史行足够了(≥3 行),就用「实际 / 估算」的中位数给新估算乘一个校准系数(限 0.4–3 倍)。0.4.x 的旧行只记了最后一步、金额系统性偏低,**只用来算步数和耗时,不参与金额校准**。 - **记账**:`assistant/message` 每步一份 usage,按步累加;`turn/end` 重复携带最后一步时去重,不会双计。缓存命中/写入按各自单价计价。 - **精度**:金额一律保留到 0.0001 元,低于 0.01 元也不会被抹成 0。 ## 校准用的调试口 `GET /dsh-preflight-estimate-api/debug` 返回最近 60 条会话事件的 `{at, type, keys, sample}`,以及当前在跟踪的 turn 数量。`sample` 是**结构不是正文**:字符串只留长度(`string(42)`)、数组只留元素个数,数字和布尔原样保留(所以要看的 `inputTokens` 这类字段仍然可读)。装好后如果发现花费一直是 `—`,打开这个口看一眼 `assistant/message`、`turn/end` 事件里到底有没有 usage 字段,据此决定要不要补 `prices.json`。 另外两个口:`GET /dsh-preflight-estimate-api/state?sessionId=`(当前 turn 的计划与进度)、`GET /dsh-preflight-estimate-api/ledger?month=YYYY-MM`(某月账本 + 汇总)。 ## 已知边界 - 被中断的 turn 也会记一笔,标 `interrupted: true`,不计入「正常完成」的对比。 - **0.5.0 之前的账本行(`v: 1`)金额只到「最后一步」口径,比实际低一个数量级**;升级后它们仍留在账本里,当月汇总会新旧混算。想从头算干净,把旧的 `YYYY-MM.jsonl` 挪走即可(插件会新建)。 - 客户端每 2 秒轮询一次状态,payload 很小;不是推送。 - 账本目录不可写时静默降级:chip 照常工作,只是没有历史。 - 只对「新任务的首个 turn」估算,同一个任务里的后续轮次不重复弹。 - 账本文件坏了(当成目录、权限被挡、JSON 行损坏)不会拖垮任务:`/ledger` 给 500 让账本页显示「读不出来的原因 + 重试」,估算退回冷启动启发式。 ## 安全与隐私 - **只读本机、只写本机**:没有任何外发请求,没有遥测,账号与密钥完全不碰。 - **三个 HTTP 口都过宿主鉴权**:`/state`、`/ledger`、`/debug` 先调 `connection.requestRejection()`,没有登录态一律 401;拿不到鉴权服务时**直接 403**(宁可全关,不在 localhost 上裸奔)。 - **`month` 参数白名单**:只接受 `YYYY-MM`,其它一律 400 。 - **不记正文**:`/debug` 只回事件结构(字段名、长度、token 数),内存里也不保留提示词原文,只留字符数。 - **账本内容**:会话 ID、模型名、起止时间、耗时、步数、工具调用次数、token 数与金额。本机明文,请自行保护 profile 目录。 - 依赖面极小:运行时**零第三方依赖**(只用 `node:fs/promises`、`node:path`、`node:os`),`@deepseek-ai/cordis` 与 `react` 是 peer,由宿主提供。 ## 免责声明 本插件按「现状」提供,不作任何保证;所有耗时 / 步数 / 金额均为**估算**,不构成报价或承诺,一切以 DeepSeek 官方账单为准。使用风险由你自行承担。完整条款(责任限制、隐私、商标与「非官方」声明)见 [DISCLAIMER.md](./DISCLAIMER.md)。 ## 开发 想改的话从仓库拿完整源码(安装包里只带 `lib/` 和 `src/`,测试与构建脚本不进包): ```bash git clone https://gitee.com/xiaooge/dsh-preflight-estimate.git cd dsh-preflight-estimate npm install # 只有 typescript / @types / react 这几个 dev 依赖 npm run typecheck # tsc --noEmit(strict) npm run build # src/index.ts -> lib/index.js, src/client/index.tsx -> lib/client.js npm test # 假 ctx + 假 ModuleLoader 回放一个完整 turn node /scripts/validate-package.mjs . --target desktop --phase all --strict ``` `lib/` 是产物,不要手改:`npm run build` 会整份重写。宿主半边是普通 ESM;客户端半边由构建脚本包进 `window.__ModuleLoader__.load({ factory: (require) => … })`,所以源码写成正常的 TSX 模块,由 CommonJS 转译结果填充 factory。 `prototype/` 里是评审过的高保真原型(自包含 HTML,直接浏览器打开),`PROTOTYPE.md` 记录了当时确认的范围与验收标准。