qwen_agent/.features/skill/changelog/2026-Q2.md

# 2026-Q2 Skill Changelog

按时间倒序记录本季度的重要变更。

---

## 2026-06-07: 新增 `table-query` skill（SQLite 表查询）

**类型**：新功能

**背景**：bot 上传的 Excel/CSV 表格此前只能走 `rag_retrieve` 语义检索回答问题，对"价格/数量/库存/排名/聚合"这类**结构化**问题精度差、答非所问。需要一条"快速、不走 LLM 的 SQL 查询路径"。

**改动**：
- 新增 `skills/developing/table-query/`：
  - `SKILL.md`：定义 search-tables → get-schemas → run-sql 三步工作流；明确"backend 不做 LLM 推理，由 agent 自己写 SQLite SQL"；`category: Data & Retrieval`。
  - `scripts/table_query.py`：CLI 入口 + run-sql plan 执行器（plan 通过 stdin heredoc 传递，无需 shell 转义）。
  - `skill.yaml`：元数据。
  - `verify_table_query.sh`：自检脚本。
- 工作流要求：search-tables **每问最多 1 次**，run-sql 出错重试 ≤ 2 次，且不回退到 search-tables；search-tables 无果时降级到 `rag_retrieve`。

**根因**：N/A（新功能）

**影响**：
- agent 可直接对上传表数据做 SUM/AVG/COUNT 等结构化查询，并通过 `__src` 列 + `file_ref_table` 输出行级 citation。
- 同时引入 plan-on-stdin 的调用约定（`<<'PLAN' ... PLAN`），后续类似 SQL/JSON 入参的 skill 可参考此模式以避免 argv 转义问题。

**相关文件**：
- `skills/developing/table-query/SKILL.md`
- `skills/developing/table-query/scripts/table_query.py`
- `skills/developing/table-query/skill.yaml`
- `skills/developing/table-query/verify_table_query.sh`

**Commit/PR**：`bb74aee`

---

## 2026-06-05: 新增 `mineru` skill（PDF/Office/图片 → Markdown 解析）

**类型**：新功能

**背景**：缺少统一的"文档转 Markdown"管道，PDF/Word/PPT/Excel/图片需要走不同工具，且 OCR / 公式 / 表格识别能力不一致。

**改动**：
- 新增 `skills/developing/mineru/`（约 4700 行，30 文件）：
  - `SKILL.md` + `references/`（api_reference / comparison / integrations）。
  - `scripts/mineru.py`：核心 CLI，自动路由 Agent API（无 token）与 Standard API（需 `MINERU_TOKEN`，支持大文件/批量/DOCX/HTML/LaTeX 导出）。
  - `scripts/mineru_mcp.py`：MCP server 包装。
  - `scripts/sinks/`：airtable / coda / confluence / dingtalk / feishu / linear / local / notion / onenote / roam / siyuan / slack / ticktick / wecom / wps / yuque 等多目标写出。
  - `scripts/chunking.py` / `splitter.py` / `local_engine.py`：分块、切分、本地引擎。
- `category: Document Processing`，标准依赖（仅标准库）。

**根因**：N/A（新功能）

**影响**：
- 提供"零 token 起步、有 token 升级"的渐进式解析路径，降低部署门槛。
- 多 sink 设计可作为后续"采集 → 结构化 → 多目的地分发"类 skill 的参考骨架。

**相关文件**：
- `skills/developing/mineru/SKILL.md`
- `skills/developing/mineru/scripts/mineru.py`
- `skills/developing/mineru/scripts/mineru_mcp.py`
- `skills/developing/mineru/scripts/sinks/*.py`（15 个目标）

**Commit/PR**：`b618cb1`

---

## 2026-06-05: `rag-retrieve` 系列空 query 改返回 success 文案（替代 JSON-RPC error）

**类型**：行为变更（兼容性）

**背景**：`rag_retrieve` / `table_rag_retrieve` 工具在缺少 `query` 参数时返回 JSON-RPC `-32602` error。MCP/agent 链路上 error 容易被上层吞掉，agent 看不到"为什么失败"，无法自我修复。

