柔性数据库设计：AI Agent时代的关系型数据库Schema动态扩展方案

1. 项目概述：一个为AI Agent设计的柔性数据库框架

如果你和我一样，经常在Claude、Cursor这类AI IDE里折腾，想把各种零散信息——比如网页摘录、会议笔记、PDF报告、甚至是聊天记录——都规整到一个地方，那你肯定遇到过这个头疼的问题：数据库的Schema（表结构）怎么定？

今天要聊的这个flexible-database-design项目，就是专门解决这个痛点的。它不是另一个Notion或Obsidian，而是一个可复用的“柔性Schema”设计心法，外加一套开箱即用的Python实现。简单说，它提供了一套方法论和工具，让你（或者更准确地说，让你的AI助手）能快速为任何“收集信息”的需求，搭建一个既灵活又结构化的个人数据库。

它的核心用户是谁？首先是开发者和重度信息处理者，尤其是那些习惯用命令行、喜欢用AI Agent（比如Claude、Cursor里的AI编程助手）来辅助工作流的人。其次，它也适合任何想建立个人知识库，但又不想被固定模板束缚的人。你不需要是数据库专家，只要会用基本的Python命令，就能跟着它的引导，让AI帮你把数据库搭起来。

这个项目的精髓在于“柔性”二字。传统的数据库设计，你得先想好要存什么字段（比如title,content,tags），然后建表。但现实是，你今天可能收集读书笔记，明天可能要存调研报告，后天又想记一下灵感碎片。为每个场景都单独建一套表？太麻烦。把所有可能字段都塞进一张大宽表？又乱又低效。flexible-database-design采用了一种“核心固定字段 + 动态扩展字段”的混合模式，用SQLite实现，让你能在保持核心数据一致性的前提下，灵活地适应各种数据结构。

2. 核心设计思路：为什么是“柔性Schema”？

在深入代码之前，我们得先搞清楚它到底解决了什么问题，以及为什么选择这样的方案。这比直接看命令更重要。

2.1 传统数据库设计的困境

想象一下，你要用数据库管理三类信息：

1. 读书笔记：需要书名、作者、摘录、个人感想、阅读进度。
2. 项目TODO：需要任务名、优先级、截止日期、负责人、状态。
3. 网页收藏：需要URL、标题、摘要、收藏时间、分类标签。

按传统做法，你有三个选择：

• 选择A：建三张表。notes,todos,bookmarks。结构清晰，查询高效。但问题是，当你又想记录“会议纪要”时，就得去改代码、加新表。不灵活，维护成本高。
• 选择B：建一张“万能”表。把所有字段（比如field1到field20）都设为TEXT，然后用一个type字段区分是笔记还是TODO。这会导致表结构非常稀疏，很多字段是空的，而且字段名没有语义（你不知道field5存的是作者还是截止日期），查询和索引都很别扭。
• 选择C：用NoSQL（如MongoDB）。文档型数据库确实灵活，但牺牲了强Schema带来的数据一致性保障，复杂的关联查询和事务处理也不如关系型数据库顺手，对于个人或轻量级应用来说，有时显得“杀鸡用牛刀”。

2.2 “柔性Schema”的折中之道

flexible-database-design的方案，可以看作是在关系型数据库的严谨和NoSQL的灵活之间，找到了一个巧妙的平衡点。其核心是两张表：

1. 核心表 (items)：存放所有记录都必须有的、结构固定的“元信息”。

   CREATE TABLE items ( id INTEGER PRIMARY KEY AUTOINCREMENT, content TEXT NOT NULL, -- 核心内容，如笔记正文、URL source TEXT, -- 来源，如 'manual', 'web', 'file' category TEXT, -- 大类，如 'note', 'todo', 'bookmark' created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP, is_deleted BOOLEAN DEFAULT 0 -- 软删除标记 );

   这张表保证了所有数据都有统一的ID、创建时间、内容主体和分类，这是数据的“骨架”。

