fix:更新项目的规则文件适配OpenCode

.gitignore

@@ -4,11 +4,9 @@ __pycache__/
 *.py[cod]
 *$py.class
 
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
+# Virtual environments
+.venv/
+venv/
 env/
 build/
 develop-eggs/

AGENTS.md

@@ -0,0 +1,190 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 项目概述
+
+路桥数据治理与知识库入库脚本项目，用于将标准规范、施工方案等文档向量化并存入 Milvus/MinIO/MySQL。
+
+**核心数据类型**：
+- `base_*`：编制依据（标准规范）
+- `plan_*`：施工方案
+- `status_*`：时效性状态
+- `entity_*`：实体抽取
+
+## 常用命令
+
+### 环境安装
+
+```bash
+# 创建虚拟环境（默认在项目根目录 .venv）
+uv venv
+
+# 安装依赖（使用清华镜像）
+uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple
+```
+
+### 虚拟环境
+
+项目使用 `uv` 管理依赖，虚拟环境位于 `.venv/`。
+
+**激活虚拟环境**：
+```bash
+# Windows PowerShell
+.venv\Scripts\Activate.ps1
+
+# Windows CMD
+.venv\Scripts\activate.bat
+
+# Linux/macOS
+source .venv/bin/activate
+```
+
+**运行方式**：
+- 推荐：直接使用 `uv run`（自动在虚拟环境中执行）
+  ```bash
+  uv run -m src.app.scripts.base_info_json_generation
+  ```
+- 或：激活虚拟环境后直接运行
+  ```bash
+  # 先激活虚拟环境
+  # 再运行脚本
+  ```
+
+### 运行脚本
+
+```bash
+# 运行任意脚本（示例）
+uv run -m src.app.scripts.base_info_json_generation
+uv run -m src.app.scripts.base_in_collection
+uv run -m src.app.scripts.status_excel_info_json
+```
+
+**重要**：多数脚本是"一次性批处理"，路径参数（`EXCEL_FILE`、`ROOT_FOLDER` 等）直接写在脚本顶部，运行前需改为本地路径。
+
+## 项目架构
+
+### 目录结构
+
+```
+src/app/
+├── config/           # 配置与客户端初始化
+│   ├── setting.py    # .env 配置加载（MinIO/Milvus/MySQL/Embedding）
+│   ├── minio_client.py   # MinIO 客户端（单例）
+│   ├── milvus_client.py  # Milvus 客户端（LRU缓存）
+│   ├── embeddings.py     # MetaXEmbeddings（requests-based，非 OpenAI）
+│   └── database.py       # SQLAlchemy 异步引擎
+├── models/           # 数据库模型
+│   └── standard_base_info.py  # 施工标准规范表模型
+└── scripts/          # 数据处理脚本
+    ├── base_*        # 编制依据处理流程
+    ├── plan_*        # 施工方案处理流程
+    ├── status_*      # 时效性状态处理
+    ├── entity_*      # 实体抽取与入库
+    └── tool/         # 辅助工具（时效性查询、去重等）
+```
+
+### 配置管理
+
+所有服务配置通过 `.env` 文件管理，由 `setting.py` 的 `Settings` 类加载：
+
+| 服务 | 关键配置项 |
+|------|------------|
+| MinIO | `MINIO_ENDPOINT`, `MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY`, `MINIO_BUCKET_NAME` |
+| Milvus | `MILVUS_HOST`, `MILVUS_PORT`, `MILVUS_DB`, `MILVUS_USER`, `MILVUS_PASSWORD` |
+| MySQL | `DATABASE_URL` (async: `mysql+aiomysql://...`) |
+| Embedding | `EMBEDDING_BASE_URL`, `EMBEDDING_MODEL`, `EMBEDDING_API_KEY` |
+
+### 数据处理流程
+
+**编制依据 (base_* 系列)**：
+1. `base_count.py` → Excel 与目录编号对比
+2. `base_check.py` → 目录结构/命名校验
+3. `base_info_json_generation.py` → 生成 JSON（含 MD 切分 parent/children）
+4. `base_in_minio.py` → 上传文件到 MinIO
+5. `base_info_in_database.py` → 写入 MySQL
+6. `base_collections_create.py` → 创建 Milvus Collection（含 BM25 + 中文分词）
+7. `base_in_collection.py` → 向量化并写入 Milvus
+
+**施工方案 (plan_* 系列)**：流程同上，Collection 名不同（`t_rag_kng_construction_plan_*`）。
+
+**时效性状态 (status_* 系列)**：Excel → JSON → MySQL → Milvus 状态检索集合。
+
+**实体 (entity_* 系列)**：从文档抽取实体并向量化导入 Milvus 实体集合。
+
+### Markdown 切分逻辑
+
+文档切分在 `base_info_json_generation.py` 中实现：
+
+- **parent**：按 `#` 一级标题切分，超长段（>6000字符）再切片，共享 `parent_id`
+- **children**：按中文句号 `。` 切分，保留标题上下文，标题本身不生成子表记录
+- `parent_id`：由 `doc_name|parent_seq|h1_title` SHA1 生成，保证稳定
+- **Markdown 表格**：整体保留，不按句号切分（避免破坏表结构）
+- **HTML 表格**：自动转换为 Markdown 表格格式
+
+### Milvus Collection Schema
+
+Collection（父表/子表结构相同）包含以下字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `pk` | INT64 | 主键，auto_id |
+| `text` | VARCHAR(65535) | 文本内容，**enable_analyzer=True, analyzer_params={"type": "chinese"}** |
+| `dense` | FLOAT_VECTOR(4096) | 密集向量（语义检索） |
+| `sparse` | SPARSE_FLOAT_VECTOR | 稀疏向量（BM25 函数生成） |
+| `document_id` | VARCHAR(128) | 文档 ID |
+| `parent_id` | VARCHAR(128) | 父节点 ID |
+| `index` | INT64 | 索引序号 |
+| `tag_list` | VARCHAR(2048) | 标签 |
+| `permission` | JSON | 权限 |
+| `metadata` | JSON | 元数据（chinese_name, standard_number, file_url 等） |
+| `is_deleted` | BOOL | 删除标志 |
+| `created_by/updated_by` | VARCHAR(128) | 创建人/修改人 |
+| `created_time/updated_time` | INT64 | 创建/修改时间戳 |
+
+**BM25 + 中文分词配置**（创建 Collection 时必须）：
+```python
+schema.add_field(
+    "text",
+    DataType.VARCHAR,
+    max_length=65535,
+    enable_analyzer=True,
+    analyzer_params={"type": "chinese"},  # 关键：中文分词
+)
+schema.add_function(
+    Function(
+        name="bm25_fn",
+        input_field_names=["text"],
+        output_field_names=["sparse"],
+        function_type=FunctionType.BM25,
+    )
+)
+```
+
+### 入库脚本运行时特性
+
+`base_in_collection.py` / `plan_info_in_collection.py` 具有以下特性：
+
+- **分批插入**：避免 GRPC 64MB 消息大小限制（默认 50 行/批）
+- **重试机制**：失败自动重试 3 次，递增延迟
+- **断点续传**：Ctrl+C 暂停时保存进度到 JSON，下次运行可恢复
+- **VARCHAR 保护**：超长文本按 UTF-8 字节切分，不截断丢弃
+- **Embedding token 保护**：文本切分同时满足 Milvus VARCHAR(65535) 和 embedding 输入限制（约 12KB）
+- **幂等写入**：每个文档先按 `document_id` 清理旧数据再写入
+
+## 开发注意事项
+
+- **脚本路径配置**：多数脚本顶部有 `EXCEL_FILE`、`ROOT_FOLDER` 等路径常量，运行前需改为本地路径
+- **base/plan 区分**：`base_*` 与 `plan_*` 脚本对应不同数据类型，Collection 名不同，不要混用
+- **中文分词器**：创建 Milvus Collection 时必须配置 `analyzer_params={"type": "chinese"}`，否则 BM25 检索效果差
+- **向量维度**：默认 4096 维，由 `EMBEDDING_MODEL`（通常是 Qwen3-Embedding-8B）决定
+- **Embedding 客户端**：使用 `MetaXEmbeddings`（`embeddings.py`），基于 requests，非 langchain-openai
+- **Embedding 批量请求**：默认 max_batch_size=16，有重试机制
+- **创建 Collection**：使用 `base_collections_create.py` / `t_kngs_construction_plan_collections_create.py`，确保 schema 正确
+
+### 常见问题
+
+1. **脚本报路径不存在**：检查脚本顶部路径常量是否为本地真实路径
+2. **Milvus 插入失败/字段不匹配**：确认 Collection schema 与写入字段一致；必要时先执行 `*_collections_create.py` 重建集合
+3. **Embedding 报 context length 超限**：入库脚本已内置文本切分保护（约 12KB），检查是否使用正确脚本版本
+4. **BM25 搜索效果差**：确认 Collection 创建时配置了中文分词器

