EISDIR: illegal operation on a directory, read '/Users/a1234/Desktop/中国人物画知识图谱/.claude/skills'

total 0
drwxr-xr-x@ 4 a1234  staff  128 Apr 19 17:51 .
drwxr-xr-x@ 4 a1234  staff  128 Apr 19 17:56 ..
drwxr-xr-x@ 7 a1234  staff  224 Apr 19 17:52 change-logger
drwxr-xr-x@ 7 a1234  staff  224 Apr 19 17:45 extraction-reviewer

1	---
2	name: extraction-reviewer
3	description: 审查中国人物画知识图谱抽取结果的数据质量。当用户要求审查、检查、验证、评估抽取数据时使用此技能。也应在用户提到以下任何情况时使用：数据完整性、准确性、健康程度、字段缺失、格式错误、CSV 问题、外键检查、数据一致性、质量控制、数据修复、字段覆盖率、枚举值错误、ID 格式问题。适用于审查 CSV、JSON 或其他格式的抽取结果，生成详细的审查报告，并自动修复可修复的问题。即使用户没有明确说"审查"，只要涉及数据质量相关的问题都应该使用此技能。
4	---
5	
6	# 抽取结果审查官
7	
8	## 目标
9	
10	根据《中国人物画知识图谱数据结构规范 v1.6》审查抽取结果，检查数据完整性、准确性、一致性，自动修复可修复问题，生成详细审查报告。
11	
12	## 核心原则
13	
14	1. **可溯源**：所有问题可追溯到具体文件、行号、字段
15	2. **可修复**：区分自动修复和人工处理
16	3. **可迭代**：支持多轮审查改进
17	4. **保留原始**：修订数据保存到新文件，不覆盖原文件
18	
19	## 工作流程
20	
21	### 第一步：读取规范
22	
23	读取规范文档：`01-元知识/中国人物画知识图谱数据结构v1_4.md`
24	
25	提取关键信息：
26	- 8个表的字段定义（必填/推荐/可选）
27	- 溯源字段要求（source_book/chapter/text/page）
28	- ID命名规范（meso_/micro_/period_/loc_等前缀）
29	- 枚举值约束（primary_role/status/support等）
30	- 外键关联关系
31	
32	### 第二步：识别审查范围
33	
34	询问用户：
35	- 单个文件：`03-初步抽取/[文献名]/[表名].csv`
36	- 整个文献目录：`03-初步抽取/[文献名]/`
37	- 多个文献：`03-初步抽取/`
38	
39	### 第三步：执行三层检查
40	
41	#### 3.1 完整性检查
42	- 必填字段是否存在且非空
43	- 推荐字段覆盖率统计
44	- 字段缺失率分析
45	
46	#### 3.2 准确性检查
47	- 书名格式：是否使用《》
48	- 章节格式：是否为"卷次·章节名"
49	- ID格式：是否有正确前缀
50	- 枚举值：是否在允许范围内

1	---
2	name: change-logger
3	description: 自动记录项目中的所有数据修订操作，生成详细的变更日志。当检测到文件修改、数据修订、CSV更新时自动触发。也应在用户提到以下情况时使用：记录修改、写入日志、变更历史、修订记录、追踪变更、审计日志。特别重要：每次使用 extraction-reviewer 修复数据后必须自动触发此技能记录变更。即使用户没有明确说"记录"，只要有文件被修改就应该使用此技能。
4	---
5	
6	# 变更日志记录器
7	
8	## 目标
9	
10	自动追踪和记录项目中的所有数据修订操作，使用 Git diff 对比变更，生成包含修改人、时间、具体变更内容的详细日志。
11	
12	## 核心原则
13	
14	1. **自动触发**：检测到文件修订后自动记录，无需用户手动触发
15	2. **字段级追踪**：记录 CSV 文件中具体哪些行、哪些字段被修改
16	3. **完整溯源**：记录修改人（Git 用户）、修改时间、修改原因
17	4. **结构化存储**：按年月组织日志，便于检索和审计
18	
19	## 工作流程
20	
21	### 第一步：检测变更
22	
23	监听以下触发条件：
24	- extraction-reviewer 生成修订数据后
25	- 用户手动修改 CSV/JSON 文件后
26	- 用户明确要求"记录这次修改"
27	
28	### 第二步：获取修改人信息
29	
30	从 Git 配置读取用户信息：
31	```bash
32	git config user.name
33	git config user.email
34	```
35	
36	如果不在 Git 仓库中，使用系统用户名。
37	
38	### 第三步：对比变更内容
39	
40	使用 `git diff` 对比文件变更：
41	```bash
42	# 对比工作区与暂存区
43	git diff <file_path>
44	
45	# 对比特定提交
46	git diff <commit1> <commit2> <file_path>
47	```
48	
49	对于 CSV 文件，解析 diff 输出提取：
50	- 修改的行号

01-元知识/中国人物画知识图谱数据结构v1_4.md

/Users/a1234/Desktop/中国人物画知识图谱/04-审查与修订/报告/审查报告_20260419_165200.md
/Users/a1234/Desktop/中国人物画知识图谱/04-审查与修订/报告/审查报告_20260419_165736.md
/Users/a1234/Desktop/中国人物画知识图谱/04-审查与修订/报告/审查报告_20260419_165338.md

# CLAUDE.md
 
本文档为 Claude Code 提供项目工作指南。
 
## 项目概述
 
**中国人物画知识图谱**：将古代画史文献转化为结构化知识图谱，采用 M3 三层框架（宏观-中观-微观）构建系统性知识表达。
 
**核心原则**：
-所有数据必须可追溯到原始文献（书名、章节、原文）
-采用混合范式：规则 + LLM + 人工抽检
-支持增量更新和质量迭代
 
## 数据结构
 
**规范文档**：[01-元知识/中国人物画知识图谱数据结构v1_4.md](01-元知识/中国人物画知识图谱数据结构v1_4.md)
 
### M3 三层框架
 
-**M1 宏观层**：时序本体、空间地理本体、图像志题材分类
-**M2 中观层**：历史人物核心表、履历与时空轨迹、社会关系实例  
-**M3 微观层**：作品实体表、文献著录与品评
 
每部文献抽取后生成 8 个 CSV 文件（M1.1-M1.3, M2.1-M2.3, M3.1-M3.2）。
 
### 溯源字段规范
 
所有表必须包含以下溯源字段：
 
| 字段 | 必填性 | 格式规范 |
|------|--------|----------|
| `source_book` | 必填 | 使用书名号《》，如《历代名画记》 |
| `source_chapter` | 强烈推荐 | 格式：卷次·章节名，如"卷一·顾野王" |
| `source_text` | 推荐 | 保留原文标点，使用""标注引文 |
| `source_page` | 可选 | 如"第12页"、"四库本卷三" |
 
### ID 命名规范
 
-**时序本体**：`period_` 前缀（如 `period_tang`）
-**空间地理**：`loc_` 前缀（如 `loc_changan`）
-**图像志**：`icon_` 前缀（如 `icon_portrait`）
-**人物**：`meso_` 前缀（如 `meso_gu_kaizhi`）
-**履历**：`cv_` 前缀（如 `cv_001`）
-**关系**：`rel_` 前缀（如 `rel_001`）
-**作品**：`micro_` 前缀（如 `micro_luoshen_fu`）
-**文献**：`lit_` 前缀（如 `lit_001`）
 
### 枚举值约束
 
**人物角色** (`primary_role`)：
-Painter, Critic, Collector, Calligrapher, Scholar, Patron, Other
 
**作品状态** (`status`)：
-Extant（存世）, Lost（佚失）, Attributed（传）, Copy（摹本）, Unknown
 
**作品材质** (`support`)：
-Silk（绢本）, Paper（纸本）, Wall（壁画）, Wood（木板）, Other, Unknown
 
**关系类型** (`relation_type`)：
-Teacher, Student, Friend, Colleague, Spouse, Parent, Child, Sibling, Other
 
详细规范见：[.claude/references/data-schema.md](.claude/references/data-schema.md)
 
## 数据处理工作流
 