**改动**：把 5 个 rag-retrieve server 变体的"missing query"分支由 `create_error_response(-32602, ...)` 改为 `create_success_response(...)` 携带 `content[].text = "Error: missing required parameter 'query'. Please call this tool again with a non-empty 'query' argument describing what you want to retrieve."`：
- `skills/autoload/onprem/rag-retrieve/rag_retrieve_server.py`
- `skills/autoload/support/rag-retrieve/rag_retrieve_server.py`
- `skills/developing/rag-retrieve-no-citation/rag_retrieve_server.py`
- `skills/onprem/rag-retrieve-only/rag_retrieve_server.py`
- `skills/support/rag-retrieve-only/rag_retrieve_server.py`

**根因**：MCP 协议层的 error 在多数 agent 框架下不会作为"tool 返回结果"传给 LLM，从而无法触发重试；改成 success-with-error-text 让 agent 把错误文本当 tool output 读到，并在下一轮自然带上 query 重试。

**影响**：
- 客户端**不能再依赖 JSON-RPC error code = -32602 判定缺参**，必须从 `content[].text` 前缀 `"Error:"` 解析；任何在 success 路径上做强校验/落盘的中间层需要兼容这种"假成功"形态。
- 新 MCP server 出错路径如果是"需要 agent 自纠错"的语义错误，应走同样的 success-with-error-text 模式；底层崩溃 / 不可恢复错误仍走 error response。

**相关文件**：见上。

**Commit/PR**：`ecf332a`

---

## 2026-06-02: 修复 deepagents 落盘 backend grep 扫描全盘问题（virtual_mode=True）

**类型**：Bug 修复

**背景**：`create_custom_cli_agent` 给 `large_results` / `conversation_history` 两个路由创建了独立 `FilesystemBackend(tempfile.mkdtemp(...), virtual_mode=False)`，配合 `CompositeBackend` 做前缀路由。线上出现 grep 调用耗时 45–152s 的异常。

**改动**：将 `large_results_backend` 与 `conversation_history_backend` 的 `virtual_mode` 由 `False` 改为 `True`，并在调用处补 NOTE 注释说明 virtual_mode 的语义。

**根因**：`CompositeBackend` 会先剥掉路由前缀，再把剩余路径（极端情况下就是 `"/"`）转发给被路由 backend 的 grep。当 backend 的 `virtual_mode=False` 时，`"/"` 解析为真实根目录而不是 `root_dir`，于是 grep 在沙箱 / 容器内对 `/usr`、`/var`、其他会话的 tmp 目录全盘扫描，单次耗时达数十秒到分钟级。`virtual_mode=True` 会把所有路径锚定到 `root_dir`，并过滤掉根目录之外的结果，把扫描限制在 backend 自己的 tmp 子目录内。

**影响**：
- 这两个 backend 的 grep 调用回落到毫秒级，整个 deep agent 的 tool 调用 P99 大幅下降。
- 任何新增的"落盘但只服务于本次会话"的 `FilesystemBackend` 走 `CompositeBackend` 路由时，**必须**使用 `virtual_mode=True`，否则容易复现同样的全盘扫描问题。
- 真实 workspace backend（用户文件根目录）仍然是 `virtual_mode=False`，因为它需要看到沙箱真实路径上的产物。

**相关文件**：
- `agent/deep_assistant.py`

**Commit/PR**：`6bccd89`

---

## 2026-05-29: 新增 ToolMetricsMiddleware（tool 调用埋点）

**类型**：新功能

**背景**：deep agent 内部的工具调用（含 MCP tool / skill script / 文件系统操作等）此前缺少统一的耗时与成功率埋点；问题排查只能依赖日志，无法对接 `emit_question_metric` 的结构化指标体系。

**改动**：
- 新增 `agent/tool_metrics_middleware.py`，定义 `ToolMetricsMiddleware(AgentMiddleware)`：
  - 同时实现 `wrap_tool_call`（同步）与 `awrap_tool_call`（异步）。
  - 对每次 tool 调用计时（`time.monotonic()`），通过 `emit_question_metric(stage="catalog_agent.tool_call", ...)` 上报：`status`（`success` / `error` / `cancel`）、`duration_ms`、`error_type`、`tool_name`、`tool_call_id`、`trace_id`、`bot_id`、`session_id`、`model`、`stream`、`tool_response`、`enable_thinking`。
  - 异步分支特别捕获 `asyncio.CancelledError` 上报 `status="cancel"` 后再 re-raise。
  - 指标 emit 自身的异常被 try/except 兜住，绝不影响 tool 调用本体。
