[RFC] Skill 整包索引与按技能返回搜索结果

[yeshion23333]

状态：草案 · 范围：Skill 添加、更新、重建索引和检索
现状依据：9eeeda4e1

整个 Skill 包参与索引；专用 skills/find 每个 Skill 返回包内得分最高的一条命中。

例如，SKILL.md 只介绍“管理数据服务”，reference/backup.md 才写了“跨地域备份恢复”。改造后，搜索这项能力可以找到该 Skill，结果直接指向 backup.md。

1. 前后变化

L0 是目录简介，L1 是目录概览，L2 是具体文件；索引表示内容可参与搜索。

项目	改造前	改造后
主目录 L0	由名称、描述、标签、允许使用的工具生成；建立索引	生成方式不变，保留元数据格式
主目录 L1	由名称、描述和 SKILL.md 正文生成；正常添加时不索引	生成方式不变，新增索引；不混入附加文件内容
SKILL.md	正常添加时只保存	建立 L2 索引
子目录	只保存目录结构	按 resource 规则生成并索引 L0、L1
附加文件	只保存	按 resource 规则建立 L2 索引
专用 skills/find	正常添加后主要靠主目录 L0 匹配	整包内容参与匹配，每个 Skill 保留最高分命中
专用 skills/find 返回数量	缺少整包命中的统一合并规则	limit=10 表示最多 10 个不同 Skill
返回内容	通用检索字段表示命中内容；专用 skills/find 的 uri 转为根目录	两者均返回实际命中；专用接口用已有 root_uri 表示所属 Skill
重建索引	覆盖主目录 L0、L1 和 SKILL.md，不遍历附加目录；L0 可能变成纯描述	覆盖整包，与添加规则一致，主目录 L0 保持元数据格式

2. 整包处理规则

data-service/
├── .abstract.md       L0：原 Skill 生成规则 + 索引
├── .overview.md       L1：原 Skill 生成规则 + 索引
├── SKILL.md           L2：索引
└── reference/
    ├── .abstract.md   L0：resource 生成规则 + 索引
    ├── .overview.md   L1：resource 生成规则 + 索引
    └── backup.md      L2：索引

复用 resource 的目录遍历、文件处理和索引能力。先处理文件，再生成各级子目录摘要；普通文件建立 L2 索引。包内内容属于原 Skill，保持 skills 路径和 context_type="skill"。

文件类型	L2 用什么内容参与搜索
文本、代码	按已有配置使用正文或摘要，沿用长度上限
图片	模型支持时使用图片和描述；仅支持文本时使用描述
音频、视频	使用媒体理解生成的文字摘要；无法获得时沿用文件名回退规则
不支持的文件	有可用摘要则使用，否则跳过并记录原因

处理边界：

• 附加文件变更沿用父目录刷新，逐级更新子目录摘要，到 Skill 主目录前停止；SKILL.md 变更时按 Skill 规则更新主目录摘要。
• 隐藏项、特殊文件、媒体开关和大目录概览采样沿用 resource 规则；首次遍历仍覆盖符合条件的全部文件。L0、L1 摘要文件不重复作为 L2 索引。
• 包内另一个 SKILL.md 作为普通附件处理；处理范围限于包内文件。
• 权限、隐私提取和文件读取规则不变；更新期间的配置写入协调见第 4 节。附加文件会产生模型处理和索引成本；媒体理解受现有配置控制，文件名回退仅用于名称匹配。

3. 检索与返回

专用 skills/find：范围和权限过滤 → 查找包内内容 → 按完整 Skill 根目录 URI 合并 → 每包取最高分 → 排序并取前 limit 个。

专用 skills/find 沿用原有的向量相似度得分。每包以最高分排序，同分按 URI 稳定排序。候选结果中不同 Skill 不足时继续查找，直到数量足够或合格候选耗尽。若处理上限导致提前结束，报告结果不完整。翻页按独立索引记录判断进度，同目录的 L0、L1 分别计数。

例如，A 包命中两个文件，得分为 0.91、0.84；B 包命中概览，得分为 0.88。最终返回 A 的文件（0.91）和 B 的概览（0.88），A 只占一个位置。不同空间的同名 Skill 分别计数，合并后统一排序和截取。

返回字段

uri、level、score、abstract 全部来自同一条最高分命中：

字段	返回内容
uri	L0 指向该目录的 .abstract.md；L1 指向 .overview.md；L2 指向具体文件
level	命中内容的层级：0、1 或 2
score	命中的最终得分，也是该 Skill 的排序得分
abstract	命中记录的摘要

专用 skills/find 的一条结果示例（省略无关字段）：

