Skill检索侧补齐：inject_skills 列表+全文两级渐进披露 #164

Merged

Yushu merged 1 commit from feat/154-inject-skills-retrieval into main

2026-08-19 03:10:12 +00:00

KumaAgent commented

2026-08-19 02:45:43 +00:00

Member

Closes #154

实现内容

inject_skills 工具补齐技能检索侧——按 CONTEXT.md「技能（Skill）」条既有设计实现列表+全文两级渐进披露：

无 skill_id：返回全部技能的预览列表（content 截断到 arise_skill_preview_max_chars，默认 80）
带 skill_id：展开该条全文（超过 arise_skill_full_text_max_chars，默认 4000，时截断+truncated: true 标记）
查无对应 skill_id：返回错误而不是静默退化成空列表——模型给的 id 大概率是编造/记错的，应如实告知
get_skill(id) 作为独立的 SkillStoragePort 方法，不复用 list_skills() 的 scroll 分页扫描，避免技能库超过 1000 条时出现"列表看得到、全文查不到"的正确性缺口
冷启动从向量 metadata 重建：PersistentStorage 本身不持有除 qdrant_client 引用外的任何状态，技能数据完全活在 Qdrant point payload 里，补了专门测试验证

范围调整

原 AC 要求三级渐进披露（列表/全文/文件）。实现期 design-verify 核实：本仓库目前没有任何 host 发文件能力（CapabilitySet 无文件位、EgressPort 无 send_file、ResourcePort 的 kind 枚举不含 file）——与用户确认后，文件级拆到独立的 #163，本票收窄到列表+全文两级。CONTEXT.md/design.md/ADR-0006 已同步标注这一范围调整。

两轴 review 修复

get_skill 对真实 Qdrant server 拒绝格式非法 point id（模型编造的 skill_id 很可能连 UUID/整数格式都凑不对）补了异常兜底，避免未捕获异常让整轮回复静默消失
补齐非字符串 skill_id、预览截断边界等测试覆盖缺口
build_tool_schemas docstring 补上 inject_skills 恒可见工具枚举

测试

全部 1934 个测试通过；ruff check/lint-imports/ty check 干净；新增逻辑（列表/全文分派、get_skill 未命中路径、格式非法 id 兜底、截断边界）均做过 mutation testing 确认能被现有测试捕获。

Closes #154 ## 实现内容 `inject_skills` 工具补齐技能检索侧——按 CONTEXT.md「技能（Skill）」条既有设计实现列表+全文两级渐进披露： - 无 `skill_id`：返回全部技能的预览列表（`content` 截断到 `arise_skill_preview_max_chars`，默认 80） - 带 `skill_id`：展开该条全文（超过 `arise_skill_full_text_max_chars`，默认 4000，时截断+`truncated: true` 标记） - 查无对应 `skill_id`：返回错误而不是静默退化成空列表——模型给的 id 大概率是编造/记错的，应如实告知 - `get_skill(id)` 作为独立的 `SkillStoragePort` 方法，不复用 `list_skills()` 的 scroll 分页扫描，避免技能库超过 1000 条时出现"列表看得到、全文查不到"的正确性缺口 - 冷启动从向量 metadata 重建：`PersistentStorage` 本身不持有除 `qdrant_client` 引用外的任何状态，技能数据完全活在 Qdrant point payload 里，补了专门测试验证 ## 范围调整原 AC 要求三级渐进披露（列表/全文/文件）。实现期 design-verify 核实：本仓库目前没有任何 host 发文件能力（`CapabilitySet` 无文件位、`EgressPort` 无 `send_file`、`ResourcePort` 的 `kind` 枚举不含 `file`）——与用户确认后，文件级拆到独立的 #163，本票收窄到列表+全文两级。CONTEXT.md/design.md/ADR-0006 已同步标注这一范围调整。 ## 两轴 review 修复 - `get_skill` 对真实 Qdrant server 拒绝格式非法 point id（模型编造的 `skill_id` 很可能连 UUID/整数格式都凑不对）补了异常兜底，避免未捕获异常让整轮回复静默消失 - 补齐非字符串 `skill_id`、预览截断边界等测试覆盖缺口 - `build_tool_schemas` docstring 补上 `inject_skills` 恒可见工具枚举 ## 测试全部 1934 个测试通过；`ruff check`/`lint-imports`/`ty check` 干净；新增逻辑（列表/全文分派、`get_skill` 未命中路径、格式非法 id 兜底、截断边界）均做过 mutation testing 确认能被现有测试捕获。

KumaAgent added 1 commit

2026-08-19 02:45:43 +00:00

feat(skill): 实现 inject_skills 检索侧——列表+全文两级渐进披露 c03e7e410f

issue #154：`inject_skills` 工具补齐技能检索侧——无 skill_id 返回预览列表，
带 skill_id 展开全文（超长截断+提示，是 issue #163 落地新 host 发文件能力
前的过渡行为）。get_skill(id) 独立于 list_skills() 的分页扫描，避免技能库
超过 1000 条时出现"列表看得到、全文查不到"的正确性缺口。

三级渐进披露的原始 AC 里"超长内容转文件"这一级需要新的 host 发文件能力，
本仓目前没有——已拆到独立的 issue #163，本票收窄到列表+全文两级，
CONTEXT.md/design.md/ADR-0006 已同步标注这一范围调整。

两轴 review 额外修复：get_skill 对 Qdrant 拒绝格式非法 point id 的场景
补了异常兜底（避免整轮回复静默消失）、补齐若干测试覆盖缺口。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>