dsh-socrates

Readme

# dsh-socrates · 把苏格拉底的提问智慧装进 DSH

> AI 时代真正的稀缺能力不是「得到答案」，而是**把模糊欲望翻译成可证伪规格**的提问能力。
> 苏格拉底助产术（承认无知 → 下定义 → 反例检验 → 暴露矛盾 → 收敛留痕）正是为此而生。
> 本插件把它落进 DSH 的 agent 循环：让 AI 不再顺从，让实现恰好是你真正想要的。

## 解决什么问题

| 症状 | 病根 | dsh-socrates 的对策 |
|---|---|---|
| AI 太顺从，你说什么它做什么 | 模型天然倾向讨好与直接执行 | **提示闸门**：实现意图模糊时强制模型先诘问、后动手 |
| 做完了才发现不是想要的 | 意图从未被翻译成可检验的标准 | **socratic 技能**：五步诘问流程 + 意图规格契约 |
| 一句「rm -rf」就被执行 | 不可逆操作没有人类当场确认 | **高危闸门**：危险命令执行前以苏格拉底式问题请你拍板 |
| 计划没人质疑 | 缺少只提问、不下结论的对抗者 | **socratic 技能**同会话审查模式（可选：苏格拉底预设做独立审查会话） |

**设计底线**（缺一即退化成烦人表单）：提问要**便宜**（一次一个问题）、要**面向人**（AI 不替人作答）、要有**终止条件**（意图可证伪即停；一句「直接做」即可绕过提示闸门）。

## 三层架构

| 层 | 形态 | 落点 | 干什么 |
|---|---|---|---|
| 方法论层 | `skills/socratic/` | `$DSH_HOME/skills/`（用户级技能） | 诘问式需求/决策分析：五步流程、提问军火库、意图规格模板 |
| 执行层 | 编译插件 `dsh-socrates` | profile 插件行（`dsh plugin add`） | 两个闸门：`agent/pre-step` 提示闸门 + `tools/pre-execute` 高危闸门 |
| 人格层（可选，默认不装） | `presets/socrates/` | `$DSH_HOME/.agent-presets/`（`--with-preset`） | 「苏格拉底」预设：只提问、不下结论、独立对抗审查会话 |

**插件本体 = 技能 + 闸门**。人格层是可选资产：DSH 的 persona 行只能挂在预设组合里（scope-only），且子代理必须继承父会话预设、无法单独指定人格——所以「独立苏格拉底审查者」的唯一合法形态是预设。不需要独立审查会话时（审查走同会话技能即可），默认安装不会碰你的预设列表。

三层共享同一契约：**意图规格文档**（`specs/<name>.intent.md`，模板见 `skills/socratic/references/intent-spec-template.md`）。技能负责生成、人格负责审问、闸门负责确保它不被跳过。

## 安装

```bash
# 1. 技能（立即生效，新会话可见）；可选 --with-preset 装入「苏格拉底」预设
./install.sh            # 或 ./install.sh --link（开发时改仓库即生效）

# 2. 插件闸门（编译产物，需要 dsh CLI 与一次进程重启）
dsh plugin --profile <你的profile> add link:$(pwd)

# 3. 重启 dsh
```

安装后：

- 新会话的模型可随时用 skill 工具加载 `socratic`（同会话诘问澄清与对抗审查）；
- （仅当用了 `--with-preset`）新建会话的预设选择器出现「苏格拉底」；
- 所有会话中：
  - 你发「帮我实现一个订单系统」→ 模型会先复述意图，必要时用提问卡逐个问你，你给出验收标准后才动手；
  - 你发「帮我实现一个订单系统，验收标准：能下单、能取消」→ 直接放行；
  - 你发「帮我实现一个订单系统，直接做」→ 尊重授权，放行（风险由闸门已知风险告知）；
  - 模型要执行 `rm -rf`、`git push --force`、`DROP TABLE`、`curl|bash` 等 → 审批弹窗向你提问「最坏结果能否接受？能否回滚？」，你批准才执行。

## 使用场景

### 场景 1：需求从模糊到可证伪

```
用户：帮我实现一个订单系统
闸门：注入诘问指令
模型：我理解你要做一个订单系统。先确认最关键的一点：
      「如果它不能做什么，你会觉得这不是你要的东西？」
用户：至少不能发货的订单不算完成
模型：明白。那验收标准写成「当用户提交订单后 1 秒内，库存扣减且订单可见」对吗？
      还有冲突要你拍板：你说越快越好，但又要支持秒杀——如果必须牺牲一个，先牺牲哪个？
用户：先保证普通下单路径正确，秒杀以后再说
模型：好的，意图已可证伪。验收标准：……（写入 specs/orders.intent.md）开始实现。
```

