💡阅读指南

前面已经分别讨论了 SPEC 的栏目和用户故事。这一节不再继续解释概念，而是把独立图片需求整理成一份完整的示例 spec.md，观察各个栏目怎样共同形成可验收的约定。

6.1 示例 SPEC

下面这份 SPEC 只覆盖“独立图片怎样形成文字证据”这一项功能。它不是胶囊系统的完整 SPEC，但作为一个独立功能，结构已经完整。

Markdown
# Feature Specification: 独立图片形成文字证据

**Feature Branch**: `001-independent-image-evidence`
**Created**: 2026-08-14
**Status**: Draft
**Input**: 用户提交一张没有正文、图注或补充说明作为上下文的图片，
系统判断它能否独立形成知识，并生成相应的文字证据。

## Scope Boundaries

- 本功能处理没有正文、图注或用户补充说明作为上下文的独立图片。
- 本功能负责判断图片能否形成文字证据，不承担图片文件的长期保存。
- PDF 中嵌入的图片和网页正文中的图片不属于本功能范围。

## User Scenarios & Testing

### User Story 1 - 把独立图片转换成文字证据 (Priority: P1)

作为个人知识库的使用者，我希望系统只把能够独立表达知识的图片
转换成文字证据，避免装饰图和普通照片进入知识内容。

**Why this priority**: 这是独立图片进入知识系统的主路径。没有这项能力，
系统既无法形成图片证据，也无法阻止无关图片进入知识内容。

**Independent Test**: 分别提交一张信息完整的流程图、一张普通风景图，检查系统是否给出二种明确且不同的处理结果。

**Acceptance Scenarios**:

1. **Given** 用户提交的图片有明确主题，并且其中的事实、步骤、关系或数据
   不依赖外部上下文也能理解，**When** 系统处理图片，**Then** 系统生成文字证据，
   保留这些主要信息，同时不保存图片文件。
2. **Given** 用户提交的是没有知识主题和事实信息的普通风景图，
   **When** 系统处理图片，**Then** 系统不生成文字证据，也不保存图片文件。
3. **Given** 用户提交的图片主体模糊或内容残缺，仅凭图片无法确认完整事实，
   **When** 系统处理图片，**Then** 系统把结果标记为待确认，并且不补写
   无法确认的内容。
4. **Given** 独立图片来自一个 URL，**When** 系统完成处理，
   **Then** 系统把处理结果与该 URL 关联。
5. **Given** 用户直接提交独立图片，并且没有提供来源 URL，
   **When** 系统完成处理，**Then** 系统不为该图片建立原始证据。

### Edge Cases

- 图片有标题，但主体内容模糊或残缺，无法形成完整事实。
- 图片包含大量文字，但这些文字只是广告、装饰语或水印。
- 图片表达了完整知识，但没有可以直接提取的文字，例如纯图形流程图。
- 来源 URL 无法再次访问，但图片内容已经完成本次判断。

## Requirements

### Functional Requirements

- **FR-001**: 系统必须把“有明确主题，并且包含可独立理解的事实、步骤、
  关系或数据”作为独立图片形成文字证据的必要条件。
- **FR-002**: 符合条件的图片必须生成文字证据，证据必须保留图片表达的
  主要事实及其关系。
- **FR-003**: 没有明确知识主题，或者不包含可独立理解的事实、步骤、关系
  或数据的图片，不得生成文字证据。
- **FR-004**: 无法确认完整含义的图片必须进入待确认状态，系统不得编造
  或补写无法从图片中确认的信息。
- **FR-005**: 图片来自 URL 时，系统必须把 URL 与处理结果关联；没有 URL 时，
  不得建立原始证据。
- **FR-006**: 系统不得把独立图片文件保存为原始证据或衍生证据。
- **FR-007**: 每次处理必须形成明确状态：已生成文字证据、不生成文字证据
  或待确认。

### Key Entities

- **独立图片输入**：用户本次提交的图片，以及可选的来源 URL。
- **处理结果**：记录本次判断状态、判断理由，以及是否形成文字证据。
- **文字证据**：从有效图片中形成的文本，记录主要事实、步骤、关系或数据。
- **原始证据**：图片存在来源 URL 时保存的 URL，并与处理结果保持关联。

