@marsken/dsh-studio 0.1.10 → 0.1.12

package/AGENTS.md

@@ -7,7 +7,7 @@
 | 路径 | 是什么 | 谁能改 |
 | --- | --- | --- |
 | `index.js` | 宿主半边：`apply(ctx)`、39 个 `studio_*` 工具、`/studio-api/*` 路由、SQLite 存储、派单引擎、门禁 | ✅ 直接改 |
-| `src/host/*.js` | 宿主层模块：`cases.js`（跨卡用例聚合与回归汇总：`collectCases` / `groupCaseKeys` / `summarizeRun`，纯函数）、`team-memory.js`（专家团的团级记忆，存 side 键）、`quality.js`（AI 质量：返工识别与按专家汇总，纯函数）、`gitlab-facts.js`（执行记录 vs MR 事实的对账，纯函数）、`impact.js`（需求改版的影响面：受影响的卡与要重跑的用例，纯函数）、`design.js`（设计评审记录与进开发前的闸门，纯函数）、`shell-runner.js`（shell 用例执行器，默认关闭）、`shell-case.js`（shell 用例的数据形状，纯函数）、`runners.js`（用例执行器注册表：match + run，加新执行方式不用动 runOneCase）、`limits.js`（数量上限的默认值与清洗，可配置）、`db-runner.js`（SQLite 用例执行器与数据形状，默认关闭）、`events.js`（进程内事件总线，同步扇出）、`webhooks.js`（事件 → 出站 webhook，失败不重试）、`domain.js`（板列/数据形状/`sanitize*`/默认配置，纯函数）、`dispatcher.js`（派单引擎）、`executor.js`（用例执行、代码事实核对、健康检查）、`store.js`（`StudioStore`/`SecretStore`：SQLite 台账 + 快照 + 登录会话）、`integrations.js`（GitLab / 飞书 / 平台健康）、`routes/*.js`（按前缀拆出的 HTTP 处理：`exports.js` 导出 CSV、`auth.js` 统一登录、`tasks.js` 卡片/专家/列、`requirements.js` 需求/文档/公开提单、`releases.js` 版本/灰度/部署、`insights.js` 指标与工作台、`skills.js` 技能库读写上传、`admin.js` 配置/权限成员/审计/快照、`connect.js` 市场/集成健康/GitLab/仓库/飞书、`agents.js` 派单运行态与起停、`coding.js` 执行记录/失败重试/worktree/项目配置、`tools.js` 39 个 `studio_*` 工具） | ✅ 直接改，新逻辑优先放这里 |
+| `src/host/*.js` | 宿主层模块：`cases.js`（跨卡用例聚合与回归汇总：`collectCases` / `groupCaseKeys` / `summarizeRun`，纯函数）、`team-memory.js`（专家团的团级记忆，存 side 键）、`quality.js`（AI 质量：返工识别与按专家汇总，纯函数）、`gitlab-facts.js`（执行记录 vs MR 事实的对账，纯函数）、`impact.js`（需求改版的影响面：受影响的卡与要重跑的用例，纯函数）、`design.js`（设计评审记录与进开发前的闸门，纯函数）、`shell-runner.js`（shell 用例执行器，默认关闭）、`shell-case.js`（shell 用例的数据形状，纯函数）、`runners.js`（用例执行器注册表：match + run，加新执行方式不用动 runOneCase）、`limits.js`（数量上限的默认值与清洗，可配置）、`db-runner.js`（SQLite 用例执行器与数据形状，默认关闭）、`usage.js`（会话用量解析与计价，纯函数）、`session-usage.js`（读 session.v4 日志并按卡/专家汇总）、`events.js`（进程内事件总线，同步扇出）、`webhooks.js`（事件 → 出站 webhook，失败不重试）、`domain.js`（板列/数据形状/`sanitize*`/默认配置，纯函数）、`dispatcher.js`（派单引擎）、`executor.js`（用例执行、代码事实核对、健康检查）、`store.js`（`StudioStore`/`SecretStore`：SQLite 台账 + 快照 + 登录会话）、`integrations.js`（GitLab / 飞书 / 平台健康）、`routes/*.js`（按前缀拆出的 HTTP 处理：`exports.js` 导出 CSV、`auth.js` 统一登录、`tasks.js` 卡片/专家/列、`requirements.js` 需求/文档/公开提单、`releases.js` 版本/灰度/部署、`insights.js` 指标与工作台、`skills.js` 技能库读写上传、`admin.js` 配置/权限成员/审计/快照、`connect.js` 市场/集成健康/GitLab/仓库/飞书、`agents.js` 派单运行态与起停、`coding.js` 执行记录/失败重试/worktree/项目配置、`tools.js` 39 个 `studio_*` 工具） | ✅ 直接改，新逻辑优先放这里 |
 | `client.src.js` | 浏览器半边的手写源码（通过 `window.__ModuleLoader__` 注册面板） | ✅ 直接改（前端逻辑） |
 | `web/src/**` | shadcn/Radix 组件、样式、`legacy.js` 桥；`web/src/studio/*.js` 是从 `client.src.js` 抬出来的纯模块（`markdown.js` 渲染器、`format.js` 日期格式、`labels.js` 标签表、`roster.js` 负责人与候选人、`fields.js` 表单适配层、`shell.js` 共享抽屉、`card.js` 看板卡片、`board.js` 看板本体、`mentions.js` @ 选择器、`cases.js` 多步用例解析、`drawer.js` 卡片详情抽屉、`editor.js` 通用编辑器、`palette.js` 命令面板（⌘K 全局搜索卡片/需求/版本/专家/专家团/项目/技能 + 动作项 + Ctrl/⌘+Alt+Shift+N/T/D 全局快捷键；带 Shift 是为了避开宿主的 Ctrl+Alt+N 新会话）、`charts.js` 进度条与燃尽图、`context.js` 共享上下文（`provideClient`/`client`）、`panels/*.js` 设置页 17 个面板、`pages/*.js` 六个页面组件（看板之外的工作台/需求/用例/版本/效能/自助提单）；**`StudioPage` 是组合根，故意留在 `client.src.js`**，它负责顶栏、页签与「＋ 新建」菜单并调用 `provideClient()`，别为了行数把它搬走），由 `make-legacy` 生成的 `legacy.js` 顶部统一 import | ✅ 直接改（样式与组件） |
 | `dist/client.js` | `pnpm build` 的产物（单文件 IIFE，注意在仓库根 `dist/`，不是 `web/dist/`） | ❌ 生成物 |
