@dsh-external/dsh-self-analyze

Readme

# @dsh-external/dsh-self-analyze

会话自我分析插件，分两层：

1. **命令 `/analyze`**（你手动触发的"入口"）：把整段会话各轮数据 + 复盘指令喂给模型，唤醒一轮模型自我分析回合，复盘正文由模型生成并展示为下一条 assistant 消息。
2. **工具 `self_analyze`**（给模型自助查证）：模型在复盘中发现某轮消耗偏高时，自己调工具查——不用你再敲命令、附加提示字。

装配：**官方 bundle**（`cordis.patch.yml` 自激活，加入 profile 的 `dsh.profile.bundles`），重启即装。

## 用法

### 命令（你在 Web 输入框敲）
- `/analyze` —— 触发**整段会话**自我复盘。
- `/analyze <n>` —— 触发**第 n 轮**聚焦复盘。

命令是**极简触发**，不塞长提示词：只注入一句简短指令并唤醒一轮模型回合。
关键保证：命令会在该 agent 的 `agent.ctx` 上执行 `tools.restrict({ allow: ['self_analyze'] })`，
让**复盘这一轮里模型唯一可调的工具就是 `self_analyze`**——逼它必须先调用工具读取真实
token/费用/过程数据，再输出复盘，而不是凭记忆空总结。复盘回合结束（`agent.whenIdle`）后
自动解除限制（并以 120s 定时器兜底，避免限制残留）。若 restrict 因故失败则降级为普通复盘回合。

### 工具（模型调用）
`self_analyze`，参数：
- `scope: "overview"` —— 各轮 token/费用/状态/步数/工具 总览 + 会话累计
- `scope: "turn", turn: <n>` —— 该轮完整过程（提示词 → 每步模型输出 → 工具调用参数）+ 该轮 token/费用

模型可凭 `/analyze` 触发后在复盘里自主调用 `self_analyze` 深挖某个高消耗轮次。

## 费用

内置与 dsh-billing 一致的官方 DeepSeek 价格表与 `rateAt` 逻辑（含 2026-08-17 起峰谷价），
**不 import、不依赖 dsh-billing 是否安装**——自包含、可独立发布。费用按每个 `(turn,step)` 的
模型名 + 实际时间折算，逐轮/逐步聚合，口径可与 dsh-billing 的整会话费用交叉校验。

单价默认**启动时从官方价格页在线同步**（`https://api-docs.deepseek.com/zh-cn/quick_start/pricing/`），
失败退避重试并回退内置默认；可通过 `config.priceSync` 关闭或改源。

token 口径：`assistant/chunk` usage 分片为主，`assistant/message.usage` 兜底（与 session-stats 一致）。

## 可选配置

profile `cordis.patch.yml` 覆盖（全部可选，有默认值）：

```yaml
- id: dsh-self-analyze
  name: '@dsh-external/dsh-self-analyze'
  config:
    promptPreviewChars: 120    # 总览里每轮任务提示词预览上限
    stepPreviewChars: 400      # 单轮每步模型输出预览上限
    toolArgsPreviewChars: 160  # 单轮工具参数摘要上限
    priceSync:
      enabled: true             # 官方价格在线同步开关
      url: https://api-docs.deepseek.com/zh-cn/quick_start/pricing/
      intervalMs: 43200000      # 同步周期（12h）
      timeoutMs: 15000
```

## 安装（给他人）

> 包名是作用域名 **`@dsh-external/dsh-self-analyze`**（带 `@`），不是 `dsh-self-analyze`。
> 装配时必须全程用完整作用域名（作为 profile `dependencies` 的键、`dsh.profile.bundles` 的项、
> 以及 `cordis.patch.yml` 的 `name:`），三者一致。若误用无作用域名 `dsh-self-analyze`，
> pnpm 只会生成 `node_modules/dsh-self-analyze`，而 patch 的
> `name: '@dsh-external/dsh-self-analyze'` 会因解析不到作用域包而装配失败。

这是标准的 DSH 外部 bundle 源码包，构建后按官方 profile bundle 装配：

```bash
# 1. 装 dev 依赖（build.sh 会 link 到 dsh 源码仓库取编译类型来源）
npm install
# 2. 构建 src → lib（自动 probe DSH_CHECKOUT）
DSH_CHECKOUT=<你的 dsh 源码仓库目录> bash scripts/build.sh
# 3. 装配进 profile（任选其一）：
#    A. 注入器环境：dev_build_plugin <本目录> → dev_install_package <本目录>
#    B. 手动：在 profile 的 package.json 里
#         dependencies 加  "@dsh-external/dsh-self-analyze": "link:/绝对路径/dsh-self-analyze"
#         dsh.profile.bundles 加 "@dsh-external/dsh-self-analyze"
#         再 pnpm install（生成 node_modules/@dsh-external/dsh-self-analyze 链接）
```

装配后重启即在 Web 输入框可用 `/analyze`，模型也自动获得 `self_analyze` 工具。

### 配置说明（对应 `cordis.patch.yml`）

插件行的 `config:` 里已用注释给出了全部可选键及其默认值（见仓库内 `cordis.patch.yml`），
需要调参直接照注释去掉 `#` 改值即可；`priceSync` 控制官方价格在线同步（默认开启）。

## 维护提示

- 价格表集中在文件顶部 `DEFAULT_PRICING` / `DEFAULT_FALLBACK_PRICE` / `rateAt`；在线同步逻辑在
  `htmlTables`/`parsePricingHtml` 与 `apply()` 的 `priceSync` 块。内置价保持与官方一致，在线价覆盖。
- 改源码后：`dev_build_plugin <目录>` 再用 `dev_reload_package <子串>` 重载即可热生效；重启后由 bundles 装配保持同样代码。