ZhuXinAI/sidesight

SideSight

用于 DeepSeek Harness

SideSight 同时支持 DeepSeek Harness 的两种原生扩展路径：用于最简单安装的文件系统技能，以及可配置的插件包。两种路径都不会启动 MCP 服务器。

作为可配置的 DSH 插件安装

在 DSH 对话中，向 agent 提出：

请安装 ZhuXinAI/sidesight dsh 插件

或直接运行：

npx @deepseek-ai/dsh plugin --profile web add github:ZhuXinAI/sidesight

更改配置后重启该 profile：

npx @deepseek-ai/dsh --profile web

打开 DSH Web 设置，选择 SideSight 条目，填写 Base URL、Vision model 和 API key。

SideSight DSH 插件设置

重要：配置 SideSight 后，在附加或粘贴图像之前，请从 DeepSeek (SideSight vision) provider 中选择一个模型。常规的 DeepSeek-V4-Flash / deepseek-official 路由仅支持文本，会在 SideSight 或任何工具运行之前拒绝该附件。

SideSight DSH 模型

API key 字段为只写：现有 key 仅显示为已配置，绝不会预填充或返回。你也可以在 profile 的 cordis.patch.yml 中设置插件字段：

- update:
id: sidesight
config:
baseUrl: https://provider.example/v1
apiKey: your-key
model: your-vision-model

该插件会将配置的值提供给 DSH 管理的 shell 调用，并且当技能调用 npx -y sidesight  时，会将这些值映射到 SideSight 的 SIDESIGHT_BASE_URL、SIDESIGHT_API_KEY 和 SIDESIGHT_MODEL 变量。API key 值不会被插值到命令文本或普通工具结果中，并且该技能禁止检查或打印它。请将 profile 配置视为敏感信息，因为手动输入的 key 会随该 profile 一起存储。

粘贴图像桥接在可用时使用该包捆绑的 dist/cli.js。GitHub/源码安装不包含该生成目录，因此插件会自动回退到 npx -y sidesight；无需在 DSH profile 中单独手动安装 CLI。该回退需要 npx 和 npm 访问权限，或已缓存的 SideSight 包。

作为文件系统技能安装

DeepSeek Harness 会从项目中的 .dsh/skills/ 或 $DSH_HOME/skills/（通常为 ~/.dsh/skills/）原生发现文件系统技能，适用于所有项目。无需适配器或核心工作流更改。

从当前项目的 Git 仓库根目录为该项目安装：

mkdir -p .dsh/skills && git clone https://github.com/ZhuXinAI/sidesight .dsh/skills/sidesight

或为所有 DSH 项目安装：

mkdir -p "${DSH_HOME:-$HOME/.dsh}/skills" && git clone https://github.com/ZhuXinAI/sidesight "${DSH_HOME:-$HOME/.dsh}/skills/sidesight"

仓库级别的 SKILL.md 会将视觉工作直接路由到 npx -y sidesight image、ui、ocr、diagnose、diagram、chart、diff 或 video。

在 DSH 中启用附加图像视觉
DSH 在接受附加图像之前，会检查所选模型声明的输入模态。因此，即使已配置 SideSight 凭据，原始的 deepseek-official 文本路由仍会显示“当前模型不支持图像”。填写 SideSight 设置字段后，从新增的 DeepSeek (SideSight vision) 提供方中选择一个模型，例如 DeepSeek-V4-Flash (SideSight vision)。该包装器向 DSH 声明支持图像输入，通过 DSH 读取持久化附件，将其发送到 SideSight，并仅将有限的可视证据转发给原始文本模型；原生缩略图仍保留在会话日志中。

附加图像桥接会自动处理确切的持久化附件。SideSight 技能不会要求模型在磁盘上定位附件或创建本地副本。原生 DSH 图像工具仍可用于显式提供的本地路径，但它不是附件恢复步骤。保持选择原始文本路由预计会保留 DSH 的图像拒绝行为；对于附加图像，请切换到 SideSight 视觉变体。

附件桥接在私有的操作系统临时目录中使用确切的 DSH 附件字节，并在分析后移除该临时物化文件。它不会用 clipboard、latest 或较早的工作区文件静默替换附件，也不会创建工作区副本。对于针对工作区之外现有路径的直接 CLI 调用，请将该文件所在目录作为限定范围的允许列表传入：

media_path="/absolute/path/to/image.png"
npx -y sidesight image "$media_path" \
--allowed-dir "$(dirname "$media_path")" \
--question "Describe this exact image"

对于 DSH 插件用户，npx sidesight setup 是可选的。当你通过 DSH 填写了 baseUrl、apiKey 和 model 时，不需要它。当这些字段为空时，它仍可作为后备方案使用，也适用于偏好 SideSight 仅所有者可访问的已保存配置的文件系统技能安装。