- `agent/deep_assistant.py::init_agent` 中间件链中，将 `ToolMetricsMiddleware(config)` 插在 `EmptyResponseRetryMiddleware` 之后、`ToolUseCleanupMiddleware` 之前。

**根因**：N/A（新功能）

**影响**：
- 所有走 deep agent / sub agent 的 tool 调用现在都会自动出 `catalog_agent.tool_call` 结构化指标，可在指标后端按 `tool_name` / `bot_id` / `status` 聚合做 P50 / P99 / 错误率分析。
- 中间件顺序硬约束扩展：`EmptyResponseRetryMiddleware → ToolMetricsMiddleware → ToolUseCleanupMiddleware → CustomFilesystemMiddleware → SubAgentMiddleware → AnthropicPromptCachingMiddleware`，调整 `init_agent` 中间件顺序时需保持 `ToolMetricsMiddleware` 在最外层（仅次于重试），否则统计到的耗时不包含其他中间件开销。
- emit 失败只打 logger.exception，不会回传给 tool handler；指标缺失需在指标后端层面单独告警，不要依赖 agent 端口的报错。

**相关文件**：
- `agent/tool_metrics_middleware.py`（新增）
- `agent/deep_assistant.py`

**Commit/PR**：`9f0ae25`

---

## 2026-05-26: skill `category` 字段全面接入

**类型**：新功能

**背景**：skill 数量越来越多（common / developing / onprem / support / linggan / autoload 各路径下数十个），列表 API 需要前端能按类别分组展示，元数据层面缺少 `category` 字段。

**改动**：
- `routes/skill_manager.py`：
  - `SkillItem` model 新增 `category: str = "other"`。
  - `SkillValidationResult` dataclass 新增可选 `category: Optional[str]`。
  - `parse_plugin_json` 解析 `plugin_config.get('category')`；`parse_skill_frontmatter` 解析 frontmatter 的 `metadata.get('category')`。
  - `get_official_skills` 中 fallback 为 `"other"`；`get_user_skills` 中 fallback 为 `"custom"`。
  - `get_skill_metadata_legacy` 在 `category` 非空时写入返回 dict（保持向后兼容）。
- 批量给 common / developing / onprem / support 多个 skill 的 `.claude-plugin/plugin.json` 与 `SKILL.md` frontmatter 添加 `category` 字段。
- `data-dashboard` 与 `mcp-ui` 的 `category` 从 `"Data & Retrieval"` 修正为 `"Interactive UI"`（更贴切 MCP App 的渲染语义）。

**根因**：N/A（新功能）

**影响**：
- `GET /api/v1/skill/list` 返回项现在包含 `category` 字段；前端可按 category 维度做分组/筛选。
- skill 元数据约定扩展——新 skill 应在 plugin.json 或 SKILL.md frontmatter 中写明 `category`，否则会落到 `"other"` / `"custom"` 兜底。
- `plugin.json.category` 与 `SKILL.md.category` 同时存在时以前者为准（`get_skill_metadata` 优先 plugin.json）。

**相关文件**：
- `routes/skill_manager.py`
- `skills/common/data-dashboard/.claude-plugin/plugin.json`
- `skills/common/mcp-ui/.claude-plugin/plugin.json`
- 以及一批 `skills/{common,developing,onprem,support}/*/SKILL.md` 与 `.claude-plugin/plugin.json`

**Commit/PR**：`203dcf4`, `3ada55a`, `9658588`

---

## 2026-05-26: developing 分支批量新增多类 skill

**类型**：新功能

**背景**：[待补充]——经 developing→staging 合并集中落地一批新 skill 与 linggan 系列 skill 回归。

