视觉归档 ZhangShurong/dsh-vista

dsh-vista

为 DeepSeek Harness 提供视觉记忆与主动查看能力。

你的智能体只看一眼图片。dsh-vista 让它随时都能找回来。

DSH 智能体经常处理截图、图表和渲染后的页面，但真正重要的那张图，往往在下一次工具调用或上下文压缩之后就没了。dsh-vista 把见过的每张图都存进一个可寻址的归档，并给智能体三个工具，随时回去翻：

- inspect —— 回看任意历史图片，裁剪任意区域，放大时不做平滑处理；
- read_pixels —— 从某个区域采样精确颜色，输出紧凑的符号矩阵；
- visuals —— 列出智能体已经见过的图片。

每张送到模型的图片都会自动打上稳定 id：

<visual id="v12" source="tool:read_image" size="1280x720"></visual>

即使原图已经滑出上下文窗口，模型之后仍能引用 v12。

dsh-vista 实际效果

为什么需要它

- 压缩丢掉的是字节，不是含义。 上下文翻篇之后，dsh-vista 仍能寻址到原始字节。
- 重新截图又贵又有损。 屏幕已经变了；你要的那张图，是三步之前的那张。
- 「再看一遍整张图」不叫查看。 好的视觉智能体会针对具体区域提具体问题。
- 纯文本兜底。 即使模型路由只接受文本，read_pixels 照样能用。

安装

dsh plugin --profile web add dsh-vista

或者锁定版本：

dsh plugin --profile web add dsh-vista@0.1.3

然后验证：

dsh --profile web --dump-config | grep dsh-vista
dsh --profile web

从 GitHub 检出安装：

dsh plugin --profile web add github:ZhangShurong/dsh-vista#v0.1.3

工具

| 工具 | 作用 | 输出 |
| inspect | 选中归档中的 visual 和可选区域；从原图裁剪，用最近邻算法放大。 | 图像块 |
| read_pixels | 把区域划分成等分的行和列，采样每个中心像素。 | 调色板 + 符号行 |
| visuals | 列出最近的视觉对象，含 id、来源、尺寸和时间戳。 | JSON |

inspect 示例：

{
"question": "Did the button move after the click?",
"views": [
{
"label": "button before",
"visual": "v11",
"region": { "x": 1180, "y": 40, "width": 100, "height": 60 }
}
]
}

read_pixels 结果示例：

{
"palette": { "0": "#FF0000", "1": "#0000FF" },
"views": [
{ "label": "quadrant", "visual": "v1", "rows": 2, "columns": 2, "samples": ["01", "11"] }
]
}

read_pixels 只做测量。它不对像素做对齐、变换或解读。

工作原理

tool result / attachment
│
▼
tools/post-execute ──► archive bytes, assign vN, prepend <visual id="vN">
│
▼
model sees: <visual id="v12" ...></visual> [image]
│
├── inspect(v12, region) ──► cropped + enlarged image
├── read_pixels(v12, region) ──► palette + symbol rows
└── visuals() ──► index of previous images

归档按内容寻址，只追加（index.jsonl 加上 archiveDir 下的文件）。送到模型的图像仍由 DSH 的附件服务管理；dsh-vista 另存一份副本，让视觉 id 在压缩和图像卸载后依然有效。

配置

默认值在 src/config.ts。在 bundle 行或配置档补丁里覆盖：

- id: dsh-vista
config:
archiveDir: /home/me/.dsh/dsh-vista/archive
displaySize: 1024
maxInspectViews: 8
maxPixelViews: 16
maxPixelSamples: 4096
annotate: true
retentionDays: 7

| 字段 | 默认值 | 含义 |
| archiveDir | $DSH_HOME/dsh-vista/archive | 字节存储和 index.jsonl。 |
| displaySize | 1024 | 裁剪图最长边的尺寸。 |
| maxInspectViews | 8 | 每次 inspect 调用的视图数。 |
| maxPixelViews | 16 | 每次 read_pixels 调用的视图数。 |
| maxPixelSamples | 4096 | 每次 read_pixels 调用的采样总数。 |
| annotate | true | 在每张归档图像前插入 <visual id="...">。 |
| retentionDays | 7 | 删除更早的归档视觉对象；0 表示永久保留。 |

已在 DSH 0.2.1-rc.2 上验证

用 deepseek-flash 做了端到端测试：

1. read_image 返回图像；dsh-vista 归档它，并追加 <visual id="v1" source="tool:read_image" size="16x16">。
2. visuals 列出 v1。
3. inspect 裁剪并放大归档图像，返回模型可见的 1024×1024 PNG。
4. read_pixels 返回预期的 01 / 11 颜色采样。
5. 模型正确描述了红蓝象限。

src/content.ts 里的附件桥接使用：

ctx.attachments.saveImage({ data, mediaType, name })
ctx.attachments.imageHostPath(ref)

两者都在已安装的 @deepseek-ai/dsh-attachment 中确认可用。

有意不做的事

- 没有环境适配器（ARC-AGI-3、GameWorld、浏览器自动化）。
- 没有 play / act 动作工具。
- 没有每回合只允许一个动作的策略、预算或评估框架。
- 没有 Python sidecar。

这些都属于后续插件。这个插件只回答一个更窄的问题：可寻址的视觉记忆加上主动检查，能否改善 DSH 智能体的视觉工作？

开发

pnpm install
pnpm typecheck
pnpm build
npm pack --dry-run

这个包是 ESM bundle。lib/ 是生成产物；assets/ 存放 logo 和 README 图片。

发布

发布在 GitHub Actions 里跑，不在本地笔记本上跑。

打标签触发（推荐）：

npm version patch # or minor / major
git push --follow-tags

手动按钮：

Actions → Publish → Run workflow → 选择 patch、minor 或 major。
工作流会升版本号、提交、打标签并发布。

工作流使用 npm Trusted Publishing（OIDC），发布时带 provenance。一次性设置：

1. 打开 https://www.npmjs.com/package/dsh-vista/access
2. 添加 Trusted Publisher → GitHub Actions：
- Owner：ZhangShurong
- Repository：dsh-vista
- Workflow filename：publish.yml
3. 不需要 NPM_TOKEN secret。

如果你更想用 token，添加 NPM_TOKEN 仓库 secret，并在发布步骤上设置 NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}。

CI（.github/workflows/ci.yml）在每次 push 和 pull request 时跑 typecheck、build 和 npm pack --dry-run。

许可证

MIT