用途
本技能用于操作 StarTrail-org/LEANN，在本地完成文档索引与语义检索，包括检查检出版本、配置嵌入与后端、构建或增量更新索引，以及执行检索查询。
主要能力
- 定位并核对指定检出版本：可从 jeo-skills 仓库根目录运行
python3 .agent-skills/leann/scripts/preflight.py --repo /absolute/upstream --json，或从已安装技能根目录调用scripts/preflight.py。省略--repo时仅做清单检查。该辅助脚本比较选定固定文件的哈希，不证明 Git HEAD、整个检出内容、已安装依赖或运行时就绪状态。 - 明确系统模型：LEANN 是使用基于图的选择性重计算来减少存储嵌入数据的向量索引；其图属于索引/搜索优化，不是语义知识图谱或持久代码架构图，后者应路由至 mex 或 graphify。
- 运行前规划本地索引：确认源路径、文件类型与排除项、索引目录、所选后端、嵌入模式与模型，以及计划采用增量更新还是全量重建；检查存储、内存、原生依赖与数据敏感性。
- 执行经批准的效果操作：在获取批准后，查看检出自身
leann --help与leann <command> --help（命令选项可能变化），先运行小规模代表性索引与检索，再验证预期源覆盖与检索结果。不能仅凭预检声称运行时已就绪。
使用方式
仅检查（使用绝对路径、非符号链接的上游检出）：
python3 .agent-skills/leann/scripts/preflight.py --repo /work/LEANN --json
仅在批准后，于已检查的 LEANN 环境中执行：
uv venv
source .venv/bin/activate
uv pip install leann
leann build handbook --docs ./docs
leann search handbook "how does the sync path work?" --top-k 5
适用场景
适用于需要在本机构建、增量更新或查询 LEANN 向量索引，并希望先做版本核对、配置规划与风险确认的场景。
限制与注意事项
- 安装软件包或下载模型、摄入私有/受监管/第三方源材料、调用付费或远程嵌入 API、启动服务或绑定到回环之外、创建/更新/重建/删除索引、启用读取账户或工作区数据的集成，均须先获批准。不得将密钥放入命令历史。全量重建（
--force）与默认增量构建不同。 - 将索引视为数据处理而非无害查询；构建前审查目标位置与嵌入端点。对已验证存在的索引优先使用默认增量路径；仅在获批并有恢复计划时使用
--force。 - 按固定说明重查后端与平台前提；LEANN 可选后端具有不同原生/GPU 要求，不能从通用 Python 包推断支持。
- 上游存储或检索百分比为工作负载特定指标，不应作为用户语料的保证。
- 区分离线检查失败、源固定不匹配、依赖/安装失败与运行时/检索失败等不同状态。
- 辅助脚本支持 POSIX Linux/macOS/WSL2 上的 Python 3.10+，在无法进行安全目录遍历时（包括不支持的原生 Windows）会失败关闭（fail closed）。