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

2026-Q2 Skill Changelog

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

---

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