# DSH ACE

**突破已有想法。**

面向 **DeepSeek Harness** 的 next-move 顾问。它读最近几轮对话，只显示**一张卡**：先复述你在回应的那件事，再点出背后那条线、它还会在哪冒出来，最后给一个能验收的小动作。按 `Tab` 只填最后那个动作，发不发由你决定。

[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Tests](https://github.com/Ghoscro/dsh-ace/actions/workflows/test.yml/badge.svg)](https://github.com/Ghoscro/dsh-ace/actions/workflows/test.yml)

[English](README.md)

![ACE Move 示例](docs/demo.svg)

> 这是渲染示例，不是录屏。首次发布前会换成真实录屏。

**一句话差别：** 补全猜你会打什么；ACE 把一件具体的事重新排一遍——读完的反应是"对哦，我怎么没想到"，不是"啥意思"。赢不过顺手继续就不出卡。

## 安装

npm 上 `dsh-ace` 已被无关项目占用，包名是 `@ghoscro/dsh-ace`。在正式发 npm 之前，[Releases](https://github.com/Ghoscro/dsh-ace/releases) 里的 tarball 就是安装路径：

```bash
# 在 DSH profile 目录里
pnpm add file:/绝对路径/ghoscro-dsh-ace-0.5.23.tgz
```

然后把 `"@ghoscro/dsh-ace"` 加进 `dsh.profile.bundles`，在 profile 里 materialize（DSH 插件页或 `pnpm install`），重启 DSH。composer 工具行会出现 **✦ 深度预测**。

开发者安装（把本目录拷进 `sakura/packages/`）放在 [INSTALL.md](INSTALL.md) 末尾。已验证宿主：**DSH 0.2.1-rc.2**，其他版本未验证。

## 它做什么

大多数下一句工具优化的是**你大概会打什么**。ACE 优化的是**这一下值不值得发**，以及它能不能让你自己想到下一层。

**四拍卡：**

> 你刚说 X → 背后其实是 Y → 所以 Z 也会这样 → 先试 W，出现某某结果就说明我错了

默认只显示 **W**（那句能直接发出去的）。X/Y/Z、人话三行和"错了会这样"点卡片底部的**显示详情**展开——一张卡先回答"发不发"，再回答"为什么"。

- **X** 用你自己的词复述那件具体的事（通常是助手最后一句里你在回应的那句）。
- **Y** 一句人话说清那条关系：它为什么成、为什么坏。抽象词最多一个。
- **Z** 同一个机制还在哪冒头。表面不像的类比，卡上必须单独一行写"这跟那个是怎么对上的"；写不出来这一拍判零。
- **W** 今天就能验收的小动作。工程师给文件、命令、测试；不写代码的人给一件能亲眼确认的事（"刷新一下，看右上角还报不报红"）。
- **错了会这样**：写明什么结果能推翻它。

**人话三行（每张卡都有）：**

- **现在**：发生了什么、卡在哪，用你看得见的现象说，不写内部机制。
- **目的**：这一步为了拿到什么结果，不是要做什么动作。
- **做完**：你会看到或拿到什么，够你自己判断"这是不是我要的"。

缺一行，这张卡就不出。王牌预测也一样：可以大胆，但 Tab 进去的那句必须让当前水平的用户读懂，不堆没解释的术语。

- 内部生成 3 个不同方向：推进、用现成工具、重新框定、验证、澄清、收范围、收尾。
- 按 `value`、`novelty`、`worth_extra_step` 和动作类型打分；关系那一拍不由模型打分——表面像不用写，表面不像必须有一句"这跟那个是怎么对上的"，没写、或只是把 X/Z 重写一遍，宿主直接不出卡。
- **看人下菜：** 卡片会读用户自己的话判断技术程度——新手用日常语言、一次一个动作；工程师直接用术语。可以在插件配置里用 `level` 强制指定。
- 默认模式回应助手最后一句里的某句话（`reply_to` 逐字引用），但挑的是值得发的那个回法，不是最顺手的那个。
- 只显示**一条**，带 X/Y/Z/W 和"错了会这样"。
- 没有一条比顺手“继续”更好时，**不出卡**。安静是功能，不是故障。
- `Tab` 只填写 W；ACE 不会替你发送。

## 输入框里

ACE 不只在卡片里工作：

- 打字时输入框光标处出现**半透明的续写**，`Tab` 收下。
- `` ` ``（反引号）或 `F1` 开关续写；`F1` 每按一次还会打一行诊断，最新的在最下面。
- `Alt+1` … `Alt+4` 选卡片里的备选行；`Escape` 关掉卡片或设置面板。
- 当前加载的版本挂在 `<html data-ace-version>` 上，报问题时带上它。

## 演示

上图是目标闭环：

1. 助手问“要不要跑全量？”
2. 最顺手的下一句是“跑吧”。
3. 卡片四拍：X“要不要跑全量” → Y 重试会把偶发失败吞掉，全量只是把概率摊薄 → Z 上传失败自动重传、CI 里的 flaky 重跑也是同一个机制 → W“把重试去掉，只跑这个用例一次”。
4. 卡片还写清“错了会这样”：去掉重试一次通过不足以下结论；多次对照仍未增加失败率，会削弱重试掩盖问题的解释，但仍不能排除低概率竞态。
5. `Tab` 只填入 W，你决定发不发。

## 快速开始

1. 按上面的安装方式装好，重启 DSH。
2. 打开对话，工具行出现 **✦ 深度预测**；点它，或等下一轮完成（如果开了自动 ACE）。
3. 在卡片上按 `Tab` 填入草稿。

从 `dsh-composer-predict` 迁移，先读 [MIGRATION.md](MIGRATION.md)，不要同时加载两个包。

**没有卡不是坏了。** 那说明这一轮没有哪条比顺手"继续"更值得发。静默轮记为 `no-card`，分数线用 `npm run sweep` 离线扫，别拿线上真聊试。

## 三个案例

这些是示例，不是受控 benchmark。它们展示 ACE 想增加的价值。

### 1. 可能被重试掩盖的测试

- **X 你刚说：** 助手问“要不要跑全量？”
- **Y 背后：** 重试把偶发失败吞掉了，全量只是把概率摊薄。
- **Z 还会：** 上传失败自动重传、CI 里的 flaky 重跑——都是同一个机制。
- **W 先试：** “把重试去掉，只跑这个用例一次。”
- **错了会这样：** 一次通过不足以下结论；多次对照仍未增加失败率，会削弱重试掩盖问题的解释，但仍不能排除低概率竞态。
- **风险：** 可能因为无关原因失败。

### 2. 更省事的实现路径

- **顺手：** “写个小脚本批量处理。”
- **ACE Move：** “直接用现有 CLI 的 `--json` 输出接管道；不新增要维护的脚本。”
- **多得到什么：** 更小的维护面，更短到结果的路径。
- **风险：** CLI 可能没有你要的字段。

### 3. 做偏了的任务

- **顺手：** “继续打磨当前卡片。”
- **ACE Move：** “卡点不在卡片，新 profile 上安装仍然失败。先修安装，再做视觉。”
- **多得到什么：** 指出真正的约束，改变工作顺序。
- **风险：** 安装失败可能只在特定环境出现。

## 工作方式

1. 浏览器把最近对话和 session `cwd` 发给宿主路由。
2. 宿主构建只读、截断的证据包：`git` 的 status、diff stat、last commit、bounded diff，加上项目顶层目录树和依赖/脚本名——结构性判断要落到真实模块上。
3. 本地生成确定性 situation（最后用户目标、助手 offer、显式约束），不再单独调用 situation 模型。
4. 一次**生成调用**返回 3 条候选和一行选择；宿主按分数选出唯一一条。`verify`/`constrain` 有惩罚，“再检查一下”不能默认胜出。
5. 选中的那条再经过一次**有边界的校核调用**：X/Y/Z、关系、类比和反证都要对着证据站得住；站不住就拒绝出卡，而不是悄悄降级成普通补全。
6. 最高分低于阈值时，不出卡。
7. `Tab` 填入草稿；卡片里的 `why`/`evidence`/`risk` 不随消息发送。

解析器按花括号扫描 JSON 对象，遇到截断/坏行会跳过，但保留前面有效候选。一行坏了不会拖垮整次响应。

## 设置与成本

- **模式：** 保守安全 / 常规推理 / 脑暴思维 / 王牌预测（英文界面显示 ACE），四种地位平等，不是音量键。每种改的是 prompt 策略和输出预算，卡片上标出当前模式，设置里切换；任何模式都不会被暗中收敛成保守。
- **缓存：** 规则和语气样本组成逐字相同的开头，对话是追加而不是每轮重新开窗，只有末尾易变的部分（模式、处境、证据）在变，所以提供方的自动前缀缓存能命中大部分 prompt。
- **自动 ACE：** 每轮完成后生成一条；可在「深度预测设置」里关闭。
- **字号：** 设置面板里一个滑块，改 `--dsh-fs-w` / `--dsh-fs-meta` / `--dsh-fs-x` 三个 CSS 变量；值存 `chrome.storage.local`（容器没有扩展 API 时退回 `localStorage`），直接挂在 `documentElement` 上，调字号不用重打包。
- **暂停：** 停止自动建议；`✦ 深度预测` 仍可按需使用。
- **模型：** 使用当前 DSH agent default，或插件配置的 route。
- **隐私：** 最近对话和本地证据包会发给选中的模型，不回写 DSH 会话。`captureSamples: false` 只关闭预测样本；`ledger: false` 单独关闭本地对话账本。开关不会删除已有文件。“毙掉”反馈、用量和错误诊断是另外的本地记录，这不是零留存模式。
- **账本：** 每个会话留一份只追加的记录，prompt 从这份记录重建，前缀只会变长；超过 `ledgerMaxEntries` 时最旧的部分写到归档文件，并用确定性摘要顶上。`ledger: false` 关掉。
- **样本：** 最近 50 次深度预测的候选、原始回答和最后一条用户消息留在 `diagnostics/dsh-ace-samples.jsonl`；`npm run sweep` 离线按各档分数线重算，不调用模型。
- **记账：** 每次预测往 `diagnostics/dsh-ace-usage.jsonl` 追加一行，带会话、轮次、token、缓存命中和按 `pricing` 折算的钱。
- **成本：** 通常每张卡两次模型调用：生成候选，再校核选中的创意；格式恢复可能再加一次生成。旧的单次调用价格估算不再适用。校核增加 token 和等待时间，不等于独立事实核验。
- **输出预算：** `safe` 1600、`standard` 2600、`brainstorm` 3200、`wild` 3600 tokens，并受 `expertMaxTokens` 限制；重试与校核各最多 2400 tokens。这些是输出上限，不是整轮用量估算。
- **等待与校核：** 界面显示已等秒数，不根据秒数推断后端阶段。校核超时保留卡片并显示“尚未完成校核”，内容校核拒绝则不出卡。默认模型阶段预算为生成 25 秒 + 可选重试 12 秒 + 校核 12 秒，历史加载和证据收集另需时间；浏览器在 58 秒取消 expert 请求。这些上限不代表实际响应速度承诺。
- **试用反馈：** 用[试用与耗时记录](docs/trial-feedback.md)区分安装、等待和创意质量问题。重启只加载已经安装的包，不会自动下载新版本。

## 开发

```bash
npm test
```

在运行中的 DSH 上测真实 token 用量。macOS / Linux：

```bash
COMPOSER_PREDICT_BASE=http://127.0.0.1:13770 node scripts/token-tiers.mjs
```

Windows（PowerShell）：

```powershell
$env:COMPOSER_PREDICT_BASE='http://127.0.0.1:13770'
node scripts/token-tiers.mjs
```

覆盖 prompt/parser、JSONL 坏行保留、选卡打分、不出卡、路由响应和单卡交互。兼容范围写在 `package.json.dsh.compatibility`；未列出的版本按未验证处理。

## 卸载

从 profile 移除 bundle 和依赖，重启 DSH，再删除包目录。旧 `composer-predict` 路由和设置键保留用于迁移；卸载新包不会删除本地设置。

## 作者

**micker 的 DSH 插件作品。**

## 许可证

[MIT](LICENSE)。贡献使用 DCO sign-off，不引入 CLA。见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [SECURITY.md](SECURITY.md)。