This commit is contained in:
许海洋 committed 2026-05-20 17:43:50 +08:00
commit e2d61f4cfb
476 files changed
+103681 -9379

No files matched your search

@@ -0,0 +1,300 @@
"""AI 写作会话定期清理。
按 ``config.yaml`` 的 ``ai_writing.cleanup`` 段做联动清理:
1. 找出 MySQL ``ai_writing_sessions`` 表里 ``updated_at < now - retention_days``
的会话 id 列表(分批,避免大事务)
2. 对每个 id 调用 LangGraph checkpointer 的 ``adelete_thread()``,删掉
SQLite checkpointer 里对应的 thread 状态
3. 再把 MySQL 行批量删掉
整个流程「先删 checkpointer 再删 DB」是有意为之 —— 即便清理被中途中断,
也只会出现「checkpointer 删了但 DB 没删」的孤儿,下一轮清理会发现这些
DB 行仍然过期,重新尝试清理(checkpointer 删一个不存在的 thread 是 idempotent)。
反过来如果先删 DB,万一 checkpointer 删失败,文件里就永久留着不可达的状态。
多 worker 下用文件锁做 leader election,只有抢到锁的 worker 才会真正跑清理。
"""
from __future__ import annotations
import asyncio
import logging
import sys
from datetime import UTC, datetime, timedelta
from pathlib import Path
from croniter import croniter
logger = logging.getLogger(__name__)
# ── 文件锁 ────────────────────────────────────────────────────────────────────
def _acquire_lock(lock_path: Path):
"""跨平台非阻塞独占文件锁,多 worker 下做 leader election。
成功 → 返回持有锁的文件句柄(调用方需保持其存活直到主动释放);
抢不到 / 打开失败 → 返回 None。进程退出时 OS 自动释放。
"""
try:
lock_path.parent.mkdir(parents=True, exist_ok=True)
handle = open(lock_path, "a+")
except OSError:
logger.exception("ai_writing_cleanup: 打开锁文件失败 path=%s", lock_path)
return None
try:
if sys.platform == "win32":
import msvcrt
handle.seek(0)
msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
else:
import fcntl
fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
except OSError:
handle.close()
return None
return handle
def _release_lock(handle) -> None:
try:
if sys.platform == "win32":
import msvcrt
handle.seek(0)
msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
else:
import fcntl
fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
except OSError:
pass
finally:
try:
handle.close()
except OSError:
pass
# ── 清理执行 ──────────────────────────────────────────────────────────────────
async def _delete_checkpoint_thread(checkpointer, thread_id: str) -> None:
"""删 checkpointer 里 thread_id 对应的全部状态。失败只记日志,不抛。"""
if checkpointer is None:
return
# LangGraph 异步删法首选 adelete_thread;老版本只有同步 delete_thread。
delete_async = getattr(checkpointer, "adelete_thread", None)
if delete_async is not None:
try:
await delete_async(thread_id)
return
except Exception:
logger.warning(
"ai_writing_cleanup: adelete_thread failed thread_id=%s", thread_id, exc_info=True
)
return
delete_sync = getattr(checkpointer, "delete_thread", None)
if delete_sync is not None:
try:
# 同步方法跑在线程池里,避免堵 event loop
await asyncio.to_thread(delete_sync, thread_id)
except Exception:
logger.warning(
"ai_writing_cleanup: delete_thread failed thread_id=%s", thread_id, exc_info=True
)
def _get_active_session_ids() -> set[str]:
"""返回内存里**当前正在跑**的 session_id 集合。
这些会话的写作流程还活着 —— 任何清理都不能动它们,否则用户「正在写」
的稿子会被秒删,体验灾难。延迟到下一轮清理(24 小时后)再处理也比误
删强。
"""
try:
# 延迟 import 避免循环依赖:cleanup 模块在 lifespan 启动时被 import,
# routers/ai_writing 也被 include_router 主动 import,两者拓扑无环但
# 还是放函数里更稳。
from app.gateway.routers.ai_writing import _event_queues
return set(_event_queues.keys())
except Exception:
# 兜底:拿不到就当作没有活动会话(最差就是清掉一个刚跑完的会话,
# 比误删正在写的要好得多 —— 用户至少能从 DB 历史里看到结果)
logger.warning("ai_writing_cleanup: 读取活动会话列表失败", exc_info=True)
return set()
async def run_cleanup_once(
*,
retention_days: int,
only_finished: bool = False,
batch_size: int = 500,
) -> dict:
"""执行一轮清理。返回统计信息。
**安全保证**:清理永远跳过内存里仍在跑的会话(``_event_queues`` 里有
对应 key 的)—— 这条规则即使在 admin 手动触发清理时也强制生效,防止
把用户「正在写」的稿子误删。
幂等 + 可重入 —— 多次调用对结果只会越扫越干净。即便清理途中被中断,下次
再跑会重新把 DB 里仍然过期的行扫到(checkpointer 删一个已不存在的 thread
是 no-op)。
"""
from deerflow.agents.ai_writing.graph import get_ai_writing_checkpointer
from deerflow.persistence.ai_writing_sessions import AIWritingSessionRepository
from deerflow.persistence.engine import get_session_factory
sf = get_session_factory()
if sf is None:
logger.info("ai_writing_cleanup: persistence backend=memory,跳过清理")
return {"deleted_db": 0, "deleted_checkpoints": 0, "skipped_active": 0}
repo = AIWritingSessionRepository(sf)
checkpointer = get_ai_writing_checkpointer()
active_ids = _get_active_session_ids()
cutoff = datetime.now(UTC) - timedelta(days=retention_days)
logger.info(
"ai_writing_cleanup: 开始清理 cutoff=%s only_finished=%s batch_size=%d active=%d",
cutoff.isoformat(),
only_finished,
batch_size,
len(active_ids),
)
total_db = 0
total_cp = 0
total_skipped = 0
while True:
ids = await repo.list_older_than(cutoff, only_finished=only_finished, limit=batch_size)
if not ids:
break
# 关键保护:跳过任何仍在内存里跑的会话
ids_to_delete = [sid for sid in ids if sid not in active_ids]
skipped = len(ids) - len(ids_to_delete)
if skipped:
logger.warning(
"ai_writing_cleanup: 跳过 %d 个仍在跑的会话: %s",
skipped,
[sid for sid in ids if sid in active_ids],
)
total_skipped += skipped
if not ids_to_delete:
# 本批全是活动会话 —— 但 list_older_than 是按 updated_at 升序的,
# 下一批拿出来的更旧,所以这种情况只可能整个 cutoff 区间都被活动
# 会话占满,不用继续往下扫,break
break
# 先删 checkpointer,再删 DB —— 保证「DB 删了 → checkpointer 一定也清干净」
for sid in ids_to_delete:
await _delete_checkpoint_thread(checkpointer, sid)
total_cp += 1
deleted = await repo.delete_by_ids(ids_to_delete)
total_db += deleted
logger.info(
"ai_writing_cleanup: 本批删 %d 行(DB),%d 个 thread(checkpointer),跳过 %d",
deleted,
len(ids_to_delete),
skipped,
)
# 整批比 batch_size 小 → 没有更多了
if len(ids) < batch_size:
break
logger.info(
"ai_writing_cleanup: 清理完成 total_db=%d total_checkpoints=%d skipped_active=%d",
total_db,
total_cp,
total_skipped,
)
return {
"deleted_db": total_db,
"deleted_checkpoints": total_cp,
"skipped_active": total_skipped,
}
# ── 调度循环 ──────────────────────────────────────────────────────────────────
def _next_cron_delay_seconds(cron_expr: str, base: datetime | None = None) -> float:
"""根据 cron 表达式算到下一次触发的秒数。
用 ``datetime.now(UTC)`` 做基准。croniter 接受 naive 时间,这里转成 naive
UTC 喂进去;当然如果用户希望按本地时区跑(凌晨 3 点),需要在外层调整 ——
我们用本地时区基准,等价于 cron 在本地时区跑。
"""
base = base or datetime.now()
nxt = croniter(cron_expr, base).get_next(datetime)
return max(1.0, (nxt - base).total_seconds())
async def cleanup_scheduler_loop() -> None:
"""常驻后台任务:按 cron 调度跑清理。
多 worker 部署下文件锁做 leader election,没拿到锁的 worker 直接退出。
被 cancel 时 CancelledError 不会被 except Exception 吞掉,能干净退出。
"""
from deerflow.config.app_config import get_app_config
from deerflow.config.runtime_paths import runtime_home
try:
cfg = get_app_config()
except Exception:
logger.exception("ai_writing_cleanup: 加载 app config 失败,调度器退出")
return
raw = getattr(cfg, "ai_writing", None) or {}
cleanup_cfg = (raw.get("cleanup") if isinstance(raw, dict) else None) or {}
if not cleanup_cfg.get("enabled", False):
logger.info("ai_writing_cleanup: cleanup.enabled=false,调度器不启动")
return
cron_expr = str(cleanup_cfg.get("cron", "0 3 * * *"))
retention_days = int(cleanup_cfg.get("retention_days", 7))
only_finished = bool(cleanup_cfg.get("delete_only_finished", False))
batch_size = int(cleanup_cfg.get("batch_size", 500))
# 提前校验 cron 表达式,配错就早 fail 早暴露
try:
croniter(cron_expr, datetime.now())
except Exception:
logger.exception("ai_writing_cleanup: 非法 cron 表达式 %r,调度器退出", cron_expr)
return
lock_handle = _acquire_lock(runtime_home() / ".ai_writing_cleanup.lock")
if lock_handle is None:
logger.info("ai_writing_cleanup: 另一个 worker 已持有调度锁,本 worker 跳过")
return
logger.info(
"ai_writing_cleanup: 已启动 cron=%r retention_days=%d only_finished=%s batch_size=%d",
cron_expr,
retention_days,
only_finished,
batch_size,
)
try:
while True:
delay = _next_cron_delay_seconds(cron_expr)
logger.info("ai_writing_cleanup: 下一次清理 %.0f 秒后", delay)
await asyncio.sleep(delay)
try:
await run_cleanup_once(
retention_days=retention_days,
only_finished=only_finished,
batch_size=batch_size,
)
except Exception:
logger.exception("ai_writing_cleanup: 本轮清理失败(不影响下一轮)")
finally:
_release_lock(lock_handle)
@@ -22,6 +22,8 @@ from app.gateway.config import get_gateway_config
from app.gateway.csrf_middleware import CSRFMiddleware
from app.gateway.deps import langgraph_runtime
from app.gateway.routers import (
ai_writing,
admin_users,
agents,
artifacts,
assistants_compat,
@@ -33,6 +35,7 @@ from app.gateway.routers import (
memory,
models,
notifications,
public_scheduled_tasks,
recommended_questions,
runs,
scheduled_tasks,
@@ -41,8 +44,11 @@ from app.gateway.routers import (
system_settings,
tags,
thread_runs,
tool_metrics,
thread_shares,
threads,
uploads,
writing,
)
from deerflow.config import app_config as deerflow_app_config
from deerflow.config.app_config import apply_logging_level
@@ -65,6 +71,12 @@ logger = logging.getLogger(__name__)
# firing signals into a worker that is stuck waiting for shutdown cleanup.
_SHUTDOWN_HOOK_TIMEOUT_SECONDS = 5.0
# AI 写作 in-flight task 收尾的最大等待时间。一个 graph 片段通常在几秒内
# 跑到下一个 interrupt 或结束,但单段草稿生成走完整个 LLM 可能耗时较久,
# 给 30 秒兜底;超时则 cancel 强制结束,已落盘的 checkpoint 仍可用于重启
# 后恢复,丢的只是最后一段 in-flight 但未 checkpoint 的进度。
_AI_WRITING_DRAIN_TIMEOUT_SECONDS = 30.0
async def _ensure_admin_user(app: FastAPI) -> None:
"""Startup hook: handle first boot and migrate orphan threads otherwise.
@@ -253,7 +265,7 @@ async def _run_db_migrations() -> None:
logger.info("Persistence backend=memory — skipping Alembic migrations")
return
db_url = str(engine.url)
db_url = engine.url.render_as_string(hide_password=False).replace("%", "%%")
migrations_dir = str(Path(_persistence_pkg.__file__).parent / "migrations")
def _run_sync() -> None:
@@ -356,10 +368,68 @@ async def _curator_scheduler_loop() -> None:
_release_singleton_lock(lock_handle)
def _warn_if_multi_worker() -> None:
"""检测 uvicorn / gunicorn 多 worker 部署并打 ERROR 日志。
AI 写作 + 主 agent 流式响应都依赖**进程内**的内存状态字典
(``_event_queues``、``_session_pending_pause`` 等)。多 worker 下,
用户的 /start /stream /resume 会被 OS 随机分配到不同 worker,
per-worker 的内存字典互相看不见 → SSE 事件丢失、会话「凭空消失」、
resume 走不通。
所以这里在 startup 打 ERROR 强提醒。**不抛异常 fail-fast** —— 万一
运维确实知道自己在干嘛(比如配了 sticky session),不应该阻止启动。
"""
# uvicorn / gunicorn 都不会主动暴露 worker 数到代码层。可以从环境变量
# 或者通过观察 sibling 进程数粗略判断。优先用 WEB_CONCURRENCY(gunicorn
# / uvicorn 都认)。
web_concurrency = os.environ.get("WEB_CONCURRENCY", "").strip()
if web_concurrency and web_concurrency.isdigit() and int(web_concurrency) > 1:
logger.error(
"⚠ 检测到 WEB_CONCURRENCY=%s(多 worker 部署)。AI 写作 / 主 agent "
"流式响应依赖进程内内存状态,多 worker 下会出现「会话丢失 / "
"SSE 断流 / resume 400」等问题。强烈建议改为 WEB_CONCURRENCY=1 "
"或在反向代理上启用 sticky session。详见 AIWritingPage.tsx 的注释。",
web_concurrency,
)
return
# 兜底:扫 /proc 里同名 uvicorn 进程数(只在 Linux 容器里能用)
if not sys.platform.startswith("linux"):
return
try:
from pathlib import Path
peers = 0
for entry in Path("/proc").iterdir():
if not entry.name.isdigit():
continue
try:
cmdline = (entry / "cmdline").read_bytes().replace(b"\x00", b" ").decode("utf-8", "ignore")
except OSError:
continue
if "uvicorn" in cmdline and "app.gateway.app" in cmdline:
peers += 1
if peers > 1:
logger.error(
"⚠ 检测到 %d 个同名 uvicorn 进程。多 worker 部署会导致 AI 写作 "
"「会话丢失 / SSE 断流」等问题,请改为单 worker 或在反向代理上 "
"启用 sticky session。",
peers,
)
except Exception:
# 检测本身失败不算事 —— 这只是个提醒
pass
@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
"""Application lifespan handler."""
# 早一点检测多 worker 部署 —— 这是 AI 写作 / 主 agent 流式响应的常见
# 配置陷阱,每个 worker 启动时都会打一条 ERROR 强提醒运维
_warn_if_multi_worker()
# Load config and check necessary environment variables at startup
try:
app.state.config = get_app_config()
@@ -397,6 +467,17 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
except Exception:
logger.exception("Skill curator scheduler failed to start (non-fatal)")
# 启动 AI 写作会话定期清理:按 config.yaml 的 ai_writing.cleanup 段调度,
# 默认每天凌晨 3 点扫一次,删 retention_days(默认 7 天)以前的会话,联动
# 清理 MySQL 业务表 + SQLite checkpointer 里的 thread 状态。多 worker
# 下用文件锁选 leader,只有抢到锁的 worker 真正跑清理。
try:
from app.gateway.ai_writing_cleanup import cleanup_scheduler_loop
app.state.ai_writing_cleanup_task = asyncio.create_task(cleanup_scheduler_loop())
except Exception:
logger.exception("AI writing cleanup scheduler failed to start (non-fatal)")
# Start IM channel service if any channels are configured
try:
from app.channels.service import start_channel_service
@@ -434,6 +515,44 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
except Exception:
logger.exception("Curator scheduler shutdown error")
# 停止 AI 写作清理调度器
cleanup_task = getattr(app.state, "ai_writing_cleanup_task", None)
if cleanup_task is not None:
cleanup_task.cancel()
try:
await cleanup_task
except asyncio.CancelledError:
pass
except Exception:
logger.exception("AI writing cleanup scheduler shutdown error")
# 等待所有 in-flight 写作 graph task 跑到下一个 interrupt / 结束。
# 这是「写作流程能完整继续」的关键 —— 如果直接关 checkpointer
# connection,正在跑 astream 的 task 会在写 checkpoint 时抛错,
# 已经生成但还没落盘的进度全丢。
try:
from app.gateway.routers.ai_writing import wait_for_inflight_graph_tasks
await wait_for_inflight_graph_tasks(timeout=_AI_WRITING_DRAIN_TIMEOUT_SECONDS)
except Exception:
logger.exception("Wait for in-flight AI writing tasks failed (non-fatal)")
# 关闭 AI 写作 graph 持有的 checkpointer 连接(aiosqlite Connection / pg pool)
try:
from deerflow.agents.ai_writing.graph import shutdown_ai_writing_graph
await asyncio.wait_for(
shutdown_ai_writing_graph(),
timeout=_SHUTDOWN_HOOK_TIMEOUT_SECONDS,
)
except TimeoutError:
logger.warning(
"AI writing checkpointer shutdown exceeded %.1fs; proceeding with worker exit.",
_SHUTDOWN_HOOK_TIMEOUT_SECONDS,
)
except Exception:
logger.exception("Failed to shutdown AI writing checkpointer")
try:
scheduler_service = getattr(app.state, "scheduled_task_service", None)
if scheduler_service is not None:
@@ -671,15 +790,32 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
# Suggestions API is mounted at /api/threads/{thread_id}/suggestions
app.include_router(suggestions.router)
# Writing rewrite API is mounted at /api/writing
app.include_router(writing.router)
# AI Writing multi-agent API is mounted at /api/ai-writing
app.include_router(ai_writing.router)
# Scheduled task API is mounted at /api/scheduled-tasks
app.include_router(scheduled_tasks.router)
# Public, unauthenticated read-only scheduled task API
# (/api/public/scheduled-tasks/*). Lets external systems query tasks and
# surface results without a DeerFlow login.
app.include_router(public_scheduled_tasks.router)
# System settings API is mounted at /api/system-settings
app.include_router(system_settings.router)
# Admin LLM metrics audit + export
app.include_router(llm_metrics.router)
# Admin window into other users' threads / messages / memory
app.include_router(admin_users.router)
# Admin tool / skill call metrics audit + export
app.include_router(tool_metrics.router)
# Channels API is mounted at /api/channels
app.include_router(channels.router)
@@ -701,6 +837,10 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
# Thread Runs API (LangGraph Platform-compatible runs lifecycle)
app.include_router(thread_runs.router)
app.include_router(thread_shares.router)
# Public, unauthenticated read-only share snapshots (/api/public/shares/*).
app.include_router(thread_shares.public_router)
# Stateless Runs API (stream/wait without a pre-existing thread)
app.include_router(runs.router)
@@ -23,11 +23,16 @@ from app.gateway.internal_auth import INTERNAL_AUTH_HEADER_NAME, get_internal_us
from deerflow.runtime.user_context import reset_current_user, set_current_user
# Paths that never require authentication.
#
# ``/api/public/`` is a namespace reserved for intentionally world-readable,
# read-only endpoints (e.g. public conversation share snapshots). Only mount
# safe read-only routes under it — everything there bypasses auth entirely.
_PUBLIC_PATH_PREFIXES: tuple[str, ...] = (
"/health",
"/docs",
"/redoc",
"/openapi.json",
"/api/public/",
)
# Exact auth paths that are public (login/register/status check).
@@ -97,6 +97,10 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
app.state.llm_metrics_store = make_llm_metrics_store(sf)
from deerflow.persistence.tool_metrics import make_tool_metrics_store
app.state.tool_metrics_store = make_tool_metrics_store(sf)
from deerflow.persistence.agents import make_agent_store
app.state.agent_store = make_agent_store(sf)
@@ -122,6 +126,18 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
app.state.tag_store = make_tag_store(sf)
from deerflow.persistence.thread_shares import make_thread_share_store
app.state.thread_share_store = make_thread_share_store(sf)
from deerflow.persistence.ai_writing_sessions import make_ai_writing_session_store
app.state.ai_writing_session_store = make_ai_writing_session_store(sf)
from deerflow.persistence.article_types import make_article_type_store
app.state.article_type_store = make_article_type_store(sf)
# Run event store (has its own factory with config-driven backend selection)
run_events_config = getattr(config, "run_events", None)
app.state.run_event_store = make_run_event_store(run_events_config)
@@ -190,6 +206,11 @@ def get_llm_metrics_store(request: Request):
return getattr(request.app.state, "llm_metrics_store", None)
def get_tool_metrics_store(request: Request):
"""Return the tool-call metrics store, or None when not configured."""
return getattr(request.app.state, "tool_metrics_store", None)
def get_agent_store(request: Request) -> AgentStore:
"""Return the custom-agent store."""
val = getattr(request.app.state, "agent_store", None)
@@ -222,6 +243,24 @@ def get_tag_store(request: Request) -> TagStore:
return val
def get_thread_share_store(request: Request):
"""Return the conversation share-link store."""
val = getattr(request.app.state, "thread_share_store", None)
if val is None:
raise HTTPException(status_code=503, detail="Thread share store not available")
return val
def get_ai_writing_session_store(request: Request):
"""Return the AI writing session store, or None when not configured."""
return getattr(request.app.state, "ai_writing_session_store", None)
def get_article_type_store(request: Request):
"""Return the article type store, or None when not configured."""
return getattr(request.app.state, "article_type_store", None)
def get_run_context(request: Request) -> RunContext:
"""Build a :class:`RunContext` from ``app.state`` singletons.
@@ -1,3 +1,3 @@
from . import artifacts, assistants_compat, mcp, models, recommended_questions, skills, suggestions, thread_runs, threads, uploads
from . import ai_writing, artifacts, assistants_compat, mcp, models, recommended_questions, skills, suggestions, thread_runs, threads, uploads, writing
__all__ = ["artifacts", "assistants_compat", "mcp", "models", "recommended_questions", "skills", "suggestions", "threads", "thread_runs", "uploads"]
__all__ = ["ai_writing", "artifacts", "assistants_compat", "mcp", "models", "recommended_questions", "skills", "suggestions", "threads", "thread_runs", "uploads", "writing"]
@@ -0,0 +1,178 @@
"""Admin-only window into another user's activity.
Lets an administrator inspect any user's conversation history (threads + the
Q&A messages inside them) and their accumulated memory (global + per-agent
buckets). All endpoints require ``system_role == "admin"``; they are strictly
read-only.
The underlying stores normally auto-scope every query to the *calling* user
via a contextvar. These endpoints pass an explicit ``user_id`` so the admin
reads the *target* user's data instead — which is exactly what those store
methods' ``user_id`` parameter is designed for.
"""
from __future__ import annotations
import logging
from fastapi import APIRouter, HTTPException, Query, Request
from pydantic import BaseModel, Field
from app.gateway.deps import (
get_checkpointer,
get_current_user_from_request,
get_thread_store,
)
from deerflow.agents.memory import BuiltinFileProvider
from deerflow.config.agents_config import AGENT_NAME_PATTERN
from deerflow.config.paths import get_paths
from deerflow.runtime import serialize_channel_values
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/api/admin/users", tags=["admin-users"])
async def _require_admin(request: Request) -> None:
"""Reject non-admin callers. In no-auth mode there is no user → allow."""
try:
user = await get_current_user_from_request(request)
except HTTPException:
raise
if user is None:
return
if getattr(user, "system_role", None) != "admin":
raise HTTPException(status_code=403, detail="Admin only")
# ── Threads ────────────────────────────────────────────────────────────────
class AdminThreadItem(BaseModel):
thread_id: str
display_name: str = ""
status: str = "idle"
created_at: str = ""
updated_at: str = ""
@router.get("/{user_id}/threads", response_model=list[AdminThreadItem])
async def list_user_threads(
user_id: str,
request: Request,
limit: int = Query(default=100, ge=1, le=500),
offset: int = Query(default=0, ge=0),
) -> list[AdminThreadItem]:
"""List one user's conversation threads, newest first."""
await _require_admin(request)
repo = get_thread_store(request)
rows = await repo.search(limit=limit, offset=offset, user_id=user_id)
return [
AdminThreadItem(
thread_id=r["thread_id"],
display_name=r.get("display_name") or "",
status=r.get("status", "idle"),
created_at=str(r.get("created_at") or ""),
updated_at=str(r.get("updated_at") or ""),
)
for r in rows
]
@router.get("/{user_id}/threads/{thread_id}/messages", response_model=list[dict])
async def list_user_thread_messages(
user_id: str,
thread_id: str,
request: Request,
limit: int = Query(default=400, ge=1, le=1000),
) -> list[dict]:
"""Return the conversation messages of one of the user's threads.
Read straight from the LangGraph checkpoint — the same source the chat UI
renders — rather than the optional ``run_events`` audit log, which may be
unconfigured (``run_events.backend=memory``) or empty for older threads.
"""
await _require_admin(request)
repo = get_thread_store(request)
# ``user_id=None`` bypasses the owner filter so the admin can fetch any row;
# we then assert the thread really belongs to the target user.
thread = await repo.get(thread_id, user_id=None)
if thread is None:
raise HTTPException(status_code=404, detail="Thread not found")
owner = thread.get("user_id")
if owner is not None and owner != user_id:
raise HTTPException(status_code=404, detail="Thread does not belong to this user")
checkpointer = get_checkpointer(request)
config = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
try:
checkpoint_tuple = await checkpointer.aget_tuple(config)
except Exception as exc: # noqa: BLE001 - surface a clean error
logger.error("Failed to read checkpoint for thread %s: %s", thread_id, exc, exc_info=True)
raise HTTPException(status_code=500, detail="Failed to read thread state") from exc
if checkpoint_tuple is None:
return []
checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {}
channel_values = checkpoint.get("channel_values", {}) if isinstance(checkpoint, dict) else {}
values = serialize_channel_values(channel_values)
messages = values.get("messages", [])
if not isinstance(messages, list):
return []
# Keep the most recent ``limit`` messages — long threads stay bounded.
return messages[-limit:]
# ── Memory ─────────────────────────────────────────────────────────────────
class AdminMemoryBucket(BaseModel):
name: str = Field(..., description="Bucket name: 'global' or a custom-agent name")
data: dict = Field(default_factory=dict, description="Raw memory data for the bucket")
class AdminMemoryResponse(BaseModel):
user_id: str
buckets: list[AdminMemoryBucket] = Field(default_factory=list)
def _read_memory_bucket(user_id: str, agent_id: str | None) -> dict:
"""Read one Memory V2 file into a JSON-able ``{"entries": [...]}`` dict.
``agent_id is None`` -> the user's ``USER.md`` (profile, cross-agent);
otherwise that agent's ``MEMORY.md`` (per-agent working notes).
"""
provider = BuiltinFileProvider()
provider.initialize(user_id=user_id, agent_id=agent_id)
target = "user" if agent_id is None else "memory"
return {"entries": provider.read(target)}
@router.get("/{user_id}/memory", response_model=AdminMemoryResponse)
async def get_user_memory(user_id: str, request: Request) -> AdminMemoryResponse:
"""Return every memory bucket for one user.
Memory V2 layout: the ``global`` bucket is ``USER.md`` (user profile);
each per-agent bucket is that agent's ``MEMORY.md`` working notes.
"""
await _require_admin(request)
buckets: list[AdminMemoryBucket] = [
AdminMemoryBucket(name="global", data=_read_memory_bucket(user_id, None))
]
agents_root = get_paths().user_dir(user_id) / "agents"
if agents_root.is_dir():
for entry in sorted(agents_root.iterdir(), key=lambda p: p.name.lower()):
if not entry.is_dir() or not (entry / "MEMORY.md").exists():
continue
if not AGENT_NAME_PATTERN.match(entry.name):
continue
try:
data = _read_memory_bucket(user_id, entry.name)
except Exception:
logger.warning("Failed to read memory bucket %s for user", entry.name)
continue
buckets.append(AdminMemoryBucket(name=entry.name, data=data))
return AdminMemoryResponse(user_id=user_id, buckets=buckets)
@@ -244,7 +244,7 @@ async def _get_editable_or_raise(
async def list_agents(
request: Request,
search: str | None = Query(default=None, description="Case-insensitive fuzzy match on agent name"),
tag_id: str | None = Query(default=None, description="Keep only agents carrying this tag"),
tag_ids: list[str] | None = Query(default=None, description="Keep agents carrying any of these tags (OR)"),
) -> AgentsListResponse:
_require_agents_api_enabled()
@@ -262,8 +262,9 @@ async def list_agents(
if search:
needle = search.strip().lower()
responses = [r for r in responses if needle in r.name.lower()]
if tag_id:
responses = [r for r in responses if any(t.get("id") == tag_id for t in r.tags)]
if tag_ids:
wanted = set(tag_ids)
responses = [r for r in responses if any(t.get("id") in wanted for t in r.tags)]
return AgentsListResponse(agents=responses)
except HTTPException:
raise
File diff suppressed because it is too large. Load diff
@@ -1,531 +1,385 @@
"""Memory API router for retrieving and managing memory data.
All endpoints accept an optional ``agent`` query parameter:
- omitted / empty / ``"global"`` -> operate on the per-user **global**
memory file (``users/{uid}/memory.json``).
- valid agent name -> operate on the **per-agent** memory file
(``users/{uid}/agents/{agent}/memory.json``).
Without this parameter the API used to be silently global-only, so any
memory written while chatting inside a custom agent (which is saved
per-agent) was invisible from the settings page. See ``GET /api/memory/agents``
for discovering which agent-scoped buckets the current user owns.
"""
import re
from fastapi import APIRouter, HTTPException, Query
from pydantic import BaseModel, Field
from deerflow.agents.memory.updater import (
clear_memory_data,
create_memory_fact,
delete_memory_fact,
get_memory_data,
import_memory_data,
reload_memory_data,
update_memory_fact,
)
from deerflow.config.agents_config import AGENT_NAME_PATTERN
from deerflow.config.memory_config import get_memory_config
from deerflow.config.paths import get_paths
from deerflow.runtime.user_context import get_effective_user_id
router = APIRouter(prefix="/api", tags=["memory"])
# Sentinel values that mean "the per-user global memory file" (no agent).
# We accept several spellings so the frontend can model the dropdown choice
# either by omitting the param or by sending an explicit "global"/"".
_GLOBAL_AGENT_VALUES: frozenset[str] = frozenset({"", "global", "__global__"})
def _resolve_agent_name(agent: str | None) -> str | None:
"""Validate the ``agent`` query parameter and normalize the global sentinel.
Returns ``None`` for the global memory bucket, or the lowercased agent
name otherwise. Raises 400 if the supplied name fails the agent-name
pattern (mirrors :func:`FileMemoryStorage._validate_agent_name`, but
surfaces a clean HTTP error instead of letting the storage layer raise
``ValueError`` via a 500).
"""
if agent is None:
return None
stripped = agent.strip()
if stripped.lower() in _GLOBAL_AGENT_VALUES:
return None
if not AGENT_NAME_PATTERN.match(stripped):
raise HTTPException(
status_code=400,
detail=f"Invalid agent name {stripped!r}: must match {AGENT_NAME_PATTERN.pattern}",
)
return stripped.lower()
_AgentQuery = Query(
None,
description=(
"Optional agent name. Omit (or pass 'global') to address the per-user "
"global memory bucket; pass a custom-agent name to address that "
"agent's per-user memory bucket."
),
examples=["my-agent"],
pattern=r"^[A-Za-z0-9-]+$|^global$|^$",
)
class ContextSection(BaseModel):
"""Model for context sections (user and history)."""
summary: str = Field(default="", description="Summary content")
updatedAt: str = Field(default="", description="Last update timestamp")
class UserContext(BaseModel):
"""Model for user context."""
workContext: ContextSection = Field(default_factory=ContextSection)
personalContext: ContextSection = Field(default_factory=ContextSection)
topOfMind: ContextSection = Field(default_factory=ContextSection)
class HistoryContext(BaseModel):
"""Model for history context."""
recentMonths: ContextSection = Field(default_factory=ContextSection)
earlierContext: ContextSection = Field(default_factory=ContextSection)
longTermBackground: ContextSection = Field(default_factory=ContextSection)
class Fact(BaseModel):
"""Model for a memory fact."""
id: str = Field(..., description="Unique identifier for the fact")
content: str = Field(..., description="Fact content")
category: str = Field(default="context", description="Fact category")
confidence: float = Field(default=0.5, description="Confidence score (0-1)")
createdAt: str = Field(default="", description="Creation timestamp")
source: str = Field(default="unknown", description="Source thread ID")
sourceError: str | None = Field(default=None, description="Optional description of the prior mistake or wrong approach")
class MemoryResponse(BaseModel):
"""Response model for memory data."""
version: str = Field(default="1.0", description="Memory schema version")
lastUpdated: str = Field(default="", description="Last update timestamp")
user: UserContext = Field(default_factory=UserContext)
history: HistoryContext = Field(default_factory=HistoryContext)
facts: list[Fact] = Field(default_factory=list)
def _map_memory_fact_value_error(exc: ValueError) -> HTTPException:
"""Convert updater validation errors into stable API responses."""
if exc.args and exc.args[0] == "confidence":
detail = "Invalid confidence value; must be between 0 and 1."
else:
detail = "Memory fact content cannot be empty."
return HTTPException(status_code=400, detail=detail)
class FactCreateRequest(BaseModel):
"""Request model for creating a memory fact."""
content: str = Field(..., min_length=1, description="Fact content")
category: str = Field(default="context", description="Fact category")
confidence: float = Field(default=0.5, ge=0.0, le=1.0, description="Confidence score (0-1)")
class FactPatchRequest(BaseModel):
"""PATCH request model that preserves existing values for omitted fields."""
content: str | None = Field(default=None, min_length=1, description="Fact content")
category: str | None = Field(default=None, description="Fact category")
confidence: float | None = Field(default=None, ge=0.0, le=1.0, description="Confidence score (0-1)")
class MemoryConfigResponse(BaseModel):
"""Response model for memory configuration."""
enabled: bool = Field(..., description="Whether memory is enabled")
storage_path: str = Field(..., description="Path to memory storage file")
debounce_seconds: int = Field(..., description="Debounce time for memory updates")
max_facts: int = Field(..., description="Maximum number of facts to store")
fact_confidence_threshold: float = Field(..., description="Minimum confidence threshold for facts")
injection_enabled: bool = Field(..., description="Whether memory injection is enabled")
max_injection_tokens: int = Field(..., description="Maximum tokens for memory injection")
class MemoryStatusResponse(BaseModel):
"""Response model for memory status."""
config: MemoryConfigResponse
data: MemoryResponse
class MemoryAgentInfo(BaseModel):
"""One per-agent memory bucket the current user owns."""
name: str = Field(..., description="Custom agent name (matches AGENT_NAME_PATTERN).")
factCount: int = Field(0, description="Number of facts stored for this agent.")
lastUpdated: str = Field("", description="lastUpdated field of the per-agent memory file, if any.")
class MemoryAgentsResponse(BaseModel):
"""Inventory of memory buckets visible to the current user."""
globalAvailable: bool = Field(..., description="Whether a per-user global memory file exists on disk.")
globalFactCount: int = Field(0, description="Facts in the per-user global memory file.")
globalLastUpdated: str = Field("", description="lastUpdated field of the global memory file, if any.")
agents: list[MemoryAgentInfo] = Field(default_factory=list, description="Sorted by name (case-insensitive).")
@router.get(
"/memory/agents",
response_model=MemoryAgentsResponse,
summary="List Memory Buckets",
description=(
"Enumerate which memory buckets exist for the current user: the "
"per-user global file, plus every per-agent memory file the user "
"has accumulated by chatting inside custom agents. Drives the "
"agent-selector dropdown on the Memory settings page."
),
)
async def list_memory_agents() -> MemoryAgentsResponse:
"""Inspect the on-disk memory layout for the current user.
This intentionally walks the filesystem instead of querying the
custom-agents API: a user can have leftover per-agent memory for an
agent they later renamed/deleted, and we still want them to be able to
open it (or clear it) from the UI.
"""
import json
user_id = get_effective_user_id()
paths = get_paths()
user_dir = paths.user_dir(user_id)
# Global bucket
global_file = paths.user_memory_file(user_id)
global_available = global_file.exists()
global_facts = 0
global_updated = ""
if global_available:
try:
with open(global_file, encoding="utf-8") as f:
data = json.load(f)
global_facts = len(data.get("facts", []) or [])
global_updated = data.get("lastUpdated", "") or ""
except (OSError, json.JSONDecodeError):
# Treat unreadable file as "exists but empty" — better than 500
# since this endpoint is purely informational.
pass
agents: list[MemoryAgentInfo] = []
agents_root = user_dir / "agents"
if agents_root.is_dir():
for entry in sorted(agents_root.iterdir(), key=lambda p: p.name.lower()):
if not entry.is_dir():
continue
mem_file = entry / "memory.json"
if not mem_file.exists():
continue
# Defensive: agent-dir name may have been hand-edited; keep only
# those that round-trip through AGENT_NAME_PATTERN so the UI
# never receives a value it can't echo back to us.
if not AGENT_NAME_PATTERN.match(entry.name):
continue
facts = 0
updated = ""
try:
with open(mem_file, encoding="utf-8") as f:
data = json.load(f)
facts = len(data.get("facts", []) or [])
updated = data.get("lastUpdated", "") or ""
except (OSError, json.JSONDecodeError):
pass
agents.append(MemoryAgentInfo(name=entry.name, factCount=facts, lastUpdated=updated))
return MemoryAgentsResponse(
globalAvailable=global_available,
globalFactCount=global_facts,
globalLastUpdated=global_updated,
agents=agents,
)
@router.get(
"/memory",
response_model=MemoryResponse,
response_model_exclude_none=True,
summary="Get Memory Data",
description=(
"Retrieve the current memory data including user context, history, and facts. "
"Pass ``?agent=<name>`` to read a per-agent bucket; omit it to read the per-user global bucket."
),
)
async def get_memory(agent: str | None = _AgentQuery) -> MemoryResponse:
"""Get the current memory data for the global or per-agent bucket.
Returns:
The current memory data with user context, history, and facts.
Example Response:
```json
{
"version": "1.0",
"lastUpdated": "2024-01-15T10:30:00Z",
"user": {
"workContext": {"summary": "Working on DeerFlow project", "updatedAt": "..."},
"personalContext": {"summary": "Prefers concise responses", "updatedAt": "..."},
"topOfMind": {"summary": "Building memory API", "updatedAt": "..."}
},
"history": {
"recentMonths": {"summary": "Recent development activities", "updatedAt": "..."},
"earlierContext": {"summary": "", "updatedAt": ""},
"longTermBackground": {"summary": "", "updatedAt": ""}
},
"facts": [
{
"id": "fact_abc123",
"content": "User prefers TypeScript over JavaScript",
"category": "preference",
"confidence": 0.9,
"createdAt": "2024-01-15T10:30:00Z",
"source": "thread_xyz"
}
]
}
```
"""
agent_name = _resolve_agent_name(agent)
memory_data = get_memory_data(agent_name, user_id=get_effective_user_id())
return MemoryResponse(**memory_data)
@router.post(
"/memory/reload",
response_model=MemoryResponse,
response_model_exclude_none=True,
summary="Reload Memory Data",
description="Reload memory data from the storage file, refreshing the in-memory cache.",
)
async def reload_memory(agent: str | None = _AgentQuery) -> MemoryResponse:
"""Reload memory data from file.
This forces a reload of the memory data from the storage file,
useful when the file has been modified externally.
Returns:
The reloaded memory data.
"""
agent_name = _resolve_agent_name(agent)
memory_data = reload_memory_data(agent_name, user_id=get_effective_user_id())
return MemoryResponse(**memory_data)
@router.delete(
"/memory",
response_model=MemoryResponse,
response_model_exclude_none=True,
summary="Clear All Memory Data",
description="Delete all saved memory data and reset the memory structure to an empty state.",
)
async def clear_memory(agent: str | None = _AgentQuery) -> MemoryResponse:
"""Clear all persisted memory data for the requested bucket."""
agent_name = _resolve_agent_name(agent)
try:
memory_data = clear_memory_data(agent_name, user_id=get_effective_user_id())
except OSError as exc:
raise HTTPException(status_code=500, detail="Failed to clear memory data.") from exc
return MemoryResponse(**memory_data)
@router.post(
"/memory/facts",
response_model=MemoryResponse,
response_model_exclude_none=True,
summary="Create Memory Fact",
description="Create a single saved memory fact manually.",
)
async def create_memory_fact_endpoint(
request: FactCreateRequest,
agent: str | None = _AgentQuery,
) -> MemoryResponse:
"""Create a single fact manually."""
agent_name = _resolve_agent_name(agent)
try:
memory_data = create_memory_fact(
content=request.content,
category=request.category,
confidence=request.confidence,
agent_name=agent_name,
user_id=get_effective_user_id(),
)
except ValueError as exc:
raise _map_memory_fact_value_error(exc) from exc
except OSError as exc:
raise HTTPException(status_code=500, detail="Failed to create memory fact.") from exc
return MemoryResponse(**memory_data)
@router.delete(
"/memory/facts/{fact_id}",
response_model=MemoryResponse,
response_model_exclude_none=True,
summary="Delete Memory Fact",
description="Delete a single saved memory fact by its fact id.",
)
async def delete_memory_fact_endpoint(
fact_id: str,
agent: str | None = _AgentQuery,
) -> MemoryResponse:
"""Delete a single fact from memory by fact id."""
agent_name = _resolve_agent_name(agent)
try:
memory_data = delete_memory_fact(fact_id, agent_name, user_id=get_effective_user_id())
except KeyError as exc:
raise HTTPException(status_code=404, detail=f"Memory fact '{fact_id}' not found.") from exc
except OSError as exc:
raise HTTPException(status_code=500, detail="Failed to delete memory fact.") from exc
return MemoryResponse(**memory_data)
@router.patch(
"/memory/facts/{fact_id}",
response_model=MemoryResponse,
response_model_exclude_none=True,
summary="Patch Memory Fact",
description="Partially update a single saved memory fact by its fact id while preserving omitted fields.",
)
async def update_memory_fact_endpoint(
fact_id: str,
request: FactPatchRequest,
agent: str | None = _AgentQuery,
) -> MemoryResponse:
"""Partially update a single fact manually."""
agent_name = _resolve_agent_name(agent)
try:
memory_data = update_memory_fact(
fact_id=fact_id,
content=request.content,
category=request.category,
confidence=request.confidence,
agent_name=agent_name,
user_id=get_effective_user_id(),
)
except ValueError as exc:
raise _map_memory_fact_value_error(exc) from exc
except KeyError as exc:
raise HTTPException(status_code=404, detail=f"Memory fact '{fact_id}' not found.") from exc
except OSError as exc:
raise HTTPException(status_code=500, detail="Failed to update memory fact.") from exc
return MemoryResponse(**memory_data)
@router.get(
"/memory/export",
response_model=MemoryResponse,
response_model_exclude_none=True,
summary="Export Memory Data",
description="Export the current global memory data as JSON for backup or transfer.",
)
async def export_memory(agent: str | None = _AgentQuery) -> MemoryResponse:
"""Export the current memory data."""
agent_name = _resolve_agent_name(agent)
memory_data = get_memory_data(agent_name, user_id=get_effective_user_id())
return MemoryResponse(**memory_data)
@router.post(
"/memory/import",
response_model=MemoryResponse,
response_model_exclude_none=True,
summary="Import Memory Data",
description="Import and overwrite the current global memory data from a JSON payload.",
)
async def import_memory(
request: MemoryResponse,
agent: str | None = _AgentQuery,
) -> MemoryResponse:
"""Import and persist memory data."""
agent_name = _resolve_agent_name(agent)
try:
memory_data = import_memory_data(request.model_dump(), agent_name, user_id=get_effective_user_id())
except OSError as exc:
raise HTTPException(status_code=500, detail="Failed to import memory data.") from exc
return MemoryResponse(**memory_data)
@router.get(
"/memory/config",
response_model=MemoryConfigResponse,
summary="Get Memory Configuration",
description="Retrieve the current memory system configuration.",
)
async def get_memory_config_endpoint() -> MemoryConfigResponse:
"""Get the memory system configuration.
Returns:
The current memory configuration settings.
Example Response:
```json
{
"enabled": true,
"storage_path": ".deer-flow/memory.json",
"debounce_seconds": 30,
"max_facts": 100,
"fact_confidence_threshold": 0.7,
"injection_enabled": true,
"max_injection_tokens": 2000
}
```
"""
config = get_memory_config()
return MemoryConfigResponse(
enabled=config.enabled,
storage_path=config.storage_path,
debounce_seconds=config.debounce_seconds,
max_facts=config.max_facts,
fact_confidence_threshold=config.fact_confidence_threshold,
injection_enabled=config.injection_enabled,
max_injection_tokens=config.max_injection_tokens,
)
@router.get(
"/memory/status",
response_model=MemoryStatusResponse,
response_model_exclude_none=True,
summary="Get Memory Status",
description="Retrieve both memory configuration and current data in a single request.",
)
async def get_memory_status(agent: str | None = _AgentQuery) -> MemoryStatusResponse:
"""Get the memory system status including configuration and data.
Returns:
Combined memory configuration and current data.
"""
agent_name = _resolve_agent_name(agent)
config = get_memory_config()
memory_data = get_memory_data(agent_name, user_id=get_effective_user_id())
return MemoryStatusResponse(
config=MemoryConfigResponse(
enabled=config.enabled,
storage_path=config.storage_path,
debounce_seconds=config.debounce_seconds,
max_facts=config.max_facts,
fact_confidence_threshold=config.fact_confidence_threshold,
injection_enabled=config.injection_enabled,
max_injection_tokens=config.max_injection_tokens,
),
data=MemoryResponse(**memory_data),
)
"""Memory V2 记忆 API 路由。
所有端点用 ``/api/memory/v2`` 前缀。Memory V2 重写后,旧的 facts/history
端点 (``/api/memory``、``/memory/facts`` 等) 已移除。
端点:
- ``GET /memory/v2`` 读取 builtin 本地记忆 (USER.md / MEMORY.md)
- ``POST /memory/v2/entries`` 新增一条记忆条目
- ``PUT /memory/v2/entries`` 替换一条记忆条目
- ``DELETE /memory/v2/entries`` 删除一条记忆条目
- ``GET /memory/v2/config`` 读取生效配置 + 用户可改字段白名单
- ``PATCH /memory/v2/config`` 写入 per-user 配置覆盖 (白名单字段)
- ``DELETE /memory/v2/config`` 撤销 per-user 配置覆盖
- ``POST /memory/v2/search`` 代理 Hindsight 检索 (recall / reflect)
可选 ``agent`` 查询参数:省略或传 ``global`` 表示全局桶;传 agent 名表示该
agent 的工作记忆桶。USER.md 始终是 per-user 全局的;MEMORY.md 按 agent 隔离。
"""
from __future__ import annotations
from typing import Any
from fastapi import APIRouter, HTTPException, Query
from pydantic import BaseModel, Field
from deerflow.config.agents_config import AGENT_NAME_PATTERN
from deerflow.config.memory_config import (
USER_WRITABLE_FIELDS,
delete_user_memory_override,
get_effective_memory_config,
save_user_memory_override,
)
from deerflow.config.paths import get_paths
from deerflow.runtime.user_context import get_effective_user_id
router = APIRouter(prefix="/api", tags=["memory"])
# 表示"全局桶 (无 agent)"的 agent 取值。
_GLOBAL_AGENT_VALUES: frozenset[str] = frozenset({"", "global", "__global__"})
def _resolve_agent_name(agent: str | None) -> str | None:
"""校验 ``agent`` 查询参数,把全局哨兵规整为 ``None``。
返回 ``None`` 表示全局桶,否则返回小写的 agent 名。非法名抛 400。
"""
if agent is None:
return None
stripped = agent.strip()
if stripped.lower() in _GLOBAL_AGENT_VALUES:
return None
if not AGENT_NAME_PATTERN.match(stripped):
raise HTTPException(
status_code=400,
detail=f"Invalid agent name {stripped!r}: must match {AGENT_NAME_PATTERN.pattern}",
)
return stripped.lower()
_AgentQuery = Query(
None,
description="可选 agent 名。省略或传 'global' 表示全局桶;传 agent 名表示该 agent 的工作记忆桶。",
examples=["my-agent"],
pattern=r"^[A-Za-z0-9-]+$|^global$|^$",
)
# ===========================================================================
# 响应 / 请求模型
# ===========================================================================
class MemoryV2DataResponse(BaseModel):
"""Memory V2 builtin provider 的数据视图。"""
user_entries: list[str] = Field(default_factory=list, description="USER.md 条目 (用户画像)")
memory_entries: list[str] = Field(default_factory=list, description="MEMORY.md 条目 (agent 工作笔记)")
user_usage: str = Field(default="", description="USER.md 字符用量,如 '12% — 165/1375 字符'")
memory_usage: str = Field(default="", description="MEMORY.md 字符用量")
class MemoryV2ConfigResponse(BaseModel):
"""Memory V2 生效配置 (含三层覆盖合并结果) + 用户可改字段白名单。"""
config: dict[str, Any] = Field(..., description="按 per-user 覆盖合并后的生效配置")
writable_fields: list[str] = Field(..., description="用户可在运行时覆盖的字段 (点号路径)")
class MemoryConfigPatchRequest(BaseModel):
"""Memory V2 配置覆盖请求。
overrides 支持嵌套形式 ``{"injection": {"enabled": false}}`` 或点号扁平形式
``{"injection.enabled": false}``;非白名单字段会被忽略。
"""
overrides: dict[str, Any] = Field(..., description="要写入 per-user 覆盖的字段")
class MemoryEntryCreateRequest(BaseModel):
"""新增一条 V2 记忆条目。"""
target: str = Field(..., description="memory(工作笔记) 或 user(用户画像)")
content: str = Field(..., min_length=1, description="条目内容")
class MemoryEntryReplaceRequest(BaseModel):
"""替换一条 V2 记忆条目。"""
target: str = Field(..., description="memory 或 user")
old_text: str = Field(..., min_length=1, description="短唯一子串,定位要替换的条目")
content: str = Field(..., min_length=1, description="新内容")
class MemorySearchRequest(BaseModel):
"""Hindsight 检索请求。"""
query: str = Field(..., min_length=1, description="检索查询")
mode: str = Field(default="recall", description="recall(返回原始片段) 或 reflect(LLM 综合)")
class MemorySearchResponse(BaseModel):
"""Hindsight 检索结果。"""
available: bool = Field(..., description="Hindsight 是否可用 (未配置/未装包时为 false)")
results: list[str] = Field(default_factory=list, description="recall 模式的检索结果")
text: str = Field(default="", description="reflect 模式的综合结论")
# ===========================================================================
# 辅助函数
# ===========================================================================
def _build_builtin_provider(user_id: str, agent_name: str | None):
"""按生效配置构建并初始化一个 V2 builtin provider。"""
from deerflow.agents.memory.providers.builtin import BuiltinFileProvider
config = get_effective_memory_config(user_id)
provider = BuiltinFileProvider(
memory_char_limit=config.builtin.memory_char_limit,
user_char_limit=config.builtin.user_char_limit,
deduplicate_on_load=config.builtin.deduplicate_on_load,
security=config.security,
)
provider.initialize(
user_id=user_id,
agent_id=agent_name or "default",
base_dir=str(get_paths().base_dir),
)
return provider
def _validate_v2_target(target: str) -> str:
"""校验 V2 entries 的 target,非法时抛 400。"""
if target not in ("memory", "user"):
raise HTTPException(status_code=400, detail=f"非法 target '{target}',只能是 'memory' 或 'user'。")
return target
def _v2_data_response(provider) -> MemoryV2DataResponse:
"""从 builtin provider 读出当前数据,组装成 MemoryV2DataResponse。"""
return MemoryV2DataResponse(
user_entries=provider.read("user"),
memory_entries=provider.read("memory"),
user_usage=provider.usage("user"),
memory_usage=provider.usage("memory"),
)
def _raise_if_write_failed(result: dict) -> None:
"""builtin provider 写操作失败时抛 400。"""
if not result.get("success"):
raise HTTPException(status_code=400, detail=result.get("error", "记忆写入失败。"))
# ===========================================================================
# 数据端点
# ===========================================================================
@router.get(
"/memory/v2",
response_model=MemoryV2DataResponse,
summary="Get Memory V2 Data",
description="读取 Memory V2 builtin provider 的 USER.md / MEMORY.md 条目。",
)
async def get_memory_v2(agent: str | None = _AgentQuery) -> MemoryV2DataResponse:
"""读取当前用户的 Memory V2 本地记忆。"""
agent_name = _resolve_agent_name(agent)
user_id = get_effective_user_id()
try:
provider = _build_builtin_provider(user_id, agent_name)
return _v2_data_response(provider)
except Exception as exc: # noqa: BLE001
raise HTTPException(status_code=500, detail="Failed to read memory V2 data.") from exc
@router.post(
"/memory/v2/entries",
response_model=MemoryV2DataResponse,
summary="Add Memory V2 Entry",
description="手动往 USER.md / MEMORY.md 新增一条记忆条目。",
)
async def add_memory_v2_entry(
request: MemoryEntryCreateRequest,
agent: str | None = _AgentQuery,
) -> MemoryV2DataResponse:
"""手动新增一条 V2 记忆条目。"""
_validate_v2_target(request.target)
user_id = get_effective_user_id()
try:
provider = _build_builtin_provider(user_id, _resolve_agent_name(agent))
result = provider.add(request.target, request.content)
except HTTPException:
raise
except Exception as exc: # noqa: BLE001
raise HTTPException(status_code=500, detail="Failed to add memory entry.") from exc
_raise_if_write_failed(result)
return _v2_data_response(provider)
@router.put(
"/memory/v2/entries",
response_model=MemoryV2DataResponse,
summary="Replace Memory V2 Entry",
description="用 old_text 定位一条记忆条目并替换为新内容。",
)
async def replace_memory_v2_entry(
request: MemoryEntryReplaceRequest,
agent: str | None = _AgentQuery,
) -> MemoryV2DataResponse:
"""手动替换一条 V2 记忆条目。"""
_validate_v2_target(request.target)
user_id = get_effective_user_id()
try:
provider = _build_builtin_provider(user_id, _resolve_agent_name(agent))
result = provider.replace(request.target, request.old_text, request.content)
except HTTPException:
raise
except Exception as exc: # noqa: BLE001
raise HTTPException(status_code=500, detail="Failed to replace memory entry.") from exc
_raise_if_write_failed(result)
return _v2_data_response(provider)
@router.delete(
"/memory/v2/entries",
response_model=MemoryV2DataResponse,
summary="Delete Memory V2 Entry",
description="用 old_text 定位并删除一条记忆条目。",
)
async def delete_memory_v2_entry(
target: str = Query(..., description="memory 或 user"),
old_text: str = Query(..., min_length=1, description="短唯一子串,定位要删除的条目"),
agent: str | None = _AgentQuery,
) -> MemoryV2DataResponse:
"""手动删除一条 V2 记忆条目。"""
_validate_v2_target(target)
user_id = get_effective_user_id()
try:
provider = _build_builtin_provider(user_id, _resolve_agent_name(agent))
result = provider.remove(target, old_text)
except HTTPException:
raise
except Exception as exc: # noqa: BLE001
raise HTTPException(status_code=500, detail="Failed to delete memory entry.") from exc
_raise_if_write_failed(result)
return _v2_data_response(provider)
# ===========================================================================
# 配置端点
# ===========================================================================
@router.get(
"/memory/v2/config",
response_model=MemoryV2ConfigResponse,
summary="Get Memory V2 Effective Config",
description="读取按 per-user 覆盖合并后的生效记忆配置,以及用户可改字段白名单。",
)
async def get_memory_v2_config() -> MemoryV2ConfigResponse:
"""读取当前用户的生效记忆配置。"""
user_id = get_effective_user_id()
config = get_effective_memory_config(user_id)
return MemoryV2ConfigResponse(
config=config.model_dump(),
writable_fields=sorted(USER_WRITABLE_FIELDS),
)
@router.patch(
"/memory/v2/config",
response_model=MemoryV2ConfigResponse,
summary="Patch Memory V2 Config",
description="把白名单字段写入当前用户的 per-user 配置覆盖。非白名单字段被忽略。",
)
async def patch_memory_v2_config(request: MemoryConfigPatchRequest) -> MemoryV2ConfigResponse:
"""更新当前用户的 per-user 记忆配置覆盖。"""
user_id = get_effective_user_id()
try:
save_user_memory_override(user_id, request.overrides)
except OSError as exc:
raise HTTPException(status_code=500, detail="Failed to save memory config override.") from exc
config = get_effective_memory_config(user_id)
return MemoryV2ConfigResponse(
config=config.model_dump(),
writable_fields=sorted(USER_WRITABLE_FIELDS),
)
@router.delete(
"/memory/v2/config",
response_model=MemoryV2ConfigResponse,
summary="Delete Memory V2 Config Override",
description=(
"撤销当前用户的 per-user 配置覆盖。传 ?field=injection.enabled 只撤销该字段;"
"不传 field 则清空整个 per-user 覆盖。"
),
)
async def delete_memory_v2_config(
field: str | None = Query(None, description="要撤销的点号路径字段;省略则清空全部覆盖"),
) -> MemoryV2ConfigResponse:
"""撤销当前用户的 per-user 记忆配置覆盖。"""
user_id = get_effective_user_id()
try:
delete_user_memory_override(user_id, field)
except OSError as exc:
raise HTTPException(status_code=500, detail="Failed to delete memory config override.") from exc
config = get_effective_memory_config(user_id)
return MemoryV2ConfigResponse(
config=config.model_dump(),
writable_fields=sorted(USER_WRITABLE_FIELDS),
)
# ===========================================================================
# Hindsight 检索代理端点
# ===========================================================================
@router.post(
"/memory/v2/search",
response_model=MemorySearchResponse,
summary="Search Hindsight Memory",
description=(
"代理 Hindsight 检索。mode=recall 返回原始记忆片段;mode=reflect 返回 LLM 综合结论。"
"Hindsight 未配置或不可用时返回 available=false。"
),
)
async def search_memory_v2(
request: MemorySearchRequest,
agent: str | None = _AgentQuery,
) -> MemorySearchResponse:
"""代理 Hindsight 检索 (recall / reflect)。"""
user_id = get_effective_user_id()
config = get_effective_memory_config(user_id)
if not config.enabled or config.provider != "hindsight":
return MemorySearchResponse(available=False)
try:
from deerflow.agents.memory.providers.hindsight import HindsightProvider
provider = HindsightProvider(config.hindsight)
if not provider.is_available():
return MemorySearchResponse(available=False)
provider.initialize(
user_id=user_id,
agent_id=_resolve_agent_name(agent) or "default",
thread_id="",
base_dir="",
)
if request.mode == "reflect":
text = provider.reflect(request.query)
return MemorySearchResponse(available=True, text=text)
results = provider.recall(request.query)
return MemorySearchResponse(available=True, results=results)
except HTTPException:
raise
except Exception as exc: # noqa: BLE001
raise HTTPException(status_code=500, detail="Failed to search Hindsight memory.") from exc
@@ -0,0 +1,304 @@
"""Public (unauthenticated) read-only API for scheduled tasks.
Mounted under the ``/api/public/`` prefix so the auth middleware lets these
routes through without a session cookie. Intended for embedding scheduled
task results into external dashboards / documentation / chat systems that
shouldn't need a DeerFlow login.
Surface area:
- ``GET /api/public/scheduled-tasks/`` — list every task (no prompt body)
- ``GET /api/public/scheduled-tasks/{task_id}`` — task metadata
- ``GET /api/public/scheduled-tasks/{task_id}/runs`` — runs for a task (latest first)
- ``GET /api/public/scheduled-tasks/runs/{run_id}`` — single run (result included)
- ``GET /api/public/scheduled-tasks/runs/{run_id}/files/{i}``— inline file content / preview
- ``GET /api/public/scheduled-tasks/runs/{run_id}/download`` — zip / md download of result
These are read-only. No write/mutation routes belong here.
"""
from __future__ import annotations
import logging
import mimetypes
import re
import zipfile
from io import BytesIO
from pathlib import Path
from typing import Any
from urllib.parse import quote
from fastapi import APIRouter, HTTPException, Query
from fastapi.responses import FileResponse, Response, StreamingResponse
from deerflow.runtime.scheduler import get_scheduled_task_service
logger = logging.getLogger(__name__)
# Whitelisted under ``auth_middleware._PUBLIC_PATH_PREFIXES`` (``/api/public/``).
router = APIRouter(prefix="/api/public/scheduled-tasks", tags=["public-scheduled-tasks"])
# ---------------------------------------------------------------------------
# Sanitisation helpers
# ---------------------------------------------------------------------------
# Fields stripped from every task before it leaves the public boundary.
# Keeps owner ids, raw cron, and the (often verbose) author prompt out of
# anonymous responses.
_TASK_PRIVATE_FIELDS: frozenset[str] = frozenset(
{
"user_id",
"owner_user_id",
"creator_user_id",
"creator_email",
"prompt",
"execution_context",
"_subscription",
"role",
"scheduler_thread_id",
}
)
# Fields stripped from every run before it leaves the public boundary.
# We keep the result body (the user explicitly wants the MD content surfaced)
# but redact any path that points at a server-side filesystem location.
_RUN_PRIVATE_FIELDS: frozenset[str] = frozenset(
{
"user_id",
"owner_user_id",
"scheduler_thread_id",
"agent_run_id",
"can_edit",
}
)
def _redact_task(task: dict[str, Any]) -> dict[str, Any]:
return {k: v for k, v in task.items() if k not in _TASK_PRIVATE_FIELDS}
def _redact_run(run: dict[str, Any]) -> dict[str, Any]:
cleaned = {k: v for k, v in run.items() if k not in _RUN_PRIVATE_FIELDS}
result = cleaned.get("result")
if isinstance(result, dict):
files = result.get("files")
if isinstance(files, list):
cleaned_files = []
for idx, item in enumerate(files):
if not isinstance(item, dict):
continue
# Strip absolute filesystem path; clients use the file index
# to fetch content via the public file endpoint.
public_file = {k: v for k, v in item.items() if k != "path"}
public_file["index"] = idx
cleaned_files.append(public_file)
result = {**result, "files": cleaned_files}
cleaned["result"] = result
return cleaned
# ---------------------------------------------------------------------------
# Internal helpers
# ---------------------------------------------------------------------------
def _safe_filename(value: str, default: str = "scheduled-task-result") -> str:
name = re.sub(r'[\\/:*?"<>|\r\n]+', "-", value).strip(" .")
return name or default
def _result_markdown(result: dict[str, Any]) -> str:
title = str(result.get("title") or "Scheduled Task Result")
content = str(result.get("content") or "")
return f"# {title}\n\n{content}".strip() + "\n"
def _utf8_sig_bytes(content: str) -> bytes:
return content.encode("utf-8-sig")
def _content_disposition(filename: str) -> str:
quoted = quote(filename)
return f"attachment; filename*=UTF-8''{quoted}"
def _run_file_path(run: dict[str, Any], file_index: int) -> tuple[dict[str, Any], Path]:
result = run.get("result") or {}
files = result.get("files") if isinstance(result, dict) and isinstance(result.get("files"), list) else []
if file_index < 0 or file_index >= len(files):
raise HTTPException(status_code=404, detail="Result file not found")
item = files[file_index]
if not isinstance(item, dict) or not isinstance(item.get("path"), str):
raise HTTPException(status_code=404, detail="Result file not found")
path = Path(item["path"])
if not path.exists() or not path.is_file():
raise HTTPException(status_code=404, detail="Result file is no longer available")
return item, path
def _is_text_previewable(path: Path, mime_type: str | None) -> bool:
if mime_type and (mime_type.startswith("text/") or mime_type in {"application/json", "application/xml"}):
return True
return path.suffix.lower() in {".md", ".markdown", ".txt", ".json", ".csv", ".xml", ".yaml", ".yml", ".log"}
# ---------------------------------------------------------------------------
# Routes
# ---------------------------------------------------------------------------
@router.get("")
async def public_list_tasks(
search: str | None = Query(default=None, description="Case-insensitive fuzzy match on task name"),
limit: int = Query(default=200, ge=1, le=500),
offset: int = Query(default=0, ge=0),
) -> dict[str, Any]:
"""Return every scheduled task across all users.
Sensitive fields (user_id, raw prompt, scheduler thread id, …) are stripped
before serialisation. The response shape is intentionally stable so external
integrations can pin to it without surprises.
"""
service = get_scheduled_task_service()
tasks = await service.admin_list_tasks()
if search:
needle = search.strip().lower()
tasks = [t for t in tasks if needle in str(t.get("name", "")).lower()]
total = len(tasks)
sliced = tasks[offset : offset + limit]
return {
"total": total,
"limit": limit,
"offset": offset,
"tasks": [_redact_task(task) for task in sliced],
}
@router.get("/{task_id}")
async def public_get_task(task_id: str) -> dict[str, Any]:
"""Return metadata for a single task (without prompt body)."""
service = get_scheduled_task_service()
task = await service.store.get_task_any(task_id)
if task is None:
raise HTTPException(status_code=404, detail=f"Task {task_id} not found")
return _redact_task(task)
@router.get("/{task_id}/runs")
async def public_list_task_runs(
task_id: str,
limit: int = Query(default=50, ge=1, le=200),
) -> dict[str, Any]:
"""Return runs for a task, latest first."""
service = get_scheduled_task_service()
task = await service.store.get_task_any(task_id)
if task is None:
raise HTTPException(status_code=404, detail=f"Task {task_id} not found")
runs = await service.admin_list_runs(task_id, limit=limit)
return {
"task": _redact_task(task),
"total": len(runs),
"runs": [_redact_run(run) for run in runs],
}
@router.get("/runs/{run_id}")
async def public_get_run(run_id: str) -> dict[str, Any]:
"""Return a single run with its full result body (Markdown included)."""
service = get_scheduled_task_service()
run = await service.admin_get_run(run_id)
if run is None:
raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
return _redact_run(run)
@router.get("/runs/{run_id}/files/{file_index}")
async def public_get_run_file(run_id: str, file_index: int) -> dict[str, Any]:
"""Return a single result-file entry with its inline text content where
previewable. Binary files come back with ``previewable: false`` and the
consumer should fetch the download endpoint instead."""
service = get_scheduled_task_service()
run = await service.admin_get_run(run_id)
if run is None:
raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
item, path = _run_file_path(run, file_index)
mime_type = item.get("mime_type") or mimetypes.guess_type(path.name)[0]
previewable = _is_text_previewable(path, mime_type)
content: str | None = None
if previewable:
try:
content = path.read_text(encoding="utf-8")
except UnicodeDecodeError:
content = path.read_text(encoding="utf-8", errors="replace")
return {
"index": file_index,
"name": item.get("name") or path.name,
"mime_type": mime_type,
"kind": item.get("kind"),
"size": path.stat().st_size,
"previewable": previewable,
"content": content,
}
@router.get("/runs/{run_id}/files/{file_index}/download")
async def public_download_run_file(run_id: str, file_index: int):
"""Stream a single result file as a download."""
service = get_scheduled_task_service()
run = await service.admin_get_run(run_id)
if run is None:
raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
item, path = _run_file_path(run, file_index)
filename = _safe_filename(str(item.get("name") or path.name), path.name)
media = item.get("mime_type") or mimetypes.guess_type(path.name)[0] or "application/octet-stream"
return FileResponse(path, filename=filename, media_type=media)
@router.get("/runs/{run_id}/download")
async def public_download_run(run_id: str):
"""Download the full result: a zipped bundle of result.md + every file,
or a single ``.md`` when no auxiliary files were produced."""
service = get_scheduled_task_service()
run = await service.admin_get_run(run_id)
if run is None:
raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
result = run.get("result") or {}
if not isinstance(result, dict):
result = {}
files = result.get("files") if isinstance(result.get("files"), list) else []
accessible_files: list[tuple[str, Path]] = []
for item in files:
if not isinstance(item, dict):
continue
path_value = item.get("path")
if not isinstance(path_value, str) or not path_value:
continue
path = Path(path_value)
if path.exists() and path.is_file():
accessible_files.append((str(item.get("name") or path.name), path))
base_name = _safe_filename(str(result.get("title") or "scheduled-task-result"))
if not accessible_files:
return Response(
content=_utf8_sig_bytes(_result_markdown(result)),
media_type="text/markdown; charset=utf-8",
headers={"Content-Disposition": _content_disposition(f"{base_name}.md")},
)
archive = BytesIO()
with zipfile.ZipFile(archive, mode="w", compression=zipfile.ZIP_DEFLATED) as zf:
zf.writestr("result.md", _utf8_sig_bytes(_result_markdown(result)))
for name, path in accessible_files:
arcname = _safe_filename(name, path.name)
zf.write(path, arcname=arcname)
archive.seek(0)
return StreamingResponse(
archive,
media_type="application/zip",
headers={"Content-Disposition": _content_disposition(f"{base_name}.zip")},
)
@@ -14,8 +14,17 @@ from fastapi import APIRouter, HTTPException, Query, Request
from fastapi.responses import FileResponse, Response, StreamingResponse
from pydantic import BaseModel, Field
from app.gateway.deps import get_current_user, get_local_provider, get_tag_store
from deerflow.runtime.scheduler import get_scheduled_task_service
from app.gateway.deps import (
get_checkpointer,
get_current_user,
get_local_provider,
get_optional_user_from_request,
get_run_event_store,
get_run_store,
get_tag_store,
)
from deerflow.runtime import serialize_channel_values
from deerflow.runtime.scheduler import DuplicateTaskNameError, get_scheduled_task_service
router = APIRouter(prefix="/api/scheduled-tasks", tags=["scheduled-tasks"])
@@ -61,6 +70,26 @@ async def _user_id(request: Request) -> str:
return user_id
async def _is_admin(request: Request) -> bool:
"""True when the caller is an admin (or auth is disabled entirely)."""
user = await get_optional_user_from_request(request)
if user is None:
return True
return getattr(user, "system_role", None) == "admin"
async def _load_run(service, request: Request, run_id: str, user_id: str) -> dict[str, Any] | None:
"""Owner/subscriber run lookup, with an admin fallback to any run.
Lets admins open run results for tasks they do not own (the admin
management view links into the shared run-detail page).
"""
run = await service.get_run(user_id, run_id)
if run is None and await _is_admin(request):
run = await service.admin_get_run(run_id)
return run
async def _enrich_with_creator(tasks: list[dict[str, Any]] | dict[str, Any] | None) -> Any:
"""Attach ``creator_email`` / ``creator_user_id`` to one or many task dicts.
@@ -177,7 +206,7 @@ async def get_scheduler_thread(request: Request) -> dict:
async def list_scheduled_tasks(
request: Request,
search: str | None = Query(default=None, description="Case-insensitive fuzzy match on task name"),
tag_id: str | None = Query(default=None, description="Keep only tasks carrying this tag"),
tag_ids: list[str] | None = Query(default=None, description="Keep tasks carrying any of these tags (OR)"),
) -> list[dict]:
service = get_scheduled_task_service()
user_id = await _user_id(request)
@@ -191,8 +220,9 @@ async def list_scheduled_tasks(
if search:
needle = search.strip().lower()
tasks = [t for t in tasks if needle in str(t.get("name", "")).lower()]
if tag_id:
tasks = [t for t in tasks if any(tg.get("id") == tag_id for tg in t.get("tags", []))]
if tag_ids:
wanted = set(tag_ids)
tasks = [t for t in tasks if any(tg.get("id") in wanted for tg in t.get("tags", []))]
return tasks
@@ -208,12 +238,156 @@ async def list_scheduled_task_runs(task_id: str, request: Request, limit: int =
async def get_scheduled_task_run(run_id: str, request: Request) -> dict:
service = get_scheduled_task_service()
user_id = await _user_id(request)
run = await service.get_run(user_id, run_id)
run = await _load_run(service, request, run_id, user_id)
if run is None:
raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
return run
def _event_type_for_checkpoint_message(message: dict) -> str:
"""Map a serialized LangChain message to the same ``event_type`` strings
the run-event store uses, so the frontend's existing role labels keep
working for checkpoint-derived synthetic rows."""
raw_type = message.get("type") or message.get("role") or ""
if raw_type in {"human", "user"}:
return "llm.human.input"
if raw_type in {"ai", "assistant"}:
return "llm.ai.response"
if raw_type == "tool":
return "llm.tool.result"
if raw_type == "system":
return "llm.system"
return f"llm.{raw_type or 'message'}"
async def _checkpoint_messages_for_run(
request: Request, agent_run: dict, *, limit: int
) -> list[dict]:
"""Return a synthetic list of message rows pulled from the LangGraph
checkpoint for an in-flight run.
The event store is updated by the streaming pipeline and may stay empty
until the first message tuple is flushed — meanwhile the checkpoint
already carries the current state (input + accumulating AI deltas). We
project that into the same row shape the frontend uses for the event
store, so the run-detail page can show progress immediately."""
try:
checkpointer = get_checkpointer(request)
except Exception:
return []
thread_id = agent_run.get("thread_id")
if not thread_id:
return []
config = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
try:
tup = await checkpointer.aget_tuple(config)
except Exception:
return []
if tup is None:
return []
checkpoint = getattr(tup, "checkpoint", {}) or {}
channel_values = checkpoint.get("channel_values") or {}
try:
values = serialize_channel_values(channel_values)
except Exception:
return []
messages = values.get("messages") or []
rows: list[dict] = []
for index, message in enumerate(messages[-limit:]):
if not isinstance(message, dict):
continue
rows.append(
{
"seq": index + 1,
"event_type": _event_type_for_checkpoint_message(message),
"category": "message",
"content": message,
"metadata": {"source": "checkpoint"},
"created_at": None,
}
)
return rows
@router.get("/runs/{run_id}/messages")
async def get_scheduled_task_run_messages(run_id: str, request: Request, limit: int = 500) -> dict:
"""Agent messages produced by a scheduled run's underlying agent run.
Resolution order (most authoritative first):
1. Event-store rows for the underlying agent run — these are the per-tuple
streaming events the worker writes as the agent runs.
2. LangGraph checkpoint snapshot — the canonical conversation state. Used
as a fallback when the event store is still empty (early in a run) or
when only partial events have been flushed; we project the snapshot
into the same row shape the frontend already renders so the user can
see the prompt + current AI output while the task is mid-flight.
3. Synthetic human-input row built from ``task.prompt`` — shown even
before the agent run is registered, so a `pending` task at minimum
displays what was queued.
"""
service = get_scheduled_task_service()
user_id = await _user_id(request)
run = await _load_run(service, request, run_id, user_id)
if run is None:
raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
capped = max(1, min(limit, 1000))
# Always available: task prompt as the seeded human input. Lets the
# ``execution process`` tab show *something* even before the agent run is
# registered, which is the user-visible bug we're fixing.
fallback_rows: list[dict] = []
task_id = run.get("task_id")
if task_id:
task = await service.store.get_task_any(task_id)
prompt = (task or {}).get("prompt")
if prompt:
fallback_rows.append(
{
"seq": 0,
"event_type": "llm.human.input",
"category": "message",
# Frontend treats human-input content as a plain string.
"content": str(prompt),
"metadata": {"source": "task_prompt"},
"created_at": run.get("created_at") or run.get("scheduled_for"),
}
)
agent_run_id = run.get("agent_run_id")
if not agent_run_id:
return {"messages": fallback_rows, "has_more": False}
# Each scheduled run executes on its own throwaway runtime thread — NOT the
# run row's ``scheduler_thread_id`` — so resolve the real thread from the
# run store before querying its message events.
run_store = get_run_store(request)
agent_run = await run_store.get(agent_run_id, user_id=None)
if agent_run is None:
return {"messages": fallback_rows, "has_more": False}
event_store = get_run_event_store(request)
rows = await event_store.list_messages_by_run(
agent_run["thread_id"],
agent_run_id,
limit=capped + 1,
user_id=None,
)
# Event store has no rows yet (run just started, or events still buffering).
# Fall back to the live checkpoint so the user immediately sees the prompt
# + whatever AI output has been streamed so far.
if not rows:
checkpoint_rows = await _checkpoint_messages_for_run(request, agent_run, limit=capped)
if checkpoint_rows:
return {"messages": checkpoint_rows[:capped], "has_more": False}
return {"messages": fallback_rows, "has_more": False}
has_more = len(rows) > capped
return {"messages": rows[:capped] if has_more else rows, "has_more": has_more}
@router.delete("/runs/{run_id}")
async def delete_scheduled_task_run(run_id: str, request: Request) -> dict:
service = get_scheduled_task_service()
@@ -221,7 +395,15 @@ async def delete_scheduled_task_run(run_id: str, request: Request) -> dict:
try:
deleted = await service.delete_run(user_id, run_id)
except PermissionError as exc:
raise HTTPException(status_code=403, detail=str(exc))
# Owner-only for regular users; admins may still delete any run.
if await _is_admin(request):
deleted = await service.admin_delete_run(run_id)
else:
raise HTTPException(status_code=403, detail=str(exc))
# A run the caller does not own returns deleted=False — fall back to an
# admin-scoped delete so admins can clean up other users' runs.
if not deleted and await _is_admin(request):
deleted = await service.admin_delete_run(run_id)
if not deleted:
raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
return {"success": True}
@@ -231,7 +413,7 @@ async def delete_scheduled_task_run(run_id: str, request: Request) -> dict:
async def get_scheduled_task_run_file(run_id: str, file_index: int, request: Request) -> dict:
service = get_scheduled_task_service()
user_id = await _user_id(request)
run = await service.get_run(user_id, run_id)
run = await _load_run(service, request, run_id, user_id)
if run is None:
raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
item, path = _run_file_path(run, file_index)
@@ -279,7 +461,7 @@ async def update_scheduled_task_run_file(
async def download_scheduled_task_run(run_id: str, request: Request):
service = get_scheduled_task_service()
user_id = await _user_id(request)
run = await service.get_run(user_id, run_id)
run = await _load_run(service, request, run_id, user_id)
if run is None:
raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
@@ -328,7 +510,7 @@ async def download_scheduled_task_run(run_id: str, request: Request):
async def download_scheduled_task_run_file(run_id: str, file_index: int, request: Request):
service = get_scheduled_task_service()
user_id = await _user_id(request)
run = await service.get_run(user_id, run_id)
run = await _load_run(service, request, run_id, user_id)
if run is None:
raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
item, path = _run_file_path(run, file_index)
@@ -361,15 +543,18 @@ async def update_delivery_profile(body: ScheduledTaskDeliveryProfileUpdateReques
async def create_scheduled_task(body: ScheduledTaskCreateRequest, request: Request) -> dict:
service = get_scheduled_task_service()
user_id = await _user_id(request)
task = await service.create_task(
user_id=user_id,
name=body.name,
prompt=body.prompt,
schedule=body.schedule,
timezone=body.timezone,
execution_agent_name=body.execution_agent_name,
execution_context=body.execution_context,
)
try:
task = await service.create_task(
user_id=user_id,
name=body.name,
prompt=body.prompt,
schedule=body.schedule,
timezone=body.timezone,
execution_agent_name=body.execution_agent_name,
execution_context=body.execution_context,
)
except DuplicateTaskNameError:
raise HTTPException(status_code=409, detail="已存在同名定时任务,请换一个名称")
await _enrich_with_creator(task)
return task
@@ -378,7 +563,10 @@ async def create_scheduled_task(body: ScheduledTaskCreateRequest, request: Reque
async def update_scheduled_task(task_id: str, body: ScheduledTaskUpdateRequest, request: Request) -> dict:
service = get_scheduled_task_service()
user_id = await _user_id(request)
task = await service.update_task(user_id, task_id, body.model_dump(exclude_unset=True))
try:
task = await service.update_task(user_id, task_id, body.model_dump(exclude_unset=True))
except DuplicateTaskNameError:
raise HTTPException(status_code=409, detail="已存在同名定时任务,请换一个名称")
if task is None:
raise HTTPException(status_code=404, detail=f"Task {task_id} not found")
await _enrich_with_creator(task)
@@ -497,3 +685,85 @@ async def delete_scheduled_task_subscription(task_id: str, request: Request) ->
if not deleted:
raise HTTPException(status_code=404, detail="Subscription not found")
return {"success": True}
# --- Admin (cross-user management) ---
async def _require_admin(request: Request) -> None:
"""Reject non-admins. Lets the call through when auth is disabled."""
user = await get_optional_user_from_request(request)
if user is None:
return
if getattr(user, "system_role", None) != "admin":
raise HTTPException(status_code=403, detail="定时任务管理仅限管理员")
@router.get("/admin/all")
async def admin_list_scheduled_tasks(
request: Request,
search: str | None = Query(default=None, description="Case-insensitive fuzzy match on task name"),
) -> list[dict]:
"""List every scheduled task across all users. Admin-only."""
await _require_admin(request)
service = get_scheduled_task_service()
tasks = await service.admin_list_tasks()
await _enrich_with_creator(tasks)
tag_store = get_tag_store(request)
assignments = await tag_store.list_assignments("scheduled_task", [str(t.get("task_id")) for t in tasks])
for task in tasks:
task["tags"] = assignments.get(str(task.get("task_id")), [])
if search:
needle = search.strip().lower()
tasks = [t for t in tasks if needle in str(t.get("name", "")).lower()]
return tasks
@router.get("/admin/{task_id}/runs")
async def admin_list_scheduled_task_runs(task_id: str, request: Request, limit: int = 50) -> list[dict]:
"""List runs for any task regardless of owner. Admin-only."""
await _require_admin(request)
service = get_scheduled_task_service()
return await service.admin_list_runs(task_id, limit=max(1, min(limit, 200)))
@router.patch("/admin/{task_id}")
async def admin_update_scheduled_task(task_id: str, body: ScheduledTaskUpdateRequest, request: Request) -> dict:
"""Update any task regardless of owner. Admin-only."""
await _require_admin(request)
service = get_scheduled_task_service()
try:
task = await service.admin_update_task(task_id, body.model_dump(exclude_unset=True))
except DuplicateTaskNameError:
raise HTTPException(status_code=409, detail="已存在同名定时任务,请换一个名称")
if task is None:
raise HTTPException(status_code=404, detail=f"Task {task_id} not found")
await _enrich_with_creator(task)
return task
@router.delete("/admin/{task_id}")
async def admin_delete_scheduled_task(task_id: str, request: Request) -> dict:
"""Delete any task regardless of owner. Admin-only."""
await _require_admin(request)
service = get_scheduled_task_service()
deleted = await service.admin_delete_task(task_id)
if not deleted:
raise HTTPException(status_code=404, detail=f"Task {task_id} not found")
try:
await get_tag_store(request).unassign_all("scheduled_task", task_id)
except Exception: # noqa: BLE001 — tag cleanup must not block deletion
pass
return {"success": True}
@router.post("/admin/{task_id}/trigger")
async def admin_trigger_scheduled_task(task_id: str, request: Request) -> dict:
"""Trigger an immediate run of any task regardless of owner. Admin-only."""
await _require_admin(request)
service = get_scheduled_task_service()
task = await service.admin_trigger_task(task_id)
if task is None:
raise HTTPException(status_code=404, detail=f"Task {task_id} not found")
return {"success": True, "task": task}
@@ -45,6 +45,24 @@ def _is_admin_user(request: Request) -> bool:
return getattr(user, "system_role", None) == "admin"
def _can_view_skill_source(
category: SkillCategory,
owner_user_id: str | None,
user_id: str,
*,
is_admin: bool,
) -> bool:
"""Whether the raw SKILL.md source is visible to a user.
Admins may view any skill's source; otherwise only the publisher (the
owner of a custom skill) qualifies. Built-in / public skills have no human
owner, so for non-admins they are never source-visible.
"""
if is_admin:
return True
return category == SkillCategory.CUSTOM and owner_user_id is not None and owner_user_id == user_id
async def _get_owned_skill_or_raise(store: SkillStore, name: str, user_id: str) -> dict[str, Any]:
owned = await store.get_owned(name, user_id)
if owned is not None:
@@ -96,6 +114,7 @@ class SkillResponse(BaseModel):
owner_user_id: str | None = Field(default=None, description="Custom skill owner (null = built-in or legacy)")
published: bool = Field(default=False, description="Whether the owner has made this skill visible to other users")
builtin: bool = Field(default=False, description="True when owner_user_id is null (no human owner)")
detail: str | None = Field(default=None, description="Human-authored long-form detail text (Markdown), editable by owner/admin")
tags: list[dict] = Field(default_factory=list, description="Tags assigned to this skill")
@@ -180,10 +199,12 @@ def _skill_to_response(skill: Skill, ownership: dict[str, Any] | None = None) ->
owner_user_id: str | None = None
published = False
builtin = skill.category != SkillCategory.CUSTOM
detail: str | None = None
if ownership is not None:
owner_user_id = ownership.get("owner_user_id")
published = bool(ownership.get("published", False))
builtin = bool(ownership.get("builtin", owner_user_id is None))
detail = ownership.get("detail")
return SkillResponse(
name=skill.name,
@@ -201,6 +222,7 @@ def _skill_to_response(skill: Skill, ownership: dict[str, Any] | None = None) ->
owner_user_id=owner_user_id,
published=published,
builtin=builtin,
detail=detail,
)
@@ -214,7 +236,7 @@ async def _attach_and_filter_tags(
tag_store: TagStore,
responses: list[SkillResponse],
search: str | None,
tag_id: str | None,
tag_ids: list[str] | None,
) -> list[SkillResponse]:
"""Bulk-attach tags to skill responses, then apply name/tag filters."""
assignments = await tag_store.list_assignments("skill", [r.name for r in responses])
@@ -223,8 +245,9 @@ async def _attach_and_filter_tags(
if search:
needle = search.strip().lower()
responses = [r for r in responses if needle in r.name.lower()]
if tag_id:
responses = [r for r in responses if any(t.get("id") == tag_id for t in r.tags)]
if tag_ids:
wanted = set(tag_ids)
responses = [r for r in responses if any(t.get("id") in wanted for t in r.tags)]
return responses
@@ -240,7 +263,7 @@ async def list_skills(
skill_store: SkillStore = Depends(get_skill_store),
tag_store: TagStore = Depends(get_tag_store),
search: str | None = Query(default=None, description="Case-insensitive fuzzy match on skill name"),
tag_id: str | None = Query(default=None, description="Keep only skills carrying this tag"),
tag_ids: list[str] | None = Query(default=None, description="Keep skills carrying any of these tags (OR)"),
) -> SkillsListResponse:
try:
user_id = _current_user_id(request)
@@ -251,13 +274,15 @@ async def list_skills(
# Public/built-in skills (no DB row) are visible to everyone.
# Custom skills must have an ownership record in the visible set.
if skill.category != SkillCategory.CUSTOM:
responses.append(_skill_to_response(skill))
# Built-in skills usually have no DB row, but an admin-authored
# ``detail`` annotation materializes one — surface it when present.
responses.append(_skill_to_response(skill, ownership.get(skill.name)))
continue
record = ownership.get(skill.name)
if record is None:
continue
responses.append(_skill_to_response(skill, record))
responses = await _attach_and_filter_tags(tag_store, responses, search, tag_id)
responses = await _attach_and_filter_tags(tag_store, responses, search, tag_ids)
return SkillsListResponse(skills=responses)
except Exception as e:
logger.error(f"Failed to load skills: {e}", exc_info=True)
@@ -828,7 +853,12 @@ async def rollback_custom_skill(skill_name: str, request: SkillRollbackRequest,
summary="Get Skill Details",
description="Retrieve detailed information about a specific skill by its name.",
)
async def get_skill(skill_name: str, config: AppConfig = Depends(get_config)) -> SkillResponse:
async def get_skill(
skill_name: str,
request: Request,
config: AppConfig = Depends(get_config),
skill_store: SkillStore = Depends(get_skill_store),
) -> SkillResponse:
try:
skill_name = skill_name.replace("\r\n", "").replace("\n", "")
skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
@@ -837,7 +867,9 @@ async def get_skill(skill_name: str, config: AppConfig = Depends(get_config)) ->
if skill is None:
raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
return _skill_to_response(skill)
# Attach ownership (owner/published/detail) when the caller may see it.
ownership = await skill_store.get_visible(skill_name, _current_user_id(request))
return _skill_to_response(skill, ownership)
except HTTPException:
raise
except Exception as e:
@@ -857,15 +889,27 @@ class SkillContentResponse(BaseModel):
"/skills/{skill_name}/content",
response_model=SkillContentResponse,
summary="Get Skill Markdown Content",
description="Retrieve the raw SKILL.md content of a specific skill (public or custom).",
description="Retrieve the raw SKILL.md content of a skill. Only an admin or the skill's publisher (owner of a custom skill) may read it; other users see only the description and detail.",
)
async def get_skill_content(skill_name: str, config: AppConfig = Depends(get_config)) -> SkillContentResponse:
async def get_skill_content(
skill_name: str,
request: Request,
config: AppConfig = Depends(get_config),
skill_store: SkillStore = Depends(get_skill_store),
) -> SkillContentResponse:
try:
skill_name = skill_name.replace("\r\n", "").replace("\n", "")
skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
skill = next((s for s in skills if s.name == skill_name), None)
if skill is None:
raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
# The raw SKILL.md is implementation detail — only an admin or the
# publisher (owner of a custom skill) may view it. Everyone else is
# limited to the description + detail surfaced by the list/detail APIs.
record = await skill_store.get_any(skill_name)
owner_user_id = record.get("owner_user_id") if record else None
if not _can_view_skill_source(skill.category, owner_user_id, _current_user_id(request), is_admin=_is_admin_user(request)):
raise HTTPException(status_code=403, detail="Only the skill publisher or an admin can view the SKILL.md source")
content = skill.skill_file.read_text(encoding="utf-8")
return SkillContentResponse(name=skill.name, category=skill.category, content=content)
except HTTPException:
@@ -926,6 +970,71 @@ async def update_skill(skill_name: str, request: SkillUpdateRequest, config: App
raise HTTPException(status_code=500, detail=f"Failed to update skill: {str(e)}")
class SkillDetailRequest(BaseModel):
"""Request body for setting a skill's human-authored detail text."""
detail: str = Field(default="", description="详情说明文本,支持 Markdown;传空字符串表示清空")
class SkillDetailResponse(BaseModel):
"""Response model for the skill-detail update endpoint."""
name: str = Field(..., description="Skill name")
detail: str | None = Field(default=None, description="Persisted detail text (null when cleared)")
@router.put(
"/skills/{skill_name}/detail",
response_model=SkillDetailResponse,
summary="Update Skill Detail",
description="设置技能的详情说明。自定义技能由其所有者或管理员编辑;内置/公开技能仅管理员可编辑。",
)
async def update_skill_detail(
skill_name: str,
body: SkillDetailRequest,
request: Request,
config: AppConfig = Depends(get_config),
skill_store: SkillStore = Depends(get_skill_store),
) -> SkillDetailResponse:
try:
skill_name = skill_name.replace("\r\n", "").replace("\n", "")
user_id = _current_user_id(request)
is_admin = _is_admin_user(request)
skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
skill = next((s for s in skills if s.name == skill_name), None)
if skill is None:
raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
# Empty / whitespace-only input clears the annotation.
detail_value: str | None = body.detail.strip() or None
if skill.category == SkillCategory.CUSTOM:
# Owner edits their own skill; admins may edit anyone's.
_record, mode = await _get_editable_skill_or_raise(skill_store, skill_name, user_id, is_admin=is_admin)
if mode == "admin":
updated = await skill_store.update_admin(skill_name, {"detail": detail_value})
else:
updated = await skill_store.update(skill_name, user_id, {"detail": detail_value})
else:
# Built-in / public skill — only admins may annotate it. These carry
# no DB row by default, so materialize one before writing detail.
if not is_admin:
raise HTTPException(status_code=403, detail="Only admin users can edit built-in skill details")
if await skill_store.get_any(skill_name) is None:
await skill_store.ensure_legacy({"name": skill_name, "owner_user_id": None, "published": True})
updated = await skill_store.update_admin(skill_name, {"detail": detail_value})
if updated is None:
raise HTTPException(status_code=500, detail="Failed to persist skill detail")
return SkillDetailResponse(name=skill_name, detail=updated.get("detail"))
except HTTPException:
raise
except Exception as e:
logger.error("Failed to update detail for %s: %s", skill_name, e, exc_info=True)
raise HTTPException(status_code=500, detail=f"Failed to update skill detail: {str(e)}")
class SkillPinRequest(BaseModel):
pinned: bool = Field(..., description="Whether to pin or unpin the skill")
@@ -0,0 +1,351 @@
"""Conversation sharing API.
A user creates a share code for *one* of their conversations; redeeming the
code copies that conversation into the redeemer's account as an independent
copy they fully own and can keep chatting in. See ``app/gateway/thread_copy.py``
for the checkpoint duplication.
"""
from __future__ import annotations
import logging
import mimetypes
import shutil
import uuid
from pathlib import Path
from fastapi import APIRouter, Depends, HTTPException, Request
from fastapi.responses import FileResponse
from pydantic import BaseModel, Field
from app.gateway.deps import get_checkpointer, get_thread_share_store, get_thread_store
from app.gateway.thread_copy import copy_thread_state
from deerflow.config.paths import get_paths
from deerflow.persistence.thread_meta.base import ThreadMetaStore
from deerflow.persistence.thread_shares.base import ThreadShareStore
from deerflow.runtime import serialize_channel_values
from deerflow.runtime.user_context import get_effective_user_id
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/api/thread-shares", tags=["thread-shares"])
# Public, unauthenticated router. Its prefix is whitelisted in
# ``auth_middleware._PUBLIC_PATH_PREFIXES`` — only mount read-only endpoints
# that are intentionally world-readable here.
public_router = APIRouter(prefix="/api/public/shares", tags=["thread-shares-public"])
_UNTITLED = "未命名对话"
# Valid share modes. "import" copies the conversation into the recipient's
# account; "view" is a public read-only static page anyone can open.
_SHARE_MODES = ("import", "view")
def _current_user_id(request: Request) -> str:
user = getattr(request.state, "user", None)
if user is not None:
return str(user.id)
return get_effective_user_id()
# ---------------------------------------------------------------------------
# Request / response models
# ---------------------------------------------------------------------------
class CreateShareRequest(BaseModel):
thread_id: str = Field(..., description="The conversation to share")
mode: str = Field(
default="import",
description='"import" — recipient copies the conversation; "view" — public read-only page',
)
class ShareResponse(BaseModel):
share_code: str = Field(..., description="Short code that recipients enter to import")
owner_user_id: str = Field(..., description="User who created the share")
thread_id: str = Field(..., description="The shared conversation")
revoked: bool = Field(default=False, description="Whether the code has been revoked")
mode: str = Field(default="import", description='"import" or "view"')
created_at: str | None = Field(default=None, description="Creation timestamp (ISO-8601)")
class PublicShareSnapshotResponse(BaseModel):
"""Read-only conversation snapshot served to anonymous viewers."""
share_code: str
title: str = Field(..., description="Conversation title")
mode: str = Field(default="view")
messages: list[dict] = Field(default_factory=list, description="Serialized conversation messages")
artifacts: list[str] = Field(default_factory=list, description="Artifact virtual paths produced in the conversation")
created_at: str | None = Field(default=None, description="When the share was created (ISO-8601)")
class SharesListResponse(BaseModel):
shares: list[ShareResponse]
class SharePreviewResponse(BaseModel):
share_code: str
shared_by: str = Field(..., description="Owner user id of the shared conversation")
title: str = Field(..., description="Title of the shared conversation")
class ImportResultResponse(BaseModel):
imported: int = Field(..., description="1 when the conversation was copied, else 0")
skipped: int = Field(..., description="1 when it was already imported, else 0")
# ---------------------------------------------------------------------------
# Owner side — create / list / revoke
# ---------------------------------------------------------------------------
@router.post("", response_model=ShareResponse, summary="Create a share code for one conversation")
async def create_share(
body: CreateShareRequest,
request: Request,
share_store: ThreadShareStore = Depends(get_thread_share_store),
thread_store: ThreadMetaStore = Depends(get_thread_store),
) -> ShareResponse:
me = _current_user_id(request)
mode = body.mode if body.mode in _SHARE_MODES else "import"
# Only the conversation's owner may share it.
meta = await thread_store.get(body.thread_id, user_id=me)
if meta is None:
raise HTTPException(status_code=404, detail="Conversation not found")
# Reuse an existing active code (of the same mode) so re-sharing is idempotent.
existing = await share_store.get_active_for_thread(me, body.thread_id, mode=mode)
if existing is not None:
return ShareResponse(**existing)
record = await share_store.create(me, body.thread_id, mode=mode)
return ShareResponse(**record)
@router.get("", response_model=SharesListResponse, summary="List my conversation share codes")
async def list_shares(
request: Request,
share_store: ThreadShareStore = Depends(get_thread_share_store),
) -> SharesListResponse:
records = await share_store.list_for_owner(_current_user_id(request))
return SharesListResponse(shares=[ShareResponse(**r) for r in records])
@router.delete("/{share_code}", summary="Revoke a conversation share code")
async def revoke_share(
share_code: str,
request: Request,
share_store: ThreadShareStore = Depends(get_thread_share_store),
) -> dict[str, bool]:
ok = await share_store.revoke(share_code, _current_user_id(request))
if not ok:
raise HTTPException(status_code=404, detail="Share code not found")
return {"success": True}
# ---------------------------------------------------------------------------
# Recipient side — preview / import
# ---------------------------------------------------------------------------
async def _resolve_active_share(share_code: str, share_store: ThreadShareStore) -> dict:
share = await share_store.get(share_code)
if share is None:
raise HTTPException(status_code=404, detail="Share code not found")
if share.get("revoked"):
raise HTTPException(status_code=410, detail="This share code has been revoked")
return share
@router.get("/{share_code}/preview", response_model=SharePreviewResponse, summary="Preview a shared conversation")
async def preview_share(
share_code: str,
share_store: ThreadShareStore = Depends(get_thread_share_store),
thread_store: ThreadMetaStore = Depends(get_thread_store),
) -> SharePreviewResponse:
share = await _resolve_active_share(share_code, share_store)
owner = share["owner_user_id"]
meta = await thread_store.get(share["thread_id"], user_id=owner)
if meta is None:
raise HTTPException(status_code=404, detail="The shared conversation no longer exists")
return SharePreviewResponse(
share_code=share_code,
shared_by=owner,
title=meta.get("display_name") or _UNTITLED,
)
def _copy_thread_files(origin_thread_id: str, owner_user_id: str, new_thread_id: str, recipient_user_id: str) -> None:
"""Copy a thread's user-data directory (uploads + outputs/artifacts)."""
paths = get_paths()
src_data = paths.thread_dir(origin_thread_id, user_id=owner_user_id) / "user-data"
if not src_data.is_dir():
return
dst_data = paths.thread_dir(new_thread_id, user_id=recipient_user_id) / "user-data"
shutil.copytree(src_data, dst_data, dirs_exist_ok=True)
@router.post("/{share_code}/import", response_model=ImportResultResponse, summary="Import a shared conversation")
async def import_share(
share_code: str,
request: Request,
share_store: ThreadShareStore = Depends(get_thread_share_store),
thread_store: ThreadMetaStore = Depends(get_thread_store),
) -> ImportResultResponse:
share = await _resolve_active_share(share_code, share_store)
if share.get("mode") == "view":
raise HTTPException(status_code=400, detail="This is a view-only share — open its link to read it instead of importing")
owner = share["owner_user_id"]
origin_id = share["thread_id"]
recipient = _current_user_id(request)
if owner == recipient:
raise HTTPException(status_code=400, detail="You cannot import your own share code")
src = await thread_store.get(origin_id, user_id=owner)
if src is None:
raise HTTPException(status_code=404, detail="The shared conversation no longer exists")
# Dedup: skip if this user already imported this conversation.
mine = await thread_store.search(user_id=recipient, limit=2000)
already = {(t.get("metadata") or {}).get("shared_origin") for t in mine}
if origin_id in already:
return ImportResultResponse(imported=0, skipped=1)
new_id = str(uuid.uuid4())
checkpointer = get_checkpointer(request)
await copy_thread_state(checkpointer, origin_id, new_id)
metadata = dict(src.get("metadata") or {})
metadata.update({"shared_from_code": share_code, "shared_origin": origin_id, "shared_by": owner})
await thread_store.create(
new_id,
assistant_id=src.get("assistant_id"),
user_id=recipient,
display_name=src.get("display_name"),
metadata=metadata,
)
try:
_copy_thread_files(origin_id, owner, new_id, recipient)
except Exception as exc: # noqa: BLE001 — file copy failure must not lose the conversation
logger.warning("Failed to copy files for thread %s -> %s: %s", origin_id, new_id, exc)
logger.info("Share %s imported by %s as thread %s", share_code, recipient, new_id)
return ImportResultResponse(imported=1, skipped=0)
# ---------------------------------------------------------------------------
# Public read-only view — no authentication required
# ---------------------------------------------------------------------------
async def _load_thread_snapshot(checkpointer, thread_id: str) -> tuple[list[dict], list[str]]:
"""Return (messages, artifacts) from a thread's latest checkpoint.
Reads straight from the checkpointer — the same source the live chat
streams from — so the static snapshot matches the conversation exactly.
"""
config = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
checkpoint_tuple = await checkpointer.aget_tuple(config)
if checkpoint_tuple is None:
return [], []
checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {}
values = serialize_channel_values(checkpoint.get("channel_values", {}) or {})
messages = values.get("messages")
artifacts = values.get("artifacts")
return (
[m for m in messages if isinstance(m, dict)] if isinstance(messages, list) else [],
[a for a in artifacts if isinstance(a, str)] if isinstance(artifacts, list) else [],
)
@public_router.get(
"/{share_code}",
response_model=PublicShareSnapshotResponse,
summary="Public read-only snapshot of a view-shared conversation",
)
async def get_public_share_snapshot(
share_code: str,
share_store: ThreadShareStore = Depends(get_thread_share_store),
thread_store: ThreadMetaStore = Depends(get_thread_store),
checkpointer=Depends(get_checkpointer),
) -> PublicShareSnapshotResponse:
"""Serve a frozen, read-only conversation. Anyone with the link can read it.
Only ``mode="view"`` shares are exposed; missing, revoked, or import-mode
codes all return 404 so the endpoint never reveals which case applies.
"""
share = await share_store.get(share_code)
if share is None or share.get("revoked") or share.get("mode") != "view":
raise HTTPException(status_code=404, detail="Share not found")
meta = await thread_store.get(share["thread_id"], user_id=share["owner_user_id"])
if meta is None:
raise HTTPException(status_code=404, detail="The shared conversation no longer exists")
messages, artifacts = await _load_thread_snapshot(checkpointer, share["thread_id"])
return PublicShareSnapshotResponse(
share_code=share_code,
title=meta.get("display_name") or _UNTITLED,
mode="view",
messages=messages,
artifacts=artifacts,
created_at=share.get("created_at"),
)
# Content types that can execute scripts in the app origin — always served as
# a download attachment so a shared file can never run as a top-level document.
_PUBLIC_SHARE_ACTIVE_TYPES = {"text/html", "application/xhtml+xml", "image/svg+xml"}
def _public_share_disposition(mime_type: str) -> str:
"""Pick a Content-Disposition for a public-share file.
Active content (HTML/XHTML/SVG) is forced to ``attachment`` so it cannot
execute as a top-level document; everything else (images, Markdown, text,
PDF, …) is served ``inline`` so viewers can open it directly.
"""
return "attachment" if mime_type in _PUBLIC_SHARE_ACTIVE_TYPES else "inline"
@public_router.get(
"/{share_code}/files/{path:path}",
summary="Public file attachment from a view-shared conversation",
)
async def get_public_share_file(
share_code: str,
path: str,
share_store: ThreadShareStore = Depends(get_thread_share_store),
) -> FileResponse:
"""Serve a file referenced by a view-shared conversation.
A ``view`` share is a public read-only page, so the files its conversation
references (images, Markdown, text, PDF, …) must be openable. Path
resolution is confined to the owner's thread directory, so this cannot read
arbitrary files. Active content (HTML/XHTML/SVG) is forced to download so it
can never execute as a top-level document in the app origin; everything
else is served inline.
"""
share = await share_store.get(share_code)
if share is None or share.get("revoked") or share.get("mode") != "view":
raise HTTPException(status_code=404, detail="Share not found")
# Resolve the virtual path inside the *owner's* thread directory.
try:
actual = get_paths().resolve_virtual_path(share["thread_id"], path, user_id=share["owner_user_id"])
except ValueError as exc:
status = 403 if "traversal" in str(exc) else 400
raise HTTPException(status_code=status, detail=str(exc))
actual_path = Path(actual)
if not actual_path.exists() or not actual_path.is_file():
raise HTTPException(status_code=404, detail="File not found")
mime_type = mimetypes.guess_type(actual_path.name)[0] or "application/octet-stream"
return FileResponse(
actual_path,
media_type=mime_type,
content_disposition_type=_public_share_disposition(mime_type),
headers={"Cache-Control": "public, max-age=300"},
)
@@ -0,0 +1,380 @@
"""Admin-only tool / skill call metrics: list + Excel export.
Companion to ``llm_metrics`` — where that audits every LLM provider call, this
audits every *tool* call (built-in tools, skills, MCP tools, subagent calls),
including the failures: retrieval errors, blocked/rate-limited IPs, timeouts,
auth problems. Failures are bucketed into a coarse ``error_category`` so an
admin can scan for systemic issues.
"""
from __future__ import annotations
import logging
from datetime import datetime
from io import BytesIO
from typing import Any
from urllib.parse import quote
from fastapi import APIRouter, HTTPException, Query, Request
from fastapi.responses import StreamingResponse
from pydantic import BaseModel, Field
from app.gateway.deps import get_local_provider, get_optional_user_from_request, get_tool_metrics_store
from deerflow.persistence.tool_metrics.base import ToolMetricsQuery, ToolMetricsStore
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/api/admin/tool-metrics", tags=["tool-metrics"])
_VALID_CATEGORIES = (
"rate_limited",
"ip_blocked",
"auth_error",
"timeout",
"network_error",
"not_found",
"empty_result",
"tool_error",
)
def _kind_is_skill(kind: str | None) -> bool:
"""``kind=skill`` keeps only rows that target a specific Agent Skill."""
return kind == "skill"
class ToolMetricResponse(BaseModel):
id: str
created_at: str | None = None
user_id: str | None = None
user_name: str | None = Field(
default=None,
description="Local part (before @) of the user's email, resolved from user_id",
)
thread_id: str | None = None
run_id: str | None = None
agent_name: str | None = None
tool_name: str | None = None
skill_name: str | None = Field(
default=None,
description="The Agent Skill this call targets (skill tools only)",
)
duration_ms: int = 0
status: str = "success"
error_category: str | None = None
error_message: str | None = None
class ToolMetricsListResponse(BaseModel):
items: list[ToolMetricResponse]
total: int = Field(..., description="Total rows matching the filter, ignoring pagination")
limit: int
offset: int
async def _require_admin(request: Request) -> None:
user = await get_optional_user_from_request(request)
if user is None:
return
if getattr(user, "system_role", None) != "admin":
raise HTTPException(status_code=403, detail="Tool metrics admin view is admin-only")
def _require_store(request: Request) -> ToolMetricsStore:
store = get_tool_metrics_store(request)
if store is None:
raise HTTPException(status_code=503, detail="Tool metrics store is not configured")
return store
def _parse_dt(value: str | None) -> datetime | None:
if not value:
return None
try:
return datetime.fromisoformat(value.replace("Z", "+00:00"))
except ValueError as exc:
raise HTTPException(status_code=422, detail=f"Invalid datetime: {value!r} ({exc})") from exc
def _email_local_part(email: str | None) -> str | None:
if not email:
return None
at = email.find("@")
return email[:at] if at > 0 else email
async def _resolve_user_name_to_id(name: str | None) -> str | None:
if not name:
return None
try:
provider = get_local_provider()
user = await provider.find_user_by_email_local_part(name)
except Exception:
return None
return str(user.id) if user is not None else None
async def _attach_usernames(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
"""Resolve each row's ``user_id`` UUID to a friendly ``user_name``."""
if not rows:
return rows
user_ids = {row["user_id"] for row in rows if isinstance(row, dict) and row.get("user_id")}
if not user_ids:
return rows
try:
provider = get_local_provider()
except Exception:
provider = None
email_by_id: dict[str, str] = {}
if provider is not None:
for uid in user_ids:
try:
user = await provider.get_user(uid)
except Exception:
user = None
if user is not None and user.email:
email_by_id[uid] = user.email
for row in rows:
if isinstance(row, dict) and row.get("user_id"):
email = email_by_id.get(row["user_id"])
row["user_name"] = _email_local_part(email) or row["user_id"]
return rows
def _build_query(
*,
user_id: str | None,
tool_name: str | None,
skill_only: bool = False,
skill_name: str | None = None,
status: str | None,
error_category: str | None,
since: str | None,
until: str | None,
limit: int,
offset: int,
) -> ToolMetricsQuery:
return ToolMetricsQuery(
user_id=user_id or None,
tool_name=tool_name or None,
skill_only=skill_only,
skill_name=skill_name or None,
status=status or None,
error_category=error_category or None,
since=_parse_dt(since),
until=_parse_dt(until),
limit=limit,
offset=offset,
)
@router.get("", response_model=ToolMetricsListResponse)
async def list_tool_metrics(
request: Request,
user_id: str | None = Query(default=None),
user_name: str | None = Query(default=None, description="Username (email local part) to filter by"),
tool_name: str | None = Query(default=None),
kind: str | None = Query(default=None, description="Coarse call kind: 'skill' keeps only Agent-Skill invocations"),
skill_name: str | None = Query(default=None, description="Filter to one specific Agent Skill by name"),
status: str | None = Query(default=None, pattern="^(success|error)$"),
error_category: str | None = Query(default=None, description="Coarse failure bucket"),
since: str | None = Query(default=None, description="ISO 8601 datetime, inclusive lower bound"),
until: str | None = Query(default=None, description="ISO 8601 datetime, inclusive upper bound"),
limit: int = Query(default=50, ge=1, le=500),
offset: int = Query(default=0, ge=0),
) -> ToolMetricsListResponse:
await _require_admin(request)
store = _require_store(request)
if error_category and error_category not in _VALID_CATEGORIES:
raise HTTPException(status_code=422, detail=f"Unknown error_category: {error_category!r}")
if not user_id and user_name:
resolved = await _resolve_user_name_to_id(user_name)
if resolved is None:
return ToolMetricsListResponse(items=[], total=0, limit=limit, offset=offset)
user_id = resolved
query = _build_query(
user_id=user_id,
tool_name=tool_name,
skill_only=_kind_is_skill(kind),
skill_name=skill_name,
status=status,
error_category=error_category,
since=since,
until=until,
limit=limit,
offset=offset,
)
rows = await store.list(query)
total = await store.count(query)
await _attach_usernames(rows)
return ToolMetricsListResponse(
items=[ToolMetricResponse(**row) for row in rows],
total=total,
limit=limit,
offset=offset,
)
class SkillStat(BaseModel):
skill_name: str
total: int
success: int
error: int
class ToolMetricsSummaryResponse(BaseModel):
total: int
error_total: int
by_category: dict[str, int] = Field(default_factory=dict)
by_skill: list[SkillStat] = Field(
default_factory=list,
description="Per-skill invocation counts — answers 'was skill X called, and did it succeed'",
)
@router.get("/summary", response_model=ToolMetricsSummaryResponse)
async def tool_metrics_summary(
request: Request,
user_id: str | None = Query(default=None),
user_name: str | None = Query(default=None),
tool_name: str | None = Query(default=None),
kind: str | None = Query(default=None),
skill_name: str | None = Query(default=None),
since: str | None = Query(default=None),
until: str | None = Query(default=None),
) -> ToolMetricsSummaryResponse:
"""Aggregate counts: total, errors, per-category breakdown, and per-skill stats."""
await _require_admin(request)
store = _require_store(request)
if not user_id and user_name:
resolved = await _resolve_user_name_to_id(user_name)
if resolved is None:
return ToolMetricsSummaryResponse(total=0, error_total=0, by_category={}, by_skill=[])
user_id = resolved
skill_only = _kind_is_skill(kind)
def _q(*, status: str | None = None, error_category: str | None = None) -> ToolMetricsQuery:
return _build_query(
user_id=user_id,
tool_name=tool_name,
skill_only=skill_only,
skill_name=skill_name,
status=status,
error_category=error_category,
since=since,
until=until,
limit=1,
offset=0,
)
total = await store.count(_q())
error_total = await store.count(_q(status="error"))
by_category: dict[str, int] = {}
for category in _VALID_CATEGORIES:
count = await store.count(_q(status="error", error_category=category))
if count:
by_category[category] = count
by_skill = [SkillStat(**row) for row in await store.skill_breakdown(_q())]
return ToolMetricsSummaryResponse(
total=total, error_total=error_total, by_category=by_category, by_skill=by_skill
)
def _format_cell(value: Any) -> Any:
if value is None:
return ""
if isinstance(value, datetime):
return value.replace(tzinfo=None) if value.tzinfo else value
return value
@router.get("/export")
async def export_tool_metrics(
request: Request,
user_id: str | None = Query(default=None),
user_name: str | None = Query(default=None),
tool_name: str | None = Query(default=None),
kind: str | None = Query(default=None),
skill_name: str | None = Query(default=None),
status: str | None = Query(default=None, pattern="^(success|error)$"),
error_category: str | None = Query(default=None),
since: str | None = Query(default=None),
until: str | None = Query(default=None),
):
"""Stream the full filtered metric set as an ``.xlsx`` file."""
await _require_admin(request)
store = _require_store(request)
if not user_id and user_name:
resolved = await _resolve_user_name_to_id(user_name)
user_id = resolved if resolved is not None else "__no_such_user__"
try:
from openpyxl import Workbook
except ImportError as exc:
raise HTTPException(status_code=500, detail=f"openpyxl is not installed: {exc}") from exc
query = _build_query(
user_id=user_id,
tool_name=tool_name,
skill_only=_kind_is_skill(kind),
skill_name=skill_name,
status=status,
error_category=error_category,
since=since,
until=until,
limit=1,
offset=0,
)
workbook = Workbook(write_only=True)
sheet = workbook.create_sheet("tool_call_metrics")
columns = [
"id",
"created_at",
"status",
"error_category",
"user_name",
"user_id",
"thread_id",
"run_id",
"agent_name",
"tool_name",
"skill_name",
"duration_ms",
"error_message",
]
sheet.append(columns)
buffered: list[dict[str, Any]] = []
FLUSH_AT = 200
async def flush() -> int:
if not buffered:
return 0
await _attach_usernames(buffered)
for row in buffered:
sheet.append([_format_cell(row.get(col)) for col in columns])
n = len(buffered)
buffered.clear()
return n
count = 0
async for row in store.iter_all(query):
buffered.append(row)
if len(buffered) >= FLUSH_AT:
count += await flush()
count += await flush()
buffer = BytesIO()
workbook.save(buffer)
buffer.seek(0)
logger.info("Exported %d tool_call_metrics rows", count)
timestamp = datetime.utcnow().strftime("%Y%m%d-%H%M%S")
filename = f"tool_call_metrics-{timestamp}.xlsx"
headers = {
"Content-Disposition": f"attachment; filename=\"{filename}\"; filename*=UTF-8''{quote(filename)}",
}
return StreamingResponse(
buffer,
media_type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
headers=headers,
)
@@ -0,0 +1,191 @@
"""Writing rewrite API — SSE streaming endpoint.
POST /api/writing/rewrite
Returns text/event-stream with frames:
event: thinking data: {"chunk": "..."}
event: text data: {"chunk": "..."}
event: done data: {}
event: error data: {"message": "..."}
"""
from __future__ import annotations
import json
import logging
from fastapi import APIRouter, Depends
from fastapi.responses import StreamingResponse
from langchain_core.messages import AIMessage, HumanMessage, SystemMessage
from pydantic import BaseModel, Field
from app.gateway.deps import get_config
from deerflow.config.app_config import AppConfig
from deerflow.models import create_chat_model
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/api/writing", tags=["writing"])
# ── Prompts ───────────────────────────────────────────────────────────────────
_SYSTEM_PROMPT = """你是一位专业的中文写作助手,擅长润色、扩写、缩写和调整文风。
规则:
- 只输出改写后的正文,不加任何前缀、解释或括号说明。
- 保持原文的语言(中文输入 → 中文输出,英文输入 → 英文输出)。
- 改写结果应与原文长度相近,除非任务要求扩写或缩写。
- 不要添加 markdown 标题或特殊格式,除非原文本身包含。
"""
_ACTION_INSTRUCTIONS: dict[str, str] = {
"polish": "请对以下文字进行润色,使其表达更流畅、自然,同时保留原意。",
"expand": "请对以下文字进行扩写,补充细节和说明,使内容更丰富饱满。",
"shorten": "请对以下文字进行缩写,保留核心意思,去除冗余表达,使其更简洁。",
"tone": "请调整以下文字的语气风格。",
}
_TONE_SUFFIX: dict[str, str] = {
"professional": "目标风格:专业、正式。",
"casual": "目标风格:轻松、口语化。",
"readable": "目标风格:通俗易懂、易于阅读。",
"academic": "目标风格:学术严谨、逻辑清晰。",
"expressive": "目标风格:生动有文采、富有感染力。",
}
# ── Request model ─────────────────────────────────────────────────────────────
class SelectionInfo(BaseModel):
from_: int = Field(..., alias="from", description="ProseMirror start offset")
to: int = Field(..., description="ProseMirror end offset")
text: str = Field(..., description="Selected plain text")
model_config = {"populate_by_name": True}
class SurroundingContext(BaseModel):
before: str = Field(default="", description="Text before the selection")
after: str = Field(default="", description="Text after the selection")
class RewriteRequest(BaseModel):
thread_id: str | None = Field(default=None, alias="threadId")
selection: SelectionInfo
action: str = Field(..., description="polish | expand | shorten | tone")
tone: str | None = Field(default=None)
model_name: str | None = Field(default=None, alias="modelName")
surrounding_context: SurroundingContext = Field(default_factory=SurroundingContext, alias="surroundingContext")
custom_instruction: str | None = Field(default=None, alias="customInstruction")
follow_up_instruction: str | None = Field(default=None, alias="followUpInstruction")
previous_result: str | None = Field(default=None, alias="previousResult")
model_config = {"populate_by_name": True}
# ── Helpers ───────────────────────────────────────────────────────────────────
def _sse(event: str, data: dict) -> str:
return f"event: {event}\ndata: {json.dumps(data, ensure_ascii=False)}\n\n"
def _extract_chunk_parts(chunk: object) -> tuple[str, str]:
"""Return (thinking_delta, text_delta) from a LangChain streaming chunk."""
thinking = ""
text = ""
content = getattr(chunk, "content", "")
if isinstance(content, str):
text = content
elif isinstance(content, list):
for block in content:
if isinstance(block, str):
text += block
elif isinstance(block, dict):
btype = block.get("type", "")
if btype in ("thinking", "thinking_delta"):
thinking += block.get("thinking", "")
elif btype in ("text", "text_delta"):
text += block.get("text", "")
elif btype == "reasoning":
thinking += block.get("content", "")
# DeepSeek / OpenAI o-series: reasoning in additional_kwargs
if not thinking:
kwargs = getattr(chunk, "additional_kwargs", {}) or {}
r = kwargs.get("reasoning_content") or ""
if isinstance(r, str):
thinking = r
return thinking, text
# ── Endpoint ──────────────────────────────────────────────────────────────────
@router.post(
"/rewrite",
summary="AI Text Rewrite (SSE stream)",
response_class=StreamingResponse,
)
async def rewrite_selection(
body: RewriteRequest,
config: AppConfig = Depends(get_config),
) -> StreamingResponse:
action = body.action if body.action in _ACTION_INSTRUCTIONS else "polish"
instruction = _ACTION_INSTRUCTIONS[action]
if action == "tone" and body.tone and body.tone in _TONE_SUFFIX:
instruction = f"{instruction}\n{_TONE_SUFFIX[body.tone]}"
context_parts: list[str] = []
before = body.surrounding_context.before.strip()
after = body.surrounding_context.after.strip()
if before or after:
context_parts.append("文章上下文(仅供参考,不要改写):")
if before:
context_parts.append(f"[前文] {before[-300:]}")
if after:
context_parts.append(f"[后文] {after[:300]}")
context_parts.append("")
context_block = "\n".join(context_parts)
base_instruction = instruction
if body.custom_instruction:
base_instruction = f"{instruction}\n用户额外要求:{body.custom_instruction}"
user_message = f"{base_instruction}\n\n{context_block}需要改写的文字:\n{body.selection.text}"
if body.follow_up_instruction and body.previous_result:
messages = [
SystemMessage(content=_SYSTEM_PROMPT),
HumanMessage(content=user_message),
AIMessage(content=body.previous_result),
HumanMessage(content=body.follow_up_instruction),
]
else:
messages = [SystemMessage(content=_SYSTEM_PROMPT), HumanMessage(content=user_message)]
# Auto-enable thinking when the selected model supports it
resolved_name = body.model_name or (config.models[0].name if config.models else None)
model_cfg = config.get_model_config(resolved_name) if resolved_name else None
thinking_enabled = bool(model_cfg and getattr(model_cfg, "supports_thinking", False))
async def generate():
try:
model = create_chat_model(name=body.model_name, thinking_enabled=thinking_enabled, app_config=config)
async for chunk in model.astream(messages, config={"run_name": "writing_rewrite"}):
thinking_delta, text_delta = _extract_chunk_parts(chunk)
if thinking_delta:
yield _sse("thinking", {"chunk": thinking_delta})
if text_delta:
yield _sse("text", {"chunk": text_delta})
yield _sse("done", {})
except Exception as e:
logger.exception("writing/rewrite failed: thread=%s action=%s", body.thread_id, action)
yield _sse("error", {"message": str(e)})
return StreamingResponse(
generate(),
media_type="text/event-stream",
headers={"X-Accel-Buffering": "no", "Cache-Control": "no-cache"},
)
@@ -155,6 +155,8 @@ _CONTEXT_CONFIGURABLE_KEYS: frozenset[str] = frozenset(
"reasoning_effort",
"writing_mode",
"writing_artifact_path",
"canvas_artifact_title",
"canvas_artifact_type",
"is_plan_mode",
"subagent_enabled",
"max_concurrent_subagents",
@@ -0,0 +1,67 @@
"""Copy a conversation's LangGraph checkpoint state from one thread to another.
Used by the conversation-sharing feature: redeeming a share link duplicates the
sharer's threads into the redeemer's account. Each duplicated thread needs its
full checkpoint history copied under a fresh ``thread_id``.
The copy goes through the checkpointer's public API (``alist`` / ``aput`` /
``aput_writes``) rather than raw SQL, so it is independent of the checkpoint
table schema and works for every backend (SQLite, Postgres, in-memory).
"""
from __future__ import annotations
import logging
logger = logging.getLogger(__name__)
async def copy_thread_state(checkpointer, src_thread_id: str, dst_thread_id: str) -> bool:
"""Duplicate every checkpoint of ``src_thread_id`` under ``dst_thread_id``.
Returns True when at least one checkpoint was copied, False when the source
thread has no checkpoints (e.g. a thread that was never run).
The destination keeps the source's checkpoint ids — they only need to be
unique within a ``thread_id``, and reusing them preserves the parent chain.
"""
src_config = {"configurable": {"thread_id": src_thread_id}}
# alist yields newest-first; reverse so parents are written before children.
tuples = [t async for t in checkpointer.alist(src_config)]
if not tuples:
return False
copied = 0
for tup in reversed(tuples):
configurable = (tup.config or {}).get("configurable", {})
checkpoint_ns = configurable.get("checkpoint_ns", "") or ""
parent_id = ((tup.parent_config or {}).get("configurable", {}) or {}).get("checkpoint_id")
put_config: dict = {"configurable": {"thread_id": dst_thread_id, "checkpoint_ns": checkpoint_ns}}
if parent_id:
# aput reads the parent checkpoint id from the incoming config.
put_config["configurable"]["checkpoint_id"] = parent_id
new_versions = tup.checkpoint.get("channel_versions", {}) or {}
await checkpointer.aput(put_config, tup.checkpoint, tup.metadata or {}, new_versions)
# pending_writes is a list of (task_id, channel, value); aput_writes
# wants them grouped per task as (channel, value) pairs.
if tup.pending_writes:
by_task: dict[str, list] = {}
for task_id, channel, value in tup.pending_writes:
by_task.setdefault(task_id, []).append((channel, value))
checkpoint_id = tup.checkpoint.get("id")
for task_id, writes in by_task.items():
writes_config = {
"configurable": {
"thread_id": dst_thread_id,
"checkpoint_ns": checkpoint_ns,
"checkpoint_id": checkpoint_id,
}
}
await checkpointer.aput_writes(writes_config, writes, task_id)
copied += 1
logger.info("Copied %d checkpoint(s) from thread %s to %s", copied, src_thread_id, dst_thread_id)
return copied > 0