2. 动态字段表 (dynamic_fields)：用于存放那些因记录而异、无法预先定义的属性。

   CREATE TABLE dynamic_fields ( item_id INTEGER NOT NULL, field_name TEXT NOT NULL, -- 属性名，如 'author', 'due_date', 'priority' field_value TEXT, -- 属性值 field_type TEXT DEFAULT 'text', -- 可选的类型提示，如 'text', 'number', 'date' PRIMARY KEY (item_id, field_name), FOREIGN KEY (item_id) REFERENCES items (id) ON DELETE CASCADE );

   这是一个经典的“实体-属性-值”（EAV）模型变体。每一条items记录，都可以通过多条dynamic_fields记录来附加任意多的属性。想给读书笔记加个“作者”字段？直接插入一条(item_id=1, field_name='author', field_value='刘慈欣')即可。明天要给TODO加个“依赖任务ID”字段？同样操作。

这种设计的好处显而易见：

• 无限扩展：无需修改表结构就能增加新字段。
• 结构清晰：核心信息与扩展信息分离，items表保持精简高效。
• 查询灵活：可以通过联结（JOIN）查询，获取某条记录的所有动态属性。

但它也有代价：

• 查询复杂度增加：要获取一条完整的记录（包括所有动态字段），需要执行JOIN操作。当动态字段很多时，查询会变慢。
• 数据类型弱化：field_value通常是TEXT，存储日期、数字时需要转换，失去了原生数据类型的校验和索引优势。
• 不适合高频、固定模式的业务：如果你的数据99%的结构都相同，用EAV就是自找麻烦。

因此，这个方案特别适合个人知识管理、碎片信息收集、实验性数据存储这类场景，这些场景的特点是：数据结构变化快、需求不固定、单次查询量不大、对极致性能要求不高。项目文档里提到的“个人知识库、碎片收集、表单、多源聚合”，正是其用武之地。

2.3 与AI Agent工作流的深度结合

这个设计最妙的一点，是它天生适合与AI Agent协同工作。在SKILL.md中定义的工作流里，AI Agent（如Claude）扮演了“数据库设计顾问”和“操作向导”的角色。

1. 引导需求分析：当你对AI说“我想做个读书笔记库”，AI会根据Skill里预设的引导逻辑，问你：“需要记录书名、作者、页数吗？需要评分或标签吗？” 它帮你把模糊的需求转化为具体的category和可能的field_name。
2. 生成与执行SQL：AI可以根据你的回答，动态生成初始化数据库的SQL语句（基于schema_template.sql微调），并调用flexible_db.py中的initialize_database()函数来执行。
3. 指导数据操作：当你说“归档我刚读的《三体》笔记”，AI可以调用archive_item.py脚本，并智能地将你提供的自然语言信息（“书名是三体，作者刘慈欣，评分5星”）映射到content和相应的dynamic_fields中。
4. 解释查询结果：当你查询“显示所有未完成的高优先级任务”，AI可以组合使用query_items.py的查询功能，并将返回的“扁平化”数据重新组织成易于阅读的自然语言格式反馈给你。

这相当于你拥有一个懂数据库设计的私人助理，它把复杂的数据库概念封装成了简单的对话。你不需要记住表名和字段名，只需要用自然语言描述你的需求。

3. 核心实现解析：代码是如何工作的？

理解了设计思路，我们再深入到项目提供的Python脚本中，看看这套心法是如何落地的。核心逻辑都在scripts/flexible_db.py里。

3.1 数据库初始化与连接管理

首先看FlexibleDatabase这个核心类。它的初始化函数确保了数据库和表结构的存在。

# 简化后的核心初始化逻辑 def initialize_database(db_path, schema_path=None): conn = sqlite3.connect(db_path) cursor = conn.cursor() # 1. 创建核心表 cursor.execute(''' CREATE TABLE IF NOT EXISTS items (...) ''') # 2. 创建动态字段表 cursor.execute(''' CREATE TABLE IF NOT EXISTS dynamic_fields (...) ''') # 3. 创建索引以加速查询 cursor.execute('CREATE INDEX IF NOT EXISTS idx_items_category ON items(category)') cursor.execute('CREATE INDEX IF NOT EXISTS idx_dynamic_cat_field ON dynamic_fields(item_id, field_name)') # 4. 可选：启用全文检索（FTS5虚拟表） if os.environ.get('FLEXIBLE_DB_FTS') == '1': cursor.execute(''' CREATE VIRTUAL TABLE IF NOT EXISTS items_fts USING fts5( content, source, category, content='items', content_rowid='id' ) ''') conn.commit() conn.close()

