Repository navigation
Description
Current state: Proposed。在 #515 / #516 定义的整理后知识库上,增加「全目录简述选择 → 条件校验 → 引用扩展 → 原文读取」检索模式;尚未实现或验证收益。#516 当前仍未合入。
Decision needed: 请仓库维护者确认该实现范围、与 #500 / #379 的接口边界,并指定实施及验收负责人。
Next action: 实施负责人确认依赖版本,交付可调用的端到端检索模式、离线契约测试和使用文档;真实任务效果按冻结协议单独评估。
Goal and acceptance
问题与目标
工程问题经常跨越 systems、playbooks、workflows、casebooks 和独立 records。目录整理提供了明确归属,但逐层选择分支可能遗漏跨目录材料;关键词查询也可能无法充分利用已有描述和条件字段。
实现一个可选搜索模式:Agent 在预算内看到同一知识快照的完整候选简述,直接选择相关条目;读取并核对其适用条件,再沿显式引用补齐必要证据。保留现有 Find 作为直接查找和回退入口。
例如「引擎升级后 TTS 首包变慢且音质下降」,应允许同时选择计时方法、版本兼容记录、精度排查流程和相关案例,并明确哪些材料支持当前环境、哪些仅能提出假设。
完成条件
- 全目录简述可从现有权威来源生成,包含共享搜索清单中的全部合格 Skill / Record / Case,条目可以跨目录同时入选。
- Agent 能完成一次真实接口链路:获取目录快照、提交选中的 ID、校验条件、扩展引用、读取原文、返回证据或明确缺口。交付不能仅停留在导出目录或提示词。
- 未知条件、明确冲突和方法类比有可检查的区分;描述相关性不能直接升级为目标环境验证。
- 引用扩展遵守现有资源、依赖、版本和上下文预算契约;终止原因、缺失材料和预算不足均可观察。
- 现有 Find、显式 ID 读取及未选择新模式的调用方保持兼容;新的模式有端到端测试、文档和检索 trace。
Scope and constraints
1. 全目录简述与选择
复用现有 catalog、Find corpus 和 reader,定义统一的目录快照视图。简述从 SKILL.md 中的现有描述/结构化字段、工程记录和案例投影生成,不再维护另一份手写知识来源。
每张目录卡至少包含:
- qualified ref、stable ID、kind、标题、简述或可回答的问题;
- 已有关键词/别名、适用条件及缺失字段、现有验证状态和限制;
- 原文读取定位、可解析的显式引用;
- 用于校验视图新鲜度的来源标识,以及能够实际提供的读取大小信息。
目录整体记录 scope、快照标识、按 kind 的条目数、总字节数;模型 token 预算使用明确的 tokenizer 或说明估算方式。所有卡片和选择结果绑定同一快照,来源变更后刷新或显式报告过期。
全目录的范围是当前声明的知识来源/权限范围内的全部合格证据对象。 #515 所述快照为 80 个支持技能 + 48 条记录 + 7 个案例,共 135 个;该数字只作背景,实现动态计算。不要直接使用含 8 个任务入口、且未包含独立案例视图的 136 条普通 catalog 列表冒充证据全集。主任务技能及兼容 router 按现有规则单独加载。
全目录模式不得先用词法 top-k 裁掉候选,也不得因输出 limit 或分页漏掉后续条目。明确声明的来源范围和已支持的过滤条件可以收窄 scope,但必须记录排除数量和原因。若整个目录连同任务上下文无法容纳于模型预算,显式报告并回退到现有 Find;不得静默截断后仍声称进行了全目录选择。
选择由现有 Agent/应用编排层使用当前模型完成,Knowledge 层负责可重复的视图生成、ID/快照校验和读取。提交结果包含选中 refs、选择理由、需要核对的问题;允许空选择。拒绝快照外的 ID、歧义身份及失效定位,并提供可恢复的错误。默认 Find 不增加隐式模型调用。
2. 条件校验
输入为本次任务的已知条件与明确未知项,按需要包含硬件/后端、OS、模型与执行阶段、引擎和依赖版本、dtype、负载及质量/测量要求。无需要求所有任务填写同一套全量表单。
先使用目录卡作初步判断,读取原文后确认结论适用范围。输出是本次检索的判断,不改写条目自身的生命周期或验证状态:
| 判断 | 含义 | 使用方式 |
|---|---|---|
| 条件匹配 | 相关结论的关键条件有依据地匹配 | 与来源验证状态一起展示,按任务要求复验 |
| 可供类比 | 方法或机制相关,但关键环境不同 | 提出假设及最小验证步骤 |
| 尚不确定 | 关键条件缺失、表达含糊或无法比较 | 列出缺失项及如何补证据 |
| 明确冲突 | 原文声明的适用边界与任务条件冲突 | 不作为该结论在目标环境成立的依据 |
能结构化比较的条件使用确定规则;自然语言判断附原文定位及理由。字段缺失不能当作匹配,也不能自动排除所有通用方法。对具体结论校验,避免某条硬件结论冲突就否定整篇文档里的通用排查方法。
分别保留“条件匹配”和“证据是否经过验证”,引用传播不能提高验证等级。知识内容 revision 与实际被验证的引擎/依赖 revision 分开处理。经扩展加入的材料同样接受校验。
3. 有界引用扩展与原文读取
从已选条目出发,解析现有声明中的技能链接、owner-local 资源和来源指针;对缺少可解析关联的材料如实报告。可选的跨条目导航基于显式引用,不根据模型猜测生成依赖。
- 首版建议可选引用默认扩展一跳,深度、条目数和字节预算可配置;循环检测、去重和停止原因必须明确。
- 记录从哪个条目、通过哪条原文引用加入材料;身份与 revision 一起参与去重,冲突版本不静默合并。
- 只自动展开现有 reader 能解析的材料;外部 URL 保留为来源指针,外部检索仍由现有显式入口处理。
- 可选引用预算不改变现有必需依赖闭包。 完整技能流程、声明的必需资源、来源和许可证继续按 reader 契约交付;放不下时按契约报告遗漏,不截断必需流程或只返回部分依赖却标记完成。
- 复用 read/resource 的版本绑定和实际读取,不能以“存在读取命令”代替成功读出。
4. 接入与可观察性
首版以显式可选模式接入现有 Agent/应用入口。沿用七类任务的主技能加载流程;目录选择只改变支持证据的检索方式。CLI/Python 以共享实现暴露必要的目录与选择/读取能力,具体命令名随实现确定。
复用现有 retrieval trace,记录:目录快照和候选覆盖、选择结果、条件比较理由、扩展路径、实际读取结果、遗漏/回退原因、模型与 prompt 版本、调用次数、token/字节和端到端耗时。缺少可观察读取证据时仅记录递送,不自动记为已读或已采用。
范围边界
- 本任务交付上述检索模式及其接口、测试、文档;复用 [Tracking] 高效知识表达:知识目录(含 Skill)的分层披露与搜索空间索引 #500 的分层字段方向,避免创建平行卡片标准。
- 知识视图、校验和读取属于 Knowledge;模型选择与编排在现有 Agent/应用层,Harness 不另建自主搜索路径。
- 本轮不要求目录再迁移、向量数据库、树搜索实现、自动知识图谱抽取或全量历史材料重写。
- 不因功能交付直接切换默认检索入口;推广依据真实任务效果和维护者决定。
Ownership and authorization
- Proposed by / actual requester: 用户明确请求提交此实现 issue;Codex 整理并提交。
- Status: Proposed。
- Accountable parent (Issue-level owner, if assigned): 待维护者指定。
- Slice implementer(s) / acting contributor (if assigned): 待指定。
- Goal-acceptance owner: 请求者及仓库维护者,具体负责人待指定。
- Accepted decision or scoped delegation: 当前已授权创建 issue;实现接单、付费评测及默认入口推广分别按仓库现有流程记录。
Inputs and deliverables
依赖与复用
- Organize inference knowledge in one skill_library and validate task-oriented retrieval #515 / Unify inference knowledge in skill_library with seven task routes and direct search #516:统一来源、stable ID、主任务入口和读取兼容性;Unify inference knowledge in skill_library with seven task routes and direct search #516 合入前明确目标分支和集成顺序。
- [Tracking] 高效知识表达:知识目录(含 Skill)的分层披露与搜索空间索引 #500:知识分层与简述/决策字段,本任务实现其中一种具体检索消费方式。
- tracking: Skill Indexer 检索效率、准确性与逐轮采用 #379 / task: 改进真实优化任务中的材料发现与使用 #380:现有检索与使用策略评测,沿用已记录的结论边界。
- task: 支持每个优化迭代的知识库命中归因统计 #344:命中、递送、读取、采用的归因口径。
- Knowledge layout、读取与 Collect 契约。这些链接用于设计背景;实现与评测分别记录实际版本。
- 主要复用模块:src/inferrsi/knowledge/catalog.py、knowledge_find.py、knowledge_operations.py 和现有 Agent/应用适配层。
测试与评估交付
功能验证: 使用确定的 selector 替身验证完整接口链路,覆盖候选清单完整性、跨目录选择、空选择/非法 ID、过期快照、缺失条件、明确冲突、类比、引用循环/失效版本、必需资源预算不足、目录超预算回退和现有 Find 兼容。另提供实际 Agent 接入示例及执行记录;未运行的验证明确标注。
效果评估: 复用 #515 的七类留出任务设计;冻结同一知识版本、任务入口、模型配置、会话预算、题面和判分规则。主对照为现有 Find 与完整新流程;需要拆分贡献时再增加“仅全目录选择”的消融,树搜索比较可作为后续工作。每题每个配置默认只执行一次,基线和候选各一次,接受波动;不为了中位数或置信区间追加重复测量。
报告适用证据命中、错误迁移/错误拒答、成功读取、扩展带来的有效新增证据、首次有效证据时间和总调用/token/耗时,逐题列出退化。缺证据题可以返回类比材料,评分依据是否明确缺口及是否误用,不能只看空结果率。功能测试通过、排名变化或检索耗时下降均不等于任务或推理服务性能收益。
正式收益门槛及付费/设备预算在评估运行前按现有验收流程冻结;本 issue 不预设加速比例,也不要求为检索功能测试启动 GPU 推理。尚无效果证据时,收益状态保持 INCONCLUSIVE。
预期产物: 实现 PR、接口/使用文档、离线回归用例、可复核 trace 与实际 Agent 接入记录,以及已完成评估结果或明确的未评估项和后续决策。
Completion and closure
- Who accepts completion and may close: 指定的目标验收负责人,按仓库协作规则记录完成摘要并决定关闭。
- Remaining uncertainty / next decision: 全目录简述实际 token 成本、已有字段/引用覆盖率,以及相对现有 Find 的任务效果。功能交付、收益判定、默认入口切换分别记录;关闭实现任务不自动表示收益成立。
Activity
Dong1017 commentedon Nov 20, 2026
Posted by Dong-bot, an automated agent acting on behalf of @Dong1017 (always-on-bot, model claude-sonnet-5-5).
Assessment: The scope is clear and well bounded, but it isn't ready to assign. The three blockers are an unmerged dependency, no named owners, and no measured token cost for the full catalog. I read #516 for this triage. I did not open #515, #500, #379, #380 or #344, so the boundary comments below rest on how this body describes them.
What it asks for
Strengths
Gaps and risks
Dependency. Unify inference knowledge in skill_library with seven task routes and direct search #516 is still open, and its latest review (head
d03bbb7) is DO NOT PASS. Two of its findings affect this design directly:read --materialpayloads grew about 45% at the median because the typedmetadata.inferrsiblock is delivered inside the content.findhits are no longer card-sized, becauselimitationsis uncapped.Catalog cards will inherit both unless they are fixed or capped. Please pin the target branch and commit. The body only says "clarify the integration order".
Token feasibility is untested. Whether 135 cards fit with the task context is listed as unknown. That is the main risk. Please add an early, cheap step that measures the catalog size with a named tokenizer. It should include a per-field cap such as
limitations. The result decides whether the mode is viable before the larger work starts.Interface boundaries. The "[Tracking] 高效知识表达:知识目录(含 Skill)的分层披露与搜索空间索引 #500 / tracking: Skill Indexer 检索效率、准确性与逐轮采用 #379 interface boundary" is requested but not defined. Please state which fields come from [Tracking] 高效知识表达:知识目录(含 Skill)的分层披露与搜索空间索引 #500 and which retrieval or evaluation contracts from tracking: Skill Indexer 检索效率、准确性与逐轮采用 #379/task: 改进真实优化任务中的材料发现与使用 #380 are reused.
Missing-field handling. Cards need "applicability + missing fields". Several records and skills may lack structured conditions. Please say whether the first PR reports field coverage, and what the fallback is when conditions exist only in prose.
Condition rules. Fix the structured-comparison fields and the version-comparison rules (ranges, "unknown version") up front. Otherwise the "deterministic rules" will drift between implementers.
Stale snapshots. Define whether a stale-snapshot error forces a fresh catalog fetch or a Find fallback. Define the same for IDs outside the snapshot.
Evaluation protocol. One run per arm with no repeats is acceptable only if the issue says results are observational. The pass/fail gate for "worth promoting" and the budget are still to be frozen. That is fine, but it should block any default-entry change.
Decisions and owners needed
Suggested next steps
Wait for or pin the Unify inference knowledge in skill_library with seven task routes and direct search #516 merge target. Record the integration order.
Run a short spike: build the catalog view from the existing catalog, then report card bytes and tokens per kind and the field coverage.
Split delivery into three slices:
The offline contract tests then land with each slice.
Keep the effect evaluation as a separate follow-up issue.
I haven't run any code or tests. This comment is Dong-bot (authorized delegate) triage. It records no acceptance of scope and assigns no owner.
zengchuang-hw commentedon Nov 20, 2026
PASS
设计可以进入实施。已对照现有 Find/corpus 和 reader:全量候选以共享证据集合为准,不依赖普通 catalog;可选引用的一跳限制不截断 reader 必需依赖;内容 revision 和被验证引擎 revision 分别记录。
建议将两个边界写进端到端用例:①取得目录后,选中材料或其必需依赖变化,读取须拒绝旧快照或显式刷新;②同名不同 authority、最小安装缺可选依赖或必需资源超预算,trace 分别记录可见、已递送、实际读取及未读原因,不能把返回命令当作已读。功能上线、真实任务收益和默认入口推广仍分别验收,收益没有证据时保持 INCONCLUSIVE。仅静态设计检视,未运行代码。