Index Copy Section

---

自定义官网式首页，内容见 .vitepress/theme/components/YuxiHome.vue

---

Develop Guides/Changelog Copy Section

版本变更记录

本页用于记录各版本发布说明（新增、修复与破坏性变更）。

同一版本的多次功能更新时，应以功能为单位进行更新，比如之前添加了 A 功能的更新，在后续的更新中修复了因 A 功能引入的 bug，那么这个修复说明应该和 A 功能描述放在一起（重新修改表达，而不仅仅是补充），而不是新增一条修复记录，功能更新同理。必须遵守：每一个修改不应超过 200 字，注意高度凝练。

v0.7.2 (current) Copy Chapter

::: warning 升级提醒
1. 升级到 v0.7.2 后，管理员此前创建的 stdio MCP 会被禁用，也无法重新启用。请在详情页迁移为 SSE 或 Streamable HTTP，或直接删除；代码内置的系统 stdio MCP 不受影响。
:::

- 清理测试套件冗余：删除 5 个自证式/假绿/重复覆盖的测试文件（test_hash_utils、test_skills_backend_error_handling、test_graph_router_list、test_agent_sync_e2e、test_viewer_filesystem_e2e），合并约 50 个文件的重复场景与参数转发断言，抽取 eval 与 e2e 共享 helper；净减约 2,900 行测试代码，真实回归覆盖不变。

- 完善 Agent Token 用量统计：state 同时保留近似上下文与主 Agent 模型返回的 Provider usage_metadata，实际用量拆分为最近调用、当前 Run 和线程累计；前端只读取 state，终态 chunk 不传递用量，worker 在 Run 终态时将父线程中 Run ID 匹配的 state 快照写入 AgentRun。支持 OpenAI priority/flex 缓存明细；L2 摘要内部调用暂未计入完整账单口径。
- 对话输入草稿按线程保存：输入内容实时写入 localStorage（按线程 ID 区分），切换对话时保存旧线程草稿并还原新线程草稿，新建对话使用独立草稿、发送创建线程后自动清理，刷新页面后草稿仍可还原，删除对话时同步清理对应草稿。
- 对话消息补充时间信息：历史接口为 assistant 消息附上关联 run 的 started_at/finished_at；复制按钮右侧以纯文本显示消息完成时间，点击切换为执行耗时（如"耗时 5s"）再点切回，无背景色块与时钟图标；时间按相对规则展示（今天 HH:mm、昨天、一周内周几、更早显示日期、跨年补全年份）。流式生成时 loading 旁实时显示已执行时长，loading 指示器去除背景色块并改为轻微呼吸的文字样式。
- 修复 Agent 产物 Word 文件无法预览：查看器文件预览路径（outputs、uploads、沙盒文件）与工作区一致，docx/pptx 先经 LibreOffice 转换为 PDF 再预览，转换失败返回明确错误，不再判定为二进制文件拒绝预览。
- Agent 文件预览的 HTML 预览新增缩放比例调节（默认 90%，范围 60%–150%，步进 10%）：内联、顶部工具栏与全屏预览均提供缩小/放大按钮并实时显示百分比，切换文件时重置为默认比例，预览/源码模式切换仅在预览态显示缩放控件。
- 修复公开图片上传的存储型 XSS 风险：头像与用户图片不再信任客户端 MIME 或文件名后缀，服务端校验真实图片内容且仅接受 PNG、JPEG、WebP、GIF，对象名使用识别出的固定安全后缀，拒绝伪装成图片的 SVG。
- 修复知识库图片公开访问风险：解析产生的知识库图片从 public bucket 迁移到私有 kb-images bucket，新增带知识库读权限校验的后端代理接口按需读取；Markdown 预览对代理图片携带鉴权头加载为 blob URL，未登录或无权限用户无法匿名访问图片，头像/Agent 图标等公开资源不受影响。
- 修复个人 Skill 列表权限解析错误：个人工作区 Skill 不再进入共享配置解析，所有者获得管理权限，其他用户不可访问；同时修正数据库 UTC-naive 时间的序列化，子智能体运行时间不再错误偏移 8 小时。