**改动**：
- 新增 `skills/developing/ai-ppt-generator/`：调用百度 AI 生成 PPT，按 topic 自动选模板（商务/科技/教育/创意/中国风等）；`category: Document Processing`。
- 新增 `skills/developing/nfc-medicine-lookup/`：通过 NFC 芯片 ID 或药品名称查询药品信息，面向老年用户的语音助手交互口径；`category: Developer Tools`。
- 新增 `skills/developing/ppt-outline/`：PPT 大纲与独立 HTML 演示文稿生成（dark/light/tech/minimal 四种风格）；`category: Document Processing`。
- 新增 `skills/developing/z-card-image/`：生成配图、封面图、卡片图、社媒帖子分享图等；依赖 `python3` + `google-chrome`。
- `skills/developing/static-hosting/SKILL.md` 由 1 行说明扩展为完整 80 行 skill；同时一批已有 SKILL.md / plugin.json 补 `category`。
- `skills/linggan/*` 系列 skill（baidu-search / bot-self-modifier / caiyun-weather / competitor-news-intel / contract-document-generator / financial-report-generator / market-academic-insight / ragflow-loader / sales-decision-report / seedream / static-hosting / static-site-deploy / voice-notification / weather-china）经合并回归 staging。

**根因**：N/A

**影响**：
- developing skill 池扩张约 5 个新业务 skill；linggan 系列重新出现在 staging。
- 新 skill 多为 SKILL.md 型业务 skill，符合"workflow + 模板"的纯 markdown 模式；其中 `ai-ppt-generator`、`z-card-image` 依赖外部 `BAIDU_API_KEY` 或 `google-chrome` 二进制。

**相关文件**：
- `skills/developing/ai-ppt-generator/SKILL.md`
- `skills/developing/nfc-medicine-lookup/SKILL.md`
- `skills/developing/ppt-outline/SKILL.md`
- `skills/developing/z-card-image/SKILL.md`
- `skills/developing/static-hosting/SKILL.md`
- `skills/linggan/**`（回归）

**Commit/PR**：`3ada55a`

---

## 2026-05-23: 新增 ecommerce-storefront skill（MCP App 型）+ MCP App 培训文档

**类型**：新功能

**背景**：MCP App 模式（host 加载静态 HTML + postMessage 传数据）已经在 `mcp-ui`、`data-dashboard` 上跑通，需要一个面向电商场景的样例 skill，演示产品浏览 / 选购 / 下单确认这类多步交互的 App 渲染；同时沉淀一份 MCP App 开发指南。

**改动**：
- 新增 `skills/developing/ecommerce-storefront/`：
  - `apps/product-list.html`（288 行）与 `apps/order-confirm.html`（233 行）两个静态 App。
  - `ecommerce_server.py`（213 行）作为自带 MCP server，`ecommerce_tools.json` 定义工具 schema。
  - `hooks/ecommerce_guide.md` + `hooks/pre_prompt.py` 注入 skill 使用指引到 system prompt。
  - `mcp_common.py`（252 行）复用 MCP 通用工具基类。
  - `.claude-plugin/plugin.json` 配置 PrePrompt hook 与 stdio MCP server，`category: Developer Tools`。
- 新增 `docs/mcp-app-training.md`（约 1063 行）：MCP App 模式的开发培训材料。

**根因**：N/A

**影响**：
- developing skill 池新增一个 MCP App 型 skill，体例对齐 `mcp-ui` / `data-dashboard`。
- MCP App 开发者有完整培训材料可参考。

**相关文件**：
- `skills/developing/ecommerce-storefront/**`
- `docs/mcp-app-training.md`

**Commit/PR**：`9d001c8`

---

## 2026-05-21: Daytona 沙箱注入 shell_env 到 BASH_ENV

**类型**：新功能

**背景**：Daytona 沙箱内的 skill 脚本需要能读取 `ASSISTANT_ID` / `USER_IDENTIFIER` / `TRACE_ID` 等运行时上下文，但宿主 process env 无法直接透传到沙箱里。