关键点解析：

• IF NOT EXISTS：这是幂等性操作的关键。无论脚本运行多少次，都不会破坏现有数据。
• 索引策略：在items.category和dynamic_fields(item_id, field_name)上创建索引。前者用于按大类快速筛选记录，后者是最重要的复合索引，用于高效地通过item_id查找其所有动态字段，或通过field_name查找所有具有该字段的记录。如果没有这个索引，涉及动态字段的查询性能会急剧下降。
• 全文检索（FTS）：这是一个高级功能，通过SQLite的FTS5扩展实现。它创建了一个items_fts虚拟表，专门用于对content等字段进行快速的全文搜索。注意，它需要SQLite 3.9+版本，并且通过环境变量FLEXIBLE_DB_FTS控制是否启用。启用后，插入items表的数据需要手动或通过触发器同步到items_fts表，项目中的archive_item.py脚本就处理了这个同步逻辑。

3.2 数据归档：核心的插入逻辑

数据是如何存进去的？看archive_item函数（在archive_item.py中被调用）。

def archive_item(content, source='manual', category=None, extra_fields=None, extractor=None): db = FlexibleDatabase() # 1. 如果有抽取器（如LLM），先用它从content中提取结构化信息 if extractor: extracted = extractor(content) # 将抽取结果与手动传入的extra_fields合并 if extra_fields: extracted.update(extra_fields) extra_fields = extracted # 2. 插入核心表 item_id = db.insert_item(content, source, category) # 3. 插入动态字段 if extra_fields: for field_name, field_value in extra_fields.items(): # 这里会处理值的序列化，比如字典、列表转为JSON字符串 db.insert_dynamic_field(item_id, field_name, field_value) # 4. 如果启用了FTS，同步到全文检索表 if db.fts_enabled: db.sync_fts(item_id, content, source, category) return item_id

操作心得与避坑指南：

• extractor参数是灵魂：这是连接AI能力的关键。你可以传入一个函数，这个函数接收原始的content（一段文本），返回一个字典。比如，你可以用OpenAI的API，让GPT分析一段会议纪要，自动提取出参会人、决议、下一步等字段。项目里scripts/extractors/目录下提供了一个dummy_extractor，就是一个简单的字符串分割示例，你需要替换成真正的LLM调用。
• 字段值的序列化：dynamic_fields.field_value是TEXT类型。如果你要存一个列表['python', 'sqlite']或字典{'score': 5}，必须在insert_dynamic_field内部将其转换为JSON字符串（json.dumps(value)）。查询时，再根据field_type或尝试json.loads()来还原。这是一个常见的陷阱，如果直接存Python对象，会报错。
• 事务处理：上面的简化代码没有展示，但实际insert_item和批量insert_dynamic_field应该包裹在一个数据库事务中。这确保了核心记录和其动态字段要么全部成功插入，要么全部失败，避免数据不一致。项目中的import_batch.py批量导入脚本就显式使用了事务，大幅提升了导入速度。

3.3 动态查询：如何灵活地查找数据？

这是柔性Schema最具挑战的部分。如何查询“category为todo且priority为高的所有记录”？query_items.py脚本和FlexibleDatabase.query_dynamic方法展示了解决方案。

