更新日志 (Changelog)

本文档记录 Clouisle 项目的所有重要变更。

格式遵循 Keep a Changelog，版本号遵循语义化版本。

[未发布]

新增

管理后台可观测性

• 将管理后台可观测性控制台重构为概览、运行、依赖、队列、基础设施和告警六个视图，统一查看运行结果、追踪详情、模型/工具/检索依赖与运维状态。
• 在持久化 AgentRun 详情中增加有界的工具与知识检索跨度，并在“依赖”视图中汇总工具和检索的成功率与延迟。
• 每个 AgentRun 最多保留 128 个依赖跨度；达到上限时详情会标明追踪已截断，历史运行不会回填这些数据。
• 为所有已持久化的 AgentRun 生命周期状态补齐中英文翻译，并在遇到未来新增状态时安全回退为原始状态值。
• 为基础设施依赖增加有界的 PostgreSQL、Redis、Celery Worker 与 Qdrant 连通性探测，展示实测延迟，并区分不可用与未配置状态。
• 新增每分钟执行的单主 AgentRun 终态摘要对账，按有界批次修复过期的状态、时间、模型与 Token 字段，不重放运行；修复导致终态摘要丢失的 ORM 查询。
• 模型依赖卡片会将已有遥测中的 UUID 解析为配置的模型名称与供应商展示名称，支持自定义网关名称，并保留同名模型各自的统计。
• 使用独立 Celery inspector 并发采集运行任务、预取任务、定时任务与活跃队列，降低队列快照延迟，保留现有缓存与异常降级行为。
• 并发采集基础设施健康状态与慢查询统计，并将 Celery 回复收集窗口缩短至 0.5 秒，降低快照延迟，保留现有探测截止时间、异常降级和缓存行为。
• 新增 Redis 共享 API 实例发现，通过实例级上报租约去重，展示可读名称、主机资源采样及过期/离线状态；基础设施面板统一列出各后端的保留实例，不再只显示当前请求命中的实例。
• 为可观测性增加双月日历范围选择器，在弹层底部提供滚动时间预设，支持按本地时区覆盖完整日期、URL 保留，并为概览、运行列表及依赖统计统一应用 UTC 时间过滤。
• 仪表盘同步采用日历区间选择器，在弹层底部提供最近 7／30／90 天和全部时间快捷项；自定义日期统一过滤趋势、排名、模型用量、工作流摘要及对话／消息／Token 摘要与平均值，其他固定累计指标保持原定义。

沙箱出口

• 为沙箱出口精确主机名新增持久化安全设置；更新后新任务直接生效，无需重启 Worker。

沙箱生命周期审计

• 新增沙箱任务启动、完成、失败、取消与恢复的审计事件。条目记录可用的任务/会话/Worker 上下文与安全错误码，不记录代码、参数、输出或原始异常文本。

模型与工作流

• 新增 TypeSafe AI（供应商标识 typesafe，默认端点 https://api.typesafe.ai/v1/systemone）决策模型供应商和 decision 模型类型：它针对给定 state 回答带类型的 choice（最多 255 个选项）、score（2–10 个有序等级）或 noul（真/假）问题，并返回带概率分布与置信度的结构化答案。
• 新增 Decision 工作流节点：提出一个带类型的问题，按返回的答案（或概率最高的得分等级）分支，并支持回退分支和可选的置信度阈值。节点输出 answer、selected_handle、confidence、probabilities 和用量。

聊天与文件预览

• 新增统一产物列表，显示文件数量、可展开结果，并为常见文档、媒体和代码格式提供共享预览与带认证下载。
• 新增 DOCX 缩略图、页面同步、响应式适应宽度和缩放控制；新增只读 PDF 与电子表格预览控制。
• 新增 Agent 隐藏产物列表设置，默认关闭；开启后隐藏聊天中助手消息下方的生成文件列表。

记忆与 RAG

• 新增管理后台 memory 站点设置分类，可配置后台记忆提取模型、去抖冷却时间和待处理轮次阈值。
• 新增有界的 get_memory_subgraph Agent 工具，用于按关系检索记忆。

变更

管理后台可观测性

• 将页签和筛选控件统一为项目共享的 Tabs、Select、Input 组件，并统一控件高度。

Agent Studio