**改动**：
- `agent/deep_assistant.py` `init_agent`：当 `sandbox is not None and sandbox_type == "daytona"` 时，组装 `_shell_env` 字典（`ASSISTANT_ID` / `USER_IDENTIFIER` / `TRACE_ID` / `ENABLE_SELF_KNOWLEDGE` 加上 `config.shell_env`），构造 `cd {REMOTE_WORKSPACE_ROOT}\n` + `export VAR="..."` 行，通过 `sandbox.execute("cat > $REMOTE_BASH_ENV_PATH << 'ENVEOF' ... ENVEOF")` 写入沙箱内。
- `utils/daytona_sync.py` 提供常量 `REMOTE_BASH_ENV_PATH` / `REMOTE_WORKSPACE_ROOT`。
- `AgentConfig` 增加 `shell_env: Optional[Dict[str, str]]`（调用方可追加自定义 env）。

**根因**：N/A

**影响**：
- 沙箱内通过 bash 启动的 skill 脚本可以 `os.environ.get("ASSISTANT_ID")` 等读到运行时上下文。
- 仅 daytona 沙箱模式生效；本地或非 bash 启动的进程不会收到 `BASH_ENV` 注入的变量。
- 扩展注入项（新增固定环境变量）需要直接改 `init_agent` 里的 `_shell_env` 字典。

**相关文件**：
- `agent/deep_assistant.py`
- `utils/daytona_sync.py`

**Commit/PR**：`776acc2`

---

## 2026-05-12: 批量精修 retrieval policy 文案

**类型**：内容调整

**背景**：[待补充]

**改动**：
- `be96f24`: 跨 6 个 skill 变体调整 `retrieval-policy-forbidden-self-knowledge.md` 的措辞（onprem / support / autoload-onprem / autoload-onprem-rag-only / autoload-support-rag-only 路径下的版本及一份 `retrieval-policy.md`）。
- `7b4f03d`: 在更广的 10 个文件范围内同步更新 `retrieval-policy.md` 与 `retrieval-policy-forbidden-self-knowledge.md` 两套 policy，使各 skill 变体的策略口径保持一致。

**根因**：N/A（非 Bug）

**影响**：所有使用 `rag-retrieve` / `rag-retrieve-only` 这两个 hook 的 skill 在策略行为上保持一致；同时影响 onprem 与 support 两个发布分支的部署。

**相关文件**：
- `skills/onprem/rag-retrieve/hooks/retrieval-policy*.md`
- `skills/support/rag-retrieve/hooks/retrieval-policy*.md`
- `skills/autoload/onprem/rag-retrieve/hooks/retrieval-policy*.md`
- `skills/autoload/onprem/rag-retrieve-only/hooks/retrieval-policy*.md`
- `skills/autoload/support/rag-retrieve-only/hooks/retrieval-policy*.md`

**Commit/PR**：`be96f24`, `7b4f03d`

---

## 2026-05-11: 子 agent (SubAgent) 支持 + pmda-drug-info skill

**类型**：新功能

**背景**：需要让单个 skill 在主 agent 之外承载多个专用子 agent，按用途隔离上下文与工具集（如 pmda 药品信息场景下的 single-drug / interaction / adverse-event / patient-specific 四个专用 agent）。

**改动**：
- 新增 `agent/subagent_loader.py`：扫描 skill 目录下的 `agents/*.md`，按 YAML frontmatter 的 `name` / `description` / `tools` 字段解析为 `SubAgent` 字典；按 `name` 去重，**后扫描的覆盖先扫描的**（last-wins）。
- `agent/deep_assistant.py`：`init_agent` 调用 `load_subagents()`，存在则将 `SubAgentMiddleware`（来自 `deepagents.middleware.subagents`）插在 `CustomFilesystemMiddleware` 之后、`AnthropicPromptCachingMiddleware` 之前，顺序匹配 `create_deep_agent`。
- 新增 `skills/developing/pmda-drug-info/`：完整 skill 包，包含 `.claude-plugin/plugin.json`、`hooks/pre_prompt.py` + `hooks/pmda-instructions.md`、四个 `agents/*.md`、自带 `pmda_server.py` MCP server + `pmda_tools.json`、`mcp_common.py` 工具基础类。

**根因**：N/A