def query_dynamic(self, category=None, field_filters=None, exact_match=False, offset=0, limit=50): """ field_filters: 字典，如 {'priority': '高', 'status': '进行中'} """ params = [] where_clauses = ["i.is_deleted = 0"] # 默认过滤已删除的 # 1. 构建基于category的查询 if category: where_clauses.append("i.category = ?") params.append(category) # 2. 构建基于动态字段的查询（最复杂的部分） if field_filters: for idx, (field_name, field_value) in enumerate(field_filters.items()): # 为每个过滤条件创建一个JOIN alias = f"df{idx}" from_clause += f" INNER JOIN dynamic_fields {alias} ON i.id = {alias}.item_id" where_clauses.append(f"{alias}.field_name = ?") params.append(field_name) # 处理值匹配：精确匹配或LIKE模糊匹配 if exact_match: where_clauses.append(f"{alias}.field_value = ?") else: # 注意：LIKE查询需要转义通配符%和_ where_clauses.append(f"{alias}.field_value LIKE ? ESCAPE '\\'") # 这里应该有一个转义函数，将用户输入的%转义为\% escaped_value = escape_like_wildcards(field_value) field_value = f"%{escaped_value}%" params.append(field_value) # 3. 组装SQL sql = f""" SELECT i.* FROM items i {from_clause} WHERE {' AND '.join(where_clauses)} ORDER BY i.created_at DESC LIMIT ? OFFSET ? """ params.extend([limit, offset]) return self.execute_query(sql, params)

关键点与性能考量：

• 多字段过滤的JOIN链：这是EAV模型查询的典型模式。每个过滤条件都需要一次INNER JOIN到dynamic_fields表。过滤两个字段，就需要JOIN两次。当过滤条件很多时，SQL会变得很长，且可能影响性能。这就是为什么前面要建(item_id, field_name)复合索引的原因，这个索引能大幅加速这种JOIN操作。
• exact_match参数的重要性：当用户想查询field_value为100%的记录时，如果使用LIKE '%100%%'，中间的%会被SQLite解释为通配符，导致查询错误。exact_match=True会改用等号=匹配，避免了这个问题。这是实际使用中极易踩的坑，脚本提供了--exact参数来应对。
• 分页与性能：使用LIMIT ? OFFSET ?进行分页。但对于海量数据（比如10万条以后），OFFSET效率会降低，因为数据库需要先扫描并跳过前面所有行。文档中建议，对于超大数据集，可以考虑使用WHERE created_at < ?这类基于游标的分页方式。
• 返回结果：这个查询只返回了items表的核心字段。如果需要同时获取每条记录的所有动态字段，通常需要再执行一次查询，或者使用更复杂的GROUP_CONCAT将动态字段聚合成一行。项目中query_items.py --list命令展示的就是后一种方式，它让数据看起来更完整。

3.4 管理功能：软删除、更新与批量操作

一个健壮的系统离不开数据管理功能。

• 软删除：manage_item.py --delete并不是真的执行DELETE，而是将items.is_deleted标记为1。这有两个好处：一是数据可以恢复（--restore），二是避免因外键约束导致dynamic_fields表中的关联数据被级联删除。查询时默认会过滤掉is_deleted=1的记录。
• 更新操作：manage_item.py --update需要谨慎处理。更新items表内容比较简单。更新动态字段则有两种策略：1) 删除该item_id的所有旧字段，重新插入新的extra_fields字典（简单粗暴，但无法保留未提及的字段）；2) 遍历新字典，逐字段更新或插入（更精细）。项目实现通常采用第二种。
• 批量导入：import_batch.py脚本是处理JSON/CSV文件的关键。它核心是使用executemany进行批量插入，并且将整个文件导入过程放在一个事务中。这比用循环单条插入要快几十甚至上百倍，因为只需要一次磁盘同步。

# 批量导入的核心逻辑示意 def import_batch(json_file_path): with open(json_file_path, 'r') as f: data = json.load(f) # 假设是列表，每个元素是一条记录 conn = self.get_connection() try: cursor = conn.cursor() cursor.execute('BEGIN TRANSACTION') # 开启事务 for item in data: # 插入items表 cursor.execute(insert_item_sql, (item['content'], ...)) item_id = cursor.lastrowid # 批量插入该条目的所有动态字段 dynamic_data = [(item_id, k, v) for k, v in item.get('extra_fields', {}).items()] if dynamic_data: cursor.executemany(insert_dynamic_sql, dynamic_data) cursor.execute('COMMIT') # 提交事务 except Exception as e: cursor.execute('ROLLBACK') # 出错则回滚 raise e

4. 实战应用：从零搭建一个个人阅读笔记库

理论说了这么多，我们来个实战。假设我想用这个框架，在Cursor编辑器里，让AI助手帮我建一个管理电子书阅读笔记的数据库。

4.1 环境准备与Skill安装