\```
02-原始文档/*.txt
    ↓
文本校勘与规范化
    ↓
结构切分（卷-条-段）
    ↓
实体抽取（人物、地名、作品）
    ↓
事件识别（履历、创作、交游）
    ↓
关系构建（师承、鉴藏、著录）
    ↓
本体映射（M1/M2/M3表格）
    ↓
质量控制与推理验证
    ↓
03-初步抽取/[文献名]/*.csv
    ↓
数据审查与修订（extraction-reviewer）
    ↓
04-审查与修订/[文献名]/修订数据/*.csv
    ↓
变更日志记录（change-logger）
    ↓
04-审查与修订/变更日志/[年月]/
\```
 
## 技能系统
 
### 项目技能
 
所有项目技能存储在 `.claude/skills/` 目录：
 
#### extraction-reviewer
**用途**：数据质量审查与自动修复  
**触发**：用户提到"审查"、"检查"、"验证"、"数据质量"等关键词  
**输出**：
-审查报告（Markdown）
-问题清单（CSV）
-修订数据（CSV）
-统计数据（JSON）
 
**使用方式**：
\```bash
# 审查单个文件
/extraction-reviewer --file 03-初步抽取/古画品录/M2.1_历史人物_古画品录.csv
 
# 审查整个文献目录
/extraction-reviewer --dir 03-初步抽取/古画品录
\```
 
详细文档：[.claude/skills/extraction-reviewer/SKILL.md](.claude/skills/extraction-reviewer/SKILL.md)
 
#### change-logger
**用途**：自动记录数据修订操作  
**触发**：
-extraction-reviewer 修复数据后自动触发
-检测到 CSV/JSON 文件修改
-用户明确要求记录变更
 
**输出**：
-变更日志（Markdown）
-按年月组织：`04-审查与修订/变更日志/YYYY-MM/`
 
详细文档：[.claude/skills/change-logger/SKILL.md](.claude/skills/change-logger/SKILL.md)
 
### 技能协作流程
 
\```
用户请求审查数据
    ↓
extraction-reviewer 执行审查
    ↓
生成修订数据
    ↓
change-logger 自动触发
    ↓
记录变更日志
\```
 
## 数据质量控制
 
### 常见问题类型
 
1.**字段名错误**：
   -`source.chapter` → `source_chapter`
   -`originalsource_sentence` → `source_text`
 
2.**格式不规范**：
   -书名缺少书名号：`历代名画记` → `《历代名画记》`
   -ID 前缀错误：`work_001` → `micro_work_001`
 
3.**必填字段为空**：
   -`source_book` 为空
   -`person_id` 为空
 
4.**枚举值错误**：
   -`status: 存世` → 应为 `Extant`
   -`primary_role: 画家` → 应为 `Painter`
 
详细问题分类见：[.claude/references/quality-issues.md](.claude/references/quality-issues.md)
 
### CSV 文件处理规范
 
**编码**：所有 CSV 文件使用 UTF-8-BOM 编码
\```python
df = pd.read_csv(file_path, encoding='utf-8-sig', index_col=False)
\```
 
**索引处理**：防止第一列被误认为索引
\```python
df = pd.read_csv(file_path, encoding='utf-8-sig', index_col=False)
\```
 
**行号计算**：CSV 行号 = DataFrame 索引 + 2（表头占1行）
\```python
row_num = int(idx) + 2 if not isinstance(idx, tuple) else int(idx[0]) + 2
\```
 
详细规范见：[.claude/references/csv-handling.md](.claude/references/csv-handling.md)
 
## 文件组织
 
### 目录结构
 
\```
中国人物画知识图谱/
├── .claude/
│   ├── skills/                    # 项目技能
│   │   ├── extraction-reviewer/
│   │   └── change-logger/
│   └── references/                # 详细文档
│       ├── data-schema.md
│       ├── quality-issues.md
│       ├── csv-handling.md
│       └── examples.md
├── 01-元知识/                     # 规范文档
│   └── 中国人物画知识图谱数据结构v1_4.md
├── 02-原始文档/                   # 原始文本（10部文献）
├── 03-初步抽取/                   # 结构化数据
│   └── [文献名]/                  # 每部文献一个子目录
│       ├── M1.1_时序本体.csv
│       ├── M1.2_空间地理本体.csv
│       ├── M1.3_图像志题材分类.csv
│       ├── M2.1_历史人物核心表.csv
│       ├── M2.2_履历与时空轨迹.csv
│       ├── M2.3_社会关系实例.csv
│       ├── M3.1_作品实体表.csv
│       └── M3.2_文献著录与品评.csv
└── 04-审查与修订/                 # 质量控制输出
    ├── [文献名]/
    │   ├── 报告/
    │   ├── 修订数据/
    │   └── 统计/
    └── 变更日志/
        └── [年月]/
\```
 
### 文件命名规范
 
**CSV 文件**：
-格式：`M[层级].[序号]_[表名]_[文献名].csv`
-示例：`M2.1_历史人物核心表_古画品录.csv`
 
**修订版文件**：
-格式：`[原文件名]_修订版_[时间戳].csv`
-示例：`M2.1_历史人物核心表_修订版_20260419_165338.csv`
 
**报告文件**：
-格式：`审查报告_[时间戳].md` 或 `问题清单_[时间戳].csv`
 
## 外键关联关系
 
跨表引用必须保证完整性：
 
-`M2.2.person_ref` → `M2.1.person_id`
-`M2.3.source_id/target_id` → `M2.1.person_id`
-`M3.1.creator_ref` → `M2.1.person_id`
-`M3.1.period_ref` → `M1.1.period_id`
-`M3.1.icon_ref` → `M1.3.icon_id`
-`M3.2.target_ref` → `M3.1.work_id` 或 `M2.1.person_id`
-`M3.2.author_ref` → `M2.1.person_id`
 
详细关系图见：[.claude/references/foreign-keys.md](.claude/references/foreign-keys.md)
 
## 已处理文献
 
当前工作区已完成初步抽取的 10 部文献：
1.《历代名画记》（唐·张彦远）- 2041条记录
2.《古画品录》（南朝·谢赫）
3.《续画品》（唐·李嗣真）
4.《续画品录》（唐·李嗣真）
5.《贞观公私画史》（唐·裴孝源）
6.《唐朝名画录》（唐·朱景玄）
7.《笔法记》（唐·荆浩）
8.《后画录》（唐·朱景玄）
9.《圣朝名画评》（北宋·刘道醇）
10.《益州名画录》（北宋·黄休复）
 
## 最佳实践
 
1.**始终先读取规范文档**：确保理解字段定义和格式要求
2.**使用 extraction-reviewer 技能**：自动化质量检查
3.**保留原始数据**：修订后的数据保存到新文件，不覆盖原文件
4.**自动记录变更**：change-logger 会自动追踪所有修订操作
5.**人工复核**：自动修复后仍需人工检查严重问题
6.**增量更新**：支持对已抽取数据的迭代改进
 
## 项目状态
 
-**数据结构版本**：M3 Framework v1.6
-**已完成文献**：10部（初步抽取）
-**总记录数**：约 2041 条（仅《历代名画记》）
-**最后更新**：2026-04-19
 

<tool_use_error>File has not been read yet. Read it first before writing to it.</tool_use_error>

1	# CLAUDE.md
2	
3	This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4	
5	## 项目概述
6	
7	中国人物画知识图谱项目：将古代画史文献转化为结构化知识图谱，采用 M3 三层框架（宏观-中观-微观）构建系统性知识表达。
8	
9	**核心原则**：
10	- 所有数据必须可追溯到原始文献（书名、章节、原文）
11	- 采用混合范式：规则 + LLM + 人工抽检
12	- 支持增量更新和质量迭代
13	
14	## 技能管理规范
15	
16	**重要：所有项目相关的技能必须创建在本项目的 `.claude/skills/` 目录下。**
17	
18	**技能存储位置**：
19	- **项目级技能**（必须）：`.claude/skills/[技能名]/`
20	- **全局级技能**（可选备份）：`~/.claude/skills/[技能名]/`
21	
22	**技能创建规则**：
23	1. 所有新技能必须首先创建在项目的 `.claude/skills/` 目录
24	2. 技能必须遵循 Claude Code 标准格式（YAML frontmatter + 渐进式披露）
25	3. 技能目录结构：
26	   ```
27	   .claude/skills/[技能名]/
28	   ├── SKILL.md          # 主文档（<500 行）
29	   ├── references/       # 详细文档
30	   ├── scripts/          # 可执行脚本
31	   ├── examples/         # 示例文件
32	   └── evals/            # 测试用例
33	   ```
34	4. 禁止在项目根目录或其他位置创建技能目录（如 `05-技能库/` 等）
35	
36	**现有技能**：
37	- `extraction-reviewer`：数据质量审查技能
38	- `change-logger`：变更日志记录技能
39	
40	## 数据结构规范
41	
42	**规范文档位置**：`01-元知识/中国人物画知识图谱数据结构v1_4.md`
43	
44	### M3 三层框架
45	
46	- **M1 宏观层**：时序本体、空间地理本体、图像志题材分类
47	- **M2 中观层**：历史人物核心表、履历与时空轨迹、社会关系实例  
48	- **M3 微观层**：作品实体表、文献著录与品评
49	
50	每部文献抽取后生成 8 个 CSV 文件（M1.1-M1.3, M2.1-M2.3, M3.1-M3.2）。
51	
52	### 溯源字段规范（所有表必须遵守）
53	
54	| 字段 | 必填性 | 格式规范 |
55	|------|--------|----------|
56	| `source_book` | 必填 | 使用书名号《》，如《历代名画记》 |
57	| `source_chapter` | 强烈推荐 | 格式：卷次·章节名，如"卷一·顾野王" |
58	| `source_text` | 推荐 | 保留原文标点，使用""标注引文 |
59	| `source_page` | 可选 | 如"第12页"、"四库本卷三" |
60	
61	### ID 命名规范
62	
63	- **时序本体**：`period_` 前缀（如 `period_tang`）
64	- **空间地理**：`loc_` 前缀（如 `loc_changan`）
65	- **图像志**：`icon_` 前缀（如 `icon_portrait`）
66	- **人物**：`meso_` 前缀（如 `meso_gu_kaizhi`）
67	- **履历**：`cv_` 前缀（如 `cv_001`）
68	- **关系**：`rel_` 前缀（如 `rel_001`）
69	- **作品**：`micro_` 前缀（如 `micro_luoshen_fu`）
70	- **文献**：`lit_` 前缀（如 `lit_001`）
71	
72	### 枚举值约束
73	
74	**人物角色** (`primary_role`)：
75	- Painter, Critic, Collector, Calligrapher, Scholar, Patron, Other
76	
77	**作品状态** (`status`)：
78	- Extant（存世）, Lost（佚失）, Attributed（传）, Copy（摹本）, Unknown
79	
80	**作品材质** (`support`)：
81	- Silk（绢本）, Paper（纸本）, Wall（壁画）, Wood（木板）, Other, Unknown
82	
83	**关系类型** (`relation_type`)：
84	- Teacher, Student, Friend, Colleague, Spouse, Parent, Child, Sibling, Other
85	
86	## 数据处理工作流
87	
88	```
89	02-原始文档/*.txt
90	    ↓
91	文本校勘与规范化
92	    ↓
93	结构切分（卷-条-段）
94	    ↓
95	实体抽取（人物、地名、作品）
96	    ↓
97	事件识别（履历、创作、交游）
98	    ↓
99	关系构建（师承、鉴藏、著录）
100	    ↓
101	本体映射（M1/M2/M3表格）
102	    ↓
103	质量控制与推理验证
104	    ↓
105	03-初步抽取/[文献名]/*.csv
106	    ↓
107	数据审查与修订
108	    ↓
109	04-审查与修订/[文献名]/修订数据/*.csv
110	```
111	
112	## 数据质量审查
113	
114	### 使用 extraction-reviewer 技能
115	
116	**技能位置**：
117	- 项目级：`.claude/skills/extraction-reviewer/`（推荐）
118	- 全局级：`~/.claude/skills/extraction-reviewer/`
119	
120	**触发方式**：
121	- 用户要求"审查"、"检查"、"验证"抽取数据
122	- 提到数据完整性、准确性、健康程度
123	- 提到字段缺失、格式错误、外键检查等数据质量问题
124	
125	**审查脚本**：
126	```bash
127	# 审查单个文件
128	python .claude/skills/extraction-reviewer/scripts/reviewer.py \
129	  --file 03-初步抽取/[文献名]/[表名].csv \
130	  --output-dir 04-审查与修订/[文献名]
131	
132	# 审查整个目录
133	python .claude/skills/extraction-reviewer/scripts/reviewer.py \
134	  --dir 03-初步抽取/[文献名] \
135	  --output-dir 04-审查与修订/[文献名]
136	```
137	
138	**输出结构**：
139	```
140	04-审查与修订/
141	└── [文献名]/
142	    ├── 报告/
143	    │   ├── 审查报告_[时间戳].md          # 人类可读报告
144	    │   └── 问题清单_[时间戳].csv         # 可筛选问题列表
145	    ├── 修订数据/
146	    │   └── [原文件名]_修订版_[时间戳].csv  # 自动修复后的数据
147	    └── 统计/
148	        └── 统计数据_[时间戳].json        # 质量统计
149	```
150	
151	## 变更日志记录
152	
153	### 使用 change-logger 技能
154	
155	**技能位置**：
156	- 项目级：`.claude/skills/change-logger/`（推荐）
157	- 全局级：`~/.claude/skills/change-logger/`
158	
159	**触发方式**：
160	- 自动触发：每次使用 extraction-reviewer 修复数据后自动记录
161	- 手动触发：用户要求"记录修改"、"写入日志"、"记录变更"
162	- 检测到文件修改、数据修订、CSV 更新时
163	
164	**日志脚本**：
165	```bash
166	# 手动记录变更
167	python .claude/skills/change-logger/scripts/logger.py \
168	  --files 04-审查与修订/[文献名]/修订数据/[文件名].csv \
169	  --reason "修改原因说明" \
170	  --original-file 03-初步抽取/[文献名]/[原文件名].csv \
171	  --report-file 04-审查与修订/[文献名]/报告/审查报告_[时间戳].md
172	```
173	
174	**输出结构**：
175	```
176	99-日志文档/
177	└── [年月]/
178	    └── 变更日志_[日期].md
179	```
180	
181	**日志内容**：
182	- 修改人（Git 用户名 + 邮箱）
183	- 修改时间（精确到秒）
184	- 修改类型（自动修复 / 手动修订）
185	- 影响范围（文件路径、修改行数、字段数）
186	- 修改内容详情（字段级对比，使用 git diff）
187	- 修改原因
188	- 相关文件（审查报告、问题清单、Git commit）
189	
190	**与 extraction-reviewer 集成**：
191	- extraction-reviewer 完成数据修订后自动调用 change-logger
192	- 变更日志路径会写入审查报告
193	- 支持追溯每次修订的完整历史
194	
195	### 常见数据质量问题
196	
197	1. **字段名错误**：
198	   - `source.chapter` → `source_chapter`
199	   - `originalsource_sentence` → `source_text`
200	
201	2. **格式不规范**：
202	   - 书名缺少书名号：`历代名画记` → `《历代名画记》`
203	   - ID 前缀错误：`work_001` → `micro_work_001`
204	
205	3. **必填字段为空**：
206	   - `source_book` 为空
207	   - `person_id` 为空
208	
209	4. **枚举值错误**：
210	   - `status: 存世` → 应为 `Extant`
211	   - `primary_role: 画家` → 应为 `Painter`
212	
213	### CSV 文件处理注意事项
214	
215	**编码**：所有 CSV 文件使用 UTF-8-BOM 编码
216	```python
217	df = pd.read_csv(file_path, encoding='utf-8-sig', index_col=False)
218	```
219	
220	**索引处理**：防止第一列被误认为索引
221	```python
222	# 始终使用 index_col=False
223	df = pd.read_csv(file_path, encoding='utf-8-sig', index_col=False)
224	```
225	
226	**行号计算**：CSV 行号 = DataFrame 索引 + 2（表头占1行）
227	```python
228	if isinstance(idx, tuple):
229	    row_num = int(idx[0]) + 2  # 多级索引
230	else:
231	    row_num = int(idx) + 2      # 单级索引
232	```
233	
234	## 技能体系
235	
236	### 元技能层（01-元知识/shiji-skills/00-META-*.md）
237	
238	从史记项目迁移的通用方法论技能：
239	- 反思闭环、迭代工作流、冷启动方法
240	- 柳叶刀方法（问题分层拆解）
241	- 知识压缩、标注体系设计
242	- 质量控制、数据融合、Agent提示词工程
243	
244	### 管线技能层（01-元知识/shiji-skills/SKILL_*.md）
245	
246	10 个阶段的数据处理技能：
247	- SKILL_00：管线总览
248	- SKILL_01：古籍校勘（统一书名、卷次、标点、异体字）
249	- SKILL_02：结构分析（卷-条-段切分）
250	- SKILL_03：实体构建（人物、地名、题材识别）
251	- SKILL_04：事件构建（生平轨迹提取）
252	- SKILL_05：关系构建（人物关系、作品关系）
253	- SKILL_06：本体构造（映射到 M1/M2/M3）
254	- SKILL_07：逻辑推理（断代推断、消歧）
255	- SKILL_08：知识库管驭（质量量化）
256	- SKILL_09：应用构造（检索、可视化）
257	
258	**技能索引**：`01-元知识/shiji-skills/INDEX.md`
259	
260	## 文件组织规范
261	
262	### 目录结构
263	
264	```
265	中国人物画知识图谱/
266	├── 01-元知识/                    # 规范与技能
267	│   ├── shiji-skills/             # 技能库（104个文件）
268	│   └── 中国人物画知识图谱数据结构v1_4.md
269	├── 02-原始文档/                  # 原始文本（10部文献）
270	├── 03-初步抽取/                  # 结构化数据
271	│   └── [文献名]/                 # 每部文献一个子目录
272	│       ├── M1.1_时序本体.csv
273	│       ├── M1.2_空间地理本体.csv
274	│       ├── M1.3_图像志题材分类.csv
275	│       ├── M2.1_历史人物核心表.csv
276	│       ├── M2.2_履历与时空轨迹.csv
277	│       ├── M2.3_社会关系实例.csv
278	│       ├── M3.1_作品实体表.csv
279	│       └── M3.2_文献著录与品评.csv
280	└── 04-审查与修订/                # 质量控制输出
281	    └── [文献名]/
282	        ├── 报告/
283	        ├── 修订数据/
284	        └── 统计/
285	└── 99-日志文档/                  # 变更日志
286	    └── [年月]/
287	        └── 变更日志_[日期].md
288	```
289	
290	### 文件命名规范
291	
292	**CSV 文件**：
293	- 格式：`M[层级].[序号]_[表名]_[文献名].csv` 或 `M[层级].[序号]_[表名]（[文献名]）.csv`
294	- 示例：`M2.1_历史人物核心表_古画品录.csv`
295	
296	**修订版文件**：
297	- 格式：`[原文件名]_修订版_[时间戳].csv`
298	- 示例：`M2.1_历史人物核心表_修订版_20260419_165338.csv`
299	
300	**报告文件**：
301	- 格式：`审查报告_[时间戳].md` 或 `问题清单_[时间戳].csv`
302	
303	## 已处理文献
304	
305	当前工作区已完成初步抽取的 10 部文献：
306	1. 《历代名画记》（唐·张彦远）- 2041条记录
307	2. 《古画品录》（南朝·谢赫）
308	3. 《续画品》（唐·李嗣真）
309	4. 《续画品录》（唐·李嗣真）
310	5. 《贞观公私画史》（唐·裴孝源）
311	6. 《唐朝名画录》（唐·朱景玄）
312	7. 《笔法记》（唐·荆浩）
313	8. 《后画录》（唐·朱景玄）
314	9. 《圣朝名画评》（北宋·刘道醇）
315	10. 《益州名画录》（北宋·黄休复）
316	
317	## 外键关联关系
318	
319	跨表引用必须保证完整性：
320	
321	- `M2.2_履历与时空轨迹.person_ref` → `M2.1_历史人物核心表.person_id`
322	- `M2.3_社会关系实例.source_id/target_id` → `M2.1_历史人物核心表.person_id`
323	- `M3.1_作品实体表.creator_ref` → `M2.1_历史人物核心表.person_id`
324	- `M3.1_作品实体表.period_ref` → `M1.1_时序本体.period_id`
325	- `M3.1_作品实体表.icon_ref` → `M1.3_图像志题材分类.icon_id`
326	- `M3.2_文献著录与品评.target_ref` → `M3.1_作品实体表.work_id` 或 `M2.1_历史人物核心表.person_id`
327	- `M3.2_文献著录与品评.author_ref` → `M2.1_历史人物核心表.person_id`
328	
329	## 数据处理最佳实践
330	
331	1. **始终先读取规范文档**：确保理解字段定义和格式要求
332	2. **使用 extraction-reviewer 技能**：自动化质量检查
333	3. **保留原始数据**：修订后的数据保存到新文件，不覆盖原文件
334	4. **自动记录变更**：使用 change-logger 记录所有修订操作
335	5. **人工复核**：自动修复后仍需人工检查严重问题
336	6. **增量更新**：支持对已抽取数据的迭代改进
337	
338	## 常用命令
339	
340	### 数据审查
341	```bash
342	# 审查单个文件
343	python .claude/skills/extraction-reviewer/scripts/reviewer.py \
344	  --file 03-初步抽取/古画品录/M2.1_历史人物_古画品录.csv \
345	  --output-dir 04-审查与修订/古画品录
346	
347	# 审查整个文献目录
348	python .claude/skills/extraction-reviewer/scripts/reviewer.py \
349	  --dir 03-初步抽取/古画品录 \
350	  --output-dir 04-审查与修订/古画品录
351	```
352	
353	### 变更日志
354	```bash
355	# 手动记录变更
356	python .claude/skills/change-logger/scripts/logger.py \
357	  --files 04-审查与修订/古画品录/修订数据/M2.1_历史人物_修订版.csv \
358	  --reason "手动修正人物生卒年份" \
359	  --original-file 03-初步抽取/古画品录/M2.1_历史人物.csv
360	
361	# 查看今天的变更日志
362	cat 99-日志文档/$(date +%Y-%m)/变更日志_$(date +%Y-%m-%d).md
363	```
364	
365	### 查看数据统计
366	```bash
367	# 统计某部文献的记录数
368	wc -l 03-初步抽取/历代名画记/*.csv
369	
370	# 查看字段覆盖率
371	head -1 03-初步抽取/历代名画记/M2.1_历史人物核心表.csv
372	```
373	
374	### 检查数据格式
375	```bash
376	# 检查编码
377	file -I 03-初步抽取/古画品录/*.csv
378	
379	# 检查书名号格式
380	grep -n "source_book" 03-初步抽取/古画品录/M2.1_历史人物_古画品录.csv | head -5
381	```
382	
383	## 项目状态
384	
385	- **数据结构版本**：M3 Framework v1.6
386	- **已完成文献**：10部（初步抽取）
387	- **总记录数**：约 2041 条（仅《历代名画记》）
388	- **最后更新**：2026-04-19
389

The file /Users/a1234/Desktop/中国人物画知识图谱/CLAUDE.md has been updated successfully.

The file /Users/a1234/Desktop/中国人物画知识图谱/CLAUDE.md has been updated successfully.

<tool_use_error>String to replace not found in file.
String: ## 数据处理工作流
 

 
## 数据质量审查
 
### 使用 extraction-reviewer 技能
 
**技能位置**：
- 项目级：`.claude/skills/extraction-reviewer/`（推荐）
- 全局级：`~/.claude/skills/extraction-reviewer/`
 
**触发方式**：
- 用户要求"审查"、"检查"、"验证"抽取数据
- 提到数据完整性、准确性、健康程度
- 提到字段缺失、格式错误、外键检查等数据质量问题
 
**审查脚本**：

 
**输出结构**：

 
## 变更日志记录
 
### 使用 change-logger 技能
 
**技能位置**：
- 项目级：`.claude/skills/change-logger/`（推荐）
- 全局级：`~/.claude/skills/change-logger/`
 
**触发方式**：
- 自动触发：每次使用 extraction-reviewer 修复数据后自动记录
- 手动触发：用户要求"记录修改"、"写入日志"、"记录变更"
- 检测到文件修改、数据修订、CSV 更新时
 
**日志脚本**：

 
**输出结构**：

 
### 常见数据质量问题
 
1. **字段名错误**：
   - `source.chapter` → `source_chapter`
   - `originalsource_sentence` → `source_text`
 
2. **格式不规范**：
   - 书名缺少书名号：`历代名画记` → `《历代名画记》`
   - ID 前缀错误：`work_001` → `micro_work_001`
 
3. **必填字段为空**：
   - `source_book` 为空
   - `person_id` 为空
 
4. **枚举值错误**：
   - `status: 存世` → 应为 `Extant`
   - `primary_role: 画家` → 应为 `Painter`
 
### CSV 文件处理注意事项
 
**编码**：所有 CSV 文件使用 UTF-8-BOM 编码

 
**索引处理**：防止第一列被误认为索引

 
**行号计算**：CSV 行号 = DataFrame 索引 + 2（表头占1行）

85	    ↓
86	事件识别（履历、创作、交游）
87	    ↓
88	关系构建（师承、鉴藏、著录）
89	    ↓
90	本体映射（M1/M2/M3表格）
91	    ↓
92	质量控制与推理验证
93	    ↓
94	03-初步抽取/[文献名]/*.csv
95	    ↓
96	数据审查与修订
97	    ↓
98	04-审查与修订/[文献名]/修订数据/*.csv
99	```
100	
101	## 数据质量审查
102	
103	### 使用 extraction-reviewer 技能
104	
105	**技能位置**：
106	- 项目级：`.claude/skills/extraction-reviewer/`（推荐）
107	- 全局级：`~/.claude/skills/extraction-reviewer/`
108	
109	**触发方式**：
110	- 用户要求"审查"、"检查"、"验证"抽取数据
111	- 提到数据完整性、准确性、健康程度
112	- 提到字段缺失、格式错误、外键检查等数据质量问题
113	
114	**审查脚本**：
115	```bash
116	# 审查单个文件
117	python .claude/skills/extraction-reviewer/scripts/reviewer.py \
118	  --file 03-初步抽取/[文献名]/[表名].csv \
119	  --output-dir 04-审查与修订/[文献名]
120	
121	# 审查整个目录
122	python .claude/skills/extraction-reviewer/scripts/reviewer.py \
123	  --dir 03-初步抽取/[文献名] \
124	  --output-dir 04-审查与修订/[文献名]
125	```
126	
127	**输出结构**：
128	```
129	04-审查与修订/
130	└── [文献名]/
131	    ├── 报告/
132	    │   ├── 审查报告_[时间戳].md          # 人类可读报告
133	    │   └── 问题清单_[时间戳].csv         # 可筛选问题列表
134	    ├── 修订数据/
135	    │   └── [原文件名]_修订版_[时间戳].csv  # 自动修复后的数据
136	    └── 统计/
137	        └── 统计数据_[时间戳].json        # 质量统计
138	```
139	
140	## 变更日志记录
141	
142	### 使用 change-logger 技能
143	
144	**技能位置**：
145	- 项目级：`.claude/skills/change-logger/`（推荐）
146	- 全局级：`~/.claude/skills/change-logger/`
147	
148	**触发方式**：
149	- 自动触发：每次使用 extraction-reviewer 修复数据后自动记录
150	- 手动触发：用户要求"记录修改"、"写入日志"、"记录变更"
151	- 检测到文件修改、数据修订、CSV 更新时
152	
153	**日志脚本**：
154	```bash
155	# 手动记录变更
156	python .claude/skills/change-logger/scripts/logger.py \
157	  --files 04-审查与修订/[文献名]/修订数据/[文件名].csv \
158	  --reason "修改原因说明" \
159	  --original-file 03-初步抽取/[文献名]/[原文件名].csv \
160	  --report-file 04-审查与修订/[文献名]/报告/审查报告_[时间戳].md
161	```
162	
163	**输出结构**：
164	```
165	99-日志文档/
166	└── [年月]/
167	    └── 变更日志_[日期].md
168	```
169	
170	**日志内容**：
171	- 修改人（Git 用户名 + 邮箱）
172	- 修改时间（精确到秒）
173	- 修改类型（自动修复 / 手动修订）
174	- 影响范围（文件路径、修改行数、字段数）
175	- 修改内容详情（字段级对比，使用 git diff）
176	- 修改原因
177	- 相关文件（审查报告、问题清单、Git commit）
178	
179	**与 extraction-reviewer 集成**：
180	- extraction-reviewer 完成数据修订后自动调用 change-logger
181	- 变更日志路径会写入审查报告
182	- 支持追溯每次修订的完整历史
183	
184	### 常见数据质量问题
185	
186	1. **字段名错误**：
187	   - `source.chapter` → `source_chapter`
188	   - `originalsource_sentence` → `source_text`
189	
190	2. **格式不规范**：
191	   - 书名缺少书名号：`历代名画记` → `《历代名画记》`
192	   - ID 前缀错误：`work_001` → `micro_work_001`
193	
194	3. **必填字段为空**：
195	   - `source_book` 为空
196	   - `person_id` 为空
197	
198	4. **枚举值错误**：
199	   - `status: 存世` → 应为 `Extant`
200	   - `primary_role: 画家` → 应为 `Painter`
201	
202	### CSV 文件处理注意事项
203	
204	**编码**：所有 CSV 文件使用 UTF-8-BOM 编码
205	```python
206	df = pd.read_csv(file_path, encoding='utf-8-sig', index_col=False)
207	```
208	
209	**索引处理**：防止第一列被误认为索引
210	```python
211	# 始终使用 index_col=False
212	df = pd.read_csv(file_path, encoding='utf-8-sig', index_col=False)
213	```
214	
215	**行号计算**：CSV 行号 = DataFrame 索引 + 2（表头占1行）
216	```python
217	if isinstance(idx, tuple):
218	    row_num = int(idx[0]) + 2  # 多级索引
219	else:
220	    row_num = int(idx) + 2      # 单级索引
221	```
222	
223	## 技能体系
224	
225	### 元技能层（01-元知识/shiji-skills/00-META-*.md）
226	
227	从史记项目迁移的通用方法论技能：
228	- 反思闭环、迭代工作流、冷启动方法
229	- 柳叶刀方法（问题分层拆解）
230	- 知识压缩、标注体系设计
231	- 质量控制、数据融合、Agent提示词工程
232	
233	### 管线技能层（01-元知识/shiji-skills/SKILL_*.md）
234

     377 /Users/a1234/Desktop/中国人物画知识图谱/CLAUDE.md

# CLAUDE.md
 
本文档为 Claude Code 提供项目工作指南。
 
## 项目概述
 
**中国人物画知识图谱**：将古代画史文献转化为结构化知识图谱，采用 M3 三层框架（宏观-中观-微观）构建系统性知识表达。
 
**核心原则**：
-所有数据必须可追溯到原始文献（书名、章节、原文）
-采用混合范式：规则 + LLM + 人工抽检
-支持增量更新和质量迭代
 
## 技能系统
 
项目技能存储在 `.claude/skills/` 目录，遵循渐进式披露原则（主文档 <300 行）。
 
### extraction-reviewer
**用途**：数据质量审查与自动修复  
**触发**：用户提到"审查"、"检查"、"验证"、"数据质量"等关键词  
**输出**：审查报告、问题清单、修订数据、统计数据
 
详细文档：[.claude/skills/extraction-reviewer/SKILL.md](.claude/skills/extraction-reviewer/SKILL.md)
 
### change-logger
**用途**：自动记录数据修订操作  
**触发**：extraction-reviewer 修复数据后自动触发，或检测到文件修改  
**输出**：变更日志（按年月组织）
 
详细文档：[.claude/skills/change-logger/SKILL.md](.claude/skills/change-logger/SKILL.md)
 
### 技能协作流程
 
\```
用户请求审查数据
    ↓
extraction-reviewer 执行审查
    ↓
生成修订数据
    ↓
change-logger 自动触发
    ↓
记录变更日志
\```
 
## 数据结构
 
**规范文档**：[01-元知识/中国人物画知识图谱数据结构v1_4.md](01-元知识/中国人物画知识图谱数据结构v1_4.md)
 
### M3 三层框架
 
-**M1 宏观层**：时序本体、空间地理本体、图像志题材分类
-**M2 中观层**：历史人物核心表、履历与时空轨迹、社会关系实例  
-**M3 微观层**：作品实体表、文献著录与品评
 
每部文献抽取后生成 8 个 CSV 文件（M1.1-M1.3, M2.1-M2.3, M3.1-M3.2）。
 
### 核心规范速查
 
**溯源字段**（所有表必填）：
-`source_book`：《书名》格式
-`source_chapter`：卷次·章节名
-`source_text`：原文引用
 
**ID 前缀**：
-人物 `meso_`、作品 `micro_`、时序 `period_`、地理 `loc_`、图像志 `icon_`
 
**枚举值**：
-角色：Painter, Critic, Collector, Calligrapher, Scholar, Patron, Other
-状态：Extant, Lost, Attributed, Copy, Unknown
-材质：Silk, Paper, Wall, Wood, Other, Unknown
 
详细规范见：[.claude/references/data-schema.md](.claude/references/data-schema.md)
 
## 数据处理工作流
 
\```
02-原始文档/*.txt
    ↓
文本校勘与规范化
    ↓
结构切分（卷-条-段）
    ↓
实体抽取（人物、地名、作品）
    ↓
事件识别（履历、创作、交游）
    ↓
关系构建（师承、鉴藏、著录）
    ↓
本体映射（M1/M2/M3表格）
    ↓
质量控制与推理验证
    ↓
03-初步抽取/[文献名]/*.csv
    ↓
数据审查与修订（extraction-reviewer）
    ↓
04-审查与修订/[文献名]/修订数据/*.csv
    ↓
变更日志记录（change-logger）
    ↓
04-审查与修订/变更日志/[年月]/
\```
 
## 数据质量控制
 
### 常见问题类型
 
1.**字段名错误**：`source.chapter` → `source_chapter`
2.**格式不规范**：缺少书名号、ID 前缀错误
3.**必填字段为空**：`source_book`、`person_id` 等
4.**枚举值错误**：中文值 → 英文标准值
 
详细问题分类见：[.claude/references/quality-issues.md](.claude/references/quality-issues.md)
 
### CSV 处理规范
 
-**编码**：UTF-8-BOM
-**索引**：始终使用 `index_col=False`
-**行号**：CSV 行号 = DataFrame 索引 + 2
 
详细规范见：[.claude/references/csv-handling.md](.claude/references/csv-handling.md)
 
## 文件组织
 
### 目录结构
 
\```
中国人物画知识图谱/
├── .claude/
│   ├── skills/                    # 项目技能
│   │   ├── extraction-reviewer/
│   │   └── change-logger/
│   └── references/                # 详细文档
│       ├── data-schema.md
│       ├── quality-issues.md
│       ├── csv-handling.md
│       ├── foreign-keys.md
│       └── examples.md
├── 01-元知识/                     # 规范文档
│   └── 中国人物画知识图谱数据结构v1_4.md
├── 02-原始文档/                   # 原始文本（10部文献）
├── 03-初步抽取/                   # 结构化数据
│   └── [文献名]/                  # 每部文献一个子目录
│       ├── M1.1_时序本体.csv
│       ├── M1.2_空间地理本体.csv
│       ├── M1.3_图像志题材分类.csv
│       ├── M2.1_历史人物核心表.csv
│       ├── M2.2_履历与时空轨迹.csv
│       ├── M2.3_社会关系实例.csv
│       ├── M3.1_作品实体表.csv
│       └── M3.2_文献著录与品评.csv
└── 04-审查与修订/                 # 质量控制输出
    ├── [文献名]/
    │   ├── 报告/
    │   ├── 修订数据/
    │   └── 统计/
    └── 变更日志/
        └── [年月]/
\```
 
### 文件命名规范
 
**CSV 文件**：
-格式：`M[层级].[序号]_[表名]_[文献名].csv`
-示例：`M2.1_历史人物核心表_古画品录.csv`
 
**修订版文件**：
-格式：`[原文件名]_修订版_[时间戳].csv`
-示例：`M2.1_历史人物核心表_修订版_20260419_165338.csv`
 
## 外键关联关系
 
跨表引用必须保证完整性：
 
-`M2.2.person_ref` → `M2.1.person_id`
-`M2.3.source_id/target_id` → `M2.1.person_id`
-`M3.1.creator_ref` → `M2.1.person_id`
-`M3.1.period_ref` → `M1.1.period_id`
-`M3.1.icon_ref` → `M1.3.icon_id`
-`M3.2.target_ref` → `M3.1.work_id` 或 `M2.1.person_id`
-`M3.2.author_ref` → `M2.1.person_id`
 
详细关系图见：[.claude/references/foreign-keys.md](.claude/references/foreign-keys.md)
 
## 已处理文献
 
当前工作区已完成初步抽取的 10 部文献：
1.《历代名画记》（唐·张彦远）- 2041条记录
2.《古画品录》（南朝·谢赫）
3.《续画品》（唐·李嗣真）
4.《续画品录》（唐·李嗣真）
5.《贞观公私画史》（唐·裴孝源）
6.《唐朝名画录》（唐·朱景玄）
7.《笔法记》（唐·荆浩）
8.《后画录》（唐·朱景玄）
9.《圣朝名画评》（北宋·刘道醇）
10.《益州名画录》（北宋·黄休复）
 
## 最佳实践
 
1.**始终先读取规范文档**：确保理解字段定义和格式要求
2.**使用 extraction-reviewer 技能**：自动化质量检查
3.**保留原始数据**：修订后的数据保存到新文件，不覆盖原文件
4.**自动记录变更**：change-logger 会自动追踪所有修订操作
5.**人工复核**：自动修复后仍需人工检查严重问题
6.**增量更新**：支持对已抽取数据的迭代改进
 
## 常用命令速查
 
\```bash
# 审查单个文件
/extraction-reviewer --file 03-初步抽取/古画品录/M2.1_历史人物_古画品录.csv
 
# 审查整个文献目录
/extraction-reviewer --dir 03-初步抽取/古画品录
 
# 统计记录数
wc -l 03-初步抽取/历代名画记/*.csv
 
# 检查编码
file -I 03-初步抽取/古画品录/*.csv
\```
 
详细命令参考见：[.claude/references/examples.md](.claude/references/examples.md)
 
## 项目状态
 
-**数据结构版本**：M3 Framework v1.6
-**已完成文献**：10部（初步抽取）
-**总记录数**：约 2041 条（仅《历代名画记》）
-**最后更新**：2026-04-19
 

File created successfully at: /Users/a1234/Desktop/中国人物画知识图谱/CLAUDE_NEW.md

     232 /Users/a1234/Desktop/中国人物画知识图谱/CLAUDE_NEW.md

(Bash completed with no output)

# 数据结构详细规范
 
本文档提供中国人物画知识图谱数据结构的详细说明。
 
**主规范文档**：[01-元知识/中国人物画知识图谱数据结构v1_4.md](../../01-元知识/中国人物画知识图谱数据结构v1_4.md)
 
## 溯源字段详细规范
 
所有表必须包含以下溯源字段：
 
| 字段 | 必填性 | 格式规范 | 示例 |
|------|--------|----------|------|
| `source_book` | 必填 | 使用书名号《》 | 《历代名画记》 |
| `source_chapter` | 强烈推荐 | 格式：卷次·章节名 | "卷一·顾野王" |
| `source_text` | 推荐 | 保留原文标点，使用""标注引文 | "顾野王，吴郡人，善画" |
| `source_page` | 可选 | 页码或版本信息 | "第12页"、"四库本卷三" |
 
## ID 命名规范详细说明
 
### 时序本体 (M1.1)
-**前缀**：`period_`
-**格式**：`period_[朝代/时期]`
-**示例**：
  -`period_tang`：唐代
  -`period_song_north`：北宋
  -`period_five_dynasties`：五代
 
### 空间地理本体 (M1.2)
-**前缀**：`loc_`
-**格式**：`loc_[地名拼音]`
-**示例**：
  -`loc_changan`：长安
  -`loc_luoyang`：洛阳
  -`loc_jiankang`：建康
 
### 图像志题材分类 (M1.3)
-**前缀**：`icon_`
-**格式**：`icon_[题材类型]`
-**示例**：
  -`icon_portrait`：人物画
  -`icon_landscape`：山水画
  -`icon_flower_bird`：花鸟画
 
### 历史人物 (M2.1)
-**前缀**：`meso_`
-**格式**：`meso_[姓名拼音]`
-**示例**：
  -`meso_gu_kaizhi`：顾恺之
  -`meso_wu_daozi`：吴道子
  -`meso_zhang_sengyou`：张僧繇
 
### 履历与时空轨迹 (M2.2)
-**前缀**：`cv_`
-**格式**：`cv_[序号]`
-**示例**：
  -`cv_001`
  -`cv_002`
 
### 社会关系实例 (M2.3)
-**前缀**：`rel_`
-**格式**：`rel_[序号]`
-**示例**：
  -`rel_001`
  -`rel_002`
 
### 作品实体 (M3.1)
-**前缀**：`micro_`
-**格式**：`micro_[作品名拼音]`
-**示例**：
  -`micro_luoshen_fu`：洛神赋图
  -`micro_nushi_zhen`：女史箴图
  -`micro_tianwang_song_zi`：天王送子图
 
### 文献著录 (M3.2)
-**前缀**：`lit_`
-**格式**：`lit_[序号]`
-**示例**：
  -`lit_001`
  -`lit_002`
 
## 枚举值详细约束
 
### 人物角色 (primary_role)
 
| 英文值 | 中文含义 | 说明 |
|--------|----------|------|
| Painter | 画家 | 主要从事绘画创作 |
| Critic | 评论家 | 主要从事画论、品评 |
| Collector | 收藏家 | 主要从事书画收藏 |
| Calligrapher | 书法家 | 主要从事书法创作 |
| Scholar | 文人学者 | 文人、学者身份 |
| Patron | 赞助人 | 皇室、贵族赞助人 |
| Other | 其他 | 其他角色 |
 
### 作品状态 (status)
 
| 英文值 | 中文含义 | 说明 |
|--------|----------|------|
| Extant | 存世 | 作品现存可见 |
| Lost | 佚失 | 作品已失传 |
| Attributed | 传 | 传为某人所作，真伪存疑 |
| Copy | 摹本 | 后人摹写的副本 |
| Unknown | 未知 | 状态不明 |
 
### 作品材质 (support)
 
| 英文值 | 中文含义 | 说明 |
|--------|----------|------|
| Silk | 绢本 | 绢帛材质 |
| Paper | 纸本 | 纸张材质 |
| Wall | 壁画 | 墙壁绘画 |
| Wood | 木板 | 木板材质 |
| Other | 其他 | 其他材质 |
| Unknown | 未知 | 材质不明 |
 
### 关系类型 (relation_type)
 
| 英文值 | 中文含义 | 说明 |
|--------|----------|------|
| Teacher | 师 | 师徒关系（师） |
| Student | 徒 | 师徒关系（徒） |
| Friend | 友 | 朋友关系 |
| Colleague | 同僚 | 同事、同僚 |
| Spouse | 配偶 | 夫妻关系 |
| Parent | 父母 | 父母关系 |
| Child | 子女 | 子女关系 |
| Sibling | 兄弟姐妹 | 兄弟姐妹关系 |
| Other | 其他 | 其他关系 |
 
## 字段类型说明
 
### 文本字段
-**短文本**：人名、地名、作品名等（<100字符）
-**中文本**：章节名、简短描述（100-500字符）
-**长文本**：原文引用、详细描述（>500字符）
 
### 数值字段
-**年份**：YYYY 格式，如 618、907
-**年份范围**：YYYY-YYYY 格式，如 618-907
-**序号**：整数，从 1 开始
 
### 布尔字段
-**格式**：TRUE/FALSE 或 1/0
-**用途**：标记字段，如 is_verified
 
### 日期字段
-**格式**：YYYY-MM-DD
-**用途**：精确日期记录
 
## 字段命名规范
 
### 通用规则
-使用小写字母和下划线
-避免使用缩写（除非是通用缩写）
-使用描述性名称
 
### 常见字段后缀
-`_id`：主键标识符
-`_ref`：外键引用
-`_name`：名称字段
-`_text`：文本内容
-`_date`：日期字段
-`_year`：年份字段
-`_type`：类型字段
 
### 溯源字段前缀
-`source_`：所有溯源相关字段统一使用此前缀
 
## 表间关系说明
 
### 一对多关系
-一个人物 → 多条履历记录
-一个人物 → 多个作品
-一部文献 → 多条著录记录
 
### 多对多关系
-人物 ↔ 人物（社会关系）
-作品 ↔ 文献（著录关系）
 
### 层级关系
-M1（宏观）→ M2（中观）→ M3（微观）
-时序本体 → 人物 → 作品
-空间本体 → 人物 → 履历
 
## 数据完整性约束
 
### 必填字段约束
-所有表必须有 `source_book` 字段
-所有实体表必须有主键 ID
-所有关系表必须有外键引用
 
### 唯一性约束
-主键 ID 在表内必须唯一
-人物名称 + 朝代组合应尽量唯一
 
### 引用完整性约束
-外键必须指向已存在的主键
-删除主记录前必须先删除引用记录
 
## 数据质量标准
 
### 完整性标准
-必填字段覆盖率：100%
-推荐字段覆盖率：>80%
-可选字段覆盖率：>50%
 
### 准确性标准
-书名格式正确率：100%
-ID 前缀正确率：100%
-枚举值正确率：100%
 
### 一致性标准
-同一人物在不同表中的 ID 一致
-同一作品在不同表中的名称一致
-同一文献的书名格式一致
 

File created successfully at: /Users/a1234/Desktop/中国人物画知识图谱/.claude/references/data-schema.md

# 数据质量问题分类
 
本文档详细列举中国人物画知识图谱数据抽取过程中的常见质量问题。
 
## 问题分类体系
 
### 1. 字段名错误
 
#### 1.1 使用点号分隔符
-**错误**：`source.book`、`source.chapter`、`source.text`
-**正确**：`source_book`、`source_chapter`、`source_text`
-**原因**：CSV 字段名应使用下划线，不使用点号
 
#### 1.2 字段名拼写错误
-**错误**：`originalsource_sentence`、`source_sentense`
-**正确**：`source_text`
-**原因**：字段名不符合规范定义
 
#### 1.3 字段名缺失前缀
-**错误**：`book`、`chapter`、`text`
-**正确**：`source_book`、`source_chapter`、`source_text`
-**原因**：溯源字段必须使用 `source_` 前缀
 
### 2. 格式不规范
 
#### 2.1 书名缺少书名号
-**错误**：`历代名画记`、`古画品录`
-**正确**：`《历代名画记》`、`《古画品录》`
-**严重性**：高（必填字段格式错误）
 
#### 2.2 章节格式错误
-**错误**：`卷一 顾野王`、`卷一-顾野王`、`第一卷·顾野王`
-**正确**：`卷一·顾野王`
-**说明**：使用中文间隔号（·）分隔卷次和章节名
 
#### 2.3 ID 前缀错误
-**错误**：`work_001`、`person_001`、`painting_001`
-**正确**：`micro_001`、`meso_001`、`micro_001`
-**说明**：必须使用规范定义的前缀
 
#### 2.4 ID 前缀缺失
-**错误**：`gu_kaizhi`、`luoshen_fu`
-**正确**：`meso_gu_kaizhi`、`micro_luoshen_fu`
-**严重性**：高（影响外键关联）
 
### 3. 必填字段为空
 
#### 3.1 溯源字段为空
-**字段**：`source_book`
-**严重性**：严重（违反核心原则）
-**处理**：必须人工补充
 
#### 3.2 主键为空
-**字段**：`person_id`、`work_id`、`period_id`
-**严重性**：严重（无法建立关联）
-**处理**：必须人工补充
 
#### 3.3 核心字段为空
-**字段**：`person_name`、`work_title`
-**严重性**：高（影响数据可用性）
-**处理**：必须人工补充
 
### 4. 枚举值错误
 
#### 4.1 使用中文枚举值
-**字段**：`primary_role`
  -**错误**：`画家`、`评论家`、`收藏家`
  -**正确**：`Painter`、`Critic`、`Collector`
 
-**字段**：`status`
  -**错误**：`存世`、`佚失`、`传`
  -**正确**：`Extant`、`Lost`、`Attributed`
 
-**字段**：`support`
  -**错误**：`绢本`、`纸本`、`壁画`
  -**正确**：`Silk`、`Paper`、`Wall`
 
#### 4.2 使用非标准枚举值
-**字段**：`primary_role`
  -**错误**：`画师`、`书画家`、`文人画家`
  -**正确**：`Painter`、`Painter`、`Scholar`
 
-**字段**：`status`
  -**错误**：`现存`、`失传`、`疑似`
  -**正确**：`Extant`、`Lost`、`Attributed`
 
#### 4.3 枚举值大小写错误
-**错误**：`painter`、`PAINTER`、`Painter`
-**正确**：`Painter`（首字母大写）
 
### 5. 外键引用错误
 
#### 5.1 外键指向不存在的记录
-**示例**：`M2.2.person_ref = meso_xxx` 但 `M2.1` 中不存在 `meso_xxx`
-**严重性**：严重（破坏引用完整性）
-**处理**：必须人工检查
 
#### 5.2 外键前缀不匹配
-**错误**：`M3.1.creator_ref = person_001`
-**正确**：`M3.1.creator_ref = meso_001`
-**说明**：外键必须使用正确的前缀
 
#### 5.3 外键为空但应有值
-**示例**：作品记录的 `creator_ref` 为空
-**严重性**：中（影响数据完整性）
-**处理**：根据上下文补充或标记为 Unknown
 
### 6. 数据类型错误
 
#### 6.1 年份格式错误
-**错误**：`公元618年`、`618-907`（应为单一年份）
-**正确**：`618`、`907`
-**说明**：年份字段应为纯数字
 
#### 6.2 布尔值格式错误
-**错误**：`是`、`否`、`yes`、`no`
-**正确**：`TRUE`、`FALSE` 或 `1`、`0`
 
#### 6.3 数值字段包含文本
-**错误**：`约618年`、`618年左右`
-**正确**：`618`（不确定性在备注字段说明）
 
### 7. 编码和特殊字符问题
 
#### 7.1 编码错误
-**表现**：乱码、问号、方框字符
-**原因**：文件编码不是 UTF-8-BOM
-**处理**：转换为 UTF-8-BOM 编码
 
#### 7.2 特殊字符错误
-**错误**：使用全角逗号、全角引号在 CSV 中
-**正确**：CSV 分隔符使用半角逗号，引号使用半角双引号
 
#### 7.3 换行符问题
-**表现**：字段内容意外换行
-**处理**：字段内容包含换行时必须用双引号包裹
 
### 8. 数据一致性问题
 
#### 8.1 同一实体 ID 不一致
-**示例**：同一人物在不同表中使用不同 ID
-**严重性**：严重（破坏数据关联）
 
#### 8.2 同一实体名称不一致
-**示例**：`顾恺之` vs `顾恺之（顾长康）`
-**处理**：统一使用标准名称，别名放在专门字段
 
#### 8.3 书名格式不一致
-**示例**：同一文献有时写《历代名画记》，有时写《歷代名畫記》
-**处理**：统一使用简体中文标准书名
 
### 9. 逻辑错误
 
#### 9.1 时间逻辑错误
-**示例**：`birth_year = 700`, `death_year = 650`
-**严重性**：高（违反常识）
 
#### 9.2 关系逻辑错误
-**示例**：A 是 B 的老师，B 是 A 的老师（循环关系）
-**严重性**：中（需人工判断）
 
#### 9.3 地理逻辑错误
-**示例**：唐代人物出生地为"北京"（应为"幽州"）
-**严重性**：中（历史地名使用错误）
 
### 10. 数据完整性问题
 
#### 10.1 推荐字段覆盖率低
-**字段**：`source_chapter`
-**标准**：覆盖率应 >80%
-**处理**：尽量补充
 
#### 10.2 可选字段覆盖率低
-**字段**：`source_page`、`notes`
-**标准**：覆盖率应 >50%
-**处理**：有则补充，无则不强求
 
#### 10.3 关键信息缺失
-**示例**：人物记录缺少朝代信息
-**严重性**：高（影响数据可用性）
 
## 问题严重性分级
 
### 严重 (Critical)
-必填字段为空
-主键/外键错误
-破坏引用完整性
-违反核心原则（可溯源性）
 
### 高 (High)
-格式严重不规范（书名号、ID 前缀）
-枚举值错误
-逻辑错误
-核心字段为空
 
### 中 (Medium)
-推荐字段为空
-格式轻微不规范
-数据一致性问题
-外键为空但可接受
 
### 低 (Low)
-可选字段为空
-格式美观性问题
-非关键信息缺失
 
## 自动修复 vs 人工处理
 
### 可自动修复
-字段名错误（重命名）
-书名号缺失（添加《》）
-枚举值中英文转换（有明确映射）
-ID 前缀缺失（根据表类型添加）
-编码转换
 
### 需人工处理
-必填字段为空（需补充内容）
-外键指向不存在（需确认正确引用）
-逻辑错误（需专业判断）
-数据一致性冲突（需人工决策）
-复杂格式错误（需理解语义）
 
## 质量检查清单
 
### 完整性检查
-[ ] 所有必填字段非空
-[ ] 推荐字段覆盖率 >80%
-[ ] 可选字段覆盖率 >50%
 
### 准确性检查
-[ ] 书名格式 100% 正确
-[ ] ID 前缀 100% 正确
-[ ] 枚举值 100% 正确
-[ ] 外键引用 100% 有效
 
### 一致性检查
-[ ] 同一实体 ID 一致
-[ ] 同一实体名称一致
-[ ] 书名格式一致
-[ ] 时间逻辑一致
 
### 规范性检查
-[ ] 文件编码为 UTF-8-BOM
-[ ] 字段名符合规范
-[ ] 数据类型正确
-[ ] 无特殊字符问题
 

File created successfully at: /Users/a1234/Desktop/中国人物画知识图谱/.claude/references/quality-issues.md

# CSV 文件处理规范
 
本文档提供 CSV 文件读写的技术规范和最佳实践。
 
## 编码规范
 
### UTF-8-BOM 编码
 
**要求**：所有 CSV 文件必须使用 UTF-8-BOM 编码
 
**原因**：
-支持中文字符
-BOM 标记帮助 Excel 正确识别编码
-避免乱码问题
 
**Python 读取**：
\```python
import pandas as pd
 
df = pd.read_csv(file_path, encoding='utf-8-sig', index_col=False)
\```
 
**Python 写入**：
\```python
df.to_csv(file_path, encoding='utf-8-sig', index=False)
\```
 
**检查编码**：
\```bash
file -I file.csv
# 输出应包含：charset=utf-8
\```
 
**转换编码**：
\```bash
iconv -f GBK -t UTF-8 input.csv > output.csv
\```
 
## 索引处理规范
 
### 防止第一列被误认为索引
 
**问题**：pandas 默认可能将第一列作为索引，导致数据错位
 
**解决方案**：始终使用 `index_col=False`
 
\```python
# 正确做法
df = pd.read_csv(file_path, encoding='utf-8-sig', index_col=False)
 
# 错误做法（可能导致第一列丢失）
df = pd.read_csv(file_path, encoding='utf-8-sig')
\```
 
### 写入时不保存索引
 
\```python
# 正确做法
df.to_csv(file_path, encoding='utf-8-sig', index=False)
 
# 错误做法（会多出一列无意义的索引）
df.to_csv(file_path, encoding='utf-8-sig')
\```
 
## 行号计算规范
 
### CSV 行号与 DataFrame 索引的关系
 
**规则**：CSV 行号 = DataFrame 索引 + 2
 
**原因**：
-CSV 第 1 行是表头
-DataFrame 索引从 0 开始
-因此 DataFrame 索引 0 对应 CSV 第 2 行
 
**单级索引**：
\```python
# DataFrame 索引 0 → CSV 行号 2
# DataFrame 索引 1 → CSV 行号 3
row_num = int(idx) + 2
\```
 
**多级索引**：
\```python
# 多级索引取第一个元素
if isinstance(idx, tuple):
    row_num = int(idx[0]) + 2
else:
    row_num = int(idx) + 2
\```
 
**示例**：
\```python
import pandas as pd
 
df = pd.read_csv('data.csv', encoding='utf-8-sig', index_col=False)
 
# 遍历 DataFrame 并输出 CSV 行号
for idx, row in df.iterrows():
    csv_row_num = int(idx) + 2
    print(f"CSV 行号: {csv_row_num}, 数据: {row['person_name']}")
\```
 
## 字段名规范
 
### 命名规则
 
-使用小写字母和下划线
-不使用点号、连字符、空格
-不使用中文字符
 
**正确**：
\```
person_id, source_book, source_chapter, birth_year
\```
 
**错误**：
\```
person.id, source-book, source chapter, 人物ID
\```
 
### 读取时处理字段名
 
\```python
# 读取后清理字段名
df = pd.read_csv(file_path, encoding='utf-8-sig', index_col=False)
df.columns = df.columns.str.strip()  # 去除空格
df.columns = df.columns.str.lower()  # 转小写（可选）
\```
 
## 特殊字符处理
 
### 逗号处理
 
**问题**：字段内容包含逗号会破坏 CSV 结构
 
**解决方案**：使用双引号包裹
 
\```python
# pandas 自动处理
df.to_csv(file_path, encoding='utf-8-sig', index=False, quoting=csv.QUOTE_MINIMAL)
\```
 
**手动处理**：
\```python
import csv
 
# 所有字段都加引号
df.to_csv(file_path, encoding='utf-8-sig', index=False, quoting=csv.QUOTE_ALL)
 
# 只对包含特殊字符的字段加引号
df.to_csv(file_path, encoding='utf-8-sig', index=False, quoting=csv.QUOTE_MINIMAL)
\```
 
### 换行符处理
 
**问题**：字段内容包含换行符
 
**解决方案**：
\```python
# pandas 自动处理，字段会被双引号包裹
df.to_csv(file_path, encoding='utf-8-sig', index=False)
 
# 读取时保持换行符
df = pd.read_csv(file_path, encoding='utf-8-sig', index_col=False, keep_default_na=False)
\```
 
### 引号处理
 
**问题**：字段内容包含双引号
 
**解决方案**：双引号转义为两个双引号
 
\```python
# pandas 自动处理
# 原始内容：He said "hello"
# CSV 中存储：He said ""hello""
\```
 
## 空值处理
 
### 空值表示
 
**标准**：使用空字符串或不填写
 
**不推荐**：
-`NULL`
-`None`
-`N/A`
-`#N/A`
 
**读取时处理空值**：
\```python
# 保持空字符串为空字符串，不转换为 NaN
df = pd.read_csv(file_path, encoding='utf-8-sig', index_col=False, keep_default_na=False)
 
# 或者指定哪些值视为 NaN
df = pd.read_csv(file_path, encoding='utf-8-sig', index_col=False, na_values=['NULL', 'N/A'])
\```
 
**写入时处理空值**：
\```python
# 将 NaN 写为空字符串
df.to_csv(file_path, encoding='utf-8-sig', index=False, na_rep='')
\```
 
## 数据类型处理
 
### 字符串类型
 
**问题**：数字 ID 可能被识别为数值类型，导致前导零丢失
 
**解决方案**：指定列类型为字符串
 
\```python
# 读取时指定类型
df = pd.read_csv(
    file_path, 
    encoding='utf-8-sig', 
    index_col=False,
    dtype={'person_id': str, 'work_id': str}
)
 
# 或读取后转换
df['person_id'] = df['person_id'].astype(str)
\```
 
### 日期类型
 
\```python
# 读取时解析日期
df = pd.read_csv(
    file_path, 
    encoding='utf-8-sig', 
    index_col=False,
    parse_dates=['birth_date', 'death_date']
)
\```
 
### 布尔类型
 
\```python
# 读取时转换布尔值
df = pd.read_csv(file_path, encoding='utf-8-sig', index_col=False)
df['is_verified'] = df['is_verified'].map({'TRUE': True, 'FALSE': False, '1': True, '0': False})
\```
 
## 大文件处理
 
### 分块读取
 
\```python
# 分块读取大文件
chunk_size = 1000
for chunk in pd.read_csv(file_path, encoding='utf-8-sig', index_col=False, chunksize=chunk_size):
    process_chunk(chunk)
\```
 
### 只读取需要的列
 
\```python
# 只读取指定列
df = pd.read_csv(
    file_path, 
    encoding='utf-8-sig', 
    index_col=False,
    usecols=['person_id', 'person_name', 'source_book']
)
\```
 
## 错误处理
 
### 读取错误处理
 
\```python
import pandas as pd
 
try:
    df = pd.read_csv(file_path, encoding='utf-8-sig', index_col=False)
except FileNotFoundError:
    print(f"文件不存在: {file_path}")
except pd.errors.EmptyDataError:
    print(f"文件为空: {file_path}")
except pd.errors.ParserError:
    print(f"文件格式错误: {file_path}")
except Exception as e:
    print(f"读取文件时发生错误: {e}")
\```
 
### 写入错误处理
 
\```python
try:
    df.to_csv(file_path, encoding='utf-8-sig', index=False)
except PermissionError:
    print(f"没有写入权限: {file_path}")
except Exception as e:
    print(f"写入文件时发生错误: {e}")
\```
 
## 完整示例
 
### 读取 CSV 文件
 
\```python
import pandas as pd
 
def read_csv_safe(file_path):
    """安全读取 CSV 文件"""
    try:
        df = pd.read_csv(
            file_path,
            encoding='utf-8-sig',  # UTF-8-BOM 编码
            index_col=False,       # 不使用第一列作为索引
            keep_default_na=False, # 保持空字符串
            dtype=str              # 所有列读取为字符串（可选）
        )
        
        # 清理字段名
        df.columns = df.columns.str.strip()
        
        return df
    except Exception as e:
        print(f"读取文件失败: {file_path}, 错误: {e}")
        return None
\```
 
### 写入 CSV 文件
 
\```python
def write_csv_safe(df, file_path):
    """安全写入 CSV 文件"""
    try:
        df.to_csv(
            file_path,
            encoding='utf-8-sig',  # UTF-8-BOM 编码
            index=False,           # 不写入索引列
            na_rep='',             # NaN 写为空字符串
            quoting=csv.QUOTE_MINIMAL  # 最小引号策略
        )
        print(f"文件写入成功: {file_path}")
        return True
    except Exception as e:
        print(f"写入文件失败: {file_path}, 错误: {e}")
        return False
\```
 
### 遍历并报告行号
 
\```python
def process_csv_with_row_numbers(file_path):
    """处理 CSV 并报告行号"""
    df = read_csv_safe(file_path)
    if df is None:
        return
    
    issues = []
    
    for idx, row in df.iterrows():
        csv_row_num = int(idx) + 2  # CSV 行号
        
        # 检查必填字段
        if pd.isna(row['source_book']) or row['source_book'] == '':
            issues.append({
                'file': file_path,
                'row': csv_row_num,
                'field': 'source_book',
                'issue': '必填字段为空'
            })
    
    return issues
\```
 
## 最佳实践清单
 
-[ ] 使用 UTF-8-BOM 编码
-[ ] 读取时使用 `index_col=False`
-[ ] 写入时使用 `index=False`
-[ ] 行号计算：DataFrame 索引 + 2
-[ ] 字段名使用下划线分隔
-[ ] 处理特殊字符（逗号、换行、引号）
-[ ] 正确处理空值
-[ ] 指定数据类型（避免类型推断错误）
-[ ] 添加错误处理
-[ ] 大文件使用分块读取
 

File created successfully at: /Users/a1234/Desktop/中国人物画知识图谱/.claude/references/csv-handling.md

# 外键关联关系详解
 
本文档详细说明中国人物画知识图谱中的外键关联关系。
 
## 关系图总览
 
\```
M1.1 时序本体 (period_id)
    ↓
M2.1 历史人物 (person_id) ← M1.2 空间地理 (loc_id)
    ↓                          ↓
    ├─→ M2.2 履历 (person_ref)
    ├─→ M2.3 关系 (source_id, target_id)
    └─→ M3.1 作品 (creator_ref) ← M1.1 时序 (period_ref)
            ↓                      ← M1.3 图像志 (icon_ref)
        M3.2 文献 (target_ref, author_ref)
\```
 
## 详细关联关系
 
### 1. M2.2 履历 → M2.1 人物
 
**外键字段**：`M2.2.person_ref`  
**引用字段**：`M2.1.person_id`  
**关系类型**：多对一（一个人物可有多条履历）  
**必填性**：必填
 
**示例**：
\```csv
# M2.1_历史人物核心表.csv
person_id,person_name,primary_role
meso_gu_kaizhi,顾恺之,Painter
 
# M2.2_履历与时空轨迹.csv
cv_id,person_ref,event_type,event_year
cv_001,meso_gu_kaizhi,Birth,344
cv_002,meso_gu_kaizhi,Career,364
\```
 
**验证规则**：
-`person_ref` 必须存在于 `M2.1.person_id` 中
-`person_ref` 不能为空
-`person_ref` 必须使用 `meso_` 前缀
 
### 2. M2.3 关系 → M2.1 人物
 
**外键字段**：`M2.3.source_id`, `M2.3.target_id`  
**引用字段**：`M2.1.person_id`  
**关系类型**：多对多（人物之间的关系）  
**必填性**：必填
 
**示例**：
\```csv
# M2.1_历史人物核心表.csv
person_id,person_name
meso_gu_kaizhi,顾恺之
meso_lu_tanwei,陆探微
 
# M2.3_社会关系实例.csv
rel_id,source_id,target_id,relation_type
rel_001,meso_gu_kaizhi,meso_lu_tanwei,Friend
\```
 
**验证规则**：
-`source_id` 和 `target_id` 必须存在于 `M2.1.person_id` 中
-`source_id` 和 `target_id` 不能相同（避免自引用）
-必须使用 `meso_` 前缀
 
### 3. M3.1 作品 → M2.1 人物
 
**外键字段**：`M3.1.creator_ref`  
**引用字段**：`M2.1.person_id`  
**关系类型**：多对一（一个人物可创作多件作品）  
**必填性**：强烈推荐（除非作者不详）
 
**示例**：
\```csv
# M2.1_历史人物核心表.csv
person_id,person_name
meso_gu_kaizhi,顾恺之
 
# M3.1_作品实体表.csv
work_id,work_title,creator_ref
micro_luoshen_fu,洛神赋图,meso_gu_kaizhi
\```
 
**验证规则**：
-`creator_ref` 应存在于 `M2.1.person_id` 中
-作者不详时可为空或使用 `Unknown`
-必须使用 `meso_` 前缀
 
### 4. M3.1 作品 → M1.1 时序
 
**外键字段**：`M3.1.period_ref`  
**引用字段**：`M1.1.period_id`  
**关系类型**：多对一（一个时期有多件作品）  
**必填性**：推荐
 
**示例**：
\```csv
# M1.1_时序本体.csv
period_id,period_name,start_year,end_year
period_eastern_jin,东晋,317,420
 
# M3.1_作品实体表.csv
work_id,work_title,period_ref
micro_luoshen_fu,洛神赋图,period_eastern_jin
\```
 
**验证规则**：
-`period_ref` 应存在于 `M1.1.period_id` 中
-必须使用 `period_` 前缀
 
### 5. M3.1 作品 → M1.3 图像志
 
**外键字段**：`M3.1.icon_ref`  
**引用字段**：`M1.3.icon_id`  
**关系类型**：多对一（一个题材有多件作品）  
**必填性**：推荐
 
**示例**：
\```csv
# M1.3_图像志题材分类.csv
icon_id,icon_name,icon_category
icon_portrait,人物画,Figure
 
# M3.1_作品实体表.csv
work_id,work_title,icon_ref
micro_luoshen_fu,洛神赋图,icon_portrait
\```
 
**验证规则**：
-`icon_ref` 应存在于 `M1.3.icon_id` 中
-必须使用 `icon_` 前缀
 
### 6. M3.2 文献 → M3.1 作品 或 M2.1 人物
 
**外键字段**：`M3.2.target_ref`  
**引用字段**：`M3.1.work_id` 或 `M2.1.person_id`  
**关系类型**：多对一（一个对象可有多条文献著录）  
**必填性**：必填
 
**示例**：
\```csv
# M3.1_作品实体表.csv
work_id,work_title
micro_luoshen_fu,洛神赋图
 
# M2.1_历史人物核心表.csv
person_id,person_name
meso_gu_kaizhi,顾恺之
 
# M3.2_文献著录与品评.csv
lit_id,target_ref,target_type,content
lit_001,micro_luoshen_fu,Work,"洛神赋图，顾恺之所作"
lit_002,meso_gu_kaizhi,Person,"顾恺之，字长康"
\```
 
**验证规则**：
-当 `target_type = Work` 时，`target_ref` 必须存在于 `M3.1.work_id` 中
-当 `target_type = Person` 时，`target_ref` 必须存在于 `M2.1.person_id` 中
-必须使用正确的前缀（`micro_` 或 `meso_`）
 
### 7. M3.2 文献 → M2.1 人物（作者）
 
**外键字段**：`M3.2.author_ref`  
**引用字段**：`M2.1.person_id`  
**关系类型**：多对一（一个作者可写多条文献）  
**必填性**：推荐
 
**示例**：
\```csv
# M2.1_历史人物核心表.csv
person_id,person_name
meso_zhang_yanyuan,张彦远
 
# M3.2_文献著录与品评.csv
lit_id,author_ref,content
lit_001,meso_zhang_yanyuan,"顾恺之，字长康"
\```
 
**验证规则**：
-`author_ref` 应存在于 `M2.1.person_id` 中
-作者不详时可为空
-必须使用 `meso_` 前缀
 
## 外键检查 SQL 示例
 
虽然我们使用 CSV 文件，但可以用类似 SQL 的逻辑检查外键完整性：
 
### 检查 M2.2 → M2.1
 
\```python
# 检查 M2.2 中的 person_ref 是否都存在于 M2.1 中
invalid_refs = df_m22[~df_m22['person_ref'].isin(df_m21['person_id'])]
\```
 
### 检查 M3.1 → M2.1
 
\```python
# 检查 M3.1 中的 creator_ref 是否都存在于 M2.1 中
# 排除空值
valid_creators = df_m31[df_m31['creator_ref'].notna()]
invalid_refs = valid_creators[~valid_creators['creator_ref'].isin(df_m21['person_id'])]
\```
 
### 检查 M3.2 → M3.1 或 M2.1
 
\```python
# 检查 M3.2 中的 target_ref
for idx, row in df_m32.iterrows():
    target_ref = row['target_ref']
    target_type = row['target_type']
    
    if target_type == 'Work':
        if target_ref not in df_m31['work_id'].values:
            print(f"行 {idx+2}: target_ref {target_ref} 不存在于 M3.1")
    elif target_type == 'Person':
        if target_ref not in df_m21['person_id'].values:
            print(f"行 {idx+2}: target_ref {target_ref} 不存在于 M2.1")
\```
 
## 外键完整性检查清单
 
### 必须检查的外键
-[ ] M2.2.person_ref → M2.1.person_id
-[ ] M2.3.source_id → M2.1.person_id
-[ ] M2.3.target_id → M2.1.person_id
-[ ] M3.2.target_ref → M3.1.work_id 或 M2.1.person_id
 
### 推荐检查的外键
-[ ] M3.1.creator_ref → M2.1.person_id
-[ ] M3.1.period_ref → M1.1.period_id
-[ ] M3.1.icon_ref → M1.3.icon_id
-[ ] M3.2.author_ref → M2.1.person_id
 
## 外键错误处理策略
 
### 严重错误（必须修复）
-必填外键为空
-外键指向不存在的记录
-外键前缀错误
 
**处理方式**：
1.人工检查原始文献
2.补充正确的外键值
3.或标记为需要进一步调查
 
### 警告（建议修复）
-推荐外键为空
-外键值存在但格式不规范
 
**处理方式**：
1.尽量补充外键值
2.规范化外键格式
3.在备注中说明原因
 
## 级联操作建议
 
### 删除操作
-删除 M2.1 人物记录前，应先检查：
  -M2.2 中是否有引用
  -M2.3 中是否有引用
  -M3.1 中是否有引用
  -M3.2 中是否有引用
 
### 更新操作
-更新 M2.1.person_id 时，应同步更新：
  -M2.2.person_ref
  -M2.3.source_id / target_id
  -M3.1.creator_ref
  -M3.2.target_ref / author_ref
 
## 外键命名规范
 
### 引用字段命名
-引用人物：`person_ref`, `creator_ref`, `author_ref`, `source_id`, `target_id`
-引用作品：`work_ref`, `target_ref`
-引用时序：`period_ref`
-引用地理：`location_ref`
-引用图像志：`icon_ref`
 
### 命名原则
-使用 `_ref` 后缀表示外键引用
-使用 `_id` 后缀表示主键
-特殊情况（如 source_id, target_id）保持语义清晰
 

File created successfully at: /Users/a1234/Desktop/中国人物画知识图谱/.claude/references/foreign-keys.md

# 使用示例
 
本文档提供中国人物画知识图谱项目的常用命令和操作示例。
 
## 数据审查示例
 
### 使用 extraction-reviewer 技能
 
#### 审查单个文件
\```bash
# 方式 1：使用技能命令
/extraction-reviewer --file 03-初步抽取/古画品录/M2.1_历史人物_古画品录.csv
 
# 方式 2：直接运行脚本（如果技能提供）
python .claude/skills/extraction-reviewer/scripts/reviewer.py \
  --file 03-初步抽取/古画品录/M2.1_历史人物_古画品录.csv \
  --output-dir 04-审查与修订/古画品录
\```
 
#### 审查整个文献目录
\```bash
# 审查某部文献的所有 CSV 文件
/extraction-reviewer --dir 03-初步抽取/古画品录
 
# 或使用脚本
python .claude/skills/extraction-reviewer/scripts/reviewer.py \
  --dir 03-初步抽取/古画品录 \
  --output-dir 04-审查与修订/古画品录
\```
 
#### 审查多个文献
\```bash
# 批量审查
for dir in 03-初步抽取/*/; do
  dirname=$(basename "$dir")
  echo "审查 $dirname"
  /extraction-reviewer --dir "$dir"