**影响**：
- skill 包结构新增约定：`agents/*.md` 目录下的 markdown 文件会被加载为子 agent。
- skill 加载流程在 `init_agent` 内增加一次目录扫描；对没有 `agents/` 的 skill 无影响。
- skill 跨 bot 共享时存在 sub-agent 同名冲突的风险——同名 sub-agent 不会报错，而是被后扫描到的覆盖。

**相关文件**：
- `agent/subagent_loader.py`（新）
- `agent/deep_assistant.py`（接线）
- `skills/developing/pmda-drug-info/`（新 skill）

**Commit/PR**：`5b634bc`

---

## 2026-05-11: pmda-drug-info MCP server 重写为 mock 实现

**类型**：内部改造

**背景**：[待补充]

**改动**：`skills/developing/pmda-drug-info/pmda_server.py` 大幅替换（+322 / -385），保留接口面向 agent 的契约，内部替换为 mock 数据实现。

**根因**：N/A

**影响**：pmda-drug-info skill 当前不再依赖外部真实 PMDA 数据源，便于开发期联调。

**相关文件**：
- `skills/developing/pmda-drug-info/pmda_server.py`

**Commit/PR**：`a92096a`

---

## 2026-05-11: retrieval-policy.md 内容更新

**类型**：内容调整

**背景**：[待补充]

**改动**：在 onprem / support / autoload-onprem-rag-only / autoload-support-rag-only 四个版本的 `retrieval-policy.md` 上做了同步内容更新。

**根因**：N/A

**影响**：与同月 12 日的 policy 批量精修配套，使 rag-retrieve hook 策略保持一致。

**相关文件**：
- `skills/onprem/rag-retrieve/hooks/retrieval-policy.md`
- `skills/support/rag-retrieve/hooks/retrieval-policy.md`
- `skills/autoload/onprem/rag-retrieve-only/hooks/retrieval-policy.md`
- `skills/autoload/support/rag-retrieve-only/hooks/retrieval-policy.md`

**Commit/PR**：`e6d1698`

---

## 2026-05-08: 通过 MCP `_meta` 透传 trace_id 给 RAG 工具

**类型**：新功能

**背景**：需要把 catalog-agent 的 trace_id 透传给 MCP 端的 `rag_retrieve` / `table_rag_retrieve` 服务，便于跨进程追踪。

**改动**：
- 新增 `agent/mcp_trace_meta.py`：通过 `patch_mcp_client_session_trace_meta()` 对 `mcp.ClientSession.call_tool` 做一次幂等 monkey-patch，调用时若工具名在 `{"rag_retrieve", "table_rag_retrieve"}` 集合内且当前请求上下文有 `trace_id`，则注入到 `kwargs["meta"]["trace_id"]`；并提供 `_call_tool_with_meta_compat` 以兼容旧版 MCP SDK（不接受 `meta=` 关键字时退化为手动构造 `CallToolRequestParams._meta`）。
- `agent/deep_assistant.py`：在 `get_tools_from_mcp()` 入口处调用一次补丁安装。
- 同步调整 `skills/onprem/rag-retrieve/rag_retrieve_server.py` 与 `skills/support/rag-retrieve/rag_retrieve_server.py`，接收并使用 `_meta.trace_id`。

**根因**：N/A

**影响**：
- `rag_retrieve` / `table_rag_retrieve` 现在在 MCP `_meta` 上必带 `trace_id`（若上下文存在）。
- 全局 monkey-patch 风格 - 只要 `get_tools_from_mcp()` 被调用过一次后，所有 `ClientSession.call_tool` 都会被包装。

**相关文件**：
- `agent/mcp_trace_meta.py`（新）
- `agent/deep_assistant.py`
- `skills/onprem/rag-retrieve/rag_retrieve_server.py`
- `skills/support/rag-retrieve/rag_retrieve_server.py`

**Commit/PR**：`1f06450`

---

## 2026-05-06: 新增 kfs-answer skill (support 分支)

**类型**：新功能

**背景**：[待补充] - 为 support 分支补齐 kfs-answer 能力（onprem 分支此前已有同名 skill）。