CLAUDE.md

@@ -4,29 +4,64 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## 项目概述
 
-路桥数据治理与知识库入库脚本项目，用于将标准规范、施工方案等文档数据向量化并存入 Milvus/MinIO/MySQL。
+路桥数据治理与知识库入库脚本项目，用于将标准规范、施工方案等文档向量化并存入 Milvus/MinIO/MySQL。
+
+**核心数据类型**：
+- `base_*`：编制依据（标准规范）
+- `plan_*`：施工方案
+- `status_*`：时效性状态
+- `entity_*`：实体抽取
 
 ## 常用命令
 
 ### 环境安装
 
 ```bash
-# 创建虚拟环境
+# 创建虚拟环境（默认在项目根目录 .venv）
 uv venv
 
 # 安装依赖（使用清华镜像）
 uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple
 ```
 
+### 虚拟环境
+
+项目使用 `uv` 管理依赖，虚拟环境位于 `.venv/`。
+
+**激活虚拟环境**：
+```bash
+# Windows PowerShell
+.venv\Scripts\Activate.ps1
+
+# Windows CMD
+.venv\Scripts\activate.bat
+
+# Linux/macOS
+source .venv/bin/activate
+```
+
+**运行方式**：
+- 推荐：直接使用 `uv run`（自动在虚拟环境中执行）
+  ```bash
+  uv run -m src.app.scripts.base_info_json_generation
+  ```
+- 或：激活虚拟环境后直接运行
+  ```bash
+  # 先激活虚拟环境
+  # 再运行脚本
+  ```
+
 ### 运行脚本
 
 ```bash
 # 运行任意脚本（示例）
-uv run -m src.app.scripts.statu_to_milvus
 uv run -m src.app.scripts.base_info_json_generation
 uv run -m src.app.scripts.base_in_collection
+uv run -m src.app.scripts.status_excel_info_json
 ```
 
