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 streaming chat API
nash_su4fee1b093eac
diff --git a/README.md b/README.mdindex 63353544..cf261e1f 100644--- a/README.md+++ b/README.md@@ -444,7 +444,7 @@ LLM Wiki ships a built-in local HTTP API at `http://127.0.0.1:19828` (token-prot- `PATCH /api/v1/projects/{id}/reviews/{reviewId}` — update one Review item (JSON body `{ "resolved": true, "action": "label" }`; `resolved` defaults to true, pass false to reopen)- `POST /api/v1/projects/{id}/reviews/resolve` — bulk-resolve Review items (JSON body `{ "ids": [...], "action": "label" }`), returns `{ resolved, notFound, count }`; the Review tab's Refresh button re-reads the result from disk- `POST /api/v1/projects/{id}/search` — **hybrid** retrieval (keyword + vector) returning `mode`, `tokenHits`, `vectorHits`, per-result `vectorScore`-- `POST /api/v1/projects/{id}/chat` — non-streaming backend Agent chat endpoint returning an assistant message, references, usage, and tool events for wiki/source/web/AnyTXT retrieval; `mode: "deep"` broadens evidence collection, while the full Deep Research workspace remains available in the desktop UI+- `POST /api/v1/projects/{id}/chat` — backend Agent chat endpoint for wiki/source/web/AnyTXT retrieval. JSON requests remain non-streaming by default; send `"stream": true` or `Accept: text/event-stream` for SSE events (`meta`, incremental `agent`, then `done`, `cancelled`, or `error`). The terminal `done` frame contains the complete aggregate response, so clients should not render both message deltas and the final message as separate answers. `mode: "deep"` broadens evidence collection, while the full Deep Research workspace remains available in the desktop UI- `GET /api/v1/projects/{id}/graph` — wikilinks graph- `POST /api/v1/projects/{id}/sources/rescan` — trigger a backend rescandiff --git a/src-tauri/src/api_server.rs b/src-tauri/src/api_server.rsindex 933cd176..121ae964 100644--- a/src-tauri/src/api_server.rs+++ b/src-tauri/src/api_server.rs@@ -1,12 +1,14 @@use std::collections::{BTreeMap, BTreeSet, VecDeque};use std::fs;-use std::io::Read;+use std::io::{Cursor, Read};use std::path::{Component, Path, PathBuf};use std::sync::atomic::{AtomicU8, AtomicUsize, Ordering};+use std::sync::mpsc::{self, Receiver, SyncSender};use std::sync::{Mutex, OnceLock};use std::thread;use std::time::{Duration, Instant};+use futures::FutureExt;use serde::{Deserialize, Serialize};use serde_json::{json, Map, Value};use tauri::{AppHandle, Manager};@@ -33,10 +35,14 @@ const APP_STATE_CACHE_TTL: Duration = Duration::from_secs(5);const RATE_LIMIT_WINDOW: Duration = Duration::from_secs(1);const RATE_LIMIT_MAX_REQUESTS: usize = 120;const MAX_IN_FLIGHT_REQUESTS: usize = 64;+const MAX_IN_FLIGHT_CHAT_STREAMS: usize = 8;+const SSE_QUEUE_CAPACITY: usize = 64;+const SSE_HEARTBEAT_INTERVAL: Duration = Duration::from_secs(10);/// API status: 0=starting, 1=running, 2=port_conflict, 3=errorstatic API_STATUS: AtomicU8 = AtomicU8::new(0);static IN_FLIGHT_REQUESTS: AtomicUsize = AtomicUsize::new(0);+static IN_FLIGHT_CHAT_STREAMS: AtomicUsize = AtomicUsize::new(0);static APP_STATE_CACHE: OnceLock<Mutex<Option<CachedAppState>>> = OnceLock::new();static RATE_LIMIT: OnceLock<Mutex<VecDeque<Instant>>> = OnceLock::new();@@ -135,6 +141,32 @@ impl Drop for RequestSlot {}}+struct ChatStreamSlot;++impl Drop for ChatStreamSlot {+ fn drop(&mut self) {+ IN_FLIGHT_CHAT_STREAMS.fetch_sub(1, Ordering::Relaxed);+ }+}++fn try_acquire_chat_stream_slot() -> Option<ChatStreamSlot> {+ let mut current = IN_FLIGHT_CHAT_STREAMS.load(Ordering::Relaxed);+ loop {+ if current >= MAX_IN_FLIGHT_CHAT_STREAMS {+ return None;+ }+ match IN_FLIGHT_CHAT_STREAMS.compare_exchange_weak(+ current,+ current + 1,+ Ordering::Relaxed,+ Ordering::Relaxed,+ ) {+ Ok(_) => return Some(ChatStreamSlot),+ Err(next) => current = next,+ }+ }+}+fn try_acquire_request_slot() -> Option<RequestSlot> {let mut current = IN_FLIGHT_REQUESTS.load(Ordering::Relaxed);loop {@@ -181,6 +213,47 @@ fn process_request(app: AppHandle, mut request: tiny_http::Request) {}};+ let (path, query) = split_url(&url);+ if wants_streaming_chat(&method, &path, &body, &headers) {+ if !api_enabled(&app) {+ respond_error(+ request,+ 503,+ "API server is disabled in Settings → API Server",+ origin.as_deref(),+ );+ return;+ }+ // Agent chat remains token-protected even when read-oriented API+ // endpoints are configured for unauthenticated local access.+ if !is_token_authorized(&app, query, &headers) {+ respond_error(request, 401, "Unauthorized", origin.as_deref());+ return;+ }+ let Some(project_id) = chat_project_id(&method, &path) else {+ respond_error(request, 404, "Not found", origin.as_deref());+ return;+ };+ let Some(stream_slot) = try_acquire_chat_stream_slot() else {+ respond_error(+ request,+ 503,+ "Too many concurrent Agent chat streams",+ origin.as_deref(),+ );+ return;+ };+ respond_chat_sse(+ request,+ app,+ project_id,+ &body,+ origin.as_deref(),+ stream_slot,+ );+ return;+ }+let response = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {handle_request(&app, &method, &url, &body, &headers)}))@@ -234,7 +307,8 @@ fn handle_request("allowLanAccess": api_allow_lan_access(app),"agent": {"chat": true,- "streaming": false,+ "streaming": true,+ "streamProtocol": "sse",},}));}@@ -259,12 +333,9 @@ fn handle_request(return err(405, "Method not allowed");}- let parts: Vec<&str> = path- .trim_start_matches(API_PREFIX)- .trim_start_matches('/')- .split('/')- .filter(|part| !part.is_empty())- .collect();+ let Some(parts) = api_path_parts(&path) else {+ return err(404, "Not found");+ };match (method, parts.as_slice()) {(&Method::Get, ["projects"]) => handle_projects(app),@@ -320,12 +391,9 @@ fn allow_request() -> bool {}fn is_agent_chat_request(method: &Method, path: &str) -> bool {- let parts = path- .trim_start_matches(API_PREFIX)- .trim_start_matches('/')- .split('/')- .filter(|part| !part.is_empty())- .collect::<Vec<_>>();+ let Some(parts) = api_path_parts(path) else {+ return false;+ };method == &Method::Post&& matches!(parts.as_slice(),@@ -333,15 +401,65 @@ fn is_agent_chat_request(method: &Method, path: &str) -> bool {)}+fn chat_project_id<'a>(method: &Method, path: &'a str) -> Option<&'a str> {+ if method != &Method::Post {+ return None;+ }+ let parts = api_path_parts(path)?;+ match parts.as_slice() {+ ["projects", project_id, "chat"] => Some(*project_id),+ _ => None,+ }+}++fn api_path_parts(path: &str) -> Option<Vec<&str>> {+ let remainder = path.strip_prefix(API_PREFIX)?;+ if !remainder.is_empty() && !remainder.starts_with('/') {+ return None;+ }+ Some(+ remainder+ .trim_start_matches('/')+ .split('/')+ .filter(|part| !part.is_empty())+ .collect(),+ )+}++fn wants_streaming_chat(+ method: &Method,+ path: &str,+ body: &str,+ headers: &[(String, String)],+) -> bool {+ if chat_project_id(method, path).is_none() {+ return false;+ }+ let accepts_sse = headers.iter().any(|(key, value)| {+ key == "accept"+ && value+ .split(',')+ .filter_map(|part| part.trim().split(';').next())+ .any(|media_type| media_type.trim().eq_ignore_ascii_case("text/event-stream"))+ });+ match serde_json::from_str::<Value>(body)+ .ok()+ .and_then(|value| value.get("stream").and_then(Value::as_bool))+ {+ Some(stream) => stream,+ None => accepts_sse,+ }+}+fn body_limit_for_request(method: &Method, url: &str) -> usize {let (path, _) = split_url(url);- let parts = path- .trim_start_matches(API_PREFIX)- .trim_start_matches('/')- .split('/')- .filter(|part| !part.is_empty())- .collect::<Vec<_>>();- if method == &Method::Post && matches!(parts.as_slice(), ["projects", _, "chat"]) {+ let parts = api_path_parts(&path);+ if method == &Method::Post+ && parts+ .as_deref()+ .map(|parts| matches!(parts, ["projects", _, "chat"]))+ .unwrap_or(false)+ {MAX_CHAT_BODY_BYTES} else {MAX_BODY_BYTES@@ -1669,15 +1787,28 @@ fn handle_search(app: &AppHandle, project_id: &str, body: &str) -> ApiResponse {}}-fn handle_chat(app: &AppHandle, project_id: &str, body: &str) -> ApiResponse {- let project = match resolve_project(app, project_id) {- Ok(project) => project,- Err(e) => return err(404, e),- };- let mut req: agent::AgentChatRequest = match serde_json::from_str(body) {- Ok(req) => req,- Err(e) => return err(400, format!("Invalid JSON: {e}")),- };+struct PreparedChat {+ project: ProjectEntry,+ request: agent::AgentChatRequest,+ runtime: agent::AgentRuntime,+ user_message: String,+ persist_session: bool,+ session_id: String,+ run_id: String,+ cancellation: Option<agent::cancel::AgentCancellationToken>,+}++fn prepare_chat(+ app: &AppHandle,+ project_id: &str,+ body: &str,+) -> Result<PreparedChat, ApiResponse> {+ let project = resolve_project(app, project_id).map_err(|e| err(404, e))?;+ let mut req: agent::AgentChatRequest =+ serde_json::from_str(body).map_err(|e| err(400, format!("Invalid JSON: {e}")))?;+ if req.message.trim().is_empty() {+ return Err(err(400, "message is required"));+ }if req.session_id.as_deref()@@ -1726,39 +1857,70 @@ fn handle_chat(app: &AppHandle, project_id: &str, body: &str) -> ApiResponse {let cancellation = app.state::<agent::cancel::AgentCancellationRegistry>().start(&project.id, &session_id, &run_id);- let result =- tauri::async_runtime::block_on(runtime.run_once_with_cancel(req, Some(cancellation)));+ Ok(PreparedChat {+ project,+ request: req,+ runtime,+ user_message: user_message_for_session,+ persist_session,+ session_id,+ run_id,+ cancellation: Some(cancellation),+ })+}++fn persist_chat_response(+ app: &AppHandle,+ prepared: &PreparedChat,+ response: &agent::types::AgentChatResponse,+) {+ if prepared.persist_session {+ app.state::<agent::session::AgentSessionStore>()+ .append_turn(+ &prepared.project.path,+ &prepared.project.id,+ &response.session_id,+ &prepared.user_message,+ &response.message,+ );+ }+}++fn external_chat_response(mut response: agent::types::AgentChatResponse) -> Value {+ for event in &mut response.events {+ event.redact_for_external_api();+ }+ json!({+ "ok": true,+ "projectId": response.project_id,+ "sessionId": response.session_id,+ "mode": response.mode,+ "message": {+ "role": "assistant",+ "content": response.message,+ },+ "references": response.references,+ "toolEvents": response.tool_events,+ "events": response.events,+ "usage": response.usage,+ })+}++fn handle_chat(app: &AppHandle, project_id: &str, body: &str) -> ApiResponse {+ let mut prepared = match prepare_chat(app, project_id, body) {+ Ok(prepared) => prepared,+ Err(response) => return response,+ };+ let result = tauri::async_runtime::block_on(prepared.runtime.run_once_with_cancel(+ std::mem::take(&mut prepared.request),+ prepared.cancellation.take(),+ ));app.state::<agent::cancel::AgentCancellationRegistry>()- .finish(&project.id, &session_id, &run_id);+ .finish(&prepared.project.id, &prepared.session_id, &prepared.run_id);match result {- Ok(mut response) => {- if persist_session {- app.state::<agent::session::AgentSessionStore>()- .append_turn(- &project.path,- &project.id,- &response.session_id,- &user_message_for_session,- &response.message,- );- }- for event in &mut response.events {- event.redact_for_external_api();- }- ok(json!({- "ok": true,- "projectId": response.project_id,- "sessionId": response.session_id,- "mode": response.mode,- "message": {- "role": "assistant",- "content": response.message,- },- "references": response.references,- "toolEvents": response.tool_events,- "events": response.events,- "usage": response.usage,- }))+ Ok(response) => {+ persist_chat_response(app, &prepared, &response);+ ok(external_chat_response(response))}Err(e) if e == "message is required" => err(400, e),Err(e) if e == "Agent turn cancelled" => err(499, e),@@ -1766,6 +1928,213 @@ fn handle_chat(app: &AppHandle, project_id: &str, body: &str) -> ApiResponse {}}+struct SseReader {+ receiver: Receiver<Vec<u8>>,+ current: Cursor<Vec<u8>>,+}++impl SseReader {+ fn new(receiver: Receiver<Vec<u8>>) -> Self {+ Self {+ receiver,+ current: Cursor::new(Vec::new()),+ }+ }+}++impl Read for SseReader {+ fn read(&mut self, buffer: &mut [u8]) -> std::io::Result<usize> {+ if buffer.is_empty() {+ return Ok(0);+ }+ loop {+ let read = self.current.read(buffer)?;+ if read > 0 {+ return Ok(read);+ }+ match self.receiver.recv() {+ Ok(chunk) => self.current = Cursor::new(chunk),+ Err(_) => return Ok(0),+ }+ }+ }+}++fn sse_frame(event: &str, data: &Value) -> Vec<u8> {+ format!("event: {event}\ndata: {}\n\n", data).into_bytes()+}++enum SseSendResult {+ Sent,+ Full,+ Disconnected,+}++fn try_send_sse(sender: &SyncSender<Vec<u8>>, frame: Vec<u8>) -> SseSendResult {+ match sender.try_send(frame) {+ Ok(()) => SseSendResult::Sent,+ Err(mpsc::TrySendError::Full(_)) => SseSendResult::Full,+ Err(mpsc::TrySendError::Disconnected(_)) => SseSendResult::Disconnected,+ }+}++fn send_terminal_sse(sender: SyncSender<Vec<u8>>, frame: Vec<u8>) {+ // A terminal frame must not be dropped when the bounded queue is briefly+ // full, but blocking a Tokio worker would stall unrelated app work. Use a+ // short-lived writer thread; send unblocks when the socket drains or the+ // request reader is dropped after a disconnect.+ thread::spawn(move || {+ let _ = sender.send(frame);+ });+}++fn respond_chat_sse(+ request: tiny_http::Request,+ app: AppHandle,+ project_id: &str,+ body: &str,+ origin: Option<&str>,+ _stream_slot: ChatStreamSlot,+) {+ let prepared = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {+ prepare_chat(&app, project_id, body)+ }));+ let mut prepared = match prepared {+ Ok(Ok(prepared)) => prepared,+ Ok(Err(response)) => {+ respond_json(request, response.status, response.body, origin);+ return;+ }+ Err(_) => {+ respond_error(request, 500, "Internal API server error", origin);+ return;+ }+ };+ let (sender, receiver) = mpsc::sync_channel::<Vec<u8>>(SSE_QUEUE_CAPACITY);+ let _ = try_send_sse(+ &sender,+ sse_frame(+ "meta",+ &json!({+ "projectId": prepared.project.id,+ "sessionId": prepared.session_id,+ "runId": prepared.run_id,+ }),+ ),+ );++ let (heartbeat_stop, heartbeat_done) = mpsc::channel::<()>();+ let heartbeat_sender = sender.clone();+ let heartbeat_registry = app+ .state::<agent::cancel::AgentCancellationRegistry>()+ .inner()+ .clone();+ let heartbeat_project = prepared.project.id.clone();+ let heartbeat_session = prepared.session_id.clone();+ let heartbeat_run = prepared.run_id.clone();+ thread::spawn(move || loop {+ match heartbeat_done.recv_timeout(SSE_HEARTBEAT_INTERVAL) {+ Ok(_) | Err(mpsc::RecvTimeoutError::Disconnected) => break,+ Err(mpsc::RecvTimeoutError::Timeout) => {+ match try_send_sse(&heartbeat_sender, b": keepalive\n\n".to_vec()) {+ SseSendResult::Disconnected => {+ heartbeat_registry.cancel(+ &heartbeat_project,+ &heartbeat_session,+ Some(&heartbeat_run),+ );+ break;+ }+ SseSendResult::Sent | SseSendResult::Full => {}+ }+ }+ }+ });++ let task_app = app.clone();+ tauri::async_runtime::spawn(async move {+ let event_sender = sender.clone();+ let registry = task_app+ .state::<agent::cancel::AgentCancellationRegistry>()+ .inner()+ .clone();+ let cancel_project = prepared.project.id.clone();+ let cancel_session = prepared.session_id.clone();+ let cancel_run = prepared.run_id.clone();+ let sink: agent::runtime::AgentEventSink = std::sync::Arc::new(move |mut event| {+ event.redact_for_external_api();+ let payload = serde_json::to_value(event)+ .unwrap_or_else(|err| json!({ "type": "error", "message": err.to_string() }));+ match try_send_sse(&event_sender, sse_frame("agent", &payload)) {+ SseSendResult::Disconnected => {+ registry.cancel(&cancel_project, &cancel_session, Some(&cancel_run));+ }+ // Intermediate events may be dropped for a temporarily slow+ // client. The terminal `done` frame still carries the complete+ // aggregate response, so correctness is preserved.+ SseSendResult::Sent | SseSendResult::Full => {}+ }+ });+ let result =+ std::panic::AssertUnwindSafe(prepared.runtime.run_once_with_cancel_and_events(+ std::mem::take(&mut prepared.request),+ prepared.cancellation.take(),+ Some(sink),+ ))+ .catch_unwind()+ .await;+ task_app+ .state::<agent::cancel::AgentCancellationRegistry>()+ .finish(&prepared.project.id, &prepared.session_id, &prepared.run_id);+ match result {+ Ok(Ok(response)) => {+ persist_chat_response(&task_app, &prepared, &response);+ send_terminal_sse(+ sender.clone(),+ sse_frame("done", &external_chat_response(response)),+ );+ }+ Ok(Err(message)) => {+ let event = if message == "Agent turn cancelled" {+ "cancelled"+ } else {+ "error"+ };+ send_terminal_sse(+ sender.clone(),+ sse_frame(event, &json!({ "ok": false, "error": message })),+ );+ }+ Err(_) => {+ send_terminal_sse(+ sender.clone(),+ sse_frame(+ "error",+ &json!({ "ok": false, "error": "Agent chat task panicked" }),+ ),+ );+ }+ }+ let _ = heartbeat_stop.send(());+ });++ let mut response = Response::new(+ StatusCode(200),+ vec![+ Header::from_bytes("Content-Type", "text/event-stream; charset=utf-8").unwrap(),+ Header::from_bytes("Cache-Control", "no-cache, no-transform").unwrap(),+ Header::from_bytes("X-Accel-Buffering", "no").unwrap(),+ ],+ SseReader::new(receiver),+ None,+ None,+ );+ for header in cors_headers(origin) {+ response.add_header(header);+ }+ let _ = request.respond(response);+}+fn handle_cancel_chat(app: &AppHandle, project_id: &str, session_id: &str) -> ApiResponse {let project = match resolve_project(app, project_id) {Ok(project) => project,@@ -2725,6 +3094,119 @@ mod tests {));}+ #[test]+ fn chat_streaming_is_enabled_by_body_or_accept_header() {+ let path = "/api/v1/projects/current/chat";+ assert!(wants_streaming_chat(+ &Method::Post,+ path,+ r#"{"message":"hello","stream":true}"#,+ &[],+ ));+ assert!(wants_streaming_chat(+ &Method::Post,+ path,+ r#"{"message":"hello"}"#,+ &[(+ "accept".to_string(),+ "application/json, text/event-stream; q=0.9".to_string(),+ )],+ ));+ assert!(!wants_streaming_chat(+ &Method::Post,+ path,+ r#"{"message":"hello","stream":false}"#,+ &[],+ ));+ assert!(!wants_streaming_chat(+ &Method::Post,+ path,+ r#"{"message":"hello","stream":false}"#,+ &[("accept".to_string(), "text/event-stream".to_string())],+ ));+ assert!(!wants_streaming_chat(+ &Method::Post,+ "/api/v1/projects/current/search",+ r#"{"stream":true}"#,+ &[],+ ));+ assert!(!wants_streaming_chat(+ &Method::Post,+ "/api/v1/projects/current/chat/s1/cancel",+ r#"{"stream":true}"#,+ &[],+ ));+ assert!(!wants_streaming_chat(+ &Method::Post,+ "/projects/current/chat",+ r#"{"stream":true}"#,+ &[],+ ));+ assert!(!wants_streaming_chat(+ &Method::Post,+ "/api/v1/api/v1/projects/current/chat",+ r#"{"stream":true}"#,+ &[],+ ));+ }++ #[test]+ fn sse_reader_preserves_event_frames_until_sender_closes() {+ let (sender, receiver) = mpsc::sync_channel(4);+ sender+ .send(sse_frame("meta", &json!({ "sessionId": "s1" })))+ .unwrap();+ sender+ .send(sse_frame(+ "agent",+ &json!({ "type": "messageDelta", "text": "Hi" }),+ ))+ .unwrap();+ drop(sender);++ let mut body = String::new();+ let mut reader = SseReader::new(receiver);+ assert_eq!(reader.read(&mut []).unwrap(), 0);+ reader.read_to_string(&mut body).unwrap();+ assert!(body.contains("event: meta\n"));+ assert!(body.contains(r#"data: {"sessionId":"s1"}"#));+ assert!(body.contains("event: agent\n"));+ assert!(body.contains(r#""type":"messageDelta""#));+ }++ #[test]+ fn sse_queue_rejects_backpressure_without_blocking_runtime_threads() {+ let (sender, _receiver) = mpsc::sync_channel(1);+ assert!(matches!(+ try_send_sse(&sender, b"first".to_vec()),+ SseSendResult::Sent+ ));+ assert!(matches!(+ try_send_sse(&sender, b"second".to_vec()),+ SseSendResult::Full+ ));+ }++ #[test]+ fn sse_queue_reports_disconnected_clients() {+ let (sender, receiver) = mpsc::sync_channel(1);+ drop(receiver);+ assert!(matches!(+ try_send_sse(&sender, b"event".to_vec()),+ SseSendResult::Disconnected+ ));+ }++ #[test]+ fn terminal_sse_waits_for_queue_capacity() {+ let (sender, receiver) = mpsc::sync_channel(1);+ sender.send(b"agent".to_vec()).unwrap();+ send_terminal_sse(sender, b"done".to_vec());++ assert_eq!(receiver.recv().unwrap(), b"agent");+ assert_eq!(receiver.recv().unwrap(), b"done");+ }+#[test]fn api_config_shape_parses_enabled_and_unauthenticated_access() {// Standalone pure-function check to mirror what `api_enabled`diff --git a/src/components/settings/sections/api-server-section.tsx b/src/components/settings/sections/api-server-section.tsxindex be8d2ebb..113ca975 100644--- a/src/components/settings/sections/api-server-section.tsx+++ b/src/components/settings/sections/api-server-section.tsx@@ -54,12 +54,13 @@ export const API_ENDPOINTS: Array<{ method: "GET" | "POST" | "PATCH"; path: stri{ method: "GET", path: "/api/v1/projects/{id}/graph", noteKey: "endpointGraphNote" },{ method: "POST", path: "/api/v1/projects/{id}/sources/rescan", noteKey: "endpointRescanNote" },{ method: "POST", path: "/api/v1/projects/{id}/chat", noteKey: "endpointChatNote" },+ { method: "POST", path: "/api/v1/projects/{id}/chat/{sessionId}/cancel", noteKey: "endpointChatCancelNote" },]export function ApiServerSection({ draft, setDraft }: Props) {const { t } = useTranslation()const [showToken, setShowToken] = useState(false)- const [copiedField, setCopiedField] = useState<"token" | "curl" | "mcp" | null>(null)+ const [copiedField, setCopiedField] = useState<"token" | "curl" | "chat" | "mcp" | null>(null)const [serverStatus, setServerStatus] = useState<string>("...")const [health, setHealth] = useState<ApiHealth | null>(null)const [mcpEntryPath, setMcpEntryPath] = useState<string | null>(null)@@ -123,14 +124,30 @@ export function ApiServerSection({ draft, setDraft }: Props) {// header is the recommended auth (never put the token in URL// query — it leaks into logs / shell history / Referer).const tokenForExample = draft.apiToken || "<your-token>"- return `curl -H 'Authorization: Bearer ${tokenForExample}' ${API_SERVER_BASE_URL}/api/v1/projects`+ return `curl -H "Authorization: Bearer ${tokenForExample}" ${API_SERVER_BASE_URL}/api/v1/projects`}, [draft.apiAllowUnauthenticated, draft.apiToken])+ const sampleChatCurl = useMemo(() => {+ const tokenForExample = health?.tokenSource === "env"+ ? "$LLM_WIKI_API_TOKEN"+ : draft.apiToken || "<your-token>"+ return `curl -N -X POST \\+ -H "Authorization: Bearer ${tokenForExample}" \\+ -H 'Content-Type: application/json' \\+ -H 'Accept: text/event-stream' \\+ ${API_SERVER_BASE_URL}/api/v1/projects/current/chat \\+ -d '{"message":"Summarize this knowledge base.","stream":true}'`+ }, [draft.apiToken, health?.tokenSource])+const sampleMcpConfig = useMemo(() => {if (!mcpEntryPath) return ""- const env = draft.apiAllowUnauthenticated- ? {}- : { LLM_WIKI_API_TOKEN: draft.apiToken || "<your-token>" }+ const env = health?.tokenSource === "env"+ ? { LLM_WIKI_API_TOKEN: "<same value as the LLM Wiki process environment>" }+ : draft.apiToken+ ? { LLM_WIKI_API_TOKEN: draft.apiToken }+ : draft.apiAllowUnauthenticated+ ? {}+ : { LLM_WIKI_API_TOKEN: "<your-token>" }return JSON.stringify({mcpServers: {@@ -144,7 +161,7 @@ export function ApiServerSection({ draft, setDraft }: Props) {null,2,)- }, [draft.apiAllowUnauthenticated, draft.apiToken, mcpEntryPath])+ }, [draft.apiAllowUnauthenticated, draft.apiToken, health?.tokenSource, mcpEntryPath])const hasUnsavedApiConfig =persistedApiConfig.enabled !== draft.apiEnabled ||@@ -163,6 +180,16 @@ export function ApiServerSection({ draft, setDraft }: Props) {}}, [sampleCurl])+ const handleCopyChatCurl = useCallback(async () => {+ try {+ await navigator.clipboard.writeText(sampleChatCurl)+ setCopiedField("chat")+ setTimeout(() => setCopiedField(null), 1500)+ } catch (err) {+ console.error("[api-settings] copy streaming chat curl failed:", err)+ }+ }, [sampleChatCurl])+const handleCopyMcpConfig = useCallback(async () => {if (!mcpEntryPath) returntry {@@ -334,7 +361,7 @@ export function ApiServerSection({ draft, setDraft }: Props) {</Button><span className="text-[11px] text-muted-foreground">{t("settings.sections.apiServer.openHealthHint", {- defaultValue: "Opens in your system browser. /health is the only unauthenticated endpoint.",+ defaultValue: "/health never requires authentication. Other endpoints follow the access mode below, except Agent chat, which always requires a token.",})}</span></div>@@ -349,7 +376,7 @@ export function ApiServerSection({ draft, setDraft }: Props) {<p className="mt-1 text-xs leading-relaxed text-muted-foreground">{t("settings.sections.apiServer.tokenHint", {defaultValue:- "Required unless unauthenticated access is enabled. Send as `Authorization: Bearer <token>` or `X-LLM-Wiki-Token: <token>`. The environment variable LLM_WIKI_API_TOKEN overrides this field if set.",+ "Send as `Authorization: Bearer <token>` or `X-LLM-Wiki-Token: <token>`. Read-oriented endpoints may omit it when unauthenticated access is enabled, but Agent chat and cancellation always require it. The environment variable LLM_WIKI_API_TOKEN overrides this field if set.",})}</p></div>@@ -414,14 +441,14 @@ export function ApiServerSection({ draft, setDraft }: Props) {{tokenStrength === "missing" && (<span className="text-xs text-amber-700 dark:text-amber-400">{t("settings.sections.apiServer.tokenMissing", {- defaultValue: "No token — every endpoint will return 401",+ defaultValue: "No token — Agent chat is unavailable and protected endpoints return 401",})}</span>)}- {tokenStrength === "unused" && (+ {tokenStrength === "unused" && health?.tokenSource !== "env" && (<span className="text-xs text-amber-700 dark:text-amber-400">{t("settings.sections.apiServer.tokenUnused", {- defaultValue: "Token is not used while unauthenticated access is enabled",+ defaultValue: "Read endpoints are open, but Agent chat still uses this token",})}</span>)}@@ -497,6 +524,53 @@ export function ApiServerSection({ draft, setDraft }: Props) {</div>{/* ── Endpoint catalog ──────────────────────────────────────── */}+ <div className="space-y-3 rounded-lg border border-border/60 bg-muted/20 p-4">+ <div className="flex items-start justify-between gap-3">+ <div>+ <h3 className="text-sm font-semibold">+ {t("settings.sections.apiServer.chatTitle", { defaultValue: "Agent chat and streaming" })}+ </h3>+ <p className="mt-1 text-xs leading-relaxed text-muted-foreground">+ {t("settings.sections.apiServer.chatHint", {+ defaultValue:+ "POST a message to /chat. The default response is one JSON document. Set stream: true or send Accept: text/event-stream to receive SSE frames while the Agent works.",+ })}+ </p>+ </div>+ <Button type="button" variant="outline" size="sm" onClick={handleCopyChatCurl} disabled={hasUnsavedApiConfig} className="shrink-0 gap-1.5">+ <Copy className="h-3.5 w-3.5" />+ {copiedField === "chat"+ ? t("settings.sections.apiServer.copied", { defaultValue: "Copied" })+ : t("settings.sections.apiServer.copy", { defaultValue: "Copy" })}+ </Button>+ </div>+ <div className="grid gap-2 text-xs sm:grid-cols-2">+ <div className="rounded-md border border-border/60 bg-background/40 px-3 py-2">+ <div className="font-medium">{t("settings.sections.apiServer.chatJsonTitle", { defaultValue: "JSON mode" })}</div>+ <p className="mt-1 leading-relaxed text-muted-foreground">+ {t("settings.sections.apiServer.chatJsonHint", { defaultValue: "Omit stream or set it to false. The request returns after the complete Agent turn." })}+ </p>+ </div>+ <div className="rounded-md border border-border/60 bg-background/40 px-3 py-2">+ <div className="font-medium">{t("settings.sections.apiServer.chatSseTitle", { defaultValue: "SSE mode" })}</div>+ <p className="mt-1 leading-relaxed text-muted-foreground">+ {t("settings.sections.apiServer.chatSseHint", { defaultValue: "Frames: meta, incremental agent events, then done, cancelled, or error. done contains the complete aggregate response." })}+ </p>+ </div>+ </div>+ <div className="flex items-start gap-2 text-xs leading-relaxed text-amber-700 dark:text-amber-400">+ <ShieldAlert className="mt-0.5 h-3.5 w-3.5 shrink-0" />+ <span>+ {t("settings.sections.apiServer.chatTokenRequired", { defaultValue: "Agent chat and its cancellation endpoint always require a token, even when read endpoints allow unauthenticated access." })}+ </span>+ </div>+ <pre className="overflow-x-auto whitespace-pre-wrap break-all rounded-md bg-background/60 px-3 py-2 text-[11px] font-mono leading-relaxed">+ {hasUnsavedApiConfig+ ? t("settings.sections.apiServer.saveFirstExample", { defaultValue: "Save settings first, then copy an example request." })+ : sampleChatCurl}+ </pre>+ </div>+<div className="space-y-2 rounded-lg border border-border/60 bg-muted/20 p-4"><h3 className="text-sm font-semibold">{t("settings.sections.apiServer.endpoints", { defaultValue: "Endpoints" })}diff --git a/src/i18n/en.json b/src/i18n/en.jsonindex ad3fd6a3..e484b6e0 100644--- a/src/i18n/en.json+++ b/src/i18n/en.json@@ -776,7 +776,7 @@"statusUnknown": "Unknown","baseUrl": "Base URL","openHealth": "Open /health",- "openHealthHint": "Opens in your system browser. /health is the only unauthenticated endpoint.",+ "openHealthHint": "/health never requires authentication. Other endpoints follow the access mode below, except Agent chat, which always requires a token.","allowUnauthenticated": "Allow access without a token","allowUnauthenticatedHint": "Use only for trusted local agents. Any process or browser page on this machine can call the API while this is enabled.","allowLanAccess": "Allow API and Clip server access from the local network",@@ -787,15 +787,15 @@"mcpUsageHint": "Build once with `npm run mcp:build`, then configure your MCP client to run the server below. Use LLM_WIKI_API_TOKEN unless unauthenticated access is enabled.","mcpPathUnavailable": "MCP server entry was not found. Run `npm run mcp:build` from the LLM Wiki repository, then reopen Settings.","token": "Access token",- "tokenHint": "Required unless unauthenticated access is enabled. Send as `Authorization: Bearer <token>` or `X-LLM-Wiki-Token: <token>`. The environment variable LLM_WIKI_API_TOKEN overrides this field if set.",+ "tokenHint": "Send as `Authorization: Bearer <token>` or `X-LLM-Wiki-Token: <token>`. Read endpoints may omit it when unauthenticated access is enabled, but Agent chat and cancellation always require it. The environment variable LLM_WIKI_API_TOKEN overrides this field if set.","tokenPlaceholder": "Paste an existing token or click Generate","generate": "Generate new token","show": "Show","hide": "Hide","copy": "Copy","copied": "Copied",- "tokenMissing": "No token — every endpoint will return 401",- "tokenUnused": "Token is not used while unauthenticated access is enabled",+ "tokenMissing": "No token — Agent chat is unavailable and protected endpoints return 401",+ "tokenUnused": "Read endpoints are open, but Agent chat still uses this token","envTokenActive": "LLM_WIKI_API_TOKEN is active and overrides this field","tokenWeak": "Token is short — consider Generate for 256-bit entropy","saveFirst": "Save settings to apply API/MCP changes",@@ -803,6 +803,13 @@"tokenWarning": "Keep this token secret. Anyone with the token on this machine can read your project files via localhost.","tokenQueryWarning": "Prefer the Authorization header — passing ?token=… via URL leaks the value into shell history, logs, and Referer headers.","sample": "Example request",+ "chatTitle": "Agent chat and streaming",+ "chatHint": "POST a message to /chat. The default response is one JSON document. Set stream: true or send Accept: text/event-stream to receive SSE frames while the Agent works.",+ "chatJsonTitle": "JSON mode",+ "chatJsonHint": "Omit stream or set it to false. The request returns after the complete Agent turn.",+ "chatSseTitle": "SSE mode",+ "chatSseHint": "Frames: meta, incremental agent events, then done, cancelled, or error. done contains the complete aggregate response.",+ "chatTokenRequired": "Agent chat and its cancellation endpoint always require a token, even when read endpoints allow unauthenticated access.","endpoints": "Endpoints","endpointsHint": "Replace {id} with a project UUID, a project filesystem path, or the literal 'current'.","endpointHealthNote": "Liveness probe. No auth.",@@ -815,7 +822,8 @@"endpointSearchNote": "JSON body: { query, topK?, includeContent?, queryEmbedding? }. Uses shared keyword + vector retrieval when embeddings are configured.","endpointGraphNote": "?q=…&nodeType=…&limit=N — wikilinks graph derived from wiki/*.md.","endpointRescanNote": "Triggers a backend rescan using your Source Watch config.",- "endpointChatNote": "Not implemented yet (returns 501)."+ "endpointChatNote": "Agent chat. Returns JSON by default; use stream: true or Accept: text/event-stream for SSE. A token is always required.",+ "endpointChatCancelNote": "Cancels the active Agent turn for a session. A token is always required."},"output": {"title": "Output Preferences",diff --git a/src/i18n/it.json b/src/i18n/it.jsonindex d4355f3c..c50679b1 100644--- a/src/i18n/it.json+++ b/src/i18n/it.json@@ -776,7 +776,7 @@"statusUnknown": "Sconosciuto","baseUrl": "URL di base","openHealth": "Apri /health",- "openHealthHint": "Si apre nel browser di sistema. /health è l'unico endpoint senza autenticazione.",+ "openHealthHint": "/health non richiede mai autenticazione. Gli altri endpoint seguono la modalità di accesso seguente, tranne la chat Agent che richiede sempre un token.","allowUnauthenticated": "Consenti l'accesso senza token","allowUnauthenticatedHint": "Usalo solo con agent locali fidati. Con questa opzione attiva, qualsiasi processo o pagina del browser su questa macchina può chiamare l'API.","allowLanAccess": "Consenti l'accesso ad API e server Clip dalla rete locale",@@ -787,15 +787,15 @@"mcpUsageHint": "Compila una volta con `npm run mcp:build`, poi configura il tuo client MCP per avviare il server qui sotto. Usa LLM_WIKI_API_TOKEN a meno che non sia attivo l'accesso senza autenticazione.","mcpPathUnavailable": "Entry point del server MCP non trovato. Esegui `npm run mcp:build` dal repository di LLM Wiki, poi riapri le Impostazioni.","token": "Token di accesso",- "tokenHint": "Obbligatorio se non è attivo l'accesso senza autenticazione. Invialo come `Authorization: Bearer <token>` oppure `X-LLM-Wiki-Token: <token>`. Se impostata, la variabile d'ambiente LLM_WIKI_API_TOKEN ha la precedenza su questo campo.",+ "tokenHint": "Invialo come `Authorization: Bearer <token>` oppure `X-LLM-Wiki-Token: <token>`. Gli endpoint di lettura possono ometterlo quando l'accesso senza autenticazione è attivo, ma chat Agent e annullamento lo richiedono sempre. LLM_WIKI_API_TOKEN ha la precedenza.","tokenPlaceholder": "Incolla un token esistente o clicca su Genera","generate": "Genera un nuovo token","show": "Mostra","hide": "Nascondi","copy": "Copia","copied": "Copiato",- "tokenMissing": "Nessun token — ogni endpoint restituirà 401",- "tokenUnused": "Il token non viene usato mentre è attivo l'accesso senza autenticazione",+ "tokenMissing": "Nessun token — la chat Agent non è disponibile e gli endpoint protetti restituiscono 401",+ "tokenUnused": "Gli endpoint di lettura sono aperti, ma la chat Agent usa ancora questo token","envTokenActive": "LLM_WIKI_API_TOKEN è attiva e ha la precedenza su questo campo","tokenWeak": "Token corto — valuta Genera per avere 256 bit di entropia","saveFirst": "Salva le impostazioni per applicare le modifiche ad API/MCP",@@ -803,6 +803,13 @@"tokenWarning": "Tieni segreto questo token. Chiunque lo possieda su questa macchina può leggere i file del tuo progetto tramite localhost.","tokenQueryWarning": "Meglio usare l'header Authorization: passare ?token=… nell'URL espone il valore nella cronologia della shell, nei log e negli header Referer.","sample": "Richiesta di esempio",+ "chatTitle": "Chat Agent e streaming",+ "chatHint": "Invia un messaggio POST a /chat. Per impostazione predefinita viene restituito un documento JSON completo. Imposta stream: true o Accept: text/event-stream per ricevere eventi SSE durante l'esecuzione.",+ "chatJsonTitle": "Modalità JSON",+ "chatJsonHint": "Ometti stream o impostalo su false. La risposta arriva al termine del turno Agent completo.",+ "chatSseTitle": "Modalità SSE",+ "chatSseHint": "Eventi: meta, eventi agent incrementali, quindi done, cancelled o error. done contiene la risposta aggregata completa.",+ "chatTokenRequired": "Chat Agent e annullamento richiedono sempre un token, anche quando gli endpoint di lettura consentono accesso senza autenticazione.","endpoints": "Endpoint","endpointsHint": "Sostituisci {id} con l'UUID di un progetto, con il percorso del progetto sul filesystem o con la parola 'current'.","endpointHealthNote": "Sonda di liveness. Nessuna autenticazione.",@@ -815,7 +822,8 @@"endpointSearchNote": "Corpo JSON: { query, topK?, includeContent?, queryEmbedding? }. Usa il recupero condiviso per parole chiave e vettori quando gli embedding sono configurati.","endpointGraphNote": "?q=…&nodeType=…&limit=N — grafo dei wikilink derivato da wiki/*.md.","endpointRescanNote": "Avvia una nuova scansione lato backend con la tua configurazione di Monitoraggio fonti.",- "endpointChatNote": "Non ancora implementato (restituisce 501)."+ "endpointChatNote": "Chat Agent. Restituisce JSON per impostazione predefinita; usa stream: true o Accept: text/event-stream per SSE. Richiede sempre un token.",+ "endpointChatCancelNote": "Annulla il turno Agent attivo per una sessione. Richiede sempre un token."},"output": {"title": "Preferenze di output",diff --git a/src/i18n/ru.json b/src/i18n/ru.jsonindex a7c5c964..c7cdad3c 100644--- a/src/i18n/ru.json+++ b/src/i18n/ru.json@@ -776,7 +776,7 @@"statusUnknown": "Неизвестно","baseUrl": "Базовый URL","openHealth": "Открыть /health",- "openHealthHint": "Открывается в системном браузере. /health — единственный эндпоинт без аутентификации.",+ "openHealthHint": "/health никогда не требует аутентификации. Остальные эндпоинты следуют режиму ниже, кроме чата Agent, которому всегда нужен токен.","allowUnauthenticated": "Разрешить доступ без токена","allowUnauthenticatedHint": "Используйте только для доверенных локальных агентов. Пока включено, любой процесс или страница браузера на этом компьютере может обращаться к API.","allowLanAccess": "Разрешить доступ к API и серверу Clip из локальной сети",@@ -787,15 +787,15 @@"mcpUsageHint": "Соберите один раз с помощью `npm run mcp:build`, затем настройте MCP-клиент на запуск сервера ниже. Используйте LLM_WIKI_API_TOKEN, если не включён доступ без аутентификации.","mcpPathUnavailable": "Точка входа MCP-сервера не найдена. Выполните `npm run mcp:build` из репозитория LLM Wiki, затем откройте Настройки заново.","token": "Токен доступа",- "tokenHint": "Обязателен, если не включён доступ без аутентификации. Отправляйте как `Authorization: Bearer <token>` или `X-LLM-Wiki-Token: <token>`. Переменная окружения LLM_WIKI_API_TOKEN переопределяет это поле, если задана.",+ "tokenHint": "Отправляйте как `Authorization: Bearer <token>` или `X-LLM-Wiki-Token: <token>`. Эндпоинты чтения могут обходиться без него в открытом режиме, но чат Agent и отмена всегда требуют токен. LLM_WIKI_API_TOKEN имеет приоритет.","tokenPlaceholder": "Вставьте существующий токен или нажмите «Сгенерировать»","generate": "Сгенерировать новый токен","show": "Показать","hide": "Скрыть","copy": "Копировать","copied": "Скопировано",- "tokenMissing": "Нет токена — каждый эндпоинт вернёт 401",- "tokenUnused": "Токен не используется, пока включён доступ без аутентификации",+ "tokenMissing": "Нет токена — чат Agent недоступен, а защищённые эндпоинты вернут 401",+ "tokenUnused": "Эндпоинты чтения открыты, но чат Agent всё ещё использует этот токен","envTokenActive": "LLM_WIKI_API_TOKEN активна и переопределяет это поле","tokenWeak": "Токен короткий — нажмите «Сгенерировать» для энтропии в 256 бит","saveFirst": "Сохраните настройки, чтобы применить изменения API/MCP",@@ -803,6 +803,13 @@"tokenWarning": "Храните этот токен в секрете. Любой, у кого есть токен на этом компьютере, сможет читать файлы вашего проекта через localhost.","tokenQueryWarning": "Предпочитайте заголовок Authorization — передача ?token=… в URL раскрывает значение в истории оболочки, логах и Referer-заголовках.","sample": "Пример запроса",+ "chatTitle": "Чат Agent и потоковый вывод",+ "chatHint": "Отправьте POST-сообщение на /chat. По умолчанию возвращается один JSON после завершения. Задайте stream: true или Accept: text/event-stream для SSE.",+ "chatJsonTitle": "Режим JSON",+ "chatJsonHint": "Не передавайте stream или задайте false. Ответ придёт после полного хода Agent.",+ "chatSseTitle": "Режим SSE",+ "chatSseHint": "События: meta, потоковые agent, затем done, cancelled или error. done содержит полный итоговый ответ.",+ "chatTokenRequired": "Чат Agent и его отмена всегда требуют токен, даже если эндпоинты чтения открыты.","endpoints": "Эндпоинты","endpointsHint": "Замените {id} на UUID проекта, путь к файловой системе проекта или литерал 'current'.","endpointHealthNote": "Проверка активности. Без авторизации.",@@ -815,7 +822,8 @@"endpointSearchNote": "JSON-тело: { query, topK?, includeContent?, queryEmbedding? }. Использует общий поиск по ключевым словам и векторам, если настроены эмбеддинги.","endpointGraphNote": "?q=…&nodeType=…&limit=N — граф вики-ссылок, построенный из wiki/*.md.","endpointRescanNote": "Запускает пересканирование бэкенда с использованием вашей конфигурации «Мониторинг источников».",- "endpointChatNote": "Пока не реализовано (возвращает 501)."+ "endpointChatNote": "Чат Agent. По умолчанию возвращает JSON; для SSE используйте stream: true или Accept: text/event-stream. Всегда требуется токен.",+ "endpointChatCancelNote": "Отменяет активный ход Agent для сессии. Всегда требуется токен."},"output": {"title": "Настройки вывода",diff --git a/src/i18n/zh.json b/src/i18n/zh.jsonindex ee4127fe..f228403f 100644--- a/src/i18n/zh.json+++ b/src/i18n/zh.json@@ -776,7 +776,7 @@"statusUnknown": "未知","baseUrl": "服务地址","openHealth": "打开 /health",- "openHealthHint": "在系统浏览器中打开。/health 是唯一不需要 token 的接口。",+ "openHealthHint": "/health 始终无需鉴权。其他接口遵循下方的访问模式,但 Agent 对话始终需要 token。","allowUnauthenticated": "允许无 token 访问","allowUnauthenticatedHint": "仅用于可信的本地智能体。启用后,这台机器上的任何进程或浏览器页面都可以调用 API。","allowLanAccess": "允许 API 和 Clip server 局域网访问",@@ -787,15 +787,15 @@"mcpUsageHint": "先执行一次 `npm run mcp:build`,然后让 MCP 客户端运行下面的服务配置。除非启用了无认证访问,否则需要设置 LLM_WIKI_API_TOKEN。","mcpPathUnavailable": "没有找到 MCP 服务入口。请在 LLM Wiki 仓库中先执行 `npm run mcp:build`,然后重新打开设置。","token": "访问令牌",- "tokenHint": "除非启用了无认证访问,否则必须配置。通过 `Authorization: Bearer <token>` 或 `X-LLM-Wiki-Token: <token>` 发送。设置了环境变量 LLM_WIKI_API_TOKEN 时优先生效。",+ "tokenHint": "通过 `Authorization: Bearer <token>` 或 `X-LLM-Wiki-Token: <token>` 发送。启用无认证访问后,读取类接口可以省略 token,但 Agent 对话和取消接口始终需要 token。环境变量 LLM_WIKI_API_TOKEN 优先生效。","tokenPlaceholder": "粘贴已有 token,或点击生成","generate": "生成新 token","show": "显示","hide": "隐藏","copy": "复制","copied": "已复制",- "tokenMissing": "未配置 token —— 所有接口都会返回 401",- "tokenUnused": "启用无认证访问时,token 不会参与鉴权",+ "tokenMissing": "未配置 token —— Agent 对话不可用,受保护的接口会返回 401",+ "tokenUnused": "读取类接口已开放,但 Agent 对话仍使用此 token","envTokenActive": "LLM_WIKI_API_TOKEN 正在生效,并会覆盖此处填写的 token","tokenWeak": "token 长度偏短 —— 建议使用「生成新 token」获得 256 位熵","saveFirst": "保存设置后 API/MCP 改动才会生效",@@ -803,6 +803,13 @@"tokenWarning": "请妥善保管。任何能访问这台机器 localhost 的进程拿到 token 后,都能通过 API 读取你的项目内容。","tokenQueryWarning": "推荐使用 Authorization header —— 将 token 放在 ?token=… 查询参数里会泄露到 shell 历史、日志和 Referer。","sample": "示例请求",+ "chatTitle": "Agent 对话与流式输出",+ "chatHint": "向 /chat POST 消息。默认在 Agent 完成后返回一个 JSON 文档;设置 stream: true 或发送 Accept: text/event-stream 可在执行过程中接收 SSE 事件。",+ "chatJsonTitle": "JSON 模式",+ "chatJsonHint": "省略 stream 或设为 false。请求会在完整 Agent 回合结束后返回。",+ "chatSseTitle": "SSE 模式",+ "chatSseHint": "事件顺序为 meta、增量 agent 事件,最后是 done、cancelled 或 error。done 包含完整汇总结果。",+ "chatTokenRequired": "Agent 对话及其取消接口始终需要 token,即使读取类接口允许无认证访问。","endpoints": "接口列表","endpointsHint": "把 {id} 替换为项目 UUID、项目文件系统路径,或字面量 'current'。","endpointHealthNote": "存活探针。无需鉴权。",@@ -815,7 +822,8 @@"endpointSearchNote": "JSON body:{ query, topK?, includeContent?, queryEmbedding? }。配置嵌入后使用统一的关键词 + 向量检索。","endpointGraphNote": "?q=…&nodeType=…&limit=N —— 基于 wiki/*.md 的双链图谱。","endpointRescanNote": "使用你的资料文件夹监控配置触发后端重新扫描。",- "endpointChatNote": "尚未实现(返回 501)。"+ "endpointChatNote": "Agent 对话。默认返回 JSON;使用 stream: true 或 Accept: text/event-stream 可启用 SSE 流式输出。此接口始终需要 Token。",+ "endpointChatCancelNote": "取消指定会话当前正在执行的 Agent 回合。此接口始终需要 Token。"},"output": {"title": "输出偏好",diff --git a/src/lib/api-server.real-llm.test.ts b/src/lib/api-server.real-llm.test.tsindex 203d6429..b4a76efa 100644--- a/src/lib/api-server.real-llm.test.ts+++ b/src/lib/api-server.real-llm.test.ts@@ -40,6 +40,20 @@ interface ApiEnvelope {[key: string]: unknown}+interface ApiChatEnvelope extends ApiEnvelope {+ sessionId?: string+ message?: {+ role?: string+ content?: string+ }+ usage?: {+ promptChars?: number+ completionChars?: number+ referenceCount?: number+ toolEventCount?: number+ }+}+interface ApiHealth extends ApiEnvelope {status?: stringenabled?: boolean@@ -48,6 +62,11 @@ interface ApiHealth extends ApiEnvelope {allowUnauthenticated?: booleanallowLanAccess?: booleantokenSource?: "env" | "store" | "none"+ agent?: {+ chat?: boolean+ streaming?: boolean+ streamProtocol?: string+ }}interface ApiProject {@@ -339,6 +358,11 @@ describe.skipIf(!ENABLED)("local API v1 against real project", () => {expect(typeof h.authConfigured).toBe("boolean")expect(typeof h.allowUnauthenticated).toBe("boolean")expect(["env", "store", "none"]).toContain(h.tokenSource)+ expect(h.agent).toMatchObject({+ chat: true,+ streaming: true,+ streamProtocol: "sse",+ })},TEST_TIMEOUT_MS,)@@ -425,6 +449,18 @@ describe.skipIf(!ENABLED)("local API v1 against real project", () => {expect(resp.body.ok).toBe(true)expect(Array.isArray(resp.body.projects)).toBe(true)expect(resp.body.currentProject == null || resp.body.currentProject.current).toBe(true)++ const chat = await api<ApiEnvelope>(+ "/api/v1/projects/current/chat",+ {+ method: "POST",+ body: JSON.stringify({ message: "This request must be rejected before calling an LLM.", stream: true }),+ },+ { auth: "none" },+ )+ expect(chat.status).toBe(401)+ expect(chat.body.ok).toBe(false)+ expect(chat.body.error).toContain("Unauthorized")},TEST_TIMEOUT_MS,)@@ -598,16 +634,70 @@ describe.skipIf(!ENABLED)("local API v1 against real project", () => {)it(- "reports chat as not implemented in API v1",+ "runs backend Agent chat through API v1",async (ctx) => {ensureServer(ctx)await requireUsableApi()- const chatResp = await api<ApiEnvelope>(`/api/v1/projects/${PROJECT_ID}/chat`, {+ if (!API_TOKEN) {+ console.warn("Skipping Agent chat API assertion because this endpoint always requires a token.")+ ctx.skip()+ }+ const chatResp = await api<ApiChatEnvelope>(`/api/v1/projects/${PROJECT_ID}/chat`, {method: "POST",body: JSON.stringify({ message: "hello" }),})- expect(chatResp.status).toBe(501)- expect(chatResp.body.ok).toBe(false)+ expect(chatResp.status).toBe(200)+ expect(chatResp.body.ok).toBe(true)+ expect(chatResp.body.sessionId).toEqual(expect.any(String))+ expect(chatResp.body.sessionId?.length).toBeGreaterThan(0)+ expect(chatResp.body.message?.role).toBe("assistant")+ expect(chatResp.body.message?.content?.trim().length).toBeGreaterThan(0)+ expect(chatResp.body.usage).toMatchObject({+ promptChars: expect.any(Number),+ completionChars: expect.any(Number),+ referenceCount: expect.any(Number),+ toolEventCount: expect.any(Number),+ })+ expect(chatResp.body.usage?.completionChars).toBeGreaterThan(0)+ },+ TEST_TIMEOUT_MS,+ )++ it(+ "streams backend Agent chat through SSE",+ async (ctx) => {+ ensureServer(ctx)+ await requireUsableApi()+ if (!API_TOKEN) {+ console.warn("Skipping streaming Agent chat assertion because this endpoint always requires a token.")+ ctx.skip()+ }+ const response = await fetch(endpoint(`/api/v1/projects/${PROJECT_ID}/chat`), {+ method: "POST",+ headers: {+ Authorization: `Bearer ${API_TOKEN}`,+ "Content-Type": "application/json",+ Accept: "text/event-stream",+ },+ body: JSON.stringify({ message: "Reply with one short sentence.", stream: true }),+ })+ expect(response.status).toBe(200)+ expect(response.headers.get("content-type")).toContain("text/event-stream")+ const body = await response.text()+ const metaIndex = body.indexOf("event: meta\n")+ const agentIndex = body.indexOf("event: agent\n")+ const doneIndex = body.indexOf("event: done\n")+ expect(metaIndex).toBeGreaterThanOrEqual(0)+ expect(agentIndex).toBeGreaterThan(metaIndex)+ expect(doneIndex).toBeGreaterThan(agentIndex)+ const doneData = body+ .split("\n\n")+ .find((frame) => frame.startsWith("event: done\n"))+ ?.split("\ndata: ")[1]+ expect(doneData).toBeTruthy()+ const done = JSON.parse(doneData ?? "{}") as ApiChatEnvelope+ expect(done.ok).toBe(true)+ expect(done.message?.content?.trim().length).toBeGreaterThan(0)},TEST_TIMEOUT_MS,)