69gg · 69gg · Jun 6, 2026 · May 30, 2026 · May 30, 2026 · May 30, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -1,10 +1,11 @@
 name: CI Code Quality
 
 on:
+  workflow_dispatch:
   push:
-    branches: [ "main" ]
+    branches: [ "main", "develop" ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ "main", "develop" ]
 
 jobs:
   quality-check:

diff --git a/config.toml.example b/config.toml.example
@@ -1286,6 +1286,9 @@ bot_name = "Undefined"
 # zh: ChromaDB 向量数据库存储路径。
 # en: ChromaDB vector store path.
 path = "data/cognitive/chromadb"
+# zh: ChromaDB 前台连续处理上限；达到后若有后台/维护任务，会让出一次执行机会。
+# en: Max consecutive foreground Chroma operations before one maintenance/background slot is allowed.
+scheduler_foreground_burst = 8
 
 [cognitive.query]
 # zh: 自动注入上下文时的召回条数。

diff --git a/docs/callable.md b/docs/callable.md
@@ -64,7 +64,7 @@ skills/agents/web_agent/callable.json
 
 - **自调用保护**：Agent 不会将自己注册为可调用工具
 - **上下文隔离**：每次调用有独立上下文，历史记录按 Agent 分组保存
-- **迭代限制**：受 `max_iterations`（默认 20）约束，防止无限递归
+- **迭代限制**：受 `max_iterations`（默认 1000）约束，防止无限递归
 
 ## 主工具共享（tools/）
 

diff --git a/docs/cognitive-memory.md b/docs/cognitive-memory.md
@@ -5,7 +5,7 @@
 认知记忆系统是 Undefined 的三层分层记忆架构，模拟人类记忆机制：
 
 - **短期记忆**（`end.memo`）：每轮对话结束自动记录便签备忘，最近 N 条始终注入，保持短期连续性，零配置开箱即用。若本轮由 MessageBatcher 合并多条消息，memo 应概括整个当前输入批次的处理结果。
-- **认知记忆**（`end.observations` + `cognitive.*`）：核心层，AI 在每轮对话中主动观察当前输入批次，提取用户/群聊事实及有价值的自身行为（`observations`），经后台史官异步改写为绝对化事件并存入 ChromaDB 向量库，支持语义检索；当对话中出现新信息（偏好、身份、习惯等）时，史官自动合并更新 Markdown 侧写文件，下次对话时注入 prompt。
+- **认知记忆**（`end.observations` + `cognitive.*`）：核心层，AI 在每轮对话中只观察当前输入批次，提取有价值的新观察（用户/群聊/第三方事实及有价值的自身行为）。`observations` 不要求与 bot 相关，也不要求长期稳定；历史消息、认知记忆、侧写和最近消息参考只能用于消歧，不能作为新事实来源。后台史官会异步改写为绝对化事件并存入 ChromaDB 向量库，支持语义检索；当对话中出现可沉淀为稳定画像的新信息（偏好、身份、习惯等）时，史官自动合并更新 Markdown 侧写文件，下次对话时注入 prompt。
 - **置顶备忘录**（`memory.*`）：AI 自身的置顶提醒（自我约束、待办事项，如"用户要求以后用英文回复"），每轮固定注入，支持增删改查。注意：用户事实（偏好、身份、习惯等）不应写入此层，一律通过 `end.observations` 写入认知记忆。
 
 与旧 `end_summaries` 的区别：
@@ -64,7 +64,7 @@ AI 调用 `end` 工具结束对话时，只做一次文件落盘（p95 < 5ms）
 `end` 字段语义：
 
 - `memo`：本轮便签纸，留给短期记忆看的简短备注（纯流水账动作写这里），可空。当前输入批次包含多条连续消息时，memo 应概括整批处理结果。
-- `observations`：本轮值得长期留存的观察列表（0..N 条），包括用户/群聊事实和有价值的自身行为（帮谁解决了什么），严格一条一个要点；每条会独立改写与入库。当前输入批次包含多条连续消息时，必须覆盖整批消息中值得留存的信息，不能只记录最后一条。
+- `observations`：本轮从当前输入批次提取的有价值新观察列表（0..N 条），包括用户/群聊/第三方事实和有价值的自身行为（帮谁解决了什么），不要求与 bot 相关，也不要求长期稳定，严格一条一个要点；每条会独立改写与入库。当前输入批次包含多条连续消息时，必须覆盖整批消息中有价值的信息，不能只记录最后一条。历史消息、认知记忆、侧写和最近消息参考只能用于消歧，不能作为 observations 的新事实来源。
 - 两字段都为空时，仅结束会话，不写认知队列。
 
 ### 后台史官流水线
