> ## Documentation Index > Fetch the complete documentation index at: https://langchain-zh.cn/llms.txt > Use this file to discover all available pages before exploring further. # 待办事项列表 > 通过从智能体状态实时同步的待办事项列表追踪智能体进度 export const PatternEmbed = ({pattern, theme, height, minHeight = 400, maxHeight = 700, className, defaultView = "preview", defaultSdk = "react", defaultLanguage = "js", showCodeTab = true, agentServer = "prod", onError, onReady}) => { var VALID_GUEST_TYPES = new Set(["READY", "RESIZE", "ERROR", "RUN_STARTED", "TRACE_URL", "THREAD_CLEARED"]); function stub() { return { safeParse: data => ({ success: true, data }), optional: () => stub(), min: () => stub(), url: () => stub() }; } var z = { object: _shape => stub(), literal: _value => stub(), string: () => stub(), number: () => stub(), boolean: () => stub(), enum: _values => stub(), array: _el => stub(), union: _schemas => stub(), record: (_key, _value) => stub(), discriminatedUnion: (_key, _schemas) => ({ safeParse(data) { if (data != null && typeof data === "object" && ("type" in data) && typeof data.type === "string" && VALID_GUEST_TYPES.has(data.type)) { return { success: true, data }; } return { success: false }; }, optional: () => stub(), min: () => stub(), url: () => stub() }) }; var SetThemeMessageSchema = z.object({ type: z.literal("SET_THEME"), theme: z.enum(["light", "dark"]) }); var SetPatternMessageSchema = z.object({ type: z.literal("SET_PATTERN"), slug: z.string() }); var ResetMessageSchema = z.object({ type: z.literal("RESET") }); var SetViewMessageSchema = z.object({ type: z.literal("SET_VIEW"), view: z.enum(["preview", "code"]) }); var SetLanguageMessageSchema = z.object({ type: z.literal("SET_LANGUAGE"), language: z.enum(["js", "python"]) }); var CodeFileSchema = z.object({ filename: z.string(), content: z.string() }); var UpdateCodeMessageSchema = z.object({ type: z.literal("UPDATE_CODE"), files: z.array(CodeFileSchema).min(1), entryFile: z.string() }); var TrackEventMessageSchema = z.object({ type: z.literal("TRACK_EVENT"), name: z.string(), properties: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional() }); var HostToGuestMessageSchema = z.discriminatedUnion("type", [SetThemeMessageSchema, SetPatternMessageSchema, ResetMessageSchema, UpdateCodeMessageSchema, SetViewMessageSchema, SetLanguageMessageSchema, TrackEventMessageSchema]); var ReadyMessageSchema = z.object({ type: z.literal("READY"), framework: z.enum(["react", "vue", "angular", "svelte"]) }); var ResizeMessageSchema = z.object({ type: z.literal("RESIZE"), height: z.number() }); var ErrorMessageSchema = z.object({ type: z.literal("ERROR"), message: z.string(), stack: z.string().optional() }); var RunStartedMessageSchema = z.object({ type: z.literal("RUN_STARTED"), runId: z.string() }); var TraceUrlMessageSchema = z.object({ type: z.literal("TRACE_URL"), url: z.string().url(), runId: z.string() }); var ThreadClearedMessageSchema = z.object({ type: z.literal("THREAD_CLEARED") }); var GuestToHostMessageSchema = z.discriminatedUnion("type", [ReadyMessageSchema, ResizeMessageSchema, ErrorMessageSchema, RunStartedMessageSchema, TraceUrlMessageSchema, ThreadClearedMessageSchema]); var PreviewMessageSchema = z.union([HostToGuestMessageSchema, GuestToHostMessageSchema]); function isOriginAllowed(origin, allowedOrigins) { return allowedOrigins.includes("*") || allowedOrigins.includes(origin); } function createPreviewHost(iframe, options) { const {allowedOrigins} = options; const targetOrigins = options.targetOrigins ?? allowedOrigins; const listeners = new Map(); function postToGuest(message) { if (!iframe.contentWindow) return; for (const origin of targetOrigins) { iframe.contentWindow.postMessage(message, origin); } } function addListener(type, callback) { if (!listeners.has(type)) { listeners.set(type, new Set()); } listeners.get(type).add(callback); return () => { listeners.get(type)?.delete(callback); }; } function handleMessage(event) { if (!isOriginAllowed(event.origin, allowedOrigins)) return; const result = GuestToHostMessageSchema.safeParse(event.data); if (!result.success) return; const msg = result.data; const cbs = listeners.get(msg.type); if (!cbs) return; for (const cb of cbs) { switch (msg.type) { case "READY": cb(msg.framework); break; case "RESIZE": cb(msg.height); break; case "ERROR": cb(msg.message, msg.stack); break; case "RUN_STARTED": cb(msg.runId); break; case "TRACE_URL": cb(msg.url, msg.runId); break; case "THREAD_CLEARED": cb(); break; } } } window.addEventListener("message", handleMessage); return { setTheme(theme) { postToGuest({ type: "SET_THEME", theme }); }, setPattern(slug) { postToGuest({ type: "SET_PATTERN", slug }); }, setView(view) { postToGuest({ type: "SET_VIEW", view }); }, setLanguage(language) { postToGuest({ type: "SET_LANGUAGE", language }); }, updateCode(files, entryFile) { postToGuest({ type: "UPDATE_CODE", files, entryFile }); }, reset() { postToGuest({ type: "RESET" }); }, trackEvent(name, properties) { postToGuest({ type: "TRACK_EVENT", name, properties }); }, onReady(callback) { return addListener("READY", callback); }, onResize(callback) { return addListener("RESIZE", callback); }, onError(callback) { return addListener("ERROR", callback); }, onRunStarted(callback) { return addListener("RUN_STARTED", callback); }, onTraceUrl(callback) { return addListener("TRACE_URL", callback); }, onThreadCleared(callback) { return addListener("THREAD_CLEARED", callback); }, destroy() { window.removeEventListener("message", handleMessage); listeners.clear(); } }; } var PROD_BASE = "https://ui-patterns.langchain.com"; var SDK_LABELS = { react: "React", vue: "Vue", svelte: "Svelte", angular: "Angular" }; var SDK_LOCAL_HOSTS = { react: "http://localhost:4100", vue: "http://localhost:4200", svelte: "http://localhost:4300", angular: "http://localhost:4400" }; var SDK_PROD_HOSTS = { react: `${PROD_BASE}/react`, vue: `${PROD_BASE}/vue`, svelte: `${PROD_BASE}/svelte`, angular: `${PROD_BASE}/angular` }; var SDK_LOGOS = { react: ``, vue: ``, svelte: ``, angular: `` }; var PROD_AGENT_API_BASE = `${PROD_BASE}/api/langgraph`; function normalizeAgentServerBase(agentServer, useLocalPreview) { const trimmed = agentServer.trim(); if (useLocalPreview) { return "http://localhost:2024"; } if (trimmed === "prod") { return PROD_AGENT_API_BASE; } if (trimmed === "local") { return PROD_AGENT_API_BASE; } return PROD_AGENT_API_BASE; } function isLocalhost() { if (typeof window === "undefined") return false; const {hostname} = window.location; return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::]"; } function detectPageTheme() { if (typeof document === "undefined") return "light"; const el = document.documentElement; if (el.classList.contains("dark")) return "dark"; if (el.getAttribute("data-theme") === "dark") return "dark"; if (el.style.colorScheme === "dark") return "dark"; return "light"; } var CACHE_KEY = "__lcPlaygroundIframeCache"; var iframeCache = globalThis[CACHE_KEY] ?? (() => { const m = new Map(); globalThis[CACHE_KEY] = m; return m; })(); var SDK_CACHE_KEY = "__lcPlaygroundSdkCache"; var sdkCache = globalThis[SDK_CACHE_KEY] ?? (() => { const m = new Map(); globalThis[SDK_CACHE_KEY] = m; return m; })(); var LANG_CACHE_KEY = "__lcPlaygroundLangCache"; var langCache = globalThis[LANG_CACHE_KEY] ?? (() => { const m = new Map(); globalThis[LANG_CACHE_KEY] = m; return m; })(); var VIEW_EYE_SVG = ``; var VIEW_CODE_SVG = ``; var CHEVRON_DOWN_SVG = ``; var TRACE_ICON_SVG = ``; var TRACE_SPINNER_SVG = ``; var EXTERNAL_LINK_SVG = ``; var DOWNLOAD_SVG = ``; var EXPAND_SVG = ``; var CLOSE_SVG = ``; var LANG_TS_SVG = ``; var LANG_PYTHON_SVG = ` `; var SDK_OPTIONS = Object.keys(SDK_LABELS).map(k => [k, SDK_LABELS[k]]); var EMBED_CSS = ` [data-lc-pe] .lc-tab{font-size:13px;font-family:inherit} [data-lc-pe] .lc-sdk-option{font-size:13px} [data-lc-pe] .lc-border{border-color:#B8DFFF} [data-lc-pe].dark .lc-border{border-color:#1A2740} [data-lc-pe] .lc-bg-surface{background-color:white} [data-lc-pe].dark .lc-bg-surface{background-color:#0B1120} [data-lc-pe] .lc-bg-wash{background-color:#F2FAFF} [data-lc-pe].dark .lc-bg-wash{background-color:#030710} [data-lc-pe] .lc-tab-active{background-color:#7FC8FF;color:#030710} [data-lc-pe] .lc-tab-inactive{background-color:transparent;color:#6B8299} [data-lc-pe] .lc-tab-inactive:hover{background-color:#E5F4FF;color:#030710} [data-lc-pe].dark .lc-tab-inactive:hover{background-color:#1A2740;color:#C8DDF0} [data-lc-pe] .lc-tab-trace{background-color:#FFF3E0;color:#E65100} [data-lc-pe].dark .lc-tab-trace{background-color:#3E2723;color:#FFB74D} [data-lc-pe] .lc-tab-trace:hover{background-color:#FFE0B2} [data-lc-pe].dark .lc-tab-trace:hover{background-color:#4E342E} [data-lc-pe] .lc-tab-trace-loading{background-color:transparent;color:#6B8299;cursor:not-allowed} [data-lc-pe] .lc-sdk-btn{border-color:#B8DFFF;background-color:white;font-size:13px;color:#030710} [data-lc-pe].dark .lc-sdk-btn{border-color:#1A2740;background-color:#0B1120;color:#C8DDF0} [data-lc-pe] .lc-sdk-btn:hover{background-color:#E5F4FF} [data-lc-pe].dark .lc-sdk-btn:hover{background-color:#1A2740} [data-lc-pe] .lc-dropdown{border-color:#B8DFFF;background-color:white;min-width:120px} [data-lc-pe].dark .lc-dropdown{border-color:#1A2740;background-color:#0B1120} [data-lc-pe] .lc-sdk-selected{background-color:#E5F4FF;color:#030710} [data-lc-pe].dark .lc-sdk-selected{background-color:#1A2740;color:#C8DDF0} [data-lc-pe] .lc-sdk-unselected{color:#6B8299} [data-lc-pe] .lc-sdk-unselected:hover{background-color:#F2FAFF;color:#030710} [data-lc-pe].dark .lc-sdk-unselected:hover{background-color:#1A2740;color:#C8DDF0} [data-lc-pe] .lc-spinner{border-color:#B8DFFF;border-top-color:#7FC8FF} [data-lc-pe].dark .lc-spinner{border-color:#1A2740;border-top-color:#7FC8FF} [data-lc-pe] .lc-error{background-color:rgb(178 125 117/0.1);border-color:rgb(178 125 117/0.3);color:#B27D75} [data-lc-pe] .lc-error-btn{border-color:rgb(178 125 117/0.3);background-color:white;color:#B27D75} [data-lc-pe].dark .lc-error-btn{background-color:#0B1120} [data-lc-pe] .lc-lang-switcher .lc-tab{padding:4px 8px} @media(max-width:639px){ [data-lc-pe] .lc-toolbar{flex-wrap:wrap;gap:8px} [data-lc-pe] .lc-tab-label{display:none} [data-lc-pe] .lc-tab{padding-left:10px;padding-right:10px} [data-lc-pe] .lc-sdk-btn{margin-left:auto} } [data-lc-pe] .lc-expand-btn{border:none;background:transparent;cursor:pointer;padding:6px;border-radius:6px;display:inline-flex;align-items:center;justify-content:center;color:#6B8299;transition:background-color 0.15s,color 0.15s} [data-lc-pe] .lc-expand-btn:hover{background-color:#E5F4FF;color:#030710} [data-lc-pe].dark .lc-expand-btn:hover{background-color:#1A2740;color:#C8DDF0} .lc-pe-backdrop{position:fixed;inset:0;z-index:9998;background:rgba(0,0,0,0.4);backdrop-filter:blur(4px);-webkit-backdrop-filter:blur(4px)} `; const slotRef = useRef(null); const cardRef = useRef(null); const placeholderRef = useRef(null); const cachedRef = useRef(null); const useLocalPreview = agentServer === "local" || agentServer === "prod" && isLocalhost(); const agentQuery = agentServer !== "local" && agentServer !== "prod" ? `?agentServer=${encodeURIComponent(agentServer)}` : ""; const sdkCacheKey = `${agentServer}|${pattern}`; const [sdk, setSdkRaw] = useState(() => { const fromCache = sdkCache.get(sdkCacheKey); if (fromCache) return fromCache; const hosts = useLocalPreview ? SDK_LOCAL_HOSTS : SDK_PROD_HOSTS; let best = null; for (const [s, url] of Object.entries(hosts)) { const entry = iframeCache.get(`${url}|${agentQuery}`); if (entry?.lastActiveAt && (!best || entry.lastActiveAt > best.at)) { best = { sdk: s, at: entry.lastActiveAt }; } } if (best) return best.sdk; return defaultSdk; }); const setSdk = useCallback(s => { sdkCache.set(sdkCacheKey, s); setSdkRaw(s); }, [sdkCacheKey]); const [sdkDropdownOpen, setSdkDropdownOpen] = useState(false); const langCacheKey = `${agentServer}|${pattern}`; const [agentLang, setAgentLangRaw] = useState(() => langCache.get(langCacheKey) ?? defaultLanguage); const setAgentLang = useCallback(l => { langCache.set(langCacheKey, l); setAgentLangRaw(l); }, [langCacheKey]); const previewUrl = useLocalPreview ? SDK_LOCAL_HOSTS[sdk] : SDK_PROD_HOSTS[sdk]; const cacheKey = `${previewUrl}|${agentQuery}`; const [ready, setReady] = useState(() => iframeCache.get(cacheKey)?.ready ?? false); const [iframeHeight, setIframeHeight] = useState(() => iframeCache.get(cacheKey)?.lastHeight ?? minHeight); const [error, setError] = useState(null); const [activeView, setActiveView] = useState(() => iframeCache.get(cacheKey)?.lastView ?? defaultView); const [traceUrl, setTraceUrl] = useState(null); const [traceLoading, setTraceLoading] = useState(false); const [expanded, setExpanded] = useState(false); const expandedRef = useRef(false); expandedRef.current = expanded; const [pageTheme, setPageTheme] = useState(detectPageTheme); useEffect(() => { setPageTheme(detectPageTheme()); const observer = new MutationObserver(() => setPageTheme(detectPageTheme())); observer.observe(document.documentElement, { attributes: true, attributeFilter: ["class", "data-theme", "style"] }); return () => observer.disconnect(); }, []); const effectiveTheme = theme ?? pageTheme; useEffect(() => { if (document.getElementById("lc-pe-css")) return; const style = document.createElement("style"); style.id = "lc-pe-css"; style.textContent = EMBED_CSS; document.head.appendChild(style); }, []); const onErrorRef = useRef(onError); onErrorRef.current = onError; const onReadyRef = useRef(onReady); onReadyRef.current = onReady; const patternRef = useRef(pattern); patternRef.current = pattern; const themeRef = useRef(effectiveTheme); themeRef.current = effectiveTheme; const activeViewRef = useRef(activeView); activeViewRef.current = activeView; const agentLangRef = useRef(agentLang); agentLangRef.current = agentLang; useEffect(() => { let cached = iframeCache.get(cacheKey); if (cached?.hideTimer) { clearTimeout(cached.hideTimer); cached.hideTimer = void 0; } if (!cached) { const iframe2 = document.createElement("iframe"); iframe2.src = `${previewUrl}/${agentQuery}#/${patternRef.current}`; iframe2.setAttribute("sandbox", "allow-scripts allow-same-origin allow-forms"); iframe2.setAttribute("allow", "clipboard-write"); iframe2.title = `${patternRef.current} pattern`; iframe2.setAttribute("data-cache-key", cacheKey); Object.assign(iframe2.style, { position: "fixed", border: "none", visibility: "hidden", pointerEvents: "auto", zIndex: "1", borderRadius: "0 0 15px 15px" }); document.body.appendChild(iframe2); let iframeOrigin; try { iframeOrigin = new URL(previewUrl).origin; } catch { iframeOrigin = previewUrl; } const host2 = createPreviewHost(iframe2, { allowedOrigins: [iframeOrigin] }); cached = { iframe: iframe2, host: host2, ready: false, lastHeight: minHeight, lastView: defaultView, lastActiveAt: 0 }; iframeCache.set(cacheKey, cached); } cachedRef.current = cached; const {iframe, host} = cached; if (cached.ready) { setReady(true); setIframeHeight(cached.lastHeight); host.setTheme(themeRef.current); host.setPattern(patternRef.current); host.setLanguage(agentLangRef.current); if (activeViewRef.current !== "preview") { host.setView(activeViewRef.current); } cached.lastActiveAt = Date.now(); iframe.style.visibility = "visible"; } const unsubReady = host.onReady(() => { cached.ready = true; cached.lastActiveAt = Date.now(); setReady(true); host.setTheme(themeRef.current); host.setPattern(patternRef.current); host.setLanguage(agentLangRef.current); if (activeViewRef.current !== "preview") { host.setView(activeViewRef.current); } iframe.style.visibility = "visible"; onReadyRef.current?.(); }); const unsubResize = host.onResize(h => { if (expandedRef.current) return; const clamped = Math.min(maxHeight, Math.max(minHeight, h)); cached.lastHeight = clamped; setIframeHeight(clamped); }); const unsubError = host.onError((message, stack) => { setError(message); iframe.style.visibility = "hidden"; onErrorRef.current?.(message, stack); }); const unsubRunStarted = host.onRunStarted(() => { setTraceUrl(null); setTraceLoading(true); }); const unsubTraceUrl = host.onTraceUrl((url, _runId) => { setTraceUrl(url); setTraceLoading(false); }); const unsubThreadCleared = host.onThreadCleared(() => { setTraceUrl(null); setTraceLoading(false); }); function syncPosition() { const slot2 = slotRef.current; if (!slot2) return; const rect = slot2.getBoundingClientRect(); const {style} = iframe; style.top = `${rect.top}px`; style.left = `${rect.left}px`; style.width = `${rect.width}px`; style.setProperty("height", `${rect.height}px`, "important"); if (expandedRef.current) { style.zIndex = "10000"; } else { style.zIndex = "1"; } } syncPosition(); const ro = new ResizeObserver(syncPosition); if (slotRef.current) ro.observe(slotRef.current); document.addEventListener("scroll", syncPosition, { passive: true, capture: true }); window.addEventListener("resize", syncPosition, { passive: true }); let frameCount = 0; let rafId = 0; function initialSync() { syncPosition(); if (++frameCount < 5) rafId = requestAnimationFrame(initialSync); } rafId = requestAnimationFrame(initialSync); return () => { cancelAnimationFrame(rafId); ro.disconnect(); document.removeEventListener("scroll", syncPosition, { capture: true }); window.removeEventListener("resize", syncPosition); unsubReady(); unsubResize(); unsubError(); unsubRunStarted(); unsubTraceUrl(); unsubThreadCleared(); cachedRef.current = null; cached.hideTimer = setTimeout(() => { iframe.style.visibility = "hidden"; }, 200); }; }, [cacheKey, previewUrl, agentQuery, defaultView, minHeight, maxHeight]); useEffect(() => { requestAnimationFrame(() => window.dispatchEvent(new Event("resize"))); if (!expanded) return; const card = cardRef.current; const placeholder = placeholderRef.current; if (!card || !placeholder) return; const wrapper = document.createElement("div"); wrapper.setAttribute("data-lc-pe", ""); wrapper.className = `${effectiveTheme === "dark" ? "dark" : ""}`; document.body.appendChild(wrapper); const backdrop = document.createElement("div"); backdrop.className = "lc-pe-backdrop"; backdrop.addEventListener("click", () => setExpanded(false)); wrapper.appendChild(backdrop); wrapper.appendChild(card); Object.assign(card.style, { position: "fixed", zIndex: "9999", top: "50%", left: "50%", transform: "translate(-50%, -50%)", width: "min(70vw, calc(100vw - 48px))", height: "85vh", display: "flex", flexDirection: "column" }); const handleKeyDown = e => { if (e.key === "Escape") setExpanded(false); }; document.addEventListener("keydown", handleKeyDown); const pageWrapper = document.body.children[0]; const savedFilter = pageWrapper?.style.filter ?? ""; const savedPointerEvents = pageWrapper?.style.pointerEvents ?? ""; if (pageWrapper && pageWrapper !== wrapper) { pageWrapper.style.filter = "blur(4px)"; pageWrapper.style.pointerEvents = "none"; } requestAnimationFrame(() => window.dispatchEvent(new Event("resize"))); return () => { document.removeEventListener("keydown", handleKeyDown); if (pageWrapper && pageWrapper !== wrapper) { pageWrapper.style.filter = savedFilter; pageWrapper.style.pointerEvents = savedPointerEvents; } card.style.cssText = ""; placeholder.appendChild(card); wrapper.remove(); requestAnimationFrame(() => window.dispatchEvent(new Event("resize"))); }; }, [expanded, effectiveTheme]); useEffect(() => { if (!ready || !cachedRef.current) return; setError(null); cachedRef.current.host.setPattern(pattern); }, [pattern, ready]); useEffect(() => { if (!ready || !cachedRef.current) return; cachedRef.current.host.setTheme(effectiveTheme); }, [effectiveTheme, ready]); useEffect(() => { if (!ready || !cachedRef.current) return; cachedRef.current.host.setLanguage(agentLang); }, [agentLang, ready]); const switchView = useCallback(view => { setActiveView(view); if (cachedRef.current) { cachedRef.current.lastView = view; if (cachedRef.current.ready) { cachedRef.current.host.setView(view); if (view === "code") { cachedRef.current.host.trackEvent("code_tab_clicked", { pattern }); } } } }, [pattern]); const sdkButtonRef = useRef(null); useEffect(() => { if (!sdkDropdownOpen || !sdkButtonRef.current) return; const isDark = effectiveTheme === "dark"; const rect = sdkButtonRef.current.getBoundingClientRect(); const dropdown = document.createElement("div"); Object.assign(dropdown.style, { position: "fixed", top: `${rect.bottom + 4}px`, right: `${window.innerWidth - rect.right}px`, zIndex: expandedRef.current ? "10001" : "10", minWidth: "120px", borderRadius: "8px", border: `1px solid ${isDark ? "#1A2740" : "#B8DFFF"}`, backgroundColor: isDark ? "#0B1120" : "white", boxShadow: "0 4px 12px rgba(0,0,0,0.15)", padding: "4px 0" }); for (const [value, label] of SDK_OPTIONS) { const isSelected = value === sdk; const btn = document.createElement("button"); btn.type = "button"; Object.assign(btn.style, { display: "flex", alignItems: "center", gap: "6px", width: "100%", textAlign: "left", padding: "6px 12px", fontSize: "13px", cursor: "pointer", border: "none", fontWeight: isSelected ? "500" : "normal", backgroundColor: isSelected ? isDark ? "#1A2740" : "#E5F4FF" : "transparent", color: isSelected ? isDark ? "#C8DDF0" : "#030710" : "#6B8299" }); btn.innerHTML = `${SDK_LOGOS[value]}${label}`; btn.addEventListener("mouseenter", () => { if (!isSelected) { btn.style.backgroundColor = isDark ? "#1A2740" : "#F2FAFF"; btn.style.color = isDark ? "#C8DDF0" : "#030710"; } }); btn.addEventListener("mouseleave", () => { if (!isSelected) { btn.style.backgroundColor = "transparent"; btn.style.color = "#6B8299"; } }); btn.addEventListener("click", () => { setSdk(value); setSdkDropdownOpen(false); cachedRef.current?.host.trackEvent("sdk_switched", { sdk: value, pattern }); }); dropdown.appendChild(btn); } document.body.appendChild(dropdown); const handleClose = e => { if (!dropdown.contains(e.target) && !sdkButtonRef.current?.contains(e.target)) { setSdkDropdownOpen(false); } }; const timer = setTimeout(() => document.addEventListener("mousedown", handleClose), 0); return () => { clearTimeout(timer); document.removeEventListener("mousedown", handleClose); dropdown.remove(); }; }, [sdkDropdownOpen, sdk, effectiveTheme, setSdk, pattern]); const handleReset = useCallback(() => { cachedRef.current?.host.reset(); if (cachedRef.current?.ready) { cachedRef.current.host.setPattern(pattern); } }, [pattern]); const resolvedHeight = height ?? Math.min(maxHeight, Math.max(minHeight, iframeHeight)); const heightStyle = typeof resolvedHeight === "number" ? `${resolvedHeight}px` : resolvedHeight; useEffect(() => { if (!expanded) { slotRef.current?.style.setProperty("height", heightStyle, "important"); } else { slotRef.current?.style.removeProperty("height"); } }, [heightStyle, expanded]); const tabBase = "lc-tab inline-flex items-center gap-1.5 px-3.5 py-1.5 rounded-lg border-none font-medium cursor-pointer transition-all duration-150"; const tabActiveClass = `${tabBase} lc-tab-active shadow-sm`; const tabInactiveClass = `${tabBase} lc-tab-inactive`; const tabTraceActiveClass = `${tabBase} lc-tab-trace`; const tabTraceLoadingClass = `${tabBase} lc-tab-trace-loading`; const toolbar = showCodeTab &&
{(traceUrl || traceLoading) && !useLocalPreview && { if (!traceUrl) e.preventDefault(); else cachedRef.current?.host.trackEvent("trace_tab_clicked", { pattern }); }} className={traceUrl ? tabTraceActiveClass : tabTraceLoadingClass} aria-disabled={!traceUrl}> Trace {traceUrl && } }
{activeView === "code" &&
}
{} {}
; const slot =
{!ready && !error &&
} {error &&
Preview Error

{error}

}
; return
{toolbar} {slot}
; }; 并非所有智能体交互都是聊天。有时智能体正在执行一个多步骤计划，而展示进度的最佳方式是实时更新的**待办事项列表**。深度智能体待办事项列表模式直接从智能体状态中读取 `todos` 数组，并在智能体执行计划时，根据每个项目的当前状态进行渲染。这是一个基于你用于聊天的相同 `useStream` 钩子构建的进度仪表板。它展示了智能体状态可以驱动任何用户界面，而不仅仅是消息气泡。 ## 工作原理 在 LangGraph 智能体中，状态不仅限于消息。你可以定义**自定义状态键**来保存任意数据。在本例中，是一个 `todos` 数组。当智能体执行其计划时，它会将每个待办事项的状态从 `"pending"` 更新为 `"in_progress"` 再到 `"completed"`。`useStream` 钩子通过 `stream.values` 暴露这些自定义状态值，你的用户界面可以响应式地渲染它们。 流程如下： 1. 用户提交请求 2. 智能体创建计划并在其状态中填充 `todos` 3. 智能体开始执行每个待办事项，状态从 `pending` → `in_progress` → `completed` 过渡 4. 随着智能体推进，`stream.values.todos` 实时更新 5. 你的用户界面使用当前状态重新渲染待办事项列表 ## 设置 useStream 无需特殊配置。将 `useStream` 指向你的智能体，并从 `stream.values` 读取 `todos`。 定义一个与你的智能体状态模式匹配的 TypeScript 接口，并将其作为类型参数传递给 `useStream`，以便对状态值（包括像 `todos` 这样的自定义状态键）进行类型安全访问。在下面的示例中，将 `typeof myAgent` 替换为你的接口名称： ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import type { BaseMessage } from "@langchain/core/messages"; interface TodoItem { title: string; status: "pending" | "in_progress" | "completed"; description?: string; } interface AgentState { messages: BaseMessage[]; todos: TodoItem[]; } ``` ```tsx React theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { useStream } from "@langchain/react"; const AGENT_URL = "http://localhost:2024"; export function TodoAgent() { const stream = useStream({ apiUrl: AGENT_URL, assistantId: "deep_agent_todo_list", }); const todos = stream.values?.todos ?? []; return (
{stream.messages.map((msg) => ( ))}
); } ``` ```vue Vue theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} ``` ```svelte Svelte theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{#each $messages as msg (msg.id)} {/each}
``` ```ts Angular theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { Component, computed } from "@angular/core"; import { useStream } from "@langchain/angular"; const AGENT_URL = "http://localhost:2024"; @Component({ selector: "app-todo-agent", template: `
@for (msg of stream.messages(); track msg.id) { }
`, }) export class TodoAgentComponent { stream = useStream({ apiUrl: AGENT_URL, assistantId: "deep_agent_todo_list", }); todos = computed(() => this.stream.values()?.todos ?? []); } ``` ## Todo 接口 数组中的每个待办事项都有一个简单的结构： ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} interface Todo { status: "pending" | "in_progress" | "completed"; content: string; } ``` | 属性 | 描述 | | --------- | ------------------------------------------------------------------ | | `status` | 此任务的当前状态。选项：`pending`（未开始）、`in_progress`（智能体正在处理）、`completed`（已完成） | | `content` | 描述任务内容的人类可读文本 | 智能体在创建计划时填充此数组，然后在执行每个步骤时更新各个项目。 ## 构建 TodoList 组件 待办事项列表使用状态图标、颜色编码和反映当前状态的视觉样式来渲染每个项目： ```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} function TodoList({ todos }: { todos: Todo[] }) { const completed = todos.filter((t) => t.status === "completed").length; const percentage = todos.length ? Math.round((completed / todos.length) * 100) : 0; return (

智能体进度

{completed}/{todos.length} 个任务
    {todos.map((todo, i) => ( ))}
); } ``` ## 进度条 一个视觉进度条为用户提供整体完成情况的概览： ```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} function ProgressBar({ percentage }: { percentage: number }) { return (
进度 {percentage}%
); } ``` ## 单个待办事项 每个项目都有一个状态图标、颜色编码的文本，以及已完成任务的删除线样式： ```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} function TodoItem({ todo }: { todo: Todo }) { const config = { pending: { icon: "○", textClass: "text-gray-600", bgClass: "bg-gray-50", iconClass: "text-gray-400", }, in_progress: { icon: "◉", textClass: "text-amber-800", bgClass: "bg-amber-50 border-amber-200", iconClass: "text-amber-500 animate-pulse", }, completed: { icon: "✓", textClass: "text-green-800 line-through", bgClass: "bg-green-50 border-green-200", iconClass: "text-green-500", }, }; const style = config[todo.status]; return (
  • {style.icon} {todo.content}
    • ); } ``` `in_progress` 图标使用 `animate-pulse` 来吸引对当前活动任务的注意。 ## 计算进度 直接从待办事项数组推导进度指标： ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} const todos = stream.values?.todos ?? []; const completed = todos.filter((t) => t.status === "completed").length; const inProgress = todos.filter((t) => t.status === "in_progress").length; const pending = todos.filter((t) => t.status === "pending").length; const percentage = todos.length ? Math.round((completed / todos.length) * 100) : 0; ``` 这些值会随着智能体修改其状态而响应式更新，保持进度条和计数器同步。 ## 与聊天消息结合 待办事项列表与常规聊天界面协同工作。一种实用的布局是将待办事项列表显示为持久的侧边栏或标题面板，聊天消息显示在下方： ```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} function TodoAgentLayout() { const stream = useStream({ apiUrl: AGENT_URL, assistantId: "deep_agent_todo_list", }); const todos = stream.values?.todos ?? []; return (
    {todos.length > 0 && (
    )}
    {stream.messages.map((msg) => ( ))}
    stream.submit({ messages: [{ type: "human", content: text }] }) } isLoading={stream.isLoading} />
    ); } ``` 仅当 `todos.length > 0` 时显示待办事项列表。在智能体创建计划之前，没有内容可显示。显示空组件会浪费空间。 ## 超越待办事项的自定义状态 此模式展示了一个强大的原则：`stream.values` 可以暴露你的智能体定义的**任何自定义状态**，而不仅仅是消息。`todos` 数组只是一个例子。你可以使用相同的方法处理： * **进度指标**：`stream.values.progress` 包含数字完成度数据 * **生成的产物**：`stream.values.document` 包含智能体正在构建的结构化文档 * **决策日志**：`stream.values.decisions` 追踪智能体做出的每个选择 * **资源列表**：`stream.values.sources` 包含智能体找到的链接和参考资料 ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} // 你的智能体定义的任何自定义状态键都是可访问的 const document = stream.values?.document; const sources = stream.values?.sources ?? []; const confidence = stream.values?.confidence_score; ``` 自定义状态键在你的 LangGraph 图的状态模式中定义。`useStream` 钩子会自动将它们包含在 `stream.values` 中，无需任何额外的客户端配置。 ## 动画过渡 待办事项状态过渡实时发生，平滑的动画使这些变化感觉更精致，而不是突兀： ```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} function TodoItem({ todo }: { todo: Todo }) { return (
  • {getStatusIcon(todo.status)} {todo.content}
    • ); } ``` `transition-all duration-300` 类确保颜色变化、删除线和透明度偏移都能平滑地动画过渡。 ## 使用场景 待办事项列表模式适用于智能体执行结构化计划的任何场景： * **项目规划**：智能体将项目分解为任务并按顺序处理 * **研究工作流**：每个研究问题成为一个待办事项，智能体调查并完成它 * **数据处理**：像数据摄取、验证、转换和导出这样的步骤各自成为一个待办事项 * **入职流程**：智能体逐步完成设置步骤，在配置服务时勾选每一项 * **报告生成**：报告的各个部分成为待办事项：收集数据、分析趋势、撰写摘要、格式化输出 ## 处理空状态和加载状态 处理智能体创建计划之前的初始状态： ```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} function TodoList({ todos, isLoading }: { todos: Todo[]; isLoading: boolean }) { if (todos.length === 0 && !isLoading) { return null; } if (todos.length === 0 && isLoading) { return (
    ⟳ 智能体正在创建计划...
    ); } return (
    {/* ... 完整的待办事项列表渲染 */}
    ); } ``` ## 最佳实践 * **突出显示待办事项列表**。对于基于计划的智能体，它是主要的进度指示器。不要将其埋没在页面下方。 * **为状态过渡添加动画**。平滑的过渡使智能体感觉更响应。在背景颜色、文本装饰和透明度上使用 CSS 过渡。 * **只高亮一个 `in_progress` 项目**。智能体通常一次处理一个任务。如果多个项目显示为 `in_progress`，用户界面会变得嘈杂。考虑只让第一个项目有脉冲效果。 * **折叠或淡化已完成项目**。随着列表增长，已完成项目变得不那么相关。降低它们的视觉权重，使用户专注于仍在进行的事情。 * **显示进度百分比**。像“完成 67%”这样的单个数字即使从远处看也能立即理解。 * **保持待办事项列表同步**。由于 `stream.values` 是响应式更新的，待办事项列表会自动保持最新。不要添加手动轮询或刷新逻辑。 ***
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/i18n\zh-CN\oss\deepagents\frontend\todo-list.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose). [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.