read-picture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Read a picture

读取图片

The answer to a question about a picture is a measurement, and this repo throws exactly one class of measurement away: the one that came from looking. A ticket whose description is a single annotated screenshot decided that a hardcoded label was a requirement rather than a bug — and every later run re-downloaded and re-read that same picture to learn the same sentence.

So this skill reads the picture once per question, writes the answer down, and hands rows back. It is a reader, not a store: the caller passes paths and a question, and gets facts (ADR 0135).

  ONE CALL = ONE QUESTION, N PICTURES
  ──────────────────────────────────────────────
  ① THE QUESTION      a kind from the named set
  │                   plus the caller's detail
  ▼
  ② LOOK IT UP      hash the bytes, ask the record
  │                   hit / candidates / no-answer
  ▼
  ③ READ ON A MISS    open the picture, answer ONLY
  │                   the question, append one line
  ▼
  ④ HAND BACK       rows, plus hit and miss counts
                      and any not-re-checked flag

针对图片的问题答案通常是一种信息提取结果，而本仓库专门解决一类重复劳动问题：避免反复读取同一张图片来获取相同的答案。曾有一个工单仅包含一张带标注的截图，其中硬编码标签被判定为需求而非bug——但后续每次运行都会重新下载并读取这张相同的图片来获取相同的内容。

因此，本技能针对每个问题仅读取一次图片，记录答案后返回结果。它是一个读取工具而非存储工具：调用者传入文件路径和问题，获取事实信息（ADR 0135）。

  ONE CALL = ONE QUESTION, N PICTURES
  ──────────────────────────────────────────────
  ① THE QUESTION      a kind from the named set
  │                   plus the caller's detail
  ▼
  ② LOOK IT UP      hash the bytes, ask the record
  │                   hit / candidates / no-answer
  ▼
  ③ READ ON A MISS    open the picture, answer ONLY
  │                   the question, append one line
  ▼
  ④ HAND BACK       rows, plus hit and miss counts
                      and any not-re-checked flag

① Take the question as a kind, plus detail

① 将问题拆分为类型和细节

The record is keyed on the picture's bytes and the question, so the question has to be a name from a set rather than free prose — two skills phrasing the same need differently would otherwise never share an answer, and nothing would report the miss (ADR 0138).

bash

python "${CLAUDE_PLUGIN_ROOT}/scripts/picture-record.py" kinds

The set and what each kind means live in

${CLAUDE_PLUGIN_ROOT}/references/picture-record-contract.md

. Read it before choosing.

If no kind fits, take
other
— and add the new kind to that contract's table in this same change. A question answered once should never be improvised twice.

Under the kind, state the caller's detail: what specifically is being asked ("the words on the primary button in the Send dialog"). The detail is part of the key.

记录的键由图片字节和问题共同决定，因此问题必须是集合中的命名类型而非自由文本——否则两个技能对同一需求的不同表述将无法共享答案，也无法记录未命中情况（ADR 0138）。

bash

python "${CLAUDE_PLUGIN_ROOT}/scripts/picture-record.py" kinds

问题类型集合及其含义存储在

${CLAUDE_PLUGIN_ROOT}/references/picture-record-contract.md

中。选择类型前请先阅读该文档。

如果没有匹配的类型，请选择
other
——并在本次变更中将新类型添加到该契约的表格中。已回答过的问题不应被重复处理。

在类型之下，需说明调用者的细节：具体询问的内容（如“发送对话框中主按钮上的文字”）。细节是键的一部分。

② Look it up before opening anything

② 先查询记录再操作图片

bash

python "${CLAUDE_PLUGIN_ROOT}/scripts/picture-record.py" lookup \
    --file "<image path>" --kind <kind> --detail "<detail>" --json

Three outcomes, and only one of them lets you skip looking:

outcome	what to do
`hit`	Use the stored answer. Do not open the picture.
`candidates`	Rows exist for this picture and kind, but none answers this detail. Read the candidates, then default to opening the picture.
`no-answer`	Open the picture.