### 场景 2：对抗式审查（同会话）

需要有人质疑你的方案时，让当前会话加载 socratic 技能并进入审查模式：

```
你：加载 socratic，然后审一下这个选型计划（粘贴计划）
模型（诘问模式）：「计划声称 Redis 能扛 10 万 QPS——什么证据出现，你会相信这个数字是对的？」
你：压测报告
模型：「如果压测暴露内存不够，你准备牺牲什么来兜底？」
……
```

如果想要一个**整段系统提示都是苏格拉底人格**的独立审查会话（角色强度更高、且与主会话互不干扰），用 `./install.sh --with-preset` 安装预设后，新建会话选「苏格拉底」即可。

### 场景 3：高危操作的最后一问

```
模型准备执行：rm -rf /var/cache/app
审批弹窗：【苏格拉底闸门】命令命中高危规则「递归删除」。
         1. 最坏的结果是什么？发生了你能接受、能回滚吗？
         2. 备份或恢复路径是否已经存在？
```

## 配置

插件行（`dsh plugin add` 自动加入 profile，可在 profile 的 `cordis.patch.yml` 中为该行补 `config` 覆盖）：

| 字段 | 默认 | 说明 |
|---|---|---|
| `promptGate` | `true` | 提示闸门总开关 |
| `promptGatePatterns` | 中英文实现动词正则 | 判定「实现意图」的模式 |
| `criteriaMarkers` | 验收/约束/边界等标记 | 命中任一视为意图已澄清，跳过 |
| `bypassMarkers` | 「直接做」等 | 用户显式授权短语，跳过提示闸门 |
| `maxQuestions` | `3` | 注入指令允许模型向用户提问的最大数 |
| `destructiveGate` | `true` | 高危闸门总开关 |
| `destructiveToolNames` | `["bash"]` | 参与高危检测的工具名 |
| `destructiveRules` | 10 条内置规则 | `{ label, pattern }` 列表，可增删 |

完整默认值见 [`src/config.ts`](src/config.ts)。

## 设计原则

1. **便宜**：提示闸门的误报代价是一行意图复述，漏报代价是返工一轮——宁误勿漏。高危闸门恰好相反：宁严勿松（用户点一下「批准」即可）。
2. **面向人**：所有问题的回答者必须是人。闸门从不替用户作答；注入指令明确禁止模型「猜测意图后直接实现」。
3. **终止条件**：提示闸门可被「直接做」绕过；高危闸门不可绕过（不可逆操作必须人类当场确认）——这是唯一的不对称，也是底线。
4. **只做确定性的事**：两个闸门都是确定性的模式匹配，零 LLM 调用、零延迟、永不抛进 agent 循环。启发式的「软判断」交给技能与 persona（模型侧）完成。

## 目录结构

```
dsh-socrates/
├── src/               # 闸门插件（TypeScript → lib/）
│   ├── index.ts       #   插件入口（name / Config / apply）
│   ├── config.ts      #   配置 schema + 出厂默认值
│   ├── prompt-gate.ts #   提示闸门（agent/pre-step）
│   ├── destructive-gate.ts # 高危闸门（tools/pre-execute）
│   ├── heuristics.ts  #   纯函数检测逻辑（可单测）
│   └── messages.ts    #   注入消息与决策理由模板
├── skills/socratic/   # 方法论技能 + 意图规格模板
├── presets/socrates/  # 可选：苏格拉底 persona 预设（--with-preset 安装）
├── tests/             # 单元测试（node --test）
├── smoke/             # cordis 事件模型冒烟测试
├── cordis.patch.yml   # profile 补丁：插入闸门插件行
└── install.sh         # 安装脚本（默认技能；--with-preset 加装预设）
```

开发：`pnpm build && pnpm test && pnpm smoke`（构建类型解析经仓库内 `node_modules/@deepseek-ai` 符号链接指向 DSH 安装农场；换机器需重指）。

## 局限与后续

- 提示闸门只覆盖「全新实现意图」的启发式检测；对「改一行」类指令不介入（也不该介入）。
- 高危闸门 v1 只查 `bash` 工具；`write`/`edit` 覆盖式写入未纳入（有版本控制可回退）。
- 意图规格的「存在性」尚未成为硬闸门（例如：无 spec 禁止大改）——留待收集真实使用反馈后再决定松紧。
- 苏格拉底预设（可选资产）用于独立审查会话，需 `--with-preset` 显式安装；默认安装不占用预设列表。

## 许可

MIT