# DeepSeek Harness Reckoner

面向 DeepSeek Harness 的确定性计算引擎：公式由模型书写，数值规则由引擎掌握。

[English](README.md)

## 目录

- [安装](#安装)
- [Reckoner 模式](#reckoner-模式)
- [计算引擎](#计算引擎)
- [记录](#记录)
- [文章生成](#文章生成)
- [配置](#配置)
- [文档](#文档)
- [许可](#许可)

## 安装

```sh
dsh plugin --profile <profile> add dsh-reckoner
```

本地检出改用路径安装：`dsh plugin --profile <profile> add link:<path>`。

1. 该命令把 `dsh-reckoner` 追加进 profile 的 `dsh.profile.bundles`。
2. profile 启动时合并本包自带的 `dsh.bundle.patch`，即 `cordis.patch.yml`。
3. 该 patch 插入插件行。

## Reckoner 模式

本包附带两个智能体预设。会话在创建时选定其一：除非问题需要外部事实，否则选纯粹的 `reckoner` 预设。会话一旦产出过内容，就无法再换预设。

| 预设 | id | 计算沙箱 | 外部检索 |
|---|---|---|---|
| **Reckoner** | `reckoner` | 六个插件工具，无网络 | 无 |
| **Reckoner with search** | `reckoner-with-search` | 同样的六个工具，外加 `search` | 一次一个事实，连同出处写进记录 |

### 纯粹预设

- **工具面**：只有六个插件工具；没有 shell、文件系统、网络与子代理
- **数字来源**：`set` 转录的值，或 `eval` 产生的结果
- **缺失的量**：人设停下并指明该量
- **提问承载**：每个提问都开启一条记录

记录中的引擎是可选的：需要数字的部分由 `set` 与 `eval` 承载，不需要数字的提问由记录自身的说明文字作答。

### 检索预设

- **工具面**：六个工具，外加恰好一个工具 `search`，别无其他
- **通用检索**：`web_search` 与 `web_fetch` 两个预设都不挂载
- **后果**：模型永远无法自行检索或抓取
- **一次检索接收**：一个问题
- **一次检索交给模型**：一句答案，仅文字；查询词、页面与出处都不给它

记录保存模型看不到的东西：问题、提供方返回的每一个候选出处、策略允许的出处，以及写出答案的抽取步骤所用的路由与提示词版本。检索策略就是该预设行的配置：严格层级只保留允许列表上的参考资料主机，一条记录默认最多四次检索。

插件每次挂载都会把两个预设目录复制到 `$DSH_HOME/.agent-presets/`。两个预设都只提供人设，因为插件本身由 bundle patch 全局挂载。

## 计算引擎

每个宿主进程只有一个引擎，所有会话的工具调用都作用于它。它是一台不含领域知识的计算器：没有求解器、没有注册表、没有具名公式。模型写下的公式说明各单位如何组合，引擎在求值时检查这些单位，因此量纲对不上的结果会被拒绝，而不是被算出来。

| 工具 | 作用 |
|---|---|
| `set` | 写入一个槽；`value: null` 删除该槽 |
| `get` | 读回一个槽；这是读取值的唯一方式 |
| `eval` | 把一条公式的结果写入 `target` 指定的槽 |
| `record_start` / `record_message` / `record_end` | 开启、批注并封闭一条记录 |

- **值**：数字、复数、数组或对象，各带一个由 7 个整数指数构成的 SI 向量；`dim` 为它命名，可以写成 `ohm` 这样的表名，也可以写成那 7 个整数。
- **公式**：一条作用于各槽的表达式，含 `+ - * / ^`、一组 `$` 函数与求和；没有比较、逻辑与赋值。
- **回执**：每次调用返回 `{ok: true, ...}` 或 `{ok: false, code, error}`；被拒绝的调用不改变任何状态。

完整参考——值类型、记法、量纲规则、磁盘上的记录与 HTTP 路径——见[引擎手册](docs/engine.zh-CN.md)（[English](docs/engine.md)）。

## 记录

一条记录就是一次计算的过程：标题、求解所依据的条件、过程中的说明、求值步骤与可选的结束语。

| 标记 | 作用 | 何时被拒 |
|---|---|---|
| `record_start {title}` | 开启一条记录 | 记录已开启时 |
| `record_message {text, hide?}` | 一条说明，数量不限 | 从不 |
| `record_end {text?}` | 封闭记录并写入磁盘 | 无记录时 |

`hide: true` 使该说明不进记录视图，但文章生成仍会收到它。`set`、`get`、`eval` 在没有记录时一律被拒绝；封闭记录会清空槽表，因此槽表非空恰好等价于存在一条未封闭的记录。

- 未封闭的记录在 `<home>/open-record.jsonl`；封闭时该文件被重命名为 `<home>/records/<id>.jsonl`，因此封闭的记录总是完整的。
- 没有索引文件：列表就是目录本身。记录文件的格式见[引擎手册](docs/engine.zh-CN.md#7-记录与轨迹)。

### 面板

**Reckoner** 面板即同名侧边栏入口。它有两个标签页。

- **记录**：已封闭的记录、置顶的未封闭记录，以及可删除的不可读文件。打开记录即进入其时间线，每个步骤一张卡片；**显示全部** 还会显示被拒的步骤与隐藏的说明，并记住该选择。
- **设置**：每种文章格式的生成默认值、检索策略，以及上述显示偏好。有改动等待宿主重启时显示一行。

## 文章生成

每条已封闭的记录都可以写成一篇独立的文章。宿主侧 LLM 调用以纯文本接收记录事实：标题、仍然成立的条件、按 `seq` 顺序交错的说明与求值步骤、结束语；数字截到最多四位小数，`hide: true` 的说明以作者注交给写作者且不得写进文章。产品名只出现在固定标题 `DeepSeek Harness Reckoner Solution` 与固定作者行中。

| 格式 | 产物 |
|---|---|
| Markdown | 平铺的 `.md` 文件，从不编译 |
| LaTeX | `.tex` 源文件写入以文件名命名的目录，按需编译为 PDF |

每种格式各自记住自己的输出目录与语言，LaTeX 还会记住是否编译：设置对话框以该格式记住的值打开，设置标签页编辑的是同一批值。文件名默认由记录标识符预填。PDF 编译交由 latexmk 或 MiKTeX 的 texify 完成，并需要 `xelatex` 引擎；勾选编译而没有可用驱动或引擎时，「生成」按钮禁用，对话框指明缺少的部分。

## 配置

| 设置 | 含义 |
|---|---|
| `DSH_RECKONER_HOME` | 插件主目录，默认 `~/.dsh-reckoner` |
| `DSH_RECKONER_LOG_LEVEL` | `debug`、`info`、`warn`、`error` 或 `off`；默认 `info` |

主目录存放未封闭的记录（`open-record.jsonl`）、已封闭的记录（`records/<id>.jsonl`）、插件状态与日志（`logs/<YYYY-MM-DD_HH-mm-ss.SSS>.log`，每次插件挂载一个文件）。状态文件 `state.json` 是一棵树：每个会记忆设置的模块一个子树，外加扁平的 `restartRequired` 标记。

## 文档

| 文档 | 内容 |
|---|---|
| [引擎手册](docs/engine.zh-CN.md)（[English](docs/engine.md)） | 引擎的长篇参考 |
| [reckoner-interface](skills/reckoner-interface.md)、[reckoner-template](skills/reckoner-template.md) | Reckoner 模式下智能体所读的手册 |
| [参与贡献](docs/CONTRIBUTING.zh-CN.md)（[English](.github/CONTRIBUTING.md)） | 环境搭建、提交规范、发布流程 |

## 许可

MIT。Copyright (c) 2026 curtainsmall