A near-miss is a miss. A stored row about the page title does not answer a question about the confirm button. Serving it anyway manufactures the failure

generating-test-cases

names — a value that is genuinely sourced but is the class rather than the instance, which slips the source check precisely because it looks verified. When the candidate does not plainly cover what was asked, read the picture.

When the bytes are gone — a temp download that was cleaned up, an attachment nobody can re-fetch — look up by source instead of by file:

bash

python "${CLAUDE_PLUGIN_ROOT}/scripts/picture-record.py" lookup \
    --source "<url or original path>" --kind <kind> --detail "<detail>" --json

That result comes back with

bytes_verified: false

. Carry that flag to the caller. A row nobody can re-check looks exactly like one verified a minute ago, and the caller about to quote it onto a published page has to be able to see the difference (ADR 0139).

bash

python "${CLAUDE_PLUGIN_ROOT}/scripts/picture-record.py" lookup \
    --file "<image path>" --kind <kind> --detail "<detail>" --json

有三种结果，只有一种可以跳过图片读取：

结果	处理方式
`hit`	使用存储的答案，无需打开图片。
`candidates`	存在该图片和类型的记录，但没有匹配当前细节的答案。先查看候选结果，再默认打开图片读取。
`no-answer`	打开图片读取。

近似匹配仍视为未命中。 关于页面标题的存储记录无法回答确认按钮相关的问题。若强行返回会导致

generating-test-cases

中定义的失败情况——结果看似有来源，但属于类别而非实例，会因看似已验证而绕过来源检查。当候选结果未明确覆盖问题内容时，需读取图片。

当图片文件不存在时——如临时下载文件已被清理、附件无法重新获取——可通过来源而非文件查询：

bash

python "${CLAUDE_PLUGIN_ROOT}/scripts/picture-record.py" lookup \
    --source "<url or original path>" --kind <kind> --detail "<detail>" --json

该结果会带有

bytes_verified: false

标记。需将该标记传递给调用者。 无法重新验证的记录与刚验证的记录外观一致，而调用者若要将结果引用到发布页面，必须能区分两者（ADR 0139）。

③ On a miss, read the picture and answer only what was asked

③ 未命中时，读取图片并仅回答指定问题

Open the image and answer the question. Then record it:

bash

python "${CLAUDE_PLUGIN_ROOT}/scripts/picture-record.py" append \
    --file "<image path>" --kind <kind> --detail "<detail>" \
    --answer "<the answer>" --asked-by "<calling skill>"

When the bytes came from somewhere that will not last - a ticket attachment downloaded to a temp path, the case

ticket-trace

hits on every run - pass

--source

too, so the record keeps the durable identity rather than a path that is gone by tomorrow.

--file

still supplies the bytes to hash;

--source

supplies what the row is found by later:

bash

python "${CLAUDE_PLUGIN_ROOT}/scripts/picture-record.py" append \
    --file "<temp download path>" --source "<the ADO attachment URL>" \
    --source-kind ado-attachment \
    --kind requirement --detail "<detail>" \
    --answer "<the answer>" --asked-by "ticket-trace"

Record only the answer. Not the customer name that happened to be on screen, not the quote number, not the rest of the window. A picture of a running system carries more than the thing being asked about, and this file is committed (ADR 0137).

No credential reaches the record. A signed link is a credential for the record it names. It stays out of the answer, out of the record and out of the commit — this one does not bend for any caller.

Quote on-screen words exactly as the product spells them. The whole value of a picture over a diagram is that it carries the real label, so "Send quote" is not "Send".

打开图片并回答问题，然后记录结果：

bash

python "${CLAUDE_PLUGIN_ROOT}/scripts/picture-record.py" append \
    --file "<image path>" --kind <kind> --detail "<detail>" \
    --answer "<the answer>" --asked-by "<calling skill>"

当图片来自临时存储位置时——如下载到临时路径的工单附件，

ticket-trace

每次运行都会遇到这种情况——需同时传入

--source

参数，确保记录保存持久标识而非次日就会失效的路径。

--file

仍用于提供字节进行哈希；

--source

