制作按关键词和含义搜索本地文档的CLI

## 只用一种运行时，并为每类命令分清职责 选择一套受支持的运行时和包管理器，作为规范的开发路径。不要仅因替代运行时或安装命令看似兼容，就将其混用。 明确区分各类命令的职责： - 集合命令管理已建立索引的根目录及其配置； - 上下文命令将搜索指导附加到路径； - 获取命令返回已知文档； - 搜索命令对候选文档进行排名； - 维护命令检查或刷新索引； - 服务命令向其他进程提供相同能力。 当已安装的命令包装器负责调用编译后的应用程序代码时，应保留该包装器。使用已记录的编译器工作流构建源代码；如果原生扩展依赖现有布局，不要用单个编译后的可执行文件替换包装器。 ## 记录每个集合的设置，并区分排除与移除 用唯一名称、源根目录、文件掩码、纳入状态和可选的更新前钩子表示每个集合。 支持添加、列出、检查、重命名、纳入、排除和移除集合。区分移除与排除：移除会取消集合注册，而排除只会在未限定范围的查询中略过该集合。 允许列出整个集合或某个路径前缀下的文件。接口支持时，同时接受普通集合路径和工具的虚拟集合URI。 将添加、移除、重命名、钩子变更、纳入状态变更和索引刷新视为状态变更。需要用户批准时，在执行前给出准确的命令及预期影响。 ## 按路径附加搜索说明（上下文），与文档内容分开 将人工编写的上下文与文档内容分开存储，使排名指导可以在不重写源文件的情况下演进。 允许在以下位置设置上下文： - 集合内检测到的当前目录； - 指定的子路径； - 虚拟集合路径； - 为所有集合提供通用指导的全局根目录。 提供用于列出上下文、检测缺少上下文的路径以及移除过时上下文的命令。在保留全局指导的同时，应用相关且范围最具体的上下文。 不要混淆上下文元数据与已建立索引的文档文本。使作用范围可见，避免局部注释在无提示的情况下影响无关集合。 ## 为每个文档分配短ID，并限制返回的内容量 为每个文档分配一个由其内容哈希前6个字符派生的短标识。在搜索结果中显示该标识，并接受带或不带前导标记的形式。 支持按路径或标识获取文档、可选的起始行和行数，以及通过glob或逗号分隔列表进行批量获取。 明确限制获取范围： - 设置每个文件的最大行数； - 设置最大字节数，并记录10 KB等默认值； - 对过大的文件予以跳过，不在未告知的情况下返回部分内容； - 默认包含行号，同时允许调用方将其关闭； - 仅在明确请求时返回磁盘上的完整路径。 ## 按查询选择搜索方式，默认使用混合搜索 提供三条不同的搜索路径： - 使用BM25等全文排名且不使用语言模型的关键词搜索； - 使用本地嵌入且不进行重排名的向量相似度搜索； - 使用查询扩展和重排名的扩展混合查询搜索，作为质量最高的默认路径。 使用倒数排名融合（Reciprocal Rank Fusion）合并各自独立排名的结果集。充分展示原始分数和搜索模式，以便诊断异常排序。 一般用途优先选择混合查询路径。需要精确术语时选择关键词搜索，目标是语义相似度时选择向量搜索，更看重速度而非最终排序质量时选择不重排名的选项。 ## 允许选择要搜索的集合和输出格式，且不因显示方式改变结果 允许调用方重复指定集合筛选器，只搜索多个具名集合并排除其他所有集合。支持结果数量、全部结果模式、最低分数、完整内容模式，以及用于提高排名针对性的意图说明。 将显示方式与数据传输分开。除了易读的命令行格式，还应提供结构化的JSON、CSV、Markdown、XML和文件列表输出。旧版格式标志只作为一个规范格式选项的别名保留。 进行批量获取时，将行数限制、字节限制和行号控制与搜索排名分别提供。不要让呈现选项改变被选中的文档。 ## 构建搜索索引，并把文档切成大小可预期的分块 全文索引使用持久的本地数据库，语义相似度搜索使用兼容的向量扩展。通过已配置的本地模型运行嵌入、重排名和查询扩展。 采用智能文档分块，以每个分块900个token、15%的重叠为目标。可行时优先以Markdown标题作为边界。 为受支持的代码文件提供感知抽象语法树的策略，使分块与函数、类和导入的边界对齐。通过明确的自动策略选择该方式。将正则表达式分块保留为默认方式，并始终将其用于Markdown和未知文件类型。 将索引构建、嵌入生成和查询时排名保持为不同阶段，以便无需重建全部内容即可诊断故障。 ## 调整排名前，先检查索引和模型的状态 提供状态输出，在不改变状态的情况下展示集合与索引的健康状况。添加诊断命令，用于检查配置、索引、模型和设备问题。 使用带版本的测试夹具文件评测搜索质量。记录查询、预期相关文档、搜索模式、排名指标、模型配置和索引版本，以确保比较可复现。 在更改排名权重、模型或设备设置前先进行诊断。模型缺失、索引陈旧、向量扩展不兼容或设备不可用，本身并不能证明排名算法有误。 ## 只在被要求时，把工具作为本地或HTTP服务运行 为本地进程集成提供标准输入/输出服务，并为远程客户端提供可选的HTTP服务。使用8181等已记录的默认端口，同时允许明确覆盖。 支持用于调试的前台运行方式和适合长期运行的后台守护进程模式。提供与之对应的停止命令，并且该命令只针对受管理的守护进程。 将服务传输方式与搜索语义分开。命令行接口与服务接口应共享集合、上下文、获取、排名和输出规则。 不要隐式启动后台服务。服务启动后，应报告端点、进程模式、配置来源和关闭方式。 ## 把修改索引的命令交给用户执行，不破坏已安装的包装器 绝不自动添加集合、生成嵌入或刷新索引。绝不直接修改底层搜索数据库。 请求的工作流需要上述变更时，给出由用户执行的准确命令，并说明预期文件、耗时和资源使用情况。在不扩大权限的前提下，继续提供只读搜索和获取功能。 不要运行会覆盖已安装的shell包装器或破坏原生向量扩展的编译模式。不要替换有意从分发目录启动编译后JavaScript的包装器。 将更新前钩子视为可执行配置。在检查时显示这些钩子，并且只在明确请求的索引更新过程中运行。 ## 补充回归测试，并附上变更日志进行发布 将自动化测试放在指定的测试树中，并通过受支持的运行时执行已记录的完整测试套件。为集合状态、获取限制、排名模式、分块边界和服务生命周期添加范围明确的回归测试。 使用规范的发布工作流，而不是手动拼装发布： 1. 每次进行变更时，在未发布部分添加变更日志条目； 2. 发布时，将该部分转换为带日期的版本； 3. 使用项目要求的引用格式注明外部贡献者； 4. 汇总目标版本系列中的发布说明； 5. 发布前运行发布钩子并完成验证。 报告已变更的行为、索引或模式兼容性、已运行的测试、对基准结果的影响、迁移需求，以及留给用户执行的任何状态变更命令。