@marsken/dsh-studio 0.1.9 → 0.1.11

package/AGENTS.md

@@ -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` 留退路。
 >
@@ -70,6 +72,7 @@ STUDIO_TOKEN=$(sudo journalctl -u dsh-web -n 50 | grep -o 'token=[A-Za-z0-9_-]*'
    - 先点侧栏文字进入面板，再等 `[data-dsh-studio]`
    - 切页签用 `elementHandle.click()`（Radix Tabs 不认 DOM `.click()`）
    - 断言 DOM + `pageerror` 为空，并截图留档
+   - **能创建的东西必须有能用的路径**：新加一种对象或执行方式，要同时给「怎么建」和「怎么用」两个入口，探针必须走完「创建 → 使用 → 看到结果」。反例：2026-11-14 的 shell / 数据库用例，抽屉里建得出来，但「▶ 跑」按钮只认接口用例，另外两种永远跑不了——功能加了两天没人发现。
    - **探针说「找不到元素」时，先截图再说**：面板崩掉时 React 的错误边界会把异常吞在自己的渲染树里，`pageerror` 是空的，页面上只有一行「工作空间渲染失败：xxx is not defined」。2026-11-13 连着两次把「页面崩了」误判成「选择器不对」，白跑两轮。截图 + `document.body.innerText.includes('渲染失败')` 才是判据。
 5. 涉及权限/门禁/发布的重改动，跑一遍既有 e2e 脚本并贴出数字
 6. `npm test`（条数以 `npm run check` 打印的为准，别再写死数字；覆盖范围是：`tests/repo.test.mjs` 管 manifest / 产物一致 / 宿主接口 / 领域层拆分与导入 / **导入只读绑定不许赋值** / **跨模块符号必须导入** / 迁移 / 文档 / locale / **用了 `React.` 的组件必须从 `client()` 或工厂参数拿到 `React`**；`tests/client-units.test.mjs` 用真实模块跑标签表/负责人/日期/命令面板检索这些纯函数；`tests/notify.test.mjs` 起一个本地 HTTP 桩验证飞书通知（正文归一、`botWants` 的事件矩阵、`feishuBroadcast` 只发给订阅该事件的机器人）；`tests/store-boot.test.mjs` 真的起一个 `StudioStore`，把「搬完代码启动就炸」这类问题挡在部署前。想连真数据验证：把生产库三个文件（`.db`/`-wal`/`-shm`）拷到临时目录，用 `new StudioStore()` + `await store.ready` 跑一遍，`tmp/boot-real.mjs` 就是这么写的）；`npm run check` = 语法 + 契约一把过

package/README.md

@@ -54,6 +54,7 @@ sudo systemctl restart dsh-web
 ## 开发与兼容性
 
 - 参与开发（构建链、部署、验证要求、禁区）：[AGENTS.md](AGENTS.md)
+更新日志（每版改了什么、有哪些已知限制）：[CHANGELOG.md](CHANGELOG.md)
 上手第一天（三条命令，已在全新 clone 上验证过）：[docs/quickstart.md](docs/quickstart.md)
 发布到插件市场（npm / GitHub 发版 + 收录条目 + 自查清单）：[docs/publish.md](docs/publish.md)
 - 依赖的 dsh 宿主接口、升级 runbook、兼容矩阵与已知限制：[docs/compatibility.md](docs/compatibility.md)
@@ -409,6 +410,16 @@ sudo systemctl restart dsh-web
 - `GET /costs`（工具 `studio_costs`）返回总次数、已结束次数、平均耗时，以及按专家 / 按模型 / 按提示词版本 / 按天的次数分布。
 - 边界：宿主没有把 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` 表示未知，页面显示"未接入/未知"，不能让报表看起来"很便宜"。
+
 ## 负载与燃尽（里程碑视图的轻量版）
 
 - `GET /workload`（工具 `studio_workload`）：每位专家 `running / open / done7d / overdue`，外加 `busy` 汇总——谁被压住了、谁闲着，一眼能看出来。