**改动**：新增 `skills/support/kfs-answer/`，包括 `SKILL.md` 与 `scripts/` 下的 `query.py` / `search.py` / `detail.py` / `query_db.py` / `format_answer.py` / `merge_citations.py` / `_session.py` 共 7 个脚本（约 1809 行）。

**根因**：N/A

**影响**：support 部署版本获得 kfs-answer 能力。

**相关文件**：
- `skills/support/kfs-answer/**`

**Commit/PR**：`a9227b8`

---

## 2026-05-06: Daytona 沙箱增量同步漏掉符号链接

**类型**：Bug 修复

**背景**：dataset 通过符号链接挂载，但增量同步用 `find -type f` 只匹配普通文件，导致 dataset 符号链接没被检测到也没被打包同步到 Daytona 沙箱；并且 `tar.add()` 默认不 dereference，打进去的是指向宿主机路径的悬空软链。

**改动**：
- `utils/daytona_sync._list_local_changed_files`：同时匹配 file 和 symlink (`-type f -o -type l`)。
- `utils/daytona_sync._tar_workspace_entries`：`tar.add(dereference=True)`，把软链解引用为实际内容打包。
- `skills/onprem/kfs-answer/SKILL.md` 和 `prompt/system_prompt_deep_agent.md`：统一数据集路径用复数形式 `datasets/`。

**根因**：`find -type f` 与 `tar.add()` 默认行为对符号链接不友好。

**影响**：Daytona 模式下 kfs-answer 等依赖 dataset 软链的 skill 可以正常使用沙箱内的数据；提示词与 SKILL.md 内的路径口径统一。

**相关文件**：
- `utils/daytona_sync.py`
- `skills/onprem/kfs-answer/SKILL.md`
- `prompt/system_prompt_deep_agent.md`

**Commit/PR**：`3c0fa49`

---

## 2026-04-24: PostAgent hooks 非阻塞执行 + 临时停用 ToolOutputLengthMiddleware

**类型**：性能优化 / 临时调整

**背景**：非流式响应路径上 `_execute_post_agent_hooks` 是同步等待，阻塞了响应返回。

**改动**：
- `routes/chat.py`：非流式分支将 `await _execute_post_agent_hooks(...)` 改为 `asyncio.create_task(_execute_post_agent_hooks(...))`，hook 在后台执行，不阻塞响应。
- `agent/deep_assistant.py`：将 `ToolOutputLengthMiddleware` 整段注释掉（未删除，可恢复）。
- `utils/settings.py`：切换 `DAYTONA_API_KEY` / `DAYTONA_SERVER_URL` 注释行（启用自托管 Daytona，注释掉 SaaS 行）。

**根因**：N/A（性能优化为主）

**影响**：
- 非流式接口响应不再等待 PostAgent hooks 完成 → hook 中失败/异常**只会被 task 内部的 logger 捕获**，调用方收不到错误反馈。
- 工具输出长度暂时不再被截断，存在超长输出冲爆上下文的风险（中间件已被注释，并未拆除）。

**相关文件**：
- `routes/chat.py`
- `agent/deep_assistant.py`
- `utils/settings.py`

**Commit/PR**：`45a9494`

---

## 2026-04-23: PrePrompt hook 内容改为模板占位符注入

**类型**：重构

**背景**：原先 PrePrompt hook 的产出文本是在 `system_prompt_default.format(...)` 之后追加在 prompt 末尾，hook 内容在 prompt 中的位置固定且偏后，模板对它的可见性差。

**改动**：`agent/prompt_loader.load_system_prompt_async`：先执行 `execute_hooks('PrePrompt', config)` 拿到 `hook_content`，然后通过新增的 `{hook_content}` 占位符传入 `system_prompt_default.format(...)`；模板侧 `prompt/system_prompt.md` 增加对应占位符。

**根因**：N/A（结构化注入更可控）

**影响**：编写 PrePrompt hook 的 skill 必须依赖模板里 `{hook_content}` 占位符的位置；若使用了未升级的旧模板，hook 内容将不再出现在最终 system prompt 中。

**相关文件**：
- `agent/prompt_loader.py`
- `prompt/system_prompt.md`

**Commit/PR**：`51fbf01`

---