要安装到另一个配置文件，请将 web 替换为该配置文件名称。使用 dsh plugin --profile  remove sidesight 移除该捆绑包。

为编码代理安装

给你的编码代理以下指令：

Read and install the SideSight skill from:
https://github.com/ZhuXinAI/sidesight/blob/main/SKILL.md

技能安装完成后，询问代理：

Help me configure SideSight for cloud vision.

代理会引导你运行 npx sidesight setup 并等待你的确认。API 密钥保留在隐藏的设置提示或你的环境中；切勿将真实密钥粘贴到代理聊天中。代理不得在 shell 配置文件、.env 文件、钥匙串、主目录或无关项目文件中搜索凭据。

如果你明确想要离线或设备端 OCR，请直接说明：

Use native on-device OCR for this screenshot; do not ask me to configure a cloud provider.
代理应运行 sidesight ocr  --provider local。此路径在 macOS 上不需要云设置。

直接使用

告诉代理要检查什么以及你需要什么证据：

Look at /path/to/screenshot.png and tell me why the button is disabled.

Read the exact error text from /path/to/error.png.

Compare before.png and after.png and list only visible UI differences.

Use native offline OCR on /path/to/receipt.png.

该技能会将请求路由到匹配的 CLI 命令。云支持的任务使用已配置的多模态提供程序；显式本地 OCR 使用 macOS Vision，并且绝不会发起云请求。

可选的 MCP 设置

SideSight 以 CLI 为先。如果你的宿主使用 MCP，请将此服务器添加到你的 MCP 客户端：

{
"mcpServers": {
"sidesight": {
"command": "npx",
"args": ["-y", "sidesight", "mcp"],
"env": {
"SIDESIGHT_PROFILE": "opencode-go",
"SIDESIGHT_API_KEY": "your-key"
}
}
}
}

对于通用的 OpenAI 兼容提供程序，还需设置 SIDESIGHT_BASE_URL 和 SIDESIGHT_MODEL。SIDESIGHT_ALLOWED_DIRS 是可选的；仅当媒体位于 MCP 客户端当前目录之外时才添加它。

继续阅读云设置和密钥保存、本地 OCR、MCP或 Codex 技能了解详情。

SideSight 的作用

SideSight 为纯文本编码模型提供了一种安全、可脚本化的方式，使其能够就截图、图表、图形、UI 差异和视频向单独配置的多模态模型提问。对于 macOS 上的显式 OCR 请求，它可以在本地使用 Apple Vision。宿主代理接收简洁的文本和结构化证据；它永远不需要原生图像支持。

Text-only coding agent
│ shell command or MCP call
▼
SideSight
│ image + focused question
▼
Multimodal vision model
│ concise text + structured evidence
▼
Text-only coding agent continues the task

安装 CLI

SideSight 面向 Node.js 22 或更高版本。

pnpm add -g sidesight
sidesight --help

对于检出：

pnpm install
pnpm build
node dist/cli.js --help

云设置和密钥保存

SideSight 使用单独的提供程序配置，因此不会干扰宿主编码模型：

Follow the prompts for the provider base URL, vision model, and API key.
The key is stored with mode 0600 under ~/.sidesight/config.json.
npx sidesight setup
sidesight doctor
sidesight diagnose ./screenshots/error.png \
--question "Transcribe the exact error and identify the likely source file"
opencode-go 预设使用 OpenAI 兼容端点 https://opencode.ai/zen/go/v1 和模型 mimo-v2.5。一个有用的搭配是文本优先的主机编码模型，例如 DeepSeek V4 Flash 与 MiMo-V2.5 用于视觉。提供商端点、模型可用性、定价、保留策略和政策可能会发生变化；请查看当前的 OpenCode Go 文档。

对于通用的 OpenAI 兼容提供商：

sidesight setup \
--profile generic \
--base-url "https://provider.example/v1" \
--model "your-vision-model" \
--api-key "your-key"

不带选项运行 npx sidesight setup 会打开一个交互式引导，用于设置基础 URL、模型和 API 密钥。现有的配置文件、环境和已保存的值会显示为默认值；按 Enter 保留它们。在终端中，API 密钥提示是隐藏的。对于脚本，请如上所示传递 setup 标志。Setup 可以重新运行；省略的值会从已保存的文件或当前环境中保留。SIDESIGHT_API_KEY 是规范的密钥变量，SideSight 也接受 Z_AI_API_KEY 作为兼容别名。config show 仅报告 apiKeyConfigured；它从不打印已保存的密钥。显式本地 OCR 不使用此 setup。