+**重要**：多数脚本是"一次性批处理"，路径参数（`EXCEL_FILE`、`ROOT_FOLDER` 等）直接写在脚本顶部，运行前需改为本地路径。
+
 ## 项目架构
 
 ### 目录结构
@@ -37,62 +72,85 @@ src/app/
 │   ├── setting.py    # .env 配置加载（MinIO/Milvus/MySQL/Embedding）
 │   ├── minio_client.py   # MinIO 客户端（单例）
 │   ├── milvus_client.py  # Milvus 客户端（LRU缓存）
-│   ├── embeddings.py     # OpenAI Embeddings 客户端
+│   ├── embeddings.py     # MetaXEmbeddings（requests-based，非 OpenAI）
 │   └── database.py       # SQLAlchemy 异步引擎
 ├── models/           # 数据库模型
 │   └── standard_base_info.py  # 施工标准规范表模型
 └── scripts/          # 数据处理脚本
     ├── base_*        # 编制依据处理流程
-    └── plan_*        # 施工方案处理流程
+    ├── plan_*        # 施工方案处理流程
+    ├── status_*      # 时效性状态处理
+    ├── entity_*      # 实体抽取与入库
+    └── tool/         # 辅助工具（时效性查询、去重等）
 ```
 
 ### 配置管理
 
-所有服务配置通过 [.env](.env) 文件管理，由 `setting.py` 的 `Settings` 类加载：
+所有服务配置通过 `.env` 文件管理，由 `setting.py` 的 `Settings` 类加载：
 
 | 服务 | 关键配置项 |
 |------|------------|
-| MinIO | `MINIO_ENDPOINT`, `MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY` |
-| Milvus | `MILVUS_HOST`, `MILVUS_PORT`, `MILVUS_DB` |
+| MinIO | `MINIO_ENDPOINT`, `MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY`, `MINIO_BUCKET_NAME` |
+| Milvus | `MILVUS_HOST`, `MILVUS_PORT`, `MILVUS_DB`, `MILVUS_USER`, `MILVUS_PASSWORD` |
 | MySQL | `DATABASE_URL` (async: `mysql+aiomysql://...`) |
