LLM Wiki is a cross-platform desktop application that turns your documents into an organized, interlinked knowledge base — automatically. Instead of traditional RAG (retrieve-and-answer from scratch every time), the LLM incrementally builds and maintains a persistent wiki from your sources。
TypeScript
feat: add faithful source answer mode
nash_su3ab48b79d320
diff --git a/src-tauri/src/agent/runtime.rs b/src-tauri/src/agent/runtime.rsindex 5554da77..aeb2989d 100644--- a/src-tauri/src/agent/runtime.rs+++ b/src-tauri/src/agent/runtime.rs@@ -222,7 +222,7 @@ impl AgentRuntime {);}- if request.tools.web {+ if request.tools.web && request.retrieval_mode != AgentRetrievalMode::Faithful {permission_policy.require(AgentCapability::SearchWeb)?;tool_emit_event(&mut tool_events, &mut events, &event_sink, AgentToolEvent {tool: "web.search".to_string(),@@ -230,7 +230,7 @@ impl AgentRuntime {detail: Some("Web search is enabled for this turn. Router decides whether to execute it immediately.".to_string()),});}- if request.tools.anytxt {+ if request.tools.anytxt && request.retrieval_mode != AgentRetrievalMode::Faithful {permission_policy.require(AgentCapability::SearchAnyTxt)?;tool_emit_event(&mut tool_events, &mut events, &event_sink, AgentToolEvent {tool: "anytxt.search".to_string(),@@ -1387,6 +1387,37 @@ impl AgentRuntime {}}+ if request.retrieval_mode == AgentRetrievalMode::Faithful && request.tools.wiki {+ let source_action = AgentLoopAction {+ action: "tool".to_string(),+ tool: Some("source.search".to_string()),+ query: Some(message.to_string()),+ ..AgentLoopAction::default()+ };+ let input = self.agent_loop_tool_input(request, "source.search", &source_action)?;+ executed_retrievals.insert(retrieval_signature(+ "source.search",+ &input,+ request.retrieval_mode,+ ));+ retrieval_steps += 1;+ let observation = self+ .execute_agent_loop_tool(+ request,+ &source_action,+ &permission_policy,+ &tool_registry,+ &skills,+ &mut references,+ &mut tool_events,+ &mut events,+ &event_sink,+ cancellation,+ )+ .await?;+ observations.push(observation);+ }+for iteration in 0..max_iterations {check_cancel(cancellation)?;let must_finalize = force_final_next || retrieval_steps >= retrieval_budget;@@ -1410,7 +1441,7 @@ impl AgentRuntime {);let (system, user) = if must_finalize {(- build_agent_final_system(&built_context.system),+ build_agent_final_system(&built_context.system, request.retrieval_mode),build_agent_final_user(&built_context.user, &observations),)} else {@@ -2764,6 +2795,13 @@ fn agent_loop_retrieval_budget(retrieval_mode: AgentRetrievalMode,has_explicit_skills: bool,) -> usize {+ if retrieval_mode == AgentRetrievalMode::Faithful {+ return match mode {+ AgentMode::Fast => 2,+ AgentMode::Standard | AgentMode::LocalFirst => 3,+ AgentMode::Deep => 5,+ };+ }if retrieval_mode == AgentRetrievalMode::Smart {return match mode {AgentMode::Fast => 3,@@ -2800,7 +2838,7 @@ fn canonical_json(value: &Value) -> String {}fn retrieval_signature(tool: &str, input: &Value, mode: AgentRetrievalMode) -> String {- if mode != AgentRetrievalMode::Smart {+ if mode == AgentRetrievalMode::Standard {return format!("{tool}:{}", canonical_json(input));}let mut normalized = input.clone();@@ -2859,11 +2897,21 @@ fn build_agent_loop_system(base_system: &str, retrieval_mode: AgentRetrievalMode} else {""};+ let faithful_retrieval = if retrieval_mode == AgentRetrievalMode::Faithful {+ "\nFaithful-source mode is enabled by explicit user choice. Answer only from raw source excerpts returned by source.search or explicitly attached source files. Preserve quoted wording exactly and cite the source path beside every quotation or factual claim. Clearly distinguish verbatim quotations from explanation. Generated wiki pages, graph context, web results, AnyTXT results, and unsupported background knowledge are not evidence in this mode. If the available excerpts are insufficient, state that limitation instead of reconstructing or guessing."+ } else {+ ""+ };+ let retrieval_example = if retrieval_mode == AgentRetrievalMode::Faithful {+ "1. {\"action\":\"tool\",\"tool\":\"source.search\",\"query\":\"...\"}"+ } else {+ "1. {\"action\":\"tool\",\"tool\":\"wiki.search\",\"query\":\"...\"}"+ };format!("{base_system}\n\nAgent loop protocol:\n\Return only compact JSON. Do not wrap it in markdown.\n\Choose exactly one action per turn:\n\-1. {{\"action\":\"tool\",\"tool\":\"wiki.search\",\"query\":\"...\"}}\n\+{retrieval_example}\n\2. {{\"action\":\"tool\",\"tool\":\"user.ask\",\"title\":\"...\",\"description\":\"...\",\"fields\":[{{\"id\":\"choice\",\"type\":\"single\",\"label\":\"...\",\"options\":[{{\"label\":\"...\",\"value\":\"...\",\"recommended\":true}}]}}]}}\n\3. {{\"action\":\"tool\",\"tool\":\"workspace.write_file\",\"path\":\"cover-image/cover.svg\",\"content\":\"...\"}}\n\3b. {{\"action\":\"tool\",\"tool\":\"workspace.append_file\",\"path\":\"deck/index.html\",\"content\":\"...\"}}\n\@@ -2877,13 +2925,18 @@ Use tools when they are useful, then wait for the observation in the next turn bDo not claim that a generated file exists until a workspace.write_file or shell.exec observation confirms it. In the final answer, mention only observed generated file paths.\n\Converge quickly. Do not keep reading optional references, running optional validation, or polishing after the requested deliverable has been written. Prefer final as soon as the core user request is satisfied.\n\Only use shell.exec when active skill instructions or the user's explicit request require command-line work after files have been written with workspace.write_file. Generated files must be written under the Agent workspace described above. Commands whose explicit file paths stay inside the Agent workspace can run without an approval prompt; commands that mention external paths, home directories, downloads, temp folders, or network URLs require approval.\n\-Use wiki.write_page only when the user explicitly asks to create or update a wiki page. Existing pages are create-only unless allowOverwrite is explicitly justified by the user's request.{smart_retrieval}"+Use wiki.write_page only when the user explicitly asks to create or update a wiki page. Existing pages are create-only unless allowOverwrite is explicitly justified by the user's request.{smart_retrieval}{faithful_retrieval}")}-fn build_agent_final_system(base_system: &str) -> String {+fn build_agent_final_system(base_system: &str, retrieval_mode: AgentRetrievalMode) -> String {+ let faithful_retrieval = if retrieval_mode == AgentRetrievalMode::Faithful {+ " Faithful-source mode remains in force: use only raw source excerpts or explicitly attached source files as evidence, cite their paths, preserve quotations exactly, and disclose insufficient evidence rather than guessing."+ } else {+ ""+ };format!(- "{base_system}\n\nThe retrieval phase is complete. No tools are available now. Answer the user's latest request directly using the project context and tool observations already provided. Return only compact JSON in the form {{\"action\":\"final\",\"answer\":\"...\"}}. Do not request, announce, or simulate another search or file read."+ "{base_system}\n\nThe retrieval phase is complete. No tools are available now. Answer the user's latest request directly using the permitted context and tool observations already provided.{faithful_retrieval} Return only compact JSON in the form {{\"action\":\"final\",\"answer\":\"...\"}}. Do not request, announce, or simulate another search or file read.")}@@ -2950,16 +3003,22 @@ fn build_agent_loop_user(out.push_str(base_user);out.push_str("\n\nAvailable Agent tools for this turn:\n");if request.tools.wiki {- out.push_str("- wiki.search: retrieve wiki pages for factual or topical questions.\n");- out.push_str("- wiki.read_page: read a specific wiki markdown page by path.\n");- out.push_str("- source.search: search raw source snippets.\n");- out.push_str("- graph.search: retrieve relationships, neighbors, backlinks, dependencies, and connections between entities. Prefer it for relational questions and query with concise entity or concept names.\n");- out.push_str("- wiki.write_page: create a wiki markdown page when explicitly requested.\n");+ if request.retrieval_mode == AgentRetrievalMode::Faithful {+ out.push_str("- source.search: search raw source excerpts. This is the only retrieval tool permitted in faithful-source mode.\n");+ } else {+ out.push_str("- wiki.search: retrieve wiki pages for factual or topical questions.\n");+ out.push_str("- wiki.read_page: read a specific wiki markdown page by path.\n");+ out.push_str("- source.search: search raw source snippets.\n");+ out.push_str("- graph.search: retrieve relationships, neighbors, backlinks, dependencies, and connections between entities. Prefer it for relational questions and query with concise entity or concept names.\n");+ out.push_str(+ "- wiki.write_page: create a wiki markdown page when explicitly requested.\n",+ );+ }}- if request.tools.web {+ if request.tools.web && request.retrieval_mode != AgentRetrievalMode::Faithful {out.push_str("- web.search: search external web sources.\n");}- if request.tools.anytxt {+ if request.tools.anytxt && request.retrieval_mode != AgentRetrievalMode::Faithful {out.push_str("- anytxt.search: search files indexed by AnyTXT.\n");}if !skills.is_empty() {@@ -3441,6 +3500,16 @@ fn require_tool_permission(request: &AgentChatRequest,permission_policy: &PermissionPolicy,) -> Result<(), String> {+ if request.retrieval_mode == AgentRetrievalMode::Faithful+ && matches!(+ tool,+ "wiki.search" | "wiki.read_page" | "graph.search" | "web.search" | "anytxt.search"+ )+ {+ return Err(format!(+ "{tool} is unavailable in faithful-source mode; use source.search"+ ));+ }match tool {"wiki.search" => {if !request.tools.wiki {@@ -4578,6 +4647,10 @@ mod tests {agent_loop_retrieval_budget(AgentMode::Deep, AgentRetrievalMode::Smart, true),6);+ assert_eq!(+ agent_loop_retrieval_budget(AgentMode::Standard, AgentRetrievalMode::Faithful, true),+ 3+ );}#[test]@@ -4605,6 +4678,24 @@ mod tests {);}+ #[test]+ fn faithful_retrieval_prompt_limits_answer_evidence_to_raw_sources() {+ let request = AgentChatRequest {+ retrieval_mode: AgentRetrievalMode::Faithful,+ ..AgentChatRequest::default()+ };+ let loop_system = build_agent_loop_system("base", request.retrieval_mode);+ let loop_user = build_agent_loop_user("question", &request, &[], &[], 0, 8, false);+ let final_system = build_agent_final_system("base", request.retrieval_mode);++ assert!(loop_system.contains("Answer only from raw source excerpts"));+ assert!(loop_system.contains("state that limitation instead of reconstructing or guessing"));+ assert!(loop_user.contains("only retrieval tool permitted"));+ assert!(!loop_user.contains("- wiki.search:"));+ assert!(!loop_user.contains("- graph.search:"));+ assert!(final_system.contains("Faithful-source mode remains in force"));+ }+#[test]fn smart_retrieval_counts_page_reads_but_not_repeated_searches_as_new_evidence() {assert!(retrieval_added_evidence(@@ -4642,7 +4733,7 @@ mod tests {#[test]fn finalization_prompt_removes_tool_choice() {- let system = build_agent_final_system("base");+ let system = build_agent_final_system("base", AgentRetrievalMode::Standard);let user = build_agent_final_user("question",&[AgentObservation {@@ -4994,6 +5085,33 @@ mod tests {.contains("disabled"));}+ #[test]+ fn faithful_retrieval_permission_rejects_non_source_evidence_tools() {+ let request = AgentChatRequest {+ retrieval_mode: AgentRetrievalMode::Faithful,+ tools: AgentToolOptions {+ wiki: true,+ web: true,+ anytxt: true,+ },+ ..AgentChatRequest::default()+ };+ let policy = PermissionPolicy::api_default();++ assert!(require_tool_permission("source.search", &request, &policy).is_ok());+ for tool in [+ "wiki.search",+ "wiki.read_page",+ "graph.search",+ "web.search",+ "anytxt.search",+ ] {+ assert!(require_tool_permission(tool, &request, &policy)+ .unwrap_err()+ .contains("faithful-source mode"));+ }+ }+#[test]fn agent_loop_observations_include_tool_names() {let text = render_observations(&[AgentObservation {diff --git a/src-tauri/src/agent/tools.rs b/src-tauri/src/agent/tools.rsindex 1397d944..47bd7117 100644--- a/src-tauri/src/agent/tools.rs+++ b/src-tauri/src/agent/tools.rs@@ -2336,6 +2336,10 @@ pub fn search_sources(if !entry.file_type().is_file() {continue;}+ let rel = relative_to_project(project_path, entry.path());+ if is_hidden_rel(&rel) {+ continue;+ }seen_files += 1;if seen_files > MAX_SOURCE_SEARCH_FILES {eprintln!(@@ -2351,13 +2355,42 @@ pub fn search_sources(else {continue;};- if !matches!(+ let content = if matches!(ext.as_str(),- "md" | "markdown" | "txt" | "json" | "csv" | "tsv" | "yaml" | "yml" | "xml" | "html"+ "md" | "markdown"+ | "org"+ | "txt"+ | "json"+ | "csv"+ | "tsv"+ | "yaml"+ | "yml"+ | "xml"+ | "html") {- continue;- }- let Ok(content) = fs::read_to_string(entry.path()) else {+ let Ok(content) = fs::read_to_string(entry.path()) else {+ continue;+ };+ content+ } else if matches!(+ ext.as_str(),+ "pdf"+ | "doc"+ | "docx"+ | "pptx"+ | "xls"+ | "xlsx"+ | "odt"+ | "ods"+ | "odp"+ | "epub"+ | "mobi"+ ) {+ let Some(content) = crate::commands::fs::read_preprocessed_cache(entry.path()) else {+ continue;+ };+ content+ } else {continue;};let lower = content.to_lowercase();@@ -2367,10 +2400,6 @@ pub fn search_sources(let Some((byte_idx, _matched_len)) = matched else {continue;};- let rel = relative_to_project(project_path, entry.path());- if is_hidden_rel(&rel) {- continue;- }refs.push(AgentReference {title: entry.path()@@ -3234,6 +3263,38 @@ mod tests {let _ = fs::remove_dir_all(root);}+ #[test]+ fn search_sources_reads_org_and_fresh_binary_extraction_cache() {+ let root = std::env::temp_dir().join(format!("llm-wiki-source-cache-{}", Uuid::new_v4()));+ let source_dir = root.join("raw").join("sources");+ fs::create_dir_all(source_dir.join(".cache")).unwrap();+ fs::write(source_dir.join("notes.org"), "* Policy\nExact org wording").unwrap();+ let pdf = source_dir.join("regulation.pdf");+ fs::write(&pdf, b"%PDF placeholder").unwrap();+ fs::write(+ source_dir.join(".cache").join("regulation.pdf.txt"),+ "Exact cached regulation wording",+ )+ .unwrap();++ let org_refs = search_sources(root.to_str().unwrap(), "org wording", 5).unwrap();+ let pdf_refs = search_sources(root.to_str().unwrap(), "cached regulation", 5).unwrap();++ assert!(org_refs+ .iter()+ .any(|reference| reference.path == "raw/sources/notes.org"));+ let pdf_ref = pdf_refs+ .iter()+ .find(|reference| reference.path == "raw/sources/regulation.pdf")+ .unwrap();+ assert!(pdf_ref+ .snippet+ .as_deref()+ .unwrap()+ .contains("cached regulation"));+ let _ = fs::remove_dir_all(root);+ }+#[test]fn source_and_graph_search_skip_hidden_paths() {let root = std::env::temp_dir().join(format!("llm-wiki-hidden-search-{}", Uuid::new_v4()));diff --git a/src-tauri/src/agent/types.rs b/src-tauri/src/agent/types.rsindex 6311c85e..73bd48a5 100644--- a/src-tauri/src/agent/types.rs+++ b/src-tauri/src/agent/types.rs@@ -23,6 +23,9 @@ pub enum AgentRetrievalMode {// Let the Agent iteratively close evidence gaps under a strict retrieval// budget and no-progress guard.Smart,+ // Use only raw source excerpts as answer evidence. This is explicit user+ // intent, never inferred from wording or language-specific heuristics.+ Faithful,}impl Default for AgentRetrievalMode {@@ -331,6 +334,17 @@ mod tests {assert!(req.images.is_empty());}+ #[test]+ fn chat_request_accepts_faithful_retrieval_mode() {+ let req: AgentChatRequest = serde_json::from_value(serde_json::json!({+ "message": "quote the source",+ "retrievalMode": "faithful"+ }))+ .unwrap();++ assert_eq!(req.retrieval_mode, AgentRetrievalMode::Faithful);+ }+#[test]fn chat_request_accepts_explicit_empty_history_marker() {let req: AgentChatRequest = serde_json::from_value(serde_json::json!({diff --git a/src-tauri/src/commands/fs.rs b/src-tauri/src/commands/fs.rsindex 67d920b9..2084e560 100644--- a/src-tauri/src/commands/fs.rs+++ b/src-tauri/src/commands/fs.rs@@ -169,6 +169,16 @@ fn read_cache(original: &Path) -> Option<String> {}}+/// Return a fresh preprocessing cache for Agent source retrieval.+///+/// Binary imports remain the referenced source of record; this helper only+/// exposes their text extraction and never causes parsing or cache writes from+/// a search request. Keeping freshness checks here also prevents the Agent+/// from quoting a cache after the original file changed externally.+pub(crate) fn read_preprocessed_cache(original: &Path) -> Option<String> {+ read_cache(original)+}+fn write_cache(original: &Path, text: &str) -> Result<(), String> {let cache_path = cache_path_for(original);if let Some(parent) = cache_path.parent() {diff --git a/src/components/chat/chat-input.tsx b/src/components/chat/chat-input.tsxindex 4bce08c5..25c37e31 100644--- a/src/components/chat/chat-input.tsx+++ b/src/components/chat/chat-input.tsx@@ -28,7 +28,7 @@ export interface ChatSendOptions {}const AGENT_MODE_OPTIONS: ChatAgentMode[] = ["fast", "standard", "deep", "local_first"]-const RETRIEVAL_MODE_OPTIONS: ChatRetrievalMode[] = ["standard", "smart"]+const RETRIEVAL_MODE_OPTIONS: ChatRetrievalMode[] = ["standard", "smart", "faithful"]export interface ChatSkillOption {id: string@@ -834,9 +834,7 @@ export function ChatInput({: "text-muted-foreground hover:bg-background/60 hover:text-foreground"} disabled:pointer-events-none disabled:opacity-50`}>- {retrieval === "smart"- ? t("chat.retrievalModes.smart")- : t("chat.retrievalModes.standard")}+ {t(`chat.retrievalModes.${retrieval}`)}</button>)})}diff --git a/src/i18n/en.json b/src/i18n/en.jsonindex 387f1b45..c7c16c31 100644--- a/src/i18n/en.json+++ b/src/i18n/en.json@@ -266,10 +266,11 @@},"agentMode": "Agent mode","retrievalMode": "Retrieval mode",- "retrievalModeHint": "Standard keeps the existing retrieval behavior. Smart iteratively closes evidence gaps under a strict budget.",+ "retrievalModeHint": "Standard keeps the existing behavior. Smart iteratively closes evidence gaps. Faithful answers only from raw source excerpts.","retrievalModes": {"standard": "Standard retrieval",- "smart": "Smart retrieval"+ "smart": "Smart retrieval",+ "faithful": "Faithful sources"},"agentModes": {"fast": "Fast",diff --git a/src/i18n/zh.json b/src/i18n/zh.jsonindex c654bebb..3c789fc4 100644--- a/src/i18n/zh.json+++ b/src/i18n/zh.json@@ -266,10 +266,11 @@},"agentMode": "Agent 模式","retrievalMode": "检索模式",- "retrievalModeHint": "传统检索保持现有行为;智能检索会在严格预算内根据证据缺口迭代检索。",+ "retrievalModeHint": "传统检索保持现有行为;智能检索按证据缺口迭代;原文忠实模式只依据原始资料片段回答。","retrievalModes": {"standard": "传统检索",- "smart": "智能检索"+ "smart": "智能检索",+ "faithful": "原文忠实"},"agentModes": {"fast": "快速",diff --git a/src/lib/chat-agent-types.ts b/src/lib/chat-agent-types.tsindex 4b4ee426..a0c389b5 100644--- a/src/lib/chat-agent-types.ts+++ b/src/lib/chat-agent-types.ts@@ -31,7 +31,7 @@ export interface ChatAgentEvent {}export type ChatAgentMode = "fast" | "standard" | "deep" | "local_first"-export type ChatRetrievalMode = "standard" | "smart"+export type ChatRetrievalMode = "standard" | "smart" | "faithful"export type ChatAgentToolName =| "project_files"diff --git a/src/lib/persist.integration.test.ts b/src/lib/persist.integration.test.tsindex bdfa45bb..07c66035 100644--- a/src/lib/persist.integration.test.ts+++ b/src/lib/persist.integration.test.ts@@ -348,6 +348,20 @@ describe("chat persistence — round-trip (new format)", () => {expect(raw).toContain('"retrievalMode": "smart"')})+ it("round-trips faithful source retrieval preference", async () => {+ await saveChatPreferences(tmp.path, {+ useWebSearch: false,+ useAnyTxtSearch: false,+ agentMode: "standard",+ retrievalMode: "faithful",+ selectedSkills: [],+ disabledSkills: [],+ })++ const loaded = await loadChatPreferences(tmp.path)+ expect(loaded.retrievalMode).toBe("faithful")+ })+it("defaults chat search preferences to off when no file exists", async () => {await expect(loadChatPreferences(tmp.path)).resolves.toEqual({useWebSearch: false,diff --git a/src/lib/persist.ts b/src/lib/persist.tsindex 03ea88bf..efaa5bd3 100644--- a/src/lib/persist.ts+++ b/src/lib/persist.ts@@ -300,5 +300,5 @@ function normalizePersistedAgentMode(value: unknown): ChatAgentMode {}function normalizePersistedRetrievalMode(value: unknown): ChatRetrievalMode {- return value === "smart" ? "smart" : "standard"+ return value === "smart" || value === "faithful" ? value : "standard"}diff --git a/src/stores/chat-store.test.ts b/src/stores/chat-store.test.tsindex 5b9305fa..9496274e 100644--- a/src/stores/chat-store.test.ts+++ b/src/stores/chat-store.test.ts@@ -21,10 +21,12 @@ describe("chat-store conversation isolation", () => {})})- it("defaults to standard retrieval and allows smart retrieval opt-in", () => {+ it("defaults to standard retrieval and allows explicit retrieval modes", () => {expect(useChatStore.getState().retrievalMode).toBe("standard")useChatStore.getState().setRetrievalMode("smart")expect(useChatStore.getState().retrievalMode).toBe("smart")+ useChatStore.getState().setRetrievalMode("faithful")+ expect(useChatStore.getState().retrievalMode).toBe("faithful")})it("writes async assistant results back to the original conversation", () => {