显式本地 OCR

当用户明确请求本地、离线、设备端或原生 OCR 时，无需云 setup：

sidesight ocr screenshot.png --provider local
等价形式：
sidesight ocr screenshot.png --offline
sidesight ocr screenshot.png --ocr-backend system

在 macOS 上，SideSight 调用捆绑的 Swift 桥接到 Apple Vision 文本识别。它返回检测到的文本、可用时的置信度以及归一化的证据区域。图像在设备上处理，不使用提供商请求或 API 密钥。此本地路由目前仅支持 OCR；UI 解读、错误诊断、图表、图形、差异和视频仍需要配置的云或私有多模态提供商。

如果 Swift 或 Xcode Command Line Tools 不可用，SideSight 会返回可操作的错误。在其他操作系统上，本地路由会明确失败，而不是静默地将图像发送到云端。

CLI

sidesight image screenshot.png --question "What visual evidence explains the disabled button?"
sidesight ui design.png --question "Describe the layout and produce React and Tailwind guidance"
sidesight ocr dashboard.png --detail fine --question "Read the bottom-right metrics card"
sidesight ocr receipt.png --provider local --format json
sidesight diagnose error.png --question "Transcribe the exact error and propose the smallest safe fix"
sidesight diagram architecture.png --question "Find single points of failure and unclear ownership"
sidesight chart metrics.png --question "Read the values and summarize visible trends"
sidesight diff reference.png actual.png --question "List only differences that fail visual acceptance"
sidesight video reproduction.mp4 --question "What happens over time and at which timestamps?"

每个任务都使用相同的核心引擎。--question - 从 stdin 读取一个聚焦的问题。--instructions-file 添加项目指导，但不会替换 SideSight 的内部安全规则。--format json 向 stdout 精确写入一个 JSON 对象；进度信息发送到 stderr。--output 在将渲染结果写入 stdout 的同时也将其保存。

支持的媒体来源包括本地 PNG、JPEG、WebP、GIF（第一帧）、MP4、MOV、M4V 和 WebM 文件；HTTP/HTTPS URL；以及经过验证的 base64 数据 URI。sidesight image latest 从 SIDESIGHT_DROP_DIR 或 ./screenshots 读取最新的图像。当 pbpaste -Prefer png 能够读取位图时，macOS 上支持 clipboard。

本地路径是编码代理工作流的首选输入。不接受原始 base64 字符串；请使用完整的 data:;base64,... URI。Codex/Claude 图像附件不会自动作为文件对 CLI 可见，因此在调用 SideSight 之前，请将附件或剪贴板图像导出到某个路径（或提供完整的数据 URI）。提供程序适配器会在内部根据经过验证的媒体创建 base64 数据 URI，但绝不会记录它们。

配置

优先级依次为 CLI 标志、环境变量、保存的用户配置，然后是配置文件默认值。sidesight setup 将提供程序设置写入 ~/.sidesight/config.json，目录模式为 0700，文件模式为 0600。设置 SIDESIGHT_CONFIG_DIR 或 SIDESIGHT_CONFIG_FILE 以使用其他位置。使用 sidesight config init 创建非机密模板，使用 sidesight config show 检查解析后的值。

重要变量：
text
SIDESIGHT_API_KEY
SIDESIGHT_BASE_URL
SIDESIGHT_MODEL
SIDESIGHT_PROFILE
SIDESIGHT_PROVIDER           # cloud/auto by default; local selects native OCR
SIDESIGHT_ALLOWED_DIRS       # optional; needed for media outside the current directory
SIDESIGHT_MAX_IMAGE_MB       # default 10
SIDESIGHT_MAX_VIDEO_MB       # default 50
SIDESIGHT_MAX_ZOOM_ROUNDS    # default 3
SIDESIGHT_TIMEOUT_SECONDS    # default 120
SIDESIGHT_DROP_DIR
SIDESIGHT_FFMPEG_PATH

提供程序兼容性一览：

| 配置文件 | 默认端点 | 默认模型 | 图像 | 原生视频 |
| --- | --- | --- | --- | --- |
| opencode-go | OpenCode Go /v1 | mimo-v2.5 | OpenAI 兼容的 image_url | 否；有界 ffmpeg 帧 |
| generic | http://localhost:8000/v1 | vision-model | OpenAI 兼容的 image_url | 否；有界 ffmpeg 帧 |
| local | 设备端 | macos-vision | 仅 macOS Vision OCR | 否 |