@@ -53,7 +53,9 @@ STUDIO_TOKEN=$(sudo journalctl -u dsh-web -n 50 | grep -o 'token=[A-Za-z0-9_-]*'
 ```
 
 > `tools/deploy.mjs` 会打印 `active=` / `files=` / `state=`，`active` 不是 active 就以非零退出。
-> 它依赖 `ssh2`（devDependency，只给部署用，不进插件运行时）；`tools/visual/smoke.mjs` 依赖 `puppeteer-core`（同样只在 devDependencies 里），浏览器用系统 Chrome，可用 `CHROME_PATH` 指定。
+> 它依赖 `ssh2`（devDependency，只给部署用，不进插件运行时）；`tools/mock-gitlab.mjs` 是本地 GitLab 打桩（三个接口，3 文件 / 3 提交），配合 `tools/verify-gitlab-facts.mjs` 可以在没有真实令牌时把「MR 事实 → 与自报值对账」整条链跑通：`node tools/mock-gitlab.mjs` + `STUDIO_BASE=<host> node tools/verify-gitlab-facts.mjs`。
+
+`tools/visual/smoke.mjs` 依赖 `puppeteer-core`（同样只在 devDependencies 里），浏览器用系统 Chrome，可用 `CHROME_PATH` 指定。
 
 > 目标机上那个老的 `deploy-all.sh` 只作兜底（它拷 `/tmp/` 下的两个文件和 `src/`）。日常用 `tools/deploy.mjs`，别再手工 scp 拼路径。改了 `package.json`（包头、`engines`、`dsh.*`、`files`）、`cordis.patch.yml`、`locale/*.json` 时必须单独上传到插件目录（`~/dsh-studio/` 或 profile 的 `node_modules` 下）再重启，否则改了个寂寞。改动前先 `cp package.json /tmp/package.json.bak` 留退路。
 >

package/README.md

@@ -408,7 +408,27 @@ sudo systemctl restart dsh-web
 - 每位专家的提示词会算一个 `promptVersion`（提示词内容的 sha1 前 8 位），存进专家配置；专家改了提示词，版本号就变。
 - 每次派单成功（`deliver` 之后）记一条运行日志：任务、会话、专家、模型、提示词版本、开始时间；会话 settle 时补上结束时间与耗时（`RUN_LOG` 最多留 300 条）。
 - `GET /costs`（工具 `studio_costs`）返回总次数、已结束次数、平均耗时，以及按专家 / 按模型 / 按提示词版本 / 按天的次数分布。
-- 边界：宿主没有把 token 用量回传给插件，所以这里统计的是**次数与时长**，不是钱；要算钱得等宿主暴露用量。
+- **真实 token 用量（0.1.12 起）**：`GET /costs` 多了 `usage` 段——直接读 `~/.dsh/sessions/*/studio-*/session.v4.jsonl.zstd` 里每次模型调用的 `usage`（入/出/缓存读/缓存写），按卡、按专家汇总。效能页的「AI 执行成本」会显示 `token 用量` 与 `预估花费`。
+- 花钱要配价目表（元 / 百万 token，空表只报 token 不报钱）：
+
+  ```json
+  { "costs": { "prices": [
+    { "model": "deepseek-v4.1-flash", "input": 2, "output": 8, "cacheRead": 0.2 }
+  ] } }
+  ```
+
+  **实测**（线上 3045 次调用 / 2.42 亿 token）：配价目表后算出 ¥81.47，其中 719 次调用因模型没配价目记「未知」；清空价目表后花费显示 `null`（未知），不会按 0 算。
+- 口径见上一节七条；订阅通道（`*-coding` / `*-token-plan`）记 token、不计钱。
+
+### 成本口径（接真实用量之前先定死，免得以后对不上账）
+
+1. **只统计本平台的会话**：`studio-<taskId>-<expertId>`。你自己在 DSH 里开的会话不算，哪怕用的是同一个模型。
+2. **订阅套餐通道不计钱，只计 token**：模型 id 以 `-coding` / `-token-plan` 结尾的走订阅额度，成本记 0，token 照记——否则会把"包月"算成"每次都在烧钱"。
+3. **按 turn 记，不按会话记**：一次派单可能追加多轮，钱是按 turn 出的。
+4. **三级汇总**：卡（taskId）→ 专家（expertId）→ 项目（project）；卡的成本是它所有 turn 之和，专家的是他所有卡之和，项目的是它所有卡之和。
+5. **缓存命中要分开记**：命中 cache 的输入 token 单价通常低一个量级，混在一起算会高估。拿不到就标"未知"，不要按 0 算。
+6. **价目表跟着日期走**：模型调价后，历史记录按当时单价算，不重算——所以每条记录要存 `{ at, model, inputTokens, outputTokens, cacheHitTokens, unitPrice }`。
+7. **拿不到用量就不写 0**：`cost: null` 表示未知，页面显示"未接入/未知"，不能让报表看起来"很便宜"。
 
 ## 负载与燃尽（里程碑视图的轻量版）