首先，确保你有Python 3.6+环境。然后，将flexible-database-design项目作为Skill安装到Cursor。

1. 克隆或下载项目到本地某个目录，比如~/projects/。
2. 在Cursor中配置Skill：根据项目README，对于Cursor，可以将整个项目目录复制到~/.cursor/skills/flexible-database-design/（全局可用）或者当前项目的.cursor/skills/flexible-database-design/目录下（仅本项目可用）。我推荐后者，因为更干净。

   # 在你的项目根目录下执行 mkdir -p .cursor/skills cp -r /path/to/flexible-database-design .cursor/skills/

3. （可选）注册Agent：有些平台需要在AGENTS.md等文件中声明。对于Cursor，通常复制过去后，在对话中提及相关关键词，AI就能识别并调用这个Skill。

4.2 与AI协作，定义数据模型

现在，在Cursor的聊天框中，我可以直接对AI说：“我想用flexible-database-design这个Skill，建立一个个人电子书阅读笔记库。”

AI（因为识别到了Skill）可能会这样引导我：

好的，我来帮你建立一个阅读笔记库。基于flexible-database-design框架，我们需要确定一些核心信息。

1. 你的笔记主要记录什么？是书籍摘录、读书感想，还是两者都有？（这会影响content字段的用途）
2. 你希望如何分类笔记？比如按书籍book、按主题topic，还是按阅读状态reading/finished？（这对应category字段）
3. 除了核心内容，你还想记录哪些信息？常见的比如：book_title（书名）、author（作者）、isbn、reading_progress（阅读进度，如50%）、rating（评分，1-5星）、tags（标签，多个）。请列出你需要的字段。

我回答：“content存我的摘录和感想。category就按book分类吧。我还需要记录：book_title、author、progress（百分比数字）、rating（整数）、tags（列表）。”

AI可以基于这个对话，在后台为我生成一个初始化的SQL脚本，或者直接调用scripts/flexible_db.py的初始化函数。它可能会告诉我数据库已经建好，默认路径是data/flexible.db。

4.3 开始归档第一条笔记

现在，我读完了《深入理解计算机系统》第一章，有一些摘录和感想。我可以手动使用命令行，也可以继续让AI帮我操作。

方式一：手动使用CLI

# 进入项目目录 cd my_reading_project # 归档一条笔记，通过 -e 参数以JSON格式传入动态字段 python3 .cursor/skills/flexible-database-design/scripts/archive_item.py \ -c "计算机系统是由硬件和系统软件组成的，它们共同协作以运行应用程序。理解这些底层原理是成为卓越程序员的关键。" \ -s "manual" \ -cate "book" \ -e '{"book_title": "深入理解计算机系统", "author": "Randal E. Bryant", "progress": 10, "rating": 5, "tags": ["CS", "底层", "经典"]}'

运行成功会返回新记录的ID（例如1）。

方式二：让AI助手执行我可以在Cursor里说：“帮我把这条笔记存进去：内容是‘计算机系统是由硬件...关键。’，书名是《深入理解计算机系统》，作者是Randal E. Bryant，进度10%，评分5星，标签CS、底层、经典。” AI会理解我的指令，并自动组装成类似上面的命令行去执行，或者直接调用Python函数。

4.4 查询与管理我的笔记库

过了一段时间，我积累了几十条笔记。我想看看所有关于“底层”的、评分在4星以上的笔记。

# 使用查询脚本，这里需要组合查询，可能需要更复杂的逻辑，脚本可能不支持直接AND多个动态字段条件。 # 可以先查询所有标签包含‘底层’的，再在结果中过滤评分。 # 或者，我们可以利用脚本的导出功能，再用其他工具处理。 python3 scripts/query_items.py --field "tags" --value "%底层%" --category "book" > notes.txt # 然后手动或写个小脚本过滤评分。

更高级的用法是直接使用FlexibleDatabase类写一个小Python脚本：