任何接受所记录的 OpenAI 兼容多模态聊天补全形式的提供程序都可以使用 generic。
SIDESIGHT_ALLOWED_DIRS 在通常情况下不是必需的：默认情况下允许当前工作目录。当图像或视频位于其他位置时设置它，例如在类 Unix 系统上使用 export SIDESIGHT_ALLOWED_DIRS="$HOME/Screenshots:$PWD"。保持允许列表范围狭窄可防止意外访问无关的本地文件。

归一化区域使用 x,y,width,height，范围为 0..1，从完整的原始图像测量：
bash
sidesight ocr screenshot.png --region 0.65,0.70,0.35,0.30 \
--question "Read every visible character"

overview 执行一次有界遍历。normal、fine 和 auto 可能会检查一个有界的全分辨率裁剪区域。裁剪始终从原始图像进行，绝不从缩放后的裁剪图像进行。缩放轮次、提供方调用、图像数量、尺寸、媒体大小、视频帧和输出 token 都是有界的。

MCP

使用以下命令运行 stdio 适配器：
bash
sidesight mcp
or, after publishing/installing the package:
npx -y sidesight mcp

该服务器暴露 ui_to_artifact、extract_text_from_screenshot、diagnose_error_screenshot、understand_technical_diagram、analyze_data_visualization、ui_diff_check、image_analysis 和 video_analysis。它使用与 CLI 完全相同的配置、提示词、媒体安全、提供方适配器和核心引擎。OCR 工具调用可以传递 backend: "local" 以使用 macOS Vision，无需云设置。MCP 协议消息使用 stdout；诊断信息使用 stderr。环境变量由 npx 继承；保存的 ~/.sidesight/config.json 设置也会自动解析。

如需可复制粘贴的客户端配置，请使用上文 可选 MCP 设置 中的 MCP 设置。

Codex 技能

唯一的路由技能是仓库级别的 SKILL.md，由 DSH 和安装程序共享。使用以下命令将其安装到用户技能目录中：
bash
node scripts/install-skill.mjs "$HOME/.agents/skills"

安装程序复制真实文件，不创建符号链接。该技能在可用时优先使用 DOM、无障碍树、日志和源数据，然后将视觉问题路由到最合适的最小 SideSight 命令。

如果你要让代理安装该技能，请使用此提示词：

Read and install the skill here at SKILL.md.

安全与隐私

媒体是不可信输入。本地路径会根据允许列表进行规范化，符号链接逃逸会被拒绝，文件大小和图像尺寸受到限制，MIME 类型会根据魔数字节进行检查。远程 URL 仅限于 HTTP/HTTPS，会解析并检查是否属于私有、localhost 和云元数据网络，下载时带有超时和响应大小限制，并在重定向过程中重新验证。媒体中嵌入的 URL 仅作为证据返回；它们绝不会被获取。
云端支持的图像和视频会传输到已配置的视觉提供商。对于敏感截图，请使用本地或私有的 OpenAI 兼容提供商，或使用显式的 --provider local 进行 macOS OCR。API 密钥、授权标头、数据 URI 和完整的提供商负载会从常规诊断中脱敏。视觉输出是不可信的证；SideSight 绝不会基于它执行命令或修改文件。

Doctor 与故障排查
bash
sidesight doctor
sidesight doctor --live

默认的 doctor 会检查 Node.js、配置、密钥是否存在、端点可达性、sharp、ffmpeg、允许的目录以及临时存储，而不会发起计费的模型调用。--live 会向所选提供商发送一张微小的确定性图像。视频帧采样需要 ffmpeg；请安装它或设置 SIDESIGHT_FFMPEG_PATH。

提供商故障会被规范化：身份验证、速率限制、无效 JSON、端点不可达以及纯文本模型对图像的拒绝都会产生可操作的非零错误。纯文本后端不能用作视觉模型；请通过 SIDESIGHT_MODEL 选择多模态模型。

开发与测试
bash
pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm test:integration
pnpm test:acceptance
pnpm test:pack

实时检查是选择性启用的，并且需要凭据；它们不属于常规 CI 的一部分。

要针对已配置的提供商运行全部八项任务，请运行 pnpm build，然后运行 SIDESIGHT_LIVE_TEST=1 pnpm test:live。如果没有选择性启用标志或三个必需的提供商变量，该脚本会报告跳过并成功退出。

发布

首次 npm 发布以及后续基于 OIDC 的 GitHub Actions 发布流程记录在 RELEASE.md 中。发布仅针对匹配的 vX.Y.Z 标签运行。

许可证与参考资料

SideSight 采用 MIT 许可证。其架构参考了公开的 Z.AI Vision MCP 文档、MIT 许可的 vision-mcp 参考、OpenCode Go 以及 Codex 技能文档。SideSight 使用原创的提示模板，不复制私有的提供商提示。