## 2026-04-23: Daytona 沙箱接入

**类型**：新功能

**背景**：技能脚本需要在隔离沙箱中执行（Daytona），避免直接污染宿主机。

**改动**：
- `agent/deep_assistant.py`：
  - 在 `init_agent` 中读取 `DAYTONA_ENABLED` / `DAYTONA_API_KEY` / `DAYTONA_SERVER_URL`，启用时创建 `DaytonaSandbox`；并将 `sandbox` / `sandbox_type` 传到 `create_custom_cli_agent` / `agent.invoke_config`。
  - 重构为并行加载：`load_system_prompt_async` 与 `load_mcp_settings_async` 用 `asyncio.gather` 并行；`get_tools_from_mcp` 与 `asyncio.to_thread(init_daytona_sandbox, ...)` 并行；`init_agent` 现在返回 `(agent, checkpointer, sandbox)`（多了 sandbox）。
  - `enable_skills` 时 `skills_sources` 从 `"/skills"` 改为 `"/workspace/skills"`（指向沙箱内的路径）。
- `agent/prompt_loader.py`：`agent_dir_path` 在 `DAYTONA_ENABLED=True` 时改为 `/workspace`，否则保持本地路径。
- `utils/daytona_sync.py` 新增（204 行）：沙箱与本地 workspace 双向同步。
- `pyproject.toml` / `poetry.lock` / `requirements.txt`：新增 `daytona`、`langchain_daytona` 依赖。
- `utils/settings.py`：新增 `DAYTONA_API_KEY` / `DAYTONA_SERVER_URL` / `DAYTONA_ENABLED` 配置。

**根因**：N/A

**影响**：
- `init_agent` 返回元组从 2 元素变为 3 元素 (`agent, checkpointer, sandbox`)——**调用方必须同步更新解构**。
- skill 在沙箱模式下的根路径与本地模式不同，所有写死路径的 hook / 脚本需要兼容两种环境。

**相关文件**：
- `agent/deep_assistant.py`
- `agent/prompt_loader.py`
- `utils/daytona_sync.py`（新）
- `utils/settings.py`
- `pyproject.toml`, `poetry.lock`, `requirements.txt`

**Commit/PR**：`c9e0789`, `8446dab`

---

## 2026-04-22: 新增 rag-retrieve-no-citation 与 novare-context 两个开发中 skill

**类型**：新功能

**背景**：[待补充]

**改动**：
- `skills/developing/rag-retrieve-no-citation/`：完整 skill 包，含 `.claude-plugin/plugin.json`、`README.md`、`hooks/pre_prompt.py`、`hooks/retrieval-policy.md` 与 `hooks/retrieval-policy-forbidden-self-knowledge.md`、独立 `rag_retrieve_server.py` + `rag_retrieve_tools.json` + `mcp_common.py`。
- `skills/developing/novare-context/`：包含 `.claude-plugin/plugin.json`、`README.md`、`hooks/pre_prompt.py`。

**根因**：N/A

**影响**：开发中 skill 集合扩张，可作为后续正式版本的母版。

**相关文件**：
- `skills/developing/rag-retrieve-no-citation/**`
- `skills/developing/novare-context/**`

**Commit/PR**：`7a30e52`

---
### 2026-05-20
- **变更**: `mcp-ui` 和 `data-dashboard` 从自定义 `uri + data` 工具协议改为 MCP Apps 模式
- **说明**: 静态 HTML App 放在各 skill 的 `apps/` 目录，host 通过 resource URI 加载 iframe，再用 postMessage 传递工具数据
- **修复**: 前端 MCP App resource 请求改为由 `ChatView` 向 `ChatMessage` 传入当前 botId，避免子组件重新创建 bot manager 导致 bot_id 为空
- **作者**: Claude

### 2026-04-20
- **新增**: `skills/autoload/onprem/rag-retrieve/hooks/retrieval-policy-forbidden-self-knowledge.md`
- **说明**: 基于现有 `retrieval-policy.md` 衍生出更严格的检索策略，明确禁止在知识问答场景中使用模型自身知识补全答案，要求回答只能来自检索证据
- **作者**: Claude