-| Embedding | `EMBEDDING_BASE_URL`, `EMBEDDING_MODEL` |
+| Embedding | `EMBEDDING_BASE_URL`, `EMBEDDING_MODEL`, `EMBEDDING_API_KEY` |
 
 ### 数据处理流程
 
 **编制依据 (base_* 系列)**：
-1. `base_count.py` → 检查 Excel ID 与目录匹配
-2. `base_check.py` → 校验目录结构/命名一致性
+1. `base_count.py` → Excel 与目录编号对比
+2. `base_check.py` → 目录结构/命名校验
 3. `base_info_json_generation.py` → 生成 JSON（含 MD 切分 parent/children）
 4. `base_in_minio.py` → 上传文件到 MinIO
 5. `base_info_in_database.py` → 写入 MySQL
-6. `base_create_collection.py` → 创建 Milvus Collection（含 BM25 function）
+6. `base_collections_create.py` → 创建 Milvus Collection（含 BM25 + 中文分词）
 7. `base_in_collection.py` → 向量化并写入 Milvus
 
-**施工方案 (plan_* 系列)**：流程同上，Collection 名不同。
+**施工方案 (plan_* 系列)**：流程同上，Collection 名不同（`t_rag_kng_construction_plan_*`）。
+
+**时效性状态 (status_* 系列)**：Excel → JSON → MySQL → Milvus 状态检索集合。
+
+**实体 (entity_* 系列)**：从文档抽取实体并向量化导入 Milvus 实体集合。
 
 ### Markdown 切分逻辑
 
 文档切分在 `base_info_json_generation.py` 中实现：
 
 - **parent**：按 `#` 一级标题切分，超长段（>6000字符）再切片，共享 `parent_id`
-- **children**：在 parent 内按空行切分，记录 `hierarchy`（标题路径）
+- **children**：按中文句号 `。` 切分，保留标题上下文，标题本身不生成子表记录
 - `parent_id`：由 `doc_name|parent_seq|h1_title` SHA1 生成，保证稳定
+- **Markdown 表格**：整体保留，不按句号切分（避免破坏表结构）
+- **HTML 表格**：自动转换为 Markdown 表格格式
 
 ### Milvus Collection Schema
 
-Collection 包含以下字段：
+Collection（父表/子表结构相同）包含以下字段：
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `text` | VARCHAR(65535) | 文本内容，enable_analyzer=True |
-| `dense` | FLOAT_VECTOR | 密集向量（语义检索） |
+| `pk` | INT64 | 主键，auto_id |
+| `text` | VARCHAR(65535) | 文本内容，**enable_analyzer=True, analyzer_params={"type": "chinese"}** |
+| `dense` | FLOAT_VECTOR(4096) | 密集向量（语义检索） |
 | `sparse` | SPARSE_FLOAT_VECTOR | 稀疏向量（BM25 函数生成） |
