indexing-rules

name	indexing-rules
description	索引条目格式与版本标注规范。凡生成/更新 indexes/ 下索引（indexes/knowledge/、indexes/repos/）条目时须遵守。维护知识库或外部仓库索引时自动参考。

索引与版本标注规范

indexes/ 下所有索引（indexes/knowledge/、indexes/repos/）共享同一套条目格式与版本标注。本规范是唯一权威来源。

索引条目格式

按主题组织，每条索引格式：

- **<文件路径>** — 一句话概要 [版本]
  - 关键词：tag1, tag2, tag3

• 每个条目必须包含文件路径、适用版本和至少 3 个关键词
• 版本标注必须出现在条目的首行（[版本] 格式）
• 不写易漂移的精确计数（如"当前条目：N 条"）——计数随内容频繁变化、手工维护必过时，用内容范围/关键词描述代替

版本标注规则

Minecraft 机制在不同版本间可能存在显著差异，索引必须标注适用版本：

• 从文件名推断：如 2024-06__1-21_raid → [1.21]，1.16.2+.xlsx → [1.16.2+]
• 从文件内容提取：读文件前 20 行，查找版本号（如 "1.16.4"、"1.18+"、"1.20.5+"）
• 无明确版本：标注 [通用]（基础机制，跨版本稳定）或 [待确认]
• 跨版本：用 - 连接，如 [1.16-1.21]
• 仅在某版本后有效：用 +，如 [1.20.5+]
• 旧版本/已过时：标注 [旧] 并注明版本

索引时间戳与更新策略

• 索引文件的「生成时间 / 最近更新 / 更新时间 / 上游 commit」是刷新判断依据（Agent 据此判断缓存/索引是否需要重新生成），必须保留，并在内容实质变更时更新
• 例外——高频无意义变动区（如 _uncategorized.csv）：索引中只保留静态占位描述（类别、用途、写入规则），不追踪其具体词条，其词条变动不触发索引更新、不更新时间戳
• 索引更新（含时间戳）仅发生在：新增稳定的知识文件/类别，或既有条目的描述/关键词实质变化时