# dsh-outer-brain

[English](README.md) | 中文

**把哲学家的思考方式变成可执行的东西 —— 用辩证法和实践检验，取代提示词层面的自我约束。治两个病，而且这两个病都随会话变长而加重：幻觉、长会话漂移。**

多数工具想给模型加智力。这个不加。它给 agent 两样东西：

- **一套思考方式** —— 抓主要矛盾、拒绝非黑即白、让实践（而不是排练）来裁决一个主张；
- **一套自查手段** —— 账本、可执行判据、外部审查，让「做完了」是事实，而不是一句自述。

## 两个病，以及为什么越聊越重

Agent 对这两件事都不擅长自查：

| 病 | 怎么表现 | 拿什么治 |
|---|---|---|
| **幻觉** | 账标绿了、总结写漂亮了，但交付物不存在。"我记得上次是这样的"、"条件不够所以没法做" | 判据必须**真跑命令看退出码**；证据没有**回执**（命令原文/路径/URL）权重记 0；机械判据通过后还要**开庭陪审**（3 个互不通气的评审员，多数决） |
| **长会话漂移** | 聊到二十轮，在优化一件没人要求的事；或者反复重跑同一条命令，还管这叫进展 | **矛盾树**把主矛盾钉住，不让它悄悄漂走；`stalled` 抓语义打转、`spin` 抓机械重复（两路取或）；被推翻的判断**记账**，不许悄悄忘掉 |

## 安装

### 方式 A — 桌面版（多数用户）

打开 **设置 → 插件**，找到 `dsh-outer-brain`，启用。

### 方式 B — 命令行 profile（`web` / `tui` 等）

```sh
dsh plugin --profile web add dsh-outer-brain
```

> ⚠️ **只跑这一行，插件不会被挂载。** `dsh plugin` 只是把参数原样转发给 pnpm —— 它只把包写进该 profile 的 `dependencies`。**挂不挂载由 `dsh.profile.bundles` 决定。**

还必须把包名加进该 profile 的 `package.json` 里的 `dsh.profile.bundles`：

```jsonc
{
  "dependencies": {
    "dsh-outer-brain": "^0.1.0"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "dsh-outer-brain"
      ]
    }
  }
}
```

**少了 `bundles` 这一项：包装好了、一行都不执行、也不报任何错** —— 用户只会以为插件坏了。

然后重启 DSH。

> **装完默认是静默的。** 要说一句 **「开机制」** 才启用（「关机制」退场）。这是刻意设计——治病的工具不该在全时段盯着你。

## 12 个工具

| 工具 | 作用 |
|---|---|
| `brain_task` | 声明任务：原话 + 我的理解 + 为什么这么做 + 要的结果 |
| `brain_plan` | 交付账：里程碑、交付物、**可执行判据**、定义（is/not/limit） |
| `brain_verify` | 跑判据（机制真执行命令看退出码）+ 自动开庭陪审 |
| `brain_contra` | 矛盾树：两条路径走到同一终点但结果不同（Φ≠0），做八种手法处置 |
| `brain_observe` | 证据池：claim / 先验 / 预期 / 观测 / 回执，按似然比记分 |
| `brain_settle` | 轮末结算：水位入历史、隐患结账、未知池捕获 |
| `brain_status` | 看当前水位、报警、欠账 |
| `brain_lift_check` | 升维判据：判一条"升维方案"是取、是执，还是暂时升不了 |
| `brain_dissolve` | 升维回执：被解决的那个矛盾现在怎么样了（消失/转移/原样还在）—— **见「已知限制」** |
| `brain_escalate` | 向上报告：我要什么 / 为什么自己搞不定 / 拿到从哪接 |
| `brain_terminate` | 终止声明：达成（列可核事实）/ 不可达（指名缺什么）/ 转移 |
| `brain_boundary` | 机制自身的边界：登记「机制自己撞过的墙」 |

## 配置

大部分行为在 `cordis.patch.yml` 里可调。几个关键的：

```yaml
enabled: true        # 总开关：false ⇒ 不注册工具、不注入
ledger: 'ledger'     # 证据不灭 + 读时折价
decay: 0.35          # 时效折价率
cap: 3               # 每轮最多处置几件
leanSelect: true     # 只撤"选题类"干预，判据类一概不动
jury:
  enabled: true
  maxTokens: 16384   # 判决 JSON + 长理由要留够余量，否则被截断 ⇒ 三票 unclear
```

状态文件默认落在 **DSH 的启动目录**（`process.cwd()`），也就是说 `.outer-brain-diag.log` 和状态 JSON 会出现在你启动 DSH 的那个目录里。建议显式固定：

```yaml
workDir: '/path/to/outer-brain-state'
```

## 已知限制（0.1.0）

这一版有三条路走不通。写在这里而不是藏起来——因为这个插件的全部意义就是**宣传过的能力应当存在**。

| 位置 | 断在哪 |
|---|---|
| `brain_dissolve` | 它拿 id 去**任务/问题树**里查，而传进来的是**矛盾树**节点 id（如 `C0`）⇒ 恒报"节点不存在"。0.1.0 无法用它给升维结账。 |
| 未知池 | `brain_settle` 能捕获契约外观察，但没有任何调用点接到 `classify` / `absorb` / `reject`。一旦有未处理的条目越过水位线，**"达成"将永久不可达**。 |
| `brain_terminate` | `blocked_evidence` 会校验、也会在回执里回显，但**不写进里程碑记录**（不落盘）。 |

## 诚实边界

- **这是 0.1.0 的早期机制**，为单机自用场景设计，不是成熟工作流的替代品。
- 它会在你的会话里**注入系统提示**并**拦截一部分"完成"声明**——这是它的工作原理，不是副作用。不喜欢可以随时「关机制」。
- 陪审需要模型支持结构化输出；`maxTokens` 配小了会导致判决被截断（表现为"判据含糊"，其实是"输出没说完"）。
- 机制本身也有缺陷史。开发过程中反复出现同一类问题：**函数写了、单测绿了、但没人调用**（报了数却没进决策）。这类问题已逐个修复，但它说明一件事：**工具能防你自欺，防不了它自己**。

## 许可

MIT
---

## 版本变更

每一版「改了什么、为什么改、怎么自己验」都在 [CHANGELOG.md](CHANGELOG.md)。