github-actions[bot] 2205d830e1

chore(.features): sync feature memory (auto) (#43 )

Generated by sparticle-toolkit feature-memory-sync

Co-authored-by: Denya0529 <217564326+Denya0529@users.noreply.github.com>

2026-05-29 17:13:19 +00:00

13 KiB

Raw Blame History

Skill 功能

负责范围：技能包管理服务 - 核心实现最后更新：2026-05-26 最后更新：2026-05-23 最后更新：2026-04-20

最后更新：2026-05-20

当前状态

Skill 系统支持两种来源：官方 skills (./skills/) 和用户 skills (projects/uploads/{bot_id}/skills/)。支持 Hook 系统和 MCP 服务器配置，通过 SKILL.md 或 plugin.json 定义元数据。

2026-04 起 skill 包可在 agents/*.md 下定义子 agent（由 SubAgentMiddleware 加载）；启用 Daytona 沙箱时 skill 加载路径变为沙箱内的 /workspace/skills。

MCP UI 类 skill 已按 MCP Apps 模式改造：工具返回数据，静态 HTML App 由 host 加载后通过 postMessage 接收数据渲染。

目前已新增一批纯 SKILL.md 型业务 skill MVP，用于研究、摘要、报告和情报编排，底层文件处理与外部检索能力继续复用既有 skill。

核心文件

routes/skill_manager.py - Skill 上传/删除/列表 API
agent/plugin_hook_loader.py - Hook 系统实现
agent/deep_assistant.py - CustomSkillsMiddleware
agent/prompt_loader.py - PrePrompt hooks + MCP 配置合并
routes/mcp_resources.py - MCP App 静态 HTML resource REST 入口
skills/ - 官方 skills 目录
skills_developing/ - 开发中 skills
agent/subagent_loader.py - 扫描 skill agents/*.md 加载子 agent（2026-05 引入）
agent/mcp_trace_meta.py - 对 ClientSession.call_tool 做 monkey-patch，向 rag_retrieve / table_rag_retrieve 的 MCP _meta 注入 trace_id（2026-05 引入）

Gotchas（开发必读）

⚠️ MCP App resource REST 读取路径是 projects/robot/{bot_id}/skills/{server_name}/apps/{resource_name}.html，前端 bot_id 应由 ChatView 从当前 bot 传给 ChatMessage，不要在子组件里重新调用 useBotManager()
⚠️ langchain-mcp-adapters 会丢失 EmbeddedResource 的 uri/_meta；MCP App payload 需作为 text JSON 传递给前端识别
⚠️ 纯 SKILL.md 型业务 skill 适合先承载 workflow、输入模板、输出模板；需要稳定文件产出或自动化时再补 scripts/
⚠️ 新业务 skill 应复用既有基础能力 skill（如 baidu-search、xlsx、docx、pdf、schedule-job、imap-smtp-email），避免重复定义底层工具能力
⚠️ 新增脚本优先采用 Python + argparse + JSON stdout，比 argv[1] JSON 更适合自动化链路
⚠️ auto-daily-summary 需要特别注意中文分句、action 边界截断、risk 窗口裁剪，否则容易把整句/整段吞进去
⚠️ competitor-news-intel 的 payload 校验应按命令拆分（collect/analyze/run），不要共用一套最小校验
⚠️ competitor-news-intel 的 collect/run 依赖 BAIDU_API_KEY；无该环境变量时应返回稳定错误 JSON，不要静默降级

Stashed changes

⚠️ create_robot_project 的 autoload 去重是“包含匹配”，只要传入的 skill 字符串里包含 autoload skill 名，就不会重复自动加载
⚠️ _extract_skills_to_robot 只会从 skills/{PROJECT_NAME} 读取官方 skills，默认是 common
⚠️ 执行脚本必须使用绝对路径
⚠️ MCP 配置优先级：Skill MCP > 默认 MCP > 用户参数
⚠️ 上传大小限制：50MB（ZIP），解压后最大 500MB
⚠️ 压缩比例检查：最大 100:1（防止 zip 炸弹）
⚠️ 符号链接检查：禁止解压包含符号链接的文件
⚠️ 子 agent 同名静默 last-wins：subagent_loader._parse_agent_md 跨 skill 扫描 agents/*.md 时，按 name 字段去重，后扫描到的覆盖先扫描的，只打 warning 不报错。多 skill 都暴露子 agent 时需自觉错开命名。
⚠️ SubAgentMiddleware 中间件顺序：必须插在 CustomFilesystemMiddleware 之后、AnthropicPromptCachingMiddleware 之前——这是匹配 deepagents.create_deep_agent 的官方顺序，调整 create_custom_cli_agent 中的中间件顺序时不能随意挪动这一段。
⚠️ Daytona 模式下 skill 路径不同：DAYTONA_ENABLED=true 时 enable_skills 的 skills_sources 是 /workspace/skills（沙箱内），同时 system prompt 的 agent_dir_path 是 /workspace；写死本地路径的 hook / 脚本需要兼容两种环境。
⚠️ PostAgent hook 非流式分支已 fire-and-forget：routes/chat.py 用 asyncio.create_task 启动 hook，调用方不会等待也不会感知到 hook 的异常——hook 失败只会被自己的 logger 捕获。
⚠️ MCP _meta.trace_id 是全局 monkey-patch 注入：agent/mcp_trace_meta.patch_mcp_client_session_trace_meta() 在 get_tools_from_mcp() 入口调用一次后，会把 mcp.ClientSession.call_tool 永久包装；仅对工具名在 {"rag_retrieve", "table_rag_retrieve"} 集合内的调用注入 _meta.trace_id，扩展白名单要直接改 _TRACE_META_TOOL_NAMES 常量。
⚠️ PrePrompt hook 内容位置由模板决定：自 2026-04-23 起 hook 产出通过 {hook_content} 占位符注入 prompt/system_prompt.md，不再追加在 prompt 末尾；自定义模板必须包含 {hook_content} 占位符否则 hook 内容会丢失。
⚠️ init_agent 返回值已变 3 元素：Daytona 改造后 init_agent 返回 (agent, checkpointer, sandbox)；调用方解构必须更新。
⚠️ skill category 默认值：API 返回的 SkillItem.category——official skill fallback 为 "other"、user skill fallback 为 "custom"；前端做分类视图时需要同时识别这两个 sentinel，不要假设官方/用户 skill 用同一套缺省值。
⚠️ category 字段双入口：同一 skill 可以同时在 .claude-plugin/plugin.json 和 SKILL.md frontmatter 写 category；get_skill_metadata 优先走 parse_plugin_json，若 skill 包没有 plugin.json 才回落到 parse_skill_frontmatter——两者写不一致时以 plugin.json 为准。
⚠️ Daytona shell_env 是文件注入而非 process env：init_agent 通过 cat > $REMOTE_BASH_ENV_PATH 写入 export VAR=... 行，沙箱内必须由 shell（bash）的 BASH_ENV 加载才能生效；非 daytona 模式或不走 bash 启动的脚本拿不到这些变量。扩展注入项需直接改 init_agent 里的 _shell_env 字典。

Skill 目录结构

skill-name/
├── SKILL.md                    # 核心指令文档（必需）
├── skill.yaml                  # 元数据配置（可选）
├── .claude-plugin/
│   └── plugin.json            # Hook 和 MCP 配置（可选）
└── scripts/                    # 可执行脚本（可选）
    └── script.py

Hook 系统

Hook 类型	执行时机	用途
`PrePrompt`	system_prompt 加载时	动态注入用户上下文
`PostAgent`	agent 执行后	处理响应结果
`PreSave`	保存消息前	内容过滤/修改

API 接口

端点	方法	功能
`GET /api/v1/skill/list`	-	返回官方 + 用户 skills
`POST /api/v1/skill/upload`	-	ZIP 上传，解压到用户目录
`DELETE /api/v1/skill/remove`	-	删除用户 skill

内置 Skills

Skill 名称	功能描述
`excel-analysis`	Excel 数据分析、透视表、图表
`managing-scripts`	管理可复用脚本库
`rag-retrieve`	RAG 知识库检索
`jina-ai`	Jina AI Reader/Search
`user-context-loader`	Hook 机制示例

plugin.json 格式

{
  "name": "skill-name",
  "description": "描述",
  "hooks": {
    "PrePrompt": [{"type": "command", "command": "python hooks/pre_prompt.py"}],
    "PostAgent": [...],
    "PreSave": [...]
  },
  "mcpServers": {
    "server-name": {
      "command": "...",
      "args": [...]
    }
  }
}

Skill 加载优先级

Skill MCP 配置
用户传入参数（覆盖已有同名配置）

安全措施

ZipSlip 防护：检查解压路径
路径遍历防护：验证 bot_id 和 skill_name 格式
大小限制：上传 50MB，解压后 500MB
压缩比限制：最大 100:1

设计原则

渐进式加载：按需加载，避免一次性读取所有
绝对路径优先：执行脚本必须使用绝对路径
通用化设计：脚本应参数化，解决一类问题
安全优先：完整的上传验证链

配置项

SKILLS_DIR=./skills           # 官方 skills 目录
BACKEND_HOST=xxx             # RAG API 主机
MASTERKEY=xxx                # 认证密钥

索引

设计决策：decisions/
变更历史：changelog/
相关文档：docs/

13 KiB Raw Blame History Unescape Escape