from scripts.flexible_db import FlexibleDatabase import json db = FlexibleDatabase() # 这是一个更复杂的查询示例，需要手动编写SQL conn = db.get_connection() cursor = conn.cursor() # 查询同时满足两个动态字段条件的记录 query = """ SELECT i.* FROM items i INNER JOIN dynamic_fields df1 ON i.id = df1.item_id AND df1.field_name = 'tags' AND df1.field_value LIKE '%底层%' INNER JOIN dynamic_fields df2 ON i.id = df2.item_id AND df2.field_name = 'rating' AND CAST(df2.field_value AS INTEGER) >= 4 WHERE i.category = 'book' AND i.is_deleted = 0 """ cursor.execute(query) results = cursor.fetchall() for row in results: print(f"ID: {row[0]}, 内容摘要: {row[1][:50]}...") # 可以再查询这条记录的所有动态字段 dynamic_fields = db.get_dynamic_fields(row[0]) print(f" 字段: {dynamic_fields}")

管理操作：

# 我发现ID为5的笔记书名写错了，更新它 python3 scripts/manage_item.py --update 5 -e '{"book_title": "深入理解计算机系统（原书第3版）"}' # 不小心加了一条重复笔记（ID为10），先软删除 python3 scripts/manage_item.py --delete 10 # 哦，删错了，恢复它 python3 scripts/manage_item.py --restore 10

4.5 进阶：接入LLM实现智能信息抽取

手动输入-e后面的JSON很麻烦。我们可以实现一个提取器。比如，用OpenAI API（需要安装openai库并设置API_KEY）。

创建一个文件my_extractor.py：

import openai import json import os openai.api_key = os.getenv("OPENAI_API_KEY") def reading_note_extractor(content: str) -> dict: """从一段阅读笔记内容中提取结构化信息""" prompt = f""" 你是一个阅读笔记助理。请从用户输入的文本中提取以下结构化信息： 1. 书名 (book_title)，如果未提及则输出null。 2. 作者 (author)，如果未提及则输出null。 3. 阅读进度 (progress)，是一个0-100的整数，如果未提及则输出null。 4. 评分 (rating)，是1-5的整数，如果未提及则输出null。 5. 标签 (tags)，是一个字符串列表，从内容中推断出最多3个关键词。 用户输入： {content} 请以JSON格式输出，只包含以下键：book_title, author, progress, rating, tags。 """ try: response = openai.ChatCompletion.create( model="gpt-3.5-turbo", messages=[{"role": "user", "content": prompt}], temperature=0.1 ) result = response.choices[0].message.content.strip() # 解析返回的JSON return json.loads(result) except Exception as e: print(f"LLM提取失败: {e}") return {} # 返回空字典 # 测试 if __name__ == "__main__": test_content = "今天读了《百年孤独》的开头，马尔克斯的笔法太震撼了。家族命运轮回的主题初现端倪。打算给5星。" print(reading_note_extractor(test_content)) # 期望输出: {"book_title": "百年孤独", "author": "马尔克斯", "progress": null, "rating": 5, "tags": ["魔幻现实主义", "家族史诗", "文学经典"]}

然后，在归档时使用这个提取器：

# 设置环境变量指定提取器 export FLEXIBLE_EXTRACTOR="my_extractor:reading_note_extractor" # 或者直接在命令行传入 python3 scripts/archive_item.py -c "今天读了《百年孤独》的开头..." -s "manual" --extractor my_extractor.reading_note_extractor

这样，你只需要粘贴一段文本，书名、作者、评分等信息就能自动填充，大大提升了归档效率。

5. 常见问题与排查技巧实录

在实际使用中，你肯定会遇到一些问题。下面是我在测试和使用过程中踩过的坑和解决方案。

5.1 数据库连接与路径问题

问题：运行脚本时报错sqlite3.OperationalError: unable to open database file。

• 排查1：检查路径权限。默认数据库文件会创建在data/flexible.db（相对于你运行脚本的目录）。确保当前用户对data目录有读写权限。可以用ls -la data/查看。
• 排查2：使用绝对路径。通过环境变量FLEXIBLE_DB_PATH指定一个绝对路径，避免相对路径的混淆。export FLEXIBLE_DB_PATH=/home/yourname/my_knowledge.db。
• 排查3：检查磁盘空间。虽然可能性小，但磁盘满了也会导致无法创建文件。