用于后续查询该记录：

bash

python "${CLAUDE_PLUGIN_ROOT}/scripts/picture-record.py" append \
    --file "<temp download path>" --source "<the ADO attachment URL>" \
    --source-kind ado-attachment \
    --kind requirement --detail "<detail>" \
    --answer "<the answer>" --asked-by "ticket-trace"

仅记录答案。 不要记录屏幕上出现的客户名称、报价编号或窗口其他内容。运行系统的截图包含的信息远多于问题所问内容，而该记录文件会被提交（ADR 0137）。

凭证不得进入记录。 签名链接是对应记录的凭证，需避免将其纳入答案、记录或提交内容——本技能不会为任何调用者破例。

严格按照产品拼写引用屏幕文字。 截图相较于示意图的核心价值在于其包含真实标签，因此“Send quote”不能简写为“Send”。

④ Hand back rows, counts, and any flag

④ 返回记录行、计数和标记

Return to the caller, per picture: the kind, the detail, the answer, and whether it was a hit, a fresh read, or a flagged row. Then the run's counts — how many hits, how many candidates-only, how many read fresh, how many not re-checked.

The counts are not decoration. A run where every call is a miss says the kind set no longer fits the questions being asked, and that is the signal to extend the set rather than keep paying.

向调用者返回每张图片的信息：类型、细节、答案，以及结果类型（命中、新读取、带标记记录）。同时返回本次运行的计数——命中数、仅候选结果数、新读取数、未重新验证数。

这些计数并非装饰项。若所有调用均未命中，说明类型集合已无法匹配当前问题，此时应扩展类型集合而非继续重复劳动。

What this skill refuses

本技能拒绝处理的情况

To answer a question it was not asked, or to transcribe a picture in full.
To serve a near-miss row as a hit. When in doubt, open the picture.
To put a credential, a customer identifier, or anything else it merely saw into the record.
To present a
bytes_verified: false
row as verified.
To hand back an answer with no picture and no row.
```
no-answer
```
is the honest result, and the caller decides what to do about it.

回答未被询问的问题，或对图片进行完整转录。
将近似匹配的记录视为命中结果。存疑时请打开图片读取。
将凭证、客户标识符或其他仅在图片中看到的内容存入记录。
将
bytes_verified: false
的记录视为已验证结果。
在无图片且无记录的情况下返回答案。
```
no-answer
```
是诚实的结果，由调用者决定后续处理方式。

Red flags — stop and go back a step

危险信号——请停止操作并返回上一步

thought	what it means
"There is a row for this image, close enough"	Check the detail. A near-miss is a miss — ②
"I will transcribe everything so future callers are covered"	The first caller cannot know what a later one needs, and this file is committed — ③
"The file is missing, I will answer from the row"	You may, but the flag travels with it — ②
"No kind fits, I will write my own phrasing"	Take `other` and add it to the contract — ①
"I will record the counts at the end"	Nothing else reports a hit that did not happen — ④

想法	含义
“这张图片已有记录，差不多能用”	检查细节。近似匹配仍视为未命中——参见步骤②
“我要转录所有内容，方便后续调用者使用”	第一个调用者无法预知后续需求，且该记录文件会被提交——参见步骤③
“文件丢失了，我直接用记录里的答案”	可以使用，但需附带标记——参见步骤②
“没有匹配的类型，我自己写个表述”	选择 `other` 并将新类型添加到契约中——参见步骤①
“我最后再记录计数”	没有其他方式能报告未发生的命中情况——参见步骤④

read-picture

Original

Translation

Read a picture

读取图片

① Take the question as a kind, plus detail

① 将问题拆分为类型和细节

② Look it up before opening anything

② 先查询记录再操作图片

③ On a miss, read the picture and answer only what was asked

③ 未命中时，读取图片并仅回答指定问题

④ Hand back rows, counts, and any flag

④ 返回记录行、计数和标记

What this skill refuses

本技能拒绝处理的情况

Red flags — stop and go back a step

危险信号——请停止操作并返回上一步

Related skills

相关技能