feat(kb): ingest surfaces — web paste bar, chat chip, API route, lisa kb CLI (K-G)#285
Merged
Conversation
Design of record for three KB capabilities on top of v1.0 (#235-#242): - K1 paste any link (web / 公众号 / B站 / YouTube) -> Markdown source - K2 a watchlist -> daily fetched, classified, summarized brief - K3 [[slug]] parsed into a real link graph; index.md becomes a ranked map-of-content; memory stores [[kb:slug]] links instead of content Review of the shipped v1.0 code found five gaps this plan closes, one of them a confirmed bug: both TF-IDF tokenizers (kb/search.ts:45 and memory/vector.ts:212) split on whitespace, so a whole CJK run collapses into a single token and Chinese content only matches an exact whole-string query. Also: normalizeSlug strips non-ASCII so every Chinese title falls back to entry-<timestamp>; web_fetch is lossy plain text with no metadata and no store; [[slug]] is documented in SCHEMA.md but nothing parses it; and there is no KB scheduler at all. Includes the pro/con debate for each decision (self-built extractor vs deps vs remote reader, immutable sources vs re-ingest, autonomous ingest as a prompt-injection path, consent, ASCII vs CJK slugs, brief storage, and RSSHub for feeds without one) and a nine-PR ship order. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Three foundation fixes the rest of the KB v2 work stands on
(docs/PLAN_KNOWLEDGE_BASE_v2.0.md K-B). All three are things that would
have corrupted or lost data once link ingest starts pouring Chinese
content in, so they land before the firehose.
1. CJK search was broken. Both TF-IDF tokenizers (kb/search.ts,
memory/vector.ts) carried the same three lines: lowercase, strip
non-word chars, split on whitespace. Chinese has no whitespace, so a
whole clause survived as ONE token:
doc "这篇公众号文章讲的是知识库的设计" -> one token
query "知识库" -> one token
intersection = empty -> zero hits
i.e. CJK content was only findable by an exact whole-clause query.
Replaced by a shared src/tokenize.ts that emits character bigrams for
CJK runs (plus the run itself, so an exact phrase still ranks
highest), segments at latin/CJK boundaries so "gpt模型" indexes as
"gpt" + CJK bigrams, and now keeps kana and CJK Ext-A, which the old
character class dropped entirely. Latin tokenization is unchanged.
2. Chinese titles produced throwaway slugs. normalizeSlug strips every
non-[a-z0-9] char, so a CJK title normalized to "" and addSource fell
back to entry-<Date.now()> — opaque, unstable, un-dedupable. New
kb/slug.ts mints <date>-<sha256/8> for titles with no usable latin,
keeping slugs ASCII on purpose (macOS NFD vs git NFC filenames, URLs,
git paths) with the real title in frontmatter. canonicalUrl() drops
utm_*/known tracking params so the same article shared twice
canonicalizes — and hashes — identically.
3. Entries can now carry arbitrary frontmatter via KbEntry.extra,
round-tripped on read/write. This is where ingest provenance goes
(url/site/author/published/hash/via) without the store knowing about
any of it, and it means keys a future version adds survive a
round-trip through an older one. Values are whitespace-collapsed on
write so a newline can't forge frontmatter lines on the next read.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…d MOC v1.0 told Lisa to cross-link wiki pages with [[slug]] (SCHEMA.md) and recorded each page's sources: in frontmatter — but nothing ever read either one. The KB was a pile of files with decorative links. src/kb/links.ts builds the graph from three edge sources ([[slug]], [[slug|alias]], [[kb:slug]] in bodies; a wiki page's sources: frontmatter) and derives what you can't get from search: backlinks, hubs, orphans, and links pointing at pages that don't exist yet. index.md is now a ranked map of content rather than a flat listing. It is injected into EVERY system prompt and hard-capped there (prompt.ts:165), so with a flat list the truncation lands at an arbitrary point once the KB grows and whatever fell below the line stops existing as far as Lisa is concerned. Ordering wiki pages by (1 + backlinks) x recency means the cut always eats the least-connected tail. Orphans and broken links are listed as the tending to-do list, and every truncation says how much it dropped instead of trailing off. Sources are now listed by TITLE ONLY. Layer 1 is raw captured material — after link ingest lands that means whole web pages — and index.md is always-on prompt text, so an excerpt there is a direct "any page on the internet -> Lisa's system prompt" path. This is a stronger form of the containment the plan assigned to K-I (it covers every source, not just origin: web), and it costs nothing: a title is all a map needs, and the body is one kb_read away. Wiki gists stay — Lisa wrote those herself. Also: kb/index.json (the machine-readable graph, for the web UI and tools), a kb_links tool (links to / linked from / shares tags with), and kb_read now takes a bare slug or a [[wikilink]] with the layer optional, and appends the pages that link to what you just read. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
K-A/K-B/K-C are open as #278/#279/#280. This is the pickup document for whoever continues: the branch stack and how not to break it, the APIs the first three PRs landed, a file-by-file spec for each remaining PR, the repo conventions that are easy to trip over (LISA_HOME must be set before import, the tool-subset triple, the giant template literals in lisa-client.ts), and the eight decisions that are already settled so they don't get re-litigated. Two things it corrects against the plan: the index-side injection containment assigned to K-I already shipped in K-C, and in a stronger form (every source is title-only in index.md, not just origin: web), so K-I is down to the watchlist restriction and the kb_read fence. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…rvative autolink (K-D) Closes the "memory stores links, not content" loop from the v2.0 plan (user need ③). Four pieces: - prompt.ts inlines page titles for [[kb:slug]] pointers found in MEMORY.md / USER.md at assembly time ([[kb:oauth]] → [[kb:oauth]](OAuth 与 PKCE)), so a pointer is meaningful without a kb_read. Titles come from the already- generated kb/index.json behind a stat-fingerprint cache — the prompt builds every turn, so no full-KB read on this path. Unresolvable links are kept verbatim: a dangling pointer is a "write this page" signal, not noise. - memory tool description now steers knowledge OUT of memory (4KB cap) and into the KB with a [[kb:slug]] pointer. - The idle tending prompt closes the loop from the other side: after distilling a wiki page, back-link it from any related memory entry. - kb/autolink.ts: conservative title → [[link]] pass applied on kb_write. Whole-word title matches only, first occurrence, longest-first, never in code / existing links, short titles skipped — a wrong edge pollutes the (backlinks × recency) hub ranking the always-on index sorts by, so misses are preferred over false links. Emits [[slug|Title]] when the slug differs so CJK prose keeps reading as prose. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…K-E) kb_ingest(url) turns a link into a searchable, citeable source entry (v2.0 user need ②). New src/kb/ingest/, all zero-dependency (D1: what the user reads never leaves the machine): - html-to-md.ts: lenient HTML tree parser + markdown serializer (headings, nested lists, fenced/inline code, blockquotes, tables, links, lazy-loaded images, emphasis). Prose is markdown-escaped BEFORE syntax is added, so page text can't forge emphasis/links/wikilinks into the KB; code bodies can't terminate their own fence; javascript: hrefs are dropped. - readability.ts: small Readability — score candidates by text mass, <p> count, link density, class/id hints; fall back to <body> when unsure (noise is recoverable by distillation, clipped content is not). - provenance.ts: og:* / JSON-LD Article / <title> / rel=canonical / lang → frontmatter (url · site · author · published · lang · hash · via). - dedupe.ts: kb/.ingested.json (hash → slug), rebuilt from the sources' own hash: frontmatter when missing/corrupt. Same URL returns the existing entry (D2, immutable sources); force re-ingests + records supersedes:. - index.ts: ingestUrl orchestration with an adapter seam for K-F. ALL fetching goes through web_fetch's fetchFollowingSafeRedirects (per-hop private-host validation) plus an up-front assertAllowedUrl — no second fetch path, no second SSRF surface. kb_ingest is REMOTE_BLOCKED (a channel message must not make Lisa fetch an attacker URL into the KB) but NOT autonomous-blocked — K-I scopes autonomous use to the feeds.json domain watchlist (D3) instead of a blanket ban. Tests are offline-fixture only: converter syntax coverage, chrome-stripping, provenance forms, dedupe/force/ledger-rebuild, SSRF rejection before fetch, content-type gates. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Three IngestAdapter implementations behind the K-E seam, for the sites where generic readability extraction can't reach the content: - wechat: article body from #js_content, account from #js_name, epoch publish time from inline `var ct`; lazy-loaded images already handled via data-src. The human-verification interstitial throws a loud, actionable error (open the share link on the phone, paste the text, kb_add) — never a silently captured blank page. - bilibili: metadata via the public view API; b23.tv short links resolve through the guarded fetch. Subtitles are cookie-gated (SESSDATA, which the user may volunteer in kb/feeds.json) — absent that, degrade. - youtube: oEmbed as the reliability floor + one InnerTube player POST for description/captions; captionTracks → &fmt=json3, manual tracks over ASR. Handles the documented failure modes (PO token, 200-with-empty-body, datacenter throttling) by degrading. Fixed subtitle layering (handoff: do not reorder): built-in API → yt-dlp (--dump-single-json only when installed; discovered subtitle URLs are still fetched through the guarded path) → metadata + description. A MISSING TRANSCRIPT IS NOT A FAILURE: the entry records `transcript: unavailable (<reason>)` and the tool reply tells the user they can paste one via kb_add. Supporting changes: fetchFollowingSafeRedirects gains an optional SafeFetchInit (method/headers/body) so adapter API calls stay on the single SSRF-guarded fetch path; ingest types moved to types.ts to break the adapter↔index cycle; the min-body-length gate now applies only to the generic path so degraded video captures can be legitimately short. All tests offline-fixture; degradation paths asserted explicitly. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… kb CLI (K-G)
Four entry points onto the K-E/K-F engine, one per place a link shows up:
- POST /api/kb/ingest ({url, title?, tags?, force?} — shaped so a future
share-sheet client can call it directly). Ingest failures return 422 with
the engine's actionable message (verification page, paywall, bad type)
instead of a generic 500.
- Knowledge view: a paste-a-link bar above search — progress state, saves,
then opens the new entry; dedupe and no-transcript degradation are surfaced
in the status line.
- Chat: a user message containing a bare URL gets a one-tap 存入知识库 chip
under the bubble (same interaction shape as the KB capture bar; kbToast is
now shared via window.lisaKbToast).
- `lisa kb add|list|search|brief` (src/cli/kb.ts), registered like mail:
passthrough subargs so --title/--tags/--force never collide with global
flags. `brief` prints the newest sources/brief-<date>.md — the file K-H
starts writing — and points at feeds.json until then.
The client edits live inside the MAIN_CLIENT_JS template literal (regex
backslashes double-escaped — the html-syntax test caught the first attempt);
lisa-html-snapshot constants recomputed accordingly.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Owner
Author
|
Clean surface work — four entry points onto one engine, the mail-style passthrough registration keeps the subcommand flags intact, and the byte-exact snapshot discipline is followed. The route correctly lands after the auth gate and inside the per-uid home scope, so authz and tenant isolation are right. Main thing before this is enabled for real cloud users: Minor:
CSRF posture is fine (no CORS → the JSON POST can't be sent cross-origin), and the CLI is injection-safe since yt-dlp only ever receives code-built canonical URLs. No correctness bugs found; the chip renders in the right spot. Verdict: RISKY on the cloud edition (unthrottled ingest); ready as-is for the loopback Mac edition. |
# Conflicts: # src/kb/ingest/html-to-md.test.ts # src/kb/ingest/html-to-md.ts # src/kb/ingest/index.ts # src/kb/links.test.ts # src/kb/links.ts # src/kb/store.test.ts # src/kb/store.ts # src/tools/web_fetch.ts
Owner
Author
|
Reconciled onto main + landed the review fixes on |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of the knowledge-base v2.0 stack (plan: #278, handoff: #281). Stacked on #284 (K-F) — merge order: #278 → … → #284 → this.
差距
K-E/K-F 的引擎只有 agent 工具一个入口；用户自己拿到链接时（浏览器里、聊天里、终端里）没有一条一步到位的路。
做了什么
POST /api/kb/ingest（server.ts，挨着 /api/kb/add）——body{url, title?, tags?, force?}，按分享面板可直接调的形状设计；摄取失败返回 422 + 引擎的可操作报错（微信验证页/登录墙/不支持的类型），不是笼统 500。window.lisaKbToast共享）。lisa kbCLI（src/cli/kb.ts）——add <url> [--title|--tags|--force]/list [wiki|sources]/search <q>/brief [date]；照 mail 的 passthrough 注册（cli-args.ts 联合类型 + PASSTHROUGH_SUBCOMMANDS），子命令 flags 不会被全局解析吞掉；HELP 加了 KNOWLEDGE BASE 段。文档没写的拍板
lisa kb brief读的是 sources/brief-.md（K-H 将写入的两份日报之一，D7）而不是 feeds/.json —— markdown 本来就是给人读的形态，CLI 直接打印零转换；feeds 未配置时提示去~/.lisa/kb/feeds.json配置。K-H 落地后此命令即自动生效，接口不用再动。仓库坑的处理
lisa-client.ts是巨型模板字符串：新代码零反引号，正则反斜杠双写（第一版没双写，html-syntax.test当场抓住——这个测试真的在干活）；lisa-html-snapshot长度/哈希已按说明重算并在注释里补了变更记录。测了什么
cli/kb.test.ts：usage 错误码、list（空/分层/tags）、search 命中与未命中、brief 三态（未配置指引/打印既有 brief/指定日期无结果）。cli-args.test.ts：kb passthrough——--title/--tags/--force原样到达 handler。npm run typecheck干净；npm test1255 pass / 0 fail。🤖 Generated with Claude Code