5.2 全文检索（FTS）不工作

问题：设置了FLEXIBLE_DB_FTS=1，但--search关键词查不到任何结果。

• 排查1：确认SQLite版本。在Python交互环境里执行import sqlite3; print(sqlite3.sqlite_version)，确保版本≥3.9.0。
• 排查2：FTS表是否已创建并同步？全文检索需要额外的虚拟表items_fts。这个表通常在数据库初始化时（第一次运行）根据环境变量决定是否创建。如果你先创建了数据库（没设置FTS），后来才设置环境变量，那么旧的数据库里没有FTS表。你需要手动创建并回填数据。项目文档提到了“需执行迁移回填FTS”，可以参考references/migrations/目录下的示例。
• 排查3：插入数据时是否同步了？检查archive_item.py的代码，在插入items表后，是否调用了sync_fts方法。只有通过项目提供的脚本或正确调用API插入的数据，才会被索引。
• 排查4：搜索语法。SQLite FTS5支持更复杂的查询，如keyword1 OR keyword2、"phrase search"。尝试一个简单的、肯定存在的单词。

5.3 动态字段查询结果不符合预期

问题：使用--field "tags" --value "python"查不到tags字段值为["python", "sqlite"]的记录。

• 原因：动态字段的值是以JSON字符串形式存储的。你存储的是'["python", "sqlite"]'这个字符串，直接用LIKE '%python%'去匹配一个JSON数组字符串，是能匹配到的。但如果你存储时没有序列化为JSON，或者查询时用了exact_match（精确匹配= "python"），就会失败。
• 解决：确保存储时使用json.dumps()。对于查询，如果知道是JSON数组，更可靠的方式是使用json_extract函数（如果SQLite编译时启用了JSON1扩展）。或者，在查询后，在Python层面对结果进行过滤。
• 更佳实践：对于像tags这种多值字段，一个更专业的做法是拆分成多行存储在dynamic_fields表中：(item_id=1, field_name='tag', field_value='python')和(item_id=1, field_name='tag', field_value='sqlite')。这样查询field_name='tag' AND field_value='python'就非常高效和准确。这需要你在设计抽取器或输入数据时做预处理。

5.4 性能优化建议

当你的笔记库增长到几千上万条时，可能会感觉查询变慢。

• 索引是王道：确保idx_dynamic_cat_field索引存在。你可以用SQLite命令行工具检查：.indexes。
• 避免SELECT *：在自定义查询时，只选择你需要的列，特别是不要轻易查询dynamic_fields的全部内容，因为每条记录可能有很多动态字段，数据量会很大。
• 分页查询：务必使用LIMIT和OFFSET，不要一次性拉取所有数据。对于深度分页（大的OFFSET），考虑基于created_at或id的范围查询。
• 定期清理：如果使用了软删除，定期（如每月）将is_deleted=1且updated_at在很久以前的记录真正删除（DELETE），并执行VACUUM命令来整理数据库文件碎片，回收空间。注意，VACUUM会锁库，请在非高峰时段进行。

5.5 与现有项目集成

问题：我想在我已有的Python项目中使用这个柔性数据库，而不是通过CLI。

• 解决：非常简单。将scripts/flexible_db.py和references/schema_template.sql复制到你的项目里。然后像导入普通模块一样使用：

  from flexible_db import FlexibleDatabase db = FlexibleDatabase(db_path='your_custom.db') item_id = db.insert_item("我的内容", source="web", category="idea") db.insert_dynamic_field(item_id, "url", "https://example.com") # ... 使用其他查询、管理方法

  你可以根据需要封装自己的业务类，继承或组合FlexibleDatabase类。

这套flexible-database-design工具，其价值远不止于它提供的这几个脚本。它更像是一个“种子”，给你展示了一种在关系型数据库中实现灵活数据存储的可行模式，以及如何将这种模式与AI助手的工作流无缝衔接。你可以基于它，根据自己的业务逻辑进行裁剪和扩展，比如增加用户权限、数据版本管理、更复杂的关联查询视图等等。最重要的是，它让你从“我该设计什么表结构”的纠结中解放出来，快速启动你的数据收集项目，把精力集中在信息和知识本身。