@@ -175,6 +175,19 @@ MMR_score = λ × relevance(doc, query) − (1 − λ) × max_similarity(doc, se
 
 史官合并侧写时，会在 merge LLM 调用前用当前 observations 作为 query 从 ChromaDB 检索该实体的 top-8 历史事件，注入 merge prompt。这让史官拥有更丰富的上下文来判断哪些特征应保留，避免因本轮未提及而误删长期稳定特征。
 
+### ChromaDB 前后台调度
+
+`cognitive_events` / `cognitive_profiles` 的 ChromaDB `query/upsert` 由进程内单 worker 串行执行，避免多群聊、WebChat 与史官后台同时访问 Chroma collection 时互相踩踏。调度只覆盖真正的 Chroma 读写；embedding 与 rerank 仍走各自模型队列，避免后台向量化长尾占住 Chroma worker。
+
+优先级：
+
+- `foreground_critical`：显式用户工具/API 检索（如 `cognitive.search_events` / `cognitive.search_profiles`）。
+- `foreground`：自动上下文注入、用户触发的侧写展示名同步。
+- `maintenance`：史官合并侧写前的历史查询。
+- `background`：史官事件/侧写向量写入。
+
+前台请求优先；连续处理 `scheduler_foreground_burst` 个前台操作后，如果维护/后台队列中有等待任务，会让出一次执行机会，防止史官长期饥饿。日志中的 `chroma_wait` 表示在调度器里等待的时间，`chroma_exec` 表示真正执行 Chroma 调用的时间。
+
 ### 自动注入场景的 Query 构造
 
 每轮对话自动注入认知记忆（`PromptBuilder -> cognitive.build_context`）时，检索 `query` 的构造规则如下：
@@ -266,6 +279,7 @@ data/cognitive/
 | 字段 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | `path` | str | `data/cognitive/chromadb` | ChromaDB 存储路径 |
+| `scheduler_foreground_burst` | int | `8` | Chroma 前台连续处理上限；达到后若有维护/后台任务，会让出一次执行机会（需重启） |
 
 ### [cognitive.query]
 
@@ -340,7 +354,7 @@ data/cognitive/
 ### 热更新说明
 
 - **支持热更新**：`cognitive.query.*`、`cognitive.historian.poll_interval_seconds`、`cognitive.historian.rewrite_max_retry`、`cognitive.historian.recent_messages_inject_k`、`cognitive.historian.recent_message_line_max_len`、`cognitive.historian.source_message_max_len`
-- **需重启**：`cognitive.enabled`、`models.embedding.*`、`models.rerank.*`
+- **需重启**：`cognitive.enabled`、`cognitive.vector_store.*`、`models.embedding.*`、`models.rerank.*`
 
 说明：
 - `knowledge.enable_rerank` 仅控制知识库检索重排。

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -385,6 +385,7 @@ Prompt caching 补充：
 
 用途：
 - 仅供 `web_agent` 内的 `grok_search` 子工具使用。
+- 工具调用该模型时会注入专用 system prompt：以服务端当前时间作为“今天 / 最新 / 最近”的基准，要求先搜索、使用多组搜索查询或多个搜索工具、禁止编造，并在结果中给出来源。
 
 默认：
 - `max_tokens=8192`
@@ -880,6 +881,7 @@ Prompt caching 补充：
 | 字段 | 默认值 | 说明 |
 |---|---:|---|
 | `path` | `data/cognitive/chromadb` | Chroma 存储目录 |
+| `scheduler_foreground_burst` | `8` | Chroma 前台连续处理上限；达到后若有维护/后台任务，会让出一次执行机会。需重启 |
 
 ### 4.24.3 `[cognitive.query]`
 

diff --git a/docs/management-api.md b/docs/management-api.md
@@ -171,8 +171,163 @@ Management API 会把运行态相关能力统一代理到主进程 Runtime API
 - `GET /api/v1/management/runtime/cognitive/events`
 - `GET /api/v1/management/runtime/cognitive/profiles`
 - `GET /api/v1/management/runtime/cognitive/profile/{entity_type}/{entity_id}`
+- `GET /api/v1/management/runtime/commands`
+- `GET /api/v1/management/runtime/commands/{command_name}`
+- `GET /api/v1/management/runtime/chat/conversations`
+- `POST /api/v1/management/runtime/chat/conversations`
+- `PATCH /api/v1/management/runtime/chat/conversations/{conversation_id}`
+- `DELETE /api/v1/management/runtime/chat/conversations/{conversation_id}`
 - `POST /api/v1/management/runtime/chat`
 - `GET /api/v1/management/runtime/chat/history`
+- `DELETE /api/v1/management/runtime/chat/history`
+- `POST /api/v1/management/runtime/chat/jobs`
+- `POST /api/v1/management/runtime/chat/files`
+- `GET /api/v1/management/runtime/chat/jobs/active`
+- `GET /api/v1/management/runtime/chat/jobs/{job_id}`
+- `GET /api/v1/management/runtime/chat/jobs/{job_id}/events`
+- `POST /api/v1/management/runtime/chat/jobs/{job_id}/cancel`
+
+所有 Runtime 代理端点都会先校验 Management session / access token，再由 WebUI 后端注入 `X-Undefined-API-Key`；浏览器不会接触 Runtime `[api].auth_key`。
+
+### `runtime/commands`
+
+代理 Runtime 斜杠命令 REST 资源，供 WebChat `/` 补全面板和管理端命令浏览使用。
+
+- 参数：
+  - `scope`：默认 `webui`；也可传 `private` / `group`。
+  - `q`、`include_hidden`、`include_unavailable`、`sender_id`、`user_id`、`group_id`：原样透传给 Runtime。
+- 校验：
+  - Management 登录态或 access token 必须有效。
+  - 后端注入 `X-Undefined-API-Key`。
+- 响应：
+  - `200`：命令、别名、子命令、用法、权限和当前 scope 可用性。
+  - Runtime 鉴权或配置错误会透传对应错误状态。
+
+```http
+GET /api/v1/management/runtime/commands?scope=webui&q=help
+```
+
+### `runtime/chat/conversations`
+
+管理 WebChat 多对话，支持查询、新建、重命名和删除。
+
+- 参数 / Body：
+  - `GET` 无必填参数。
+  - `POST` 可传 `{"title":"..."}`。
+  - `PATCH` 传 `{"title":"..."}`。
+  - `DELETE` 使用路径参数 `conversation_id`。
+- 校验：
+  - 删除会话时 Runtime 会检查是否存在运行中或收尾落盘中的 WebChat job。
+- 响应：
+  - `200` / `201`：会话列表或会话对象。
+  - `404`：会话不存在。
+  - `409`：仍有 WebChat job 阻塞会话删除。
+
+```json
+{
+  "conversation": {
+    "id": "legacy-system-42",
+    "title": "新对话",
+    "virtual_user_id": 42
+  }
+}
+```
+
+### `runtime/chat`、`runtime/chat/history`、`runtime/chat/jobs`、`runtime/chat/jobs/active`
+
+代理 WebChat 发送、历史分页、后台 job 创建和 active job 查询；`conversation_id` 会在 body 或 query 中原样透传。
+
+- 参数 / Body：
+  - `conversation_id`：可选；不传时使用 Runtime 默认兼容会话。
+  - `POST runtime/chat`：`message` 必填，`stream` 可选。
+  - `GET runtime/chat/history`：`limit`、`before`、`conversation_id`。
+  - `DELETE runtime/chat/history`：`conversation_id`。
+  - `POST runtime/chat/jobs`：`message` 必填，`conversation_id` 可选。
+  - `GET runtime/chat/jobs/active`：`conversation_id` 可选。
+- 校验：
+  - Runtime 会检查 `conversation_id` 是否存在。
+  - 删除历史时，如果仍有运行中或收尾落盘中的 job，会透传 `409`。
+- 响应：
+  - `200` / `202`：聊天结果、历史页、job 快照或 active job。
+  - `404`：会话不存在。
+  - `409`：job 正在运行或历史尚未完成落盘。
+- 元数据语义：
+  - `webchat.duration_ms`、`webchat.events`、`webchat.timeline`、`current_tool_calls`、`stage` / `agent_stage` 是 **display-only**，用于刷新后恢复工具 / Agent 展示块、阶段和耗时。
+  - 这些 WebChat 展示元数据不是 **AI-context**，不会作为后续 AI 对话上下文注入。
+  - 工具 / Agent 输入输出预览由 Runtime 统一脱敏和截断。
+
+```json
+{
+  "message": "你好",
+  "conversation_id": "legacy-system-42"
+}
+```
+
+### `runtime/chat/files`
+
+缓存 WebChat 待发送文件，前端随后把返回的 `id` 合并为 `CQ:file` 随当前消息提交。
+
+- 参数 / Body：
+  - `multipart/form-data` 字段 `file` 必填。
+- 校验：
+  - Management 登录态或 access token 必须有效。
+  - Runtime / WebUI 文件大小限制会返回 `413`。
+- 响应：
+  - `200`：`{ "id": "...", "name": "...", "size": 123 }`。
+  - `400`：缺少 `file` 字段或 multipart body 无效。
+  - `413`：文件超过限制。
+
+```http
+POST /api/v1/management/runtime/chat/files
+Content-Type: multipart/form-data
+```
+
+```json
+{ "id": "abc123", "name": "report.pdf", "size": 2048 }
+```
+
+前端合并为：
+
+```text
+CQ:file,id=abc123,name=report.pdf,size=2048
+```
+
+### `runtime/chat/jobs/{job_id}/events`
+
+按 `conversation_id + job_id + seq` 续接 WebChat job 事件，支持 JSON 增量查询和兼容 SSE。
+
+- 参数：
+  - `conversation_id`：可选；传入时必须与 job 所属会话一致。
+  - `after`：返回大于该 `seq` 的事件。
+  - `format=json`：显式 JSON 查询。
+  - `Accept: text/event-stream`：透传 Runtime WebChat SSE。
+- 校验：
+  - `conversation_id` 不一致时返回 `404`，避免跨会话误续接。
+- 响应：
+  - 默认 JSON：持久事件、当前顶层 `stage` 快照、当前 `agent_stage` 快照、`current_tool_calls` 和耗时字段。
+  - SSE：事件帧和 keep-alive 由 Runtime 透传。
+
+```json
+{
+  "job": {
+    "job_id": "9c1...",
+    "status": "running",
+    "current_stage": "waiting_tools",
+    "current_tool_calls": []
+  },
+  "after": 4,
+  "last_seq": 5,
+  "events": [
+    { "seq": 5, "event": "stage", "payload": { "stage": "waiting_tools" } }
+  ]
+}
+```
+
+```text
+id: 5
+event: stage
+data: {"stage":"waiting_tools"}
+```
 
 除此之外，Management API 还额外代理了表情包库管理接口：
 

diff --git a/docs/message-batching.md b/docs/message-batching.md
@@ -30,7 +30,9 @@
 
 `res/prompts/undefined.xml`、`res/prompts/undefined_nagaagent.xml` 与 `res/IMPORTANT/each.md` 均按"当前输入批次"适配：有【连续消息说明】时整批当前 `<message>` 都属于本轮输入；没有连续说明时，当前输入批次退化为最后一条消息。防幽灵任务规则仍然生效，但它只隔离当前输入批次之外的历史消息；「催促/在吗」不等于新任务，历史同类或语义等价操作不得自动重跑（与 each.md 硬性熔断一致）。
 
-`end.memo` / `end.observations` 也按同一语义适配：当前输入批次包含多条连续消息时，短期 memo 要概括整批处理结果，认知 observations 要覆盖整批消息中值得留存的信息；后台史官收到的 `source_message` 会按时间顺序列出本批所有 `<message>`，不会只取最后一条。
+Prompt 构建顺序按缓存命中友好设计：固定系统提示词、运行环境配置、Skills 元数据和强制规则尽量放在前面；会频繁变化的 memory / cognitive / end 摘要 / history / 当前时间 / 当前输入批次放在后面。`system_prompt_as_user=true` 时，系统块会合并进首条 user，但合并后的文本仍保留这个顺序，且当前输入批次仍在最后。
+
+`end.memo` / `end.observations` 也按同一语义适配：当前输入批次包含多条连续消息时，短期 memo 要概括整批处理结果，认知 observations 要覆盖整批消息中有价值的新观察；这些观察不要求与 bot 相关，也不要求长期稳定，但只能来自当前输入批次。历史消息、认知记忆、侧写和最近消息参考只用于消歧，不能作为 observations 的新事实来源。后台史官收到的 `source_message` 会按时间顺序列出本批所有 `<message>`，不会只取最后一条。
 
 > **重要**：当前主提示词按 MessageBatcher 默认开启设计。`[message_batcher].enabled = true` 是推荐和默认配置；如果关闭 batcher，连续补充/修正会退化为逐条独立 AI 调用，提示词中的"当前输入批次"语义可能不再覆盖这些连续消息，需要单独调整提示词或接受旧版逐条触发行为。