Repository navigation
Description
[RFC] 全量接入 cannbot-knowledge:MCP 常驻查询通道设计
Status: Proposed — 整体 RFC 尚未接受。 维护者已在实施会话授权 PR #484 的 C0–C3 切片及评审修复;本次同步决定与实现边界,不代替独立审批,不宣布组织许可确认、C4–C6 完成或 #388 关闭。
Governing dependency: #388(外部技能/知识依赖治理)。本文是其"外链或 submodule 待决"的候选实现,落实为选定的第三方机制,但不关闭 #388。
接口依赖: #387(read/collect公开接口,仍为 Proposed)。
文中所有上游 revision 与统计值都是写作时的实测观测值,不是本仓 pin,也不是验收基线。
0. 决策摘要
2026-11-18 决策同步。 维护者在实施会话明确批准开发、手工安装/启用说明和检索前后对照,随后将 cannbot 默认返回上限从 10 改为 100,并授权处理 review 意见。此处由实施代理记录授权,不作为独立批准。保留单一显式 backend、参数优先于已批准项目 grant、未知时不推断;本地是否命中不影响已授权 Ascend 查询。两个本地设计草稿不随 PR 提交。C0–C3 交付本地只读 worker;MindIE adapter、MCP serving、receipt/import、HTTP、缓存和旧版本重放留待后续。
| 项 | 决定 | 位置 |
|---|---|---|
| 接入形态 | 包外只读查询;C0–C3 本地 worker,C5 后续 MCP;内容不进本仓、wheel、evidence | §5.1 |
| 触发语义 | 平台门控命中即查,与本地是否命中无关;不再"零命中才补漏" | §5.2 |
| 平台门控来源 | 显式声明(--backend 或 grant),不推断;--backend 只接受单值 |
§5.2 |
| 结果呈现 | 分栏并列,外部结果不进 items,分数带 score_scale,不跨通道合并 |
§5.3 |
| 每通道条数 | cannbot-knowledge 100 / 后续 mindie-agent 5 |
§5.4 |
find 默认 |
默认带外部查询;CI 与单测必须显式 --no-external |
§5.4 |
| MCP 面 | C5 后续设计;当前 C0–C3 不提供 serve |
§8.5 |
| 证据 | receipt 只存 locator + card_sha256 + revision,不含正文 |
§7 |
为何从"候选比较"走到"选定 MCP"
前几轮评审已比较过五种形态(包内转换、submodule、外链锁缓存、MCP、混合)。包外只读查询的工程理由如下,不构成许可结论:
- 内容边界:InferRSI 不将外部正文、完整 frontmatter 或派生文本摘要复制进包和 evidence;C6 最小元数据另需发布授权。包外 checkout、worker 或 MCP 不代替本地使用、模型传输、缓存、镜像及再分发的许可确认。
- 产能:上游已有 10,550 张卡与自身的 ingest/lint/index 生产系统。任何"复制或缓存进本仓"的形态都在与一个数量级的产能赛跑。
1. 现状:InferRSI 的 Ascend / CANN 知识极度匮乏
这是本 RFC 的起因。在 main 6c7e237935a22cc5e90e954d4f397376e753e7d8(2026-11-16)上实测 src/inferrsi/knowledge/data/:
| 项 | 实测值 | 说明 |
|---|---|---|
| 打包知识数据总量 | 7.8 MiB / 850 个 md+json / 921 个文件 | 含全部 skill、引用与记录 |
| 知识记录总数 | 128 | repo_packs 108 + knowledge_packs 20 |
| 其中 Ascend 记录 | 22 | 占 17.2% |
| Ascend 记录中真正的内容卡 | 6 | 3 条 Qwen3-TTS audio、3 条 vLLM-Omni diffusion |
| Ascend 记录中仅是 skill 指针 | 16 | 只指向 skills 组件,不承载技术结论 |
| Ascend 硬件 skill | 14 / 143 个 SKILL.md |
380 KiB,43 个文件 |
| Ascend skill 正文 | 131,860 字节 | 14 篇 SKILL.md 合计 |
| Ascend skill 引用资料 | 174,559 字节 / 29 个文件 | 含 3 份上游 LICENSE 抄本 |
| per-API 粒度知识卡 | 0 | 全仓没有任何一张卡对应单个 CANN/AscendC API |
出现 aclnn* / __aicore__ 签名的文件 |
1 | frameworks/torch-npu/.../references/development.md |
对照上游 cannbot-knowledge 的同一维度:
| 项 | 上游实测值 | 倍数 |
|---|---|---|
| 知识卡总数 | 10,550 | 内容卡 6 → 10,550(约 1,758×) |
ops/ascendc 领域卡 |
6,804 | — |
API 类型卡 |
3,875 | 本仓 0 |
| 其中 Ascend C API 卡 | 2,993 | — |
runtime API 卡 |
516 | 本仓 0 |
Operator 卡 |
903 | 本仓 0 |
Runbook 卡 |
2,585 | 本仓无对应类型 |
这是粒度差,不只是数量差。 InferRSI 现有 Ascend 知识是技能粒度:14 篇 SKILL.md,讲"怎么设计 tiling""怎么抓 ACLGraph""怎么诊断算子瓶颈"这类流程。上游是API 与算子粒度:单张卡讲清 CeilDivision 的参数、单位、平台约束、失效边界。两类内容不可互相替代——技能粒度无法回答"这个 API 在 a3 上是否支持、参数语义是什么",而现有仓恰好完全缺失后者。
为什么既有路径补不上。 #91 的蒸馏路径是"人力策展 + 逐条 PR",本仓至今累计 6 条 Ascend 内容卡;按同一速度覆盖 2,993 张 API 卡在工程上不成立。而且这 6 条内容卡全部绑定具体模型 campaign(Qwen3-TTS 音码、MiniMax-H3 KV 复用、Qwen-Image 预热),描述的是"某模型在某卡上的某次优化",不是可复用的通用 Ascend 机制。
匮乏不等于现有内容有错。 那 14 篇 skill 多数经 campaign 验证,质量可用;问题纯粹是覆盖面——aclnn / AscendC API / CANN Runtime / 算子实现这四类基础层次在本仓几乎是空白,导致 Agent 做 Ascend 任务时只能依赖 campaign 记忆与现场搜索,无法像 CUDA 路径那样先查知识再动手。
这也解释了为什么不能只靠"蒸馏": 上游的知识生产侧(knowledge-ingest、两个 Operator producer、trace ingest)已经是一个持续产出系统,本仓若只做消费端的手工蒸馏,永远落后一个数量级的产能。本 RFC 讨论的正是"以什么形态消费这套外部产能",而不是"要不要再造一套"。
2. 上游形态与许可(实测)
写作时对上游 master 的一次浅克隆观测(commit 观测值 92dc260756e91e72e6dcd60f3996a4d54f43c8f5,2026-11-16):
| 项 | 值 |
|---|---|
| 知识正文根 | knowledge/,OKF v0.2 唯一 Bundle,Concept ID = Bundle 相对路径去 .md |
| 概念卡 / 导航 | 10,550 张 / 818 个 index.md(不参与检索) |
| 正文字节 | 约 118 MiB(不含导航);目录占用约 143 MB |
| 领域分布 | ops 7,440 · model 1,890 · contrib 653 · runtime 530 · common 21 · tools 16 · graph 0(保留结构入口) |
| 状态分布 | stable 6,589 · draft 3,920 · deprecated 41 |
| 类型分布 | API 3,875 · Runbook 2,585 · Guide 1,788 · Optimization 1,087 · Operator 903 · Concept 287 · Example 23 · Glossary 2 |
| 平台受控值 | a2 1,765 · a3 1,610 · 310p 395 · agnostic 228 · kirin_x90 198 · kirin_9030 172 |
| 写作语言 | 标题、描述与正文说明以中文写作;API 名、签名与代码为英文 |
2026-11-18 同 revision 复算。 文件集合为 Git 跟踪的 knowledge/**/*.md,排除 basename 为 index.md 的导航文件。用该 checkout 自带的 split_frontmatter 解析,得到 10,550 张卡、818 个导航文件,解析错误 0,status/type 缺失 0;状态和类型均合计 10,550。旧表少计的 223 项全部采用 JSON 形式的 frontmatter(带引号且缩进的键),都是 Runbook:222 draft、1 stable。逐行匹配未加引号的字段会漏掉它们;这是旧统计口径的问题,不是新增或未分类卡。draft/deprecated 状态照实呈现,不意味着本地可信或具有验收资格。
复算(只输出汇总;使用已批准 checkout/interpreter,不下载来源):
<approved-python> - <approved-checkout> <<'PY'
from collections import Counter
from pathlib import Path
import json, subprocess, sys
root = Path(sys.argv[1]).resolve()
sys.path.insert(0, str(root / ".agents/skills/knowledge-query/scripts"))
from retrieval.index import load_contract
_, split = load_contract(root)
paths = subprocess.check_output(
["git", "-C", str(root), "ls-files", "-z", "knowledge"], text=True
).split("\0")
cards = [p for p in paths if p.endswith(".md") and Path(p).name != "index.md"]
counts = {key: Counter() for key in ("status", "type")}
errors = 0
for path in cards:
try:
metadata, _ = split((root / path).read_text(encoding="utf-8"))
metadata = metadata or {}
except Exception:
errors += 1
metadata = {}
for key in counts:
counts[key][str(metadata.get(key, "<missing>"))] += 1
print(json.dumps({
"revision": subprocess.check_output(
["git", "-C", str(root), "rev-parse", "HEAD"], text=True
).strip(),
"cards": len(cards),
"navigation": sum(Path(p).name == "index.md" for p in paths),
"parse_errors": errors, **counts,
}, indent=2))
PY上游不是一个资料包,是一个知识系统:
governance/有机器可读的 schema、路径 Profile、受控值规则与 20 余个 check 实现(来源、链接、索引同步、生命周期、信任层级)。- 检索索引版本化(
cannbot-knowledge-index.v1),带content_fingerprint与built_repository_state.commit;索引相对当前提交过期时拒绝服务。 mcp-server/提供只读discover/search/read_card,stdio 与 HTTP 双传输。- 卡的来源资源不在 Git 内:
sources[].resource常指向cann-docs-raw/...或cann-recipes-raw/<repo>/<commit>/...,由get_resources.sh恢复,默认不提交。单张卡本身不自包含证据闭包。
许可。 上游声明 CANN Open Software License Agreement v2.0,本仓为 Apache-2.0。组织需针对指定上游 revision 和实际用途确认条件;历史 cannbot 文本不能替代该核验。包外存储、只读访问或 MCP 形式不自动解决本地使用、模型传输、缓存、镜像/再分发授权。Q1 仍开放,工程侧不作法律批准。
关于本仓内的 12 个 skill: cannbot-knowledge 的 .agents/skills/ 有 12 个 skill,但它们是知识仓自己的工具链——三个消费流程(knowledge-query 等,就是 MCP 背后的 CLI)、五个生产流程(*-ingest、operator producer)、两个治理(knowledge-lint、knowledge-issue-handler)、两个带 VENDORED.md 的裁剪副本。CANN 领域知识全在 knowledge/,MCP 三工具已完整覆盖,不存在"skill 覆盖不到"的缺口。
3. 形态选择记录
五种候选的比较与结论(保留作为决策依据,不再并行生效):
| 形态 | 许可可分发 | 离线复现 | 漂移检测 | 结论 |
|---|---|---|---|---|
| A 外链锁 + 包外缓存 | 待按用途确认 | ✅ digest | ✅ | 未选:仍需同步与自建索引,收益低于 MCP |
| A′ 索引先行 | 待逐字段确认;索引也在包外 | ✅ | ✅ | 未选:同 A |
| B git submodule(KDA 式) | ✅ | 未选:把许可义务交给集成方,且 143 MB 随克隆 | ||
| C 全量转换进本仓 | 未建立分发依据 | ✅ | ❌ 副本即漂移 | 不选:许可待确认、体积及同步成本 |
| D 只读 MCP | 待按用途确认 | 需索引、revision 和读卡摘要共同检查 | 选定工程方向:复用上游治理;许可仍待确认 | |
| E 混合 | — | — | — | 收敛为 D;C 仅以 #91 蒸馏精选子集的形式保留 |
KDA 的可借之处仍是纪律:README 锁表、third_party_licenses/ 逐件许可、以及"submodule 指向做过去敏的发布点而非上游任意 commit"。本方案把这三条落在 §7 的 receipt 与 §5.3 的 revision 字段上,而不引入 submodule 这一形式。
4. 本仓检索侧事实
| 项 | 值 |
|---|---|
find 实现 |
src/inferrsi/knowledge/knowledge_find.py,commit 61303fa8(#466 统一检索) |
| 检索模型 | 纯词法:idf × 字段权重 × sqrt(出现次数),FIELD_WEIGHTS 见 knowledge_find.py:42 |
| 来源 | kinds=("case","skill","record"),load_corpus 见 :620 |
| 语料规模 | 143 篇 SKILL.md + 128 条记录 + cases,同进程内构建 |
| 确定性 | 完全离线、可复现、无 I/O 依赖 |
| 中文处理 | tokens() 已内建 CJK 双字切分(:87);_BACKEND_NAME_ALIASES 含 昇腾 → ascend |
| 权威源枚举 | AUTHORITIES = ("package", "checkout", "store")(knowledge_operations.py:25) |
上游 MCP 侧实测:索引构建 73.9 秒(7,921,396 postings);查询冷启 3.67 秒 / 热 1.46 秒;结果字段 rank / score / match_basis / path / local_path / card_lines / card_sha256;响应 schema knowledge-search.v5。
5. 接入设计
5.1 通道抽象
新增 src/inferrsi/knowledge/channels.py,把外部源收敛到同一协议,使 find 不认识具体是 cannbot 还是 MindIE:
class Channel(Protocol):
name: str # "cannbot-knowledge" | "mindie-agent"
backend: str | None # "ascend" | None(None = 平台无关)
def describe(self, *, request: ChannelRequest) -> ChannelStatus: ...
def search(self, query: str, *, platform: str | None,
limit: int, request: ChannelRequest) -> ChannelResult: ...
def read(self, locator: str, *, expected_sha256: str | None = None,
expected_revision: str | None = None) -> str: ...@dataclass
class ChannelStatus:
state: str # ok | not_enabled | unreachable | index_stale | timeout
# | version_mismatch | rejected | unknown | backend_unknown | skipped
revision: str | None # 上游 commit / catalog generation
detail: str = ""
fix: str = "" # 修复命令,例如索引重建
checked_at: float = 0.0
@dataclass
class ChannelResult:
status: ChannelStatus
items: list[ChannelHit] # 失败时为空,但 state 必须说明原因
elapsed_ms: intChannelHit 字段:locator / title / summary / score / score_scale / status / platforms / card_sha256 / source_card_sha256。card_sha256 是整张卡原始字节的 SHA256;source_card_sha256 保留上游解析 metadata/body 后的 fingerprint,两者不可混用。选中卡先用批准来源的实现核验 fingerprint,再计算原始字节摘要;多余结果在读卡前截断。
| 通道状态 | hits | revision | 错误/处理 |
|---|---|---|---|
| ok,有命中 | 受 limit 限制 | 本次索引 provenance | 无失败状态 |
| ok,零命中 | 空 | 本次索引 provenance | 成功空集 |
| 其他状态 | 空 | 已知时可保留,否则空 | 明确 detail/fix;不假装成功零命中 |
ChannelRequest 贯穿 describe/search,携带共同 deadline 和资源回收注册。原始 JSON 重复键、非有限数、非法结构及超过 2 MiB 的 stdout/stderr 返回 rejected;未知 schema 返回 version_mismatch。各源失败独立,迟到结果丢弃。
score_scale 是关键:标明分数来自哪套评分("cannbot/knowledge-search.v5" 或 "mindie/graded-0.13.13"),从结构上阻止调用方跨通道比较。
5.2 平台门控(决定"要不要查")
find(query, backend=?)
├─ --no-external ──► 仅本地;不启动外部 worker
├─ 显式 backend 不匹配 ──► 跳过该源;无匹配通道时省略 external
├─ 其余路径缺少项目/grant ──► not_enabled;保留本地结果
├─ 未声明任务 backend ──► backend_unknown;提示显式声明
└─ backend == ascend ──► 已授权 cannbot(C4 后续才加入 MindIE)
backend_unknown 是无声明时的通用门控状态;CLI 中缺少 grant 的
not_enabled 提示优先。无效 grant 则报告 rejected,不静默查询。
backend 来源优先级:--backend 显式参数 > grant 文件声明 > backend_unknown(不猜)。
--backend 只接受单值。多平台任务由调用方分两次查询并各自保留结果。理由:多值会让输出无法回答"这条外部结果是为哪个平台召回的",而上游平台纪律本身 fail-closed(--platform 必填、不混合各平台结果),本仓不应在门控层放宽这一语义。
这里刻意不使用 named_backends()(knowledge_find.py:739)那种从查询词推断的方式:从"query 里出现了 asc"推断"这是 Ascend 任务"不可靠,且失败形态是静默查错平台。门控必须是显式事实。
5.3 分栏呈现(决定"怎么放")
不做混合排序。 本仓 idf 建立在 143+128 条语料上,上游建立在 10,550 张卡上;同一个词在两套体系里的权重完全不同。任何跨通道合并都要发明归一化函数——那正是 RSI 明令禁止的"编造分数"。
{
"query": "AscendC tiling 参数",
"backend": "ascend",
"items": [ /* 只放本仓结果,沿用现有 ranked list */ ],
"matched": 3,
"external": [
{
"channel": "cannbot-knowledge",
"state": "ok",
"revision": "92dc260756e91e72e6dcd60f3996a4d54f43c8f5",
"elapsed_ms": 1520,
"score_scale": "knowledge-search.v5",
"count": 1,
"items": [{
"locator": "ops/ascendc/apis/simd_api/adv_api/cube_compute/matmul_tiling",
"title": "Matmul Tiling类使用说明",
"score": 18.4,
"status": "stable",
"platforms": ["a2", "a3"],
"card_sha256": "049b4824...",
"open": "inferrsi cannbot read ops/ascendc/apis/simd_api/adv_api/cube_compute/matmul_tiling --sha256 <card_sha256> --revision <revision>"
}]
}
],
"external_notes": [
"External results are not locally verified; scores are not comparable across channels.",
"Pin external revisions from this output when citing them."
]
}三条不可退让的规则:
items只放本仓结果。 外部命中不进items,避免下游按items处理时静默把未验证内容当成已验证。- 每个通道独立
state。 一个通道失败不影响另一个;失败必须可见,具有可操作修复方法时附 fix;timeout 等状态不保证有修复命令。 - 不合并
score。 每个通道内部排序,跨通道并列。需要合并时由调用方决定。
5.4 执行模型:并行、预算、缓存
find()
├─ 本地 Corpus 打分 (毫秒级,主线程)
└─ 并行启动 N 个外部通道
├─ cannbot-knowledge (当前本地 worker)
└─ mindie-agent (C4 后续,不在当前 registry 中)
通道使用 daemon 线程并行派发,共享截止时间;describe/search 消费同一预算,避免 executor 退出时等待不返回的线程。超时取消已注册 worker/process group,丢弃迟到结果并保留本地结果。清理会增加短暂耗时;Python adapter、启动 factory 和 cleanup 必须协作,不能宣称任意 Python 代码具有硬墙钟或安全隔离保证。POSIX 后代进程回收有回归测试;Windows 原生进程树专项验证仍待完成。
| 参数 | 默认 | 说明 |
|---|---|---|
--external-timeout |
8 秒 | 外部并行请求共同 deadline;含 describe/search,清理另有短暂耗时 |
--no-external |
关闭 | 只用本仓结果(CI 与离线场景) |
--external-limit |
通道默认 | 覆盖单通道返回条数 |
| 通道 | 默认条数 | 理由 |
|---|---|---|
cannbot-knowledge |
100 | 维护者后续决定;返回上限,可覆盖为 1–200,不是语料总数 |
mindie-agent |
5 | 返回 navigation_only 的 ref 定位符,粒度更粗;过多会淹没本地结果 |
find 默认启用外部路径,但只有显式批准的项目 checkout/interpreter、有效 backend 和 platform 才会查询;全新安装无外部授权。CI 与单测必须显式传 --no-external,以隔离外部通道可用性对基线的影响。
超时必须映射成 state:"timeout" 并附 elapsed_ms,绝不能表现为空结果。"查了但超时"与"查了没命中"是两种事实,混同会让 Agent 误判为"上游没有这个知识"。
| 缓存对象 | TTL | 理由 |
|---|---|---|
describe() / discover |
当前不缓存 | 原提案 300 秒 TTL 暂缓;另行定义身份、撤销授权及 revision 失效规则 |
| 通道授权状态与 checkout identity | 每次操作重新加载校验 | 不以缓存延长已撤销授权 |
| search 结果 | 不缓存 | query 空间无限,缓存会让"上游更新"不可见 |
当前不缓存发现或搜索结果;后续缓存需单独评审失效规则。
5.5 cannbot-knowledge 接法
C0–C3 当前文件:project.py 管理授权和 worker 调用,read_worker.py 执行有界捕获、源协议校验及卡片读取,init.py 提供 Channel adapter。原分层提案中的 context.py/worker.py 已合并到这三处;mcp.py、receipt.py 仍为 C5/C6 后续项。
| 文件 | 职责 | 交付状态 |
|---|---|---|
| project.py | 逐项目 grant、参数校验、worker 调用 | C0–C3 当前 |
| read_worker.py | 2 MiB 捕获、源 JSON/schema 校验、卡片身份及读取 | C0–C3 当前 |
| init.py | CannbotChannel adapter | C0–C3 当前 |
| mcp.py | stdio MCP 代理 | C5 后续 |
| receipt.py | 最小化 receipt | C6 后续 |
授权文件:
{
"schema": "inferrsi-cannbot-project/1",
"project_root": "<project-abs-path>",
"upstream": "<approved-source-abs-path>",
"checkout_identity": {"device": 0, "inode": 0, "created": 0},
"python": "<venv>/bin/python",
"backend": "ascend",
"platforms": ["a2"]
}checkout_identity 抄 MindIE 的做法(.git 的 device + inode + birthtime),防止 grant 被复制到另一个 clone 误用。原设计名 default_platforms 在当前 grant 中为 platforms。首版配置一个默认值,find/search 的 --platform 优先于 grant 首个默认值;两处均无值时 rejected 并附修复提示。每次只传一个平台,不隐式采用上游多平台交集。backend 选择与查询传输授权分开:只运行已批准本地 checkout/interpreter,不配置远端目的地;--no-external 不启动外部 worker。
5.6 MindIE Agent 接法(C4 后续,命令接口待单独实现)
不重写,加一层 adapter 让现有 call() 满足 Channel 协议:
| 现状 | 改造 |
|---|---|
call("query", args) 返回 repository.query(navigation_only=True) |
adapter 映射为 ChannelResult |
ref 形如 mindie://<domain>/units/<id>@<gen> |
作为 locator |
| grant 无 backend | 增可选 backend 字段 |
ReadFailure 区分失败 |
映射到 not_enabled / version_mismatch / rejected |
mindie-agent 的 describe 已有:repository.available() + component_version(版本钉 0.13.13,read_worker.py:24)。
6. 为什么不采用其余形态(要点)
- C 全量转换:尚无已确认的分发依据,另有体积、同步和权威来源治理成本;外部卡不能直接标为 locally_verified。不采用该形态,不作所有分发均非法的结论。
- B submodule:需明确集成方义务、克隆体积和来源可达性;本轮未选择,不以其他项目的做法证明本来源获准。
- A/A′ 外链锁缓存:机制正确但与 MCP 重叠——两者都在解决"如何引用外部内容",而 MCP 让上游承担索引与治理。保留为未来若需要"完全离线复现"时的备选,当前不实现。
7. 证据与许可
7.1 receipt 最小化元数据(C6 设计)
{
"schema": "inferrsi-external-receipt/1",
"channel": "cannbot-knowledge",
"revision": "92dc260756e91e72e6dcd60f3996a4d54f43c8f5",
"index": {"schema": "cannbot-knowledge-index.v1", "version": 3,
"content_fingerprint": "0047983f..."},
"platforms": ["a2"],
"hits": [{
"locator": "ops/ascendc/apis/utils_api/cpp_stdlib/math_functions/ceil_division",
"card_sha256": "<raw-byte-sha256>",
"status": "stable", "platforms": ["a2", "a3"]
}],
"delivered": "locators_only",
"locally_verified": false
}不含卡片正文、不含 frontmatter 全文、不含 local_path。 前两者会把 CANN OSL 内容带进 evidence/(把许可问题从 data/ 原样搬到 evidence/);后者是个人绝对路径,违反隐私规则。
card_sha256 标识卡片字节,revision 标识观察到的 checkout,不证明来源闭包已恢复。公开 receipt 默认只保留已批准的来源、卡片 ID、平台、revision、摘要与交付状态;省略原始 query/decision、路径、正文及派生摘要。访问权限、发送查询权限和发布 receipt 权限分别判断;摘要不替代发布授权。C6 尚未实施。
7.2 引用话术与验证状态
引用外部结论必须写成 cannbot-knowledge @ <commit> 或 mindie-knowledge 0.13.13 / <domain>@<gen>,并显式标注 locally_verified=false。外部命中本身不产生 PASS。卡片可供参考;验收仍需核验所需 sources、entrypoint、required_resources 和依赖摘要。要求来源闭包却未恢复时显式拒绝或 INCONCLUSIVE,不削弱 Bundle 检查。
8. 代码改动清单
| # | 文件 | 改动 | 交付状态 |
|---|---|---|---|
| 1 | knowledge/channels.py | Channel/Status/Hit/Result/Registry/Request 和有界并发 | C0 当前 |
| 2 | knowledge/knowledge_find.py find() | registry、backend、platform、external_limit、external_timeout;external[] | C1 当前 |
| 3 | knowledge/knowledge_find.py load_corpus | 不改语料或评分 | 不变量 |
| 4 | knowledge/knowledge_operations.py AUTHORITIES | 不新增 external Bundle 权威源 | 不变量 |
| 5 | apps/cannbot/ | project.py、read_worker.py、init.py | C2–C3 当前 |
| 6 | apps/mindie/ | channel adapter 和 backend grant 扩展 | C4 后续 |
| 7 | apps/cli/arguments.py | find 外部门控/预算参数及 cannbot enable/disable/describe/search/read | C1–C3 当前 |
| 8 | apps/cli/init.py | find 外部展示及 cannbot 分发 | 当前;serve/import 留待 C5/C6 |
| 9 | tests/ | fake channel、真实 CLI 边界、显式启用的真实源验收 | 当前测试,区别执行/跳过 |
第 2 条的不变量: registry 为空或 --no-external 时保持本地 find 结果;开启、空结果、失败及乱序完成均不得更改本地排序和内容。CLI 无授权时额外展示外部状态,不能把这一提示误称为原 CLI 全输出逐字节相同。
第 4 条的理由: 不把 external 加进 AUTHORITIES,意味着 find 的 read_args / open_argv 不会指向外部卡(避免生成一个执行即错的命令),外部读走独立的 cannbot read。
9. 使用方式
9.1 首次配置(每台机器、每个 checkout 一次)
inferrsi cannbot enable \
--checkout ~/src/cannbot-knowledge \
--python ~/venvs/cannbot/bin/python \
--backend ascend \
--platform a2
前置条件由用户负责:上游要求 Python 3.10+、uv、完整 checkout、索引已构建。
自查与自修复:
inferrsi cannbot describe
# {"state":"ok","revision":"92dc2607...","cards":10550,
# "index":{"version":3,"content_fingerprint":"0047983f..."}}state: index_stale
detail: index built at <old> differs from checkout <new>
fix: cd ~/src/cannbot-knowledge && python3 .agents/skills/knowledge-query/scripts/knowledge_index.py build
9.2 日常检索(Ascend 任务,常驻双查)
$ inferrsi find "AscendC tiling 参数怎么算" --backend ascend本仓 (backend=ascend)
1. ascendc-tiling-design score 42.1
2. ascend-performance-analysis score 31.7
外部通道
cannbot-knowledge @ 92dc2607 ok 1.5s 3 hits
1. Matmul Tiling类使用说明 18.4 ops/ascendc/apis/.../cube_compute/matmul_tiling
2. 使用高阶API时配套的Tiling实现 17.9 ops/ascendc/guides/.../tiling
3. Matmul tiling 形状与核数推导链 17.2 ops/ascendc/guides/.../derivation_chain
→ inferrsi cannbot read <locator> --sha256 <card_sha256> --revision <revision>
本仓有命中时照样查询已授权 cannbot;本地与外部各自一段,分数不跨栏比较。MindIE 加入 find 属于 C4 后续。
9.3 非 Ascend 任务 / 未声明 backend
$ inferrsi find "CUDA graph capture" --backend cuda
# 只查本仓;当前无匹配通道时省略 externalexternal: [{"channel":"cannbot-knowledge","state":"not_enabled",
"fix":"inferrsi cannbot enable --checkout <path> --python <interpreter>"}]
9.4 读外部卡正文
inferrsi cannbot read ops/ascendc/apis/utils_api/cpp_stdlib/math_functions/ceil_division
inferrsi cannbot read <locator> --revision <revision> --sha256 <card_sha256>
inferrsi cannbot read <locator> --revision <revision> --sha256 <card_sha256> --page 2生成的 open 同时携带 revision 和 raw-byte SHA256,分页保留两者。read 校验实际 HEAD、卡片字节和读后 HEAD;版本漂移返回 version_mismatch,字节漂移 rejected,均提示重新搜索;成功返回观察到的 revision 和摘要。locator-only 读取当前内容。前后检查不是原子快照,不提供旧版本重放。正文仅交付调用方,不由本实现保存或加入 receipt。
9.5 Agent 挂载(C5 后续,当前不可用)
inferrsi cannbot serve # stdio MCP:discover / search / read_card透传,不收窄。 三工具的名称、参数与语义与上游一致,只多一层授权检查、receipt 与错误归一化。理由:自造收窄契约会在上游演进(新增过滤参数、search schema 从 v5 升级)时变成必须同步维护的负债,而透传可依靠 schema_version 直接暴露差异。授权检查、receipt、错误归一化都在这一层完成。
9.6 进 campaign evidence(C6 后续,当前不可用)
inferrsi cannbot search "CeilDivision 向上取整" --platform a2 \
--receipt .inferrsi/receipts/ceil.json
inferrsi campaign import-cannbot .inferrsi/receipts/ceil.json10. 切片
| 片 | 内容 | 依赖 | 可独立合入 |
|---|---|---|---|
| C0 | channels.py 协议 + fake channel + 全部 state 的测试 |
— | ✅ |
| C1 | find() 融合 + --backend 门控(只接 fake channel) |
C0 | ✅ |
| C2 | apps/cannbot/ 的 enable/disable/describe |
C0 | ✅ |
| C3 | cannbot search / read(worker + 子进程) |
C2 | ✅ |
| C4 | MindIE channel adapter + grant backend |
C0 | ✅ |
| C5 | cannbot serve(stdio MCP 代理) |
C3 | ✅ |
| C6 | receipt.py + campaign import-cannbot 统一 |
C3、C4 | ✅ |
C1 先行的理由:它把"平台门控 + 分栏 + 超时语义"这套契约钉死,之后两个真源接入都只是实现 Channel,不会反过来改 find 的输出结构。
C4 建议紧跟 C0,因为 MindIE 已有 call() 与 describe(),adapter 成本低,能最早验证协议抽象是否成立。
11. 风险
| # | 风险 | 现状 | 缓解 |
|---|---|---|---|
| R1 | 热路径增加查询成本 | 观测值不是延迟保证 | 并行共同 deadline + --no-external;缓存暂缓 |
| R2 | 破坏本地检索确定性 | 有回归覆盖 | backend 参数优先于 grant,均无值时不查;--no-external 零调用;开启、失败、空集均保留本地结果 |
| R3 | 上游索引过期导致"昨天能查今天不能查" | 上游 fail-closed | state: index_stale + fix;不做静默重试 |
| R4 | 平台枚举不可映射(a2/a3/950/310p vs ascend) |
未决 | grant 声明 backend + platform 两级;未知值拒绝,不猜 |
| R5 | 内容或私有查询进入公开记录 | C6 尚未实现 | 默认省略正文、query/decision、路径;仅已批准最小元数据 |
| R6 | 两套评分被下游误混 | 已设计 | score_scale 字段 + 分栏结构 + notes |
| R7 | uv / 完整 checkout 在 CI 不可用 |
未验证 | 单测只用 fake channel;真上游走人工验收 |
| R8 | MindIE 0.13.13 版本钉导致升级即断 | 现有行为 | state: version_mismatch + fix |
12. 关闭条件
本文作为 RFC 关闭时应当满足:
- 评审接受 §5 的通道契约(
Channel协议、state枚举、external[]结构、score_scale)。 - 评审接受 §5.2 的平台门控语义:显式声明、单值、不推断。
- 评审接受 §7 的最小化 receipt 形状与使用/传输/发布权限边界;Q1(CANN OSL 立场)有组织层面的答复或明确接受为"实施前再定"。
- 评审接受 §5.4 的默认值:
find默认查外部、每通道 100/5、共同预算 8 秒及清理边界。 - 确认 §8 第 2 条与第 4 条不变量写入测试。
- 明确与 #388 / #387 的关系:本文不关闭 rfc: 外部技能内容的依赖、版本锁定与可复现导入(外链或 submodule 待决) #388,
external[]需在 rfc: K/H/B 与 Apps 公开接口详细设计(最小交接与模块边界) #387 的 schema 中登记。 - 分别追踪实施切片(C0–C6)与审批;PR feat(knowledge): add external read-only channels to find #484 是已授权 C0–C3 的交付记录,不表示本 RFC 或 rfc: 外部技能内容的依赖、版本锁定与可复现导入(外链或 submodule 待决) #388/rfc: K/H/B 与 Apps 公开接口详细设计(最小交接与模块边界) #387 已完成。
13. 相关
- #388 外部技能内容的依赖、版本锁定与可复现导入(治理 RFC,仍 Open)
- #387 K/H/B 与 Apps 公开接口详细设计(
read/collect,仍 Proposed) - #362 三模块目标架构(已接受方向)
- #91 SearchSpace 蒸馏覆盖跟踪(本仓内唯一权威来源路径)
- #43 历史
license: UNKNOWN与许可链遗留约束 - #466 统一
find检索(本文接入的宿主接口) - #114 cann/cannbot 固定阶段证据蒸馏入库(既有蒸馏先例,不是外部依赖机制)
14. 参考实现(外部)
- cann/cannbot-knowledge:OKF v0.2 + CANNBot Profile,自带 governance / Query / Lint / MCP。
- NVlabs/kda:submodule 钉版本 + README 锁表 +
third_party_licenses/逐件许可 + 明确"submodule 不受本仓一方许可覆盖"。可借的是纪律,不是形式。
Activity
jiangkuaixue123 commentedon Nov 17, 2026
cc @jiaran-king @david6666666 @fake0fan
david6666666 commentedon Nov 17, 2026
Could we separate a verified card snapshot from eligibility as evidence? A’s lock covers the
knowledge/subtree, not the external files named insources[].resource, and A′ may have only index metadata. Keep those cards discoverable, but do not mark them evidence-eligible unless the required sources resolve at a verified revision and digest. Please add a negative fixture where the card digest matches but a cited source is missing or has drifted: search should still find the card, while evidence use should be rejected.Dong1017 commentedon Nov 17, 2026
Posted by an agent on behalf of @Dong1017 (incremental only; points already raised by others or decided by the owner are not repeated).
Incremental note: §5 rates A′ as "✅ 元数据可再分发", but invariant 2 in §7 forbids external content and its derived summaries in
knowledge/dataand the wheel. The RFC should say where the A′ index lives and which license position covers it before reviewers compare A′ with B.id / title / description / tags / status / platforms / sourcesfrom the frontmatter.titleanddescriptionare upstream Chinese prose written under the same license as the card bodies. The RFC's own §3.1 reading (non-transferable, non-sublicensable) applies to them as much as to the bodies. So "redistributable" is not established; it is part of Q1.AGENTS.md:101,docs/contributing.md:80: library content in English). Please pick one reading and add it to the A′ section, and add a matching negative fixture next to @david6666666's source-drift fixture: derived metadata appearing undersrc/inferrsi/knowledge/data/must fail CI.6c7e2379, thesrc/inferrsi/knowledge/data/git tree is 921 files and 6,296,420 bytes (6.0 MiB). 7.8 MiB looks like a filesystem-dependentdufigure. Against the 118 MiB body, the growth is about 20× rather than 15×. The conclusion does not change.Scope: read the RFC body and the two comments, the license and language rules on main
1acfacf8, andgit ls-tree -lat6c7e2379. I did not read the upstream LICENSE or OKF schema at gitcode, so this is not a license opinion.zengchuang-hw commentedon Nov 17, 2026
独立 RFC 检视:暂不能据此确认选型/许可可行性;建议先修正契约再接受实施切片。
检视基准:本 Issue 当前正文、#388 原始需求,以及 main
1bbc3b0c8de14d6194d7ee7987607365b665fbfe的 AGENTS、知识库契约、pyproject.toml、knowledge_operations.py与knowledge_store.py。未阅读其他人的评审/讨论意见;本轮不授权导入、复制、分发或实施。“不进包”不是许可已成立的证明。 A 的“无许可冲突”、A′ 的“元数据可再分发”、D 的“许可可分发 ✅”应改为“待针对使用方式确认”。本仓保留的 CANN 2.0 文本 对使用目的也有限制,不仅约束分发;同时它包含有条件分发条款,不能单凭 non-sublicensable 就推导“所有分发都非法”。这份历史 cannbot 文本也不能代替 cannbot-knowledge 指定 revision 的逐项许可核验。建议把本地缓存、元数据抽取、向模型传输、镜像/再分发分别列为待确认动作;我不作法律批准。
A′ 与 §7.2 自相矛盾。 A′ 提取 title/description 等并承诺元数据可分发,而 §7.2 禁止外部内容及派生摘要进入包。需明确索引也放包外,或先得到逐字段的分发依据,再修订该不变量。不能因为字段名叫 metadata 就视为自动获准分发。wheel/sdist、日志及 evidence 的负例检查也应覆盖这些派生文本,而不只检查正文目录。
锁定卡片不等于证据闭包完整。 当前 Bundle.manifest 要求 entrypoint、声明的 required_resources 和依赖字节实际存在且与摘要一致。若 sources.resource 尚未恢复,应区分“卡片字节可重放”和“来源证据可复核”,不把
resource_closure: external-unrestored与矩阵中无条件“证据资格可”并列。建议允许有界 discovery,但在要求来源闭包的消费场景显式拒绝/INCONCLUSIVE;不可为外部源放松现有完整 Bundle 检查。“全量”统计尚未闭合。 正文的领域计数合计 10,550,但 status 和 type 两组各只合计 10,327,均差 223。接受 Q2 前需给出同一 revision 的扫描命令、文件集合定义及这 223 项的归类/无效状态;不能直接把 draft/deprecated 或未归类项纳入默认可信召回。这是对正文数字的独立算术检查,不是上游重扫描结果。
先把建议与必须修改的接口分开。 当前 AUTHORITIES 确为 package/checkout/store,skill_root 为本地 Path;但是否增加 external、采用适配器还是单独外部 discovery 接口,仍需 rfc: K/H/B 与 Apps 公开接口详细设计(最小交接与模块边界) #387/rfc: 外部技能内容的依赖、版本锁定与可复现导入(外链或 submodule 待决) #388 的边界决策。“来源 unavailable / 格式非法 / 许可未知”之外,建议补上缓存被替换、路径逃逸/符号链接、索引与正文跨 pin 混配、来源资源未恢复这四类负例。验收时比较同一 pin 的搜索/读正文可用性,别把不可达镜像静默换成 latest。
倾向:包外、显式启用、锁定版本的 A/A′ 可作为工程试验候选,而非已经解决许可问题的最终方案;默认搜索不混入未明确状态的外部材料。D 是否能绑定 revision 应取决于实际服务协议,不能仅凭 MCP 形式判定绝对不可复现。
已做:读取上述固定 main 文件与 #388;核对打包 glob、authority/Bundle/存储保护实现;复算统计;查阅上游 README 的公开检索结果以确认其声明的许可名称。未做:上游指定 commit 的完整克隆/许可证与资源闭包验证、10,550 卡重扫、适配器实现、运行时/性能测试、组织许可确认。上游直接页面本次不可达,因此不把索引结果或历史许可证当作指定 revision 已核验。
[-]rfc: 全量接入 cannbot-knowledge 的候选形态与许可边界[/-][+]rfc: 全量接入 cannbot-knowledge:MCP 常驻查询通道设计[/+]jiangkuaixue123 commentedon Nov 17, 2026
附件:独立设计文档《外部知识通道设计:cannbot-knowledge 与 MindIE Agent 的常驻查询接入》
本附件是 §5–§9 的展开版,包含实测数据、通道协议、并行/缓存模型、receipt 形状与完整的使用方式。正文 §5 已吸收其结论;若两者冲突,以正文 §5 与本评论下方「已定决策」一节为准。
GitHub Issue 不支持文件附件,故以折叠附录形式收录全文(本地镜像路径:
docs/plans/2026-11-17-external-knowledge-channels.md)。展开全文(457 行)
外部知识通道设计:cannbot-knowledge 与 MindIE Agent 的常驻查询接入
0. 相对前一版的关键变更
前一版设计把外部通道当作补漏:本地
find零命中时才提示外部存在。本文改为常驻并行查询:no_match == trueexternal_channels提示条目external[]实际检索结果ascend任务常驻查询,其他平台不触发理由:Ascend 任务的真实知识分布是"本仓有 14 篇流程型 skill,上游有 10,550 张 API/算子卡"。只在零命中时查,等于假设"本地一旦有命中,外部就没有增量"——这个假设在粒度互补的场景下明显不成立(本仓命中"如何设计 tiling 流程",上游同时有"
Matmul Tiling类的具体参数")。1. 现状与约束(实测)
1.1 本仓知识侧
find实现src/inferrsi/knowledge/knowledge_find.py,commit61303fa8(#466 统一检索)idf × 字段权重 × sqrt(出现次数),FIELD_WEIGHTS见knowledge_find.py:42kinds=("case","skill","record"),load_corpus见:620SKILL.md+ 128 条记录 + cases,同进程内构建1.2 cannbot-knowledge MCP 侧
rank/score/match_basis/path/local_path/card_lines/card_sha256knowledge-search.v5,含request_sha256与index.repository_state.commit--platform必填,缺失即报错(fail-closed,不混合各平台)index_stale,不自动重建discover/search/read_card,全部read_only1.3 MindIE Agent 侧
src/inferrsi/apps/mindie/(639 行)knowledge_query/knowledge_explainsubprocess.run([grant["python"], "-I", "-B", worker, ...]),project.py:103mindie-knowledge == 0.13.13硬校验,read_worker.py:24~/.config/inferrsi/mindie-projects/<sha256>.jsonrepository.query(navigation_only=True),返回 ref 定位符1.4 由此产生的设计约束
idf建立在 143+128 条语料上,上游建立在 10,550 张卡上;同一个词在两边的 idf 与权重体系完全不同。任何"混合排序"都需要我们自己发明一个归一化函数——那是本轮 RSI 明令禁止的"编造分数"。find的毫秒级是数量级差异,且失败模式有七种(未授权 / 不可达 / 索引过期 / 平台未知 / 超时 / 协议错 / 上游拒绝)。find的结果无法被任何人复现。path+card_sha256+revision。2. 核心设计:通道抽象 + 平台门控 + 分栏呈现
2.1 通道抽象
新增
src/inferrsi/knowledge/channels.py,把两个外部源收敛到同一协议,使find不认识具体是 cannbot 还是 MindIE:ChannelHit字段固定:locator/title/summary/score/score_scale/status/platforms/card_sha256。score_scale是关键:标明这个分数来自哪套评分("cannbot/knowledge-search.v5"或"mindie/graded-0.13.13"),从结构上阻止调用方跨通道比较。2.2 平台门控(决定"要不要查")
数据流:
backend来源优先级:inferrsi find --backend ascend(显式参数,最高)cannbot enable --backend ascend)backend_unknown,不猜--backend只接受单值。一次调用只能声明一个 backend;同时涉及 Ascend 与 CPU host 侧等多平台任务,由调用方分两次查询并各自保留结果。理由:多值会让输出无法回答"这条外部结果是为哪个平台召回的",而外部源的平台纪律本身是 fail-closed 的(上游--platform要求明确目标平台,不混合各平台结果),本仓不应在门控层放宽这一语义。这里刻意不使用
named_backends()(knowledge_find.py:739)那种从查询词推断的方式:从"这个 query 里出现了 asc"推断"这个任务是 Ascend 任务"是不可靠的,且失败形态是静默查错平台。门控必须是显式事实。2.3 分栏呈现(决定"怎么放")
不做混合排序。 输出结构:
{ "query": "AscendC tiling 参数", "backend": "ascend", "items": [ /* 本仓结果,沿用现有 ranked list */ ], "matched": 3, "external": [ { "channel": "cannbot-knowledge", "state": "ok", "revision": "92dc260756e91e72e6dcd60f3996a4d54f43c8f5", "elapsed_ms": 1520, "score_scale": "cannbot/knowledge-search.v5", "items": [ { "locator": "ops/ascendc/apis/simd_api/adv_api/cube_compute/matmul_tiling", "title": "Matmul Tiling类使用说明", "score": 18.4, "status": "stable", "platforms": ["a2", "a3"], "card_sha256": "049b4824...", "open": "inferrsi cannbot read ops/ascendc/apis/simd_api/adv_api/cube_compute/matmul_tiling" } ] }, { "channel": "mindie-agent", "state": "not_enabled", "detail": "no project grant for this checkout", "fix": "inferrsi mindie enable --domain <d>" } ], "notes": [ "External results are not locally verified; scores are not comparable across channels.", "Pin external revisions from this output when citing them." ] }三条不可退让的规则:
items只放本仓结果。 外部命中不进items,避免任何下游按items处理时会静默把未验证内容当成已验证。state。 一个通道失败不影响另一个;失败必须可见并附fix。score。 每个通道内部排序,跨通道并列。需要合并时由调用方决定,不由find代劳。3. 执行模型:并行、预算、降级
3.1 并行
用
concurrent.futures.ThreadPoolExecutor,通道之间无共享状态。总耗时 ≈ max(各通道),而不是 sum。3.2 预算与降级
--external-timeout--no-external--external-limit每通道条数默认值:
cannbot-knowledgepath即 Concept ID),多给几条能让调用方一次选中正确粒度mindie-agentnavigation_only的 ref 定位符,粒度更粗;过多会淹没本地结果find默认即带外部查询(不带--no-external),因此 Ascend 任务开箱就是双查。CI 与单测必须显式传--no-external,以保证基线不受外部通道可用性影响。超时必须映射成
state: "timeout"并附elapsed_ms,绝不能表现为空结果。"查了但超时"与"查了没命中"是两种事实,混同会让 Agent 误判为"上游没有这个知识"。3.3 缓存
describe()/discover缓存落在内存,不落盘;落盘缓存会引入"缓存里的 revision 与当前不一致"的经典问题。
4. 两个通道的具体接法
4.1 cannbot-knowledge
新增
src/inferrsi/apps/cannbot/,结构镜像apps/mindie/:project.py~/.config/inferrsi/cannbot-projects/<sha256(repo)>.jsoncontext.py_object/_invalid_constant)worker.pyknowledge_query.py search/read或 MCPsearch/read_cardmcp.pyreceipt.py授权文件:
{ "schema": "inferrsi-cannbot-project/1", "checkout": "<abs-path>", "checkout_identity": {"device": 0, "inode": 0, "created": 0}, "python": "<venv>/bin/python", "backend": "ascend", "default_platforms": ["a2"], "enabled_at": "<iso8601>" }default_platforms让常用平台不必每次传;未声明时search直接报错(与上游 fail-closed 一致)。4.2 MindIE Agent
不重写,增加一层 adapter 让现有的
call()满足Channel协议:call("query", args)返回repository.query(navigation_only=True)ChannelResultmindie://<domain>/units/<id>@<gen>locatorbackend字段,默认ascendstate由ReadFailure区分not_enabled/version_mismatch/rejectedmindie-agent的describe已有:repository.available()+component_version。5. 证据与许可
5.1 receipt 只存定位符
{ "schema": "inferrsi-external-receipt/1", "channel": "cannbot-knowledge", "revision": "92dc260756e91e72e6dcd60f3996a4d54f43c8f5", "index": {"schema": "cannbot-knowledge-index.v1", "version": 3, "content_fingerprint": "0047983f..."}, "query": "CeilDivision 向上取整", "platforms": ["a2"], "decision": "确认 a3 上的取整语义", "hits": [{ "locator": "ops/ascendc/apis/utils_api/cpp_stdlib/math_functions/ceil_division", "card_sha256": "b97cbe82492d25cc0363d1852eddcf87d991c9d75a57891a9aed3e75188ffc86", "status": "stable", "platforms": ["a2", "a3"] }], "delivered": "locators_only", "locally_verified": false }不含卡片正文、不含 frontmatter 全文、不含 local_path。 原因:前两者会把 CANN OSL 内容带进
evidence/,把许可问题从data/原样搬到evidence/;local_path是个人绝对路径,违反隐私规则。card_sha256的作用是"我引用的确实是这一版这张卡",且摘要不构成再分发。5.2 引用话术
引用外部结论时必须写成:
cannbot-knowledge @ <commit>或mindie-knowledge 0.13.13 / <domain>@<gen>,并显式标注locally_verified=false。外部命中不参与PASS判定(沿用AGENTS.md的证据纪律)。6. 代码改动清单
knowledge/channels.pyChannel/ChannelStatus/ChannelHit/ChannelResult/ChannelRegistryknowledge/knowledge_find.py:732find()channels、backend、external_limit、external_timeout参数;并行调度;输出external[]channels=None时行为与现在逐字节一致knowledge/knowledge_find.py:620load_corpusknowledge/knowledge_operations.py:25AUTHORITIESapps/cannbot/*apps/mindie/channel.pyadapter;grant 增backendapps/cli/arguments.pyfind增--backend/--no-external/--external-limit/--external-timeout;新增cannbot子命令组apps/cli/__init__.pycannbot;campaign import-cannbot/import-mindie统一tests/state第 2 条的不变量:
channels为空或--no-external时,find的输出必须与 #466 之后的行为完全一致。 这条要写成测试,否则外部通道会悄悄改变现有 143 篇 skill 的排序基线。7. 使用方式
7.1 首次配置(每台机器、每个 checkout 一次)
自查:
失败时直接给修复命令:
7.2 日常检索(Ascend 任务,常驻双查)
$ inferrsi find "AscendC tiling 参数怎么算" --backend ascend输出(示意):
要点:本地有命中时照样查外部;两个通道各自一段;分数不跨栏比较。
7.3 非 Ascend 任务
不传
--backend且 grant 未声明时:7.4 读外部卡正文
正文只在终端呈现,不落盘、不进 receipt。
7.5 Agent 挂载(Claude Code / Codex)
inferrsi cannbot serve # stdio MCP:discover / search / read_card透传,不收窄。 三个工具的名称、参数与语义与上游保持一致,只是多一层授权检查、receipt 与错误归一化。理由:自造一层收窄契约会在上游演进(例如新增过滤参数、
searchschema 从 v5 升级)时变成必须同步维护的负债,而透传可以靠schema_version字段直接暴露差异。在 agent 配置中注册一条命令即可。7.6 进 campaign evidence
8. 切片
channels.py协议 + fake channel + 七种 state 的测试find()融合 +--backend门控(只接 fake channel,不接真源)apps/cannbot/的enable/disable/describesearch/read(worker + 子进程)backendcannbot serve(stdio MCP 代理)receipt.py+campaign import-cannbot统一C1 先行的理由:它把"平台门控 + 分栏 + 超时语义"这套契约固定下来,之后两个真源接入都只是实现
Channel,不会反过来改find的输出结构。9. 风险与未决
describe缓存 300s +--no-externalfind的确定性与离线可测--backend时不查外部;--no-external关闭全部通道;fake channel 覆盖全部 state;两种路径下的输出都逐字节固定state: index_stale+fix;不做静默重试a2/a3/950/310pvsascend)backend+platform两级;未知值拒绝,不猜local_pathscore_scale字段 + 分栏结构 +notesuv/ 完整 checkout 在 CI 不可用state: version_mismatch+fix,与现状一致已定决策
以下四项已确认,不再是待决项;实现按此执行,若需变更须另行评审。
--backend是否允许一次声明多个find默认是否带--no-external--no-external,以隔离外部通道可用性对基线的影响external[]每通道默认条数cannbot-knowledge10 条 /mindie-agent5 条。 上游定位符精确到path且平台过滤已生效,多给几条有助于一次选中正确粒度;MindIE 返回粗粒度 ref,过多会淹没本地结果cannbot serve的 MCP 面discover/search/read_card三工具,名称、参数、语义保持一致;只增加授权检查、receipt 与错误归一化。不收窄,以免在上游searchschema 升级时产生必须同步维护的自造契约10. 与既有文档的关系
find新增的external[]属于 Knowledge 公开接口的一部分,需在 #387 的 schema 中登记AGENTS.mdPASS;引用须带 revision 与locally_verified=falsedavid6666666 commentedon Nov 17, 2026
Could the RFC separate platform selection, permission to send a query, and permission to publish its receipt? The §5.5 grant identifies a checkout and interpreter, while §7's example still persists raw
queryanddecisiontext. Those can contain private model names, paths or logs even when no card bodies are stored. Keep local transport distinct from explicitly authorized remote destinations; public receipts should contain only approved metadata, not those text fields by default. A synthetic query containing a private marker should not reach an unauthorized remote channel or appear in exported evidence.zengchuang-hw commentedon Nov 17, 2026
独立设计增量检视(关联新增设计材料入口 #issuecomment-6943680953)
结论:分源并行检索的方向与现有本地检索可分离实现,但详细规范仍需形成可验证合同;本轮不批准实施或宣布验收通过。
本意见已更新纳入完整附件的隔离“方案/目标”提取,剔除了作者论据、实测结论、声称已定的决策和他人评议。未直接读取原附件、原 Issue 正文或其他评审;隔离材料不是逐字完整的规范,不能据此断定所有状态/默认值已经一致。
代码检查固定于 main
61303fa8150472dfbda62ec8d77908bc05c73f3b,以下是独立判断:保持独立 Corpus 是必要约束,不只是显示样式。 当前 Corpus 的 IDF 和正文长度归一化依赖整个语料;find 再统一截断 limit。因此把外部文档加进本地 Corpus 后再分栏会改变本地排序。方案提出本地 items 不动、每源独立块/分数、无跨源合并排名,方向正确;实现应由组合层封装未经改写的本地 find 结果。验收不应仅覆盖外部关闭,也应证明开启、空结果、超时、乱序完成时本地完整结果仍相同。
明确平台/配置的权威顺序与请求边界。 提取材料已提出未知平台不猜测、不匹配不查询、显式离线路径;这比复用查询词推断 backend 更清晰。仍需规范 CLI 与 per-checkout 配置冲突时谁生效、平台映射及未知值处理、配置能否扩大可访问来源、关闭是否保证零网络/worker调用。“配置了平台”本身不是传输私有完整查询的许可。外部全局预算与每源超时也需独立规定,不能用逐源限额代替总工作量上界。
统一每源状态和超时后的生命周期。 方案已区分失败与成功空集、隔离各源故障。完整精确 enum 尚未进入可审查的清晰合同,建议给一张 status×hits×revision×error 的有效组合表,禁止同一响应同时表示 success 和 timeout。子进程超过时限时不仅停止等待,还要终止/回收工作;迟到响应不能覆写本次结果或误归属下一次请求。独立来源失败不能清空本地/其他成功来源。字节上界、重复键和非有限数拒绝是有用的拟议解析约束,还需说明截断/超大响应的失败状态。
独立 read 要维护身份与版本,而不是传递任意执行命令。 现有 Document.view 生成本地 read_args/open_argv;KnowledgeReader authority 只有 package/checkout/store。提案中的独立 locator/read、source-specific score、revision/generation 和 digest 与这条隔离边界相容。必须明确同名跨源 ID 不碰撞、搜索到读取间版本变化如何拒绝或显式标识、revision不可提供时不能称可重放,以及可信适配器如何约束 locator/重定向/worker argv。不能把外部 ID 直接套入现有本地 read 命令或接受来源返回的可执行指令。
receipt 的最小化不止“去掉正文”。 方案已排除完整卡正文、完整 metadata/frontmatter 和本地绝对路径,且不持久缓存检索结果;这些约束应分别落实到响应、错误、日志、receipt、MCP返回与打包产物。提取中的 query/decision 文本字段仍可能包含私有内容,要确定默认省略/脱敏规则、保存位置和发布授权。来源可访问、包外存储、MCP形式都不自动证明许可或持续访问授权。外部发现/正文可读与完整证据闭包需分级;不要削弱现有 Bundle.manifest 对 entrypoint、required_resources、依赖摘要的检查。
建议先交付纯离线 fake-channel 合同切片。 提案已有该分层,适合先验证上述约束。补充对照矩阵:本地已有命中仍调用已启用外部;关闭/未知平台零调用;两个源同名 ID;一个超时另一成功;乱序响应及迟到回包;索引与正文 pin 不符;异常文本不能触发操作;开启前后本地结果逐字段相同。真实 upstream/host、许可与性能验收另列版本、权限和证据,不把 stub 测试算作来源已合格。
已做:核对作者 jiangkuaixue123/open;核对本人旧意见去重;读取安全设计提取;检查上述固定 main 的评分/Corpus、来源身份与读取、Bundle完整性及 apps 组合入口的 AST 安全视图。已读 AGENTS/review skill 相对该基准无变化。未做:原附件规范逐字完整性验证、实现、测试或实验执行、外部检索/正文读取、来源/许可/性能验证。
需要的下一份材料是清晰的协议 schema、状态表、平台配置优先级、worker/MCP权限与超时边界、receipt隐私规则及对应离线验收表;这是设计澄清请求,不是修改代码、联网或部署授权。
docs(knowledge): document that external channels are not installed
jiaran-king commentedon Nov 18, 2026
赞成用本地 MCP 接入 cannbot。它能补上 InferRSI 缺少的 Ascend API 和算子资料。建议首版在显式启用的项目里跑通一条完整链路,用
find搜到 cannbot 卡片,再打开正文。设计上把下面三点写清就可以推进。什么时候查。 项目显式启用 cannbot、绑定本地知识源并配置有效平台后,Ascend 查询才调用它。
--backend ascend负责选择后端,a2或a3这一级由项目配置提供。上游传多个platform取的是交集,首版约定一个生效的平台值就够。 上游search参数外部调用慢或失败时怎么返回。 保留 RFC 的
external[],本地继续用原语料独立排序。文本模式在本地no_match时也要展示外部命中,当前文本输出在这里会提前返回。外部正常零命中、超时和索引过期应能区分,超时后结束本次外部调用,照常交付本地结果。--no-external全程只走本地,外部调用次数为零。cannbot 可以沿用 8 秒和 10 条作为起始默认值。 当前文本输出打开哪一版、公开记录什么。 上游
read_card读的是当前卡片。打开时比较实际返回的版本和卡片摘要与搜索命中时的值,有漂移就提示重新搜索。公开 receipt 只保留来源、卡片 ID、平台、版本、摘要和交付状态,§7 示例里的原始query和decision可以删掉。读到卡片后可以将其用作参考,支持验收结论还要按现有证据规则核对所需的原始来源。MCP 避免了随包分发,上游许可仍应按实际使用和共享方式确认。 上游read_card· 隐私讨论 · 证据讨论 · 上游许可首版可以用测试替身覆盖关闭外部、外部超时、本地零命中和读卡前发生版本漂移,再用真实 cannbot 验一次搜索和正文读回。本次审阅核对了源码,真实链路留给首版验收。MindIE 通用适配、HTTP、托管优化流程接入和旧版本重放可以各自后续推进。
feat(knowledge): add external read-only channels to find (#484)
jiangkuaixue123 commentedon Nov 18, 2026
2026-11-18 ·
moe-forward-npu外部知识通道配对试验RFC 实验观测。cannbot 的平均增益及验收结论仍为
INCONCLUSIVE。 这是单对独立 Agent 会话,测量范围为 Ascend A3 上 BF16、EP=2 的一层完整 MoE forward(含路由、通信、专家计算与输出完成)。实验口径
013519c621359246a43444fad42f864455b21d7a,卡片来源标记locally_verified=false。观测结果
第 8 轮检查点的 B/A 加速比差异为 +37.3%。将两份最终快照互换设备后,同卡比较为 +31.7%(2.156× / 2.840×,A / B)和 +47.0%(2.013× / 2.960×,A / B)。原始独立复测与换卡复测均通过双 rank 正确性检查。换卡复测单独计时。
逐轮曲线
蓝线为 A,橙线为 B。纵轴为截至该轮的最佳有效搜索分数,起点为共同基线 1.000×。独立复测见上表。
%%{init: {"themeVariables":{"xyChart":{"plotColorPalette":"#2368B2, #B95219"}}}}%% xychart-beta title "MoE forward · 逐轮最佳有效加速比" x-axis "搜索轮次" ["0","1","2","3","4","5","6","7","8"] y-axis "相对共同基线(×)" 1 --> 3.1 line [1.000,1.257,1.963,1.963,1.963,2.016,2.016,2.107,2.107] line [1.000,1.000,1.061,2.520,2.772,2.772,2.820,2.820,2.962]B 的首轮多流尝试测得 0.971×。最终候选对小、中用例使用密集批处理,对大用例使用 BF16 分组矩阵乘,并将共享专家计算与异步 AllGather 重叠。中途一次外部读卡引出了本地算子适用性核对,候选继续遵守 EP=2。B 在前 4 轮检查点已经领先,两组到第 8 轮都继续改善。本次结果支持继续验证外部通道在优化搜索中的价值,单对会话无法拆分知识、候选选择和搜索轨迹的贡献。
jiangkuaixue123 commentedon Nov 18, 2026
2026-11-18 · Qwen-Image 2.1 denoiser 外部知识通道配对试验
RFC 实验观测。cannbot 的平均增益及验收结论仍为
INCONCLUSIVE。 本次是一对独立 Agent 会话,工作负载为qwen21-denoise-npu定义的单卡 Ascend A3 BF16 缩放 denoiser,覆盖 prefill、完整去噪步和 latent 轨迹输出。实验口径
find摘要。R1 前的托管正文超过 16 KiB 预算,R3 前的托管检索未命中,因此两组通过该入口收到的本地正文均为 0 字节。B 额外完成两次外部查询和两次按 revision / SHA‑256 校验的读卡。013519c621359246a43444fad42f864455b21d7a,卡片来源标记locally_verified=false。评估用独立 FP32 参考核对每一步 latent,分数取三个计时用例加速比的几何平均。观测结果
原分配下 B/A 加速比差异为 −2.64%。将两份最终快照互换设备后,同卡比较为 −1.73%(1.998× / 1.964×,A / B)和 −2.01%(1.986× / 1.946×,A / B)。原始独立复测和换卡复测均通过完整正确性检查。换卡复测单独计时。
逐轮曲线
蓝线为 A,橙线为 B。纵轴为截至该轮的最佳有效搜索分数。独立复测见上表。
%%{init: {"themeVariables":{"xyChart":{"plotColorPalette":"#2368B2, #B95219"}}}}%% xychart-beta title "Qwen-Image 2.1 denoiser · 逐轮最佳有效加速比" x-axis "搜索轮次" ["0","1","2","3","4"] y-axis "相对共同基线(×)" 1 --> 2.1 line [1.000,1.459,1.841,1.981,1.994] line [1.000,1.049,1.603,1.940,1.940]B R1 用
npu_rms_norm替换 Q/K 归一化。R3 读卡后,B 保留任务所需的带掩码 SDPA 并优化 Q/K RoPE。A 在 R3 验证了带掩码的融合注意力,portrait 候选中位延迟从 15.016 ms 降到 13.731 ms,landscape 从 20.531 ms 降到 17.776 ms。尚无基于同一 B 快照的单因素注意力替换结果。与 MoE 配对试验 对照,两次试验的观测方向不同,工作负载、轮次及本地正文交付也不同。下一轮可先对齐两组实际读取的本地正文,再用多对独立会话比较固定轮次下的收益与搜索成本。
david6666666 commentedon Nov 18, 2026
Could the next paired study report a fixed-resource comparison alongside the fixed-round curves? In the MoE pair, B finished at 2.960× vs. 2.156×, but the reported task also took 35:34 vs. 29:57. Please freeze the same search-time budget up front (including query/read time), select each arm’s best valid snapshot at that cutoff, then retest both under the same separate measurement budget. A per-arm receipt for delivered context and time spent retrieving, evaluating, and searching would make the cost/quality tradeoff auditable. Swapping the final snapshots across cards checks placement, not search cost.