背景
想搞一个数据标注系统，我没有这方面经验，这两天刚好用上opencode，想做一个实践。
Step1 先整一个明确的需求文档
需求文档比较难整格式，我只有一些我想要让这个标注系统达成的要求，然后我就让chatgpt老师给我输出一个完整的需求文档。
我的输入：
我想让AI agent帮我写一个标注系统的代码，我需要先梳理清楚我的需求，但是我的需求可能目前还不够清晰。我想让这个标注系统可以做到以下几件事情： 1、服务起来后，我可以通过网页打开这个服务； 2、标注的第一页是能上传一个我待标注的数据文件，这个数据文件我想是json格式； 3、上传后能能自助解析我json文件里，每一个元素有多少个字段，每个字段的格式和示例； 4、然后让我选在具体标注页面里，哪些字段需要显示出来； 5、更关键的是有字段是图像字段，但是json文件里只有图像的相对路径地址，在标注页面里需要能够根据这个相对地址取到这个图像； 6、还有一个要求，用户每标注完一条数据，可以把他的标注结果及时保存，其中有几个字段可以由用户指定标注时会修改的字段，并且需要保存标注人信息。 现在请你根据我的上述要求，写一份完整的需求文档，我好让AI-Agent开始帮我写代码。chatgpt老师的输出：
下面我帮你把“想法级需求”整理成一份**结构化、可直接交给 AI Agent 开发的完整需求文档（PRD）**。我会尽量做到：清晰、无歧义、可实现、可拆解。
---
# 🧾 标注系统需求文档（PRD）
## 一、项目背景
为了提高数据标注效率，需要开发一个**通用的 Web 标注系统**，支持上传 JSON 数据、自定义字段展示、图像加载、在线标注及实时保存。
系统目标：
* 降低标注工具开发成本（通用化）
* 支持不同 JSON 结构的数据
* 支持图像 + 文本混合标注
* 支持多人标注及标注记录追踪
---
## 二、系统总体功能
系统分为 4 个核心模块：
1. **数据上传与解析模块**
2. **字段配置模块（标注配置）**
3. **标注执行模块（核心页面）**
4. **结果存储与管理模块**
---
## 三、功能需求详述
### 3.1 服务访问
#### 功能描述
* 系统启动后提供 Web 服务
* 用户通过浏览器访问
#### 要求
* 支持本地访问（如：[http://localhost:xxxx）](http://localhost:xxxx）)
* 后续可扩展为部署服务（可选）
---
### 3.2 数据上传
#### 功能描述
用户上传待标注数据文件
#### 输入要求
* 文件格式：JSON
* 支持两种结构：
* JSON Array（推荐）
* JSON Lines（可选）
#### 示例
```json
[
{
"id": 1,
"text": "这是一段文本",
"image_path": "images/1.jpg"
}
]
```
#### 功能点
* 文件上传（前端按钮）
* 后端保存文件
* 校验 JSON 格式是否合法
---
### 3.3 JSON 自动解析
#### 功能描述
系统自动分析 JSON 数据结构
#### 输出内容
解析结果需包括：
1. 字段列表
2. 每个字段：
* 字段名
* 数据类型（string / number / list / object）
* 示例值（前 N 条）
* 是否为空（统计）
#### 示例输出
```json
{
"fields": [
{
"name": "text",
"type": "string",
"example": "这是一段文本"
},
{
"name": "image_path",
"type": "string",
"example": "images/1.jpg"
}
]
}
```
---
### 3.4 字段选择（标注配置）
#### 功能描述
用户选择在标注页面展示哪些字段
#### 配置项
每个字段支持以下配置：
| 配置项 | 描述 |
| ------- | -------------------- |
| 是否显示 | 在标注界面展示 |
| 是否可编辑 | 是否允许标注时修改 |
| 字段类型 | text / image / label |
| 是否为标注字段 | 标注结果字段 |
#### 特殊要求（重点）
* 用户需手动指定：
* 哪些字段是“图像字段”
* 哪些字段是“标注字段”
---
### 3.5 图像字段处理（重点）
#### 问题
JSON 中只提供相对路径，如：
```
images/xxx.jpg
```
#### 解决方案
系统需支持：
1. **配置图像根目录**
* 如：`/data/project/`
2. 拼接路径：
```
完整路径 = 根目录 + 相对路径
```
3. 后端提供图片访问接口：
```
GET /image?path=xxx
```
#### 前端显示
* 自动加载图片
* 支持：
* 缩放
* 预览（可选）
---
### 3.6 标注页面（核心）
#### 页面结构
每条数据展示：
* 字段展示区（只读）
* 标注区（可编辑字段）
* 图像展示区（如有）
#### 示例 UI
```
-------------------------
文本：这是一段文本
图片：[展示图片]
标注：
[分类标签 dropdown]
[备注 textarea]
[保存按钮]
-------------------------
```
---
### 3.7 标注流程
#### 单条标注流程
1. 展示一条数据
2. 用户填写标注字段
3. 点击“保存”
4. 自动跳转下一条
---
### 3.8 实时保存（关键需求）
#### 要求
* 每标注一条立即保存
* 防止数据丢失
#### 保存内容
每条记录需保存：
```json
{
"original_data": {...},
"annotations": {
"label": "xxx",
"remark": "xxx"
},
"annotator": "用户名",
"timestamp": "时间戳"
}
```
---
### 3.9 标注人信息
#### 功能描述
记录是谁标注的
#### 实现方式（简单版）
* 用户进入系统时输入用户名
* 后续自动带入
（可扩展登录系统）
---
### 3.10 数据存储
#### 存储方式（建议）
* JSON 文件（简单版）
或
* SQLite（推荐）
#### 数据结构
表：annotations
| 字段 | 描述 |
| ----------- | ------ |
| id | 主键 |
| data_id | 原始数据ID |
| annotations | 标注结果 |
| annotator | 标注人 |
| timestamp | 时间 |
---
### 3.11 进度管理（建议）
#### 功能
* 显示：
* 总数据量
* 已标注数量
* 当前进度 %
---
## 四、非功能需求
### 4.1 性能
* 支持至少 1万条数据加载（分页）
* 标注保存 < 200ms
### 4.2 可扩展性
* 支持后续增加：
* 多人协作
* 多任务管理
### 4.3 易用性
* 无需代码即可配置标注任务
---
## 五、系统架构建议（给 AI Agent）
### 后端（推荐）
* Python + FastAPI
模块：
* 文件上传
* JSON解析
* 图片服务
* 标注保存 API
### 前端（推荐）
* React / Vue
页面：
1. 上传页
2. 字段配置页
3. 标注页
---
## 六、接口设计（简要）
### 1. 上传文件
```
POST /upload
```
### 2. 获取字段信息
```
GET /schema
```
### 3. 保存配置
```
POST /config
```
### 4. 获取数据
```
GET /data?page=1
```
### 5. 保存标注
```
POST /annotate
```
### 6. 获取图片
```
GET /image?path=xxx
```
---
## 七、关键难点（AI Agent重点实现）
1. **JSON 自动解析（通用化）**
2. **动态表单生成（字段驱动 UI）**
3. **图像路径映射**
4. **实时保存机制**
5. **配置驱动标注系统（核心）**
---
## 八、可选增强（后续版本）
* 标注撤销 / 修改
* 多人协作冲突控制
* 标签体系管理
* 数据导出（JSON / CSV）
* 快捷键标注
* 自动预标注（AI辅助）
---
## 九、交付标准
AI Agent 生成代码需满足：
* 可运行（本地一键启动）
* 有 README
* 示例 JSON 数据
* 支持完整流程：
```
上传 → 配置 → 标注 → 保存
```
---
## 十、你可以下一步这样做
你现在可以直接对 AI Agent 说：
👉
**“请按照这个PRD，用 FastAPI + React 帮我实现第一版（MVP）代码”**
如果你愿意，我也可以帮你下一步直接做👇：
* 拆成“AI可执行任务清单”（一步步生成代码）
* 或者直接给你一版**完整可运行的初始代码骨架**
只要你说一句：**“开始写代码”** 👍
Step 2 让OpenCode帮我生成MVP版
将上面需求文档放到一个新建文件夹下的某个txt文档，让openCode根据这个需求文档，用FastAPI + React 帮我实现第一版（MVP）代码。
opencode一顿操作后，有了基本代码结构和readme，还告诉我怎么启动，按照他的启动方式，出现下面的问题，然后让opencode解决这个问题并自己验证，下面是和opencode进行的第二轮交互：
> [email protected] dev /home/huangting/Documents/codes/chat_label_sys/frontend
> vite
/home/huangting/Documents/codes/chat_label_sys/frontend/node_modules/vite/bin/vite.js:2
import { performance } from 'node:perf_hooks'
^
SyntaxError: Unexpected token {
at Module._compile (internal/modules/cjs/loader.js:723:23)
at Object.Module._extensions..js (internal/modules/cjs/loader.js:789:10)
at Module.load (internal/modules/cjs/loader.js:653:32)
at tryModuleLoad (internal/modules/cjs/loader.js:593:12)
at Function.Module._load (internal/modules/cjs/loader.js:585:3)
at Function.Module.runMain (internal/modules/cjs/loader.js:831:12)
at startup (internal/bootstrap/node.js:283:19)
at bootstrapNodeJSCore (internal/bootstrap/node.js:623:3)
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] dev: `vite`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] dev script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.
npm ERR! A complete log of this run can be found in:
npm ERR! /home/huangting/.npm/_logs/2026-04-01T11_48_46_089Z-debug.log 我按照你给我的启动方式，前端代码有报错，请你解决一下，一会最好是能自己启动验证下。之后继续交互n轮，修复了启动前端报错问题，目前前面load json文件，配置每个字段是否显示在标注系统，以及哪些路径是对应的图像路径都有了。
step3 一边使用一边提示opencode调整代码，优化展示形式
最终差不多经过3个小时左右的打磨，到了完全满足我的最初对标注系统提的要求，自己适用后也满足我的预期。以下是readme部分的说明。
# 通用标注系统
基于 FastAPI + React 的通用 Web 标注系统，支持 JSON 数据上传、字段配置、图像标注和实时保存。
## 功能特性
- **JSON 数据上传与自动解析** - 支持 JSON Array 格式，自动解析字段类型
- **字段配置** - 可配置是否显示、是否可编辑、字段类型（text/image/label）、是否为标注字段
- **图像字段支持** - 支持配置图像根目录，单图/多图列表，点击放大查看
- **实时保存** - 标注后立即保存到 SQLite 数据库
- **进度统计** - 显示总数据量、已标注数量、进度百分比
- **断点续标** - 自动从上次标注结束的位置继续
- **配置记忆** - 同一文件再次上传时保留之前的字段配置
- **标注状态绑定** - 标注结果与文件名绑定，不同文件独立管理
- **数据导出** - 一键导出已标注数据（仅导出标注过的记录）
- **长文本显示** - 支持复杂字典和列表嵌套结构，默认滚动到最后
## 项目结构
```
chat_label_sys/
├── backend/ # FastAPI 后端
│ ├── main.py # 主程序
│ ├── requirements.txt
│ ├── annotations.db # 标注数据库（自动生成）
│ └── uploads/ # 上传的 JSON 文件
├── frontend/ # React 前端
│ ├── src/
│ │ ├── App.jsx # 主组件
│ │ ├── main.jsx
│ │ └── index.css
│ └── package.json
└── README.md
```