- 优化知识库文档列表性能：根目录虚拟目录分组改用部分索引（idx_kf_kb_parent_segment 按路径首段聚合），平铺文件筛选与排序用 idx_kf_kb_parent_flat 支撑，避免大知识库全表扫描与 46MB 磁盘排序溢出；文件统计聚合结果增加 10 秒 Redis 短缓存，列表、统计、子目录计数与创建人查询并行执行，前端自动刷新轮询间隔同步调整为 10 秒。36 万文件知识库列表接口耗时由约 1.3s 降至约 300ms。
- 修复 MCP 管理接口可通过 stdio 启动任意本地进程的问题：用户配置仅允许 SSE/Streamable HTTP，运行时拒绝加载历史用户 stdio 记录，系统内置 stdio 的连接参数改为仅由代码维护；前端移除用户 stdio 配置入口，文档补充内置 stdio 的代码添加与验证方式。
- 工作区新增只读历史对话文件入口 agents/chats/{thread_id}，网页以 YYYY-MM-DD-title 显示并按日期标题倒序浏览各 thread 的非空 uploads 与 outputs；空目录、无文件对话及 large_tool_results、conversation_history 等内部中间产物不展示。该目录由 API 虚拟映射，不创建符号链接或复制文件，也不进入当前会话 viewer 与 sandbox 挂载，避免 Agent 读取其他会话历史。面包屑中该目录固定显示为"历史对话"与目录列表一致，多选过滤改用只读路径集合避免逐项查找。
- 收窄知识库状态边界：读取模型统一收口至 read_models.py；创建、列表、详情与更新由 Manager 统一返回 KnowledgeBaseSummary/Detail，Router 只转换 HTTP 响应；Manager 协调查询配置、主记录与聚合统计，Repository 在行锁内合并统计投影；executor 接收 frozen KnowledgeBaseConfig，负责类型资源、文档操作与类型专属一致性检测，不再写知识库主记录。
- 修复 Agent worker 知识库运行配置不一致：get_kb_config 从 Redis 读取最小 Config 快照，未命中时在 KB 级分布式锁内回源 PostgreSQL，Redis 连接故障时只读请求直接回源且不回填；更新与删除先可靠失效缓存再提交数据库，避免旧请求回填过期配置。查询参数在数据库行锁内合并，并发保存不再互相覆盖。
- 精简知识库文档内容接口响应：GET /api/knowledge/databases/{kb_id}/documents/{doc_id}/content 不再返回分块内部的实体 ID 与抽取结果，避免向文档预览请求传输仅供知识图谱构建使用的数据。
- 清理未使用的共享访问级别常量模块，移除 Agent、Skill 与知识库中的冗余导入和别名；共享范围校验继续由统一权限模块负责。
- 统一 Agent、Skill 与知识库共享权限：配置拆分读取/管理范围并统一解析 none/read/manage；启动时将旧 share_config 幂等迁移为 v2 且只回填只读范围、不追溯授予管理权，运行时代码仅接受 v2；创建者与超管保留管理权。非管理员创建或编辑 Agent 时共享范围与 Skill 一致收敛为仅个人可见，避免越权扩大到部门或全局；共享 Skill 仅管理员可安装，普通用户固定安装到个人工作区。知识库路由统一按 READ/MANAGE ACL 校验，配置弹窗按基础信息、权限、检索分栏，非检索保存不再覆盖检索参数，编辑表单不再残留已移除的“自动生成问题”开关；用户编辑不允许修改角色身份。同步修复 Agent/Skill share_config 列实际类型为 json 而非预期 jsonb 导致迁移语句报错、后端无法启动的问题。
- 收敛消息型 AgentRun 提交：Web Chat 与 Agent Call/Eval 共用 run_submission_service.submit_run_command，Call/Eval 拆为独立 Router；Request/Run 固化 source/channel/external_id/origin_metadata 来源快照，Eval 评估上下文继续透传到 worker 与 Langfuse，保留现有接口与响应兼容性，Resume、Subagent 生命周期不变。
- 新增个人工作区 Skill：安装确认可选择个人或共享位置；个人 Skill 保存到 workspace/agents/skills 且不入库，元数据按用户缓存 5 分钟并在安装、删除、手动刷新后立即更新；Card List 与 Agent 运行时统一按个人版本覆盖同名共享版本，卡片与聊天技能选择列表共用 slug 到 Lucide 图标映射；Agent 直接读取工作区真实路径，不再复制到线程 /home/gem/skills 投影；共享 Skill 投影统一以来源映射为单一数据源。
- 统一后端真实路径根目录校验：Skill、工作区和沙盒复用 ensure_within_root，保持原有越界拒绝语义并减少重复安全判断。
- 统一前端单元测试目录为 web/test/unit，测试脚本仅收集该目录；测试规范同步说明主应用与独立 CLI 包的目录约定，避免同一子项目混用 test 和 tests。
- Skill 推荐区升级为套件卡片，首批提供 Anthropic 文档处理套件；统一选择、短时加载、生效范围和结果四步弹窗，远程仓库与全局搜索保持在同一弹窗，选择页标签居中并以桌面三列网格展示，技能列表支持纵向滚动；确认页支持移除、范围摘要及失败草稿清理；公共扩展卡片采用紧凑 gray 样式；上传入口共用普通请求流程，支持部分失败与重试。
- 远程 Skill 来源策略迁移到 PostgreSQL，并在「基本设置」提供精确域名白名单配置；默认允许 GitHub 与 ModelScope，空列表会关闭远程安装。远程 Skill CLI 改用无环境凭据的一次性 Sandbox，删除失败时也清理一次性连接缓存；Kubernetes 不挂载 ServiceAccount token；数据回流严格校验相对路径并限制文件数、目录深度和总大小，同时统一命令与 HTTP 超时，修复 #895 并缩小 #855 的风险面。
- 新增 PDF 解析前置页树校验：PDF 进入 PyPDFLoader、MinerU 或 OCR 引擎前会用 PyMuPDF 逐页加载页槽，提前识别加密、空文档、null 页槽和非 Page 对象等结构异常，并返回可操作的中文错误，避免解析服务内层延迟失败。
- 修复真实 API 测试资源清理：integration 与 E2E 会在测试会话前后通过公开接口删除名称以 pytest（兼容旧 py_test）开头的评估基准、评估运行和知识库，并删除带显式 E2E 标记的对话、临时智能体及独立沙盒目录；知识库删除改用列表真实返回的 kb_id，清理失败会明确中止测试，避免测试数据污染最近对话或长期残留。
- CLI 新增 yuxi chat 本地网页调试入口：临时服务仅监听 127.0.0.1，使用本地保存的 remote 与 API Key 代理 Agent Call 和 Run SSE，浏览器可连续对话并实时显示文本增量；API Key 不进入页面，支持指定智能体、remote 及仅打印地址。
- 新增纯文本 Channel 入口：/api/agent-invocation/channel/messages 统一接收 CLI/未来 IM 消息，普通文本复用 submit_run_command 并默认使用 steer，首版支持 /state 查询线程状态与 /approve 恢复工具审批；yuxi chat 已切换到该入口，并将工具审批中断显示为等待 /approve 的正常状态，页面采用无侧边栏的微信 PC 对话布局与色块头像，暂不处理 ask_user_question。同步修复测试模块重名、Subagent Run 来源快照错误，并在 HTTP 与共享提交边界拒绝超长来源字段。
- 优化知识图谱构建：以持续队列并发执行 LLM 抽取、结构写入和向量索引，失败自动重试并持久化进度；已有结果支持断点恢复，新增按最近 Chunk 查询失败样例和向量 reconcile 接口，任务与前端分别展示抽取、结构、向量进度，索引面板支持键盘操作。
- HTML 辅助可视化迁移为内置 html-preview Skill：默认 Chatbot Prompt 不再常驻注入 html:preview 专属说明，Agent 改为通过统一的 Skill 描述发现并按需读取静态 HTML/CSS 的适用场景、布局和安全边界；未显式配置 Skills 的 Agent 按现有默认规则自动获得该能力，使用显式 Skills 允许列表的 Agent 需选择 html-preview，内置 deep-research 已声明依赖；保留前端既有围栏清洗、sandboxed iframe、自适应高度和流式占位行为，普通 HTML 源码继续使用 html 代码块。
- 模型供应商的单个 chat 模型配置新增“模型请求参数 JSON”：管理员可为每个模型独立保存、回显、修改和清空思考参数，未配置或空对象保持原行为；运行时模型缓存会携带该配置，测试模型连接与正式聊天/Agent 调用统一在模型加载入口合并。该字段仅面向 OpenAI/OpenRouter 等 OpenAI 兼容供应商，并通过 extra_body 透传；出于安全考虑，顶层字段采用白名单机制，当前支持 enable_thinking、thinking_budget、thinking、reasoning 和 reasoning_effort，对象内部结构交由供应商校验。
- 新增通用管理员配置 Options 模块：系统运行时配置迁移到 PostgreSQL，API 与 worker 通过带版本失效的 Redis 短缓存共享最新值，Redis 故障时回源数据库；旧 base.toml 只补充缺失字段且读取失败后可重试。LangGraph checkpoint 默认使用 PostgreSQL，跨进程串行初始化且异常解锁时销毁持锁连接；附件正式文件迁移到 MinIO，本地按需缓存，Run 在提交数据库快照后恢复附件，避免重复查询和长事务。
- 修复部署配置：开发与生产 Compose 中的 Milvus 现在复用对应环境文件里的自定义 MinIO 凭据，避免对象存储认证失败导致服务无法健康启动；Web 生产镜像会统一将静态资源目录设为 755、文件设为 644，避免 Nginx 因构建产物权限过严返回 403。
- 丰富模型选型参考信息：接入 @opencode-ai/models 内置 snapshot，补充模型上下文、能力和价格等信息；模型选择器移除价格悬浮提示并关闭搜索自动完成，底部增加“配置模型”入口；模型供应商候选列表支持美元与人民币价格切换，默认美元，人民币按固定汇率 1 USD = ¥7 换算，并明确 models.dev 数据与固定汇率仅供参考；候选模型工具栏统一靠右排列搜索、币种和类型筛选控件，类型文案改为“对话 / 向量 / 重排”。DashScope 中国站内置标识修正为 alibaba-cn，alibaba 改为使用 dashscope-intl.aliyuncs.com 的国际站定义。
- 优化 Agent 会话与设置页多项交互细节：修复文件侧栏重新展开丢失预览、审批模式改为本地记忆最近选择、下拉面板点击外部区域自动收起、输入框添加内容入口改为 + 并可直接引用知识库与 Skill、Skill 图标统一为 Lucide WandSparkles、账户设置合并 Memory 开关等；侧栏导航“智能体管理”简化为“智能体”，路由由 /model-manage 重命名为 /agent-manage；智能体卡片增加共享范围标签，并将“去对话”调整为紧凑文字入口；文件预览标签的关闭按钮补充紧凑圆角悬浮、按下和键盘聚焦状态；同步优化首页首屏视觉细节。
- 新增 Agent backend 工具审批与完全信任模式：Agent 配置可定义默认模式，聊天 run、Agent Call 与评估请求可用 tool_approval_mode 做单次覆盖，实际模式固化到 AgentRun 并由 resume/子智能体继承；默认审批仅拦截 write_file、edit_file、execute，只读 filesystem 工具直接执行，完全信任保持自动执行。前端输入框左下角新增线程级“请求审批 / 完全信任”选择器，支持刷新恢复显式选择；智能体配置页将带选项的 string 字段正确渲染为选择控件，模式解析按“线程显式选择、智能体显式配置、本地最近选择、系统默认值”依次回退，避免本地缓存覆盖智能体配置。同轮多个工具调用按顺序一次展示一项，参数默认只显示单行摘要，点击后带轻量动画在卡片内展开完整内容，展开区最大高度为 300px。审批卡进一步调整为直接覆盖输入区，按工具类型优先展示命令或目标路径，操作固定为“拒绝 / 允许”，审批期间底层输入控件不可交互。默认模式下子智能体隐藏敏感 backend 工具，避免绕过主线程审批。补充模式解析、middleware、run 继承、事件压缩、子智能体过滤、前端状态恢复测试，并在真实页面验证刷新恢复、逐项批准或拒绝、参数点击展开与完全信任自动执行。模式解析合并为单次 context 共享（resolve_agent_run_config）避免 run 创建/intake 重复加载上下文；resume 与子智能体继承统一读取固化快照，前端审批弹窗参数序列化改为 computed，并清理 reviewConfigs 等未消费状态。resume 解析 tool_approval_mode 时对旧版本固化、缺少该字段的 interrupted 运行回退默认值而非报错，避免历史中断会话升级后无法恢复。
- 新增智能体请求队列（Phase 1/2/Steer）：同一线程运行中提交的新请求默认持久化排队，并按 FIFO 顺序自动执行；新消息或已有排队项也可设为 Steer，在当前步骤结束后的下一次模型调用前停止旧 Graph，再复用 completed 接力优先执行。支持实时查看排队位置、单条取消和刷新恢复，也可通过 reject 策略保持“不能立即执行就拒绝”。聊天、Agent Call 和评估统一接入该队列，前端会分开展示排队请求与当前回复，并修复连续请求交接时的流状态和消息顺序问题；排队请求区域改为紧贴输入框的附属列表，移除冗余标题与表格式分割线，保留顺序和删除操作但弱化次要信息。同步 Agent Call 遇到忙线程时会直接返回拒绝结果，不再因缺少 run_id 进入等待逻辑并返回 500。failed/cancelled 时已有积压请求会明确进入暂停状态，用户可手动继续 FIFO 队头；队列为空后的新请求可正常执行。interrupted 必须先完成 resume，前端会禁用普通消息发送，后端也会在持久化 Message/Request 前返回 run_interrupted 冲突，不能被继续动作或绕过前端的请求破坏恢复顺序；completed 自动接力的故障窗口会在 worker 重试和启动恢复时补齐。Phase 2.1 进一步使用 Conversation 行锁串行化 intake、resume、continue 和自动接力，保证并发 enqueue 仍严格遵守 FIFO；pending AgentRun 作为持久化投递意图，completed job 重试和 worker startup 会优先重新投递已有 run，不再依赖重启修复提交后 ARQ 投递失败；终态写入增加单赢家语义，后到的 cancelled/failed/completed 不再造成 AgentRun、Message 与 SSE 状态分裂；request_id 幂等绑定 uid、agent、thread、source 和 queue policy，跨作用域复用返回结构化冲突。并发 reject 现在会在锁定 FIFO 队头后确认当前请求确实能够立即派发，竞争失败的请求原子转为 rejected；终态 run 缺少 finished_at 时显式暴露数据不变量，实时进入 interrupted 后也会立即刷新队列提示。Request SSE 恢复时会复用已有连接，开发容器也会在有长连接时按时完成热重载。审批中断改为在消息和 Agent 状态写入事件流后再发布中断终态，resume 时保留排队 Request SSE；交付物按 present_artifacts 所在对话渲染，避免连续审批必须刷新和后续消息错位。Steer 增加无工具模型轮次的 aafter_model 兜底检查，含工具调用时仍等待完整批次，并由 worker 接力和启动恢复保证持久化意图不丢失。新增《Agent 请求队列与调度设计》文档，说明调度目标、策略、状态、异常处理和当前范围。补充队列、取消、暂停恢复、消息排序、流交接及接口测试。
普通发送遇到 run_interrupted 冲突时会从 checkpoint 重载中断载荷、恢复审批框，并回填后端未持久化的文本与图片草稿；恢复过程按线程和请求版本隔离，避免旧请求污染当前草稿或重新显示已处理的审批，状态读取失败时明确提示刷新重试。
- 知识库列表直接读取 PostgreSQL 中的概览和持久化统计，不再为展示卡片同步初始化 Milvus 等知识库实例，避免首次进入知识库页面时卡片长时间不可点击。
- 新增知识库 external API 与 yuxi kb 查询类命令：后端在 /api/knowledge/databases/external/* 下暴露列库、文件搜索、检索、打开和文件内查找接口，统一走认证身份校验；CLI 新增 yuxi kb list/files/query/open/find，补充后端 external API 集成测试与 CLI client/命令测试。管理端同步新增 GET /api/knowledge/databases/{kb_id}/documents/search，复用底层文件名搜索能力供前端调用；知识库详情页工具栏新增「搜索文件」按钮，打开命令面板式弹窗（与历史对话搜索弹窗同风格），输入关键词按文件名搜索并在结果列表展示状态/大小/更新时间，placeholder 明确标注仅匹配文件名、不搜索文件内容，点击结果可直接打开文件详情。搜索请求增加序号校验，连续回车与快速重搜时丢弃过期响应，避免后发先至覆盖当前关键词结果。文件名搜索改为数据库侧按 filename/status 过滤、updated_at desc 排序与 count 统计，避免大知识库超过仓储单页上限时静默漏结果；管理端搜索先做当前用户可见性校验再判断文档能力，external open/find 统一清晰处理只读源与预期参数错误；CLI 查询结果从 metadata.score 读取并展示检索得分。
- 新增 download_kb_file 知识库工具：通过 file_id 调用 knowledge_base.get_file_download(variant="original") 从 MinIO 拉取原始二进制（pdf/docx/xlsx 等），落盘到沙盒 outputs 目录并返回沙盒内可见的虚拟路径，供后续代码工具以文件对象方式读取（openpyxl.load_workbook、pdfplumber.open 等），弥补 query_kb/open_kb_document 只返回文本切片、丢失原始文件结构的不足。复用会话可见知识库校验与 ocr_parse_file 的落盘范式，支持 save_as 指定文件名（剥离目录防穿越，重名追加 _N 后缀），工具只搬运不解析、不自动登记交付物。工具已登记到 knowledge-base 内置 Skill 的 tool_dependencies，并在 SKILL.md 可用工具段补充说明；只读源拦截下沉到 manager.get_file_download 内部，与 open_document/find_in_document 落点一致，工具/router/CLI 所有调用方统一获得 dify 等只读检索源的拦截；返回的 size_bytes 与落盘统一用下标访问 data["content"]，避免回退掩盖契约异常。
- 内置网页搜索工具新增豆包联网搜索支持：新增 WEB_SEARCH_PROVIDER（doubao/tavily）与 DOUBAO_SEARCH_API_KEY 配置，未显式指定时按已配置的 API Key 自动识别 provider；两种 provider 统一注册为工具名 web_search，deep-research Skill 依赖同步从 tavily_search 改为 web_search。
- 只读用户知识库开放图谱与知识导图查看：非管理权限用户也能打开“知识图谱”“知识导图”页签查看已构建内容，但隐藏配置抽取器、开始索引、生成/重新生成/增量更新等写操作；空状态提示改为等待管理员构建。
- 模型供应商编辑表单优化：API Key 密码框关闭浏览器自动填充识别，避免被误判为登录用户名/密码；供应商处于停用状态时，保存按钮拆分为“仅保存”与“保存并启用”，后者保存后自动启用，避免漏开启。
- 新增内置模型供应商 OpenCode Go（opencode-go），Base URL 与模型发现地址指向 https://opencode.ai/zen/go/v1，配置方式与 OpenCode 一致。
- 模型供应商列表优化：卡片移除右下角启用/禁用开关，供应商按启用状态拆分为「已启用 / 未启用」两组展示；已启用供应商保留 Base URL、能力与「管理模型」入口，未启用供应商只展示图标与名称的小卡片，不再展示 Base URL 与管理模型按钮。
- 知识库卡片补充共享权限标签：参考 Skill / 智能体卡片，在现有类型与嵌入模型标签之外新增共享范围标签（如「只读全局」），与 Agent 卡片保持一致的灰色样式。
- 收敛 Ruff CI 行为：Pull Request 与 push 到 main 均只检查、不修改仓库内容，发现问题直接标红并提示本地运行 make format；工作流仅保留 contents: read 权限，不再自动提交或创建修复 PR。
- 优化知识库详情页自动轮询：轮询从固定 1s setInterval 改为链式调度，等上一轮知识库信息与文件列表请求全部返回后再排下一轮，慢接口下不再出现请求堆积重叠；全库 processing_count 持续不变时按退避因子拉长间隔（上限 30s），连续多轮无进展即自动停止轮询；离开详情页时 onUnmounted 主动清理定时器。
- 统一工具调用展示名称映射：知识库工具显示名改为后端 display_name 定义，前端拉取完整工具元数据；工具卡片与折叠摘要按「工具列表 display name → middleware 兜底映射 → 工具 id」统一展示。
- 侧边栏对话列表新增 Thread 运行状态：以 AgentRun 为事实来源，后端把每个线程最新顶层 chat/resume Run 聚合成 thread_status（进行中显示 loading、已终态未查看显示 ready 点、已查看或无 Run 为 done），列表接口一次窗口查询完成聚合、不逐项请求；Conversation 新增 last_viewed_run_id 持久化查看边界，POST /api/chat/thread/{id}/viewed 幂等标记已读。前端打开线程、当前线程收到终态/中断事件时自动标记已读，发送或恢复 Run 时置为 loading，侧边栏可见时低频轮询刷新后台线程状态；历史线程上线时按各自最新顶层 Run 一次性回填为已读，新建线程写入未读哨兵避免回填误清新产生的未读点。
- 修复 Thread 运行状态两个正确性问题：终态/中断事件仅在事件线程等于当前打开线程时才自动标记已读，后台线程完成保留 ready 点直至用户打开；无 chat/resume Run 的历史会话（agent_call / agent_evaluation 调用、从未对话过的线程）在回填时写入未读哨兵，使回填探测条件收敛为 false，避免每次启动都重复对 agent_runs 做全表聚合。
- 优化侧边栏对话列表操作渐隐：.actions-mask 三态（默认/悬浮/激活）渐隐统一为线性延伸至操作按钮左边缘（距右缘 28px）再转为实色，修复悬浮时渐隐铺满整条遮罩导致按钮下方文字残留鬼影、以及三处渐隐宽度不一致的问题。

v0.7.1 (2026-07-17) Copy Chapter

安全 Copy Section

- 生产 Compose 不再回退到公开的 Neo4j、MinIO 和 PostgreSQL 默认凭证，并要求显式配置 JWT 随机密钥与实例标识；相关配置缺失时会在解析阶段拒绝启动并提示具体变量名。管理员初始化、创建用户、创建部门管理员及修改用户密码在前后端统一要求密码不少于 8 位。
- 修复沙箱执行边界：每个动态 Docker 沙箱使用只与 provisioner 相连的独立网络，沙箱之间不能互访，也不再加入业务 app-network 或发布随机宿主机端口；provisioner 重启后会重新接入已有沙箱网络，清理时只删除自身创建且标签匹配的网络。API/worker 使用至少 32 字符的 SANDBOX_PROVISIONER_TOKEN 调用 provisioner，并通过认证代理访问沙箱文件与命令接口，代理在应用生命周期内复用 HTTP 连接池。生产 Compose 同时移除 PostgreSQL 和解析服务的宿主机端口，阻断沙箱对其他租户、业务数据库、对象存储和无鉴权 provisioner 的横向访问。
- 公开头像和 Agent 图片改用同源 /minio/public/... 地址，由开发 Vite 和生产 Nginx 只读代理 public bucket；MinIO 9000 对象 API 与 9001 管理控制台无需对外开放，私有 bucket 不进入前端代理。
- Markdown 渲染兼容历史 PDF 解析结果中的 http(s)://<host>:9000/public/... 图片链接，在展示时转换为同源 /minio/public/...，无需批量重写 MinIO 中已有的 .md 文件或重新解析文档。

破坏性变更 Copy Section

- 沙箱 provisioner 现在强制要求 SANDBOX_PROVISIONER_TOKEN。升级前运行初始化脚本自动补生成，或手工使用 openssl rand -hex 32 生成并写入 .env / .env.prod；API、worker、provisioner 必须使用同一个值，但不能把它写入 sandbox.env。已有动态沙箱会因网络不匹配被 provisioner 删除并按新网络重建。
- API Key 收紧到具体用户：api_keys.user_id 收紧为非空，启动 schema 演进会先清理 cli_auth_sessions 中对未绑定 API Key 的引用，再 DELETE FROM api_keys WHERE user_id IS NULL，最后 ALTER COLUMN user_id SET NOT NULL。升级前请在 0.7.0 库执行 SELECT id, name, department_id FROM api_keys WHERE user_id IS NULL;，决定每个未绑定 Key 的归属用户并手动 UPDATE，未绑定的 Key 升级后会被静默删除且无法恢复；清理前后端日志会输出 Schema migration will delete N unbound API key(s) 告警以便回溯。
- Dashboard 收紧到 superadmin：所有 /api/dashboard/* 端点从 get_admin_user 收紧为 get_superadmin_user，前端路由同步收紧。0.7.0 中创建过 role='admin'（非 superadmin）的运维用户升级后将失去 Dashboard 访问权限，且应用内无自助提权路径；升级前请在数据库中将需要继续访问 Dashboard 的 admin 用户 UPDATE users SET role='superadmin' WHERE uid=...。首装场景的首个管理员始终是 superadmin，新部署不受影响。
- CORS 生产环境默认拒绝跨域：CORS 改为通过 YUXI_CORS_ORIGINS 显式配置允许来源；YUXI_ENV=production 且未设置该变量时返回空列表（拒绝所有跨域），显式设为 * 时会自动关闭 credentials。前后端跨域部署的运维请在升级前设置 YUXI_CORS_ORIGINS=https://your-frontend.example.com，否则浏览器跨域请求将被拒绝；同源部署（前端与 API 同源）不需要额外配置。
- 系统配置接口权限下放：GET /api/system/config 由 admin 收紧到任意登录用户可读，便于普通用户读取 default_ocr_engine 等运行时配置；接口会暴露 sandbox_provisioner_url、sandbox_virtual_path_prefix、默认模型 ID 等基础设施信息（不包含任何密钥/Token），如有更高保密要求请通过反向代理限制该路径。

开发记录 Copy Section

- 修复 Milvus 知识图谱子图查询忽略 max_depth 的问题：查询会按请求深度展开路径，并完整返回路径中的中间节点与关系；排除 Chunk 时同时限制整条路径，避免通过 Chunk 间接扩展。路径结果继续遵循现有节点和边数量上限。

- 修复线程文件接口的同步文件 I/O 阻塞：交付物预览仅异步读取媒体类型识别所需的 512 字节文件头，不再同步加载完整文件；线程文件全文读取和目录扫描下沉到工作线程，避免大文件或大目录并发访问时阻塞 API 事件循环。
- 修复应用 lifespan 关闭时未释放共享 Neo4j driver 的问题，避免同进程重载或重复启动后残留图数据库连接。
- 修复删除 Milvus 知识库阻塞事件循环：MilvusKB.delete_database 恢复异步基类契约，并将同步的主集合与图集合清理下沉到工作线程，避免删除期间阻塞其他对话和 SSE 推送。
- 修复 Agent 对话流式输出时的前端性能问题：自动滚动改为监听 conversations computed 的顶层引用变化，不再对完整对话与消息树执行深度 watch，避免每个 token 到达时递归遍历全部历史消息。
- 修复删除知识库文件图谱时清理范围过宽：Neo4j 仅删除本次文件 MENTIONS 边触及且已无任何 MENTIONS 引用的实体，不再顺带删除同知识库内其他文件遗留的孤儿实体。
- 对照当前解析器、知识库工具和 Agent 运行链路重整正式文档：补充默认 OCR、文件级处理参数、工作区 AGENTS.md / USER.md / MEMORY.md、知识库 knowledge-base Skill、search_file、ocr_parse_file、子智能体进度和图片 OCR 回退语义；更正知识库工具使用 kb_id、MCP 配置按数据库实时读取等过时描述；移除正式文档中的问答式栏目。
- 统一用户菜单的设置入口：管理员与普通用户均显示“设置”，打开后默认进入账户设置；管理员专属的基本设置、用户管理等标签继续按原权限展示。
- 工作区 agents 目录新增 USER.md 与 MEMORY.md 上下文文件，并与 AGENTS.md 一起在 Agent 运行开始时加载；三个默认文件首次创建时均写入对应标题和说明，不再生成空文件，已有内容保持不变。
- 新增 Summary 上下文压缩实时状态流式同步：YuxiSummarizationMiddleware 触发压缩时通过 langgraph.config.get_stream_writer() 推送 yuxi.context_compression 自定义事件（started/completed/failed），复用 DeepAgents 已有 _summarization_event 作为完成数据源；base.py 通过 astream_events(version="v3") 的 CustomTransformer 透传 custom 流，chat_service/agent_run_service 将事件映射为 context_compression chunk 并透传到前端；前端收到 started 时将"正在生成回复"加载态文案切换为"正在压缩上下文"，压缩结束（completed/finished）即切回，不额外渲染分隔符、不保留压缩完成态。为避免摘要 LLM 调用的 token 流被 LangGraph messages stream 捕获并广播成 phantom 摘要消息，重写 _create_summary/_acreate_summary 在摘要模型 invoke 的 config 上挂 TAG_NOSTREAM，让流式层在源头跳过该调用，主 messages 流天然只含用户可见回复，无需 chat_service 下游过滤（参考 DeerFlow 实现）。异步 L2 压缩路径的 _aoffload_to_backend 与 _acreate_summary 改回 asyncio.gather 并发执行，与 DeepAgents 父类一致，避免串行等待一次文件 I/O 与一次摘要 LLM 调用；两路复用 _SUMMARY_SANITIZED_MESSAGES 的 id 缓存。L1-only 调用若仍触发 provider context overflow，会回落到 L2 summary 后重试；summary_tool_result_token_limit 默认改为 300，并同时作为 L1 工具结果 offload 阈值和预览上限，L2 只消费 L1 视图，不再对工具结果做第二轮 offload；L2 摘要模型的待摘要历史输入上限改为与 summary_threshold 对齐，避免固定 4000 token 裁剪丢失早期历史；新增 summary_l2_trigger_ratio 管理 L1 后进入 L2 的比例阈值，默认 0.4。

- 知识库文件列表新增文件级 Token 内容量与创建人头像、用户名展示，内容量悬浮可查看 Chunk 数量；创建人复用全局用户头像解析规则，长用户名省略且悬浮可查看完整名称。
- 知识库编辑配置表单移除“自动生成问题”开关，不再由前端编辑或提交该配置。
- 知识库详情页新增整页内容加载态：切换或首次进入详情时，在知识库信息返回前仅展示居中 loading，避免标题、标签页和文件区域先渲染旧数据或空状态。
- 修复知识库文件处理中频繁刷新时，旧目录请求覆盖当前子目录列表并造成列表抖动的问题。
- InfoCard 新增统一的 card-more-action-corner 菜单插槽，并在组件内部固定渲染横向三点按钮；更多操作从卡片绝对定位改为进入 header 的正常 flex 布局，与图标、标题和 status 共享同一垂直中心线，业务页面只能提供菜单内容；智能体、知识库和用户管理卡片均改为复用该组件与菜单能力，用户部门/角色标签使用现有 status 插槽展示在标题区右侧，菜单图标与文字使用统一行高居中，知识库菜单支持复制 ID、直接打开编辑弹窗，以及确认后删除并刷新列表。
- 智能体管理页的普通智能体卡片新增“去对话”入口，点击后进入新建对话并预选对应智能体；子智能体卡片不展示该入口。
- 修复 API/Worker Docker 镜像构建失败：后端项目要求 Python >=3.12,<3.14，Dockerfile 基础镜像与 .python-version 同步到 python:3.13-slim，并将 docker/api.Dockerfile 的 COPY 源路径改为相对仓库根目录的 backend/...，与 docker-compose 中 build.context: . 保持一致；同时移除 uv sync 对 BuildKit --mount 的依赖并启用 --no-cache，避免分别因 Python 版本不兼容、../backend/... 越出 build context、未启用 BuildKit 或 uv 缓存残留导致镜像构建失败或体积膨胀。
- 新增用户级配置：保留现有全局配置链路不变，新增 user_config 表、UserConfigSchema 与无缓存的 UserConfig PostgreSQL 读取/保存入口；新增 /api/user/config，所有登录用户可读写自己的配置。首个字段为 enable_memory（是否启用 Memory），作为预留开关仅持久化与展示，不接入运行逻辑；设置弹窗新增“用户配置” Tab 展示并保存该开关。
- 优化 Skills 管理页展示文案：补充推荐 Skills 与内置 mysql-reporter 的卡片描述，避免短描述在两行卡片布局下显得过空。
- 新增 PaddleOCR 云端 API OCR 解析器：支持 paddleocr_vl_1_6 调用 PaddleOCR-VL-1.6 输出版面 Markdown，支持 paddleocr_pp_ocrv6 调用 PP-OCRv6 输出纯 OCR 文本；解析器复用 PaddleOCR jobs 提交、轮询与 JSONL 下载逻辑，健康检查仅校验 PADDLEOCR_API_TOKEN 配置状态，不创建真实 OCR 任务；知识库上传与临时附件解析弹窗同步增加两个 OCR 选项。
- 优化对话消息代码块交互：助手消息中的 Markdown 代码块右上角新增简约复制按钮，支持点击快速复制代码内容并显示短暂“已复制”反馈。
- 新增 Markdown html:preview 辅助可视化预览：仅显式标记的围栏会渲染为 sandboxed iframe，普通 html 继续展示源码；预览使用清洗后的静态 HTML/CSS srcdoc，按内容自适应高度并最高限制为 700px，超高时保留 iframe 内滚动，流式输出期间复用预览节点避免闪烁；内置 Agent Prompt 同步约束 Markdown 仍为回答主体，HTML 只补齐指标、对比、时间线、关系结构等可视化短板，不承载大段叙事、完整报告或正文解释。
- 新增历史对话搜索：侧边栏增加“搜索对话”入口，打开命令面板式弹窗，支持默认最近对话、新对话入口、搜索中骨架屏、结果列表、方向键选择与 Enter 跳转；后端新增 /api/chat/threads/search，按当前用户 active 对话中的非工具消息 content 检索并按对话聚合返回命中片段，同时将侧边栏导航项高度统一调整为 32px。
- 模型供应商管理前端开放 Anthropic provider type：Provider Type 下拉仅保留 OpenAI Completions API 与 Anthropic Messages API 两种可选项，保存值继续使用后端枚举，并在供应商卡片中展示友好类型名称。
- 优化 Agent 状态面板子智能体弹窗：弹窗消息列表复用对话消息渲染路径，打开运行中的子智能体时会展示主 run SSE 已路由到 child thread 的流式消息，并在生成中保持与主对话一致的处理态；修复当前 run 的历史半成品消息与 ongoing 流式片段叠加导致同一个子智能体在主对话中重复展示的问题，子智能体状态查询工具不再渲染成独立 Agent 卡片，弹窗会随子智能体条目补齐 run_id 后订阅对应 SSE，并复用主对话的流式平滑输出与底部跟随滚动控制；已完成的子智能体改为直接读取持久化 Message 历史，不再从 Redis run event 重放渲染。
- 增强异步子智能体 subagent_status：状态查询会从子 run 的 Redis 事件流反向提取最近 3 条可读进度摘要，并在工具卡中优先展示，终态结果读取语义保持不变；同时移除模型侧 subagent_events 工具，Redis 原始事件流继续仅供运行基础设施与前端 SSE 使用，避免包含重复 metadata、query 与嵌套 payload 的事件信封进入模型上下文并被写入 large_tool_results。
- 优化任务中心（Tasker）定位为「后台作业实体 + 只读进度面板」。前端修正失效的任务类型标签、状态判断收敛、任务详情补充参数/结果，并把轮询收敛到 store 修复抽屉关闭后角标不更新；取消操作提交后提示“取消请求已提交”，不再将请求受理误报为任务已取消。后端 TaskContext 暴露 payload 消除私有穿透，进度更新按增量节流降低写放大，新增终态任务保留上限自动裁剪内存与数据库，_load_state 恢复历史任务使任务中心重启后仍可见。修复运行中任务关闭时 shutdown() 持有状态锁等待 worker、worker 又等待同一锁写入取消状态形成的死锁；生命周期操作改用独立锁串行化，等待 worker 前释放状态锁，并区分服务关闭取消与任务协作式取消，确保关闭能够完成且普通任务取消不会损失 worker。后台任务增加默认 6 小时且可通过 TASKER_DEFAULT_TIMEOUT_SECONDS 调整的执行上限，入队时可按单任务覆盖；超时会取消并等待业务协程清理后释放 worker，知识库文件与评估任务同步退出“处理中”状态。
- 知识库访问能力迁移为内置 Skill：新增 knowledge-base Skill，绑定 list_kbs、query_kb、find_kb_document、open_kb_document、get_mindmap 等知识库工具；内置 Agent 不再默认挂载知识库工具，改为读取并激活 Skill 后按需加载，同时保留 knowledges 作为知识库资源范围与权限边界。Agent 配置页在启用知识库但显式未选择 knowledge-base Skill 时实时展示提示，保存时不阻断。修复 Skill 依赖工具的可执行性：create_agent 中「模型可见工具」与「ToolNode 可执行工具」是两套，仅靠 awrap_model_call 动态追加工具只会绑定给模型、不进 ToolNode，导致激活 Skill 后调用 list_kbs/query_kb 报 not a valid tool；现由 resolve_configured_runtime_tools 统一把所有可见 Skill 依赖的本地工具随基础工具一起注册进 ToolNode（可执行），SkillsMiddleware 运行期再按 Skill 激活状态门控模型可见性（保持按需加载）。新增 search_file 工具支持按文件名关键词跨/指定知识库搜索文件，并已加入 knowledge-base Skill 的依赖工具；其分页统计基于全量扫描结果计算 total/has_more，避免按 limit+offset 截断导致计数失真。
- 增强知识库工具结果豁免：open_kb_document 工具结果加入 Summary 卸载豁免名单，避免大文档窗口被摘要后丢失上下文。
- 新增 Yuxi Python CLI 首版底座：新增独立 packages/yuxi-cli 包，提供 remote add/use/list/ping、login --browser、login --api-key、whoami、status、logout；配置统一写入 ~/.yuxi/config.toml，remote URL 只保留实例入口并派生 /api 请求路径。后端新增 /api/auth/cli/sessions device flow 授权接口与 cli_auth_sessions 持久表，浏览器确认后为当前用户创建一次性返回的 API Key；新增公开 /api/system/discovery 声明服务端版本、API 前缀、CLI 能力和关键端点，CLI 登录前校验服务端版本至少为 0.7.1（0.7.1.dev* 按 release tuple 兼容）及对应能力；前端新增 /auth/cli/authorize 授权确认页。补充 CLI 本地单测与后端服务/路由单测。
- 安全与健壮性加固：token 兑换接口改为 POST /api/auth/cli/sessions/token，device_code 改走请求体，避免凭据出现在访问日志的 URL 路径中；兑换与批准会话时对会话行加 with_for_update 行锁，防止并发/重试导致重复签发 API Key；CLI 浏览器登录轮询区分瞬时错误（网络层错误、5xx）与终止错误，瞬时错误继续重试而非中断整个登录；config.toml 以 0600 原子创建并对名称等写入值做引号/反斜杠转义，避免明文凭据短暂可读及特殊字符破坏配置；API Key 认证在绑定用户失效时改为直接拒绝，不再 fallback 到部门管理员或 superadmin，创建 API Key 时校验部门与关联用户一致，用户软删除会同步禁用其 API Key；进一步要求 API Key 必须绑定具体用户，启动 schema 演进会清理历史未绑定用户的 API Key 并将 api_keys.user_id 收紧为非空；Dashboard 管理接口与前端入口改为仅 superadmin 可访问；用户软删除脱敏名改用用户主键生成，避免短哈希碰撞触发唯一索引冲突；前端授权页新增确认提示与对结构化错误 detail 的兼容渲染。
- 收敛 API Key 生成逻辑：移除独立 API Key 生成服务，统一通过 AuthUtils.generate_api_key() 生成 CLI 授权与用户管理中的 API Key。
- 收敛认证模块命名：CLI 浏览器授权路由合并到 auth_router.py，授权会话服务迁移到 auth_service.py。
- 为 CLI 知识库上传补齐后端接口边界：discovery 新增 cli.kb_upload 能力声明；普通文件上传接口在传入 kb_id 时先校验知识库存在且支持文档，校验通过后才读取文件或写 MinIO；新增同步 POST /api/knowledge/databases/{kb_id}/documents/add，用于把已上传的 MinIO 文件添加为知识库文档记录但不解析、不入库、不进入 Tasker；新增 GET /api/knowledge/databases/{kb_id}/documents/exists?filename=...，用于上传前按文件名或相对路径检查知识库内是否已有同名文件；旧 /documents ingest 入口保留兼容，但在 enqueue 前补充空 items、非 MinIO URL 与缺失 content hash 的请求级校验。
- 新增 yuxi kb upload 上传命令：默认仅包含 .md/.txt/.docx/.html/.htm，省略 --kb-id 时会从 remote 拉取并只展示支持文档上传的知识库，支持非全屏的方向键单选知识库与多选文件类型；支持 --include-ext/--exclude-ext 与 --concurrency 控制本地并发队列，并发默认 10、上限 300；交互终端上传阶段显示进度条，非交互输出保留文本进度；每个并发单元默认会先按相对路径调用 /documents/exists 检查知识库中是否已有文件，存在则直接跳过，传入 --force-upload-file 时跳过该预检并完全依赖上传接口的重复文件校验；单文件上传成功后立即调用 /documents/add 添加该文件记录，不触发解析/OCR/入库；目录上传通过 source_paths 保留相对路径，后端创建文件记录时使用该路径作为展示文件名以保持前端目录层级；上传接口返回“同内容文件已存在”时按已上传过跳过，不再作为错误展示；大批量上传调度改为有界提交，避免数十万文件时一次性创建全部 future 导致资源峰值过高。
- 发布 yuxi-cli 到 PyPI，并新增 GitHub Release 触发的 PyPI Trusted Publishing 工作流；文档新增命令行工具使用说明；CLI 运行访问 remote 的命令前会先输出当前 CLI 版本、remote 名称和 URL。CLI 输出测试在断言前去除 ANSI 样式，避免 GitHub Actions 的强制彩色输出拆分版本号、URL 与参数名并误阻塞 PyPI 发布。
- 修复知识库文件入库/解析成功却被统计为失败（#793）：成功的文件元数据会固定携带 error: None，而后台任务此前以「结果中是否存在 error 键」判定失败，导致成功项也被计入失败数并在全部成功时仍抛出「处理完成，失败 N 个」。改为统一通过 _is_failed_item 按「显式 status == failed 或非空 error」判定，覆盖入库、解析、单独解析/入库三处统计。
- 修复 Windows 初始化脚本自动生成 JWT 配置失败（#804）：init.ps1 改用 Windows PowerShell 兼容的 RandomNumberGenerator.Create().GetBytes(...) 生成随机字节，避免旧 .NET 环境缺少 RandomNumberGenerator.Fill() 导致按 Enter 自动生成时报错。
- 优化 Bash 与 Windows 初始化脚本：目标镜像标签已存在时直接跳过重复拉取；已有 .env 会逐项检查必填 API Key、JWT 密钥、实例 ID 和 Sandbox Provisioner Token，缺失或为空时提示输入，安全配置支持回车生成，并避免写入重复键。
- 优化知识库文件列表状态流转与文件预览边界：uploaded/parsed/error_parsing/error_indexing 状态分别展示解析、入库或重试操作；源文件预览与解析后的 Markdown 查看分离，txt/图片/Markdown/HTML/PDF/代码类按源文件类型预览；Office 源文件仅支持 .docx/.pptx，点击预览时按需生成并缓存 PDF 预览内容，由同一个预览接口直接返回，不再把解析 Markdown 产物当作源文件预览。
- 收敛知识库分块策略选项来源：后端以单一 CHUNK_PRESETS 配置派生 preset id、描述和选项列表，并新增 /api/knowledge/chunk-presets；前端分块策略选择器改为通过接口读取选项，避免前后端重复维护同一份文案。
- 优化大规模知识库文件列表加载：知识库详情接口默认不再返回全量 files，新增按 parent_id/path_prefix/page/page_size/status 查询的轻量文件列表接口；前端文件管理页改为目录懒加载与服务端分页，后端按 source_path/路径型文件名聚合虚拟目录，列表项只保留交互所需字段，顶部统计改用后端聚合结果，避免数十万文件场景下前端全量建树和传输压力。工作区知识库文件浏览统一改用同一套分页懒加载查询，支持真实目录和虚拟目录页码分页，非文档型知识库不再出现在工作区文件源中；文件浏览组件和后端列表接口均不再承载文件名搜索，后续搜索能力由独立后端接口和组件实现；文件列表展示抽出共享 FileBrowserTable，知识库详情和工作区共用展示层，并移除原知识库文件列表拖拽移动入口。
修复二级目录点击“全部文件”仍沿用当前 parent_id 的问题，显式根目录导航会清空目录上下文并重新加载根目录。
- 优化知识库启动元数据加载：服务启动时不再把全部 knowledge_files 记录加载进 self.files_meta，文件解析、入库、预览、下载、打开内容等单文件操作改为按 file_id 从数据库懒加载；文件状态流转改为通过数据库窄字段更新和状态条件更新完成，移除进程内处理队列修复逻辑，避免 api/worker 多进程下出现虚假的状态修复；文件统计刷新改用数据库聚合，文件大小补全从启动阶段移入显式统计修复任务，并收敛处理参数合并日志，避免大规模文档场景下启动内存和日志压力随文件数线性放大。
- 调整知识库待处理统计卡行为：文件管理顶部“待解析/待入库”统计卡从状态筛选改为提交对应后台处理任务；新增按待处理状态批量解析/入库接口，任务内按 500 条游标分页读取文件 ID，避免前端一次拉取和提交海量 ID；显式选中文件解析/入库接口增加 1000 个 ID 的单次上限。
- 修复大规模知识库统计修复失败：repair_missing_file_stats 不再对未入库文件查询 chunk 表，未入库文件残留的 chunk/token 统计会归零；chunk repository 的批量 IN 查询统一分批执行，避免 asyncpg 单条 SQL 参数超过 32767。
- 优化思维导图构建接口设计，支持增量构建和更新：新增 GET /mindmap/diff 接口检测文件变更，POST /mindmap/generate 新增 incremental 参数支持增量更新；纯删除场景无需 AI 调用（递归树手术），新增文件时 AI 整合进现有分类结构；思维导图文件加载改为显式 repository 查询，增量 diff 会按已追踪 file_id 补查分页外文件，避免把分页文件列表误当全量文件集；前端导图 Tab 新增"增量更新"按钮和变更数量 badge。修复删除文件后知识导图仍展示旧内容：单文件删除接口成功后调用 remove_file_from_mindmap、批量删除接口成功后调用 batch_remove_files_from_mindmap，同步移除导图快照中对应叶子节点，无需用户再手动增量更新。
导图文件查询改为覆盖知识库全部目录中的非文件夹记录，根目录为空但子目录有文件时也可正常生成和增量检测。
- 优化文档结构与智能体运行说明：项目简介去除对 LangGraph 具体版本的强调；中间件文档按当前内置 Agent 链路重写，补充知识库工具、Skills 激活、附件/文件系统、子智能体 task、Summary 上下文压缩与工具结果卸载机制；知识库文档补充知识导图与示例问题生成机制；Langfuse 集成文档从“智能体开发”移动到“高级配置”分组。
- 移除知识库普通上传接口遗留的 allow_jsonl 参数，上传类型判断统一依赖 SUPPORTED_FILE_EXTENSIONS；评估数据集 JSONL 继续通过独立评估接口上传。
- 修复 Dependabot esbuild 告警：web 与 docs 统一锁定 [email protected]，docs 同步升级 Vite/Vue 插件 override 并固定 pnpm 版本，避免旧锁文件继续解析到存在漏洞的 esbuild 版本。
- 修复 CORS 与依赖安全告警：后端 CORS 改为通过 YUXI_CORS_ORIGINS 配置允许来源，开发环境默认仅允许本机前端端口，生产环境未配置时不开放跨域，显式使用 * 时会关闭 credentials；同步刷新前后端锁文件，将 aiohttp、cryptography、langchain、langchain-anthropic、pypdf、python-multipart、starlette、pyjwt、torch、torchvision、dompurify、js-yaml、markdown-it、vite 升级到安全版本。
- 修复添加/编辑 MCP 弹窗中环境变量无法新增的问题：环境变量编辑器存在 rows -> object -> rows 的双向同步回环，modelValue 变化时会完全根据已有 key 重建行，导致只填了 key 的行（含刚点击「添加变量」生成的空行）被过滤掉而无法新增；现在仅当传入值与组件自身 emit 的内容不一致时才重建行，避免回声覆盖未填 key 的行。
- 修复模型与知识库后端导入循环：yuxi.models 改为惰性导出模型选择函数，知识库可见范围和知识库工具延迟读取全局 knowledge_base 实例，避免单测、热重载或轻量导入知识库包时因模块尚未完成初始化而失败。
- 修复知识库创建权限持久化一致性：创建知识库时由 Manager 归一化 share_config/created_by 后作为受控记录字段随首次知识库元数据插入写入数据库，避免先插入基础记录再二次更新权限字段产生短暂不一致。
- 修复 HTML 预览 iframe 高度问题：侧边预览模式改为 height: 100% 适应父容器，避免底部内容裁切；全屏预览模式移除 min-height: calc(80vh - 40px)，避免短内容下方白边；iframe 设为 display: block 消除行内基线间隙导致的底部白边；全屏渲染改用独立 srcdoc（不注入 zoom）按 100% 显示，侧边预览仍保持 0.75 缩放。
- 对话消息图片支持点击全屏预览：对话中用户上传的图片支持点击放大查看，复用文件预览的全屏蒙层交互（Teleport 蒙层，点击图片/空白处或按 Esc 关闭），不引入额外依赖。
- 新增 Agent token usage 状态快照，在状态面板中作为普通可折叠分组展示完整 messages、当前传给 LLM 的 messages、system/tools 构成、输入构成堆叠条和上下文窗口占用估算。
- 优化 Agent token usage 状态面板展示：后端补充 LLM 内容消息与工具消息的 token/count 拆分字段，前端将内容消息、工具消息、系统消息与工具定义分开展示，并修正上下文窗口/剩余信息换行与对话流式输出期间的底部跟随滚动。
- 收敛 Agent read_file 多模态边界：仅 UTF-8 文本和图片可读，PDF/Office 文档会引导使用 ocr_parse_file 转为 Markdown，音视频及未知二进制不再注入模型消息；OpenAI 兼容链路的 tool-role 图片桥接从私有 payload 覆盖迁移到公开模型中间件，Provider 明确拒绝图片输入时会自动调用 ocr_parse_file 提取文字，并在后续请求中移除同一张历史图片，避免文本模型重复报错。
- 新增默认 OCR 解析引擎配置 default_ocr_engine，普通登录用户可读取系统配置；知识库上传弹窗与临时附件解析弹窗默认选中系统默认 OCR，解析入口仅在未显式传入 ocr_engine 时使用该默认值。修复读取该配置时因反向导入知识库模块导致配置初始化循环、并中断后续配置加载的问题；OCR 注册表改为轻量模块，知识库单例迁移到显式 runtime 入口，解析器调用方直接导入真实定义模块，包初始化不再加载运行对象。
- 新增 Agent 内置 ocr_parse_file 工具：只允许解析 /home/gem/user-data/{workspace,uploads,outputs} 下的沙盒虚拟路径文件，使用指定或系统默认 OCR 引擎生成 Markdown，并把结果写入 outputs/ocr/*.md；工具返回结果文件路径、字符数和短预览，不写入知识库 MinIO，也不创建知识库文件记录。
- 收敛 Agent Invocation 服务边界：新增 agent_invocation_service.py 承接 agent-call/eval 的外部调用语义、同步等待、异步响应与 OpenAI-compatible 响应装配；agent_invocation_router.py 收敛为 HTTP 适配层，agent_run_service.py 只保留通用 AgentRun 生命周期能力，subagent_run_service.py 改为调用公开 AgentRun 创建 API，不再穿透私有函数。
- 修复 Agent 状态读取与消息落库在重新读取 LangGraph checkpoint 时未传入运行时 context 的问题，避免主智能体或子智能体线程因系统默认模型已不可用而查询状态/保存历史失败；模型供应商管理页新增默认模型保护，阻止删除、停用默认模型所属供应商或移除当前默认模型。
- 评估数据集自动生成支持断点续跑：生成过程中按 YUXI_DATASET_PERSIST_BATCH_SIZE（默认 1）批量持久化已生成的题目，任务失败或中断后可从已持久化进度继续生成；新增 POST /api/evaluation/databases/{kb_id}/datasets/{dataset_id}/resume 接口与前端"继续生成"按钮。修复生成器先收集后产出导致批量持久化在生成中途不生效的问题：改为 worker 产出即流式回报、消费端按 attempt_no 重排输出，异常或取消时已产出未落库的题目（含队列中未消费与 buffer 残余）一并保存；恢复接口改用原子化入队，消除并发恢复创建重复任务引发的唯一约束冲突。失败数据集支持查看已持久化题目：数据集详情接口状态限制放宽为 completed/failed 白名单，前端放开失败数据集的点击查看，下载与发起评估仍仅限生成完成。
- 优化 Agent 上下文压缩：Yuxi 的 DeepAgents summary adapter 在生成 summary 与写入 conversation history 时，会先对本次模型调用的临时消息视图执行 L1 结构精简，截断旧 write_file/edit_file 大参数，并把超过阈值的大 ToolMessage.content 写入 outputs/large_tool_results 后替换为路径和有限预览；L1 不修改 LangGraph state 原始消息，L1 后若上下文低于入口阈值的 40% 则直接调用模型，不生成 summary event，仍超过时才进入 L2 summary。L2 继续使用 DeepAgents _summarization_event.cutoff_index 重建 effective messages；Summary 阈值判断改为使用 Yuxi 自己的近似 token 计算结果，不再根据 provider usage_metadata.total_tokens 或 usage scaling 提前触发；首次写入 conversation_history 前读取旧文件的 sandbox 404 会按 file_not_found 处理，不再产生误导性 warning；present_artifacts 会拒绝展示 large_tool_results 与 conversation_history 等工具调用阶段文件。新增管理员可配置项 summary_keep_messages、summary_prompt、summary_tool_result_token_limit 与 max_execution_steps，分别控制摘要后保留消息数、摘要提示词、summary 阶段工具结果预览上限和 LangGraph recursion_limit。
- 收敛普通聊天模型加载链路：select_model 保留旧 .call() 调用契约，内部改为通过 LangChain chat model adapter 复用 Agent 侧模型加载器，统一 OpenAI-compatible、Anthropic 与 Gemini 等 provider 的运行时适配；移除旧 OpenAIBase wrapper，默认重试策略迁移为 LangChain provider 参数。
- 统一 Redis 客户端管理：新增 yuxi.storage.redis 作为 Redis 配置、短生命周期同步客户端、共享异步客户端与 ARQ RedisSettings 的唯一基础设施入口；运行队列、系统配置快照同步、模型缓存和 worker 不再各自散落读取 REDIS_URL 或直接创建 Redis 客户端，Redis 连接失败日志统一使用脱敏 URL。
- 新增系统配置 Redis 快照同步：管理员保存配置时仍以 saves/config/base.toml 作为唯一持久化来源，成功写入后将可运行时同步的公开配置字段写入 yuxi:runtime_config；API 与 worker 进程在启动时各拉起一个后台同步线程，按 5 秒间隔从快照刷新内存值，读取端按普通属性访问、无需感知，Redis 不可用时继续使用当前内存值。save_dir 是启动期内部路径配置，不在管理员配置中展示、不从 base.toml 读取、不写入 Redis 快照且不支持通过管理员配置接口修改；sandbox 相关配置仍属于启动期敏感配置，运行中的已初始化组件不承诺完整热更新，修改后仍需重启保证生效；移除已无运行时调用点的 enable_reranker 与 default_agent_id 配置字段。
- 优化 FastAPI 请求链路并发能力：Milvus 知识库检索中的同步 embedding、向量/BM25/混合检索调用，以及图谱查询中的同步 Milvus/Neo4j 读操作（含连接建立）统一通过有界 asyncio.to_thread 在线程中执行，避免阻塞 API 事件循环；并发上限按事件循环懒加载信号量控制，不改变检索默认行为与参数上限。
- 修复 AgentRun worker 在 LLM 流式响应期间长期占用 PostgreSQL 连接：chat 与 resume 在完成运行时解析、会话和附件等预处理后，进入流式执行前显式提交事务并归还业务连接，最终消息保存时再按需获取连接。
- 修复异步文档解析阻塞 API 事件循环：DOCX、PPTX、XLS/XLSX、DOC、CSV 与 HTML 的同步转换统一下沉到工作线程，文本读取改用异步文件 I/O；Docling 单例转换增加线程互斥，避免并发解析共享转换器，并补充事件循环可继续调度的回归测试。
- 改进 OpenAI 兼容提供商流式工具调用兼容（替代 v0.7.0 的按 provider 禁流式处理）：根因是 LangGraph v3 流式累积对 tool_call 字段“后值覆盖”，SiliconFlow、阿里云百炼等在参数续片里把 name/id 下发为空字符串覆盖首片真实值。改为 _ToolCallChunkFixChatOpenAI 把续片空串 name/id 归一化为 None，对所有 OpenAI 兼容 provider 通用生效且保留流式，移除原 _NON_STREAMING_TOOL_CALL_PROVIDERS 名单。
- 新增 Agent 评估运行入口：POST /api/agent-invocation/eval/runs 会创建正常对话与 AgentRun，复用 worker 执行链路，并以 source=agent_evaluation 与 agent_invocation_meta.evaluation 标记写入 conversation、AgentRun 输入消息与 Langfuse trace；接口阻塞至运行结束后直接返回最终结果（状态、最终 assistant 输出、Langfuse trace id），并支持通过 include_trajectory_summary 按需返回轻量工具调用轨迹摘要。yuxi-cli 新增 yuxi agent eval 命令，用于从 Langfuse 数据集读取输入并回传实验输出
- 对话消息点赞/点踩反馈接入 Langfuse score：本地 MessageFeedback 保存成功后，如助手消息已关联 Langfuse trace，则同步写入 user-feedback score，点赞为 1、点踩为 0，点踩原因写入 comment，便于在 Langfuse 中按用户反馈筛选 trace。
- 新增外部系统 Agent 调用入口：独立 agent-invocation router 提供 POST /api/agent-invocation/agent-call/runs 与 POST /api/agent-invocation/agent-call/runs/result，字段沿用 Yuxi 命名（agent_slug/thread_id/request_id/model_spec），复用 AgentRun 队列和结果读取能力；支持非流式同步等待或 async_mode=true 立即返回 run_id，Agent Call 不允许通过 agent_call_meta.context 覆盖 Agent context，运行时模型覆盖只允许走独立 model_spec；修复无 thread_id 且模型校验失败时提前提交空对话，导致孤儿对话和 request_id 失败重试非幂等的问题；Agent Call 的 messages[].content 兼容 OpenAI 风格的 text/image_url 多模态数组，纯文本数组不再误报 422，图片输入会保留原始 LangChain 多模态消息供 AgentRun worker 恢复；Agent Eval 与 Agent Call 统一通过 conversation-backed invocation helper 创建 run，后续定时任务等入口只需做请求解析和结果出口适配。
- 修复 Agent Invocation 创建的 eval/call 对话进入用户对话导航的问题：侧边栏最近对话与对话搜索会按 conversation metadata source 排除 agent_evaluation 与 agent_call，保留 run/conversation 持久化与结果追踪能力。
- 下沉 AgentRun 基础能力：将「读取某个 run 的最终结果」（get_agent_run_result/load_agent_run_result，含状态、最终 assistant 输出、Langfuse trace id 与错误）与「阻塞至 run 终结再取结果」（await_agent_run_result，复用有限事件流、无额外轮询）提升进 agent_run_service，供 chat/eval 及未来定时任务统一复用；eval 运行入口改为非流式复用该能力（不再做 SSE 封装），移除其私有结果构建逻辑（结果不变）。
- 重构 AgentRun 接口底座：agent_run_service 拆出内部 create_agent_run、enqueue_agent_run 与 request_cancel_agent_run，保留现有 /api/agent/runs 行为并新增 /api/agent/runs/{run_id}/result 结果读取接口；AgentRunRepository 增加按 parent_agent_run_id 查询 child run 的能力，为后续异步 subagent 生命周期控制预留统一入口。
- 修复子智能体流式事件兼容：Yuxi task middleware 的 DeepAgents 子智能体 transformer 改用专用 yuxi_subagents projection，避免与 LangChain create_agent 默认注册的 subagents projection 冲突导致运行流式消息时报错；子线程路由收集优先读取 Yuxi projection，并保留原 subagents fallback。
- 重构 AgentRun 与子智能体运行链路：保留现有 /api/agent/runs 行为并新增 /api/agent/runs/{run_id}/result 结果读取接口；子智能体新增 subagent_start/status/cancel/await 工具，支持后台启动、轻量进度查询、等待结果、取消运行和已完成 child thread 续跑；同一用户、同一子智能体、同一 conversation thread 存在运行中 run 时返回 busy，不做隐藏排队。
- 修复子智能体同步等待超时语义：await_agent_run_result 在有限 SSE 等待结束后会校验 run 终态，非终态时抛出明确等待超时；task 与 subagent_await 不再把仍在运行的子智能体误报为“已完成但无文本结果”，同步 Agent Call / Eval 入口遇到等待超时返回 504 和当前 run 快照。
- 收紧子智能体运行创建边界：SubagentRunService 显式拒绝以子智能体 run 作为父 run 创建新的子智能体，固化“不支持孙子智能体”的架构约束。
- 修复 AgentRun busy 检查的并发窗口：为同一用户、智能体和 conversation thread 的非终态 run 增加数据库部分唯一索引，并在插入冲突时返回现有 run_busy 结构，避免不同 request_id 并发启动绕过忙碌检查；AgentRun 创建冲突改用局部 savepoint 处理，避免 _create_agent_run 在共享 session 上 rollback 撤销调用方刚创建的子智能体线程关系或输入消息。
- 收敛 AgentRun 数据模型与输入语义：运行记录统一使用 agent_slug、conversation_thread_id、created_by_run_id、input_message_id 等字段，子智能体通过 subagent_threads 关系表维护 parent/child conversation 归属；补齐旧库升级时 agent_runs 旧字段到新字段、subagent_threads.subagent_slug/created_by_run_id 的静默回填与约束收敛，并在创建部分唯一索引前终结重复活跃 run，避免早期分支库保留 nullable schema 或历史重复活跃数据阻塞升级；Agent 状态中的 subagent_runs 改为以 run_id 作为执行身份，resume 请求字段明确为 Command(resume=...) 输入载荷。
- 精简旧链路与失败语义：恢复审批统一走 POST /api/agent/runs 的 resume 载荷，移除旧 POST /api/chat/thread/{id}/resume 流式接口和已废弃的 chat_service.agent_chat；子智能体运行缺少必要线程上下文时直接报错，状态查询只在真实缺失或无权访问时返回 404，内部运行记录格式异常返回 500。
- 统一流式事件线程 ID 提取契约：新增共享 extract_thread_id 工具，BaseAgent、聊天服务和 run worker 统一只读取规范化事件的一层稳定路径，并通过显式 fallback 处理父线程归属，避免递归扫描嵌套 metadata 导致父/子线程事件路由分歧。

v0.7.0 (2026-06-13) Copy Chapter

破坏性变更 Copy Section

- Provider 与模型配置收敛：移除旧版 v1 模型配置与 Ollama 支持，运行时模型统一使用 provider_id:model_id 与独立 provider 模块；自定义 provider 实现逻辑从文件移动到数据库，并从 config 文件迁移到 provider 模块。
- 智能体运行时语义收敛：用户可见的 AgentConfig 收敛为数据库持久化的一级 Agent，内置 Python Agent 改为智能体后端；聊天、运行任务、恢复审批和文件预览均从线程绑定的 Agent 解析运行时上下文，前端只提交 agent_id。
- 知识库能力边界收敛：移除 Upload 与 LightRAG 知识库/图谱能力，知识库类型收敛为 Milvus 与只读连接器；知识库 API 统一使用 /databases/{kb_id}/xxx 形式，并整合 mindmap / eval 等子接口。
- Agent 资源默认选择与权限过滤：未显式配置工具、知识库、MCP、Skills、子智能体时默认启用当前用户可访问/可用的全部资源，显式选择后按允许列表过滤；Agent 创建前统一完成最终资源权限过滤、知识库 kb_id 可见范围派生和 Skill prompt/readable 依赖闭包派生。
- Skill 安装与权限模型收敛：Skill 元数据使用 source_type/share_config/enabled 表达来源、生效范围与启用状态；内置 Skill 启动或同步时自动写入数据库并默认全局启用，上传和远程添加统一改为解析草稿后确认安装，不保留旧直接安装兼容路径。
- 历史兼容层精简：移除 sandbox provisioner local 后端别名、ask_user_question 单问题旧协议、JWT 历史默认密钥特殊判断、内置 Skill SKILLS.md 文件名回退、运行事件数字 seq 兼容和前端旧字段回退。
- 用户身份命名收敛：原业务登录标识统一改为 uid，Agent/LangGraph runtime、conversation、agent_run、sandbox 路径和前端用户态均使用字符串 uid；user_id 仅保留给外部响应中的数值 users.id 或真实外键场景。

开发记录 Copy Section

- 发布版本号更新至 0.7.0，同步 package、Docker 镜像标签与快速开始分支引用。
- 新增内置「深度研究」多智能体：编排器 Agent（deep-research，ChatbotAgent 后端）负责澄清、拆解、并行调度子智能体与综合成稿，配套两个子智能体 research-explorer（围绕单个子问题多轮检索网页/知识库并返回带引用发现）和 fact-verifier（对抗式核验关键论断、标注冲突与置信度）；完整研究方法论沉淀为新增内置 Skill deep-research（依赖 tavily_search），编排器运行时读取并据此调度。三者随 lifespan 启动通过 AgentRepository.ensure_deep_research_agents 幂等落库（已存在不覆盖管理员修改）。
- 新增内置 general-purpose 通用任务子智能体：使用 SubAgentBackend 与空运行配置，作为 task 工具的通用委派目标，由启动初始化自动写入数据库。
- 收敛 MCP 创建与编辑入口：前端移除整段配置文本入口和模式切换器，仅保留表单字段提交；后端 MCP 创建/更新请求拒绝额外配置字段，避免绕过表单约束。
- 调整内置 MCP 默认项：移除 sequentialthinking 的系统内置同步，启动同步时清理历史系统内置记录，保留用户手动创建的同名 MCP。
- 图片生成能力迁移为 Skill：Qwen-Image 从内置 Python 生成工具迁移到内置 Skill image-gen，模型调用与图片下载在 Agent 沙盒中完成，生成结果保存到 outputs 并通过 present_artifacts 展示，为多图片生成模型接入复用同一产物展示链路。
- 优化前端头像加载兜底：用户与智能体头像优先展示已配置图片，加载失败后回退到基于 ID 的 DiceBear 默认头像；离线或默认头像不可达时显示名称前两个字和稳定背景色。
- 降低知识库路由与工具模块复杂度：示例问题生成迁移到知识库 utils，文件上传统一 100 MB 限制，URL 预处理入库路径与旧 content_type=url 行为收敛，并修复 uid、导出 MIME 与异常透传等路由问题。
- 重构智能体配置语义：用户可见的 AgentConfig 收敛为数据库持久化的一级 Agent，内置 Python Agent 改为智能体后端；新增 /api/agent 管理与运行接口，聊天、运行任务、恢复审批和文件预览均从线程绑定的 Agent 解析运行时上下文，前端只提交 agent_id，并在模型配置页新增“智能体”管理页签。
- 删除 Upload 与 LightRAG 图谱/知识库能力：知识库类型收敛为 Milvus 与 Dify，只保留 Milvus 知识库内图谱构建/展示/检索，移除独立 /graph 页面和默认上传图谱工具。
- 收敛只读知识源连接器：新增 ReadOnlyConnectors 基类，Dify 改为声明自身创建参数与校验规则，新增 Notion Data Source 只读知识库并支持 Search/Find/Open；知识库类型接口返回创建参数 schema，前端新建表单按类型动态渲染非 Milvus 配置并统一保存到 additional_params。
- 新增知识库 Chunk 持久化：Milvus 知识库索引/更新流程会将 chunks 双写到 PostgreSQL knowledge_chunks 表与 Milvus，文件内容查看优先查询 PostgreSQL，并为位置信息、图谱实体关联、标签和抽取结果预留结构化字段；chunk 入库改为分批 embedding 与分批写入，避免大文件一次性写入触发 gRPC 消息大小限制；入库成功后将单文件 chunk 数与 token 数写入文件元数据，并将知识库级总 chunk 与总 token 汇总保存到 metadata，前端文件管理页展示该统计并支持一键修复历史文件缺失的统计值。
- 完善 Milvus 知识库图谱构建：修复 Chunk 图谱写入返回值、Neo4j 同步写入阻塞事件循环、重复构建任务竞态、图谱查询提前终止、Neo4j 连接复用、LLM 抽取超时重试和前端错误详情展示等问题；图谱构建会将 entity/triple 本体与 chunk 引用写入 PostgreSQL，并为唯一 entity/triple 建立 Milvus 语义索引，单文件删除时同步清理图谱引用和孤儿向量。
- 优化图谱抽取器配置：未配置时在图谱中心展示配置入口，抽取方案收敛为 LLM，前端仅保留“更多拓展中”占位；LLM 抽取器使用固定 Prompt + 自定义 Schema，并支持模型参数与并发队列数；已配置后允许修改参数并提示重置重抽风险。修复上传并入库新文件时旧内存 metadata 覆盖数据库图谱配置的问题。
- 新增 Milvus 图谱检索链路：Query 可召回图谱实体和三元组，结合 Chunk 命中实体构造 seed entity，读取 Neo4j 2-hop 子图后用 igraph 执行 PPR，最终以 Chunk 为产物并通过 RRF 与原 Chunk 召回融合；检索配置改为 dataclass 元数据生成，支持 depend_on 控制重排序和图检索参数展示。
- 收紧用户管理部门隔离：普通管理员创建用户时固定归属本部门，用户列表、访问选项、详情、更新和删除接口均限制在本部门范围内。
- 修复用户管理列表超过 100 人时被默认分页截断的问题：前端按 skip/limit 分批加载用户，并在用户卡片列表中补充分页渲染。
- 调整 Agent 资源默认选择与运行时上下文：未显式配置工具、知识库、MCP、Skills、子智能体时默认启用当前用户可访问/可用的全部资源，显式选择后按允许列表过滤；Agent 创建前统一完成最终资源权限过滤、知识库 kb_id 可见范围派生和 Skill prompt/readable 依赖闭包派生，聊天运行时与文件系统预览复用同一结果。
- 重构 Skills 权限与安装流程：Skill 增加 source_type/share_config/enabled，内置 Skill 作为启动同步入库的全局资源，不再保留前端安装/更新状态，支持启停但不允许删除；上传和远程添加统一为解析草稿后确认生效范围，安装 slug 优先读取 SKILL.md 的 slug 字段并保留 name 展示名，压缩包名称不参与 slug 校验；管理端支持编辑生效范围与启停；Agent 运行时按当前用户可访问 Skills 派生 prompt/readable 依赖闭包并限制挂载/激活，Skills prompt 改为模型请求级注入以避免污染 runtime context；主智能体恢复 install_skill 工具，允许当前用户安装私有 Skill 并激活当前会话，子智能体配置和运行态均禁用该工具。
- 精简历史兼容层：移除 sandbox provisioner local 后端别名、ask_user_question 单问题旧协议、JWT 历史默认密钥特殊判断、内置 Skill SKILLS.md 文件名回退、运行事件数字 seq 兼容和前端若干旧字段回退。
- 重构知识库共享权限：share_config 改为全局共享、部门共享、指定人可访问三档，部门共享必须包含当前用户部门，指定人可访问必须包含当前用户，并补充权限过滤测试。
- 移除知识库沙盒文件系统映射：不再通过 /home/gem/kbs 暴露知识库文件树，Agent 继续使用 query_kb 与 open_kb_document 访问知识库内容。
- 修复 MinerU 文档解析配置说明：文档处理指南原先指引启动 openai-server（30000 端口，仅提供 /v1/chat/completions），与解析器实际调用的 /file_parse 接口不匹配导致 mineru_ocr 不可用；更正为使用项目内置的 mineru-api 服务（30001 端口），并补充镜像构建与显存调优说明。
- 规范 Agent 知识库 Search/Find/Open 工具协议：resource_id 统一表示知识库 kb_id，Search 返回结构化 resource_id/file_id/chunk 结果，新增 find_kb_document 在已知文件内做关键词或正则定位，Open 默认窗口扩大到 1800 行。
- 收敛知识库分块配置：分块预设仅表达策略选择，通用分块参数统一通过 chunk_parser_config 传递；移除 chunk_size、chunk_overlap、qa_separator 等旧 root 字段兼容。
- 收敛知识库文件解析参数：文件级 processing_params 统一保存 ocr_engine 与 ocr_engine_config，解析阶段直接使用该结构并保留分块参数快照。
- 修复知识库文件大小显示为 0 的问题：文件上传时 file_sizes 参数未正确传播或历史数据缺失导致 DB 中 file_size 为 None；新增 MinIOClient.stat_file/astat_file 获取文件大小方法，add_file_record 在 size 缺失时从 MinIO 回补，_load_metadata 加载元数据后自动为缺少 size 的文件从 MinIO 补全并持久化。
- 优化评估基准自动生成：生成任务支持配置队列并发数，默认 10，范围 1-20。
- 完善模型供应商类型：普通聊天模型运行时新增 Anthropic provider type 适配，并清理不再支持的旧 provider type 入口。
- 重梳理知识库评估存储：评估数据集、题目、评估运行和逐题结果统一入库，JSONL 仅作为导入/导出格式；后端和前端 API 统一使用 dataset/run 语义；评估运行支持用户命名，历史记录按名称展示，综合评分只聚合检索指标。
- 扩展知识库上传来源：添加“从工作区上传”模式，后端将当前用户工作区文件预处理上传到 MinIO，前端沿用现有 addDocuments 入库链路提交 MinIO URL、内容哈希和文件大小。
- 重构知识库详情页布局：DatabaseInfo 改为顶部详情 header + 左侧功能 tab 侧边栏 + 右侧内容区，Milvus 默认进入文件管理，并将检索测试、知识图谱、知识导图、检索配置、RAG 评估和评估基准统一纳入侧边栏导航；只读连接器保留检索测试与检索配置。
- 整合知识导图接口：移除独立 mindmap router 与前端 API 模块，思维导图生成、查询和文件列表接口统一收敛到知识库 API 下。
- 收敛独立模型配置模块运行时：运行时 chat / embedding / rerank 均统一从 provider 模块与模型缓存读取 provider_id:model_id；旧版静态模型配置、v1 slash spec、旧模型列表接口和 Ollama 适配已移除；内置 provider 模板补充 XiaomiMiMo、XiaomiMiMo Token Plan CN 与 Kimi Code（kimi-for-coding）。
- 调整智能体模型配置默认值：BaseContext.model 默认保持为空，运行时按“请求模型 > 智能体配置模型 > 系统默认模型”解析；子智能体未配置模型时继承主智能体当前运行模型，避免把系统默认模型固化进每个智能体配置。
- 调整智能体配置归属与字段权限：AgentConfig 从部门共享改为按 uid 隔离，所有登录用户可管理自己的配置；BaseContext 支持字段级 auth 元数据，后端按用户角色过滤可见与可保存的配置项。
- 新增用户级沙盒环境变量：增加 agent_envs 表与 /api/user/agent-env 接口，设置面板支持当前用户维护 Agent 沙盒环境变量；创建新沙盒时与全局 sandbox.env 合并注入，用户变量优先。
- 收敛用户身份命名：原业务登录标识统一改为 uid，Agent/LangGraph runtime、conversation、agent_run、sandbox 路径和前端用户态均使用字符串 uid；user_id 仅保留给外部响应中的数值 users.id 或真实外键场景。
- 工作区知识库分类显示：知识库侧边栏按创建者分组为“我的知识库”和“共享知识库”，自己创建的知识库显示在“我的知识库”下，非自己创建的显示在“共享知识库”下；knowledge_bases 表新增 created_by 字段记录创建者 uid。
- 工作区文件上传支持多选：/workspace/upload 与 Viewer 工作区上传统一使用 files 多文件字段，一次最多上传 50 个文件，批量上传失败时清理本次已写入文件。
- 聊天附件新增 MinIO tmp 临时上传、可选 PDF/图片解析、确认后加入线程附件的流程；前端改为弹窗内上传、解析与确认。
- 修复智能体对话上传透明 PNG 后图片失真的问题：多模态图片处理在导出 RGB 前会先按白底合成 alpha 通道，避免透明像素中的隐藏颜色被直接转为可见像素；交付物预览优先按文件头识别 MIME，避免 .jpg 文件名包裹 PNG 内容时前端按错误格式加载；Agent run 输入消息会持久化为 multimodal_image，刷新历史后仍能显示用户上传图片。
- 优化智能体对话页细节：状态面板隐藏空 section，待办名称限制为 20 个中文汉字以内，模型选择器展示供应商名称，并收紧附件状态标签与文件编辑浮动操作样式；
- 标准化 Agent run/SSE 执行链路：run 创建时持久化输入消息并提交后入队，worker 统一写入 Redis Stream envelope，SSE 输出 event/data/id、心跳注释、Last-Event-ID 回放和终止 end 事件；前端强制使用 run API 并支持 ask_user_question 中断后以 resume run 恢复；事件 envelope 构造收敛到统一 helper，前端优先使用 envelope 一级 thread_id 路由。
- 修复 AgentRun 恢复与取消边界：无显式 request_id 的 resume run 改为按父 run 与恢复载荷派生稳定幂等 key，避免恢复重试创建重复 run；取消请求先提交数据库状态再发布 Redis 取消信号，避免 worker 在提交窗口内读到旧状态。
- Agent run SSE 新增 verbose=false 精简模式：默认仍返回完整事件载荷；精简模式仅在 SSE 输出前重建最小 payload，跳过 metadata 和空 yuxi.agent_state，将同一 data 内的 request_id 外提为单个字段，移除 chunk 中重复的 meta、metadata、thread_id、response、空 namespace 和图片 base64 等调试字段，保留消息增量、工具调用、工具结果、非空 Agent state、终止状态和 SSE 游标，前端订阅默认使用精简模式。
- 修复 SiliconFlow MiniMax 与阿里云百炼工具调用流式兼容：二者的 OpenAI 兼容流经 LangGraph v3 event stream 累积工具调用时会丢失关键字段（MiniMax 在参数增量 chunk 返回空 function.name，百炼丢失 tool_call.id），空值被写入 checkpoint 后会导致工具执行失败或工具结果无法按 tool_call_id 关联、工具状态永远停留在“进行中”；这两类提供商默认对工具调用禁用流式模型响应（正文回答仍流式），保留 LangGraph v3 运行事件并拿到完整 tool_call。该缺陷属 LangChain v3 流式协议上游问题（参见 langchain#37420、langchainjs#10937、langgraphjs#2496），截至 langchain-core 1.4.4 仍未修复，待上游修复后可移除对应提供商的禁流式处理。
- 收敛后端模块边界：文档解析从 plugins.parser 移动到 knowledge.parser，内容审查从 plugins.guard 移动到 services.guard。
- 收敛文件服务边界：文件预览判断抽为独立服务，Viewer 文件系统的 workspace 分支复用用户 workspace 服务，线程运行时上下文解析从泛化 filesystem_service 拆出为 agent runtime helper。
- 升级 DeepAgents 到 0.6.7 并适配新版文件系统协议：SubAgentMiddleware 改为显式 subagent spec，Skills prompt 补齐新版占位符；sandbox/skills backend 复用新版 ReadResult、GlobResult、GrepResult 等协议类型，文件权限在 backend 层明确区分 skills、uploads、outputs 与 workspace，保留最小 CustomCompositeBackend 以避免非 route glob 误扫其他 route；Agent 上下文压缩改为复用 DeepAgents SummarizationMiddleware，历史摘要与大工具结果统一 offload 到 outputs。
- 优化聊天输入 @ 文件提及：未创建 Thread 时可搜索用户 workspace，创建 Thread 后按当前对话文件优先、workspace 兜底的来源顺序搜索，并拆分 workspace/thread 缓存避免假 thread 与跨用户缓存污染；输入框与用户消息支持将 raw mention 渲染为带类型图标的引用单元，文件仅显示文件名且保留原始沙盒路径文本。
- 重构子智能体为 Agent-backed 形态：移除旧 subagents 表与 /api/system/subagents 管理链路，子智能体改为 agents.is_subagent=true 且使用 SubAgentBackend，创建/编辑统一走 Agent 管理入口；内置后端收敛为 ChatbotAgent 与 SubAgentBackend，Context 分为 BaseContext、ChatBotContext 与 SubAgentContext；主 Agent 通过 Yuxi task middleware 启动真实子 Agent graph，子智能体不再嵌套调用子智能体。沙盒挂载同步拆分为 child checkpoint thread、父对话 uploads/outputs、用户级 workspace 与子 Agent skills scope；主线程状态记录 subagent_runs 并在前端 task 工具中展示子智能体名称、执行状态、child thread 和产物，task 工具结果会暴露 child thread ID 且支持传回 thread_id 继续既有子智能体线程；子智能体执行复用 agent_runs(run_type=subagent) 记录父 run、child thread 与状态，child thread state 查询以 agent_runs 关系为准，不再解析 thread ID 反推父线程；真实流式 E2E 覆盖子智能体输出文件可由父线程文件/Viewer API 读取。流式链路参考 DeepAgents event streaming，后端将 LangGraph v3 raw event 归一化为 Yuxi semantic stream event，按父/子线程归属隔离 run SSE chunk，并支持通过 child thread state 拉取子智能体中间过程。
- 修正评估综合得分计算：overall_score 改为有答案准确率时取各题准确率平均，否则取各题 recall@10 平均，不再把 recall/f1/各 k 检索指标混合平均；历史已存运行不回填。
- 清理无效鉴权中间件：移除启动时未实际校验令牌的 AuthMiddleware 和公开路径残留判断，后端认证边界明确收敛到路由依赖；/api/auth/me 改为强制登录并补充未登录访问返回 401 的集成测试。

v0.6.2 (2026-05-22) Copy Chapter

新增 Copy Section

- 新增个人工作区预览与管理：提供独立于对话 thread 的用户级 workspace API，并增加“工作区”页面，用于浏览、预览、编辑、上传、下载、删除个人 workspace 文件；默认创建 agents/AGENTS.md，并在 Agent 执行时将其内容追加到系统提示词。
- 新增独立模型配置模块：增加 model_providers 表、独立管理接口和“模型配置”页面，支持 provider 基础信息、远端候选模型、enabled models 配置和手动添加模型能力。
- 新增远程 Skill 批量安装能力：后端新增 install_remote_skills_batch() 与 POST /remote/install-batch，前端补充批处理安装 API 和 UI 逻辑。

优化 Copy Section

- 下放扩展管理权限：普通管理员现在可进入扩展管理并完整管理 Tools、MCP、SubAgent、Skills；同步放开 Skill 管理接口权限并补充权限测试。
- 调整 Agent 知识库默认选择：未显式配置知识库时默认启用当前用户可访问的全部知识库，显式保存空列表仍表示不启用知识库。
- 优化评估基准自动生成：仅支持 commonrag/Milvus 知识库，默认参考 chunks 数量改为 1；多 chunk 场景复用知识库向量检索选择相似 chunks，不再对全量 chunks 重新计算 embedding。
- 优化 Agent 输入框文件 mention：用户级 workspace 文件候选改为从独立 workspace API 递归加载，不再依赖 active thread；插入时仍转换为 /home/gem/user-data/workspace/ 沙盒虚拟路径。
- 调整知识库思维导图后端结构：将思维导图路由文件重命名为知识库语义更明确的 router，并把文件列表整理、提示词构建、AI JSON 解析等纯逻辑下沉到知识库 utils。
- 收敛知识库评估后端结构：将评估指标、单题评估、答案生成提示词和自动基准生成算法下沉到 knowledge/eval，EvaluationService 保留任务、文件和持久化编排职责。
- 扩展管理界面交互逻辑重构：MCP / Subagents / Skills 从“左侧边栏 + 右侧详情面板”调整为“卡片式网格布局 + 路由跳转二级页面”，工具标签页改为卡片网格布局 + 弹窗详情。
- 统一卡片样式：ExtensionCard 新增 tags prop 并复用于知识库列表页，知识库列表改用 ExtensionCard + ExtensionCardGrid 替代原有自定义卡片。
- 调整应用主导航：AppLayout 升级为默认展开的侧边栏，保留折叠态图标导航，并统一导航项、任务中心、GitHub、用户信息的图标与文字对齐。
- 合并智能体对话导航：移除 AgentChatComponent 内部聊天侧边栏，将新建对话入口和对话历史移动到 AppLayout 主侧边栏，并通过共享线程 store 统一管理。
- 统一前端 Markdown 预览渲染：新增共享 MarkdownPreview 组件与 markdown_preview 渲染工具，替换 Agent 消息、文件预览、知识库 chunk、任务工具结果、聊天导出等场景中的旧预览实现。

修复 Copy Section

- 修复聊天中普通用户 @ 提及出不来技能和 MCP 列表的问题：放宽技能列表与 MCP 服务器列表读取接口至已登录用户，并对普通用户请求的 MCP 列表进行敏感连接参数脱敏。
- 修复知识库文档入库状态回退：当已解析文件缺失 markdown_file 解析产物时，索引流程会将文件状态恢复为未解析，便于重新解析。
- 修复附件上传后未立即刷新 mention 候选的问题。
- 加固 JWT 鉴权安全：移除历史默认密钥回退，初始化脚本支持生成并持久化 JWT_SECRET_KEY 与 YUXI_INSTANCE_ID，签发和验证令牌时校验 iss/aud，并拒绝已删除或登录锁定用户继续使用旧令牌访问系统。
- 修复模型配置路由请求模型未接收 embedding_base_url / rerank_base_url 导致前端已填写仍被后端校验拦截的问题。
- 修复知识库文档处理任务状态不一致问题：文件解析失败时任务中心正确显示"失败"而非"已完成"。

v0.6.1 (2026-04-24) Copy Chapter

新增 Copy Section

- 合并知识库导航入口：左侧导航仅保留"知识库"，文档知识库与图知识库在页面 header 中通过同一组轻量切换入口切换
- 抽象页面轻量切换 header：知识库与扩展管理页直接共用 ViewSwitchHeader，收敛文档知识库、知识图谱、Tools、MCP、Subagents、Skills 等入口的信息层级
- 调整任务中心交互：入口移动到 GitHub 按钮下方，并将右侧抽屉展示改为居中弹窗
- 将 yuxi 从 uv workspace 成员调整为 backend/package 下可独立构建的本地 Python 包，backend 通过 path dependency 以已安装包形式发现依赖
- 新增 Skills 远程安装能力：Skills 管理页支持填写 owner/repo 或 GitHub URL，后端通过隔离的临时 HOME 调用 npx skills add 下载指定 skill
- 调整部门删除语义：删除部门时不再要求用户数为 0，而是将部门下用户迁移到默认部门
- 扩展 viewer 工作区文件操作：/home/gem/user-data/workspace 支持从文件系统面板新建文件夹和上传文件
- 为历史线程补充前端本地配置变更提示：当已有历史消息的对话中切换 Agent、切换配置或编辑配置项时，插入非持久化的信息提示
- 调整 Worker run 模式下的消息首屏反馈：前端发送消息时先乐观渲染用户消息，再将前端生成的 request_id 透传给 /api/chat/runs 与服务端 init 对账
- 调整聊天首页的智能体切换入口：当智能体数量 >= 4 或内容区宽度小于 380px 时自动收敛为"当前智能体 + 下拉按钮"形式
- 调整智能体对话中的工具调用展示：连续工具调用默认折叠为"调用了 N 个工具"的轻量摘要
- 调整输入框配置入口与侧边栏头尾交互：输入区配置按钮改为轻量 dropdown 触发器

修复 Copy Section

- 修复沙盒 workspace 隔离粒度：宿主机目录从共享 saves/threads/shared/workspace 收敛为用户级 saves/threads/shared/<user_id>/workspace
- 收紧文件系统安全边界：viewer/chat 下载与删除路径统一基于解析后的真实路径做允许目录校验，阻止通过软链接逃逸工作区/线程目录
- 修复 OIDC 原始用户名绑定中的占位用户解析：解析目标用户 ID 时改为从右侧拆分，避免 sub 中包含冒号时把已绑定账号误判成冲突账号
- 修复 DOCX 解析中的图片回插顺序：Docling 导出的多个 ` 占位符现在按文档图片顺序替换
- 修复前端依赖安全告警：通过 pnpm.overrides 将传递依赖 flatted 锁定到 3.4.2、lodash-es 锁定到 4.18.1
- 修复对话摘要中间件的工具结果卸载链路：摘要触发时改为将大体积 ToolMessage 写入当前 agent 可见的 sandbox outputs 路径
- 修复 agents 页对话侧边栏在 keep-alive 路由切换后的误关闭问题
- 调整 Milvus 混合检索实现：集合 schema 增加 BM25 稀疏向量字段、BM25 函数和中文 analyzer 配置
- 重构 MCP 运行时配置加载模型：移除 MCP_SERVERS 作为运行正确性前提的设计，改为每次直接从数据库读取最新 MCP 配置
- 为知识库检索工具补充 metadata.filepath 注入：在 query_kb 统一出口基于会话可见知识库构建 file_id -> /home/gem/kbs/... 映射并回填 Milvus 检索结果
- 移除知识库沙盒文件系统映射：Agent 不再通过 /home/gem/kbs 遍历知识库文件，继续通过 query_kb 和 open_kb_document 检索与打开文档。

v0.6.0 (2026-04-01) Copy Chapter

新增 Copy Section

- 调整聊天首页的智能体切换入口：在无历史对话时，智能体数量 <= 3 且 chat-main 宽度不小于 380px 时继续使用横向 segmented；当智能体数量 >= 4 或内容区宽度小于 380px 时自动收敛为“当前智能体 + 下拉按钮”形式，避免多智能体或窄屏场景下入口被截断
- 发布前一致性修复：统一 0.6.0 版本号（backend/package/web）、更新 dev/prod 镜像标签语义（0.6.0.dev / 0.6.0），并为 /api/system/health 补充 version 字段，提升部署可观测性与发版追溯能力
- 收敛“状态工作台”自动弹出规则：前端不再因为共享 workspace 或文件系统天然存在内容而默认展开，改为仅在 /home/gem/user-data/uploads 或 /home/gem/user-data/outputs 下检测到实际文件时自动弹出；手动打开、关闭、刷新和伸缩交互保持不变
- 调整智能体 todo 展示语义：待办状态不再作为 capabilities 前端开关，而是直接根据运行态 agent_state.todos 渲染；同时将 todo 入口从 Agent Panel 移到输入框内的轻量浮层，并让右侧“状态工作台”收敛为文件系统视图，输入框按钮文案同步由“状态”调整为“文件”
- 优化 Agent 输入框 mention 行为：在保留附件 mention 的同时，将共享 workspace 文件纳入候选范围；并将 @ 空查询时的候选列表改为空，仅在继续输入后再执行筛选，避免工作区文件过多时直接铺满下拉面板
- 为前端工作台文件树补齐文件删除能力：/api/viewer/filesystem/file 新增删除接口，AgentPanel 文件节点新增删除按钮与确认交互，删除后会同步刷新树与预览状态
- 扩展 Agent Panel 状态工作台删除能力：继续复用 DELETE /api/viewer/filesystem/file，在保持接口不变的前提下支持删除文件夹；空目录与非空目录现在都会递归删除，workspace 下目录也可直接清理，前端目录节点同步新增删除入口与对应确认文案
- 调整前端工作台文件预览交互：恢复默认侧边/弹窗预览，并新增显式“全屏预览”入口；全屏模式下由预览内容直接覆盖整页，仅保留右上角悬浮关闭按钮；同时修复 HTML 文件首次在弹窗中预览偶现白屏的问题，改为在内容更新后强制重建 iframe
- 统一 Agent Panel 文件预览与消息区交付物预览组件：两处改为复用同一套 AgentFilePreview 预览实现，并为交付物预览补齐与工作台一致的“全屏预览”入口
- 修复交付物卡片展开后的长列表展示：当单轮交付物文件超过面板可见高度时，卡片内容区改为显示纵向滚动条，避免超过约 10 项后底部文件与操作按钮被裁切
- 兼容旧版已安装的内置 reporter 技能记录：update_builtin_skill 现在会识别由 system 或 builtin-system 管理的历史记录，避免更新时误报“技能 reporter 不是内置 skill”
- 调整沙盒 user-data 目录隔离策略：workspace 改为共享目录 saves/threads/shared/workspace，uploads/outputs 继续保持 thread 级隔离；同时更新 thread artifact 权限校验、viewer 文件系统列举逻辑，以及对应的 router/E2E 测试
- 重构聊天接口请求模型：流式与非流式聊天统一使用 query + agent_config_id 请求体，并移除路径中的 agent_id；同时修复非流式接口实际误走流式执行链路的问题，改为调用 invoke_messages 一次性执行，并补充对应测试
- 修复对话线程与 Agent 配置错位的问题：发送消息时将当前 agent_config_id 绑定到 thread 的 extra_metadata，线程列表接口返回该绑定值，前端切换历史 thread 时会自动恢复对应配置
- 为沙盒与 viewer 文件系统补齐知识库只读映射：新增 /home/gem/kbs 命名空间，按“用户可访问知识库 ∩ 当前 Agent 已启用知识库”暴露原始文件与解析后的 Markdown，并补充对应后端与 viewer 路由测试
- 优化 viewer 文件系统目录树加载：根目录与 /home/gem/user-data 改为直接读取本地线程挂载目录，不再为只读树视图触发 sandbox 冷启动，并补充对应后端测试
- 修复 /home/gem/user-data 根目录文件不可见的问题：根目录现在会同时展示 thread 目录下的真实文件和 workspace 入口，不再只保留固定命名空间目录
- 修复前端工具图标与渲染匹配不准确的问题：工具管理列表与工具调用结果统一改为基于工具 id 的精确映射，避免模糊匹配导致的误渲染，未命中的工具不再显示默认扳手图标
- 修复 GitHub Pages 文档部署工作流失败：移除 actions/setup-node@v4 对不存在 docs/package-lock.json 的缓存依赖，并将 docs 目录安装命令从 npm ci 调整为 npm install，避免因未提交锁文件导致 CI 在依赖缓存和安装阶段直接失败
- 修正沙盒 provisioner backend 命名与配置说明：统一对外使用 docker / kubernetes，保留 local 作为兼容别名；同步清理 compose 中未生效的 provisioner 环境变量、补齐 K8s 相关变量注释，并更新沙盒架构文档中的默认模式与 backend 描述
- 修复智能体配置列表接口在“无配置自动创建默认配置”路径下的参数缺失：补齐 get_or_create_default 的 agent_id 入参，避免 /api/chat/agent/{agent_id}/configs 返回 500
- 修复 LightRAG 同库写入并发导致的入库失败：为 index_file / update_content 增加按知识库维度的串行锁，并补齐 documents 接口 auto_index 阶段对最新解析状态的回写与回归测试，避免长时间入库任务进行中再次选择同库文件时直接并发写入报错


---

v0.5 Copy Chapter

新增 Copy Section

- 优化 OCR 体验并新增对 Deepseek OCR 的支持
- 优化 RAG 检索，支持根据文件 pattern 来检索（Agentic Mode）
- 重构智能体对于“工具变更/模型变更”的处理逻辑，无需导入更复杂的中间件
- 重构知识库的 Agentic 配置逻辑，与 Tools 解耦
- 将工具与知识库解耦，在 context 中就完成解耦，虽然最终都是在 Agent 中的 get_tools 中获取
- 优化chunk逻辑，移除 QA 分割，集成到普通分块中，并优化可视化逻辑
- 重构知识库处理逻辑，分为 上传—解析—入库 三个阶段
- 重构 MCP 相关配置，使用数据库来控制 #469
- 使用 docling 解析 office 文件（docx/xlsx/pptx）
- 优化后端的依赖，减少镜像体积 #428
- 优化 liaghtrag 的知识库调用结果，提供 content/graph/both 多个选项
- 优化数据库查询工具，可通过设计环境变量添加描述，让模型更好的调用
- 优化任务组件，改用 postgresql 存储，并新增删除任务的接口
- 支持更多类型的文档源的导入功能（支持后端配置的白名单的 URL 导入）

修复 Copy Section

- 修复文件上传弹窗中 OCR 下拉选项展开时不会自动检查服务状态的问题
- 修复知识图谱上传的向量配置错误，并新增模型选择以及 batch size 选择
- 修复部分场景下获取工具列表报错 #470
- 修改方法备注信息 #478
- 修复多次 human-in-the-loop 的渲染解析问题 #453 #475
- 修复沙盒后端接入回归：补齐 composite backend 的 sandbox_backend 参数、限制 /api/sandbox/prepare 仅允许访问当前用户线程、确保 release() 之后的 destroy() 会真正停止热池容器，并恢复 docker-compose 的完整模式默认值
- 重构沙盒为 deer-flow 风格的 AIO provider：切换为 thread-local sandbox、统一 /home/gem/user-data/{workspace,uploads,outputs} 固定路径、移除公开 /api/sandbox/* 生命周期接口，并补充 lite 模式下的 provider 生命周期、filesystem API 与 sandbox 复用/隔离 E2E 验证
- 调整聊天附件存储链路：线程附件改为直接落盘到 saves/threads/<thread_id>/user-data/uploads，解析成功后额外生成 uploads/attachments/*.md，不再依赖 MinIO 或显式上传到 sandbox
- 修复知识库文件列表包体异常膨胀：上传阶段不再把批次级 content_hashes 写入每个文件的 processing_params，并从数据库详情列表接口中移除该字段，改为按需读取单文件详情

v0.4 Copy Chapter

新增 Copy Section

1. Fork 并克隆仓库。
2. 配置上游仓库并同步最新 main。
3. 从最新 main 创建独立分支。
4. 完成开发、测试和文档更新。
5. 使用独立上下文的 Reviewer Agent 完成提交前 Code Review，并处理 Review 结论。
6. 提交改动并将分支推送到自己的 Fork。
7. 从 Fork 分支向 xerrors/Yuxi:main 发起 PR。
8. 根据 CI 和 Review 反馈继续修改，直至合并。

如果任务来自 GitHub Project，开始开发时将任务状态更新为进行中；PR 创建后关联对应 Issue 或 Project 条目。任务只有在必要测试通过并完成合并后，才应标记为完成。

1. Fork 与克隆仓库 Copy Chapter

先在 GitHub 上 Fork xerrors/Yuxi，然后克隆自己的 Fork：

git clone https://github.com/<your-username>/Yuxi.git
cd Yuxi

克隆完成后，默认的 origin 应指向你的 Fork。将官方仓库配置为 upstream：

git remote add upstream https://github.com/xerrors/Yuxi.git
git remote -v

推荐保持以下远程仓库关系：

origin    你的 Fork，用于推送开发分支
upstream  xerrors/Yuxi，用于获取主仓库更新

不要把开发分支直接推送到 upstream。

2. 同步最新主分支 Copy Chapter

每次开始新任务前，先同步官方仓库的最新 main：

git fetch upstream
git switch main
git merge --ff-only upstream/main
git push origin main

--ff-only 可以避免在本地 main 上意外产生额外的合并提交。如果该命令失败，说明本地 main 已经包含独立修改；请先检查分支状态，不要直接覆盖或删除未确认的工作。

3. 创建任务分支 Copy Chapter

必须从同步后的 main 创建独立分支，不要直接在 main 上开发：

git switch -c feat/knowledge-graph-import

分支名应简短、明确，并能表达改动目的。推荐格式：

feat/<topic>      新功能
fix/<topic>       Bug 修复
docs/<topic>      文档更新
refactor/<topic>  重构
test/<topic>      测试改进
chore/<topic>     工程或辅助任务

示例：

git switch -c fix/chat-stream-interrupt
git switch -c docs/update-contributing-guide

4. 开发环境 Copy Chapter

Yuxi 使用 Docker Compose 管理开发环境。开发、调试和测试应在运行中的容器环境中完成。

首次启动前，根据 .env.template 准备项目根目录下的 .env，然后启动服务：

docker compose up -d

确认容器状态和后端日志：

docker ps
docker logs api-dev --tail 100

Compose 服务 api 和 web 对应的容器名分别为 api-dev 和 web-dev，默认支持热重载。修改本地代码后通常不需要重启容器。

服务定义和挂载方式见 docker-compose.yml。

5. 实现原则 Copy Chapter

提交代码时请遵循以下原则：

- 使用满足验收标准的最小实现，不增加当前任务未要求的功能、配置或扩展点。
- 保持主流程简单、线性、易读；不要为了单次使用的逻辑创建多层抽象。
- 修改范围应能直接追溯到当前任务，不格式化或重构无关代码。
- 预设条件不成立时应明确失败，不使用静默回退或吞异常掩盖问题。
- 修复 Bug 时，优先增加能够稳定复现问题的回归测试，再修复实现。
- 行为、接口或配置发生变化时，同步更新相关文档。

前端改动 Copy Section

前端代码位于 web/，请遵循以下约束：

- 使用 pnpm 管理依赖。
- API 接口统一定义在 web/src/apis。
- Icon 优先使用 lucide-vue-next，并保持尺寸一致。
- 样式使用 less。
- 非特殊情况使用 base.css 中已有的颜色变量。
- 遵循 界面设计规范，保持现有交互和视觉语言一致。

不要在没有必要的情况下引入新的前端依赖。如果确实需要新增依赖，请在 PR 中说明用途和替代方案。

后端改动 Copy Section

后端代码位于 backend/，请遵循以下约束：

- 使用 Python 3.12+ 支持的现代、Pythonic 写法。
- 保持路由、服务、仓储和领域逻辑的现有边界。
- 新增测试应放入 backend/test/unit、backend/test/integration 或 backend/test/e2e 对应目录。
- 不在测试或文档中写入 .env 中的账号、密码、Token 或其他敏感值。

测试分层、fixture 和 skip 规则见 测试规范与工作流。

6. 检查与测试 Copy Chapter

提交前按照“检查 → 测试 → Lint”的顺序验证改动。测试范围应与改动风险匹配：

- 纯逻辑改动：运行相关单元测试。
- API、权限或持久化改动：补充并运行相关集成测试。
- 关键用户链路：补充并运行对应 E2E 测试。
- 前端改动：运行 Lint、相关单元测试和构建检查。

后端测试 Copy Section

单元测试

docker compose exec api uv run --group test pytest test/unit -m "not slow"
集成测试

docker compose exec api uv run --group test pytest test/integration
E2E 测试

docker compose exec api uv run --group test pytest test/e2e -m e2e

也可以使用项目脚本：

backend/test/run_tests.sh unit
backend/test/run_tests.sh integration
backend/test/run_tests.sh e2e
backend/test/run_tests.sh all

优先运行与改动直接相关的最小测试集，再根据影响范围扩大回归测试。不要只因为本地缺少默认数据就跳过测试，应通过 fixture 显式准备需要的资源。

格式化与静态检查 Copy Section

应用项目格式化规则：

make format

如需在不修改文件的情况下核对后端 Ruff 检查，可运行：

docker compose exec api uv run ruff check package
docker compose exec api uv run ruff format package --check

前端改动还应运行：

docker compose exec web pnpm run lint
docker compose exec web pnpm run test:unit
docker compose exec web pnpm run build

最后检查补丁是否包含空白错误：

git diff --check

如果某项检查因环境或外部服务不可用而无法执行，请在 PR 的测试说明中明确记录原因和未验证范围，不要把未执行写成已通过。

7. 提交前独立 Agent Code Review Copy Chapter

所有包含代码变更的任务，在开发和测试完成后、执行 git commit 前，必须使用 Codex、Claude Code 或同等工具完成一次独立 Agent Code Review。

这里的“独立”是指 Reviewer Agent 必须运行在一个全新的会话和上下文中：

- 不继承当前开发会话的对话历史、推理过程或实现结论。
- 不使用继承当前上下文的 SubAgent 代替独立 Review。
- Reviewer 应根据需求、完整 diff、相关代码、测试和项目规范独立判断，而不是只检查开发者指定的局部代码。

Review 重点检查以下内容：

1. 功能正确且完整：实现满足需求和验收标准，主路径、关键边界、错误处理和测试可信，没有遗漏主要使用场景或引入明显回归。
2. 实现简单且低认知负担：优先复用现有能力，减少重复开发和重复代码；避免过度设计、过度防御、不必要抽象、细碎 helper、冗余 fallback 和过长调用链；主流程应直接、清晰、易读。
3. 风格一致且位置合理：新代码与相邻实现保持一致，Python 代码符合 Python 3.12+ 和 Pythonic 风格；路由、服务、仓储、前端 API、测试等内容位于正确边界，并符合 AGENTS.md、ARCHITECTURE.md、测试规范 和相关开发文档。

发现影响功能、代码边界或明显增加冗余和认知负担的问题时，应在提交前修正。这个阶段用于提升代码质量，不要求在 PR 中记录 Review 过程或问题清单。

独立 Agent Review 用于提升代码质量，不改变代码作者的责任；作者仍需对最终实现、测试结果和维护成本负责。

8. 提交改动 Copy Chapter

提交前先检查本次变更范围：

git status
git diff

不要提交 .env、密钥、运行数据、构建产物或与当前任务无关的文件。

提交信息遵循 Conventional Commits；标题应简洁说明改动内容。项目提交信息推荐使用中文：

git add <changed-files>
git commit -m "docs: 完善 Fork 与 PR 贡献流程"

常用类型：

feat      新功能
fix       Bug 修复
docs      文档更新
refactor  不改变行为的代码重构
test      测试新增或调整
chore     构建流程或辅助工具变更

保持提交历史易于 Review。不要为了“整齐”而修改已经共享的提交历史；如果 Reviewer 要求整理提交，再根据具体情况处理。

9. 推送分支并创建 PR Copy Chapter

将任务分支推送到自己的 Fork：

git push -u origin docs/update-contributing-guide

创建 PR 时确认目标和来源：

base repository: xerrors/Yuxi
base branch:     main
head repository: <your-username>/Yuxi
compare branch:  当前任务分支

不要向自己 Fork 的 main 创建 PR，也不要把多个任务分支合并后再统一提交。

由 Agent（Codex、Claude Code 等）创建的 PR，在调用创建命令前先向用户展示拟提交的标题和完整正文，等待明确确认后再创建。确认针对的是标题和正文，不代表跳过测试、敏感信息检查、Fork/远程目标检查和 CI 结果记录等提交前必做项。

PR 标题直接表达变更目标。正文按照 PR 模板 填写，并按实际改动补充对应章节：

Fix（Bug 修复），至少包含：

- 触发场景和可复现步骤：用户做了什么、在什么环境下触发。
- 当前错误表现与影响范围。
- 根因定位和修复方式。
- 回归测试或验证方式，说明如何证明问题已修复。
- 兼容性、数据影响和仍未覆盖的边界。

稳定复现、范围聚焦、带回归验证的 Fix 是优先欢迎的贡献类型。

Feature（新功能），至少包含：

- 背景、用户场景和要解决的问题。
- 目标、非目标及主要验收标准。
- 实现方案、关键设计取舍和受影响模块/接口。
- 配置、数据、兼容性或迁移影响。
- 实际测试、E2E 场景、截图/录屏（如适用）和未验证风险。

UI 改动，必须提供最终界面截图或录屏：

- 重要视觉改动提供修改前/后对比或关键交互状态。
- 适用时覆盖浅色/暗色、响应式尺寸、loading/empty/error 等关键状态，并在正文中标明截图对应场景。
- 提交时因 Docker、浏览器或环境问题暂时无法取得截图，必须在提交前明确告知用户截图缺失和补充计划；PR 创建后补充到 GitHub PR/评论，并把可访问链接回填到 PR 正文或 Project 任务。
- 没有截图时不得声称 UI 已完成视觉验证。

如果 PR 对应仓库 Issue，请在正文中使用：

Closes #123

这样 PR 合并后可以自动关闭对应 Issue。准备好接受 Review 时提交普通 PR；仍需讨论方案或 CI 尚未完成时，可以先提交 Draft PR。

10. 处理 CI 和 Review Copy Chapter

PR 创建后，贡献者负责持续跟进 CI 和 Review：

1. 查看失败检查的具体日志，定位与本次改动有关的问题。
2. 在原任务分支继续修改、测试和提交。
3. 将新提交推送到同一远程分支，PR 会自动更新。
4. 回复 Review 时说明如何处理；如果不采纳建议，应解释具体原因和取舍。
5. 所有必要检查通过、Review 意见解决后再请求合并。

不要为同一个任务重复创建 PR。除非维护者明确要求，也不要关闭原 PR 后重新提交来隐藏讨论记录。

来自 Fork 的 PR 默认无法读取主仓库 Secrets。不要通过修改工作流、打印环境变量或扩大权限来绕过这一限制；如果验证必须依赖受保护凭证，请在 PR 中说明并由维护者执行对应检查。

如果开发期间 main 有更新，先获取最新上游代码：

git fetch upstream

只有在出现冲突、CI 明确要求更新，或维护者要求时，再将任务分支更新到最新 upstream/main。涉及 rebase 和强制推送时，应使用 --force-with-lease，并确保该分支没有其他贡献者共同开发。

11. 合并后的清理 Copy Chapter

PR 合并后，可以删除已经完成的远程和本地任务分支：

git push origin --delete docs/update-contributing-guide
git switch main
git branch -d docs/update-contributing-guide

然后重新同步 upstream/main，再开始下一个任务。不要复用已经合并过的任务分支提交新的需求。

如果任务来自 GitHub Project，确认关联 PR 已合并、验收结果已记录，再将任务更新为完成状态。

文档维护 Copy Chapter

代码改动后，请检查是否需要同步更新文档：

- 正式文档位于 docs/。
- 文档导航定义在 docs/.vitepress/config.mts；新增正式页面时需要同步加入导航。
- 已完成的用户可见变更或发布说明更新到 changelog.md。
- 未来规划和未完成事项更新到 roadmap.md，不要将已完成变更继续保留为路线图事项。
- 仅开发者可见且确有必要的临时设计记录放在 docs/vibe/。

AI 辅助贡献 Copy Chapter

使用 Codex、Claude Code 等 AI 工具辅助开发时，贡献者仍需对代码、测试、文档和安全性承担完整责任，提交流程与人工贡献完全一致：完成开发与测试、按本文档创建 PR、如实填写 PR 内容。

Agent 可以在任务范围和用户授权内完成 commit、push 和创建 PR，不因使用 Agent 而要求额外的 Human Review。创建 PR 前，Agent 需要先向用户展示拟提交的标题和正文并等待确认，具体见上文「创建 PR」一节。

不要把仓库 Secrets、.env 内容、用户数据或其他敏感信息提供给不受信任的服务。

获取帮助 Copy Chapter

- Bug 反馈：GitHub Issues
- 功能和方案讨论：GitHub Discussions

感谢每一位贡献者的投入。

---

Develop Guides/Design Copy Section

产品体验与界面设计规范

本文档定义 Yuxi 的产品体验与界面设计规范，适用于需求设计、交互方案、视觉设计、web/src 下的新页面、新组件和现有 UI 调整。它同时面向产品、设计、人类开发者和 AI coding agent：开始实现前先说明用户目标、信息层级和交互语义，再复用现有组件、CSS 变量和交互模式。

0. 产品判断先于界面实现 Copy Chapter

界面不是接口字段的可视化投影。设计前先明确：目标用户、主要任务、需要做出的判断、成功与异常状态，以及哪些信息只是实现细节。

- 每个可见元素必须帮助用户识别、选择、判断状态、执行操作或恢复错误；否则删除。
- 默认使用用户语言描述用途、差异和影响。内部 ID、枚举和环境变量只在复制、对接或排障时按需展示。
- 不同概念不能因为数据结构相同就放进同一列表。“不使用服务”“自动选择”等通常是策略，不是资源项。
- 一个页面或分区只解决一个主要问题；高级和低频配置使用渐进披露。
- “接口返回了”“其他后台都有”“看起来更丰富”不能成为展示理由。

1. 视觉气质 Copy Chapter

Yuxi 是知识库、知识图谱与 Agent 开发平台，界面应保持克制、清晰、工程化。设计服务于长时间阅读、配置、调试和数据管理，不做营销页式装饰。

核心原则：

- 功能优先：视觉层级帮助用户理解任务、状态和下一步操作，不为装饰牺牲信息密度。
- 一致优先：相似功能使用相同布局、颜色、状态和交互反馈。
- 轻量优先：用背景、边框、字号和留白建立层级，避免重阴影、夸张渐变和非功能性动效。
- 可维护优先：新增样式必须基于现有 token 和组件模式，不为单次需求引入新的设计体系。

2. 颜色与 Token Copy Chapter

颜色必须优先使用 web/src/assets/css/base.css 和 web/src/assets/css/base.dark.css 中定义的 CSS 变量。不要在组件中随意新增硬编码色值；确需新增全局色值时，先补充 token 并说明用途。

主色 Copy Section

--main-* 和 --main-color 用于品牌主色与关键交互：

| Token | 使用场景 |
| --- | --- |
| --main-color | 主按钮、选中态、重点链接、关键图标 |
| --main-700 / --main-600 / --main-500 | 主色文字、hover、active、强调状态 |
| --main-50 / --main-30 / --main-10 | 主色浅背景、选中行背景、轻量提示背景 |

主色只用于表达“当前选择、主要操作、关键入口”。不要把主色当作普通装饰色铺在卡片或大面积背景上。

中性色 Copy Section

--gray-* 是默认界面骨架，用于背景、文本、边框和分割线：

| Token | 使用场景 |
| --- | --- |
| --gray-0 | 页面和卡片主背景 |
| --gray-10 / --gray-25 / --gray-50 | 次级背景、hover 背景、弱分区背景 |
| --gray-100 / --gray-150 / --gray-200 | 分割线、输入框边框、卡片边框 |
| --gray-900 / --gray-1000 | 标题和主要正文 |
| --gray-600 / --gray-500 / --gray-400 | 辅助说明、占位文本、禁用文本 |

文本也可以使用 Ant Design 兼容语义变量：--color-text、--color-text-secondary、--color-text-tertiary。组件内优先选语义变量；需要更细层级时再使用 --gray-*。

语义色 Copy Section

语义色只用于状态和反馈，不用于装饰：

| Token 组 | 使用场景 |
| --- | --- |
| --color-success-* | 成功、已完成、连接正常 |
| --color-error-* | 错误、危险操作、删除、失败 |
| --color-warning-* | 警告、待处理、需要注意但未失败 |
| --color-info-* | 信息提示、说明性状态 |
| --color-accent-* | 少量辅助强调，不能替代主色 |

状态标签建议使用浅背景 + 深文字，例如 background: var(--color-success-50); color: var(--color-success-700);。不要只依靠颜色传达状态，必要时配合文字或图标。

图表色 Copy Section

图表和统计可视化优先使用 --chart-palette-*。不要复用错误色、警告色做普通图表分类，避免与状态反馈混淆。

暗色模式 Copy Section

Yuxi 通过 :root.dark 覆盖同名 token。新增 UI 必须使用 CSS 变量而不是固定浅色值，并检查浅色、暗色两套表现。

新增组件时至少检查：

- 背景、卡片、输入框不出现纯白硬编码导致的暗色穿帮。
- 文本和边框在暗色模式下仍有足够对比度。
- hover、focus、disabled、selected、error 等状态在暗色模式下可辨认。
- 图表、代码块和第三方组件需要显式传入 theme 时，使用 useThemeStore() 的现有模式。

3. 字体与文本层级 Copy Chapter

全局字体栈定义在 web/src/assets/css/main.css，新增组件不要私自引入新字体。代码、命令、路径和技术标识可使用 monospace，优先复用现有 @mono-font 或系统 monospace 栈。

建议层级：

| 角色 | 建议样式 | 使用场景 |
| --- | --- | --- |
| 页面标题 | 20-24px，600 | 页面主标题、弹窗主标题 |
| 分组标题 | 16-18px，600 | 卡片标题、表单分组标题 |
| 正文 | 14-15px，400 | 常规说明、列表内容 |
| 辅助说明 | 12-13px，400 | helper text、元信息、时间、统计说明 |
| 标签/状态 | 12px，500 | tag、chip、状态徽标 |
| 代码/路径 | 12-14px，monospace | 文件路径、命令、代码片段 |

文本规范：

- 标题要短，优先描述对象，不写营销式口号。
- 按钮文案使用明确动作，如“保存配置”“重新检测”“删除文件”。
- 危险操作必须让文案直接表达后果，如“删除知识库”。
- 不使用 placeholder 替代表单 label；placeholder 只做输入示例。
- 不使用负字距或按视口宽度缩放字体，避免宽屏和小屏出现不可控排版。

4. 组件样式 Copy Chapter

技术栈约束 Copy Section

- 包管理器：pnpm
- 图标库：优先使用 lucide-vue-next
- 样式语言：LESS
- 颜色变量：使用 base.css / base.dark.css 中的 CSS 变量
- UI 基础：复用 Ant Design Vue 和项目现有组件模式，避免为单次需求封装新组件体系

按钮 Copy Section

按钮应按操作优先级区分：

| 类型 | 使用场景 | 样式规则 |
| --- | --- | --- |
| 主按钮 | 页面主操作、确认提交 | 使用主色背景或 Ant Design primary，不在同一区域放多个主按钮 |
| 次按钮 | 返回、取消、普通操作 | 使用中性边框和浅背景，hover 只增强边框或背景 |
| 文本/链接按钮 | 表格行内操作、轻量入口 | 保持轻量，不扩大视觉权重 |
| 危险按钮 | 删除、撤销、清空等不可逆操作 | 使用 error 语义色，并配合确认弹窗或明确文案 |
| 图标按钮 | 工具栏、折叠、刷新、复制 | 使用 lucide-icon-btn 保证图标与文本居中 |

交互状态：

- hover 可以改变 background、border-color、color，不要位移或放大。
- focus 必须可见，不能移除键盘焦点样式。
- disabled 使用弱化文本和背景，不绑定 hover 强反馈。
- loading 应保留按钮宽度，避免布局跳动。

输入框与表单 Copy Section

表单用于配置和管理任务，优先保证可读性和错误可恢复：

- 输入框背景使用 --gray-0 或 Ant Design 默认容器色。
- 边框使用 --gray-150 / --gray-200，focus 使用主色或框架默认 focus ring。
- label 必须稳定显示，helper text 放在输入框下方。
- 错误信息使用 --color-error-*，并写清楚修复方式。
- 多字段表单按逻辑分组，避免把无关设置塞进同一行。
- 参数名称应说明业务含义和单位；非显然参数补充调整影响、推荐范围或示例。
- 只允许用户修改真正属于业务配置的值。官方端点、内部枚举和部署参数由系统管理，不伪装成普通输入项。

卡片、列表与表格 Copy Section

Yuxi 的信息界面以配置卡片、列表和表格为主，默认使用轻量分层：

- 普通卡片：background: var(--gray-0); border: 1px solid var(--gray-150); border-radius: 8px;
- 次级区域：可使用 var(--gray-10) / var(--gray-25) 做轻背景。
- 点击态列表行：hover 只改变背景或边框，不使用 transform。
- 表格行内操作保持紧凑，避免每行出现多个高权重按钮。
- 空状态要说明“当前没有什么”和“下一步可以做什么”，不要只显示图标。

阴影只用于真实浮层，如弹窗、抽屉、下拉菜单、tooltip。普通卡片和列表不要用阴影制造装饰性层级。

#### 列表、状态与操作

- 摘要层按“名称 → 用途或关键差异 → 需关注状态 → 操作”组织，不机械展示名称、ID、类型和全部状态。
- 内部 ID 默认隐藏；确需展示时放入详情，使用 monospace 和明确标签或复制入口。
- 一个状态只保留一种主要表达。开关已经表达启用状态时，不再增加绿色点和“已启用”文字。
- 正常状态保持安静，只突出异常和需要行动的状态；颜色不能作为唯一信息载体。
- “不启用”“自动”“沿用默认”等策略放在选择器或策略区，不伪装成普通资源项。
- 开关默认表示立即生效。需要统一保存时，应明确显示未保存状态，不能混用两种提交模型。
- 同类行共享稳定的展开、文本、状态和操作列。图标使用固定盒、统一 gap 和 line-height，右侧操作保持同一边界。
- 配置列表优先使用一个列表容器和轻分割线，避免每行形成厚重卡片；展开内容与触发行保持连续。
- 至少在真实页面的目标宽度、1024px、768px 和 375px 检查对齐、长文本和溢出。

状态标签 Copy Section

状态标签使用语义色浅背景 + 深文字：

| 状态 | 推荐 token |
| --- | --- |
| 成功/正常 | --color-success-50 + --color-success-700 |
| 失败/错误 | --color-error-50 + --color-error-700 |
| 警告/待处理 | --color-warning-50 + --color-warning-900 |
| 信息/运行中 | --color-info-50 + --color-info-700 |
| 普通/未知 | --gray-100 + --gray-600 |

标签可以使用 pill 圆角，但不要把 pill 形状扩散到所有按钮和卡片。

图标 Copy Section

- 常规图标尺寸使用 16px、18px 或 20px。
- 图标颜色默认继承文本色；需要强调时使用语义 token。
- 图标按钮添加 lucide-icon-btn，避免图标与文本或按钮中心线错位。
- 不为同一概念混用多个图标；相同操作在不同页面保持一致。

5. 布局与间距 Copy Chapter

间距以 4px / 8px 为基础节奏：

| 场景 | 建议值 |
| --- | --- |
| 图标与文本间距 | 6px / 8px |
| 表单项内部间距 | 6px / 8px |
| 卡片内部 padding | 16px / 20px / 24px |
| 列表行间距 | 8px / 12px |
| 页面主要区块间距 | 24px / 32px |
| 弹窗内容区间距 | 16px / 24px |

布局原则：

- 配置型页面保持适度信息密度，不做大面积营销式留白。
- 相邻操作靠近对应内容，页面级操作放在标题区或工具栏。
- 一组按钮中主操作在视觉上最明确，取消/返回等次操作弱化。
- 宽屏下限制正文行长，避免说明文字横跨整个页面。
- 小屏下优先纵向堆叠，避免强行压缩表格和表单字段。

6. 深度与层级 Copy Chapter

Yuxi 默认采用“背景 + 边框”的轻量层级：

| 层级 | 处理方式 | 使用场景 |
| --- | --- | --- |
| 页面背景 | var(--gray-0) 或布局已有背景 | 主页面 |
| 次级背景 | var(--gray-10) / var(--gray-25) | 分区、弱提示、列表 hover |
| 卡片边界 | 1px solid var(--gray-150)，8px 圆角 | 配置卡片、内容块 |
| 浮层 | 框架默认阴影或轻量 --shadow-* | 弹窗、抽屉、dropdown、tooltip |
| 焦点 | 主色 outline / Ant Design focus ring | 键盘可达控件 |

不要在普通内容卡片上使用重阴影。只有当元素真实覆盖其他内容、需要表达浮层关系时，才允许使用阴影。

7. Do / Don't Copy Chapter

Do Copy Section

- 使用 base.css 和 base.dark.css 中的 token。
- 为新增交互补齐 hover、focus、disabled、loading、empty、error 等必要状态。
- 用背景、边框、字号、间距建立层级。
- 保持浅色和暗色模式一致可用。
- 复用 lucide-vue-next、Ant Design Vue 和项目已有组件模式。
- 在复杂配置区保留简短说明，帮助用户理解设置影响。

Don't Copy Section

- 不要在 hover 时使用位移、放大、旋转等装饰性 transform。
- 不要使用浓重阴影装饰普通卡片。
- 不要使用夸张渐变或大面积高饱和背景。
- 不要把语义色用于纯装饰。
- 不要新增一次性 helper、样式体系或无复用价值的抽象。
- 不要硬编码浅色模式色值导致暗色模式失效。
- 不要在同一区域放置多个同等视觉权重的主操作。

8. 响应式行为 Copy Chapter

响应式设计以“功能不丢失、信息不挤压”为优先：

- 小屏下表单字段纵向排列，按钮组可换行。
- 侧栏、抽屉和弹窗要保证最小宽度内内容可读。
- 表格在小屏下允许横向滚动；不要把关键字段压缩到不可读。
- 图标按钮和主要操作需要保持可点击区域，移动端目标尺寸尽量不小于 40px。
- 长文本使用省略号时，应提供 tooltip、title 或详情入口查看完整内容。
- 图谱、图表、代码块等宽内容应保留横向滚动或自适应缩放策略。

9. 设计交付与审阅流程 Copy Chapter

UI/UX 质量不能只由构建通过和没有溢出证明。交付前按三层审阅：

1. 产品层：每个元素是否有价值，概念是否符合用户心智，是否暴露无用实现细节。
2. 交互层：操作是否可发现，生效时机是否明确，失败能否恢复，状态是否一致。
3. 视觉层：层级、对齐、间距、文字、图标、颜色和响应式是否精确一致。

UI 修改必须提供真实运行页面截图，覆盖核心状态和至少一个边界状态。使用真实数据检查长名称、加载、错误、空状态、浅色/暗色和关键响应式宽度；未验证内容在交付说明中列出。

10. Agent Prompt Guide Copy Chapter

AI agent 修改或生成 Yuxi UI 时，优先按这一节执行。

Quick Reference Copy Section

- 页面背景：var(--gray-0)
- 次级背景：var(--gray-10) / var(--gray-25)
- 主要文本：var(--color-text) 或 var(--gray-900)
- 次级文本：var(--color-text-secondary) 或 var(--gray-600)
- 边框：var(--gray-150) / var(--gray-200)
- 主色：var(--main-color)
- 卡片圆角：8px
- 小控件圆角：4px / 6px
- 状态标签圆角：999px
- 常规图标尺寸：16px / 18px / 20px
- 卡片 padding：16px / 20px / 24px
- 普通 hover：只改变背景、边框或文字颜色

Example Prompts Copy Section

实现配置卡片：

实现一个 Yuxi 风格的配置卡片：背景使用 var(--gray-0)，边框 1px solid var(--gray-150)，圆角 8px，不加阴影。标题使用 var(--color-text)，说明文字使用 var(--color-text-secondary)。hover 只轻微改变边框或背景，不使用 transform。

实现工具栏按钮：

实现一个工具栏按钮：优先使用 lucide-vue-next 图标，图标尺寸 16px，按钮添加 lucide-icon-btn。默认使用中性色，hover 时使用 var(--main-color) 或 var(--main-10) 强化，不位移、不放大。

实现状态标签：

实现状态标签：成功使用 var(--color-success-50) 背景和 var(--color-success-700) 文字；错误使用 var(--color-error-50) 背景和 var(--color-error-700) 文字；警告使用 var(--color-warning-50) 背景和 var(--color-warning-900) 文字。圆角使用 999px，文字保持 12px。

实现检查清单 Copy Section

- 已说明用户任务、信息层级和提交模型。
- 没有平铺无用字段、重复状态或伪装成资源的策略项。
- 名称和描述使用用户语言，内部 ID 仅按需展示。
- 图标、文字、输入框和操作列已完成视觉对齐检查。
- 使用现有 CSS 变量，没有新增随意硬编码色值。
- 浅色和暗色模式都检查过。
- hover、focus、disabled、loading、empty、error 状态符合场景。
- 没有使用 hover 位移、放大、旋转或装饰性动画。
- 普通卡片没有使用重阴影。
- 图标来自 lucide-vue-next，尺寸和对齐符合现有模式。
- API 接口、组件位置、样式语言符合前端开发规范。
- 已在真实页面和关键响应式宽度截图验收，而不只依赖构建通过。

参考资料 Copy Chapter

- web/src/assets/css/base.css：浅色模式 token
- web/src/assets/css/base.dark.css：暗色模式 token
- web/src/assets/css/main.css：全局字体、布局基础样式和 lucide-icon-btn
- Awesome DESIGN.md：面向 AI agent 的 DESIGN.md 样例集合

---

Develop Guides/Roadmap Copy Section

开发路线图

路线图可能会经常变更，如果有强烈的建议，可以在 issue 中提。

项目看板（Maintainer Only）：GitHub Project


后续 0.8 的非兼容计划更新

1. Milvus 3.0 https://milvus.io/docs/zh/release_notes.md
2. API 和 Worker 等从文件系统解耦，分布式部署

看板 Copy Section

知识库
- [ ] 知识库 Mindmap 扩展：新增基于文件名的文件“边”构建，支持聚类算法形成社区节点，并提供思维导图 (Mindmap) 可视化结构展示
- [ ] 知识库工具新增 query_keywords 工具，专门用于基于关键词命中的排序
- [ ] 增强知识库检索体验：增强 metadata、标签等
- [ ] 个人工作区增加可检索能力（但是不做向量化）

智能体
- [ ] 子智能体缺少 steer 机制
- [ ] 子智能体的双向通信，缺少 ask_for_main_agent 的机制
- [ ] 子智能体与子智能体的通信机制

其他
- [ ] 集成 Memory，基于 deepagents 的文件后端实现，需要考虑定位
- [ ] 优化 Agent 向用户追问交互：支持较长文本回答输入，并在流式输出时保持聊天区跟随最新内容（#753）

Bugs Copy Section

- backend/test/unit
- 纯单元测试
- 不依赖运行中的 Docker 服务
- 优先使用 monkeypatch、fake repo、stub、tmp_path

- backend/test/integration
- 真实 API 集成测试
- 依赖 docker compose up -d 后的运行环境
- 统一通过真实 HTTP 接口验证认证、权限、参数和副作用

- backend/test/e2e
- 关键链路端到端测试
- 覆盖 run、viewer、附件、文件落盘等完整流程
- 默认数量少、执行更慢

其他子项目约定：

- 前端单元测试统一放在 web/test/unit，通过 pnpm test:unit 运行。
- packages/yuxi-cli 是独立 Python 包，沿用 Python 社区惯例放在 packages/yuxi-cli/tests。
- 同一个子项目内不要同时创建 test 和 tests 两个测试根目录。

2. 新增测试时怎么选目录 Copy Chapter

新增测试前先判断：

1. 只测 Python 逻辑，不需要真实服务
放到 unit

2. 需要请求真实接口
放到 integration/api

3. 需要验证从入口到最终结果的完整链路
放到 e2e

不要再默认把测试直接丢到 backend/test/ 根目录。

3. 文件和命名规范 Copy Chapter

文件名：

- 使用 test_<domain>_<target>.py
- 一个文件只测一个明确主题

函数名：

- 使用 test_<行为>_<预期结果>
- 名称直接表达业务语义

示例：

- test_create_agent_run_commits_before_enqueue
- test_viewer_download_returns_attachment_response
- test_agent_bubble_sort_run_creates_expected_artifacts

4. 写测试的基本要求 Copy Chapter

每个测试尽量保持三段式：

1. Arrange：准备数据、打桩、创建资源
2. Act：调用被测行为
3. Assert：断言结果

要求：

- 不要只断言 status_code == 200
- 要断言关键业务字段和副作用
- 失败信息要能帮助定位问题

5. fixture 规范 Copy Chapter

原则：

- 同一个文件内复用，优先写本地 helper
- 多个文件复用，再提取到对应层级的 conftest.py
- 根 backend/test/conftest.py 只保留通用 marker，不绑定真实环境

当前约定：

- backend/test/integration/conftest.py
- 管理 test_client、admin_headers、standard_user、knowledge_database

- backend/test/e2e/conftest.py
- 管理 e2e_client、e2e_headers、e2e_agent_context

6. 允许与禁止 Copy Chapter

允许：

- 在单元测试里使用 monkeypatch
- 在集成测试里通过 fixture 创建测试资源
- 在 E2E 中使用轮询等待最终状态

禁止：

- 在测试文件里硬编码真实账号密码
- 在单元测试里请求真实 HTTP 服务
- 在根 conftest.py 里继续添加重环境依赖
- 写 if __name__ == "__main__": 作为测试入口
- 用 print 作为通过/失败判断手段
- 因为系统里没有默认数据就直接 skip

7. skip 的使用规则 Copy Chapter

只在下面两类场景允许 pytest.skip：

1. 外部可选能力不可用
例如 OCR 服务、外部模型服务未启动

2. E2E 环境变量未配置
例如没有配置专用测试账号

不允许把“系统里没有 agent / config / 预置数据”当成正常 skip 条件。
这类情况应优先改为 fixture 显式准备资源，或者直接 fail 暴露环境问题。

8. 修改测试文件时的规则 Copy Chapter

如果是修 bug：

1. 先补一个能稳定复现 bug 的测试
2. 再修代码
3. 先跑最小相关测试集
4. 再跑相关层级回归

如果是改已有功能：

- 行为变了，就更新断言
- 文件职责混乱，就顺手拆分或迁移目录
- 依赖现成系统状态的测试，优先改成 fixture 建资源

9. 运行方式 Copy Chapter

启动环境：

docker compose up -d
docker ps
docker logs api-dev --tail 100

运行单元测试：

docker compose exec api uv run --group test pytest test/unit -m "not slow"

运行集成测试：

docker compose exec api uv run --group test pytest test/integration

运行 E2E：

docker compose exec api uv run --group test pytest test/e2e -m e2e

运行全部测试：

docker compose exec api uv run --group test pytest test

也可以使用：

backend/test/run_tests.sh unit
backend/test/run_tests.sh integration
backend/test/run_tests.sh e2e
backend/test/run_tests.sh all

运行前端单元测试：

docker compose exec web pnpm test:unit

10. 推荐的日常开发流程 Copy Chapter

建议顺序：

1. 本地改代码
2. 先跑相关单元测试
3. 涉及接口时跑相关集成测试
4. 涉及关键主链路时补跑对应 E2E
5. 提交前至少完成“检查 -> 测试 -> Lint”

11. 当前落地原则 Copy Chapter

这套规范的重点不是一步到位重写所有旧测试，而是：

- 新增测试必须按新目录落位
- 改到旧测试时顺手迁移
- 优先保持测试可执行和可信
- 优先减少假绿和环境耦合

对当前 Yuxi 来说，这就是最务实、也最容易持续执行的测试标准。

---

Agents/Agent Evaluation Copy Section

智能体评估

Yuxi 的智能体评估用于回答一个具体问题：某个 Agent 在一组固定任务上能不能稳定完成工作。它不在 Yuxi 内部维护评估数据集、评分规则或对比报表，而是把这些能力交给 Langfuse；Yuxi 只负责按真实 Agent 运行链路执行每条样例，并把结果回写到 Langfuse experiment。

适用边界 Copy Chapter

这个功能面向 Agent 端到端行为评估，不是知识库检索指标评估。如果你要评估 RAG 检索召回、答案准确率和知识库基准，请使用「知识库评估」。如果你要评估一个 Agent 在编程、研究、工具调用、规划或多步骤任务上的真实表现，则使用本页介绍的 Langfuse dataset experiment 流程。

评估链路保持三个边界：

- Langfuse 负责 dataset、experiment、score、对比和可视化。
- Yuxi 后端负责创建正常 conversation 和 AgentRun，并复用 worker 执行链路。
- yuxi CLI 只负责读取 Langfuse dataset、运行 experiment、调用 Yuxi eval API，不负责创建或上传 dataset。

前置条件 Copy Chapter

1. Yuxi 后端已经启用 Langfuse tracing，并在 .env 中配置：

LANGFUSE_PUBLIC_KEY=...
LANGFUSE_SECRET_KEY=...
LANGFUSE_BASE_URL=https://cloud.langfuse.com

2. 本机 CLI 环境也能读取同一组 Langfuse 环境变量。yuxi agent eval 需要直接调用 Langfuse SDK 读取 dataset 和创建 experiment。

3. 已经登录 Yuxi CLI：

yuxi remote add local http://localhost:5173
yuxi login --browser

评估命令必须使用当前 remote 的登录态，不支持在 yuxi agent eval 上直接传 token。CI 环境也必须先执行登录步骤，例如：

yuxi login --api-key "$YUXI_API_KEY"

4. 要评估的 Agent 已经存在，并且当前 CLI 登录用户有权限访问该 Agent。命令使用的是 Agent slug，例如 default-chatbot。

准备 Langfuse Dataset Copy Chapter

评估数据集必须先在 Langfuse 中准备好。CLI 不提供上传能力，避免把数据集管理职责混进运行命令。

Dataset item 的 input 推荐使用下面任一字段承载任务文本：

{"input": "请用 Python 完成任务并给出最终答案：..."}

也兼容 query、question、prompt。expected_output 可以写标准答案，后续在 Langfuse UI 或 evaluator 中使用。

运行评估 Copy Chapter

上传 dataset 后，用 dataset name 运行：

yuxi agent eval \
  --dataset-name yuxi-python-tasks-20260619-demo \
  --agent-slug default-chatbot \
  --experiment-name default-chatbot-python-tasks-20260619 \
  --max-concurrency 1 \
  --timeout-seconds 900

命令执行流程：

1. 从 Langfuse 读取 dataset。
2. 对每条 dataset item 提取任务文本。
3. 调用 POST /api/agent-invocation/eval/runs。
4. Yuxi 后端创建正常 conversation 和 AgentRun。
5. worker 按真实 Agent 链路执行任务。
6. 接口阻塞到 run 终态后返回最终 assistant output。
7. CLI 将 output 写回 Langfuse experiment item。

--max-concurrency 控制 Langfuse experiment runner 的并发数。复杂 Agent 或本地开发环境建议从 1 开始，避免同时压垮模型服务、worker 或沙盒。

查看结果 Copy Chapter

评估完成后，在 Langfuse 控制台打开对应 dataset，可以看到刚创建的 experiment run。每条 item 会保存本次 Yuxi Agent 的最终输出。Yuxi 后端会在运行内部使用 agent_invocation_meta.evaluation 保存评估上下文，并给 Langfuse trace 写入 agent_evaluation 标记，方便筛选：

- source=agent_evaluation
- evaluation_dataset_name=<dataset name>
- evaluation_dataset_item_id=<item id>
- evaluation_experiment_name=<experiment name>

如果没有看到 experiment，先确认 CLI 环境中的 Langfuse key 和 dataset name 是否正确。如果 experiment 有记录但 Yuxi trace 缺失，检查 api-dev 容器是否读取到了同一组 Langfuse 配置。

---

Agents/Agent Request Queue Copy Section

Agent 请求队列与调度设计

Agent 运行可能包含模型调用、知识库检索、工具执行和文件读写，持续时间通常高于普通接口请求。在一次运行尚未结束时，同一对话线程可能收到新的用户输入或外部调用。请求队列用于接收这些请求，并控制它们进入 Agent 执行链路的顺序。

本文介绍 Yuxi Agent 请求队列的设计目标、调度规则、状态变化和当前功能边界。具体接口、数据表和事务实现不在本文展开。

设计目标 Copy Chapter

请求队列主要处理以下问题：

- 同一对话线程内的多个请求不应并发修改同一份对话上下文。
- Agent 运行期间仍可接收后续请求，不要求调用方等待当前运行结束后再次提交。
- 排队状态需要持久化，页面刷新或服务恢复后仍可查询。
- 调用方需要区分“请求已接收”和“Agent 已开始运行”。
- 网页聊天和同步 API 对忙碌线程的处理方式不同，需要提供明确的策略选择。

请求队列不负责提高单次 Agent 运行速度，也不改变 Agent 内部的模型和工具执行方式。它负责确定请求何时进入现有的运行链路。

调度范围 Copy Chapter

队列以用户、Agent 和对话线程共同确定的执行范围为单位。同一范围内最多存在一个活跃的 Agent 运行，后续请求按提交顺序等待。

不同对话线程拥有独立的调度范围，可以并行运行。例如，一个用户在两个不同对话中分别提交任务，两条线程不会因为队列而相互阻塞。

线程一：请求 A（运行中） -> 请求 B（队列第 1 位） -> 请求 C（队列第 2 位）
线程二：请求 D（运行中） -> 请求 E（队列第 1 位）

普通请求采用 FIFO（先入先出）规则。顺序以服务端记录的创建时间和稳定顺序字段为准，不依赖浏览器时间；待处理的 Steer 会成为下一条请求，其余请求之间仍保持 FIFO。

请求与运行 Copy Chapter

Yuxi 将 Agent 请求和 Agent 运行作为两个不同阶段处理。

Agent 请求表示系统已经接收了一次输入。请求在提交时创建，可处于排队、已派发、已取消或已拒绝等状态。

Agent 运行表示请求已经获得执行机会，并进入实际的 Agent 执行链路。只有请求被派发后，才会创建对应运行。

这种划分主要有三项作用：

1. 排队请求可以独立查询和取消。
2. 页面刷新后可以恢复队列，而不依赖前端内存状态。
3. 排队中的用户消息不会提前进入当前 Agent 运行的上下文。

第三点用于保证对话顺序。假设请求 A 正在运行，请求 B 和 C 已经排队，A 对应的 Agent 上下文不会提前包含 B 和 C。B 被派发后，其输入才会成为下一轮 Agent 运行的一部分。

调度过程 Copy Chapter

一次普通请求的处理过程如下：

1. 系统接收输入并创建请求记录。
2. 如果线程当前空闲，请求立即派发并创建 Agent 运行。
3. 如果请求不能立即成为并派发 FIFO 队头，请求根据队列策略进入等待或被拒绝。
4. 运行成功结束后，调度器检查同一线程的队头请求。
5. 如果存在排队请求，队头请求被派发，其他请求的位置相应前移。

同一请求不会因为客户端重试而重复排队。调用方使用相同请求 ID 重试时，系统返回已有请求及其运行状态。请求 ID 被其他用户或不匹配的目标复用时，应作为冲突处理。

队列策略 Copy Chapter

当前支持 enqueue、reject 和 steer 三种策略。

| 策略 | 线程空闲 | 线程忙碌 | 主要适用场景 |
| --- | --- | --- | --- |
| enqueue | 立即派发 | 保存并进入 FIFO 队列 | 网页聊天、异步 Agent Call |
| reject | 立即派发 | 返回拒绝结果，不进入队列 | 同步 Agent Call、需要立即决策的调用方 |
| steer | 立即派发 | 当前步骤结束后优先执行 | 运行中修正后续方向 |

enqueue Copy Section

enqueue 用于允许延后执行的请求。请求排队后，调用方可以读取其当前位置，也可以在派发前取消。

网页聊天默认采用该策略，因此当前回复生成期间仍可提交后续输入。排队请求与当前回复分开展示，避免尚未执行的输入提前出现在对话正文中。

reject Copy Section

reject 用于不接受排队的调用。只要请求不能立即成为并派发 FIFO 队头，系统就记录并返回拒绝状态，不创建 Agent 运行。这包括线程忙碌、已有积压请求、队列因失败或取消暂停，以及运行正在等待人工回答的情况。

同步 Agent Call 默认采用该策略。同步调用会等待最终运行结果，如果允许其进入队列，请求等待时间将同时包含排队和执行两个阶段。因此，同步入口通过明确拒绝，使调用方可以自行决定重试、切换线程或终止本次调用。

拒绝是预期的调度结果，不属于服务器内部错误。

steer Copy Section

steer 是 enqueue 的优先执行形式，不引入新的请求或运行状态。请求仍以 queued 保存；Chatbot Middleware 在下一次模型调用前发现待处理 Steer 时结束当前 Graph，worker 按既有 completed 接力流程派发该请求。

因此，已经开始的模型调用和工具批次会正常完成并写入 checkpoint，Steer 不会强制取消工具。当前 Run 按普通 completed 结束，Steer 创建的新 Run 继续读取同一线程上下文。已有普通 Chat 排队项也可以原地提升为 Steer；同一线程一次只接受一个待处理 Steer。

Steer 意图采用持久化请求作为唯一事实来源，按以下生命周期边界消费，避免到达时机造成丢失：

1. 请求事务提交后，abefore_model 在下一次模型调用前检查待处理 Steer。
2. aafter_model 对不含工具调用的模型轮次再次检查，覆盖 Steer 恰好到达最后一次模型检查之后的窗口；含工具调用时不跳过工具批次。
3. 当前 Run 以 completed 结束后，worker 通过队列头派发 Steer；若进程在接力前退出，worker 启动恢复会重新扫描 queued 请求并执行同一派发逻辑。

这套兜底只保证 Steer 意图最终进入下一次 Run，不改变“已开始的模型调用和完整工具批次不可强制终止”的安全边界。

状态说明 Copy Chapter

请求和运行分别维护状态。请求状态用于描述排队阶段，运行状态用于描述实际执行阶段。

| 请求状态 | 说明 |
| --- | --- |
| queued | 请求已保存，正在等待派发 |
| dispatched | 请求已派发，并已关联 Agent 运行 |
| cancelled | 请求在派发前被取消 |
| rejected | 采用 reject 策略时因线程忙碌被拒绝 |
| failed | 请求在派发前处理失败 |

请求派发后，执行结果由 Agent 运行状态表达，例如完成、失败、取消或中断。前端在排队阶段订阅请求状态，在收到运行创建信息后切换到运行事件流。

取消处理 Copy Chapter

取消排队请求和停止 Agent 运行是两个独立操作。

- 排队请求尚未开始执行，可以单独取消。取消后不会影响当前活跃运行，后续请求的位置会重新计算。
- Steer 在等待活跃 Run 到达安全点时不能取消，避免取消操作与 Middleware 消费引导意图竞态；若目标 Run 失败或取消、队列进入暂停后，可以删除该 Steer。
- 已派发请求已经进入运行阶段，需要通过运行取消能力停止，不再通过队列取消接口处理。

这种区分可以避免取消一个排队项时误停当前运行，也可以保持请求状态与实际执行状态一致。

失败、中断与后续请求 Copy Chapter

Agent 运行成功完成后自动派发下一条请求。运行失败、被取消或进入需要人工处理的中断状态时，系统按以下规则处理后续请求：

- failed/cancelled 时已经在等待的请求会保持暂停。页面会展示原因，用户可以点击“继续队列”；该动作只派发当前 FIFO 队头。
- failed/cancelled 发生时队列为空，之后提交的新请求属于新的输入意图，可以正常立即执行。
- interrupted 表示当前运行正在等待回答或审批。中断前已经存在的排队请求继续保留；中断期间的新普通请求会在写入 Message/Request 前返回 run_interrupted，也不能通过“继续队列”绕过。用户完成 resume 后，既有队列才会按原有完成链路继续。

页面刷新后会恢复暂停原因和继续操作。若完成后的自动派发因短暂故障遗漏，系统会把该队列识别为待恢复状态并继续既有 completed 调度语义，而不会把仍有请求的队列视为已空闲。

持久化与恢复 Copy Chapter

请求、输入消息和派发关系保存在数据库中。浏览器刷新后，前端可以重新读取当前线程的排队请求和位置。

Agent 运行由后台任务系统执行。pending AgentRun 同时表达已经提交、仍需投递或等待 worker 接收的执行意图。为处理“数据库已经记录派发，但任务尚未成功投递”这一故障窗口，completed hook 重试和服务启动恢复都会优先重新投递已有 pending run；没有 pending run 时才会派发 ready 队头。恢复过程复用已有请求和运行记录，不创建重复运行。

同一对话线程的 intake、resume、continue 和自动接力会锁定线程对应的 Conversation 记录，再读取和修改 request/run 事实。线程级共同锁负责保证并发请求的严格 FIFO，active-run 唯一索引继续作为最终数据库保护。

持久化恢复保证的是调度状态可继续处理，不代表失败中的 Agent 运行会自动重新执行。具体是否重试由运行层的重试规则决定。

对话展示 Copy Chapter

排队区和对话正文承担不同职责：

- 排队区展示尚未开始的请求、当前位置和取消操作。
- 对话正文展示已经进入 Agent 运行的用户输入和回复。

请求派发后，其用户消息从排队状态转入对应运行轮次。多个请求的展示顺序与执行顺序一致，例如：

请求 A -> A 的回复 -> 请求 B -> B 的回复

排队中的 B 不会覆盖或打断正在生成的 A 的回复。

当前范围 Copy Chapter

当前版本包含以下能力：

- 普通聊天、异步 Agent Call 和评估入口使用统一请求接收流程。
- 支持 enqueue、reject 和主会话 Chat 的 steer 策略。
- 同一线程串行调度，不同线程可并行运行。
- 支持排队位置查询、页面刷新恢复和派发前取消。
- 请求派发后转入已有 Agent 运行与事件流链路。

当前版本不包含以下能力：

- 强制取消正在执行的模型或工具。
- 多个 Steer 的排序、合并或连续接替。
- 通用请求优先级和任意插队。
- 运行失败后的自动回滚。
- 多个请求合并为一次 Agent 运行。

这些能力涉及运行上下文、工具副作用和消息展示语义，需要在扩展队列策略时分别设计。

---

Agents/Agents Config Copy Section

智能体配置

Yuxi 的智能体系统基于 LangGraph 构建。对开发者来说，最重要的不是单独理解某个页面或某个字段，而是理解三件事：

- Agent 如何被定义和发现
- Context 如何驱动配置界面
- Context 如何贯穿一次 Agent 运行周期

本文聚焦这三部分。

1. 整体结构 Copy Chapter

智能体开发围绕四个核心对象展开：

- BaseAgent：统一的 Agent 抽象，定义 get_graph()、context_schema、capabilities
- BaseContext：配置 Schema，也是前端配置项的来源
- Graph / Middleware：LangGraph 图与中间件链，决定运行时行为
- Agent：数据库中的一级智能体实例，保存展示信息、后端 backend_id、共享权限和 config_json.context

仓库中已经内置了可直接参考的智能体：

- chatbot：通用对话智能体，使用 ChatBotContext 扩展可调用子智能体配置
- subagent：专用子智能体后端，使用 SubAgentContext，用于被主 Agent 通过 task 工具调用

2. Agent 的代码组织 Copy Chapter

建议在 backend/package/yuxi/agents 下按包组织一个智能体：

backend/package/yuxi/agents/
└── my_agent/
    ├── __init__.py
    ├── context.py
    └── graph.py

最小实现通常包含：

- 一个继承 BaseAgent 的主类
- 一个 context_schema
- 一个 get_graph() 实现

示例：

from yuxi.agents import BaseAgent, BaseContext, load_chat_model
from langchain.agents import create_agent

class MyAgent(BaseAgent):
    name = "我的智能体"
    description = "示例智能体"
    context_schema = BaseContext
    async def get_graph(self, context=None, kwargs):
        context = context or self.context_schema()
        graph = create_agent(
            model=load_chat_model(context.model),
            system_prompt=context.system_prompt,
            checkpointer=await self._get_checkpointer(),
        )
        return graph

3. Context 是配置模型，不只是运行时参数 Copy Chapter

3.1 BaseContext 的角色 的角色')" title="Copy section prompt for LLMs"> Copy Section

BaseContext 定义在 backend/package/yuxi/agents/context.py，它不是一个普通的数据类，而是整个智能体配置链路的核心：

- 它定义了 Agent 可以配置哪些字段
- 它定义了这些字段在前端如何展示
- 它也是运行期传入 Graph 和中间件的上下文对象

当前基础字段包括：

| 字段 | 作用 |
| --- | --- |
| system_prompt | 系统提示词 |
| model | 主模型 |
| tools | 启用的内置工具 |
| knowledges | 关联知识库 |
| mcps | 启用的 MCP 服务器 |
| skills | 关联 Skills |
| summary_threshold | 摘要触发阈值 |
| summary_prompt | 摘要触发时使用的提示词 |
| summary_keep_messages | 摘要后保留的最近消息数 |
| summary_tool_result_token_limit | 工具结果 offload 阈值和预览 token 上限 |
| summary_l2_trigger_ratio | L1 后进入 L2 summary 的触发比例 |
| max_execution_steps | 单次运行最大执行步数 |
| model_retry_times | 模型调用失败时的最大重试次数 |
| thread_id / uid | 运行期标识，不作为页面配置项暴露 |

tools、knowledges、mcps、skills 在未显式配置时会默认启用当前用户可访问的全部资源。

ChatBotContext 在 BaseContext 之上增加 subagents 字段，表示当前主 Agent 允许调用的子智能体。subagents 未显式配置或保存空列表时会默认启用当前用户可见的全部子智能体；显式选择后则作为允许列表过滤。

SubAgentContext 在 BaseContext 之上增加 parent_thread_id、file_thread_id、skills_thread_id 与 is_subagent_runtime 等隐藏运行态字段，不包含 subagents，因此子智能体不能继续配置下一层子智能体。

3.2 前端配置项如何从 Context 生成 Copy Section

BaseContext.get_configurable_items() 会遍历字段定义，把字段类型、默认值、描述、模板元数据整理成 configurable_items。

随后：

1. BaseAgent.get_info() 暴露 configurable_items
2. 前端读取 Agent 详情
3. AgentRuntimeConfigForm 按 kind 渲染不同控件

也就是说，AgentRuntimeConfigForm 不是手写每个字段，而是直接消费 context_schema 生成的配置描述。

这也是为什么：

- 新增一个 Context 字段，往往会直接影响侧边栏
- 字段的 metadata 信息会直接影响展示方式

3.3 配置表单与 Agent 的联动关系 Copy Section

这部分是最关键的。

在前端：

- AgentRuntimeConfigForm.vue 负责渲染配置表单
- agentStore 加载配置时，读取 config_json.context
- 如果某些字段未配置，会用 configurable_items 中的默认值补全
- 保存时，前端将当前表单写回 config_json: { context: agentConfig }

因此真实关系是：

context_schema
  -> get_configurable_items()
  -> Agent detail API 返回 configurable_items
  -> AgentRuntimeConfigForm 渲染表单
  -> 用户编辑后保存到 config_json.context

这里需要特别注意两点：

- 侧边栏展示结构来自 context_schema
- 配置实例值来自数据库中的 config_json.context

前者决定“能配什么、怎么展示”，后者决定“当前配置实际选了什么”。

3.4 自定义 Context 的推荐方式 Copy Section

如果某个智能体有额外配置，不要在前端单独加一套表单，而是直接扩展 Context：

from dataclasses import dataclass, field
from yuxi.agents import BaseContext

@dataclass(kw_only=True)
class MyAgentContext(BaseContext):
    custom_mode: str = field(
        default="default",
        metadata={
            "name": "运行模式",
            "description": "控制智能体的自定义行为",
            "options": ["default", "strict"],
        },
    )

然后在 Agent 中声明：

class MyAgent(BaseAgent):
    context_schema = MyAgentContext

这会同时影响：

- 后端可接收的配置结构
- 前端配置侧边栏的展示内容
- 运行期 context 可访问的字段

4. Context 如何贯穿 Agent 的运行周期 Copy Chapter

Context 的价值不只在“配置页面”。它贯穿了从配置加载到实际执行的整条链路。

4.1 配置加载阶段 Copy Section

在聊天请求进入后端时，服务会先解析请求中的 agent_id 或线程已绑定的 Agent，再加载对应配置。

当前主流程在 chat_service.py 中：

1. 新线程通过 agent_id 查找用户可访问的 Agent
2. 已有线程通过 thread_id 读取 Conversation.agent_id，并拒绝运行中切换 Agent
3. 取出 Agent 的 config_json.context
4. 与 uid、thread_id 合并成运行时输入

也就是说，运行期 Context 的基础来源并不是前端临时状态，而是数据库中保存的 Agent。

用户工作区会默认创建 agents/AGENTS.md、agents/USER.md 与 agents/MEMORY.md。每次 Agent 运行开始时，后端按这三个文件的固定顺序读取非空内容并追加到 system_prompt：前者适合放长期工作约束，USER.md 记录稳定的用户偏好，MEMORY.md 保存可跨对话复用的事实。它们属于用户级共享工作区；文件不存在、为空或不可读时不会阻断运行。每个文件最多读取 64 KiB，超出部分会截断并标记。

合并后的提示词结构可以理解为：

Agent.config_json.context.system_prompt
  + 用户工作区 agents/AGENTS.md、USER.md、MEMORY.md 内容
  + 运行期中间件继续追加的系统提示段

一次性要求仍应直接写在当前对话中，而不应写入这三个跨对话文件。

4.2 Context 实例化阶段 Copy Section

BaseAgent 在运行前会创建 context_schema() 实例，并通过 update_from_dict() 注入配置值。

这一步完成后，Context 才真正成为运行期对象。

可以把它理解为：

config_json.context + runtime ids -> context_schema instance

4.3 Graph 构建阶段 Copy Section

get_graph(context=context) 会收到这份 Context。

以内置 chatbot 为例，Context 会直接参与：

- 主模型选择：context.model
- 系统提示词拼接：context.system_prompt
- 可调用子智能体列表：context.subagents
- 摘要阈值：context.summary_threshold

因此 Graph 不是和 Context 解耦的。相反，Graph 的构造本身就依赖 Context。普通 Agent 在归一化后的 context.subagents 非空时会挂载 Yuxi 的 task middleware；SubAgentBackend 自身隐藏并清空 subagents 字段，因此子智能体不会继续调用子智能体。

4.4 Graph 构建与中间件运行阶段 Copy Section

get_graph() 创建 LangGraph 前会先调用 prepare_agent_runtime_context，用当前用户重新过滤资源字段，并派生运行时字段：

- _visible_knowledge_bases：当前会话实际可查询的知识库对象
- _prompt_skills：需要注入提示词的 Skill 闭包
- _readable_skills：当前运行时可读的 Skill 闭包，包括共享只读投影与个人工作区 Skill

随后 Graph 构建会直接使用这份 Context：

- load_chat_model(context.model) 选择主模型
- build_prompt_with_context(context) 生成系统提示词
- resolve_configured_runtime_tools(context) 组装已配置的内置工具和 MCP 工具
- SkillsMiddleware 根据 _prompt_skills 注入 Skill 提示段，并在 Skill 被激活后按需让模型看见其工具与 MCP 依赖；知识库工具由内置 knowledge-base Skill 提供
- save_attachments_to_fs 将线程附件转换为运行时可读的文件提示

文件系统与沙盒接入同样读取这些运行时字段：

- 普通 Agent 默认使用当前 thread_id 作为文件与 Skills 作用域
- 子智能体使用 child thread_id 做 checkpoint，file_thread_id 指向父会话 uploads/outputs，skills_thread_id 指向子智能体自身 Skills 作用域
- 通过 _readable_skills 与来源映射决定共享/内置 Skill 的 /home/gem/skills 投影；个人 Skill 直接读取工作区

所以 Context 既是输入配置，也是 Graph 创建前整理出的运行时资源上下文。

4.5 文件系统与 Viewer 阶段 Copy Section

文件系统服务不会重新发明一套配置结构，而是再次从 config_json.context 还原出 runtime context，用于：

- 判断当前线程下 Agent 可见的 Skills
- 构造 Agent 视图的 composite backend
- 构造 Viewer 视图的文件系统展示

这也是为什么 Context 不只是聊天链路的一部分，它还影响：

- Agent 文件工具
- Viewer 文件浏览器
- Skills 可见性
- 沙盒挂载语义

4.6 恢复运行阶段 Copy Section

在 resume 流程中，系统同样会通过线程绑定的 Agent 重新构造 Context，再继续执行 Graph。

也就是说，无论是：

- 首次对话
- 中断恢复
- 文件系统查看

它们都依赖同一份 Context 配置来源。

5. capabilities 的作用 的作用')" title="Copy chapter prompt for LLMs"> Copy Chapter

capabilities 用于声明前端可直接从 Agent 静态元数据判断的能力开关，控制上传入口、文件面板等固定 UI，不等同于 Context，也不适合表达运行中才会出现的状态。

示例：

class MyAgent(BaseAgent):
    capabilities = ["file_upload", "files"]

当前常见能力包括：

| capability | 说明 |
| --- | --- |
| file_upload | 启用上传入口 |
| files | 启用文件面板 |

像 todo 这类运行态信息，不建议再放进 capabilities。Yuxi 当前会直接从 LangGraph state 中提取 agent_state，前端在创建对话后常态化展示状态入口，并在状态面板中渲染 todos、files、artifacts、subagent_runs 等运行时内容。

它解决的是“Agent 先天支持什么固定入口”，而不是“运行时当前产生了什么状态”。

6. 开发建议 Copy Chapter

6.1 新增配置时优先改 Context Copy Section

如果一个配置项会影响 Agent 行为，优先考虑把它做成 context_schema 字段，而不是前端单独维护状态。

6.2 把 Graph 逻辑和配置逻辑分开 Copy Section

推荐做法：

- context.py 定义配置模型
- graph.py 使用这些配置构建 Graph

这样前后端联动关系会清晰很多。

6.3 把“配置来源”和“运行时状态”区分开 Copy Section

建议始终区分两层语义：

- config_json.context：持久化配置来源
- runtime.context：实际运行对象，可能被中间件继续补充或修改

7. 相关主题 Copy Chapter

- 工具系统
- 中间件
- 沙盒架构与设计
- MCP 集成
- Skills 管理
- 子智能体
- Langfuse 集成

---

Agents/Mcp Integration Copy Section

MCP 集成

MCP（Model Context Protocol）是扩展智能体能力的重要方式。系统支持通过管理界面动态配置 MCP 服务器，无需修改代码。

内置 MCP 服务器以代码为事实源：系统启动时会自动补齐缺失项，并用代码中的最新连接与展示字段覆盖数据库定义；是否“已添加”以及工具级禁用列表仍保留数据库状态。

支持的传输协议 Copy Chapter

| 协议 | 说明 | 适用场景 |
|------|------|----------|
| Streamable HTTP | 流式 HTTP 连接 | 远程 MCP 服务 |
| SSE | Server-Sent Events | 标准 HTTP 长连接 |
| Stdio | 标准输入输出 | 仅限代码中维护的系统内置 MCP |

配置示例 Copy Chapter

远程 MCP 服务 Copy Section

{
    "name": "custom-remote-mcp",
    "transport": "streamable_http",
    "url": "https://example.com/mcp"
}

管理接口只允许配置 streamable_http 与 sse 远程服务。stdio 会在 API / worker 容器内启动本地进程，
因此仅允许 _DEFAULT_MCP_SERVERS 中代码定义的系统内置 MCP；管理员不能通过接口新增 stdio 服务，
也不能修改内置 MCP 的连接配置。升级前已保存的用户 stdio 配置会被禁用，需要迁移为远程 MCP。

添加系统内置 stdio MCP Copy Chapter

只有经过代码审查、确实需要在 Yuxi 容器内启动本地进程的 MCP 才应使用 stdio。能够部署为远程服务时，
优先使用 SSE 或 Streamable HTTP，通过管理界面添加即可。

编辑 backend/package/yuxi/agents/mcp/service.py 中的 _DEFAULT_MCP_SERVERS，新增一个全局唯一的 slug。
下面的包名和版本仅作结构参考，实际提交时应替换为经过审查并固定版本的 MCP 包：

_DEFAULT_MCP_SERVERS = {
    # 已有内置 MCP ...
    "example-mcp": {
        "command": "npx",
        "args": ["-y", "@scope/[email protected]"],
        "transport": "stdio",
        "description": "示例内置 MCP，请替换为真实用途说明",
        "icon": "🧩",
        "tags": ["内置", "示例"],
    },
}

常用字段如下：

| 字段 | 要求 |
|------|------|
| command | 容器内已安装或明确可用的可执行程序，不接受用户输入 |
| args | 固定参数列表；使用包执行器时应固定包版本，不使用动态脚本参数 |
| transport | 固定为 stdio |
| description | 说明 MCP 的具体能力和使用场景 |
| icon / tags | 管理界面的展示信息 |
| env | 仅允许非敏感固定值；密钥不得提交到代码或同步进数据库 |

新增 slug 前应确认数据库和 _DEFAULT_MCP_SERVERS 中没有同名项。运行时只信任
_DEFAULT_MCP_SERVERS 的固定 slug 白名单；created_by 仅用于审计，不能通过复用用户记录或手工修改
created_by 来创建内置 MCP。

开发环境会在 API / worker 热重载后的启动阶段调用 ensure_builtin_mcp_servers_in_db()；生产部署需要重新
构建并启动 API 与 worker。新内置项首次同步时默认 enabled=false，管理员需要在 MCP 管理页中“添加”后
才会进入运行时。后续启动会用代码定义覆盖连接与展示字段，同时保留启用状态和工具禁用列表。

添加后执行一次验证：

docker compose up -d --build api worker
docker logs api-dev --tail 100
docker logs worker-dev --tail 100

确认日志中没有同步异常，并在管理页添加该 MCP，检查能够发现预期工具。验证过程不得执行文件写入、
Shell 命令或其他无关副作用。

::: danger 安全边界
stdio MCP 与在 API / worker 容器内执行程序等价。提交前必须审查可执行程序、依赖来源、固定版本、参数、
网络访问和工具副作用；不得从 HTTP 请求、数据库用户配置或环境中的非受信任内容拼接 command、args
或 env，也不得通过把用户记录改成 created_by=system 绕过运行时限制。
:::

服务器管理 Copy Chapter

管理界面使用“添加 / 移除”语义管理 MCP 服务器：

- 已添加：enabled=true；远程 MCP 读取数据库中的最新连接配置，内置 stdio MCP 使用代码中的固定连接配置
- 可添加：enabled=false，记录保留但不会进入运行时

Agent 配置中的 mcps 决定本次运行可使用哪些已添加服务器；未显式配置时使用当前用户可见的全部服务器。工具对象会按配置哈希做本地缓存，更新服务器配置后会自动使用新的缓存键，不需要重启服务。

工具管理 Copy Chapter

MCP 工具支持粒度控制：管理员可以单独启用或禁用某个 MCP 服务器下的特定工具，实现精细化的权限管理。

---

Agents/Middleware Copy Section

中间件系统

中间件是 Yuxi 扩展智能体运行行为的主要机制。它工作在 LangGraph Agent 的模型调用、工具调用、状态更新和文件系统访问路径上，用来把知识库、Skills、附件、子智能体、上下文压缩和运行观测接入同一条执行链路。

内置 ChatbotAgent 与 SubAgentBackend 都会在 get_graph() 中构建中间件列表。运行前的资源过滤不再依赖旧版运行时配置中间件，而是在创建 Graph 前由 prepare_agent_runtime_context 完成。

运行时准备 Copy Chapter

运行时准备不是中间件，但它决定后续中间件能看到什么资源。内置 Agent 创建 Graph 前会先执行以下步骤：

- prepare_agent_runtime_context：按当前用户权限过滤工具、知识库、MCP、Skills 和子智能体，并派生 _visible_knowledge_bases、_prompt_skills、_readable_skills 与最终 _runtime_skill_sources
- build_prompt_with_context：基于 Context 生成系统提示词
- load_chat_model(context.model)：加载主模型
- resolve_configured_runtime_tools(context)：加载已配置的内置工具和 MCP 工具

这意味着中间件不负责重新判断“用户是否能访问某个资源”。它们消费的是已经归一化后的 runtime context。

内置中间件链路 Copy Chapter

当前内置 ChatbotAgent 的中间件顺序如下：

| 中间件 | 作用 |
| --- | --- |
| create_agent_filesystem_middleware | 接入沙盒文件系统、用户工作区、线程 uploads/outputs 与只读 Skills 路由，并在工具结果过大时把内容写入 outputs/large_tool_results |
| save_attachments_to_fs / AttachmentMiddleware | 从 LangGraph state 的 uploads 读取附件路径，把可读路径注入系统提示，提示模型按需使用 read_file |
| SkillsMiddleware | 注入可见 Skill 的提示段，监听读取 SKILL.md 后的 Skill 激活，并按依赖追加工具和 MCP 工具；知识库工具由内置 knowledge-base Skill 按需加载 |
| YuxiSubAgentMiddleware | 仅主 Agent 在存在可见子智能体时挂载，提供 task 工具调用真实子 Agent graph |
| YuxiSummarizationMiddleware | 基于 DeepAgents SummarizationMiddleware 做长上下文压缩，并清洗被摘要历史里的工具结果 |
| TodoListMiddleware | 提供待办状态，让前端状态面板可展示 Agent 运行进度 |
| PatchToolCallsMiddleware | 修正部分工具调用消息形态，提升工具调用兼容性 |
| ModelRetryMiddleware | 在模型调用失败时按配置重试 |
| ImageInputCompatibilityMiddleware | 仅为 OpenAI Chat Completions 兼容链路桥接 read_file 返回的图片；模型明确拒绝图片输入时自动改为 ocr_parse_file |
| TokenUsageMiddleware | 在 LangGraph state 写入近似上下文、本次与线程累计的 Provider 实际 token 用量、模型标识和缓存命中率，供前端状态面板查看 |

SubAgentBackend 使用同一组核心能力，但不会挂载 YuxiSubAgentMiddleware，并额外过滤 present_artifacts、ask_user_question、install_skill 等不适合子智能体直接使用的工具。

知识库工具 Copy Chapter

知识库访问能力沉淀为内置 knowledge-base Skill。Agent 读取 /home/gem/skills/knowledge-base/SKILL.md 激活该 Skill 后，SkillsMiddleware 会按依赖追加 list_kbs、query_kb、find_kb_document、open_kb_document、get_mindmap 等知识库工具。

实际可见知识库仍由 prepare_agent_runtime_context 根据当前用户和 Agent 配置写入 _visible_knowledge_bases，工具执行时只会在这批知识库中检索。context.knowledges 是资源范围，不是 Skill 本身。

系统不会把知识库文件树挂进沙盒。Agent 访问知识库内容应使用 query_kb、find_kb_document 和 open_kb_document，而不是遍历 /home/gem/kbs 这类旧路径。

Skills 注入与激活 Copy Chapter

SkillsMiddleware 分两步工作：

1. 模型调用前读取 _prompt_skills，把可见 Skill 的名称、描述和 SKILL.md 路径追加到系统提示。
2. 工具调用后检查模型是否读取了共享路径 /home/gem/skills/<slug>/SKILL.md 或个人路径
/home/gem/user-data/workspace/agents/skills/<slug>/SKILL.md。如果该 Skill 在 _readable_skills
范围内，就把它写入 activated_skills，并在后续模型调用中追加它声明的工具和 MCP 依赖。

这种设计让 Skill 可以先作为说明可见，只有模型真正读取并激活后才扩展工具集，避免一开始就把所有依赖工具塞进上下文。

附件与文件系统 Copy Chapter

附件上传后会先落盘到线程文件系统，并在 LangGraph state 中记录 uploads。AttachmentMiddleware 只把文件名和可读路径注入提示词，不会把文件内容整体塞进模型上下文。模型需要查看附件时，应通过 read_file 读取对应路径。

文件系统中间件负责把 sandbox backend、线程 uploads/outputs、用户工作区和只读 Skills 组合成 Agent 可访问的虚拟文件系统。普通 Agent 默认使用当前 thread_id 作为文件作用域；子智能体使用 child thread_id 做 checkpoint，同时沿用父线程的 uploads/outputs，并使用子 Agent 自己的 Skills 作用域。

子智能体任务 Copy Chapter

主 Agent 如果配置了可见子智能体，会挂载 YuxiSubAgentMiddleware 并获得 task 工具。这个工具不会调用旧版独立 SubAgents 表，而是查找 agents.is_subagent=true 且后端为 SubAgentBackend 的真实 Agent 配置，然后启动对应子 Agent graph。

子智能体执行时会获得独立 child thread、独立 checkpoint 和 agent_runs(run_type=subagent) 记录；工具结果会返回 child thread ID，后续可以把该 ID 传回 task 继续同一个子任务。子智能体自身不会再挂载下一层 task 中间件，避免形成嵌套子智能体链路。

Summary 上下文压缩 Copy Chapter

长对话压缩由 Yuxi 封装的 YuxiSummarizationMiddleware 负责。它基于 DeepAgents 的 SummarizationMiddleware，但针对 Yuxi 的知识库检索和工具调用结果做了额外处理。

触发条件来自 Agent Context：

| 字段 | 说明 |
| --- | --- |
| summary_threshold | 上下文超过该 K token 阈值后触发摘要；L2 摘要模型的待摘要历史输入上限也使用同一阈值 |
| summary_keep_messages | 摘要后保留最近消息数 |
| summary_prompt | 摘要模型使用的提示词 |
| summary_tool_result_token_limit | 工具结果 offload 阈值和预览 token 上限 |
| summary_l2_trigger_ratio | L1 后进入 L2 summary 的触发比例，建议 0.1~1.0，默认 0.4 |

触发判断使用 Yuxi 自己的近似 token 计算结果，不使用模型返回的 usage_metadata.total_tokens 作为触发依据，避免 provider 的计费口径、累计口径或异常上报导致短对话过早压缩。

Token 用量统计 Copy Chapter

TokenUsageMiddleware 同时维护两种口径，二者不能混用：

- 近似上下文统计通过 count_tokens_approximately 计算，用于上下文窗口、摘要阈值和消息构成展示。
- 实际用量直接保留主 Agent 模型调用返回的 AIMessage.usage_metadata，包括 input_tokens、output_tokens、total_tokens、缓存和推理 token 明细。当前不包含 Summary 中间件内部直接发起的 L2 摘要模型调用，因此尚不能作为完整账单口径。

state 中的实际用量分为 latest、run 和 thread：分别表示最近一次模型调用、当前 AgentRun 累计和当前 LangGraph 线程累计。前端状态面板只读取 state；流式终态 chunk 不携带用量。worker 从当前父线程、current_run_id 匹配的 AgentState 提取 run，在 Run 进入终态时将该快照写入 AgentRun.token_usage。run.models 与 thread.models 使用 Yuxi provider_id:model_id 配置 spec 分桶，并记录 Provider 响应中的实际模型 ID，避免模型切换后把不同模型的 token 混为一组，也避免把 OpenAI 兼容协议类型误当作业务供应商。

每个模型桶独立计算缓存 token 命中率：使用 Provider 明确上报的 input_token_details.cache_read / input_tokens；OpenAI priority / flex service tier 对应识别 priority_cache_read / flex_cache_read。累计时先汇总该模型已上报缓存明细的输入 token，再计算 sum(cache_read) / sum(input_tokens)；缺少缓存读取字段表示 Provider 未上报，不按 0 命中处理。当前 Run 的按模型聚合会在终态事务中写入 AgentRun.token_usage，父 Run 与 SubAgent Run 分别保存，不重复合并。

siliconflow-cn 与 siliconflow 当前返回的 usage 格式与统计契约不一致，暂列入 Token 用量 Provider 黑名单。黑名单模型仍计算近似上下文占用，但不写入最近调用、Run 或线程的 Provider 实际用量聚合。

触发后，中间件先执行 L1 结构精简：在本次模型调用的临时消息视图里截断旧 write_file/edit_file 工具调用的大参数；ToolMessage.content 估算 token 数超过 summary_tool_result_token_limit 时，会写入当前 Agent 可见的 outputs/large_tool_results，消息内替换为工具名、近似 token 数、完整结果路径和不超过同一 token 上限的预览。未超过该上限的工具结果保持原样。这个步骤不修改 LangGraph state 中的原始消息。

L1 后会重新计算上下文大小；如果仍超过入口阈值乘以 summary_l2_trigger_ratio，才进入 L2 summary，把较早的 L1 视图消息压缩成一条 summary message，并保留最近窗口内的原始消息。比例越小越容易进入 L2；1.0 表示 L1 后仍超过原始触发阈值才进入 L2。L2 传给摘要模型的待摘要历史上限等于 summary_threshold 对应的 token 数，避免用过小的固定窗口丢掉早期关键信息。L2 不再对工具结果做第二轮 offload，只写入 _summarization_event，后续调用仍由 DeepAgents 的 cutoff 语义重建 effective messages。

这对知识库检索尤其重要：query_kb、open_kb_document、find_kb_document 等工具可能返回较长的片段、引用和文档内容。Summary 阶段保留“查过什么、结果在哪里、关键预览是什么”，同时避免把大量检索原文反复卷入摘要，减少上下文污染和 token 压力。压缩开始、完成或失败会以 context_compression 流事件同步到前端；摘要模型自身的 token 流不会作为聊天消息输出。

未达到入口阈值的常规模型调用不会额外清洗工具结果；达到入口阈值但 L1 后低于 L2 门槛时，会直接用 L1 精简后的临时视图调用模型，不生成 summary event。

自定义中间件 Copy Chapter

新增中间件时，将实现放入 backend/package/yuxi/agents/middlewares，再在具体 Agent 的 get_graph() 中加入 middleware 列表。新增前先确认它属于哪一种职责：

- 资源过滤、权限收敛和默认资源选择应放在 prepare_agent_runtime_context 一类的 Graph 创建前逻辑中。
- 模型提示注入、工具动态追加、工具结果处理和 state 更新适合做成 LangChain Agent middleware。
- 文件读写、工具结果卸载和 artifacts 展示应优先复用 create_agent_filesystem_middleware 与沙盒 backend。

仓库中仍保留 DynamicToolMiddleware，但当前内置 Agent 的工具和 MCP 加载已经由 resolve_configured_runtime_tools(context) 与 SkillsMiddleware 承担。新增功能时不要默认复用旧的动态工具中间件，除非确实需要“预注册后按请求筛选”的模式。

---

Agents/Sandbox Architecture Copy Section

Yuxi 沙盒架构说明

::: tip info
本文档是由 Codex 联合撰写，开发者审阅，尽管已经多次校对，但仍可能存在不准确或过时的描述。如果你发现任何问题，欢迎提交 issue 或 PR 来帮助我们改进文档。
:::

我们在 Yuxi 里引入沙盒，不是为了让架构更“重”，而是因为 Agent 一旦从纯文本对话进入真实执行阶段，就一定会碰到一组很具体的运行时需求：执行命令、读写文件、处理用户上传附件、产出可下载结果，以及在受控目录里保留中间过程文件。如果把这些能力直接放进 API 进程本身，权限边界、租户隔离、环境一致性和后续运维成本都会迅速恶化。

从设计目标上看，沙盒这一层主要解决三件事。第一，给 Agent 一个可写、可执行、可回收的独立运行空间，而不是让它直接操作应用主进程。第二，把模型可见文件系统整理成稳定的命名空间，例如 /home/gem/user-data 和 /home/gem/skills，这样 prompt、工具、viewer 和 artifact 下载接口可以共享同一套路径语义。第三，让这套能力既能在本地 Docker 开发环境里稳定工作，也能在需要时切到 Kubernetes 这类更适合多实例部署的承载方式。

这份文档说明当前项目中“沙盒”这一层到底是什么、为什么同时会看到 Docker 和 Kubernetes、默认开发环境实际启用的是哪一种模式，以及沙盒如何和 skills、附件、工作区文件系统组合在一起工作。内容以当前仓库实现为准，我们重点解释真实调用链、配置入口、路径语义和运维边界，而不是抽象地介绍容器技术。

一、先说明白：Docker 和 K8s 在这里是什么关系 Copy Chapter

Docker 和 Kubernetes 不是互斥关系。Docker 解决的是“把一个进程放进容器里运行”这个问题，Kubernetes 解决的是“如何在一组机器上批量调度、暴露、重建和管理这些容器”这个问题。可以把 Docker 理解成容器运行时和镜像分发方式，把 Kubernetes 理解成容器编排平台。

放到 Yuxi 里，这个关系更具体一些。Yuxi 本身并不直接决定“沙盒一定跑在 Docker 还是一定跑在 K8s 上”，它只要求后端拿到一个可访问的沙盒地址，然后通过 agent-sandbox 的 HTTP API 去执行命令、读写文件。真正负责创建和回收沙盒实例的是 sandbox-provisioner 这个单独的服务。也就是说，Yuxi 的应用层只依赖 “provisioner”，而 provisioner 的后端可以选择用本机 Docker 去起容器，也可以选择向 Kubernetes 集群创建 Pod 和 Service。

所以项目里看到的概念其实分成两层。第一层是应用层的 SANDBOX_PROVIDER，当前代码只支持 provisioner。第二层是 provisioner 内部的 SANDBOX_PROVISIONER_BACKEND，它决定具体用哪种底层实现去创建沙盒。当前真正应该对外理解和配置的是 docker、kubernetes，测试或占位场景可以使用 memory。

二、当前项目的真实沙盒调用链 Copy Chapter

当前仓库里，后端只支持 SANDBOX_PROVIDER=provisioner。当某个对话线程第一次需要执行文件操作或命令执行时，后端会基于文件线程与 skills 线程生成稳定的 sandbox_id，然后请求 sandbox-provisioner 创建或复用对应沙盒；普通 Agent 的文件线程和 skills 线程都回退为当前 thread_id。应用层拿到返回的 sandbox_url 之后，才会真正通过 agent-sandbox 客户端去调用远程沙盒的文件 API 和 shell API。

调用链可以概括为：Web/API 请求进入 Yuxi 后端，后端构造 ProvisionerSandboxBackend，再经由 ProvisionerClient 调用 sandbox-provisioner 的 /api/sandboxes 接口。sandbox-provisioner 根据 SANDBOX_PROVISIONER_BACKEND 选择内存占位实现、Docker 容器实现或 Kubernetes 实现。沙盒真正启动后，对外暴露一个 HTTP 地址，Yuxi 再使用这个地址完成执行命令、上传文件、下载文件、目录遍历等操作。

当前仓库的默认配置和默认开发环境都应该理解为 docker。正常情况下运行中的 provisioner 健康检查应返回 backend=docker。这意味着我们用 docker compose up -d 启动项目时，应用并不是直接把代码跑在宿主机上，而是通过 sandbox-provisioner 再去用 Docker 启一个真正的沙盒容器。

三、memory、docker、kubernetes 分别是什么 、docker、kubernetes 分别是什么')" title="Copy chapter prompt for LLMs"> Copy Chapter

当前实现里，memory、docker、kubernetes 是三种需要区分的语义。

memory 是一个纯内存登记实现。它不会真正创建容器，也不会提供真实隔离，主要适合测试或极轻量的占位场景。它只是记录一个 sandbox_id -> sandbox_url 的映射，因此不能把它理解成生产可用的沙盒。

docker 是当前默认也是推荐的本机容器后端。sandbox-provisioner 会使用 LocalContainerProvisionerBackend 通过宿主机 Docker daemon 动态创建沙盒容器。

kubernetes 则是另一条实现路径。它不会再去调用本机 Docker 起容器，而是使用 Kubernetes API 在指定 namespace 中创建一个 Pod 和一个 NodePort Service，然后把这个 Service 对应的可访问地址回传给 Yuxi 后端。

因此，如果在界面、文档或者环境变量里看到 “docker / k8s” 这几个词，最准确的理解应该是：Yuxi 的应用层只有一种 provider，也就是 provisioner；provisioner 下面有多种 backend；其中 docker 是默认的本机 Docker 后端，kubernetes 是另一种远程集群后端。

四、默认开发模式到底是什么 Copy Chapter

默认开发模式是 Docker Compose 启动整个项目，再由 sandbox-provisioner 按 docker 后端去创建沙盒容器。也就是说，项目本身跑在 Compose 里，沙盒也跑在 Docker 里，只不过沙盒不是 Compose 静态声明的长期服务，而是 provisioner 按需动态拉起和回收的短生命周期容器。

这也是为什么在 docker-compose.yml 中既能看到 api、worker、sandbox-provisioner 这样的常驻服务，又能看到 sandbox-provisioner 挂载了 /var/run/docker.sock。这不是重复设计，而是为了让 provisioner 有能力继续调用宿主机 Docker daemon 去创建新的“每线程沙盒容器”。

换句话说，当前项目不存在单独的 “纯宿主机 local 模式”。本机开发和单机部署应显式使用 docker 后端。

这里还需要把 Compose 里的环境变量分两层看。api 和 worker 关注的是应用层变量，例如 SANDBOX_PROVIDER、SANDBOX_PROVISIONER_URL、SANDBOX_PROVISIONER_TOKEN、SANDBOX_VIRTUAL_PATH_PREFIX、SANDBOX_EXEC_TIMEOUT_SECONDS、SANDBOX_MAX_OUTPUT_BYTES。sandbox-provisioner 自己则有另一组变量，负责决定具体如何创建沙盒实例。两层不要混看，否则很容易误以为改了 API 环境变量就能切换底层承载方式。

五、Docker 本机后端是如何工作的 Copy Chapter

当 SANDBOX_PROVISIONER_BACKEND=docker 时，sandbox-provisioner 会进入 LocalContainerProvisionerBackend。它会检查 Docker 是否可用，解析自身容器里 /app/saves 这个挂载点在宿主机上的真实路径，并据此推导出线程数据目录。随后它为每组文件线程与 skills 线程准备一个稳定的 sandbox_id，把容器命名为类似 yuxi-sandbox-<id> 的形式，并在 Docker 网络中启动真正的沙盒镜像。

这个沙盒镜像默认来自 SANDBOX_IMAGE，容器内部监听的端口默认是 8080。provisioner 会为每个动态沙盒创建独立的 Docker bridge 网络，只把 provisioner 和该沙盒接入其中；沙盒之间不能互访，也不能访问承载 PostgreSQL、Redis、Neo4j、MinIO 等服务的 app-network。沙盒端口不发布到宿主机，provisioner 通过对应的独立网络访问真实容器，再以需要 Bearer token 的代理地址向 API/worker 提供文件和命令接口。API/worker 不直接持有沙盒容器地址。

这个拓扑把沙箱按“其中代码可能被完全控制”处理。SANDBOX_PROVISIONER_TOKEN 只配置给 API、worker 和 provisioner，绝不能写进 sandbox.env 或用户级 Agent 环境变量，否则沙箱会重新获得 provisioner 管理权限。

Docker 后端在启动沙盒时，会挂载三类关键目录。第一类是用户级 workspace，挂载到容器内的 /home/gem/user-data/workspace。第二类是文件线程级 uploads/outputs，分别挂载到 /home/gem/user-data/uploads 和 /home/gem/user-data/outputs。第三类是 skills 线程可见的 skills 目录，挂载到 /home/gem/skills，而且是只读挂载。除此之外，容器的 /home/gem 本身还会额外挂一个 tmpfs，原因是当前沙盒镜像启动时要求 /home/gem 可写，但 Yuxi 希望真正持久化的只有 user-data 下面的内容。

为了避免长期空闲的沙盒一直占资源，provisioner 还带了一个 idle reaper。它会记录每个沙盒最近一次被 touch 的时间，超过 SANDBOX_IDLE_TIMEOUT_SECONDS 之后自动删除。当前默认空闲超时是 120 秒，但如果这个值小于命令执行超时，系统会自动把它提高到“命令超时 + 30 秒”，以免执行中的任务被误回收。

对应到 docker-compose.yml 和 docker-compose.prod.yml，当前 sandbox-provisioner 实际会读取的 Docker 后端相关变量主要是这些：

- 通用变量：PROVISIONER_BACKEND、SANDBOX_IMAGE、SANDBOX_CONTAINER_PORT、SANDBOX_HEALTH_TIMEOUT_SECONDS、SANDBOX_IDLE_TIMEOUT_SECONDS、SANDBOX_IDLE_CHECK_INTERVAL_SECONDS、SANDBOX_EXEC_TIMEOUT_SECONDS、MEMORY_SANDBOX_URL_TEMPLATE
- Docker 后端变量：DOCKER_NETWORK_PREFIX、DOCKER_THREADS_HOST_PATH、DOCKER_SANDBOX_PREFIX
- 容器代理变量：HTTP_PROXY、HTTPS_PROXY、NO_PROXY

DOCKER_NETWORK_PREFIX 用于生成每个沙盒的独立网络名称。DOCKER_THREADS_HOST_PATH 也是 Docker 后端专用；如果不显式传入，provisioner 会尝试根据自身容器挂载反推出宿主机路径。

六、Kubernetes 后端是如何工作的 Copy Chapter

当 SANDBOX_PROVISIONER_BACKEND=kubernetes 时，sandbox-provisioner 会改用 Kubernetes Python 客户端。它会先加载 kubeconfig 或集群内配置，然后在指定的 namespace 中创建一个沙盒 Pod，再创建一个同名的 NodePort Service，把这个 Service 的 nodePort 暴露给 Yuxi 后端使用。

Kubernetes 后端下，沙盒还是同一套镜像，还是暴露同样的 HTTP API，但存储方式和暴露方式变了。它不会依赖宿主机 Docker bind mount，而是要求有一个可写的 PVC。当前实现里真正使用的是 THREAD_PVC，Pod 会把这块共享存储挂到 /mnt/shared-data，然后用 subPath 的方式把 threads/shared/<uid>/workspace 挂到 /home/gem/user-data/workspace，把 threads/<file_thread_id>/user-data/uploads 与 threads/<file_thread_id>/user-data/outputs 分别挂到 uploads/outputs，把 threads/<skills_thread_id>/skills 挂到 /home/gem/skills。这样做的好处是目录结构仍然可以和 Docker 模式保持一致，同时允许子智能体共享父对话文件但隔离 skills。

需要特别说明的是，代码里虽然读取了 SKILLS_PVC 这个环境变量，但当前 Pod 规格实际没有使用单独的 skills PVC，而是统一从 THREAD_PVC 中切 threads/<thread_id>/skills 这个子路径。因此，如果看到环境变量里同时出现 SKILLS_PVC 和 THREAD_PVC，应当以 THREAD_PVC 的真实挂载语义为准，SKILLS_PVC 目前更像一个预留字段。

Kubernetes 后端还需要一个 NODE_HOST。这是因为当前实现使用的是 NodePort Service，而不是 Ingress，也不是 ClusterIP。provisioner 创建完 Service 后会通过 http://<NODE_HOST>:<nodePort> 访问目标沙箱，但返回给 Yuxi 后端的仍是 provisioner 认证代理地址。所以 NODE_HOST 必须从 provisioner 可达，不需要直接暴露给 API/worker。

当前 Compose 中与 Kubernetes 后端对应的变量主要是：

- K8S_NAMESPACE
- KUBECONFIG_PATH
- NODE_HOST
- THREAD_PVC
- SKILLS_PVC

其中真正决定运行时挂载的是 THREAD_PVC。SKILLS_PVC 目前只保留为代码层读取字段，并没有进入实际 Pod 挂载。

七、如果要使用“远程 K8s”，应该怎么接 Copy Chapter

这里最容易误解的一点是，所谓“选择远程 K8s”，并不是在 Yuxi 页面里点一个开关，然后系统自动发现一个集群。当前实现没有内建集群选择器，也没有多集群管理界面。它的工作方式很直接：我们把 sandbox-provisioner 配置成 kubernetes 后端，并让它能拿到目标集群的 kubeconfig 或者运行在集群内即可。对 provisioner 来说，只要 Kubernetes 客户端能连上 API Server，这个集群就是它要操作的“远程 K8s”。

如果 Yuxi 部署在 Docker Compose 里，而 Kubernetes 集群在另一台机器或云厂商托管环境中，那么最常见的做法是把本地 kubeconfig 文件挂载进 sandbox-provisioner 容器，然后设置 KUBECONFIG_PATH。同时把 SANDBOX_NODE_HOST 改成一个从 api 容器也能访问的节点公网 IP、负载均衡域名，或者已经做过反向代理的地址。

一个典型的 Compose 覆盖配置会长这样：

services:
  sandbox-provisioner:
    environment:
      - PROVISIONER_BACKEND=kubernetes
      - K8S_NAMESPACE=yuxi-know
      - KUBECONFIG_PATH=/root/.kube/config
      - THREAD_PVC=yuxi-thread
      - SKILLS_PVC=yuxi-skills
      - NODE_HOST=203.0.113.10
    volumes:
      - ~/.kube/config:/root/.kube/config:ro

这段配置表达的意思不是“把整个应用迁到 K8s”，而是“仍然用 Compose 跑 Yuxi 主服务，但沙盒实例改为由远程 Kubernetes 集群承载”。这是当前代码最自然的混合部署方式。

如果 sandbox-provisioner 本身就运行在 Kubernetes 集群内部，那么通常不需要显式提供 KUBECONFIG_PATH。它会优先尝试 incluster_config，也就是使用 Pod 的服务账号权限直接访问 Kubernetes API。此时更需要关注的是 namespace、PVC 和 NodePort 的可达性，而不是 kubeconfig 文件本身。

八、当前项目的沙盒文件系统是如何设计的 Copy Chapter

从模型和工具调用的视角看，Yuxi 主要向 Agent 暴露两类路径：/home/gem/user-data 和 /home/gem/skills。其中 user-data 是可写的用户工作区，skills 是只读的技能目录。知识库不再映射为沙盒文件系统路径，模型应通过知识库工具检索和打开文档。

在宿主机侧，和线程相关的数据主要放在 saves 目录下。当前可读的目录结构可以概括为下面这样：

saves/
├── skills/
│   ├── <skill-slug>/
│   └── ...
├── threads/
│   ├── <thread_id>/
│   │   ├── user-data/
│   │   │   ├── uploads/
│   │   │   ├── outputs/
│   │   │   └── ...
│   │   └── skills/
│   │       ├── <skill-slug>/
│   │       └── ...
│   ├── shared/
│   │   └── <uid>/
│   │       └── workspace/
│   └── ...

这里要重点理解 workspace 和 uploads/outputs 的区别。按照当前宿主机路径解析逻辑，workspace 被定义为用户级共享目录，位置是 saves/threads/shared/<uid>/workspace；而 uploads 和 outputs 属于文件线程目录，位置分别是 saves/threads/<file_thread_id>/user-data/uploads 和 saves/threads/<file_thread_id>/user-data/outputs。普通 Agent 的 file_thread_id 就是当前对话 thread_id，子智能体运行时则使用父对话作为 file_thread_id，因此可以读取父对话附件并把产物写回父对话 outputs。

与此同时，运行时 provisioner 在创建 Docker 容器或 Kubernetes Pod 时，会把用户级 saves/threads/shared/<uid>/workspace 单独挂到 /home/gem/user-data/workspace，再把文件线程的 uploads/outputs 分别挂到 /home/gem/user-data/uploads 和 /home/gem/user-data/outputs。因此在排查文件问题时，需要先明确一个前提：当前项目里同时存在“宿主机侧目录组织”和“容器内统一虚拟路径”两层概念。对外接口和 viewer 语义与底层挂载实现现在是一致的，workspace 是用户共享空间，而 uploads/outputs 跟随文件线程隔离或共享。

九、路径暴露规则是什么 Copy Chapter

Yuxi 不会把整个容器文件系统都开放给 Agent 或 viewer。当前 viewer 根目录只会列出几个命名空间入口，而不会直接暴露 / 的真实文件树。这样做是为了避免只看文件树就触发沙盒冷启动，也为了让权限边界更稳定。

/home/gem/user-data 是主要工作区。它允许模型和工具写入，但推荐语义并不相同。内置 prompt 中已经明确说明，workspace 应当放中间文件，outputs 应当放最终产物，uploads 是用户上传文件的位置。对于普通对话 Agent，文案甚至提示“非必要不要写 workspace，而优先写 outputs”。

/home/gem/skills 是共享与内置 Skill 的只读目录。它不是简单地把 saves/skills 整个暴露进去，而是按当前运行时最终生效的共享与内置 Skill，将来源同步到 saves/threads/<skills_thread_id>/skills，再把线程目录只读挂进沙盒。个人 Skill 不进入这层投影，Agent 直接读取已经挂载的 /home/gem/user-data/workspace/agents/skills/<slug>。

知识库访问不属于沙盒文件系统暴露规则。当前 Agent 可见知识库仍由用户权限和 Agent 配置共同决定，但只通过 query_kb、open_kb_document 等工具访问，不提供沙盒目录投影。

十、skills、知识库、附件是怎么和沙盒结合的 Copy Chapter

skills 的结合方式分成两层。第一层是提示词层，prepare_agent_runtime_context 会先根据当前 Agent 配置的 context.skills 展开依赖闭包，SkillsMiddleware 再把 _prompt_skills 注入到系统提示里，并给出每个 Skill 的真实运行入口。第二层是文件系统层：共享与内置 Skill 由 sync_thread_readable_skills 同步到当前 skills_thread_id 的线程目录，并只读挂载到 /home/gem/skills；个人 Skill 直接使用用户工作区中的 workspace/agents/skills，不再生成线程副本。

附件的结合方式更偏向“先落盘，再把路径告诉模型”。用户上传文件后，系统会先把原始文件写入 saves/threads/<file_thread_id>/user-data/uploads。如果该文件可以被解析，系统还会额外生成一个 Markdown 副本，写到 saves/threads/<file_thread_id>/user-data/uploads/attachments/<name>.md。普通 Agent 的文件线程就是当前对话线程；子智能体沿用父对话文件线程，所以能访问父对话附件。随后，LangGraph state 中会维护一份 uploads 列表，AttachmentMiddleware 会把这些可读路径注入系统提示，告诉模型优先用 read_file 去读取这些路径。因此，附件并不是“作为消息大段内联塞给模型”，而是被转换成沙盒文件系统中的路径对象。

知识库不再与沙盒文件系统结合。它不会被复制到每个线程目录，也不会生成虚拟目录；模型通过专门的知识库工具检索，并在需要更完整上下文时用 open_kb_document 按 kb_id 和 file_id 打开文档内容。

十一、当前推荐如何使用 Docker 沙盒 Copy Chapter

如果只是正常开发、调试或单机部署，最简单也是当前默认的方式就是保留 SANDBOX_PROVIDER=provisioner，同时把 SANDBOX_PROVISIONER_BACKEND 设为 docker。这会让整个项目继续由 Docker Compose 管理，而沙盒实例由 provisioner 动态创建。通常不需要手工 docker run 沙盒镜像，也不需要在 Compose 文件里静态声明每一个沙盒容器。

最小必要配置通常就是下面这几项：

SANDBOX_PROVIDER=provisioner
SANDBOX_PROVISIONER_URL=http://sandbox-provisioner:8002
SANDBOX_PROVISIONER_TOKEN=<至少 32 个随机字符>
SANDBOX_PROVISIONER_BACKEND=docker
SANDBOX_VIRTUAL_PATH_PREFIX=/home/gem/user-data
SANDBOX_DOCKER_NETWORK_PREFIX=yuxi-know-sandbox

然后用常规方式启动即可：

docker compose up -d
curl http://localhost:8002/health

如果健康检查返回 backend: docker，就说明 provisioner 已经处于默认的 Docker 本机后端。真正的沙盒容器不会在系统启动时立即全部出现，而是在你第一次创建线程并触发需要文件系统或命令执行的操作后才会被创建。

升级已有开发环境时可以重新运行初始化脚本，让脚本补生成 SANDBOX_PROVISIONER_TOKEN。历史共享沙盒网络中的容器会在下次发现时被重建到各自独立的网络。

十二、如何理解文件管理与暴露边界 Copy Chapter

从产品行为上看，viewer 文件系统和 artifact 下载接口优先走的是宿主机路径解析，而不是无条件透传到沙盒容器内部。这么设计有两个直接收益。第一，浏览 / 或 /home/gem/user-data 这样的树形入口时，不需要为了只读查看而冷启动沙盒。第二，权限边界更好做，因为 resolve_virtual_path 会把用户可见路径严格限制在预定义的 user-data 和 skills 命名空间内。

从工程上看，当前实现更像“双层文件系统”。对 Agent 执行来说，真正工作的对象是远程沙盒进程暴露的文件 API；对 viewer、附件下载和一部分 artifact 查看来说，系统会优先在宿主机侧解析虚拟路径，再用本地文件读取或只读 backend 下载内容。这也是为什么你会看到既有 ProvisionerSandboxBackend，又有 viewer_filesystem_service、SelectedSkillsReadonlyBackend 这样的配套实现。

十三、环境变量配置与传递链 Copy Chapter

sandbox-provisioner 的环境变量传递分两层，需要分别理解：

第一层：应用层 → sandbox-provisioner Copy Section

api 和 worker 服务通过 SANDBOX_* 前缀的环境变量告诉后端如何连接 provisioner。这些变量定义在 docker-compose.yml 的 x-api-worker-env 锚点中：

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| SANDBOX_PROVIDER | 提供者类型，固定为 provisioner | provisioner |
| SANDBOX_PROVISIONER_URL | provisioner 服务地址 | http://sandbox-provisioner:8002 |
| SANDBOX_PROVISIONER_TOKEN | provisioner 管理与代理接口 Bearer token，至少 32 个字符 | 无，必填 |
| SANDBOX_VIRTUAL_PATH_PREFIX | 虚拟路径前缀 | /home/gem/user-data |
| SANDBOX_EXEC_TIMEOUT_SECONDS | 命令执行超时时间 | 180 |
| SANDBOX_MAX_OUTPUT_BYTES | 最大输出字节数 | 262144 |

第二层：sandbox-provisioner 内部配置 Copy Section

sandbox-provisioner 服务本身读取另一组环境变量，决定如何创建沙盒容器。这些变量直接写在 docker-compose.yml 的 sandbox-provisioner.environment 中：

通用配置：

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| PROVISIONER_BACKEND | 底层后端类型，docker 或 kubernetes | docker |
| SANDBOX_IMAGE | 沙盒容器镜像 | 详见 compose 文件 |
| SANDBOX_CONTAINER_PORT | 沙盒容器内部端口 | 8080 |
| SANDBOX_IDLE_TIMEOUT_SECONDS | 空闲回收时间 | 120 |
| SANDBOX_HEALTH_TIMEOUT_SECONDS | 健康检查超时 | 300 |

Docker 后端专用：

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| DOCKER_NETWORK_PREFIX | 每沙盒独立网络的名称前缀 | yuxi-know-sandbox |
| DOCKER_SANDBOX_PREFIX | 沙盒容器名前缀 | yuxi-sandbox |
| DOCKER_THREADS_HOST_PATH | 线程数据宿主机路径 | 自动推断 |

Kubernetes 后端专用：

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| K8S_NAMESPACE | Kubernetes namespace | yuxi-know |
| NODE_HOST | Kubernetes 节点地址 | host.docker.internal |
| KUBECONFIG_PATH | kubeconfig 文件路径 | 空（使用 incluster 配置） |
| THREAD_PVC | 线程数据持久化卷 | yuxi-thread |
| SKILLS_PVC | 技能目录持久化卷（预留） | yuxi-skills |

环境变量传递链 Copy Section

宿主机 .env / 系统环境变量
         ↓
    docker-compose.yml
         ↓
    ┌────────────────────────────────┐
    │  api/worker 服务               │  应用层变量 (SANDBOX_*)
    │    SANDBOX_PROVISIONER_URL     │
    │    SANDBOX_PROVISIONER_TOKEN   │
    └────────────┬───────────────────┘
                 ↓  带 Bearer token 的 HTTP 调用
    ┌────────────────────────────────┐
    │  sandbox-provisioner 服务       │  沙盒层变量 (PROVISIONER_BACKEND, DOCKER_, K8S_)
    │    PROVISIONER_BACKEND         │
    └────────────┬───────────────────┘
                 ↓  Docker API / K8s API + 认证 HTTP 代理
    ┌────────────────────────────────┐
    │  动态创建的沙盒容器              │
    └────────────────────────────────┘

两层变量不要混看。改了 api/worker 的 SANDBOX_PROVISIONER_URL 只是改了后端找 provisioner 的地址；改了 sandbox-provisioner 的 PROVISIONER_BACKEND 才是改了 provisioner 本身用什么方式创建沙盒。

sandbox.env 的特殊作用 Copy Section

docker/sandbox_provisioner/sandbox.env 文件的用途与上述两层变量不同。它通过 volume 挂载到 provisioner 容器内 (/app/sandbox.env)，然后由 LocalContainerProvisionerBackend 在创建沙盒容器时读取，解析后的键值对会作为环境变量注入到每个动态创建的沙盒容器中。

docker-compose.yml 中 sandbox-provisioner 的挂载

sandbox-provisioner:
  volumes:
    - ./docker/sandbox_provisioner/sandbox.env:/app/sandbox.env:ro

也就是说，sandbox.env 配置的是沙盒容器内部可见的环境变量，而不是 provisioner 本身的配置。当前该文件内容为：

CHECK_YUXI_SANDBOX_ENV_EXISTS=True

如果需要给所有沙盒容器注入额外的环境变量（如代理配置、认证信息等），可以添加到 sandbox.env 文件中。

远程 Skill 拉取使用专门的一次性 Sandbox，不继承这里的全局环境变量或用户级 Agent 环境变量，避免不可信仓库通过复制文件带出凭据。Kubernetes 创建的 Sandbox 同时会禁用 ServiceAccount token 自动挂载。

配置方式汇总 Copy Section

| 配置目标 | 配置位置 | 示例变量 |
|----------|----------|----------|
| 应用层连接 provisioner | .env 或 compose 环境 | SANDBOX_PROVISIONER_URL, SANDBOX_PROVISIONER_TOKEN |
| provisioner 自身行为 | .env 或 compose 环境 | PROVISIONER_BACKEND, DOCKER_* |
| 沙盒容器内部环境 | sandbox.env 文件 | 代理、认证等运行时变量 |

十四、和旧版文档相比，今天最重要的理解方式 Copy Chapter

当前项目不应再按“应用直接管理一个长期存在的本地 sandbox 服务”去理解。更准确的认识应该是：Yuxi 只管理线程和上下文；provisioner 负责创建线程对应的沙盒实例；文件系统不是简单地暴露一个容器根目录，而是把可写工作区、只读 skills 等组合成一个受控命名空间（知识库不再映射为沙盒目录，改由 query_kb/open_kb_document 等工具访问）。

因此，当你在界面上“启用沙盒”或者在文档里“选择 K8s”时，本质上做的不是切换一段业务逻辑，而是在切换 provisioner 的底层实例承载方式。选择 docker 时，沙盒由当前部署机上的 Docker daemon 动态创建；选择 kubernetes 时，沙盒由目标 K8s 集群动态创建。Yuxi 自己始终只面对一个 provisioner 服务地址。

十五、排障时建议先看什么 Copy Chapter

如果怀疑是 provisioner 级问题，先看 http://localhost:8002/health，确认 backend 类型和 idle timeout 是否符合预期。默认 Docker 部署下这里应看到 backend=docker。接着看 docker logs sandbox-provisioner --tail 200，因为这里能直接看到创建容器、复用旧实例、健康检查失败和 idle reaper 删除的日志。

如果怀疑是 Docker 地址不可达，先确认每个动态沙箱只连接自己的 yuxi-know-sandbox-<id> 网络，provisioner 同时连接该网络，而 API/worker 只在 app-network。provisioner 日志中的目标地址应是动态容器名，API/worker 拿到的地址应是 /api/sandboxes/<id>/proxy；代理请求必须携带 SANDBOX_PROVISIONER_TOKEN。如果怀疑是 Kubernetes 地址不可达，重点检查 NODE_HOST 和 NodePort 是否从 provisioner 可达。

如果怀疑是文件看得到但模型读不到，或者模型写了但 viewer 看不到，优先把问题拆成两层：一层是宿主机路径是否存在于 saves/... 下，另一层是该路径是否真的被当前线程沙盒挂载并暴露到了 /home/gem/user-data 或 /home/gem/skills。只要先分清“宿主机侧文件语义”和“沙盒侧运行时挂载语义”，定位问题通常会快很多。

---

Agents/Skills Management Copy Section

Skills 管理系统

Skills 是 Yuxi 系统中用于扩展 Agent 能力的重要机制。通过 Skills，开发者可以将特定的工具、提示词模板或领域知识打包成可复用的技能包，让 Agent 在对话过程中能够调用这些额外能力。

为什么需要 Skills Copy Chapter

在实际业务场景中，我们常常会遇到一些特定的需求：比如需要 Agent 能够查询特定的 API、调用某个外部服务、或者使用特定的提示词模板来完成特定任务。传统的做法是在代码中硬编码这些功能，但这样会导致系统变得越来越臃肿，且难以复用。

Skills 系统的设计理念就是将这类"可插拔"的能力封装成独立的技能包。每个 Skill 包含完整的实现文件和元数据，Agent 可以根据配置动态加载所需的技能，实现能力的灵活组合。

架构设计 Copy Chapter

Skills 系统分为平台共享与个人工作区两层。共享 Skill 采用「文件系统存内容，数据库存索引」；
个人 Skill 只存在于当前用户 workspace，并使用 Redis 保存 5 分钟的元数据快照：

┌─────────────────────────────────────────────────────────────┐
│                      Skills 存储架构                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   /app/saves/skills/          数据库索引                    │
│   ├── skill-a/               ┌──────────────┐              │
│   │   ├── SKILL.md           │ skills 表    │              │
│   │   ├── tools/             │ - slug       │              │
│   │   └── prompts/           │ - name       │              │
│   └── skill-b/               │ - description│              │
│       ├── SKILL.md           │ - dir_path   │              │
│       └── ...                │ - source_type│              │
│                              │ - share_config              │
│                              │ - enabled     │              │
│                              │ - deps...     │              │
│                              └──────────────┘              │
│                                                             │
│   workspace/agents/skills/    Redis 临时索引                │
│   └── my-skill/              - 按 uid 隔离                 │
│       └── SKILL.md           - 5 分钟失效                  │
│                              - 安装/删除/刷新后立即更新     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

存储结构 Copy Section

- 文件系统：/app/saves/skills 目录下，每个 Skill 占用一个子目录
- 数据库索引：skills 表存储元数据（slug、name、description、来源、共享范围、启用状态、依赖关系等）
- 关联机制：通过 dir_path 字段关联文件系统目录与数据库记录
- 个人工作区：workspace/agents/skills/<slug> 保存当前用户个人 Skill，不创建数据库记录
- 个人缓存：解析后的名称、slug 和描述按用户缓存到 Redis，默认 5 分钟失效

::: tip 两种存储边界
共享 Skill 必须通过系统导入并写入数据库；个人 Skill 可以由安装流程写入工作区，也可以在工作区中手动维护。手动修改后点击 Skills 页刷新，或等待最多 5 分钟重新解析。
:::

创建方式 Copy Chapter

系统提供以下方式创建或安装 Skills：

1. 推荐 Skill 安装：在 Skills 管理页的推荐分组点击 +，系统会拉取对应远程来源并生成安装草稿
2. ZIP / SKILL.md 上传：上传后先解析为安装草稿，再选择安装到个人工作区或共享 Skill 库
3. 远程仓库安装：填写 skills 仓库地址、ModelScope Skill 地址或合集地址，下载并解析后选择安装位置
4. 在线编辑：对已有且可管理的 Skill 在线创建目录、编辑文件和维护依赖
5. Agent 内安装：主智能体可通过 install_skill 工具安装个人工作区 Skill；子智能体禁用该工具

个人 Skill 不解析 tool_dependencies、mcp_dependencies 或 skill_dependencies。需要平台依赖、共享范围或在线管理时，应选择共享安装。

Skills 来源 Copy Chapter

Skills 本质上是提示词和工具的封装，以下是一些可以参考的 Skills 实现：

- Anthropic 官方 Tools：https://github.com/anthropics/skills 可以参考其 skills 的组织方式和提示词设计
- ModelScope Skill 市场：https://modelscope.cn/skills 支持单个 Skill 地址，也支持合集地址批量拉取
- MiniMax-AI CLI：https://github.com/MiniMax-AI/cli 文本、图片、视频、语音和音乐生成 + Web 搜索（可通过 MiniMax-AI/cli 远程安装）
- 社区 Skills：各平台分享的 Agent 提示词模板
- 自定义开发：根据业务需求自行开发

系统也会在启动时同步仓库内置 Skills。内置 html-preview 用于指导 Agent 在普通
Markdown 不足以清晰表达指标、对比、流程、时间线或层级关系时，按需输出
html:preview 静态 HTML/CSS 围栏；普通 HTML 源码仍使用 html 代码块。该 Skill
不依赖额外工具，前端继续通过清洗后的 sandboxed iframe 渲染预览。

未显式配置 Skills 的 Agent 会按现有资源默认规则自动获得该 Skill。使用显式 Skills
允许列表的 Agent 需要选择 html-preview 才能使用；内置 deep-research 已声明该依赖，
升级后仍可继续输出辅助可视化。

快速开始 Copy Chapter

创建你的第一个 Skill Copy Section

一个标准的 Skill 目录结构如下：

my-awesome-skill/
├── SKILL.md              # 必选，Skill 的核心定义文件
├── tools/                # 可选，相关的工具脚本
│   └── helper.py
└── prompts/              # 可选，提示词模板
    └── system.md

其中 SKILL.md 是每个 Skill 必须包含的核心文件，它采用 Markdown + Frontmatter 格式：

---
name: My Awesome Skill
slug: my-awesome-skill
description: 这是一个用于处理特定任务的技能
---
Skill 使用说明
这里是技能的详细使用文档，Agent 会读取这部分内容来了解如何使用这个技能。
功能列表  Copy Chapter
1. 功能一：xxx
2. 功能二：yyy
使用示例  Copy Chapter
当用户 xxx 时，可以调用此技能...

Frontmatter 字段说明：

| 字段 | 必填 | 说明 |
|------|------|------|
| name | 是 | Skill 展示名称，可使用更易读的名称（如 Word / DOCX） |
| slug | 否 | Skill 唯一标识，必须是小写字母、数字、短横线的组合，且不能连续短横线（如 my-skill）。未填写时兼容旧格式，系统会使用 name 作为 slug，此时 name 也必须满足 slug 规则 |
| description | 是 | Skill 的功能描述，会在 Agent 配置时展示 |

导入 Skill Copy Section

可以通过以下方式导入或安装 Skill：

方式一：从推荐列表安装

1. 在系统设置的「Skills 管理」页面查看「推荐」分组
2. 未安装的推荐 Skill 会以普通 Skill 卡片样式展示，右侧显示 +
3. 点击推荐卡片或 + 后，系统会使用该 Skill 的远程来源拉取内容
4. 拉取成功后会弹出安装草稿，选择个人工作区或共享 Skill 后完成安装

已安装的推荐 Skill 不会继续显示在「推荐」分组中。

方式二：通过 ZIP 包或 SKILL.md 上传

1. 将 Skill 目录打包成 ZIP 文件（注意：ZIP 的根目录就是 Skill 目录）
2. 在系统设置的「Skills 管理」页面，点击「上传 Skill」
3. 上传 ZIP 文件或单个 SKILL.md
4. 系统解析上传内容并返回安装草稿
5. 选择安装位置后完成安装；选择共享 Skill 时继续确认共享范围，也可以放弃草稿

系统会自动：
- 校验 ZIP 内容和路径安全性
- 检查 slug 冲突：共享安装沿用全局冲突处理，个人安装同用户冲突时明确失败且不改写 slug
- 解析 SKILL.md 的 frontmatter；只有共享安装会写入数据库
- 按当前用户角色校验可选择的共享范围

方式三：从远程来源安装

管理员可以在「设置 → 基本设置 → Skill 配置 → 远程来源白名单」中配置允许远程安装 Skill 的来源域名；对应系统配置项为 remote_skill_source_policy.allowed_hosts。
该策略保存在 PostgreSQL config_options 中，默认允许 github.com 和 modelscope.cn，只做
精确域名匹配，不自动放行子域名；保存空列表时，远程 Skill 安装会被禁用。运行时以数据库
配置为准，不依赖 base.toml、环境变量或 Redis 配置快照。

1. 在 Skills 管理页面点击「远程安装」
2. 在“按仓库拉取”中填写来源，例如：
- anthropics/skills
- https://github.com/anthropics/skills
- https://modelscope.cn/skills/@anthropics/pdf
- https://modelscope.cn/collections/MiniMax/MiniMax-Office-skills
3. 点击“拉取技能”获取该来源中可发现的 Skills 列表
4. 单个 Skill 地址通常会自动选中；仓库或合集地址可在列表中勾选一个或多个 Skills
5. 点击“解析并确认”，系统返回安装草稿；选择个人工作区或共享 Skill 后正式安装

也可以切换到“全局搜索发现”，输入关键字检索 skills.sh 上的开源 Skills，再选择结果安装。

系统会在后端：
- 只接受管理员白名单中的 HTTPS 来源；GitHub owner/repo 简写按 github.com 校验
- 在不继承全局或用户环境变量的一次性 Sandbox 中执行 npx skills，Kubernetes Sandbox 不挂载 ServiceAccount token
- 通过 Sandbox 文件 API 提取对应 Skill，严格校验返回的相对路径，并限制文件数、目录深度和总大小；个人确认写入 workspace，共享确认写入 /app/saves/skills 与数据库

来源白名单用于限制产品允许的远程仓库，并不等同于 Sandbox 网络出口防火墙。

::: tip ModelScope 合集适合批量安装
ModelScope 合集地址可以作为远程来源填写，例如 https://modelscope.cn/collections/MiniMax/MiniMax-Office-skills。拉取后在列表中勾选需要的 Skills，再统一解析为安装草稿。
:::

方式四：在线编辑已有 Skill

在 Skills 管理页面，你可以：
- 新建目录或文件
- 在线编辑文本文件（支持 .md、.py、.js、.json 等格式）
- 直接在网页上修改 SKILL.md 内容

只有具备 can_manage 权限的用户才能编辑文件、依赖、共享范围和启用状态。

::: tip 安装位置决定管理能力
个人工作区适合公开、平台无关或用户自定义 Skill；共享 Skill 适合需要工具、MCP、Skill 依赖以及部门或全局共享的能力。
:::

依赖系统 Copy Chapter

Skills 之间可以建立依赖关系，形成一个松耦合的技能网络。

依赖类型 Copy Section

每个 Skill 可以声明三类依赖：

| 依赖类型 | 说明 | 加载时机 |
|----------|------|----------|
| tool_dependencies | 需要的内置工具 | 激活后按需加载 |
| mcp_dependencies | 需要的 MCP 服务 | 激活后按需加载 |
| skill_dependencies | 依赖的其他 Skill | 会话启动即生效 |

渐进式加载机制 Copy Section

系统采用三级渐进式加载策略，确保资源的高效利用：

阶段一：会话启动

当 Agent 会话启动时，系统会：
1. 在创建 Graph 前读取已过滤的 context.skills 列表
2. 递归展开 skill_dependencies，派生 _prompt_skills 和 _readable_skills
3. 将 _prompt_skills 对应的技能说明注入到系统提示词中

这意味着：只要配置了某个 Skill，它的依赖 Skill 就会立即进入提示词；共享与内置 Skill 进入沙盒
/home/gem/skills 只读范围，个人 Skill 直接使用
/home/gem/user-data/workspace/agents/skills/<slug>。

阶段二：技能激活

当 Agent 通过 read_file 读取共享路径 /home/gem/skills/<slug>/SKILL.md，或个人工作区路径
/home/gem/user-data/workspace/agents/skills/<slug>/SKILL.md 时，视为“激活”该技能。系统会：
1. 验证该技能在可见列表中
2. 将其添加到 activated_skills 列表
3. 后续的模型调用会使用激活列表来加载依赖

阶段三：按需加载

每次模型调用时，系统会：
1. 检查 activated_skills 中的技能
2. 收集这些技能的 tool_dependencies 和 mcp_dependencies
3. 动态将需要的工具和 MCP 服务添加到可用工具集中

这种设计的好处是：不会在会话开始时加载所有工具，而是根据 Agent 实际使用情况按需加载，既节省资源又保证响应速度。

依赖声明示例 Copy Section

假设我们有三个 Skills：

- base-skill：基础技能，无依赖
- advanced-skill：依赖 base-skill
- pro-skill：依赖 advanced-skill

当在 Agent 配置中只选择 pro-skill 时：
1. 启动阶段：_readable_skills = [pro-skill, advanced-skill, base-skill]（自动展开依赖链）
2. Agent 首次调用任何 skill 时：所有三个 Skill 都可读
3. 当 Agent 读取 pro-skill/SKILL.md 时：触发激活，工具和 MCP 依赖被加载

权限管理 Copy Chapter

数据库中的共享与内置 Skills 使用 source_type、share_config 和 enabled 控制来源、共享范围和启用状态。个人工作区 Skill 由认证用户目录天然隔离，不携带 share_config，避免与数据库“指定用户共享”语义混淆。

| 字段 | 说明 |
|------|------|
| source_type | builtin、upload、remote 或 personal |
| share_config | 仅共享与内置 Skill 使用；v2 配置分别声明 read_scope 和 manage_scope |
| enabled | 是否允许在 Agent 配置与运行时使用 |

访问与管理规则：

| 用户 | 可见 / 可用 | 可管理 |
|------|-------------|--------|
| 超级管理员 / 管理员 | 可查看可管理或已启用且可访问的 Skills | 可管理所有非内置 Skills；可启停内置 Skills |
| 普通用户 | 可查看已启用且对自己可访问的 Skills，只能把新 Skill 安装到个人工作区 | 可管理自己创建的非内置 Skills |
| 内置 Skills | 默认全局共享并启用 | 管理员可启停；不允许删除或直接编辑文件 |
| 个人工作区 Skills | 只对当前用户可见，文件与缓存按 uid 隔离 | 当前用户可预览、删除和手动刷新 |

共享范围限制：

- global：所有用户可访问
- department：指定部门用户可访问
- user：指定用户可访问
- 只有管理员可以把 Skill 安装到平台共享 Skill 库；普通用户安装固定进入个人工作区，不创建数据库记录，也不配置共享范围

旧版单层共享范围会在 PostgreSQL 启动迁移中复制为读取和管理范围；运行时接口仅接受 v2 配置。

管理员和普通用户在创建或编辑 Agent 时，都只能从自己可访问且启用的 Skills 中选择能力。
个人 Skill 与共享 Skill 同 slug 时，个人 Skill 整项覆盖共享版本；共享版本的工具、MCP 和 Skill
依赖不会继续加载。删除个人版本后，用户仍有权访问的同名共享版本会在下一次运行恢复生效。

运行时行为 Copy Chapter

Agent 如何使用 Skills Copy Section

1. 提示词注入：系统在每次模型请求时动态注入可用 Skills 的描述（请求级注入，避免污染 runtime context）
2. 文件访问：共享与内置 Skill 从只读 /home/gem/skills/<slug>/... 读取；个人 Skill 直接从工作区读取
3. 工具调用：当 Agent 需要使用某个 Skill 时，会先读取对应的 SKILL.md 了解使用方法

文件操作限制 Copy Section

共享与内置 Skill 的运行时 /home/gem/skills 路径有以下限制：
- 只读：Agent 只能读取文件内容
- 禁止写入：不能创建、修改或删除文件
- 路径安全：所有路径都经过安全校验，防止目录穿越攻击

::: tip 只读不等于不可执行
/home/gem/skills 对 Agent 是只读的，但沙盒命令工具仍可执行其中的脚本。Skill 应把依赖、运行方式和产物位置写清楚；脚本若需要写文件，应写入 workspace 或 outputs，而不是 Skill 目录。
:::

个人 Skill 位于 /home/gem/user-data/workspace/agents/skills，属于用户可写工作区。运行时不会再把它复制到
线程 /home/gem/skills 目录，因此工作区中的修改会直接成为后续读取内容。

会话隔离 Copy Section

每个 Agent 会话都有独立的 Skills 可见集：
- 不同会话可以配置不同的 Skills
- 同一会话内修改 context.skills 会重建共享与内置 Skill 的只读投影
- 个人 Skill 元数据最多缓存 5 分钟；安装、删除和 Skills 页手动刷新会立即更新缓存
- 每次构建运行时只同步最终生效的共享与内置 Skill；个人版本同名覆盖时直接使用工作区路径

最佳实践 Copy Chapter

Skill 命名规范 Copy Section

- slug 使用小写字母、数字和短横线，不能连续短横线
- slug 应具有描述性，如 weather-query、sql-reporter
- name 用于展示，可比 slug 更自然，例如 Word / DOCX
- 避免过长的 name 和 slug

依赖管理建议 Copy Section

- 保持依赖链简洁：层级不宜过深，一般 1-2 层为宜
- 避免循环依赖：系统会检测并阻止循环依赖
- 明确依赖必要性：只在真正需要共享能力时才建立依赖

SKILL.md 编写技巧 Copy Section

---
name: example-skill
description: 简短描述技能功能
---
技能名称
这里是详细的使用说明...
何时使用  Copy Chapter
描述在什么场景下应该使用这个技能...
使用方法  Copy Chapter
1. 第一步...
2. 第二步...
示例  Copy Chapter

Yuxi 的子智能体是 Agent-backed 形态：它仍然是 agents 表中的一级 Agent，只是额外带有 is_subagent=true 标记，并使用专用后端 SubAgentBackend。子智能体不再有独立的创建入口、独立表或独立管理接口。

用户视角 Copy Chapter

子智能体能解决什么问题 Copy Section

当任务复杂、需要分工处理时，主 Agent 可以通过 task 工具把一个子任务交给子智能体。例如：

- 通用型子任务：交给内置 general-purpose 子智能体，使用默认运行配置处理分析、整理、写作或文件处理。
- 研究型子任务：聚焦检索和资料整理。
- 评审型子任务：对草稿进行结构和质量审查。
- 领域型子任务：使用指定模型、工具、知识库或 Skills 处理特定领域问题。

在哪里创建和编辑 Copy Section

子智能体与普通 Agent 使用同一个管理入口：进入模型配置中的“智能体”管理页，点击新增智能体，并在后端类型中选择 SubAgentBackend。

创建和编辑流程与普通 Agent 保持一致：

- 展示信息、共享权限、系统提示词和运行配置都保存在同一份 Agent 配置中。
- 模型、工具、知识库、MCP 和 Skills 仍通过 Agent runtime config 表单配置。
- 子智能体不会出现在聊天页的 Agent 快速切换列表中。
- 子智能体不能再配置或调用其他子智能体。

如何让主 Agent 调用子智能体 Copy Section

主 Agent 会通过 runtime config 的“子智能体”字段确定 task 工具可调用的子智能体范围。

subagents 字段表示当前主 Agent 的允许列表：

- 未选择或保存空列表时，默认启用当前用户可见的全部子智能体，包括内置 general-purpose。
- 显式选择后，只允许调用所选子智能体。
- 只会调用当前用户可访问且 is_subagent=true 的 Agent。
- 每个子智能体使用自己的 config_json.context，包括模型、工具、知识库、MCP、Skills 和系统提示词。

内置 general-purpose 的 config_json.context 为空，运行时会按 SubAgentContext 和 BaseContext 默认值解析模型、工具、知识库、MCP 与 Skills。

开发者视角 Copy Chapter

数据模型 Copy Section

子智能体复用 agents 表，核心字段包括：

| 字段 | 说明 |
|------|------|
| backend_id | 子智能体固定使用 SubAgentBackend |
| is_subagent | 子智能体标记，SubAgentBackend 必须对应 true |
| config_json.context | 子智能体自己的运行配置 |
| share_config | 可见性与管理权限，沿用 Agent 共享模型 |

后端会校验 backend_id 与 is_subagent 一致：普通 Agent 不能伪装成子智能体，SubAgentBackend 也不能以普通 Agent 形态保存。子智能体不能被设置为默认 Agent。

API 与列表语义 Copy Section

子智能体沿用 /api/agent CRUD：

- GET /api/agent 默认只返回聊天可用的普通 Agent。
- GET /api/agent?include_subagents=true 返回管理页需要的完整 Agent 列表。
- 创建或更新 SubAgentBackend 时，payload 会携带或推导 is_subagent=true。
- 详情、更新和删除仍走同一套 Agent 管理接口，并复用现有权限过滤。

旧的独立 SubAgent 管理链路已经移除，不再维护单独的启停状态、内置初始化或 spec 缓存。

运行时调用链 Copy Section

主 Agent 构图时，会先把 context.subagents 归一化为当前用户可见的允许列表；允许列表非空时挂载 Yuxi 的 task middleware。middleware 会把允许的子智能体列表注入模型提示，并暴露一个 task 工具。

工具参数为：

class TaskToolSchema(BaseModel):
    description: str
    subagent_slug: str
    thread_id: str | None = None

thread_id 是可选的子智能体线程 ID。新任务不需要填写；如果要继续之前同一个子智能体任务，应使用上一次 task 工具结果中的 子智能体线程 ID。

执行时的关键流程：

1. 从父 Agent 的 context.subagents 读取允许的子智能体 slug；未显式配置或空列表会展开为当前用户可见的全部子智能体。
2. 使用 AgentRepository 加载当前用户可见且 is_subagent=true 的 Agent。
3. 新任务会为本次调用生成 child checkpoint thread id，例如 <parent_thread_id>_sub_<slug>_<uuid8>；续跑任务会校验并复用传入的 thread_id。
4. 使用子智能体自己的 SubAgentContext 和 config_json.context 构建真实 Agent graph。
5. 调用结束后，把子智能体线程 ID 和最终 assistant 文本作为 task 工具结果返回给主 Agent。

SubAgentBackend 复用普通 Agent 的运行时资源归一化流程，但不会挂载 task middleware；它的 subagents 字段隐藏且默认为空，因此不会形成嵌套子智能体调用。

同步调用与异步调用 Copy Section

task 是同步工具：父智能体调用后会阻塞等待子智能体 run 走到终态，再拿到最终 assistant 文本。这种模式适合短任务，例如父智能体必须立即依赖子智能体结果继续推理时。

但当子任务耗时较长或可以并行多个时，同步等待会让父智能体长时间停在工具调用上，无法继续工作。因此 middleware 还同时暴露一组异步子智能体生命周期工具：

| 工具 | 作用 | 关键参数 |
|------|------|----------|
| subagent_start | 异步启动子智能体 run，立即返回 run_id 和 thread_id | description、subagent_slug、可选 thread_id |
| subagent_status | 按 run_id 查询状态，附带最近 3 条可读进度摘要；run 终态时返回最终结果 | run_id |
| subagent_cancel | 取消运行中的子智能体 run | run_id |
| subagent_await | 阻塞等待子智能体 run 终态并返回最终结果；超时返回当前快照和 wait_timed_out 标志 | run_id |

调用约束：

- 长任务或多个可并行任务优先使用 subagent_start，让父智能体继续推进主流程；短任务需要立即拿到结果时继续使用 task。
- thread_id 是子智能体的长期上下文 ID，同一个 thread_id 终态后可以再创建新的 run 续跑。若同线程已有运行中的 run，subagent_start 会返回 busy 结构，不会隐藏排队。
- subagent_status、subagent_cancel、subagent_await 都按 run_id 操作，并校验该 run 是否归属当前父 run 创建的子智能体，避免越权访问其它子任务。
- Redis 原始事件流只供运行基础设施和前端 SSE 订阅使用，不作为模型工具结果返回；父智能体通过 subagent_status 获取轻量进度，通过 subagent_await 获取最终结果。
- 父智能体不应通过 shell、curl 或 HTTP API 间接调用子智能体，所有调用必须走上述工具。

异步子智能体在状态面板的「子智能体」分组中按 run_id 展示运行身份；状态查询工具不会渲染成独立 Agent 卡片，弹窗会随子智能体条目补齐 run_id 后订阅对应 SSE，已完成的子智能体改为直接读取持久化 Message 历史。

文件系统与沙盒作用域 Copy Section

子智能体与主 Agent 共享文件系统时使用拆分作用域：

| 路径/作用域 | 普通 Agent | 子智能体 |
|------|------|------|
| LangGraph checkpoint | 当前 thread_id | child thread_id |
| /home/gem/user-data/workspace | 当前 uid 的共享工作区 | 同一 uid 的共享工作区 |
| /home/gem/user-data/uploads | 当前会话文件作用域 | 父会话 file_thread_id |
| /home/gem/user-data/outputs | 当前会话文件作用域 | 父会话 file_thread_id |
| /home/gem/skills | 当前 Agent 的 Skills 作用域 | 子智能体自己的 skills_thread_id |

这保证子智能体可以读取父会话上传、产物也会回到父会话 artifacts 中，同时子智能体的 Skills 不会污染主 Agent。

---

Agents/Tools System Copy Section

工具系统

Yuxi 的工具系统基于注册机制，支持多种工具类型的动态组装。

工具注册机制 Copy Chapter

Yuxi 的工具系统采用 @tool 装饰器注册机制，核心位于 backend/package/yuxi/agents/toolkits/registry.py。

@tool 装饰器 Copy Section

from yuxi.agents.toolkits.registry import tool
@tool(category="buildin", tags=["示例"], display_name="示例工具")
def example_tool(text: str) -> str:
    """示例工具：返回处理后的文本"""
    ...

装饰器参数：
- category: 工具分类，用于分组，例如 buildin、knowledge、debug
- tags: 标签列表，用于前端展示
- display_name: 显示名称（给人看的名字）
- icon: 图标名称（可选）

自动发现 Copy Section

导入 toolkits 包时会自动触发注册：

from yuxi.agents.toolkits import buildin, debug  # 触发模块内 @tool 装饰器执行

toolkits/__init__.py 会导入 buildin 与 debug 模块；知识库工具由内置 knowledge-base Skill 的依赖显式注册，而不是作为所有 Agent 的默认工具。

工具分类 Copy Chapter

内置工具 (buildin) Copy Section

| 工具 | 说明 |
|------|------|
| ask_user_question | 向用户发起交互式提问 |
| ocr_parse_file | 将 uploads、outputs 或 workspace 中的 PDF、Office 或图片文件转换为 Markdown |
| present_artifacts | 展示 Agent 沙盒 outputs 目录下的产物文件 |
| install_skill | 从沙盒路径或 Git 来源安装当前用户私有 Skill，并激活当前主智能体会话；子智能体禁用 |
| tavily_search | Tavily 网页搜索（需配置 TAVILY_API_KEY） |

Qwen-Image 生成能力已迁移为内置 Skill image-gen。模型调用与图片下载在 Agent 沙盒中完成，生成后的图片保存到 /home/gem/user-data/outputs/，再通过 present_artifacts 展示。

知识库工具 (kbs) Copy Section

知识库工具使用 @tool(category="knowledge") 注册，并通过内置 knowledge-base Skill 的 tool_dependencies 按需加载。get_common_kb_tools() 仍可用于直接获取完整工具列表：

from yuxi.agents.toolkits.kbs import get_common_kb_tools
kb_tools = get_common_kb_tools()
返回: [list_kbs, get_mindmap, query_kb, find_kb_document, open_kb_document]

| 工具 | 说明 |
|------|------|
| list_kbs | 列出用户可访问的知识库 |
| get_mindmap | 获取知识库的思维导图结构 |
| query_kb | 按 kb_id 检索内容，返回结构化的 kb_id、file_id 与命中片段 |
| find_kb_document | 在已知文件内按关键词或正则定位内容 |
| open_kb_document | 按 file_id 分段打开知识库文档（默认窗口 1800 行） |
| search_file | 按文件名在指定或全部可见知识库中搜索文件 |

工具组装 Copy Chapter

工具组装在 Graph 创建阶段完成。内置 Agent 会先调用 prepare_agent_runtime_context 过滤当前用户可用资源，再调用 resolve_configured_runtime_tools(context) 加载已配置工具：

1. 基础工具：从 context.tools 中按名称筛选
2. MCP 工具：根据 context.mcps 加载 MCP 服务器工具
3. Skill 依赖工具：由 SkillsMiddleware 在 Skill 激活后按需追加，包括 knowledge-base 绑定的知识库工具

from yuxi.agents.context import prepare_agent_runtime_context
from yuxi.agents.toolkits.service import resolve_configured_runtime_tools
context = await prepare_agent_runtime_context(context, user=current_user, db=db)
tools = await resolve_configured_runtime_tools(context)

Skills 集成 Copy Chapter

Skills 与工具是两种不同的扩展机制。工具是具体的功能实现，而 Skills 是包含提示词、工具依赖和元数据的完整技能包。通过 context.skills 配置 Skills 时，共享与内置 Skill 从 /home/gem/skills/<slug>/... 读取，个人 Skill 从 /home/gem/user-data/workspace/agents/skills/<slug>/... 读取；智能体通过对应的 SKILL.md 了解使用方式。

关于 Skills 的详细机制，请参阅 Skills 管理。

---

Advanced/Api Key Integration Copy Section

API Key 外部集成

Yuxi 平台提供了 API Key 认证机制，允许外部系统在无需用户登录的情况下调用智能体对话接口。本文档详细介绍 API Key 的使用方法、接口调用方式以及安全注意事项。

API Key 概述 Copy Chapter

API Key 是一种用于身份验证的密钥字符串，外部系统可以通过它在请求头中携带凭据来访问 Yuxi 的对话接口。与传统的用户名密码登录方式相比，API Key 更加适合用于系统间的自动化调用场景。Yuxi 的 API Key 以 yxkey_ 为前缀，长度为 54 个字符，采用 SHA-256 哈希存储，确保密钥本身不会在数据库中明文保存。系统会记录每个 API Key 的最后使用时间，方便管理员追踪使用情况。

创建 API Key Copy Chapter

登录系统后，进入 API Key 管理界面，可以创建新的密钥。创建时需要为 API Key 设置一个名称，用于标识其用途，例如"外部客服系统"或"数据同步服务"。创建的 API Key 会自动绑定到当前登录用户，绑定后的 API Key 在调用接口时会以该用户的身份执行操作。API Key 还支持设置过期时间，过期后该密钥将自动失效。

需要特别注意的是，创建 API Key 时返回的完整密钥（secret）只会显示一次，务必在创建时将其安全保存。如果遗失，请删除旧密钥并创建一个新的 API Key。

管理接口同样走通用认证：

- GET /api/user/apikey/：列出当前用户可见的 API Key
- POST /api/user/apikey/：创建 API Key
- PUT /api/user/apikey/{api_key_id}：更新名称、状态或过期时间
- DELETE /api/user/apikey/{api_key_id}：删除密钥

确定 API 访问地址 Copy Chapter

Yuxi 后端服务绑定在 0.0.0.0:5050，不会自动探测或对外宣告本机 IP。实际访问地址取决于部署环境：

- 本地开发：http://localhost:5050
- 生产部署（Nginx 反向代理）：强烈建议使用 HTTPS，即 https://<服务器域名>（443 端口）。由于 API Key 会在请求头中以明文形式传输，使用 HTTP（80 端口）会导致密钥在网络传输过程中被窃听或篡改，必须避免

完整的 API 交互流程可参考自动生成的 Swagger 文档：{base_url}/docs。

接口调用方式 Copy Chapter

关于 agent_id / agent_slug 的说明：创建会话线程时仍使用 agent_id 绑定目标 Agent；创建运行任务时使用 agent_slug 快照本次运行目标。二者的取值都是智能体的 slug（如 default-chatbot），不是数据库自增 ID 或 agent_config_id。

外部系统通过 HTTP 请求调用 Yuxi 接口时，需要在请求头中携带 API Key：

Authorization: Bearer yxkey_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

当前智能体对话采用 run + SSE 流程：

1. 创建对话线程：POST /api/chat/thread
2. 创建运行任务：POST /api/agent/runs
3. 订阅事件流：GET /api/agent/runs/{run_id}/events

POST /api/agent/runs 请求体必填 query、agent_slug 和 thread_id，可选字段包括 meta、image_content、resume、created_by_run_id。接口返回 run_id、thread_id、status、request_id 和 stream_url。

以下是一个典型的 Python 调用示例：

/ Detailed source-code truncated for AI context efficiency. /

如果已经有会话线程，可以复用已有 thread_id 直接创建 run：

{
    "query": "继续上一轮话题",
    "agent_slug": "default-chatbot",
    "thread_id": "existing-thread-id",
    "meta": {}
}

读取运行结果 Copy Section

如果不需要逐事件消费 SSE，可以在 run 终态后直接拉取最终结果：

GET /api/agent/runs/{run_id}/result

返回结构包含运行状态、最终 assistant 输出、Langfuse trace id 和错误信息。该接口只读，不会再次触发 run。对外部系统只关心「最终答案」、不需要展示中间过程的场景，比订阅 SSE 更简单。

外部系统调用入口 Copy Section

除通用 /api/agent/runs 之外，Yuxi 还提供专为外部系统设计的 agent-invocation 路由，复用同一套 AgentRun 队列与结果读取能力：

| 接口 | 用途 | 关键字段 |
|------|------|----------|
| POST /api/agent-invocation/agent-call/runs | 外部系统调用 Agent；async_mode=true 时立即返回 run_id，否则阻塞到 run 终态返回结果 | agent_slug、messages、thread_id、request_id、model_spec、async_mode |
| POST /api/agent-invocation/agent-call/runs/result | 读取 agent-call run 的 OpenAI 兼容结果结构 | run_id、可选 agent_slug |
| POST /api/agent-invocation/eval/runs | 运行一次评估样例，阻塞到 run 终态后返回最终输出与可选轨迹摘要 | query、agent_slug、evaluation、include_trajectory_summary |

agent-call 的 messages[].content 兼容 OpenAI 风格的 text/image_url 多模态数组：纯文本数组不会触发 422，图片输入会保留原始 LangChain 多模态消息供 worker 恢复。出于安全考虑，不允许通过 agent_call_meta.context 覆盖 Agent 运行上下文；运行时模型覆盖只允许走独立 model_spec 字段。Agent Eval 通常通过 yuxi agent eval CLI 触发，详见智能体评估。

响应格式 Copy Chapter

运行事件流采用 Server-Sent Events 格式，响应头为 text/event-stream。每个事件包含：

- event：事件类型，可能是模型输出、工具调用、子智能体输出等语义事件，也可能是 error 或终止事件 end
- data：JSON 编码的事件 envelope，包含 run_id、thread_id、事件载荷等字段
- id：Redis Stream 序号，可作为断线重连游标

服务端还会定期发送以 : 开头的 heartbeat 注释，客户端应忽略。断线重连时，可以在请求头中传 Last-Event-ID，或在 query 参数中传 after_seq，服务端会从该序号后继续回放事件。

事件流默认返回完整载荷，便于排查 LangGraph/Langfuse 运行细节。如果只需要渲染消息、工具调用、工具结果、Agent state 和终止状态，可以在订阅地址追加 ?verbose=false。精简模式会保留 SSE event/data/id、data 中的 run_id/thread_id/request_id/payload 以及客户端消费所需字段；同一 data 内的 request_id 会外提为单个字段。精简模式还会跳过 metadata 和空 yuxi.agent_state，并去掉每个 chunk 中重复的 meta、metadata、thread_id、response、空 namespace 和图片 base64 等调试字段。

每次创建 run 都会返回 request_id，可用于日志追踪和问题排查。如果需要在多轮对话中使用同一个会话，请复用 thread_id，系统会将同一线程的消息串联起来形成连贯的对话上下文。

认证方式 Copy Chapter

Yuxi 的 API 接口统一支持两种认证方式：

1. API Key 认证：使用 Authorization: Bearer <api_key> 格式，其中 API Key 必须以 yxkey_ 前缀开头
2. JWT Token 认证：使用 Authorization: Bearer <jwt_token> 格式

系统根据 token 的前缀自动判断认证方式。以 yxkey_ 开头的 token 被视为 API Key，其他 token 则作为 JWT Token 处理。这种设计使得同一个接口可以同时支持外部系统（使用 API Key）和内部前端应用（使用用户登录态）调用。

安全注意事项 Copy Chapter

传输层安全：API Key 在请求头中以明文形式传输，生产环境必须通过 HTTPS（443 端口）调用，避免在公网上以 HTTP 明文传输造成密钥泄露。建议在 Nginx 反向代理层启用 TLS 并强制 HTTP 重定向到 HTTPS。

保管好 API Key 密钥是最重要的安全原则。由于 API Key 一旦泄露就可能被滥用，建议不要将密钥硬编码在代码中，而是通过环境变量或配置中心来管理。如果怀疑密钥泄露，应立即在管理界面禁用或删除该 API Key，并创建新密钥替换。启用密钥过期功能是一种良好的安全实践，可以设置较短的有效期并定期轮换。

在生产环境中，建议为不同的外部系统创建独立的 API Key，这样可以在某个密钥泄露时快速定位问题并限制影响范围。同时，建议在管理界面定期查看 API Key 的使用记录，检查是否存在异常调用情况。

关于权限控制，API Key 的权限等同于其绑定的用户在系统中的角色。如果 API Key 绑定到特定用户，则该用户的所有权限都会体现在 API Key 的操作中，因此务必妥善保管。

---

Advanced/Branding Copy Section

品牌自定义

Yuxi 支持完整的品牌自定义，包括 Logo、组织名称、版权信息、登录协议等，方便企业用户进行品牌定制。

品牌信息配置 Copy Chapter

步骤 1：复制模板文件 Copy Section

cp backend/package/yuxi/config/static/info.template.yaml backend/package/yuxi/config/static/info.local.yaml

步骤 2：编辑品牌信息 Copy Section

在 backend/package/yuxi/config/static/info.local.yaml 中配置你的品牌信息：

- 应用名称
- 组织名称
- Logo
- 版权信息
- 登录页用户协议/隐私协议链接

步骤 3：指定配置文件 Copy Section

在 .env 中指定配置文件路径：

YUXI_BRAND_FILE_PATH=backend/package/yuxi/config/static/info.local.yaml

::: tip 配置优先级
info.local.yaml > info.template.yaml（默认）
:::

登录协议配置 Copy Chapter

登录页支持从品牌配置中读取用户协议与隐私协议链接。

配置项 Copy Section

在 backend/package/yuxi/config/static/info.local.yaml 的 footer 下新增以下字段：

footer:
  copyright: "© your org 2026"
  user_agreement_url: "/protocols/user-agreement.template.html"
  privacy_policy_url: "/protocols/privacy-policy.template.html"

显示规则 Copy Section

- 当 user_agreement_url 和 privacy_policy_url 都有值时，登录页会显示协议勾选项。
- 任一字段为空时，登录页不显示协议勾选项。
- 未勾选协议时，提交登录/初始化会通过消息提示用户先同意协议。

协议模板文件 Copy Section

系统默认提供两个 HTML 模板文件：

- web/public/protocols/user-agreement.template.html
- web/public/protocols/privacy-policy.template.html

你可以直接编辑这两个文件中的协议内容，并替换占位符（如 {{ORG_NAME}}、{{PRODUCT_NAME}}、{{EFFECTIVE_DATE}}）。

如果你有自己的协议页面，也可以将 user_agreement_url 和 privacy_policy_url 指向自定义路径或外部链接。

Icon 定制 Copy Section

系统预设了多种 Icon，如需更多图标，可以从 lucide-vue-next 中引入。

样式定制 Copy Chapter

系统支持完整的主题色定制。配置文件位于 web/src/assets/css/base.css，以及 web/src/assets/css/base.dark.css：

:root {
  --main-color: #1890ff;        / 主色调 /
  --main-1000: #f0f2f5;          / 色板 /
  --main-900: #e6f7ff;           / 色板 /
  / ... 其他色板 /
}

修改配色变量后，界面会实时更新，无需重启服务。

此外，web/src/stores/theme.js 中的 colorPrimary 也需要同步修改。

---

Advanced/Configuration Copy Section

配置系统详解

概述 Copy Chapter

系统采用分层配置架构，模型供应商和运行时系统配置由网页界面管理，启动期配置由环境变量提供。

配置层级 Copy Chapter

代码默认值 → 环境变量 → PostgreSQL 管理员配置
   (低)                              (高)

模型配置 Copy Chapter

由网页统一管理，详见 模型配置。

应用配置 Copy Chapter

运行时系统配置定义于 backend/package/yuxi/config/options.py，管理员通过系统配置页面或 /api/system/config 接口修改，值保存到 PostgreSQL。API 与 worker 通过 Redis 短期缓存共享配置；Redis 不可用时直接回源 PostgreSQL。

读取配置 Copy Section

from yuxi.config.options import system_options
values = await system_options.get()
default_model = values["default_model"]

管理员更新配置后，服务先提交 PostgreSQL，再失效 Redis 缓存。运行中的 API 和 worker 会在下一次读取时获得最新配置，不需要重启。

SAVE_DIR、数据库、Redis、sandbox 和 LangGraph checkpointer 后端仍属于启动期环境变量配置。运行中的已初始化组件不承诺这些配置热更新，修改后需要重启服务。

升级时，服务会一次性把旧 saves/config/base.toml 或旧数据库系统配置迁移到 PostgreSQL；已存在的管理员值不会被旧配置覆盖。迁移完成后不再读取 base.toml。

---

Advanced/Deployment Copy Section

生产部署指南

本文档介绍如何在生产环境中部署 Yuxi。

前置要求 Copy Chapter

- Docker Engine (v24.0+)
- Docker Compose (v2.20+)
- NVIDIA Container Toolkit（如需使用 GPU 服务）

::: warning 注意事项
1. 生产环境和开发环境建议使用不同的机器，避免端口和资源冲突
2. 虽然名为「生产环境」，但这只是基本配置，真正上线需要根据实际情况调整
3. 前端有调试面板（长按侧边栏触发），生产环境建议关闭
:::

部署步骤 Copy Chapter

1. 准备配置文件 Copy Section

为避免与开发环境冲突，生产环境建议使用 .env.prod 文件：

cp .env.template .env.prod

编辑 .env.prod，设置强密码和必要的 API 密钥：

POSTGRES_PASSWORD=
NEO4J_PASSWORD=
MINIO_ACCESS_KEY=
MINIO_SECRET_KEY=
JWT_SECRET_KEY=
YUXI_INSTANCE_ID=
SANDBOX_PROVISIONER_TOKEN=
SILICONFLOW_API_KEY=

生产 Compose 会在前七项配置缺失或为空时拒绝启动，并提示具体变量名。JWT_SECRET_KEY 和 SANDBOX_PROVISIONER_TOKEN 均应至少使用 32 字节随机值并持久保存，可分别使用 openssl rand -hex 32 生成；两者不能复用。YUXI_INSTANCE_ID 应是每套部署稳定且唯一的实例标识。模型 API 密钥按实际使用的供应商配置。

2. 启动服务 Copy Section

使用生产环境配置文件启动：

仅启动核心服务（CPU 模式）

docker compose -f docker-compose.prod.yml up -d --build
启动所有服务（包含 GPU OCR）

docker compose -f docker-compose.prod.yml --profile all up -d --build

3. 验证部署 Copy Section

- Web 访问：http://localhost（直接通过 80 端口）
- API 健康检查：curl http://localhost/api/system/health

公开头像和 Agent 图片通过前端同源路径 /minio/public/... 读取，由 Nginx 只读代理到 MinIO 的 public bucket。无需也不应向公网开放 MinIO 的 9000 对象 API 或 9001 管理控制台；知识库等私有 bucket 不经过这个代理。需要使用独立静态资源域名时，可在 .env.prod 中设置 MINIO_PUBLIC_URL=https://assets.example.com，并在该域名侧保持同等的只读 bucket 限制。

历史 PDF 解析 Markdown 中已经写入的 http://localhost:9000/public/... 或其他 <host>:9000/public/... 图片地址，会在前端渲染时自动转换为同源路径，不需要重新解析 PDF。

跨域（CORS）配置 Copy Chapter

docker-compose.prod.yml 默认把 YUXI_ENV 设为 production，后端在该环境下会按 YUXI_CORS_ORIGINS 显式声明允许的来源。未配置时返回空列表，浏览器跨域请求会被拒绝。生产部署前请根据前端与 API 的相对位置选择策略：

| 部署形态 | 推荐配置 |
|----------|----------|
| 前端与 API 同源（Nginx 同端口反代） | 不需要设置，留空即可 |
| 前端与 API 跨域部署 | YUXI_CORS_ORIGINS=https://your-frontend.example.com |
| 多个前端域名 | 逗号分隔，如 https://a.example.com,https://b.example.com |
| 完全放开（不推荐） | YUXI_CORS_ORIGINS=*，会自动关闭 credentials，登录态/JWT 无法跨域携带 |

开发环境（YUXI_ENV=development 且未设置该变量）默认允许 http://localhost:5173 与 http://127.0.0.1:5173，方便本地前后端独立启动调试。从 0.7.0 升级到 0.7.1 时，如果此前是跨域部署但未显式声明来源，必须补上 YUXI_CORS_ORIGINS，否则前端跨域请求会被拒绝。

维护与更新 Copy Chapter

从使用默认凭据的版本升级 Copy Section

如果部署曾使用仓库历史默认的 PostgreSQL、Neo4j 或 MinIO 凭据，升级 Compose 文件本身不会保证已有数据卷中的服务凭据已经改变。升级前应分别通过对应服务的管理命令真实修改凭据，再把新值写入 .env.prod；完成后重建相关服务，并使用旧凭据验证登录已被拒绝。

PostgreSQL 可以在数据库容器内使用交互式命令修改，避免新密码出现在 shell 历史和进程参数中：

docker compose -f docker-compose.prod.yml exec postgres psql -U postgres -d yuxi -c '\password postgres'

Neo4j 应使用 cypher-shell 的当前用户密码修改流程；MinIO 应使用 mc admin 或部署所采用的密钥管理流程。不要把真实密码写入文档、测试脚本或命令历史。完成凭据轮换并配置 SANDBOX_PROVISIONER_TOKEN 后，再执行下面的重建命令。

更新代码 Copy Section

拉取最新代码

git pull
重新构建并启动

docker compose -f docker-compose.prod.yml up -d --build

生产 Compose 不再向宿主机发布 PostgreSQL 和文档解析服务端口。确需从宿主机维护时，优先使用 docker compose exec；不要为了临时调试把这些端口重新暴露到公网。

查看日志 Copy Section

API 日志

docker logs -f api-prod
Nginx 访问日志

docker logs -f web-prod

---

Advanced/Document Processing Copy Section

文档处理与 OCR

Yuxi 将上传文件先保存为原文件，再解析为 Markdown 并按知识库分块策略入库。管理员可在“设置 → OCR 配置”选择默认 OCR 方法，并维护确有需要的服务地址和云端凭证；知识库上传或临时附件解析仍可逐次选择方法，未显式选择时使用系统默认项。

支持的文件类型 Copy Chapter

常规文档 Copy Section

| 类型 | 格式 | 说明 |
|------|------|------|
| 文本 | .txt, .md, .html, .htm | 直接提取内容 |
| Word | .docx | 保留格式和结构 |
| PowerPoint | .pptx | 保留主要文本结构 |
| PDF | .pdf | 支持文本和图片 PDF |
| 表格 | .csv, .xls, .xlsx | 识别表格结构 |
| JSON | .json | 结构化数据 |

图片文件 Copy Section

图片文件必须选择 OCR 引擎才能提取文字：
- .jpg, .jpeg, .png, .bmp, .tiff, .tif

压缩包 Copy Section

支持上传 ZIP 压缩包，系统会：
- 自动提取并处理其中的 Markdown 文件
- 处理图片并上传到对象存储
- 智能识别 full.md 或第一个 .md 文件

网页内容 Copy Section

知识库支持先从 URL 抓取页面内容，再作为文件进入现有上传、解析与入库链路：

1. 配置 YUXI_URL_WHITELIST 环境变量启用白名单机制
2. 系统自动将 HTML 转换为 Markdown
3. 内置去重机制，避免重复抓取

::: tip URL 白名单配置
示例：YUXI_URL_WHITELIST=github.com,*.wikipedia.org,docs.python.org
:::

OCR 方案选择 Copy Chapter

系统提供多种 OCR 方案，适用于不同场景：

方案对比 Copy Section

| 方案 | 适用场景 | 硬件要求 | 特点 |
|------|----------|----------|------|
| RapidOCR | 基础文字识别 | CPU | 免费开源，速度快 |
| MinerU | 复杂 PDF、表格 | GPU | 精度高，版面分析好 |
| MinerU Official | 复杂文档 | 无 | 官方云服务，开箱即用 |
| PP-Structure-V3 | 表格、票据 | GPU | 专业版面解析 |
| DeepSeek OCR | 智能理解 | 无 | 复用 SiliconFlow 模型供应商，Markdown 输出 |
| PaddleOCR-VL-1.6 | 复杂文档、表格、图片 PDF | 无 | 百度 AI Studio 云端服务，输出 Markdown |
| PP-OCRv6 | 基础文字识别 | 无 | 百度 AI Studio 云端 OCR，输出纯文本 |

后端保存的引擎标识与界面名称对应如下：rapid_ocr、mineru_ocr、mineru_official、pp_structure_v3_ocr、deepseek_ocr、paddleocr_vl_1_6、paddleocr_pp_ocrv6。

选择建议 Copy Section

- 个人使用或 CPU 环境：选择 RapidOCR，免费且资源占用低
- 高精度需求：选择 MinerU（需要 GPU）或 MinerU Official
- 表格密集型文档：选择 PP-Structure-V3
- 云端版面解析：选择 PaddleOCR-VL-1.6，适合希望输出 Markdown 的 PDF 或图片文档
- 云端纯文字识别：选择 PP-OCRv6，适合只需要提取图片文字的场景
- 简单云服务：选择 DeepSeek OCR 或 PaddleOCR API

快速配置 Copy Chapter

管理员打开“设置 → OCR 配置”后，可以：

- 选择全局默认 OCR 方法
- 配置 MinerU、PP-Structure 等自托管服务端点
- 每个服务使用独立卡片；非编辑状态以禁用输入框展示当前数据库值或环境变量来源，敏感字段只显示脱敏预览
- 点击卡片右上角“编辑”后修改配置；取消不会修改，留空保存会清除数据库值并改为读取环境变量

DeepSeek OCR 固定复用 siliconflow-cn 模型供应商的 API 密钥与 Base URL，不显示独立配置表单。其他服务配置保存在通用 config_options 表中：每次运行时读取都会查询数据库，数据库非空值优先，字段为空时读取对应环境变量。API Key / Token 允许明文写入数据库，这是明确的部署取舍；需要脱敏的字段由定义中的 sensitive 元数据显式标记。读取接口不会回显密钥原文：数据库值只返回真实首尾字符的脱敏预览，环境变量只返回配置来源，前端不会获得环境变量内容。

附件添加和知识库解析统一使用 OCR Selector。Selector 每次展开都会刷新全部 OCR 方法的健康状态；可用方法直接显示标题和状态，不可用方法默认折叠，管理员可通过右上角“去配置”直接打开 OCR 配置页。后端系统配置仍允许将默认值设为 disable，但 Selector 默认不展示该选项；需要显示时必须由调用方显式开启。

RapidOCR Copy Section

启动后会默认下载，无需配置

MinerU（高精度） Copy Section

项目已内置 mineru-api 服务（位于 docker-compose.yml，属于 all profile），无需额外下载官方 compose 文件。首次构建镜像时会基于 docker/mineru.Dockerfile 下载模型，该过程耗时较长。

启动服务（需要 GPU）：

docker compose --profile all up -d --build mineru-api

该服务在 30001 端口提供 /file_parse 接口，后端 api / worker 默认通过 MINERU_API_URI=http://mineru-api:30001 连接，通常无需额外配置。

::: tip 显存不足
若显存有限导致启动失败，可在 docker-compose.yml 的 mineru-api 服务下放开 --gpu-memory-utilization 参数（如 0.5，必要时进一步降低）。
:::

MinerU Official（云服务） Copy Section

从 MinerU 官网 获取 API 密钥，在 .env 配置环境变量

MINERU_API_KEY=your-api-key-here

PP-Structure-V3（结构化） Copy Section

启动服务（需要 GPU）

docker compose up paddlex -d

DeepSeek OCR（简单云服务） Copy Section

在模型供应商配置中启用 siliconflow-cn 并配置 API 密钥。DeepSeek OCR 会复用该供应商的 Base URL 和凭证，不需要额外配置。

PaddleOCR API（百度 AI Studio 云服务） Copy Section

PaddleOCR API 使用百度 AI Studio 的 Access Token。获取方式：

1. 登录 百度 AI Studio Access Token 页面
2. 在页面中复制 Access Token
3. 在 .env 中配置为 PADDLEOCR_API_TOKEN

PADDLEOCR_API_TOKEN=your-access-token-here

如需使用自定义 PaddleOCR API 地址，可额外配置：

PADDLEOCR_API_URL=https://paddleocr.aistudio-app.com/api/v2/ocr/jobs

配置完成后，重启后端服务，在上传文件或解析临时附件时可以选择：

- PaddleOCR-VL-1.6：对应 paddleocr_vl_1_6，用于文档版面解析，返回 Markdown
- PP-OCRv6：对应 paddleocr_pp_ocrv6，用于基础 OCR，返回按行拼接的纯文本

解析参数与分块快照 Copy Chapter

知识库分块配置由两部分组成：chunk_preset_id 只表示策略（general、qa、book、laws、semantic、separator），具体参数统一放在 chunk_parser_config 中。不要再写入旧的根级 chunk_size、chunk_overlap 或 qa_separator 字段。

文件级 processing_params 保存 ocr_engine、分块策略和 chunk_parser_config。OCR 的连接端点和凭证在执行时从通用配置或环境变量读取，不写入文件快照。

图片显示配置 Copy Chapter

上传文档中的图片需要正确配置才能在外部显示：

在 .env 中设置服务器 IP：

HOST_IP=your_server_ip

注意事项 Copy Chapter

1. 图片文件必须启用 OCR：否则无法提取内容
2. GPU 要求：MinerU 和 PP-Structure-V3 需要 GPU 支持
3. API 密钥：DeepSeek OCR 复用 siliconflow-cn 模型供应商凭证；MinerU Official 和 PaddleOCR API 需要各自的 API 密钥或 Access Token
4. 超时处理：复杂文档解析可能耗时较长，可通过 MINERU_TIMEOUT 环境变量调整超时时间
5. 文件大小限制：知识库与工作区的单个上传文件大小均不超过 100 MB；工作区一次最多上传 50 个文件
6. 解析配置：文件只保存当次 ocr_engine 与分块参数快照；端点和凭证执行时使用最新通用配置或环境变量
7. Agent 读取非文本文件：Agent 的 read_file 只直接读取 UTF-8 文本和图片；遇到 PDF、Office 或其他二进制文件时，应使用 ocr_parse_file 生成 Markdown 后再读取

---

Advanced/Langfuse Integration Copy Section

Langfuse 集成

为什么 Yuxi 需要 Langfuse Copy Chapter

Langfuse 是一套面向大模型应用的可观测性平台，适合用来观察一次智能体执行过程中到底发生了什么。在 Yuxi 里，一轮用户消息通常不会只对应一次简单的模型调用，它往往会伴随 LangGraph 图执行、工具调用、知识库检索以及多轮中间状态切换。仅靠普通后端日志，虽然也能定位问题，但往往需要在多个文件和多个服务日志之间来回跳转，阅读成本高，而且很难从用户、线程和智能体三个维度统一查看。Langfuse 的价值就在于，它把这些原本分散的执行细节收拢到同一条 trace 里，让你能够从一次对话出发，回看模型输入输出、工具链路、耗时和错误位置。

在 Yuxi 当前的实现中，Langfuse 主要承担的是智能体执行观测层，而不是业务主流程的一部分。换句话说，它不会替代模型服务，也不会替代聊天接口本身，而是帮助你在智能体已经能够工作的前提下，看清楚它是如何工作的。对于调试复杂 Agent、排查工具调用失败、评估多轮会话质量以及分析不同智能体的耗时与成本来说，这类观测能力非常关键。尤其是在一个线程里连续发生多轮交互时，Langfuse 可以帮助你把“这轮请求是谁发起的、落在哪个 thread、触发了哪个 agent、调用了哪些模型和工具”这些信息统一串起来。

在 Yuxi 中能做什么 Copy Chapter

Yuxi 对 Langfuse 的映射方式比较直接。一个 Yuxi 用户会映射为 Langfuse 中的 user_id，一个对话线程会映射为 session_id，而每次用户输入触发的一轮智能体执行会形成一条独立的 trace。这样做的好处是，既能按单轮请求排查问题，也能在同一个线程维度下连续查看多轮会话。对于需要长期分析使用质量、成本和延迟的场景，这种映射方式能够兼顾可读性和后续统计需求。

当 Langfuse 与 Yuxi 连通之后，它最直接的作用是帮助你看清一轮智能体请求内部发生了哪些步骤。你可以看到这一轮调用关联的是哪个用户、哪个线程、哪个智能体，也可以进一步观察模型调用、工具调用和整体耗时表现。对于日常调试来说，它让“问题到底出在模型、工具、配置还是图流程”这件事变得更容易判断。对于长期运行的系统来说，它也为后续做延迟分析、成本分析和用户反馈分析提供了统一的观察入口。

用户在对话界面对助手消息提交点赞或点踩后，Yuxi 会继续把反馈保存在本地业务表中；如果该助手消息已经关联 Langfuse trace，则会同步写入 Langfuse score。同步到 Langfuse 的 score 名称为 user-feedback，点赞值为 1，点踩值为 0，点踩原因会作为 score comment 保存，便于在 Langfuse 中按低分反馈筛选和分析具体 trace。

如何配置 Copy Chapter

如果你准备启用 Langfuse，首先需要在 Langfuse Cloud 中创建项目并获取访问凭证。当前版本推荐优先使用云端模式，因为接入成本最低，也更适合先把 tracing 跑通。你需要在运行 Yuxi 的环境中配置 LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY 和 LANGFUSE_BASE_URL。其中前两个字段用于鉴权，LANGFUSE_BASE_URL 用于指定 Langfuse 服务地址；如果你使用官方云服务，通常可以直接填写 https://cloud.langfuse.com。在大多数部署场景下，只要把这些变量写入 .env 并通过 Docker Compose 传给 api 服务即可生效。

从当前实现来看，Langfuse 只有在 key 配置完整时才会被启用。如果没有配置 LANGFUSE_PUBLIC_KEY 或 LANGFUSE_SECRET_KEY，Yuxi 会自动退化为“不启用 tracing”的状态，正常聊天功能不会因此中断。这意味着 Langfuse 是一个可选增强项，而不是系统启动的前置依赖。对于希望先验证主流程、后续再逐步补全观测能力的部署者来说，这种行为比较友好，因为它降低了接入门槛，也减少了配置错误对主业务的影响。

配置后系统会如何工作 Copy Chapter

理解 Langfuse 的另一个关键点在于，它并不等于“所有调试信息都会立即显示在界面里”。当前 Yuxi 的设计重点是先把 trace id 与执行上下文稳定关联起来，再把这些信息作为后续调试和分析的基础。也正因为如此，系统会优先保证聊天主链路的稳定性，而不是为了获取额外的可点击 URL 去同步等待 Langfuse 的远程接口。换句话说，Langfuse 在 Yuxi 里首先是观测数据的来源，其次才是一个方便跳转查看的外部页面入口。

这也意味着，Langfuse 接入的目标并不是改变用户聊天体验，而是在不破坏主流程稳定性的前提下，为系统补上一层可观测性。只要配置正确，用户的对话仍然按照原有方式执行，只是在后台额外留下可追踪的执行记录。对于运维和开发来说，这类“尽量不影响主流程”的接入方式更适合在现有系统中逐步落地。

如何查看是否生效 Copy Chapter

启用完成后，你最常见的查看方式是在 Langfuse 控制台中按项目查看 traces。进入项目后，可以按照用户、线程、Agent 或时间范围来筛选，定位到某一轮具体的请求。打开单条 trace 之后，你通常可以看到这一轮智能体执行的整体耗时、模型调用、工具调用以及相关 metadata。对于排查问题来说，这比直接翻阅后端日志更高效，因为你不需要自己手动拼装上下文。对于性能分析来说，也可以更直观地看出某个智能体是否在某类请求上耗时异常，或者某个工具是否经常成为慢点。

如果你是系统管理员或开发者，希望快速确认 Yuxi 是否已经成功把 tracing 打到 Langfuse，最简单的方法不是先看代码，而是先发起一条真实对话，再到 Langfuse 控制台中按最近时间排序查看是否出现新的 trace。如果配置正确，你应该可以看到对应线程下新增的一轮执行记录；如果没有看到，则优先检查 .env 中的三个关键变量是否正确传入 api 容器，以及容器内依赖是否已经包含 Langfuse SDK。对于基于 Docker Compose 的开发环境，这一步尤其重要，因为仅修改 pyproject.toml 并不会自动把新依赖装进已经运行中的镜像，通常还需要重新构建或更新容器。

当前建议的接入方式 Copy Chapter