## Success Criteria

### Measurable Outcomes

- **SC-001**: 对预先标明预期结果的有效图片、无效图片和待确认图片样例，
  系统的处理状态与预期结果的一致率达到 100%。
- **SC-002**: 带有 URL 的验收样例，其处理结果与来源 URL 的关联率达到 100%。
- **SC-003**: 所有验收样例都产生一个明确处理状态，不出现没有结果的输入。

## Assumptions

- 当前使用者是个人知识库的所有者，不涉及多人审批和企业合规流程。
- 用户接受独立图片处理完成后不长期保存原始图片文件。
- 如果用户在提交图片时另外提供了正文、图注或文字说明，系统需要把图片和这些内容放在一起理解。
- 待确认状态表示系统没有形成有效文字证据，需要用户以后决定是否继续处理。

6.2 英文字段

SPEC 文档通常可以先由 AI 生成初稿。比如上面这份 SPEC，就是先由 GPT 生成，然后再由我手动修改。GPT 保留了 Spec Kit 模板中的英文字段，我也没有特意把它们换成中文。当然，你也可以要求 GPT 在生成 SPEC 时使用中文字段。

大部分字段直接翻译就能理解。比如，Key Entities 就是“关键实体”，Success Criteria 就是“成功标准”。这些字段的中英文对照放在本节最后的“学点英语”中，这里不再逐个展开。

真正需要单独解释的是 Given、When 和 Then。它们放在一起时，不是三个普通的英文字段，而是一条验收场景的固定结构：

Text
Given：在什么前提下
When：当什么动作发生时
Then：系统应该产生什么结果

Given 描述系统开始处理之前已经成立的条件。它可以是用户提交了某种输入，也可以是系统已经处在某个状态。When 描述触发这次验收的动作。Then 则规定动作发生以后，系统必须给出什么结果。

以前面的普通风景图为例，这条验收场景可以按中文读成：

在用户提交了一张没有知识主题和事实信息的普通风景图时（Given），当系统处理这张图片（When），系统不应生成文字证据，也不应保存图片文件（Then）。

这样写的价值在于，测试人员不需要猜测这条需求应该怎样验收。他只需要准备 Given 规定的输入，执行 When 规定的动作，再核对是否出现了 Then 规定的结果。

6.3 不要看不起中英混合

很多人会认为中英混合不专业。但我的看法不同。英文相对于中文来说，有更强的标识性。如果你对此有怀疑，那么可以把上述 SPEC 中的英文字段，更换成中文，你会发现整个文档的可读性变差了。

如果自己特意写中英混合，那大可不必。但如果是 AI 生成就这样，那没有必要纠正 AI 必须全中文。

6.4 从需求判断到验收约定

这份 SPEC 没有规定使用哪个视觉模型，也没有决定文字识别工具、提示词和判断阈值。它只固定了用户目标、功能范围、典型场景、特殊输入、系统行为、核心数据和成功标准。

因此，开发完成以后，验收者可以直接准备流程图、风景图和信息残缺的图表，逐项检查系统是否产生预期状态。至于系统怎样识别图片、怎样保存处理结果，要留给后面的 Plan 和 Tasks。

6.5 ■ 学点英语

中文 English 音标 说明
用户故事 User Story /ˈjuːzər ˈstɔːri/ 从用户目标和价值出发描述需求
独立测试 Independent Test /ˌɪndɪˈpendənt test/ 说明如何单独验证这条用户故事
验收场景 Acceptance Scenario /əkˈseptəns səˈnerioʊ/ 用明确的前提、动作和结果表达验收条件
前提—动作—结果 Given-When-Then /ˈɡɪvən wen ðen/ 把一条验收场景组织成前提条件、触发动作和预期结果
功能需求 Functional Requirement /ˈfʌŋkʃənəl rɪˈkwaɪərmənt/ 规定系统必须执行或禁止的行为
成功标准 Success Criteria /səkˈses kraɪˈtɪriə/ 用来判断整项功能是否成功的标准，缩写为 SC