{
  "name": "data-service",
  "description": "管理数据服务",
  "root_uri": "viking://agent/skills/data-service",
  "skill_md_uri": "viking://agent/skills/data-service/SKILL.md",
  "uri": "viking://agent/skills/data-service/reference/backup.md",
  "level": 2,
  "score": 0.91,
  "abstract": "跨地域备份恢复的前提、步骤和验证方法。"
}

接口约定

入口或参数	行为
skills/find	每个 Skill 一条；名称、描述、标签、允许使用的工具仍从主目录读取；root_uri、skill_md_uri 保持原意
通用 find/search	保持原有按命中内容返回的行为；同一个 Skill 可以有多条结果，不按 Skill 补页
search(mode="context")	沿用原有结果选择、配额和内容预算
read_content	支持该参数的入口仍按命中 uri 读取；专用 skills/find 不支持该参数
skills/find 的 level、target_uri	先限制参与匹配的内容，再合并；例如 level=[2] 只返回文件命中。不传层级时允许 L0～L2
skills/find 权限	命中内容和 Skill 根目录均须可访问，被排除内容不能贡献得分；内部隐藏备份不作为 Skill 搜索结果，也不占返回名额
仅按 filter 查询，无查询文本	沿用原行为：score=0，保留索引记录 URI，不额外补 L0、L1 文件后缀
Skill 列表、按名称读取、文件读取和目录浏览	保持原行为

ov skills find 的终端卡片显示 Skill 根目录 root_uri，JSON 保留实际命中字段。

**兼容变化：**依赖专用 skills/find.uri 获取 Skill 根目录的调用方，应改用已有的 root_uri；uri 现在可能指向任一层级的命中内容。

4. 添加、更新、锁与失败恢复

操作	行为
添加	默认处理整包
更新	整包替换，清理旧索引并处理新包
重建	覆盖整包；重生成摘要时保留 Skill 主目录规则，只重建向量时不重生成或补齐摘要
删除	删除整包和关联索引，旧任务不能重新写回
wait=true	等待整包摘要和索引任务完成

到底有几把锁

一次更新锁住 3 处：当前 Skill 包、旧包备份、当前用户的该 Skill 隐私配置。前两处一起获取，配置随后单独获取。 所有范围都包含各自的子目录和文件；未启用隐私配置服务时，只涉及前两处。

锁住哪里	谁持有、何时释放
当前 Skill 包	更新请求和包处理任务各持有一份凭证；两份都释放，当前包才解锁
本次旧包备份	与当前包一起由更新请求取得；请求成功清理备份，或恢复收尾后释放
当前用户、当前 Skill 的隐私配置及历史	更新请求在读取旧配置之前取得；成功或恢复收尾后释放

这里的“凭证”表示谁还需要继续持锁。包处理任务先在请求内取得自己的一份，写完文件后交给后台；它与更新请求共用同一把当前包锁，可以分别释放。后台接手不会再多锁一处目录。 配置保存、恢复函数内部也复用本次配置锁的持有身份。

相对原实现，增加了当前包从写入到后台结束的持续保护，以及更新期间的备份保护；已有配置锁延长到更新请求成功或恢复收尾。底层仍使用现有路径锁。

正常更新：先获取，再交接，最后释放

图中的“请求收尾”统一指：清理旧备份和空配置目录 → 释放配置锁 → 释放请求持有的当前包、备份凭证。

flowchart TD
    A["解析、校验新包"] --> B["请求一起锁住：当前包 + 旧包备份"]
    B --> C["请求锁住隐私配置，再读取旧配置"]
    C --> D["备份旧文件和索引 → 清理包内旧内容 → 应用新配置"]
    D --> E["包处理取得当前包的另一份凭证<br/>保存新文件、主目录摘要和来源信息"]
    E --> F["先交接处理凭证，再入队<br/>后台开始生成摘要和索引；请求仍持锁"]
    F --> G{"wait 参数"}
    G -->|true| H["请求等待后台成功<br/>后台释放自己的包凭证"]
    H --> I["请求收尾，返回成功<br/>三处全部解锁"]
    G -->|false| J["请求收尾，返回 task_id<br/>配置和备份解锁；后台仍持有自己的包凭证"]
    J --> K["后台完成或失败并收尾<br/>释放最后一份包凭证，当前包解锁"]

Loading

后台与请求并行，上图 wait=false 分支展示后台尚未完成的情况；若后台先完成，则它先释放自己的凭证。当前包总是等双方都释放才解锁。 wait=false 成功返回后，后台失败通过任务状态报告，新版保留，不自动恢复旧包。

更新异常：先停止本次任务，再恢复，最后解锁

以下流程用于更新的同步异常，以及 wait=true 的失败、超时、请求取消或通过任务接口取消后台任务。恢复期间，请求继续持有已取得的包、备份和配置锁。

