cc-vision-hook 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+本项目遵循 [Semantic Versioning](https://semver.org/)。
+
+## [0.1.0] - 2026-07-08
+
+首个可发布版本（P0 范围）。
+
+### 新增
+
+- `UserPromptSubmit` Hook：扫描 `~/.claude/image-cache/<session_id>/` 识别用户粘贴的图片。
+- `PostToolUse` Hook（`matcher: "*"`）：通用递归提取器识别任意工具的图片输出，已验证覆盖
+  三种真实 schema（`Read` 判别式对象 / MCP content block 数组 / `Bash`/`PowerShell` 的
+  `isImage` 旁路标志 + data URI 字符串）。
+- 两个 Hook 均只输出 `additionalContext`（追加文字描述），不替换/删除原始内容——
+  仅对"静默忽略图片"型模型有效，对"协议层硬拒绝"型模型无效（已在 README/`doctor` 中显著声明）。
+- 视觉解析统一通过 [AI SDK](https://sdk.vercel.ai/) 对接四个 provider：
+  `oai`（Chat Completions）、`responses`（Responses API）、`anthropic`、`gemini`。
+- 图片解析结果按内容 hash 缓存在本地磁盘（`~/.claude/cc-vision-hook/cache/`），
+  全局共享、TTL 7 天惰性清理，跨来源（粘贴/工具产图）同一张图只解析一次。
+- Session 级"已展示过的图片"标记（`seenTracker.ts`），避免多轮对话后
+  `additionalContext` 随对话轮数线性膨胀。
+- CLI 命令：`install`/`uninstall [--purge]`/`enable`/`disable`/`status`/`doctor`/
+  `config get`/`config set`/`test-image`，全部支持 `--json` 输出。
+- SDK 导出（`cc-vision-hook/sdk`），供其他 Node/Bun 项目直接内置调用。
+
+### 修复
+
+- **AI SDK provider 混淆**：`"oai"` 配置项曾经直接用 `openai(modelId)` 默认调用，
+  在当前 AI SDK 版本下实际解析成 Responses API，导致 `"oai"`/`"responses"` 两个
+  配置项形同虚设。已改为显式 `openai.chat(modelId)`，并加回归测试。
+- `PostToolUse` Hook 注册补充显式 `matcher: "*"`（不依赖未经验证的默认留空行为）。
+- `config set` 增加前置值校验（provider 枚举、baseUrl URL 格式、timeoutMs/maxTokens
+  正数校验），避免非法值要等到真正调用视觉模型时才报错。
+
+### 测试
+
+- 55+ 单测覆盖 `extract`/`cache`/`claudeSettings`/`vision`/两个 hook，均为 fixture
+  驱动（fixture 来自真实 Claude Code payload 样本）。
+- 真机验证：用真实 API Key + Claude Code 2.1.144，在隔离 `HOME` 下验证了完整链路——
+  一个协议层"静默忽略图片"型模型在未装 cvh 时会瞎猜图片颜色，装了 cvh 后
+  transcript 证实 `additionalContext` 被正确注入并最终答对颜色。
+
+### 已知限制
+
+见 README「已知限制」章节：不支持协议层硬拒绝型模型；粘贴图片场景依赖非官方
+实现细节（`~/.claude/image-cache/`）；不做模型能力自动判断；只面向 Claude Code。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cc-vision-hook contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+<div align="center">
+
+# cc-vision-hook
+
+**Give vision-blind Claude Code models eyes — without touching your prompt.**
+
+`cvh` is a local-only Claude Code Hook toolkit. When you paste an image, or a tool (`Read` / `Bash` / MCP) produces a screenshot, `cvh` sends it to a vision model of your choice and injects the description back into Claude Code's context as `additionalContext` — so a model that would otherwise silently ignore the image can actually "see" it.
+
+[![npm version](https://img.shields.io/npm/v/cc-vision-hook.svg?color=cb3837&logo=npm)](https://www.npmjs.com/package/cc-vision-hook)
+[![npm downloads](https://img.shields.io/npm/dm/cc-vision-hook.svg?color=blue)](https://www.npmjs.com/package/cc-vision-hook)
+[![GitHub stars](https://img.shields.io/github/stars/RainSunMe/cc-vision-hook?style=social)](https://github.com/RainSunMe/cc-vision-hook)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+[![Node >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](package.json)
+
+[English](./README.md) · [简体中文](./README.zh-CN.md)
+
+</div>
+
+---
+
+## Why
+
+Not every model behind Claude Code understands images. Depending on the backend, an unsupported image request fails in one of two very different ways:
+
+| Failure mode | What happens | Can `cvh` fix it? |
+|---|---|---|
+| **Silently ignoring** | The API call succeeds (HTTP 200), but the model never actually looks at the image — it guesses, hallucinates, or just says "I can't see the image." | ✅ Yes — this is exactly what `cvh` is built for |
+| **Protocol-level hard rejection** | The API call fails outright (e.g. `404 No endpoints found that support image input`), and the *entire* turn fails, text included. | ❌ No — see [Scope & limitations](#scope--limitations) |
+
+`cvh` targets the first case. It never touches the original image content block — it only **appends** a text description generated by a vision model you configure, via Claude Code's `additionalContext` hook output. That's the whole trick: no schema surgery, no risky content replacement, just an honest text description sitting next to the image the main model can't parse.
+
+> ✅ **Verified against a real Claude Code session.** A model that silently ignores images was tested with and without `cvh`: without it, it guessed the wrong color for a test image; with `cvh` installed, the hook transcript shows `additionalContext` being injected and the model answering correctly. See [`CHANGELOG.md`](./CHANGELOG.md) for details.
+
+## How it works
+
+```mermaid
+flowchart LR
+    A["User pastes image /<br/>tool returns screenshot"] --> B{cvh enabled?}
+    B -- no --> Z["passthrough, no-op"]
+    B -- yes --> C["Extract image bytes<br/>(UserPromptSubmit / PostToolUse)"]
+    C --> D{"Cached by<br/>content hash?"}
+    D -- hit --> F
+    D -- miss --> E["Ask your vision model<br/>(via AI SDK)"]
+    E --> F["additionalContext<br/>injected into Claude Code"]
+```
+
+- **`UserPromptSubmit`** hook scans `~/.claude/image-cache/<session_id>/` for newly pasted images.
+- **`PostToolUse`** hook (`matcher: "*"`) runs a generic recursive extractor over any tool's `tool_response` — verified against three real, structurally different shapes: `Read`'s discriminated object, MCP's content-block array, and `Bash`/`PowerShell`'s flat `isImage` + data-URI string.
+- Both hooks **only ever output `additionalContext`** — never `updatedToolOutput`. This keeps `cvh` simple and safe: no per-tool schema replication, no risk of a silently-dropped hook output because the replacement shape didn't match.
+- Vision inference goes through the [Vercel AI SDK](https://sdk.vercel.ai/), so you can point `cvh` at OpenAI (Chat Completions or Responses), Anthropic, or Gemini — or any OpenAI/Anthropic-compatible gateway.
+- Descriptions are cached on disk by image content hash (`~/.claude/cc-vision-hook/cache/`), shared globally, with a 7-day lazy-expiring TTL — the same image is only ever described once, no matter where it came from.
+
+## Scope & limitations
+
+**`cvh` only helps with models that silently ignore images.** If your model hard-rejects image input at the protocol level (the request itself fails), `cvh` cannot help — it never replaces or removes the original image content block, so the upstream will still see (and reject) it. Run `cvh doctor` or send a manual test request to figure out which category your model falls into before enabling `cvh`.
+
+Other known limitations:
+
+1. Hard-rejection models are out of scope (see above).
+2. Support for "user pastes an image" relies on an **unofficial implementation detail** of Claude Code (`~/.claude/image-cache/` directory scanning). This could break in a future Claude Code release; `cvh` does not attempt version detection or graceful degradation.
+3. `cvh` does not auto-detect model capabilities. It's a plain `enable`/`disable` switch — you decide when to turn it on.
+4. Claude Code only. No support for other agent hosts.
+5. Images are sent to whichever third-party vision provider you configure. You are responsible for that data flow — review your provider's data handling policy if your screenshots may contain sensitive information.
+
+## Install
+
+```bash
+npm install -g cc-vision-hook
+
+cvh install                            # create config + register hooks (idempotent)
+cvh config set provider anthropic      # or: oai / responses / gemini
+cvh config set model <your-vision-model>
+cvh config set apiKey <your-api-key>
+cvh doctor                             # sanity-check config + connectivity
+cvh enable
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `cvh install` | Create config + register hooks (idempotent, safe to re-run) |
+| `cvh uninstall [--purge]` | Remove hook registration; `--purge` also deletes config and cache |
+| `cvh enable` / `cvh disable` | The one and only runtime switch |
+| `cvh status` | Show current state, hook registration, cache stats |
+| `cvh doctor` | Self-check config / hooks / vision model connectivity, plus a boundary reminder |
+| `cvh config get` / `cvh config set <key> <value>` | Read/write config (`provider`/`model`/`baseUrl`/`apiKey`/`timeoutMs`/`maxTokens`) |
+| `cvh test-image <path>` | Manually verify the pipeline: local image → vision model → description |
+
+Every command supports `--json` output for scripting.
+
+## Configuration
+
+`~/.claude/cc-vision-hook.json`:
+
+```json
+{
+  "enabled": true,
+  "provider": "oai",
+  "model": "gpt-4o-mini",
+  "baseUrl": "https://api.openai.com/v1",
+  "apiKey": "sk-...",
+  "timeoutMs": 45000,
+  "maxTokens": 1200,
+  "cache": { "ttlDays": 7 }
+}
+```
+
+The API key is stored in plaintext; the file permission is automatically set to `0600` (owner read/write only).
+
+Environment variable overrides (take priority over the config file): `CVH_ENABLED` / `CVH_PROVIDER` / `CVH_MODEL` / `CVH_BASE_URL` / `CVH_API_KEY` / `CVH_TIMEOUT_MS` / `CVH_MAX_TOKENS`.
+
+## Roadmap
+
+- [ ] `cvh init` — interactive setup wizard.
+- [ ] MCP tools (`vision_ask`, `vision_describe_image`, `vision_describe_data_url`) so an agent can follow up on a previously seen image. The on-disk cache already stores everything needed — the MCP surface just hasn't been wired up yet.
+
+## Troubleshooting
+
+- **Installed but nothing happens** — Claude Code reads `$HOME/.claude/settings.json` (not `$HOME` itself). Make sure the path `cvh install` wrote to matches the one Claude Code actually loads. Run `cvh status` and confirm both hooks are `true` and `enabled` is `true`.
+- **`doctor` reports a connectivity failure** — run `cvh test-image <local-image>` first to isolate whether the problem is in the vision-model call itself or in hook wiring.
+- **The model errors out entirely / the whole turn fails when an image is involved** — you're using a hard-rejection model. `cvh` cannot help here; see [Scope & limitations](#scope--limitations).
+
+## Development
+
+```bash
+bun install
+bun run typecheck   # tsc --noEmit
+bun run build       # emit dist/
+bun test            # fixture-driven unit tests, no real network calls
+```
+
+For local/integration testing, override `~/.claude` with the `CVH_CLAUDE_HOME` environment variable so you never touch your real Claude Code configuration:
+
+```bash
+export CVH_CLAUDE_HOME=/tmp/some-isolated-dir/.claude
+node dist/cli.js install
+```
+
+When wiring this up against a real Claude Code session, set `CVH_CLAUDE_HOME` to `$HOME/.claude` (not `$HOME` itself), and also set `HOME=<isolated dir>` so the `claude` process reads the same `settings.json`.
+
+## Contributing
+
+Issues and PRs are welcome. Please run `bun run ci` (typecheck + test + build) before submitting.
+
+Contributions that add or change behavior should include a [changeset](https://github.com/changesets/changesets):
+
+```bash
+bun run changeset
+```
+
+## Releasing
+
+Releases are published to npm via [Trusted Publishing](https://docs.npmjs.com/trusted-publishers) (OIDC, no long-lived tokens) whenever a `v*` tag is pushed. See [`docs/releasing.md`](./docs/releasing.md) for the full process and [`docs/release-checklist.md`](./docs/release-checklist.md) for the pre-flight checklist.
+
+## License
+
+[MIT](./LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,158 @@
+<div align="center">
+
+# cc-vision-hook
+
+**让"看不懂图片"的 Claude Code 模型拥有眼睛——完全不动你的 prompt。**
+
+`cvh` 是一个纯本地运行的 Claude Code Hook 工具集。当你粘贴图片、或某个工具（`Read` / `Bash` / MCP）产出截图时，`cvh` 会把图片发给你自己配置的视觉模型，再把描述文字以 `additionalContext` 的形式注入回 Claude Code 的上下文——让原本"看不懂图片"的主模型也能真正"看到"图片内容。
+
+[![npm version](https://img.shields.io/npm/v/cc-vision-hook.svg?color=cb3837&logo=npm)](https://www.npmjs.com/package/cc-vision-hook)
+[![npm downloads](https://img.shields.io/npm/dm/cc-vision-hook.svg?color=blue)](https://www.npmjs.com/package/cc-vision-hook)
+[![GitHub stars](https://img.shields.io/github/stars/RainSunMe/cc-vision-hook?style=social)](https://github.com/RainSunMe/cc-vision-hook)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+[![Node >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](package.json)
+
+[English](./README.md) · [简体中文](./README.zh-CN.md)
+
+</div>
+
+---
+
+## 为什么需要它
+
+Claude Code 背后接的模型不一定都支持图片。当一个不支持视觉的模型收到图片请求时，通常会出现两种完全不同的失败方式：
+
+| 失败模式 | 表现 | `cvh` 能解决吗 |
+|---|---|---|
+| **静默忽略** | API 调用成功（HTTP 200），但模型根本没真正理解图片内容——它会瞎猜、幻觉，或者直接说"我看不到图片"。 | ✅ 能——这正是 `cvh` 的目标场景 |
+| **协议层硬拒绝** | API 调用直接失败（例如常见的 `404 No endpoints found that support image input`），**整轮对话**都会失败，连文本部分也一起废弃。 | ❌ 不能——见[适用范围与已知限制](#适用范围与已知限制) |
+
+`cvh` 只解决第一种场景。它从不修改原始的图片内容块，只通过 Claude Code 的 `additionalContext` Hook 输出，**追加**一段由你配置的视觉模型生成的文字描述。整个方案就这么简单：不需要精确还原任何工具的输出 schema，不需要冒险替换原始内容，只是在模型看不懂的图片旁边，放一段诚实的文字描述。
+
+> ✅ **已通过真实 Claude Code 会话验证。** 一个"静默忽略图片"型模型分别在装/未装 `cvh` 的情况下测试：未装时，它把测试图片的颜色猜错了；装了 `cvh` 后，Hook 执行记录显示 `additionalContext` 被正确注入，模型给出了正确答案。详见 [`CHANGELOG.md`](./CHANGELOG.md)。
+
+## 工作原理
+
+```mermaid
+flowchart LR
+    A["用户粘贴图片 /<br/>工具返回截图"] --> B{cvh 已启用?}
+    B -- 否 --> Z["直接放行，不做任何事"]
+    B -- 是 --> C["提取图片字节<br/>(UserPromptSubmit / PostToolUse)"]
+    C --> D{"内容 hash<br/>命中缓存?"}
+    D -- 命中 --> F
+    D -- 未命中 --> E["调用你配置的视觉模型<br/>(经由 AI SDK)"]
+    E --> F["additionalContext<br/>注入 Claude Code 上下文"]
+```
+
+- **`UserPromptSubmit`** Hook 扫描 `~/.claude/image-cache/<session_id>/` 目录，找出新粘贴的图片。
+- **`PostToolUse`** Hook（`matcher: "*"`）用通用递归提取器扫描任意工具的 `tool_response`——已验证覆盖三种结构完全不同的真实样本：`Read` 的判别式对象、MCP 的 content block 数组、`Bash`/`PowerShell` 的扁平 `isImage` 标志 + data URI 字符串。
+- 两个 Hook **永远只输出 `additionalContext`**，从不使用 `updatedToolOutput`。这让 `cvh` 保持简单又安全：不需要为每个工具单独复刻输出 schema，也不用担心替换值 shape 不匹配导致 Hook 输出被 Claude Code 静默丢弃。
+- 视觉推理统一通过 [Vercel AI SDK](https://sdk.vercel.ai/) 完成，你可以把 `cvh` 指向 OpenAI（Chat Completions 或 Responses）、Anthropic、Gemini，或任何兼容 OpenAI/Anthropic 协议的网关。
+- 解析结果按图片内容 hash 缓存在本地磁盘（`~/.claude/cc-vision-hook/cache/`），全局共享，TTL 7 天惰性过期——同一张图无论来自哪里，只会被解析一次。
+
+## 适用范围与已知限制
+
+**`cvh` 只对"静默忽略图片"型模型有效。** 如果你的模型在协议层就直接硬拒绝图片输入（请求本身就失败），`cvh` 无法帮上忙——它从不替换或移除原始的图片内容块，上游依然会看到（并拒绝）它。启用前先跑一下 `cvh doctor` 或手动发一次测试请求，确认你的模型属于哪一类。
+
+其他已知限制：
+
+1. 协议层硬拒绝型模型不在解决范围内（见上）。
+2. "用户粘贴图片"场景的支持依赖 Claude Code 的一个**非官方实现细节**（扫描 `~/.claude/image-cache/` 目录）。未来的 Claude Code 版本可能会让这条路径失效；`cvh` 不做版本检测或优雅降级。
+3. `cvh` 不会自动判断模型能力，只有简单的 `enable`/`disable` 开关——启用与否由你决定。
+4. 仅支持 Claude Code，不支持其他 Agent 宿主。
+5. 图片会被发送给你配置的第三方视觉模型服务商，数据流向由你自己负责——如果截图可能包含敏感信息，请自行评估该服务商的数据处理政策。
+
+## 安装
+
+```bash
+npm install -g cc-vision-hook
+
+cvh install                            # 创建配置 + 注册 Hook（幂等）
+cvh config set provider anthropic      # 或 oai / responses / gemini
+cvh config set model <你的视觉模型>
+cvh config set apiKey <你的-api-key>
+cvh doctor                             # 自检配置与连通性
+cvh enable
+```
+
+## 命令
+
+| 命令 | 说明 |
+|---|---|
+| `cvh install` | 创建配置 + 注册 Hook（幂等，可重复执行） |
+| `cvh uninstall [--purge]` | 移除 Hook 注册；`--purge` 连带删除配置和缓存 |
+| `cvh enable` / `cvh disable` | 唯一的运行开关 |
+| `cvh status` | 查看当前状态、Hook 注册情况、缓存统计 |
+| `cvh doctor` | 自检配置 / Hook / 视觉模型连通性，并提示适用边界 |
+| `cvh config get` / `cvh config set <key> <value>` | 读写配置（`provider`/`model`/`baseUrl`/`apiKey`/`timeoutMs`/`maxTokens`） |
+| `cvh test-image <path>` | 手动验证：本地图片 → 视觉模型 → 描述文字 |
+
+所有命令均支持 `--json` 输出，方便脚本调用。
+
+## 配置文件
+
+`~/.claude/cc-vision-hook.json`：
+
+```json
+{
+  "enabled": true,
+  "provider": "oai",
+  "model": "gpt-4o-mini",
+  "baseUrl": "https://api.openai.com/v1",
+  "apiKey": "sk-...",
+  "timeoutMs": 45000,
+  "maxTokens": 1200,
+  "cache": { "ttlDays": 7 }
+}
+```
+
+API Key 以明文存储，文件权限会自动设为 `0600`（仅当前用户可读写）。
+
+环境变量覆盖（优先级高于配置文件）：`CVH_ENABLED` / `CVH_PROVIDER` / `CVH_MODEL` / `CVH_BASE_URL` / `CVH_API_KEY` / `CVH_TIMEOUT_MS` / `CVH_MAX_TOKENS`。
+
+## 路线图
+
+- [ ] `cvh init` —— 交互式安装向导。
+- [ ] MCP 工具（`vision_ask`、`vision_describe_image`、`vision_describe_data_url`），支持 Agent 对已解析过的图片进行事后追问。底层磁盘缓存已经具备所需数据，只是还没有暴露 MCP 入口。
+
+## 排障
+
+- **装了但看起来没生效**：Claude Code 读取的是 `$HOME/.claude/settings.json`（不是 `$HOME` 本身），确认 `cvh install` 写入的路径和 Claude Code 实际加载的路径一致。用 `cvh status` 确认两个 Hook 均为 `true`，`enabled` 为 `true`。
+- **`doctor` 报连通性失败**：先用 `cvh test-image <本地图片>` 单独验证视觉模型调用链路，排除 Hook 集成层面的问题。
+- **模型收到图片直接报错、整轮对话失败**：说明你用的是「协议层硬拒绝」型模型，`cvh` 对此无效，见[适用范围与已知限制](#适用范围与已知限制)。
+
+## 开发
+
+```bash
+bun install
+bun run typecheck   # tsc --noEmit
+bun run build       # 产出 dist/
+bun test            # fixture 驱动的单测，不发真实网络请求
+```
+
+本地/集成测试时，可用 `CVH_CLAUDE_HOME` 环境变量覆盖 `~/.claude` 根目录，避免影响你真实的 Claude Code 配置：
+
+```bash
+export CVH_CLAUDE_HOME=/tmp/some-isolated-dir/.claude
+node dist/cli.js install
+```
+
+如果要联调真实的 Claude Code 会话，需要把 `CVH_CLAUDE_HOME` 设为 `$HOME/.claude`（不是 `$HOME` 本身），同时设置 `HOME=<隔离目录>`，这样 `claude` 进程才会读到同一份 `settings.json`。
+
+## 贡献
+
+欢迎提交 Issue 和 PR。提交前请先跑通 `bun run ci`（typecheck + test + build）。
+
+涉及行为变更的贡献请附带一个 [changeset](https://github.com/changesets/changesets)：
+
+```bash
+bun run changeset
+```
+
+## 发布
+
+发布通过 npm [Trusted Publishing](https://docs.npmjs.com/trusted-publishers)（基于 OIDC，不存任何长期 token）完成，推送 `v*` tag 即触发。完整流程见 [`docs/releasing.md`](./docs/releasing.md)，发布前检查清单见 [`docs/release-checklist.md`](./docs/release-checklist.md)。
+
+## 许可证
+
+[MIT](./LICENSE)

package/dist/cache.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 图片解析结果的本地磁盘缓存。
+ *
+ * 设计决策：
+ * - Key：图片字节内容的 sha256（内容寻址，天然去重，跨来源——粘贴/工具产图——同一张图只解析一次）；
+ * - 作用域：全局共享，不按 session/project 隔离；
+ * - TTL：7 天，惰性清理（读写时顺带清理过期条目，不需要常驻后台任务）；
+ * - 存储位置：`~/.claude/cc-vision-hook/cache/`，每个条目一对文件（`.json` 元数据 + `.bin` 原图字节）。
+ */
+export interface CacheEntry {
+    /** 缓存条目 ID（等于内容 sha256 的前缀，作为对外暴露的 image_id）。 */
+    imageId: string;
+    mimeType: string;
+    createdAt: string;
+    expiresAt: string;
+    /** 产生这张图片的工具名（如 "Read"、"Bash"、"mcp__xxx__yyy"），粘贴场景下为 "paste"。 */
+    sourceTool: string;
+    description: string;
+}
+/**
+ * 对图片原始字节计算内容 hash，作为缓存 key（image_id）。
+ *
+ * @param bytes - 图片的原始二进制数据
+ * @returns 64 位十六进制 sha256 摘要，取前 16 位加 `img_` 前缀作为短 ID
+ */
+export declare const computeImageId: (bytes: Buffer) => string;
+/**
+ * 按 image_id 查询缓存条目（元数据），命中且未过期才返回。
+ *
+ * @param imageId - 缓存条目 ID
+ * @returns 命中的元数据，未命中或已过期返回 null
+ */
+export declare const getCacheEntry: (imageId: string) => Promise<CacheEntry | null>;
+/**
+ * 读取缓存条目对应的原图字节（用于 `vision_ask` 追问时重新提问）。
+ *
+ * @param imageId - 缓存条目 ID
+ * @returns 原图二进制数据，不存在时返回 null
+ */
+export declare const getCachedImageBytes: (imageId: string) => Promise<Buffer | null>;
+/**
+ * 按内容 hash 查找是否已有缓存（用于"命中即跳过视觉解析调用"）。
+ *
+ * @param bytes - 图片原始字节
+ * @returns 命中的缓存条目，未命中返回 null
+ */
+export declare const findCacheByBytes: (bytes: Buffer) => Promise<CacheEntry | null>;
+/**
+ * 写入一条新的缓存条目：落盘原图字节 + 元数据（含描述文本），并计算好 TTL 过期时间。
+ *
+ * @param bytes - 图片原始字节
+ * @param mimeType - 图片 MIME 类型
+ * @param sourceTool - 产生这张图片的工具名
+ * @param description - 视觉模型给出的描述文本
+ * @param ttlDays - 缓存有效期（天），来自用户配置
+ * @returns 写入后的缓存条目（含 image_id，供 additionalContext 引用）
+ */
+export declare const putCacheEntry: (bytes: Buffer, mimeType: string, sourceTool: string, description: string, ttlDays: number) => Promise<CacheEntry>;
+/**
+ * 统计当前缓存条目数量，用于 `cvh status` 展示。
+ *
+ * @returns 未过期的缓存条目数量
+ */
+export declare const countCacheEntries: () => Promise<number>;
+/**
+ * 获取缓存目录占用的磁盘大小（字节），用于 `cvh status`/`doctor` 展示。
+ *
+ * @returns 缓存目录总大小（字节），目录不存在时返回 0
+ */
+export declare const getCacheDiskUsage: () => Promise<number>;

package/dist/cache.js

@@ -0,0 +1,164 @@
+/**
+ * 图片解析结果的本地磁盘缓存。
+ *
+ * 设计决策：
+ * - Key：图片字节内容的 sha256（内容寻址，天然去重，跨来源——粘贴/工具产图——同一张图只解析一次）；
+ * - 作用域：全局共享，不按 session/project 隔离；
+ * - TTL：7 天，惰性清理（读写时顺带清理过期条目，不需要常驻后台任务）；
+ * - 存储位置：`~/.claude/cc-vision-hook/cache/`，每个条目一对文件（`.json` 元数据 + `.bin` 原图字节）。
+ */
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile, readdir, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { getCvhHomeDir } from "./config.js";
+const getCacheDir = () => join(getCvhHomeDir(), "cache");
+const metaPath = (imageId) => join(getCacheDir(), `${imageId}.json`);
+const binPath = (imageId) => join(getCacheDir(), `${imageId}.bin`);
+/**
+ * 对图片原始字节计算内容 hash，作为缓存 key（image_id）。
+ *
+ * @param bytes - 图片的原始二进制数据
+ * @returns 64 位十六进制 sha256 摘要，取前 16 位加 `img_` 前缀作为短 ID
+ */
+export const computeImageId = (bytes) => {
+    const full = createHash("sha256").update(bytes).digest("hex");
+    return `img_${full.slice(0, 16)}`;
+};
+/**
+ * 按 TTL 惰性清理过期缓存条目。每次读写缓存时调用一次，成本很低（只扫元数据文件）。
+ *
+ * @param ttlDays - 配置里的 TTL 天数，仅用于新建条目时计算 expiresAt，本函数只看条目自带的 expiresAt
+ */
+const cleanupExpired = async () => {
+    const dir = getCacheDir();
+    let files;
+    try {
+        files = await readdir(dir);
+    }
+    catch {
+        return; // 目录还不存在，无需清理
+    }
+    const now = Date.now();
+    for (const file of files) {
+        if (!file.endsWith(".json"))
+            continue;
+        const imageId = file.slice(0, -".json".length);
+        try {
+            const raw = await readFile(join(dir, file), "utf8");
+            const entry = JSON.parse(raw);
+            if (new Date(entry.expiresAt).getTime() < now) {
+                await unlink(metaPath(imageId)).catch(() => { });
+                await unlink(binPath(imageId)).catch(() => { });
+            }
+        }
+        catch {
+            // 元数据损坏，直接按过期处理，避免脏数据常驻
+            await unlink(join(dir, file)).catch(() => { });
+        }
+    }
+};
+/**
+ * 按 image_id 查询缓存条目（元数据），命中且未过期才返回。
+ *
+ * @param imageId - 缓存条目 ID
+ * @returns 命中的元数据，未命中或已过期返回 null
+ */
+export const getCacheEntry = async (imageId) => {
+    try {
+        const raw = await readFile(metaPath(imageId), "utf8");
+        const entry = JSON.parse(raw);
+        if (new Date(entry.expiresAt).getTime() < Date.now())
+            return null;
+        return entry;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * 读取缓存条目对应的原图字节（用于 `vision_ask` 追问时重新提问）。
+ *
+ * @param imageId - 缓存条目 ID
+ * @returns 原图二进制数据，不存在时返回 null
+ */
+export const getCachedImageBytes = async (imageId) => {
+    try {
+        return await readFile(binPath(imageId));
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * 按内容 hash 查找是否已有缓存（用于"命中即跳过视觉解析调用"）。
+ *
+ * @param bytes - 图片原始字节
+ * @returns 命中的缓存条目，未命中返回 null
+ */
+export const findCacheByBytes = async (bytes) => {
+    await cleanupExpired();
+    return getCacheEntry(computeImageId(bytes));
+};
+/**
+ * 写入一条新的缓存条目：落盘原图字节 + 元数据（含描述文本），并计算好 TTL 过期时间。
+ *
+ * @param bytes - 图片原始字节
+ * @param mimeType - 图片 MIME 类型
+ * @param sourceTool - 产生这张图片的工具名
+ * @param description - 视觉模型给出的描述文本
+ * @param ttlDays - 缓存有效期（天），来自用户配置
+ * @returns 写入后的缓存条目（含 image_id，供 additionalContext 引用）
+ */
+export const putCacheEntry = async (bytes, mimeType, sourceTool, description, ttlDays) => {
+    await mkdir(getCacheDir(), { recursive: true });
+    const imageId = computeImageId(bytes);
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + ttlDays * 24 * 60 * 60 * 1000);
+    const entry = {
+        imageId,
+        mimeType,
+        createdAt: now.toISOString(),
+        expiresAt: expiresAt.toISOString(),
+        sourceTool,
+        description,
+    };
+    await writeFile(binPath(imageId), bytes);
+    await writeFile(metaPath(imageId), JSON.stringify(entry, null, 2));
+    return entry;
+};
+/**
+ * 统计当前缓存条目数量，用于 `cvh status` 展示。
+ *
+ * @returns 未过期的缓存条目数量
+ */
+export const countCacheEntries = async () => {
+    await cleanupExpired();
+    try {
+        const files = await readdir(getCacheDir());
+        return files.filter((f) => f.endsWith(".json")).length;
+    }
+    catch {
+        return 0;
+    }
+};
+/**
+ * 获取缓存目录占用的磁盘大小（字节），用于 `cvh status`/`doctor` 展示。
+ *
+ * @returns 缓存目录总大小（字节），目录不存在时返回 0
+ */
+export const getCacheDiskUsage = async () => {
+    let total = 0;
+    try {
+        const dir = getCacheDir();
+        const files = await readdir(dir);
+        for (const file of files) {
+            const s = await stat(join(dir, file));
+            total += s.size;
+        }
+    }
+    catch {
+        return 0;
+    }
+    return total;
+};
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/claudeSettings.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 对 `~/.claude/settings.json` 里 Hook 注册条目的幂等读写。
+ *
+ * 幂等标识：用固定的 command 字符串（"cvh hook user-prompt-submit"/"cvh hook post-tool-use"）
+ * 作为唯一标识——install 前先检查是否已存在同样的条目，避免重复注册；uninstall 时精确按这个
+ * 字符串过滤移除，不误删用户自己配置的其他 Hook。
+ */
+export declare const USER_PROMPT_SUBMIT_COMMAND = "cvh hook user-prompt-submit";
+export declare const POST_TOOL_USE_COMMAND = "cvh hook post-tool-use";
+/**
+ * 幂等地在 `~/.claude/settings.json` 中注册 `UserPromptSubmit` 和 `PostToolUse` 两个 Hook。
+ * 已存在同样 command 的条目时跳过，不重复添加；不会动用户已有的其他 Hook 配置。
+ *
+ * @returns 本次实际新增的 Hook 数量（0 表示已经是安装好的状态，重复执行安全）
+ */
+export declare const installHooks: () => Promise<number>;
+/**
+ * 精确移除 cvh 注册的两个 Hook 条目，不影响用户配置的其他 Hook。
+ *
+ * @returns 本次实际移除的 Hook 数量
+ */
+export declare const uninstallHooks: () => Promise<number>;
+/**
+ * 检查两个 Hook 是否都已注册（用于 `cvh status`/`doctor`）。
+ *
+ * @returns 分别表示两个 Hook 是否已注册
+ */
+export declare const checkHooksInstalled: () => Promise<{
+    userPromptSubmit: boolean;
+    postToolUse: boolean;
+}>;