• 手机端 Agent 预览改为全屏抽屉式面板打开，避免并排显示时压缩编排区。

资源与媒体

• 将生成的图片和视频持久化为带范围的 Asset，并提供会话/工作流范围内供模型使用的媒体引用。
• 更新 CSV 的 GBK/GB18030 编码处理，并移除电子表格查看器中的重复下载入口。

Agent 检索与聊天时间线

• 未关联知识库的 Agent 现在会持久化并运行在 rag_mode: off；选择知识库前，Agent 编辑器隐藏 RAG 选择器。
• 聊天思考过程按检索、压缩、推理、工具和生成步骤实际发出的顺序渲染。
• 未执行检索时 rag_context 保持为 null；执行检索但没有上下文时为 []。

修复

管理后台可观测性

• 修复工具与检索跨度缺少 Token 计数时“依赖”视图接口报错的问题；此类行现在显示为不可用，而不是令整个响应失败。
• 在 Tortoise 生成模型结构和索引前，为已有 PostgreSQL observability_runs 表补充 model_name 与 message_started_at 列，修复旧数据库升级时的启动及概览查询失败。

沙箱会话

• 会话任务改走按 Worker 划分的 Celery 队列，并持久化带隔离的工作区/存储绑定；过期代际的消息会被拒绝，执行结果不确定的命令不会自动重放。
• 新增 sandbox-worker 就绪心跳、同盘监督重启与检查点恢复；原 Worker 存储不可用时按有界原子流程换绑到新工作区代际，AgentRun 收到 WORKSPACE_RESET 后重新规划，不再复用过期路径或进程状态。
• 每个 sandbox-worker 的工作区与检查点保留在 Worker 本地存储（Compose 命名卷、Kubernetes 节点本地 hostPath DaemonSet）；同节点进程替换可恢复检查点数据，节点或磁盘永久丢失则不可恢复。
• 拒绝符号链接工作区路径时使用平台 ELOOP 错误码常量。
• 延迟清理与空闲回收重试改走独立 Redis 索引，避免不可用的属主队列阻塞后续会话；首次会话分配在就绪 Worker 间分散，并对绑定/墓碑保留期设界。
• 拒绝值为零的 sandbox-worker 恢复超时。
• 隔离沙箱与依赖安装出口改走按任务 HTTPS 代理，按精确主机名放行；被拦截的主机会出现在执行诊断信息中。
• 旧版代码执行与工作流代码节点收敛到沙箱网关之后；禁用、不可用与失败的运行时直接失败，不在调用方执行负载。
• Python 与 Node 依赖安装默认限制 300 秒；超时的安装进程组会被终止，未完成的安装环境会被丢弃。
• 沙箱输出在内存中设界捕获，并对每个进程应用 prlimit 限制。直接负载在 Bubblewrap 中丢弃全部 capability；可信出口桥接在隔离网络命名空间中拉起 loopback，再设置 no-new-privileges 并清除负载 capability。交付的 Worker 为该流程保留 NET_ADMIN 并保持资源上限。

资源访问与预览

• 为生成图片、生成视频和沙箱产物增加基于范围的授权，并在客户端使用带认证的下载。
• 保留文件过大、未认证、无权限、不支持类型和解析失败等明确预览状态，不再回退到未保护的 URL。

[0.2.9] - 2026-06-09

新增

管理后台与可观测性

• 新增管理后台可观测性仪表盘，用于查看平台用量、性能、错误和活动监控
• 新增 Agent 与工作流的管理后台管理面板和路由

包导入导出

• 新增 Clouisle 包导入导出能力，支持在不同环境之间迁移应用和资源

知识库

• 新增多模态知识库资源支持，支持上传图片和媒体引用
• 新增失败分块重试和知识库文档/分块批量操作

聊天与 Agent

• 新增上传聊天图片作为媒体引用的能力
• 扩展 Agent 配置中的提示词生成上下文

变更

聊天体验

• 重构聊天消息渲染、思维链展示、工具展示和滚动行为，减少闪烁和卡死
• 优化 AI 对话流式响应超时处理

平台与权限

• 支持超级管理员转移团队所有权
• 改进 Skill 能力视图，并补全 Skill 动作映射
• 媒体生成选择器简化为仅展示模型名称

自动化与依赖