done
\```
 
### 查看审查报告
 
\```bash
# 查看最新的审查报告
ls -lt 04-审查与修订/古画品录/报告/ | head -5
 
# 查看报告内容
cat 04-审查与修订/古画品录/报告/审查报告_20260419_165338.md
 
# 查看问题清单（CSV 格式，可用 Excel 打开）
open 04-审查与修订/古画品录/报告/问题清单_20260419_165338.csv
\```
 
## 变更日志示例
 
### 使用 change-logger 技能
 
#### 自动记录（extraction-reviewer 触发）
\```bash
# extraction-reviewer 完成后会自动调用 change-logger
# 无需手动操作
\```
 
#### 手动记录变更
\```bash
# 记录单个文件的修改
python .claude/skills/change-logger/scripts/logger.py \
  --files 04-审查与修订/古画品录/修订数据/M2.1_历史人物_修订版_20260419.csv \
  --reason "手动修正人物生卒年份" \
  --original-file 03-初步抽取/古画品录/M2.1_历史人物.csv
 
# 记录多个文件的修改
python .claude/skills/change-logger/scripts/logger.py \
  --files 04-审查与修订/古画品录/修订数据/*.csv \
  --reason "批量修复书名格式" \
  --original-file 03-初步抽取/古画品录/
\```
 
### 查看变更日志
 
\```bash
# 查看今天的变更日志
cat 04-审查与修订/变更日志/$(date +%Y-%m)/变更日志_$(date +%Y-%m-%d).md
 
# 查看本月所有变更
ls -l 04-审查与修订/变更日志/$(date +%Y-%m)/
 
# 搜索特定文件的变更历史
grep "M2.1_历史人物" 04-审查与修订/变更日志/2026-04/*.md
\```
 
## 数据统计示例
 
### 统计记录数
 
\```bash
# 统计某部文献的总记录数
wc -l 03-初步抽取/历代名画记/*.csv
 
# 统计所有文献的记录数
for dir in 03-初步抽取/*/; do
  dirname=$(basename "$dir")
  count=$(wc -l "$dir"/*.csv | tail -1 | awk '{print $1}')
  echo "$dirname: $count 行"
done
\```
 
### 查看字段覆盖率
 
\```bash
# 查看表头
head -1 03-初步抽取/历代名画记/M2.1_历史人物核心表.csv
 
# 统计某字段的非空值数量
awk -F',' 'NR>1 && $3!="" {count++} END {print count}' \
  03-初步抽取/历代名画记/M2.1_历史人物核心表.csv
\```
 
### 查看统计数据
 
\```bash
# 查看审查统计（JSON 格式）
cat 04-审查与修订/古画品录/统计/统计数据_20260419_165338.json
 
# 使用 jq 格式化输出
jq '.' 04-审查与修订/古画品录/统计/统计数据_20260419_165338.json
\```
 
## 数据格式检查示例
 
### 检查文件编码
 
\```bash
# 检查单个文件编码
file -I 03-初步抽取/古画品录/M2.1_历史人物_古画品录.csv
 
# 批量检查编码
for file in 03-初步抽取/古画品录/*.csv; do
  echo "$file:"
  file -I "$file"
done
\```
 
### 检查书名格式
 
\```bash
# 检查 source_book 字段是否有书名号
grep -n "source_book" 03-初步抽取/古画品录/M2.1_历史人物_古画品录.csv | head -5
 
# 查找缺少书名号的记录
awk -F',' 'NR>1 && $4!~/《.*》/ {print NR": "$4}' \
  03-初步抽取/古画品录/M2.1_历史人物_古画品录.csv
\```
 
### 检查 ID 前缀
 
\```bash
# 检查 person_id 是否都有 meso_ 前缀
awk -F',' 'NR>1 && $1!~/^meso_/ {print NR": "$1}' \
  03-初步抽取/古画品录/M2.1_历史人物_古画品录.csv
 
# 检查 work_id 是否都有 micro_ 前缀
awk -F',' 'NR>1 && $1!~/^micro_/ {print NR": "$1}' \
  03-初步抽取/古画品录/M3.1_作品实体表_古画品录.csv
\```
 
## 数据备份示例
 
### 备份原始数据
 
\```bash
# 备份整个抽取目录
tar -czf backup_$(date +%Y%m%d).tar.gz 03-初步抽取/
 
# 备份单个文献
tar -czf 古画品录_backup_$(date +%Y%m%d).tar.gz 03-初步抽取/古画品录/
\```
 
### 恢复备份
 
\```bash
# 恢复备份
tar -xzf backup_20260419.tar.gz
 
# 恢复到指定目录
tar -xzf backup_20260419.tar.gz -C /path/to/restore/
\```
 
## Git 操作示例
 
### 提交修订数据
 
\```bash
# 查看修改状态
git status
 
# 添加修订数据
git add 04-审查与修订/古画品录/修订数据/
 
# 提交
git commit -m "修订古画品录数据：修复书名格式和ID前缀"
 
# 推送到远程
git push origin main
\```
 
### 查看修改历史
 
\```bash
# 查看某个文件的修改历史
git log --follow 03-初步抽取/古画品录/M2.1_历史人物_古画品录.csv
 
# 查看具体修改内容
git diff HEAD~1 03-初步抽取/古画品录/M2.1_历史人物_古画品录.csv
\```
 
## Python 脚本示例
 
### 读取 CSV 文件
 
\```python
import pandas as pd
 
# 读取 CSV 文件
df = pd.read_csv(
    '03-初步抽取/古画品录/M2.1_历史人物_古画品录.csv',
    encoding='utf-8-sig',
    index_col=False
)
 
# 查看基本信息
print(f"总记录数: {len(df)}")
print(f"字段列表: {df.columns.tolist()}")
print(f"前5条记录:\n{df.head()}")
\```
 
### 检查数据质量
 
\```python
import pandas as pd
 
df = pd.read_csv(
    '03-初步抽取/古画品录/M2.1_历史人物_古画品录.csv',
    encoding='utf-8-sig',
    index_col=False
)
 
# 检查必填字段
required_fields = ['source_book', 'person_id', 'person_name']
for field in required_fields:
    null_count = df[field].isna().sum()
    empty_count = (df[field] == '').sum()
    print(f"{field}: {null_count} 个空值, {empty_count} 个空字符串")
 
# 检查书名格式
no_brackets = df[~df['source_book'].str.contains('《.*》', na=False)]
print(f"缺少书名号的记录数: {len(no_brackets)}")
 
# 检查 ID 前缀
wrong_prefix = df[~df['person_id'].str.startswith('meso_', na=False)]
print(f"ID 前缀错误的记录数: {len(wrong_prefix)}")
\```
 
### 批量修复数据
 
\```python
import pandas as pd
 
df = pd.read_csv(
    '03-初步抽取/古画品录/M2.1_历史人物_古画品录.csv',
    encoding='utf-8-sig',
    index_col=False
)
 
# 修复书名格式
df['source_book'] = df['source_book'].apply(
    lambda x: f"《{x}》" if not pd.isna(x) and not x.startswith('《') else x
)
 
# 修复 ID 前缀
df['person_id'] = df['person_id'].apply(
    lambda x: f"meso_{x}" if not pd.isna(x) and not x.startswith('meso_') else x
)
 
# 保存修订数据
df.to_csv(
    '04-审查与修订/古画品录/修订数据/M2.1_历史人物_修订版.csv',
    encoding='utf-8-sig',
    index=False
)
 
print("数据修复完成")
\```
 
## 常用查询示例
 
### 查找特定人物
 
\```bash
# 在所有文件中查找"顾恺之"
grep -r "顾恺之" 03-初步抽取/
 
# 查找特定 person_id
grep "meso_gu_kaizhi" 03-初步抽取/*/M2.*.csv
\```
 
### 统计人物数量
 
\```bash
# 统计某部文献的人物数量
wc -l 03-初步抽取/古画品录/M2.1_历史人物_古画品录.csv
 
# 统计所有文献的人物总数
cat 03-初步抽取/*/M2.1_*.csv | wc -l
\```
 
### 查找重复记录
 
\```python
import pandas as pd
 
df = pd.read_csv(
    '03-初步抽取/古画品录/M2.1_历史人物_古画品录.csv',
    encoding='utf-8-sig',
    index_col=False
)
 
# 查找重复的 person_id
duplicates = df[df.duplicated(subset=['person_id'], keep=False)]
print(f"重复的 person_id 数量: {len(duplicates)}")
print(duplicates[['person_id', 'person_name']])
\```
 
## 项目维护示例
 
### 清理临时文件
 
\```bash
# 清理 Python 缓存
find . -type d -name "__pycache__" -exec rm -rf {} +
find . -type f -name "*.pyc" -delete
 
# 清理 macOS 文件
find . -name ".DS_Store" -delete
\```
 
### 更新文档
 
\```bash
# 更新 CLAUDE.md
vim CLAUDE.md
 
# 更新数据结构规范
vim 01-元知识/中国人物画知识图谱数据结构v1_4.md
 
# 提交文档更新
git add CLAUDE.md 01-元知识/
git commit -m "更新项目文档"
\```
 
### 生成项目报告
 
\```bash
# 统计项目进度
echo "=== 项目统计 ==="
echo "已处理文献数: $(ls -d 03-初步抽取/*/ | wc -l)"
echo "总记录数: $(cat 03-初步抽取/*/M*.csv | wc -l)"
echo "审查报告数: $(find 04-审查与修订 -name "审查报告_*.md" | wc -l)"
echo "变更日志数: $(find 04-审查与修订/变更日志 -name "*.md" | wc -l)"
\```
 

File created successfully at: /Users/a1234/Desktop/中国人物画知识图谱/.claude/references/examples.md

(Bash completed with no output)

(Bash completed with no output)

total 96
-rw-r--r--@ 1 a1234  staff   8.3K Apr 19 18:07 csv-handling.md
-rw-r--r--@ 1 a1234  staff   5.7K Apr 19 18:05 data-schema.md
-rw-r--r--@ 1 a1234  staff   8.6K Apr 19 18:09 examples.md
-rw-r--r--@ 1 a1234  staff   7.4K Apr 19 18:08 foreign-keys.md
-rw-r--r--@ 1 a1234  staff   7.1K Apr 19 18:06 quality-issues.md

     232 /Users/a1234/Desktop/中国人物画知识图谱/CLAUDE.md