-| `document_id` | VARCHAR(256) | 文档 ID |
-| `parent_id` | VARCHAR(256) | 父节点 ID |
-| `metadata` | JSON | 元数据（chinese_name, standard_number 等） |
-
-BM25 函数配置：
+| `document_id` | VARCHAR(128) | 文档 ID |
+| `parent_id` | VARCHAR(128) | 父节点 ID |
+| `index` | INT64 | 索引序号 |
+| `tag_list` | VARCHAR(2048) | 标签 |
+| `permission` | JSON | 权限 |
+| `metadata` | JSON | 元数据（chinese_name, standard_number, file_url 等） |
+| `is_deleted` | BOOL | 删除标志 |
+| `created_by/updated_by` | VARCHAR(128) | 创建人/修改人 |
+| `created_time/updated_time` | INT64 | 创建/修改时间戳 |
+
+**BM25 + 中文分词配置**（创建 Collection 时必须）：
 ```python
+schema.add_field(
+    "text",
+    DataType.VARCHAR,
+    max_length=65535,
+    enable_analyzer=True,
+    analyzer_params={"type": "chinese"},  # 关键：中文分词
+)
 schema.add_function(
     Function(
         name="bm25_fn",
@@ -103,9 +161,30 @@ schema.add_function(
 )
 ```
 
+### 入库脚本运行时特性
+
+`base_in_collection.py` / `plan_info_in_collection.py` 具有以下特性：
+
+- **分批插入**：避免 GRPC 64MB 消息大小限制（默认 50 行/批）
+- **重试机制**：失败自动重试 3 次，递增延迟
+- **断点续传**：Ctrl+C 暂停时保存进度到 JSON，下次运行可恢复
+- **VARCHAR 保护**：超长文本按 UTF-8 字节切分，不截断丢弃
+- **Embedding token 保护**：文本切分同时满足 Milvus VARCHAR(65535) 和 embedding 输入限制（约 12KB）
+- **幂等写入**：每个文档先按 `document_id` 清理旧数据再写入
+
 ## 开发注意事项
 
-- **脚本路径配置**：大多数脚本顶部有 `EXCEL_FILE`、`ROOT_FOLDER` 等路径常量，运行前需改为本地路径
+- **脚本路径配置**：多数脚本顶部有 `EXCEL_FILE`、`ROOT_FOLDER` 等路径常量，运行前需改为本地路径
 - **base/plan 区分**：`base_*` 与 `plan_*` 脚本对应不同数据类型，Collection 名不同，不要混用
-- **Milvus 动态字段**：当前 schema 未开启动态字段，写入字段必须与 collection 定义完全一致
-- **向量维度**：默认 4096 维，由 `EMBEDDING_MODEL`（Qwen3-Embedding-8B）决定
+- **中文分词器**：创建 Milvus Collection 时必须配置 `analyzer_params={"type": "chinese"}`，否则 BM25 检索效果差
+- **向量维度**：默认 4096 维，由 `EMBEDDING_MODEL`（通常是 Qwen3-Embedding-8B）决定
+- **Embedding 客户端**：使用 `MetaXEmbeddings`（`embeddings.py`），基于 requests，非 langchain-openai
+- **Embedding 批量请求**：默认 max_batch_size=16，有重试机制
+- **创建 Collection**：使用 `base_collections_create.py` / `t_kngs_construction_plan_collections_create.py`，确保 schema 正确
+
+### 常见问题
+
+1. **脚本报路径不存在**：检查脚本顶部路径常量是否为本地真实路径
+2. **Milvus 插入失败/字段不匹配**：确认 Collection schema 与写入字段一致；必要时先执行 `*_collections_create.py` 重建集合
+3. **Embedding 报 context length 超限**：入库脚本已内置文本切分保护（约 12KB），检查是否使用正确脚本版本
+4. **BM25 搜索效果差**：确认 Collection 创建时配置了中文分词器