# dsh-possibility-space

[English](README.md) | 中文

> 不用再说“换一个”，直接拖到你想要的方案。

`dsh-possibility-space` 把 DSH 的回答变成一张可探索的二维语义地图，并直接展开在这条回答下方。它不是一次生成十个答案再替你选，而是先找出真正有意义的取舍维度；你把圆点拖到某个位置，松手后才生成那个位置对应的一个版本。

![真实 DSH 会话中的 Possibility Space 白色精密仪器界面](assets/possibility-space.webp)

![DSH 会话内演示：展开、拖动、查看差异和版本轨迹](assets/possibility-space-demo.gif)

## 它改变了什么

安装后，每条已完成的助手回答旁会出现一个地图图标。点击后地图在当前会话中原地展开，原回答和输入框仍然可见；需要专注操作时也可切到全屏。随后可以：

1. 插件分析当前回答，提取三个相互独立的语义取舍维度。
2. 你选择其中两个组成地图，例如“兼容现状 ↔ 激进创新”和“极简克制 ↔ 丰富表现”。
3. 拖动圆点只改变预览坐标；松手时才请求模型生成一个版本。
4. 在方案正文里点击锁图标，可以把满意的段落逐字锁住；也可以输入自定义的不可变要求。
5. 地图会保留每次尝试的位置，右侧版本轨迹可随时回退。
6. 可查看当前方案与原始回答的逐行差异，复制采用，并把坐标保存为个人偏好。后续遇到相同语义轴时会恢复该坐标，但不会在后台自动生成。

适用于 UI、代码设计、文章、产品方案和决策分析。维度不是固定模板，而是根据当前回答动态提取。

## 安装

要求 DSH `0.1.1-rc.2` 或更新版本，以及 Node.js 22+。

```bash
npx --yes @deepseek-ai/dsh@latest plugin --profile web add \
  github:zhangguiping-xydt/dsh-possibility-space
```

然后重启 Web Profile：

```bash
npx --yes @deepseek-ai/dsh@latest web
```

插件不要求单独填写 API Key。它会读取被点击回答实际使用的 provider/model，并通过 DSH 已配置的模型适配器发起请求。如果原回答没有文本或模型来源，入口会保持禁用并说明原因。

## 使用方法

- 将鼠标移到一条已完成回答的操作栏，点击地图图标。
- 首次打开会生成三个维度，但不会批量生成方案。
- 在 X/Y 下拉框中选择两个维度。
- 拖动地图中央圆点；移动过程中不消耗 Token，松手才生成。
- 键盘用户可用方向键移动圆点，`Shift + 方向键` 大步移动，`Enter` 生成。
- 点击正文段落旁的开锁图标可锁住该段；右侧也可添加自定义约束。
- 点击地图历史点或版本轨迹可回退；“复制采用”不会改写原会话。

## Token 如何控制

- 打开时只调用一次模型来生成语义维度。
- 内部的维度提取和受控改写沿用原回答的 provider/model。只有该模型明确支持 `off` 时才关闭长推理；其他模型保留适配器认可的默认档位，不会因强塞不支持的参数而失败。
- 拖动过程中零请求，只有 `pointerup` 或明确点击“在此生成”才调用模型。
- 坐标按 `0.05` 离散化，避免手抖形成大量近似请求。
- 缓存键由原回答、两条轴、坐标和锁定约束共同决定；命中相同位置直接读取本地缓存。
- 不在后台并行生成候选，也不让模型自动选优。

## 锁定如何保证

段落锁包含原文引用和不可变说明。生成时，原文引用必须逐字出现在新方案中，模型还必须声明已处理每个锁；Host 会再次校验。任一锁未满足，整个版本会被拒绝并显示 `lock_violation`，不会悄悄保存一个破坏约束的答案。

自定义约束没有可机械比较的原文，插件要求模型显式确认，但语义正确性仍需人工判断。这个边界会在界面中保持可见，而不是假装模型约束绝对可靠。

## 数据与隐私

- 模型请求只经过当前 DSH Host 和它已经配置的模型适配器；插件不连接自己的云服务。
- 原回答、版本、锁和偏好保存在当前浏览器的 `localStorage`。
- 插件不会修改原始 Session 日志，不会自动提交代码，也不会执行工具。
- 浏览器到 Host 的 `/api` 通道、`possibility-space` RPC 端点由 DSH Connection 层进行来源检查和认证。
- Host 限制基线长度、锁数量、输出 Token 和并发数，并对模型 JSON 做严格结构校验。

清理某条回答的数据，可在浏览器开发者工具中删除以 `dsh-possibility-space:` 开头的本地存储项。

## 架构

```text
已完成的助手回答
       │ messageId + 文本 + 实际模型来源
       ▼
assistant-actions 插槽 ──► 当前回答下方的会话内锚点
       │                        │
       │                        ├─ 地图、Diff、约束、轨迹、可选全屏
       │                        └─ localStorage 缓存/偏好
       ▼
DSH Connection 已认证 RPC 端点
       │ 仅在生成维度或松开拖拽点时
       ▼
ctx.llm.stream ──► 当前回答使用的 DSH 模型适配器
       │
       └─ JSON 校验 + 锁定校验 ──► 单个新版本
```

浏览器端使用官方 `conversation.chat.assistant-actions` 扩展位。点击后，React Portal 会挂到这条回答既有的 `data-turn-tail` 容器，因此地图随会话正常滚动，也不会抢占其他插件的扩展位。Host 端注册私有 DSH Connection RPC 拦截器，并直接使用 DSH 的 provider-neutral LLM 服务；不修改 DSH 源码。

## 配置

默认配置已适合日常使用，可在 Cordis 配置中覆盖：

```yaml
- id: dsh-possibility-space
  name: '@dsh-external/dsh-possibility-space'
  config:
    maxBaselineChars: 80000
    maxVariantTokens: 6000
    maxConcurrentRequests: 2
```

## 开发与验证

```bash
corepack enable
pnpm install
pnpm run check
pnpm run test:coverage
pnpm run pack:check
```

测试覆盖会话内挂载、圆点拖动、坐标归一化、缓存键、偏好恢复、原回答保留、模型能力兼容、请求边界、模型 JSON、锁校验、真实 LLM seam 调用、回答提取、本地持久化、Diff 和 Client Slot 注册。`lib/` 有意提交到仓库，因为 DSH 从 GitHub 安装插件时不会运行构建脚本。

## 兼容性

当前基线是 DSH `0.1.1-rc.2` 的公开 npm 包。插件依赖该版本引入的逐回答 `conversation.chat.assistant-actions` 插槽。DSH 后续如调整 Client Slot ABI，将通过兼容性测试跟进。

## 参与贡献

见 [CONTRIBUTING.md](CONTRIBUTING.md)。安全问题请按 [SECURITY.md](SECURITY.md) 私下报告。

MIT © 2026 [Guiping Zhang](https://github.com/zhangguiping-xydt)