/** * `kb` — the knowledge base as a tool the agent can ASK, from inside its own * session, in the middle of a run. * * ## Why a pull side exists at all * * Retrieval used to be push-only: the control plane picked what an agent would * need at the moment it dispatched the work, and that was the agent's only shot. * For standing knowledge that is exactly right — build-system and device facts * are chosen by platform and past usefulness precisely because they do not * depend on the ticket, and in production they are cited 43% of the time. * * For everything else it cannot work, and the production numbers say so without * ambiguity: pushed `experiment` knowledge was shown 89 times and cited 0, * `entry_path` 79 times and cited 7. Not because the knowledge is bad — because * the question had not been asked yet. A ticket title is written before anyone * has seen the screen; the entry path that matters is the one for the screen the * agent is stuck on forty minutes in. Nothing at dispatch time could have known * to send it. * * So: push what recurs regardless of the ticket, pull what only the moment can * know. * * ## What it prints * * A block whose `K` labels CONTINUE this run's numbering (the control plane * appends the hits to the same injected list the dispatch block came from), so a * pulled hit is cited exactly like a pushed one — `〔K7〕` in the report, `K7` in * the final `KB_USED:` line — and the effectiveness numbers keep working. * * ## What it never does * * Fail loudly. A miss prints "nothing found" and exits 0: the agent's correct * next move is its own research either way, and a tool that errors on an empty * result teaches it to stop calling the tool. Exit 1 is reserved for the tool * being broken (no control plane configured, network down) — a different fact, * and one the agent should not silently read as "the knowledge base is empty". */ import { CONTROL_INTERNAL, PROD_CONTROL_PLANE_URL, DEBUG_CONTROL_PLANE_URL, CLUSTER_SECRET_HEADER } from "../shared/src/protocol"; const CONTROL = ( process.env.CONTROL_PLANE_URL || (process.env.STREAMLINE_DEBUG ? DEBUG_CONTROL_PLANE_URL : PROD_CONTROL_PLANE_URL) ).replace(/\/+$/, ""); const TIMEOUT_MS = Number(process.env.KB_RECALL_TIMEOUT_MS || 8000); function parseArgs(argv: string[]): { flags: Record; rest: string[] } { const flags: Record = {}; const rest: string[] = []; for (let i = 0; i < argv.length; i++) { const a = argv[i]; if (!a.startsWith("--")) { rest.push(a); continue; } const key = a.slice(2); const next = argv[i + 1]; if (next == null || next.startsWith("--")) flags[key] = "true"; else { flags[key] = next; i++; } } return { flags, rest }; } const val = (flags: Record, key: string): string | null => { const v = flags[key]; if (v == null || v === "true") return null; const t = v.trim(); return t ? t : null; }; const USAGE = "用法:\n" + ` kb recall --target : "<你的问题>" [--kind entry_path,experiment] [--limit 6]\n\n` + "说明:\n" + " 按你的问题检索历史真机确证的知识,命中项接着当前 prompt 里的 K 编号往下排。\n" + " 查不到会直说 —— 那就按你自己的调研走,别把「没查到」当成「不存在」。\n"; /** * `bug:abc-123` → the two fields the control plane needs. Also accepts a bare id * (bug is by far the most common caller) rather than failing on a missing prefix * mid-run. */ export function parseTarget(raw: string | null): { targetKind: string; targetId: string } | null { if (!raw) return null; const m = /^(bug|feature|security)[:/](.+)$/i.exec(raw.trim()); if (m) return { targetKind: m[1].toLowerCase(), targetId: m[2].trim() }; const bare = raw.trim(); return bare ? { targetKind: "bug", targetId: bare } : null; } async function cmdRecall(argv: string[]): Promise { const { flags, rest } = parseArgs(argv); const target = parseTarget(val(flags, "target") || process.env.KB_TARGET || null); if (!target) { process.stderr.write(`缺少 --target :(或设置 $KB_TARGET)\n\n${USAGE}`); process.exit(2); } // The question may come as positional words or as --query; both read naturally // in a shell and an agent will use whichever it happened to see in the prompt. const query = (val(flags, "query") || rest.join(" ")).trim(); if (!query) { process.stderr.write(`缺少问题正文。\n\n${USAGE}`); process.exit(2); } const headers: Record = { "content-type": "application/json" }; if (process.env.CLUSTER_SECRET) headers[CLUSTER_SECRET_HEADER] = process.env.CLUSTER_SECRET; let data: { ok?: boolean; count?: number; block?: string | null; firstLabel?: string | null; known?: string[]; }; try { const res = await fetch(CONTROL + CONTROL_INTERNAL.kbRecall, { method: "POST", headers, body: JSON.stringify({ ...target, query, kinds: (val(flags, "kind") || val(flags, "kinds") || "") .split(/[,\s]+/).map((k) => k.trim()).filter(Boolean), ...(val(flags, "limit") ? { limit: Number(val(flags, "limit")) } : {}), }), signal: AbortSignal.timeout(TIMEOUT_MS), }); if (!res.ok) throw new Error(`${res.status}`); data = (await res.json()) as typeof data; } catch (err) { // The tool is broken, not the knowledge base empty. Say which, so the agent // does not record "no knowledge exists" as a finding about the base. process.stderr.write( `⚠️ 知识库检索没跑通(${(err as Error).message})—— 这是工具/网络的问题,不代表库里没有。\n` + " 按你自己的调研继续,不要因此下「无相关知识」的结论。\n", ); process.exit(1); } const known = Array.isArray(data.known) ? data.known : []; if (!data.block || !data.count) { // "You already have it" and "there is none" are different answers, and // collapsing them into the second is how an agent learns to stop asking. process.stdout.write(known.length ? `🔍 跟「${query}」相关的知识你已经拿到了:${known.join("、")} —— 回到 prompt 里那几条看。\n` : `🔍 知识库里没有跟「${query}」相关的已确证知识。\n` + " 按你自己的代码调研 / 真机试验继续 —— 这就是常态,不是异常。\n" + " 如果你这一轮把它跑通了,记得用 conditions record 记下来,下一个任务就能查到。\n"); process.exit(0); } process.stdout.write( `${data.block}\n` + (known.length ? `(另外 ${known.join("、")} 也相关,它们已经在你上面的 prompt 里了。)\n` : "") + `(共 ${data.count} 条,编号从 ${data.firstLabel || "K?"} 起。采纳了哪条就在报告里标 〔编号〕,并计入最后的 KB_USED: 行;` + "验证或推翻了哪条,记条件时加 --kb <编号>。)\n", ); process.exit(0); } /** CLI entry — direct (`bun bin/kb.ts recall …`) or as the bundle's `kb` subcommand. */ export async function runKb(argv: string[]): Promise { const sub = argv[0]; switch (sub) { case "recall": case "search": case "query": return await cmdRecall(argv.slice(1)); case "-h": case "--help": case undefined: process.stdout.write(USAGE); process.exit(sub ? 0 : 2); default: process.stderr.write(`未知子命令「${sub}」\n\n${USAGE}`); process.exit(2); } } if (import.meta.main) await runKb(process.argv.slice(2));