flowchart TD
    A["更新失败、等待超时或请求取消"] --> B{"本次任务是否已入队？"}
    B -->|否| C["释放尚未交出的包处理凭证<br/>入队失败则先收回凭证"]
    B -->|是| D["保存取消状态，阻止迟到消息回写<br/>跳过未开始的工作，停止可中断的计算"]
    D --> E["等待已经开始的写入及任务清理退出<br/>释放后台包凭证"]
    C --> F["请求仍持锁<br/>清理新版，恢复旧文件、索引和原隐私配置及历史"]
    E --> F
    F --> G{"恢复成功？"}
    G -->|是| H["清理旧备份"]
    G -->|否| I["保留可用备份<br/>记录恢复失败和备份位置"]
    H --> J["释放配置锁，再释放请求的包、备份凭证<br/>返回错误"]
    I --> J

Loading

恢复只针对已变更的内容；尚未修改旧包时无需还原。取消后只等写入安全退出及取消清理，不继续等剩余摘要、索引全部算完。 因此错误响应可能晚于 timeout。替换和恢复始终保留当前 Skill 根目录及锁文件，避免恢复过程中提前失去保护。

场景	操作与最终状态
获取包锁或配置锁失败	释放已取得的凭证，旧文件、索引和配置尚未修改
备份失败	不开始替换旧包；保留可用备份并报告位置，释放请求的锁
后台可重试异常	携带原包锁凭证重新交接入队；被新任务替代的旧重试释放自己的凭证后退出
恢复本身失败	返回恢复失败及备份位置；当前包可能只恢复了一部分，保留备份并释放请求的锁
备份、空配置目录或临时上传清理失败	保留原操作结果，继续释放锁；成功响应增加 warnings，失败请求保留原错误并记录清理日志

服务关停

向量消费者先结束正在进行的写入并退出；Skill 后台随后释放自己的包锁凭证，不再等待尚未执行的向量消息。未完成的消息保留在队列，重启后恢复处理。

哪些操作会等待

• 修改或删除同一个 Skill： 受当前包锁约束，直到请求和后台都释放；按对应入口原有等待或冲突规则处理。
• 单独保存同一隐私配置： 等待更新请求成功或恢复收尾，最多等 30 秒，超时不写入；wait=false 成功返回后即可保存，无需等后台摘要和索引。
• 默认读取和搜索： Skill 普通读取、find/search，以及隐私配置的读取、目录和历史版本查询，都不获取上述锁。更新期间可能读到中间状态，例如文件暂时不存在、索引尚未建齐、配置值和历史尚未同步完成；隐私配置接口没有独立的语义搜索入口。
• 带校验信息的 Skill 详情读取： include_integrity=true 会按原有逻辑获取当前包锁，读取文件及校验信息后释放。更新持锁时会发生锁冲突；该读取入口的锁等待时间为 0，获取失败会报错。默认 include_integrity=false 不走这条加锁路径。
• 其他 Skill： 不在这些锁的范围内。

添加只取得当前包的处理凭证，写入后交给后台；配置锁只覆盖配置保存。添加部分失败保留成功内容，等待超时只结束等待。重建沿用原入口的锁，等已提交的索引工作收尾后释放；部分失败保留成功内容并报告。更新才需要旧包备份及贯穿请求的配置锁。

文件保存、摘要和索引关联同一个任务，后台入队前创建任务并保存来源信息。取消只作用于本次 Skill 任务。保留各失败文件的明细，同一包只结算一次队列任务；所有工作收尾后全局等待结束，关闭监控统计也不影响等待。Resource、Memory 的添加处理规则不变。
专用 skills/find 各页复用同一查询向量；通用搜索的过滤排序及停止规则不变。向量重建兼容旧版纯文本摘要，保留原描述及已有标签等元数据。创建 Skill 任务期间请求被取消，已经保存的任务记录也会结算为失败，正常参与过期清理。

5. 启用与已有数据

• 新增、更新默认处理整包；专用 skills/find 按 Skill 合并，每个包占一个结果位置。
• 已有 Skill 通过分批重建补齐，服务升级不自动批量调用模型。补齐前仍可用原 L0 检索；首次补齐须生成缺失摘要，不能只重建向量。
• 模型调用量、索引数量、处理耗时和搜索排序会变化，继续使用已有并发、长度及媒体配置控制。

验收重点：各层内容可命中且主目录规则不变；同包合并后能返回足够的不同 Skill；各接口字段与过滤一致；更新、删除无旧索引残留；失败和超时能完整恢复且迟到任务不能回写；其他 Skill、Resource、Memory 不受影响。性能验证覆盖小包、大量小文件和媒体包。

[yeshion23333]

本方案已实现。