• 更新 GitHub 自动化 Action 版本和依赖锁文件
• 从版本控制中移除生成的仓库活动和文档同步工作流报告

修复

聊天与工作流

• 修复 Agent 聊天闪烁、思维链滚动状态、聊天滚动、Agentic 工作流渲染和生产环境聊天折叠卡死问题
• 修复继续对话时 Agent 消息版本分支上下文问题

知识库

• 修复知识库批量操作评审问题，以及媒体资源处理和搜索路径问题

管理后台与工具

• 修复管理后台工具管理文案和 Skill 能力页面回归问题

安全

依赖

• 更新后端 aiohttp、starlette 和 idna 依赖以进行安全维护

[0.2.5] - 2026-05-20

变更

界面一致性

• 统一平台菜单与对话框中的删除操作样式，包括 SSO 提供商、知识库与能力操作。
• 悬停删除菜单项时通知徽标文字保持可读。
• 统一工作流日志、运行详情与活动日志中的运行状态标签与徽标样式。

部署

• Docker 镜像中以后端字节码形式打包应用。
• Docker standalone 前端部署支持将 /api/* 请求代理到内部后端服务。
• 公共 API 地址为相对路径时，为前端 SSR 请求新增服务端 API 地址解析。

修复

聊天与日志

• 修复 Docker 构建排除 logs 路由目录、导致生产环境日志页 404 的问题。
• 修复聊天流式失败时的 UnboundLocalError。
• 修复 Docker 部署中认证与公开聊天 SSR 元数据请求失败的问题。
• 修复从工作流日志页选择运行后运行详情丢失的问题。
• 修复工作流日志筛选使用后端运行状态值，并修正从日志页跳转工作流监控的导航。
• 本地化工作流运行详情的开始时间、结束时间与调试模式标签。

Skill 与自动化

• 在 Skill 导入环境中安装 Git，使 Git 托管的 Skill 导入可以完成。

安全

聊天流式

• 移除聊天流式错误响应中的堆栈暴露。

[0.2.3] - 2026-05-19

修复

认证

• 未登录用户访问平台和仪表盘页面时，在渲染依赖凭证的内容前重定向到登录页
• 保留后端返回的登录凭证错误提示，避免误显示为会话已过期
• 居中卡片认证布局保留表单边框，分栏认证布局继续使用无边框表单

仪表盘

• 为仪表盘趋势图提供可测量容器，避免 Recharts 宽高无效警告

[0.2.2] - 2026-05-17

新增

认证

• 新增可配置的分栏认证布局，部署时可在居中布局和分屏布局之间切换

自动化

• 新增 GitHub issue 和 pull request 自动分配工作流支持

变更

前端与站点设置

• 更新站点设置界面和 API 接入，支持配置认证布局选项
• 优化后台和平台表单中的数字输入处理
• 更新前端依赖，包括 React、React DOM、shadcn、lucide-react、TypeScript 和 Next.js lint 配置

CI/CD

• 更新 GitHub Actions 发布和自动化依赖

修复

文档

• 修正部署文档中的 PostgreSQL 环境变量引用，将 POSTGRES_HOST 改为 POSTGRES_SERVER
• 完善仓库自动化相关的文档同步校验说明

[0.2.1] - 2026-05-11

修复

聊天与 Agent 运行时

• 跨 Agent 会话保留上传文件上下文：缓存解析后的文件内容并在后续轮次复用。
• 恢复后端聊天工具处理中的知识检索工具执行。
• 避免用完整消息容器包裹出错的 Agent 消息，使错误展示与手动中断一致。
• 对不支持的 HTTP 工具 URL 模板返回结构化本地化校验错误。

安全与依赖

• 将 langchain-core 升级到已修复安全公告的后端依赖版本。
• 调整 Dependabot 前端更新分组，使不兼容的前端依赖升级单独处理。

文档

• 修正英文 README、中文指南 README 与快速入门中的后端启动命令。
• 为 Celery worker 与 beat 启动命令补充显式的 celery_app 用法说明。

[0.1.2] - 2026-03-04

新增

用户记忆系统

• 基于 D3.js 力导向布局的交互式记忆图谱可视化。
• 支持完整增删改查的记忆管理面板。
• 基于 LLM 函数调用的自主记忆创建与更新。
• 基于 Qdrant 向量检索的语义搜索。
• 基于用户的多租户数据隔离。
• 10 种颜色区分的实体类型（person、preference、skill、project、goal、fact、concept、organization、location、custom）。
• 9 种颜色区分的关系类型（prefers、works_on、knows、uses、works_at、located_in、has_goal、related_to、part_of）。
• 可配置的自动提取、重要度阈值与单次检索记忆上限。
• 图谱的搜索、筛选与缩放控制。
• 带关系导航的实体详情面板。

Agent 功能

• Agent 交互式提问工具，支持结构化多问题输入。
• 对话中的多选选项支持。
• 聊天流程中的动态问题生成。
• Agent 编排表单中的记忆配置。

工作流增强

• 面向工作流集成的知识检索节点。
• 面向数据处理的参数提取器节点。
• 面向模块化设计的子工作流支持。
• 变量引用校验系统。
• 带内部变量访问的循环迭代。
• 带断点与时间旅行调试的调试模式。
• 带流式更新的实时执行监控。

文档

• 18000+ 行的中英双语完整文档。
• 架构指南与 API 参考。
• Docker 与 Kubernetes 部署指南。
• MCP（Model Context Protocol）文档。
• 沙箱执行文档。
• 文档自动生成脚本。

认证与安全

• SSO 提供商名称路由。
• SSO 属性映射中的 JSONPath 支持。
• 密码重置与验证的邮件模板。
• 注册时的默认角色分配。
• 基于团队成员关系的全局角色同步。

通知

• 新消息的浏览器推送通知。
• 按用户语言投递的通知。
• 面向触发用户的工作流运行通知。
• 知识库文档处理通知。

国际化

• 模块化结构的前端完整 i18n 支持。
• 系统消息的后端完整 i18n 支持。
• 用户语言持久化与自动同步。
• 面向 Agent 的语言感知系统提示词。
• 用户语言的内置工具展示名。
• 默认语言站点设置。

基础设施

• 面向容器编排的健康检查端点。
• 自动构建 Docker 镜像的 CI/CD 流水线。
• 优化镜像体积的多阶段 Docker 构建。
• 无 YAML 锚点的 Kubernetes manifest。

变更

• 按逻辑分组重排平台头部下拉菜单。
• 改进会话列表更新与状态管理。
• 增强错误处理与用户反馈。
• 用批量更新优化分块重建索引。
• 重构 LLM 聊天适配器以提高模块化程度。
• 提升向量存储服务性能。

修复

前端

• TCP 分片时 SSE 解析器丢事件（#61）。
• 工具调用完成后状态卡在“运行中”（#60）。
• 提示词编辑器换行保留（#59）。
• 多行文本的聊天输入框自适应高度（#59）。
• 开发页自动刷新与认证重定向循环（#58）。
• 密码校验与邮箱验证（#57）。
• 语言同步与 favicon 主题切换。
• 会话列表更新与推理块状态管理。
• 使用绝对 URL 的浏览器通知图标。

后端

• 直接使用 bcrypt 兼容 Bcrypt 5.0。
• 用预加载数据修复用户序列化的 N+1 查询（#56）。
• 使用公开 site_url 构造 SSO 回调地址。
• SSO 登录 URL 中重复的 /api/v1 前缀。
• 从 user.locale 而非请求头检测语言。
• 使用触发用户语言发送工作流运行通知。
• 使用上传者语言发送知识库文档通知。
• 对 SSE 流式响应跳过日志中间件。

部署

• Docker 构建中的 Bun lockfile 兼容（#52）。
• 使用 JSON 数组格式的 CORS 配置（#51）。
• 面向 kubectl 的 Kubernetes manifest 兼容。

安全

• 增强密码校验。
• 自定义工具凭据的安全存储。
• 带过期跟踪的 API Key 范围访问。

[0.1.0] - 2025-02-07

Clouisle 首个公开发布版本 - 企业级知识库与 AI Agent 平台。

核心功能

Agent 系统

• Agent 类型：支持聊天 Agent 和工作流 Agent
• Agent 编排：现代化三栏布局，实时预览
  • 提示词编辑器，支持 AI 生成
  • 变量配置
  • 知识库关联
  • 工具配置
  • 视觉能力支持
• Agent 发布：发布/取消发布工作流，状态管理
• Agent API 访问：OpenAI 兼容 API，提供文档和代码示例
• Agent 监控：使用统计、对话趋势、Token 用量、响应时间指标

工作流引擎

• 可视化工作流编辑器：基于 React Flow 的拖拽式工作流构建器
• 节点类型：
  • 开始/结束节点
  • LLM 节点（支持模型选择和参数调优）
  • 条件节点（分支逻辑）
  • 代码节点（JavaScript/Python 执行）
  • 工具节点（HTTP API、MCP、内置工具）
  • 迭代/循环节点
  • 变量赋值/聚合节点
  • 子工作流节点
  • 问题分类器节点
  • 参数提取器节点
• 变量系统：上游变量引用与校验
• 执行：实时流式执行，节点级状态跟踪

知识库

• 文档管理：
  • 多格式支持：PDF、DOCX、TXT、MD、HTML、CSV、XLSX、JSON、PPTX
  • URL 导入
  • 拖拽批量上传
• 文档处理：
  • 智能文本分块（可配置 chunk_size、chunk_overlap、separator）
  • 提交前分块预览
  • 文本清洗选项
• 搜索模式：
  • 向量搜索（语义相似度）
  • 全文搜索（jieba 中文分词）
  • 混合搜索（RRF 算法）
• 动态 Embedding：支持多种 embedding 维度（768、1024、1536、3072）

聊天系统

• 通用聊天组件：可复用的聊天组件库
• 消息类型：文本、推理（思维链）、工具调用、文件、来源
• 流式输出：实时流式响应，Streamdown 渲染
• 多轮对话：对话历史管理

工具系统

• 内置工具：计算器、时间/时区
• HTTP API 工具：可配置 URL、方法、Headers、Body 模板
• MCP 服务器工具：stdio/sse 传输、命令执行
• 代码工具：在线 JavaScript/Python 编辑器

平台功能

用户管理

• 认证：用户名/密码、SSO（OIDC、SAML、CAS）
• 注册：可配置注册、审批流程、邮箱验证
• 密码策略：可配置强度要求
• 会话管理：超时、单一会话模式
• 登录安全：最大尝试次数、锁定、验证码

团队管理

• 多租户：基于团队的资源隔离
• 基于角色的访问控制：可自定义角色和权限
• 团队成员：邀请、移除、角色分配

模型管理

• 多供应商支持：OpenAI、Anthropic、Azure、本地模型
• 模型授权：团队级模型访问控制
• 用量跟踪：按团队统计 Token 用量

API 密钥管理

• API 密钥 CRUD：创建、轮换、过期 API 密钥
• Agent 绑定：限制 API 密钥访问特定 Agent
• 速率限制：可配置速率限制

站点设置

• 常规：站点名称、描述、URL、图标
• 默认语言：可配置系统消息的默认语言
• 安全：注册、密码策略、会话、登录安全
• 通知：邮件（SMTP）、钉钉、企业微信、飞书、Slack、Webhook
• 自动通知：可配置系统事件通知
• SSO：OIDC、SAML、CAS 提供商配置
• 存储：审计日志保留和归档

审计日志

• 全面记录：记录所有用户操作
• 日志查看器：可筛选、可搜索的审计日志界面
• 导出：支持 CSV 导出
• 归档：可配置保留期限，自动归档

国际化

• 语言：英语、简体中文
• 用户语言：每用户语言偏好
• 站点默认：可配置系统消息的默认语言
• 动态 i18n：所有用户界面消息国际化

UI/UX

• 主题：明/暗模式，支持系统偏好检测
• 动态 Favicon：主题感知的 Favicon 切换
• 响应式设计：桌面端优化的仪表板
• 组件库：基于 shadcn/ui 的组件

技术栈

后端

• Python 3.13、FastAPI
• Tortoise ORM + AsyncPG
• Celery 后台任务
• Redis 缓存和发布/订阅
• Qdrant 向量存储

前端

• Next.js 15、React 19
• TypeScript
• Tailwind CSS
• shadcn/ui 组件
• Bun 包管理器

贡献指南

在提交代码时，请在提交信息中关联相关 Issue，格式如：

feat(knowledge-base): 实现知识库搜索功能

- 添加向量搜索、全文搜索、混合搜索三种模式
- 集成 jieba 中文分词

Closes #12