diff --git a/docs/mcp-app-training.md b/docs/mcp-app-training.md new file mode 100644 index 0000000..a940629 --- /dev/null +++ b/docs/mcp-app-training.md @@ -0,0 +1,1063 @@ +# MCP App 协议培训文档 + +> 面向团队的技术培训材料，帮助理解 MCP App 协议的核心机制、实现方式与应用场景。 + +--- + +## 目录 + +1. [为什么需要 MCP App](#1-为什么需要-mcp-app) +2. [MCP Apps vs A2UI 对比](#2-mcp-apps-vs-a2ui-对比) +3. [核心概念：三层分离架构](#3-核心概念三层分离架构) +4. [协议通信机制详解](#4-协议通信机制详解) +5. [代码实现走读](#5-代码实现走读) +6. [现有实现案例分析](#6-现有实现案例分析) +7. [如何开发一个新的 MCP App Skill](#7-如何开发一个新的-mcp-app-skill) +8. [实际应用场景](#8-实际应用场景) +9. [FAQ](#9-faq) + +--- + +## 1. 为什么需要 MCP App + +### 传统 Agent 的局限 + +传统的 AI Agent 只能输出文本（Markdown、代码块等），无法直接在对话中呈现**可交互的 UI**。用户看到的永远是静态文字。 + +### MCP App 解决的问题 + +MCP App 协议让 Agent 的工具调用（tool call）能够返回**富交互组件**——图表、表单、按钮、嵌入页面等——直接渲染在聊天窗口中，用户可以点击、选择、输入，结果再传回 Agent 继续对话。 + +``` +用户提问 → Agent 思考 → 调用 MCP Tool → 返回 UI 组件 → 用户交互 → 结果回传 Agent +``` + +**核心价值：让 Agent 从"只会说话"变成"能展示、能交互"。** + +--- + +## 2. MCP Apps vs A2UI 对比 + +> 参考：[hia2ui.com - MCP Apps vs A2UI](https://hia2ui.com/zh-cn/blog/mcp-apps-vs-a2ui/) + +在 Agent UI 领域，目前存在两种主流协议方案。了解它们的差异有助于我们做出更好的技术选型。 + +### 2.1 两种哲学 + +| | MCP Apps (Anthropic) | A2UI (Google) | +|---|---|---| +| **核心理念** | **UI 即资源** — 将 UI 视为不透明的、外部获取的黑盒资源 | **UI 即协议** — 通过只具有声明语义的强类型 JSON 蓝图传输 | +| **传输内容** | 完整的 HTML/CSS/JavaScript 代码包 | 纯 JSON 声明式数据，**绝对不包含可执行代码** | +| **URI 格式** | `ui://server-name/resource` | N/A（通过 JSON schema 定义组件类型） | +| **宿主角色** | 被动容器 — 将 HTML 丢进 iframe 渲染 | 主动绘制者 — 用本地原生组件树渲染 JSON 蓝图 | + +用一句话概括差异： +- **MCP Apps**：服务端说"这是我画好的 UI 界面，你直接嵌进去展示" +- **A2UI**：服务端说"这是我要展示的数据结构，你用你自己的 UI 组件来画" + +### 2.2 四大维度详细对比 + +#### 维度一：核心架构 + +``` +MCP Apps（Iframe 沙盒模式）： +┌──────────────────────┐ +│ Host（聊天界面） │ +│ ┌──────────────────┐ │ +│ │ Iframe (sandbox) │ │ ← 将服务端返回的 HTML 代码 +│ │ ┌──────────────┐ │ │ "盲目地"丢进 iframe 沙盒 +│ │ │ 完整 HTML/JS │ │ │ +│ │ └──────────────┘ │ │ +│ └──────────────────┘ │ +└──────────────────────┘ + +A2UI（原生声明式蓝图）： +┌──────────────────────┐ +│ Host（聊天界面） │ +│ │ +│ ┌─────┐ ┌─────┐ │ ← Host 拿到 JSON 蓝图后 +│ │Button│ │Card │ │ 用自己本地的原生组件渲染 +│ └─────┘ └─────┘ │ +│ ┌─────┐ ┌─────┐ │ +│ │Chart│ │List │ │ +│ └─────┘ └─────┘ │ +└──────────────────────┘ +``` + +#### 维度二：跨平台可移植性 + +| 平台 | MCP Apps | A2UI | +|------|---------|------| +| Web 浏览器 | 原生支持，表现优秀 | 映射为 React/Web 组件 | +| iOS | 需启动 WebView 内核，体验较重 | 映射为原生 UIButton 等 iOS 组件 | +| Android | 需启动 WebView 内核，体验较重 | 映射为 Material Design 组件 | +| 桌面端 | Electron 等框架可支持 | 映射为对应平台原生组件 | + +**结论**：A2UI 在跨平台一致性上优势明显。同一份 JSON 负载可以在各平台渲染为原生体验，而 MCP Apps 在非 Web 平台需要依赖 WebView，体验较重。 + +#### 维度三：样式控制权与设计一致性 + +| 维度 | MCP Apps | A2UI | +|------|---------|------| +| 样式由谁决定 | **服务端**决定（HTML/CSS 自带样式） | **宿主应用**决定（本地组件库样式） | +| 品牌一致性 | 较难保证，第三方 HTML 样式难以覆盖 | 自动继承宿主的 Design Tokens | +| 深色模式 | 需要 HTML App 自行适配 | 自动继承宿主的主题设置 | +| 定制能力 | 需要 CSS overrides 强行覆盖 | 天然支持，AI 只决定"展示什么"，不决定"长什么样" | + +**结论**：A2UI 在设计一致性上完胜。MCP Apps 的 HTML 自带样式可能与宿主应用的设计规范冲突。 + +#### 维度四：安全性与信任边界 + +| 维度 | MCP Apps | A2UI | +|------|---------|------| +| 可执行代码 | 包含（HTML 中可嵌入 JS） | **绝对禁止**（纯 JSON 数据） | +| 隔离方式 | 浏览器 Iframe 沙盒 | 在协议层面从根本上阻断代码注入 | +| 攻击面 | Iframe 沙盒逃逸是已知攻击面 | 无可执行代码 = 无 UI 注入攻击面 | +| LLM 生成风险 | HTML 可能由 LLM 实时生成，存在幻觉风险 | 仅传输声明式数据，组件由预审批目录提供 | + +**结论**：A2UI 从架构层面更安全（无可执行代码传输）。MCP Apps 依赖 Iframe 沙盒隔离，安全性取决于浏览器实现。 + +### 2.3 各自适用场景 + +#### 选择 MCP Apps 的场景 + +适合需要展示**完整独立应用**或**重度定制 UI** 的场景： + +- 包含复杂交互逻辑的独立工具（如 3D WebGL 可视化、代码编辑器） +- 需要嵌入的遗留系统界面（老旧的内部报表系统等） +- 有特殊渲染需求的第三方工具（终端模拟器、地图引擎等） +- 全屏弹窗类的沉浸式体验 + +> 特点：Agent 将它们作为**独立的全屏应用**召唤出来，自成一体。 + +#### 选择 A2UI 的场景 + +适合需要在聊天流中**深度内联嵌入**富交互微件的场景： + +- 聊天流中的原生交互卡片（商品卡片、审批卡片等） +- 数据驱动的动态仪表盘 +- 需要完美匹配宿主品牌设计规范的组件 +- 需要跨 Web + Mobile 统一体验的场景 + +> 特点：AI 生成的卡片与前端手写组件**无法分辨真假**。 + +### 2.4 对比总结 + +``` + MCP Apps A2UI + ┌─────────────────┐ ┌─────────────────┐ + 灵活度 │ ★★★★★ 极高 │ │ ★★★☆☆ 受组件库约束│ + 跨平台 │ ★★★☆☆ Web 为主 │ │ ★★★★★ 全平台原生 │ + 设计一致性 │ ★★☆☆☆ 需手动适配│ │ ★★★★★ 自动继承 │ + 安全性 │ ★★★☆☆ 依赖沙盒 │ │ ★★★★★ 架构级安全 │ + 开发门槛 │ ★★★★☆ 写 HTML 即可│ │ ★★★☆☆ 需组件库支持│ + 复杂 UI 能力 │ ★★★★★ 无限制 │ │ ★★★☆☆ 受限于组件集│ + └─────────────────┘ └─────────────────┘ +``` + +### 2.5 我们的选择与思考 + +**我们当前采用 MCP Apps 协议**，原因： + +1. **灵活度优先**：我们的场景需要渲染各种复杂 UI（ECharts 图表、自定义表单、任意 HTML），MCP Apps 的"传 HTML"模式给了我们最大的自由度 +2. **Web 优先**：我们的宿主环境是 Web 聊天界面，MCP Apps 的 iframe 方案天然契合 +3. **开发效率**：写一个 HTML 模板 + 一个 MCP Server 就能实现一个新组件，门槛低 +4. **生态兼容**：MCP 协议本身已有广泛的社区和工具链支持 + +**未来可能的演进**： + +- 对于需要深度内联到聊天流、强调品牌一致性的轻量卡片（如通知卡片、状态标签），可以考虑引入 A2UI +- 两种协议**并不互斥**，未来可能在同一应用中混合使用：重度工具用 MCP Apps，轻量卡片用 A2UI +- 关注 CopilotKit 等框架的双协议支持进展 + +--- + +## 3. 核心概念：三层分离架构 + +MCP App 协议的精髓是 **数据与 UI 分离**： + +``` +┌─────────────────────────────────────────────────┐ +│ Host (宿主) │ +│ 即聊天界面，负责 iframe 管理和消息路由 │ +│ │ +│ ┌─────────────────┐ ┌─────────────────────┐ │ +│ │ MCP Server │ │ HTML App (iframe) │ │ +│ │ (数据层) │ │ (渲染层) │ │ +│ │ │ │ │ │ +│ │ tools/call │ │ 接收 postMessage │ │ +│ │ → 返回纯数据 │ │ → 渲染成可交互 UI │ │ +│ │ │ │ │ │ +│ │ resources/read │ │ 用户操作 │ │ +│ │ → 返回静态 HTML │ │ → postMessage 回传 │ │ +│ └─────────────────┘ └─────────────────────┘ │ +└─────────────────────────────────────────────────┘ +``` + +### 三个角色 + +| 角色 | 职责 | 对应代码 | +|------|------|----------| +| **MCP Server** | 处理 `tools/call` 返回结构化数据；处理 `resources/read` 返回 HTML 模板 | `*_server.py` | +| **HTML App** | 静态 HTML 文件，监听 `postMessage` 接收数据后渲染 UI | `apps/*.html` | +| **Host** | 聊天界面，负责创建 iframe、加载 HTML App、通过 postMessage 传递数据 | 前端聊天框架 | + +### 为什么要分离？ + +- **安全**：HTML App 运行在 sandboxed iframe 中，与主页面隔离 +- **复用**：同一个 HTML App 模板可以渲染不同数据 +- **解耦**：MCP Server 不需要关心渲染细节，只负责产出数据 + +--- + +## 4. 协议通信机制详解 + +### 3.1 完整通信流程 + +以 `render_chart` 工具调用为例，完整流程如下： + +``` +步骤 1: Agent 决定调用 render_chart 工具 + ↓ +步骤 2: Host 发送 tools/call 请求到 MCP Server + → {"method": "tools/call", "params": {"name": "render_chart", "arguments": {...}}} + ↓ +步骤 3: MCP Server 返回 App Response（纯数据 + 资源引用） + ← {"type": "app", "resourceUri": "ui://data-dashboard/chart", "data": {...}} + ↓ +步骤 4: Host 解析到 resourceUri，发送 resources/read 请求 + → {"method": "resources/read", "params": {"uri": "ui://data-dashboard/chart"}} + ↓ +步骤 5: MCP Server 返回静态 HTML 模板 + ← {"mimeType": "text/html;profile=mcp-app", "text": "...chart.html内容..."} + ↓ +步骤 6: Host 将 HTML 加载到 sandboxed iframe + ↓ +步骤 7: iframe 内 HTML App 发送就绪信号 + → window.parent.postMessage({type: 'mcp-app-ready'}, '*') + ↓ +步骤 8: Host 收到就绪信号后，通过 postMessage 发送数据 + → iframe.postMessage({type: 'mcp-app-data', payload: {...}}, '*') + ↓ +步骤 9: HTML App 接收数据并渲染 UI + ↓ +步骤 10: （可选）用户交互后，HTML App 通过 postMessage 回传结果 + → window.parent.postMessage({type: 'mcp-app-response', payload: {...}}, '*') +``` + +### 3.2 三种关键消息类型 + +| 消息类型 | 方向 | 用途 | +|----------|------|------| +| `mcp-app-ready` | iframe → Host | HTML App 加载完毕，请求数据 | +| `mcp-app-data` | Host → iframe | 向 HTML App 传递工具调用返回的数据 | +| `mcp-app-response` | iframe → Host | 用户交互结果回传给 Agent | + +### 3.3 App Response 数据结构 + +MCP Server 的 `tools/call` 返回的核心结构： + +```json +{ + "type": "app", + "resourceUri": "ui://data-dashboard/chart", + "data": { + "title": "Monthly Revenue", + "chart_type": "line", + "data": { + "categories": ["Jan", "Feb", "Mar"], + "series": [{"name": "Revenue", "data": [820, 932, 901]}] + } + }, + "_meta": { + "mcpui.dev/ui-preferred-frame-size": ["100%", "400px"] + } +} +``` + +关键字段： +- `type: "app"` — 告诉 Host 这是一个需要渲染的 App 类型结果 +- `resourceUri` — 指向要加载的 HTML App 模板的 URI +- `data` — 传递给 HTML App 的业务数据 +- `_meta` — 元信息，如建议的 iframe 尺寸 + +### 3.4 Resource URI 协议 + +资源 URI 使用 `ui://` scheme： + +``` +ui://data-dashboard/chart → chart.html +ui://data-dashboard/metrics → metrics.html +ui://mcp-ui/html → html.html (通用 HTML 渲染器) +ui://mcp-ui/ask-user → ask-user.html (交互式问答) +``` + +MIME Type 约定： +- `text/html;profile=mcp-app` — 标准 MCP App HTML +- `text/uri-list` — 外部 URL 嵌入 + +--- + +## 5. 代码实现走读 + +### 5.1 目录结构（以 data-dashboard 为例） + +``` +skills/common/data-dashboard/ +├── .claude-plugin/ +│ └── plugin.json # 插件注册配置 +├── hooks/ +│ ├── pre_prompt.py # PrePrompt 钩子：注入工具使用指南 +│ └── dashboard_guide.md # Agent 使用指南（注入到 system prompt） +├── apps/ +│ ├── chart.html # 单图表渲染器 +│ ├── metrics.html # KPI 指标卡渲染器 +│ └── multi-chart.html # 多图表网格渲染器 +├── dashboard_server.py # MCP Server 主体 +├── dashboard_tools.json # 工具定义（JSON Schema） +└── mcp_common.py # 共享工具函数 +``` + +### 5.2 plugin.json — 插件注册 + +```json +{ + "name": "data-dashboard", + "description": "Renders data as interactive dashboard card UI", + "hooks": { + "PrePrompt": [{"type": "command", "command": "python hooks/pre_prompt.py"}] + }, + "mcpServers": { + "data_dashboard": { + "transport": "stdio", + "command": "python", + "args": ["./dashboard_server.py", "{bot_id}"] + } + } +} +``` + +要点： +- `mcpServers` 注册 MCP Server，使用 stdio 传输 +- `hooks.PrePrompt` 在对话开始前注入工具使用指南，让 Agent 知道何时/如何调用这些工具 +- `{bot_id}` 是动态参数，运行时替换为实际的 bot ID + +### 5.3 MCP Server 核心逻辑 + +Server 需要处理 5 种 MCP 方法： + +```python +# 1. initialize — 握手，声明 capabilities +if method == "initialize": + return {"capabilities": {"tools": {}, "resources": {}}} + +# 2. tools/list — 返回可用工具列表（含 _meta.ui.resourceUri） +elif method == "tools/list": + tools = load_tools_from_json("dashboard_tools.json") + return {"tools": tools} + +# 3. resources/list — 返回可用资源列表 +elif method == "resources/list": + return {"resources": RESOURCE_DEFINITIONS} + +# 4. resources/read — 返回 HTML App 文件内容 +elif method == "resources/read": + html = _load_app_html(uri) + return {"contents": [{"uri": uri, "mimeType": "text/html;profile=mcp-app", "text": html}]} + +# 5. tools/call — 执行工具，返回 App Response +elif method == "tools/call": + result = handler(arguments) + return result +``` + +### 5.4 工具定义中的 `_meta` 字段 + +工具定义（`dashboard_tools.json`）中的 `_meta.ui.resourceUri` 是关键： + +```json +{ + "name": "render_chart", + "description": "Render a single ECharts chart", + "inputSchema": { ... }, + "_meta": { + "ui": { + "resourceUri": "ui://data-dashboard/chart" + } + } +} +``` + +这个字段告诉 Host：调用这个工具的结果需要使用 `ui://data-dashboard/chart` 对应的 HTML App 来渲染。 + +### 5.5 HTML App 模板的标准写法 + +每个 HTML App 都遵循同一个模式： + +```html + + + + + + +
+ + + +``` + +如果需要**回传用户交互结果**（如 ask-user），额外添加： + +```javascript +// 用户点击提交后 +window.parent.postMessage({ + type: 'mcp-app-response', + payload: { /* 用户选择的数据 */ } +}, '*'); +``` + +--- + +## 6. 现有实现案例分析 + +### 6.1 mcp-ui — 基础 UI 组件库 + +提供三个通用工具： + +| 工具 | 功能 | HTML App | +|------|------|----------| +| `render_html` | 渲染任意 HTML/CSS/JS | `html.html` — 通用 HTML 注入渲染器 | +| `render_url` | 嵌入外部 URL | `url.html` — iframe 嵌套器 | +| `ask_user` | 交互式问答（单选/多选） | `ask-user.html` — 选项卡界面 | + +**特点**：`render_html` 是万能的——Agent 可以生成任意 HTML 内容直接渲染，灵活度最高。 + +### 6.2 data-dashboard — 数据可视化 + +提供三个专用图表工具： + +| 工具 | 功能 | HTML App | +|------|------|----------| +| `render_metrics` | KPI 指标卡 | `metrics.html` — 网格卡片布局 | +| `render_chart` | 单图表（6种类型） | `chart.html` — ECharts 渲染器 | +| `render_multi_chart` | 多图表网格 | `multi-chart.html` — 网格 ECharts | + +**特点**：Agent 只需提供结构化数据（类型、分类、数值），HTML App 负责用 ECharts 渲染出专业图表。 + +### 6.3 static-hosting — 静态文件托管 + +与前两者不同，static-hosting 不走 MCP App 协议，而是： +- Agent 将生成的 HTML/CSS/JS 写入文件系统 +- 通过 FastAPI 静态文件服务提供公开 URL +- 适用于需要**持久化访问**的场景（生成报告、网页等） + +**与 MCP App 的区别**： +- MCP App → 嵌入在聊天窗口内，临时性 +- static-hosting → 独立 URL，持久化，可分享 + +--- + +## 7. 如何开发一个新的 MCP App Skill + +### 步骤总结 + +``` +1. 创建目录结构 + skills/common/my-skill/ + ├── .claude-plugin/plugin.json + ├── hooks/ + │ ├── pre_prompt.py + │ └── usage_guide.md + ├── apps/ + │ └── my-widget.html + ├── my_server.py + ├── my_tools.json + └── mcp_common.py (symlink 或 copy) + +2. 定义工具 (my_tools.json) + - name, description, inputSchema + - _meta.ui.resourceUri 指向你的 HTML App + +3. 编写 HTML App (apps/my-widget.html) + - 监听 mcp-app-data + - 发送 mcp-app-ready + - （可选）发送 mcp-app-response + +4. 编写 MCP Server (my_server.py) + - 实现 initialize / tools/list / resources/list / resources/read / tools/call + - tools/call 中将参数转为 App Response + +5. 编写 Agent 使用指南 (hooks/usage_guide.md) + - 告诉 Agent 什么时候用、怎么用这个工具 + +6. 注册插件 (.claude-plugin/plugin.json) + - 配置 mcpServers 和 hooks +``` + +### 快速模板 + +一个最小的 MCP App Server（Python）： + +```python +import asyncio, json, os +from mcp_common import (create_error_response, create_ping_response, + create_tools_list_response, load_tools_from_json, + handle_mcp_streaming) + +RESOURCE_MIME_TYPE = "text/html;profile=mcp-app" +APPS_DIR = os.path.join(os.path.dirname(__file__), "apps") + +RESOURCE_MAP = {"ui://my-skill/widget": "widget.html"} + +def _load_app_html(uri): + filename = RESOURCE_MAP.get(uri) + if not filename: + raise ValueError(f"Unknown resource URI: {uri}") + with open(os.path.join(APPS_DIR, filename), "r") as f: + return f.read() + +def _create_app_response(resource_uri, data, width="100%", height="auto"): + return {"content": [{"type": "text", "text": json.dumps({ + "type": "app", "resourceUri": resource_uri, "data": data, + "_meta": {"mcpui.dev/ui-preferred-frame-size": [width, height]}, + }, ensure_ascii=False)}]} + +async def handle_request(request): + method = request.get("method") + params = request.get("params", {}) + rid = request.get("id") + + if method == "initialize": + return {"jsonrpc": "2.0", "id": rid, "result": { + "protocolVersion": "2024-11-05", + "capabilities": {"tools": {}, "resources": {}}, + "serverInfo": {"name": "my-skill", "version": "1.0.0"}}} + elif method == "tools/list": + return create_tools_list_response(rid, load_tools_from_json("my_tools.json")) + elif method == "resources/list": + return {"jsonrpc": "2.0", "id": rid, "result": {"resources": [ + {"uri": "ui://my-skill/widget", "name": "widget", + "mimeType": RESOURCE_MIME_TYPE}]}} + elif method == "resources/read": + html = _load_app_html(params.get("uri", "")) + return {"jsonrpc": "2.0", "id": rid, "result": {"contents": [ + {"uri": params["uri"], "mimeType": RESOURCE_MIME_TYPE, "text": html}]}} + elif method == "tools/call": + # 在这里处理你的业务逻辑 + return {"jsonrpc": "2.0", "id": rid, "result": _create_app_response( + "ui://my-skill/widget", params.get("arguments", {}))} + return create_error_response(rid, -32601, f"Unknown method: {method}") + +if __name__ == "__main__": + asyncio.run(handle_mcp_streaming(handle_request)) +``` + +--- + +## 8. 实际应用场景 + +### 8.1 已实现的场景 + +| 场景 | 使用的 Skill | 说明 | +|------|-------------|------| +| 数据可视化 | data-dashboard | 将查询结果渲染为图表（折线图、饼图、KPI 卡片等） | +| 通用 HTML 渲染 | mcp-ui / render_html | Agent 生成任意 HTML 内容直接展示 | +| 交互式问答 | mcp-ui / ask_user | 让用户通过点击选项来回答问题 | +| 外部页面嵌入 | mcp-ui / render_url | 在聊天中嵌入外部网页 | +| 报告生成 | static-hosting | 生成独立 HTML 报告，提供持久化 URL | + +--- + +### 8.2 电商 & 零售行业 + +#### 场景 1：商品浏览与选购 + +Agent 作为导购，在对话中展示可交互的商品卡片，用户直接点选下单。 +``` +用户: "我想买一杯咖啡" +Agent: 查询商品 → render_html 展示商品卡片列表（图片、价格、规格选择按钮） +用户: 点击"大杯拿铁" → mcp-app-response 回传选择 +Agent: 生成订单 → render_html 展示订单确认页（含二维码/支付链接） +用户: 点击"确认支付" → 跳转支付或内嵌支付页 +``` + +#### 场景 2：订单追踪可视化 + +用户查询订单后，Agent 用图表和时间轴展示物流进度。 +``` +用户: "我的订单到哪了？" +Agent: 查询物流 API → render_html 渲染物流时间轴（已下单→已发货→运输中→派送中） + render_url 嵌入地图展示快递实时位置 +``` + +#### 场景 3：智能比价与推荐 + +Agent 搜索多平台价格，用图表对比展示，用户点击心仪商品直接购买。 +``` +用户: "帮我比较一下 AirPods Pro 各平台价格" +Agent: 调用多个 API → render_chart(chart_type="bar") 展示各平台价格柱状图 + render_html 渲染商品对比卡片（含"去购买"按钮） +用户: 点击最低价平台的"去购买" → render_url 嵌入购买页面 +``` + +#### 场景 4：营销数据看板 + +商家用 Agent 查看店铺运营数据，实时图表展示 GMV、转化率、流量来源等。 +``` +店主: "看看这周的店铺数据" +Agent: 查询后台 API + → render_metrics 展示 KPI 卡片（GMV、订单数、客单价、退货率） + → render_multi_chart 展示趋势图 + 流量来源饼图 + 热销品排行柱状图 +``` + +#### 场景 5：退换货自助流程 + +用户在对话中完成退换货的完整流程，无需跳出。 +``` +用户: "我想退货" +Agent: ask_user 选择订单 → ask_user 选择退货原因 + → render_html 展示退货信息确认页（商品图、退款金额、退货地址） +用户: 点击"确认退货" → Agent 调用退货 API → 展示退货单号和进度 +``` + +--- + +### 8.3 教育 & 培训行业 + +#### 场景 1：交互式测验 + +Agent 出题后用选项卡 UI 让学生作答，即时批改并展示成绩图表。 +``` +老师: "给学生出一套 10 道英语选择题" +Agent: 生成题目 → ask_user 逐题展示选项（支持单选/多选） +学生: 逐题点击选项并提交 +Agent: 批改 → render_chart(chart_type="gauge") 展示总分 + → render_multi_chart 展示各知识点得分雷达图 + 错题分布 +``` + +#### 场景 2：学习进度仪表盘 + +学生查看自己的学习数据，Agent 用图表展示进度和薄弱环节。 +``` +学生: "我的学习情况怎么样？" +Agent: 查询学习记录 + → render_metrics 展示关键指标（完成率、连续学习天数、总学时） + → render_chart(chart_type="radar") 展示各科目能力雷达图 + → render_chart(chart_type="line") 展示近 30 天学习时长趋势 +``` + +#### 场景 3：代码 Playground + +编程教学中，Agent 在对话内嵌入可运行的代码编辑器，学生即学即练。 +``` +老师: "教学生用 Python 写一个冒泡排序" +Agent: 讲解算法 → render_html 渲染一个内嵌的代码编辑器 + 运行按钮 + 输出区 +学生: 修改代码 → 点击运行 → 实时看到排序过程动画 +``` + +#### 场景 4：课程安排与选课 + +用交互式日历展示课表，学生直接点选空闲时段报名课程。 +``` +学生: "我想报名下周的课程" +Agent: 查询可选课程 → render_html 渲染交互式周历（已有课程标灰，可选课程高亮） +学生: 点击某个时段的课程 → mcp-app-response 回传选课信息 +Agent: 确认选课 → 更新课表 +``` + +#### 场景 5：知识图谱可视化 + +复杂知识点之间的关系用交互式图谱展示，点击节点展开详情。 +``` +学生: "帮我梳理一下机器学习的知识体系" +Agent: render_html 渲染交互式知识图谱（D3.js 力导向图） + 节点：监督学习、无监督学习、强化学习... +学生: 点击"监督学习" → 回传节点 ID → Agent 展开子图谱（回归、分类、SVM、决策树...） +``` + +--- + +### 8.4 金融 & 财务行业 + +#### 场景 1：投资组合分析 + +Agent 查询持仓数据后，用图表展示资产配置和收益走势。 +``` +用户: "看看我的投资组合表现" +Agent: → render_chart(chart_type="pie") 展示资产配置比例（股票/债券/基金/现金） + → render_chart(chart_type="line") 展示近一年收益率走势（vs 沪深300） + → render_metrics 展示关键指标（总资产、日收益、年化收益率、最大回撤） +``` + +#### 场景 2：财务报表可视化 + +企业财务数据自动生成专业图表，支持钻取查看明细。 +``` +CFO: "展示 Q2 的财务概况" +Agent: 查询 ERP → render_multi_chart 四宫格展示： + - 收入趋势（折线图） + - 成本结构（饼图） + - 各部门预算执行（堆叠柱状图） + - 现金流仪表盘（gauge） +用户: 点击"销售部"柱子 → Agent 展开销售部详细费用明细 +``` + +#### 场景 3：风险评估与审批 + +贷款/保险审核场景，Agent 渲染评估报告和审批按钮。 +``` +风控: "审核这笔贷款申请" +Agent: 查询征信 → render_html 渲染风险评估报告（信用评分、负债率、历史逾期） + → render_chart(chart_type="gauge") 展示综合风险分数 + → render_html 底部渲染"批准 / 拒绝 / 补充材料"操作按钮 +风控: 点击"批准" → Agent 调用审批 API → 流程完成 +``` + +#### 场景 4：账单与报销管理 + +员工在对话中完成报销申请的完整流程。 +``` +员工: "我要提交上周出差的报销" +Agent: ask_user 选择出差项目和费用类型 + → render_html 渲染报销单表单（日期、金额、发票上传区） +员工: 填写并提交 → Agent 校验金额 → 提交审批流 + → render_html 展示审批进度时间轴 +``` + +--- + +### 8.5 医疗 & 健康行业 + +#### 场景 1：健康数据可视化 + +患者查看自己的健康指标趋势，Agent 用图表直观展示。 +``` +患者: "看看我最近的血压数据" +Agent: 查询健康记录 + → render_chart(chart_type="line") 展示近 30 天血压趋势（收缩压/舒张压双线） + → render_metrics 展示平均值、最高值、异常次数 + → render_html 底部展示健康建议卡片 +``` + +#### 场景 2：在线问诊引导 + +Agent 用交互式问答收集症状，辅助分诊。 +``` +患者: "我最近头疼" +Agent: ask_user 收集症状细节： + Q1: "头疼持续多久？" → [1-3天, 一周以上, 反复发作] + Q2: "伴随哪些症状？" → [恶心, 视力模糊, 发热, 无其他] (multi_select) + Q3: "疼痛位置？" → render_html 展示头部示意图，用户点击标记位置 +Agent: 综合分析 → render_html 展示初步评估结果 + 推荐科室 + 预约按钮 +``` + +#### 场景 3：预约挂号 + +在对话中展示医生排班表，患者点选预约。 +``` +患者: "帮我挂神经内科的号" +Agent: 查询排班 → render_html 渲染医生列表卡片（照片、职称、擅长、可约时段） +患者: 点击某医生 → ask_user 选择具体时间段 +Agent: 确认预约 → 展示预约成功信息和就诊提醒 +``` + +--- + +### 8.6 企业办公 & HR + +#### 场景 1：OA 审批流程 + +请假、采购、出差等审批在对话中一键完成。 +``` +员工: "帮我请三天年假" +Agent: ask_user 选择请假类型和日期范围 + → render_html 渲染请假申请预览（含剩余年假天数） +员工: 确认 → Agent 提交 OA 系统 + → render_html 展示审批链进度（直属经理→HR→完成） +``` + +#### 场景 2：团队数据看板 + +管理者查看团队运营指标，图表一目了然。 +``` +经理: "看看我们团队这个月的情况" +Agent: → render_metrics 展示 KPI（项目完成率、工时利用率、bug 数、客户满意度） + → render_multi_chart 展示： + - 各成员工时分布（堆叠柱状图） + - 项目进度甘特图（render_html 自定义） + - 本月 vs 上月对比（折线图） +``` + +#### 场景 3：招聘面试管理 + +HR 用 Agent 管理候选人，在对话中查看面试安排和评估。 +``` +HR: "今天有哪些面试？" +Agent: 查询日程 → render_html 渲染今日面试时间轴（候选人、岗位、面试官、时间） +HR: 点击某候选人 → Agent 展示简历摘要 + 前几轮面评 + → ask_user 选择面试结论（通过/待定/淘汰） +``` + +#### 场景 4：会议纪要与投票 + +会议中实时收集决策投票，即时展示结果。 +``` +主持人: "大家投票选择 Q3 的主推方案" +Agent: ask_user 展示方案选项（方案A/方案B/方案C），支持多人投票 + → 汇总结果 → render_chart(chart_type="pie") 展示投票比例 + → render_html 展示会议结论摘要 + 行动项清单 +``` + +--- + +### 8.7 房产 & 本地生活 + +#### 场景 1：房源浏览与对比 + +在对话中展示房源卡片，支持对比和地图查看。 +``` +用户: "帮我找朝阳区两居室，预算 500 万以内" +Agent: 搜索房源 → render_html 渲染房源卡片列表（图片轮播、价格、面积、户型图） +用户: 选中 3 套 → Agent → render_html 渲染对比表格（价格/面积/楼层/朝向/学区） +用户: 点击"查看位置" → render_html 渲染地图标注（3 套房源 + 周边配套） +``` + +#### 场景 2：餐厅推荐与订位 + +Agent 推荐餐厅，用户在对话中直接预约座位。 +``` +用户: "今晚想吃日料，帮我推荐" +Agent: 搜索附近餐厅 → render_html 渲染餐厅卡片（评分、人均、距离、招牌菜图片） +用户: 点击某餐厅 → Agent 展示详情 + 可用时段 + → ask_user 选择用餐时间和人数 +Agent: 调用预约 API → 展示预约确认信息 +``` + +#### 场景 3：装修进度管理 + +业主用 Agent 追踪装修进度，图文结合展示。 +``` +业主: "装修到哪一步了？" +Agent: 查询工程系统 → render_html 渲染装修进度时间轴（水电→瓦工→木工→油漆→软装） + 每个节点可展开查看现场照片 + → render_chart(chart_type="pie") 展示费用分配 + → render_metrics 展示预算执行（总预算、已花费、剩余） +``` + +--- + +### 8.8 物流 & 供应链 + +#### 场景 1：运输追踪大屏 + +在对话中展示车队/货物的实时状态。 +``` +调度员: "看看今天所有在途车辆" +Agent: 查询 TMS → render_html 渲染地图（标注所有在途车辆位置和状态） + → render_metrics 展示概览（在途 23 辆、已到达 15 辆、异常 2 辆） +调度员: 点击异常车辆标注 → Agent 展示异常详情 + 处理选项按钮 +``` + +#### 场景 2：库存预警与补货 + +Agent 监控库存，低于阈值时主动展示预警图表和补货建议。 +``` +仓管: "哪些商品快缺货了？" +Agent: 查询 WMS → render_html 渲染库存预警表格（红/黄/绿三色标注） + → render_chart(chart_type="bar") 展示 Top 10 紧缺商品及预计断货天数 + → render_html 底部渲染"一键生成补货单"按钮 +仓管: 点击按钮 → Agent 自动生成采购单 → ask_user 确认供应商和数量 +``` + +--- + +### 8.9 旅游 & 酒店行业 + +#### 场景 1：行程规划助手 + +Agent 生成交互式行程表，用户拖拽调整。 +``` +用户: "帮我规划 5 天东京自由行" +Agent: 生成行程 → render_html 渲染交互式日程表（每天的景点、交通、餐厅、住宿） + 每个景点卡片含图片、预计时长、门票价格 +用户: 拖拽调整顺序 / 删除某景点 → mcp-app-response 回传新顺序 +Agent: 重新优化路线 → render_html 更新地图路线图 +``` + +#### 场景 2：酒店预订对比 + +Agent 搜索多个平台，在对话中渲染对比界面。 +``` +用户: "帮我找东京新宿的酒店，2 晚" +Agent: 搜索多平台 → render_html 渲染酒店对比卡片（图片轮播、评分、价格、设施标签） + → render_chart(chart_type="scatter") 展示价格 vs 评分散点图 +用户: 点击心仪酒店 → render_url 嵌入预订页面 +``` + +#### 场景 3：景区实时信息 + +展示景区客流量、天气、开放状态等实时信息。 +``` +用户: "迪士尼现在人多吗？" +Agent: → render_metrics 展示实时数据（当前客流 12,000、各区域排队时长） + → render_chart(chart_type="line") 展示今日客流量趋势（预测下午 3 点高峰） + → render_html 展示热门项目排队时间排行（红绿标注） +``` + +--- + +### 8.10 制造 & 工业行业 + +#### 场景 1：生产监控大屏 + +Agent 实时展示产线状态和异常告警。 +``` +厂长: "1 号产线今天的情况怎么样？" +Agent: → render_metrics 展示 KPI（产量、良品率、设备 OEE、停机次数） + → render_multi_chart 展示： + - 每小时产量趋势（折线图） + - 不良品分类（饼图） + - 各工位效率对比（柱状图） + - 设备温度仪表盘（gauge） +``` + +#### 场景 2：设备维保管理 + +展示设备健康状态，支持一键报修。 +``` +维保工程师: "哪些设备需要保养了？" +Agent: 查询设备系统 → render_html 渲染设备列表（状态灯：绿/黄/红） + → render_chart(chart_type="bar") 展示各设备距下次保养的剩余天数 +工程师: 点击某设备 → Agent 展示维保记录 + 零件清单 + → render_html 渲染"创建工单"按钮 → 点击后自动创建维保工单 +``` + +#### 场景 3：质检报告可视化 + +质检数据自动生成可视化报告，支持导出。 +``` +质检员: "生成今天的质检报告" +Agent: 查询质检数据 + → render_multi_chart 展示各检测项合格率、SPC 控制图 + → render_html 渲染质检报告摘要（含不合格批次明细表格） + → static-hosting 生成 PDF 格式报告，提供下载 URL +``` + +--- + +### 8.11 IT & 运维行业 + +#### 场景 1：服务监控仪表盘 + +在对话中实时展示系统运行状态。 +``` +运维: "生产环境现在状态怎么样？" +Agent: → render_metrics 展示关键指标（在线实例 12/12、P99: 230ms、错误率 0.02%） + → render_multi_chart 展示 CPU/内存/QPS/错误率四宫格图表 + → render_url 嵌入 Grafana 面板查看更多细节 +``` + +#### 场景 2：故障排查向导 + +Agent 引导运维人员逐步排查问题。 +``` +运维: "用户反馈页面加载很慢" +Agent: + Step 1 → ask_user 选择受影响的服务（API/Web/DB） + Step 2 → Agent 查询日志 → render_chart 展示该服务近 1 小时响应时间 + Step 3 → 发现 DB 慢查询 → render_html 渲染慢查询 Top 10 表格 + Step 4 → ask_user 选择处理方式（添加索引 / 重启连接池 / 扩容） + Step 5 → Agent 执行 → render_metrics 展示恢复后的指标 +``` + +#### 场景 3：CI/CD 流水线管理 + +在对话中创建和监控部署流水线。 +``` +开发者: "帮我配一个新的部署流水线" +Agent: + → ask_user 选择代码仓库和分支策略 + → ask_user 选择构建环境（Node 20 / Python 3.12 / Go 1.22） + → ask_user 选择部署目标（dev / staging / prod） + → render_html 展示生成的 YAML 配置预览 + → 用户确认 → Agent 调 API 创建 → render_html 展示流水线状态时间轴 +``` + +--- + +### 8.12 场景速查表 + +| 行业 | 典型场景 | 核心工具组合 | +|------|---------|-------------| +| 电商零售 | 商品浏览、比价、订单追踪、营销看板、退换货 | render_html + ask_user + render_chart | +| 教育培训 | 在线测验、学习看板、代码练习、选课、知识图谱 | ask_user + render_chart + render_html | +| 金融财务 | 投资分析、财报可视化、风控审批、报销管理 | render_multi_chart + render_metrics + render_html | +| 医疗健康 | 健康趋势、问诊引导、预约挂号 | render_chart + ask_user + render_html | +| 企业办公 | OA 审批、团队看板、招聘管理、会议投票 | ask_user + render_metrics + render_chart | +| 房产生活 | 房源对比、餐厅预约、装修追踪 | render_html + render_chart + ask_user | +| 物流供应链 | 运输追踪、库存预警、补货管理 | render_html + render_metrics + render_chart | +| 旅游酒店 | 行程规划、酒店对比、景区实时信息 | render_html + render_chart + render_url | +| 制造工业 | 产线监控、设备维保、质检报告 | render_multi_chart + render_metrics + render_html | +| IT 运维 | 服务监控、故障排查、CI/CD 管理 | render_metrics + render_multi_chart + ask_user | + +## 9. FAQ + +### Q: MCP App 和 static-hosting 有什么区别？ + +| 维度 | MCP App | static-hosting | +|------|---------|----------------| +| 渲染位置 | 聊天窗口内（iframe） | 独立浏览器 Tab | +| 生命周期 | 临时，随对话存在 | 持久化，有独立 URL | +| 交互能力 | 双向（postMessage） | 单向（只展示） | +| 适用场景 | 对话内交互组件 | 报告、网页、可分享内容 | + +### Q: HTML App 是每次重新加载还是缓存的？ + +HTML App 模板是通过 `resources/read` 获取的静态文件，Host 可以缓存。但每次 `tools/call` 的数据是动态的，通过 postMessage 实时传入。 + +### Q: 用户交互结果如何回传给 Agent？ + +HTML App 通过 `window.parent.postMessage({type: 'mcp-app-response', payload: ...})` 发送，Host 接收后将 payload 作为工具调用结果传回 Agent，Agent 可以据此继续对话。 + +### Q: 安全性如何保证？ + +- HTML App 运行在 **sandboxed iframe** 中，无法访问主页面 DOM +- 使用 `postMessage` 通信，有明确的消息协议 +- 不执行任意远程代码，HTML 模板是预定义的静态文件 + +### Q: 我能用 React/Vue 来写 HTML App 吗？ + +可以，但建议将构建产物打包为单个 HTML 文件（inline CSS/JS）。因为 `resources/read` 返回的是一个完整的 HTML 字符串，不支持多文件加载。也可以用 CDN 引入框架（如示例中 ECharts 用了 CDN）。 + +### Q: PrePrompt Hook 是做什么的？ + +PrePrompt 钩子在每次对话开始前执行，将 `usage_guide.md` 的内容注入到 Agent 的 system prompt 中。这让 Agent 知道有哪些工具可用，以及什么时候应该调用它们。**这是让 Agent "学会"使用 UI 工具的关键。** + +--- + +## 附录：参考资源 + +- 项目内 mcp-ui 源码：`skills/common/mcp-ui/` +- 项目内 data-dashboard 源码：`skills/common/data-dashboard/` +- 项目内 static-hosting 定义：`skills/support/static-hosting/SKILL.md` +- MCP UI 社区项目：[github.com/idosal/mcp-ui](https://github.com/idosal/mcp-ui) +- MCP 协议规范：[modelcontextprotocol.io](https://modelcontextprotocol.io) diff --git a/routes/skill_manager.py b/routes/skill_manager.py index 41f27e0..0b4eed1 100644 --- a/routes/skill_manager.py +++ b/routes/skill_manager.py @@ -22,6 +22,7 @@ class SkillItem(BaseModel): name: str description: str user_skill: bool = False + category: str = "other" class SkillListResponse(BaseModel): @@ -35,6 +36,7 @@ class SkillValidationResult: valid: bool name: Optional[str] = None description: Optional[str] = None + category: Optional[str] = None error_message: Optional[str] = None @@ -268,7 +270,8 @@ def parse_plugin_json(plugin_json_path: str) -> SkillValidationResult: return SkillValidationResult( valid=True, name=plugin_config['name'], - description=plugin_config['description'] + description=plugin_config['description'], + category=plugin_config.get('category'), ) except json.JSONDecodeError as e: @@ -335,7 +338,8 @@ def parse_skill_frontmatter(skill_md_path: str) -> SkillValidationResult: return SkillValidationResult( valid=True, name=metadata['name'], - description=metadata['description'] + description=metadata['description'], + category=metadata.get('category'), ) except yaml.YAMLError as e: @@ -411,10 +415,13 @@ def get_skill_metadata_legacy(skill_path: str) -> Optional[dict]: """ result = get_skill_metadata(skill_path) if result.valid: - return { + ret = { 'name': result.name, - 'description': result.description + 'description': result.description, } + if result.category: + ret['category'] = result.category + return ret return None @@ -457,7 +464,8 @@ def get_official_skills(base_dir: str) -> List[SkillItem]: skills.append(SkillItem( name=metadata['name'], description=metadata['description'], - user_skill=False + user_skill=False, + category=metadata.get('category', 'other'), )) skill_names.add(skill_name) logger.debug(f"Found official skill: {metadata['name']} from {official_skills_dir}") @@ -490,7 +498,8 @@ def get_user_skills(base_dir: str, bot_id: str) -> List[SkillItem]: skills.append(SkillItem( name=metadata['name'], description=metadata['description'], - user_skill=True + user_skill=True, + category=metadata.get('category', 'custom'), )) logger.debug(f"Found user skill: {metadata['name']}") diff --git a/skills/autoload/onprem/rag-retrieve/.claude-plugin/plugin.json b/skills/autoload/onprem/rag-retrieve/.claude-plugin/plugin.json index a929aa6..4633057 100644 --- a/skills/autoload/onprem/rag-retrieve/.claude-plugin/plugin.json +++ b/skills/autoload/onprem/rag-retrieve/.claude-plugin/plugin.json @@ -18,5 +18,6 @@ "{bot_id}" ] } - } + }, + "category": "Data & Retrieval" } diff --git a/skills/autoload/support/rag-retrieve/.claude-plugin/plugin.json b/skills/autoload/support/rag-retrieve/.claude-plugin/plugin.json index a929aa6..4633057 100644 --- a/skills/autoload/support/rag-retrieve/.claude-plugin/plugin.json +++ b/skills/autoload/support/rag-retrieve/.claude-plugin/plugin.json @@ -18,5 +18,6 @@ "{bot_id}" ] } - } + }, + "category": "Data & Retrieval" } diff --git a/skills/common/data-dashboard/.claude-plugin/plugin.json b/skills/common/data-dashboard/.claude-plugin/plugin.json index a7c0b8a..8ed7587 100644 --- a/skills/common/data-dashboard/.claude-plugin/plugin.json +++ b/skills/common/data-dashboard/.claude-plugin/plugin.json @@ -1,6 +1,7 @@ { "name": "data-dashboard", "description": "Renders data as an interactive dashboard card UI using the mcp-ui protocol.", + "category": "Interactive UI", "hooks": { "PrePrompt": [ { diff --git a/skills/common/docx/SKILL.md b/skills/common/docx/SKILL.md index 6646638..8f04a28 100644 --- a/skills/common/docx/SKILL.md +++ b/skills/common/docx/SKILL.md @@ -2,6 +2,7 @@ name: docx description: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks" license: Proprietary. LICENSE.txt has complete terms +category: Document Processing --- # DOCX creation, editing, and analysis diff --git a/skills/common/imap-smtp-email/SKILL.md b/skills/common/imap-smtp-email/SKILL.md index b61ca3e..713b320 100644 --- a/skills/common/imap-smtp-email/SKILL.md +++ b/skills/common/imap-smtp-email/SKILL.md @@ -16,6 +16,7 @@ metadata: - node - npm primaryEnv: SMTP_PASS +category: Communication --- # IMAP/SMTP Email Tool diff --git a/skills/common/mcp-ui/.claude-plugin/plugin.json b/skills/common/mcp-ui/.claude-plugin/plugin.json index bb8ca06..a90ec7c 100644 --- a/skills/common/mcp-ui/.claude-plugin/plugin.json +++ b/skills/common/mcp-ui/.claude-plugin/plugin.json @@ -13,7 +13,11 @@ "mcp_ui": { "transport": "stdio", "command": "python", - "args": ["./ui_render_server.py", "{bot_id}"] + "args": [ + "./ui_render_server.py", + "{bot_id}" + ] } - } + }, + "category": "Interactive UI" } diff --git a/skills/common/pdf/SKILL.md b/skills/common/pdf/SKILL.md index f6a22dd..52a8cf8 100644 --- a/skills/common/pdf/SKILL.md +++ b/skills/common/pdf/SKILL.md @@ -2,6 +2,7 @@ name: pdf description: Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form or programmatically process, generate, or analyze PDF documents at scale. license: Proprietary. LICENSE.txt has complete terms +category: Document Processing --- # PDF Processing Guide diff --git a/skills/common/pptx/SKILL.md b/skills/common/pptx/SKILL.md index 03107c4..fad4906 100644 --- a/skills/common/pptx/SKILL.md +++ b/skills/common/pptx/SKILL.md @@ -2,6 +2,7 @@ name: pptx description: "Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying or editing content, (3) Working with layouts, (4) Adding comments or speaker notes, or any other presentation tasks" license: Proprietary. LICENSE.txt has complete terms +category: Document Processing --- # PPTX creation, editing, and analysis diff --git a/skills/common/r2-upload/SKILL.md b/skills/common/r2-upload/SKILL.md index ddd167b..8272e8e 100644 --- a/skills/common/r2-upload/SKILL.md +++ b/skills/common/r2-upload/SKILL.md @@ -5,6 +5,7 @@ compatibility: Requires Python 3.8+ and PyYAML. Uses AWS SigV4 signing (no exter metadata: author: foundra version: "2.1" +category: Web Services --- # R2 Upload diff --git a/skills/common/schedule-job/.claude-plugin/plugin.json b/skills/common/schedule-job/.claude-plugin/plugin.json index 0e19806..d59bc15 100644 --- a/skills/common/schedule-job/.claude-plugin/plugin.json +++ b/skills/common/schedule-job/.claude-plugin/plugin.json @@ -8,5 +8,6 @@ "command": "python scripts/schedule_manager.py list --format brief" } ] - } + }, + "category": "Task Scheduling" } diff --git a/skills/common/schedule-job/SKILL.md b/skills/common/schedule-job/SKILL.md index 16d645e..92be694 100644 --- a/skills/common/schedule-job/SKILL.md +++ b/skills/common/schedule-job/SKILL.md @@ -1,6 +1,7 @@ --- name: schedule-job description: Scheduled Task Management - Create, manage, and view scheduled tasks for users (supports cron recurring tasks and one-time tasks) +category: Task Scheduling --- # Schedule Job - Scheduled Task Management diff --git a/skills/common/skill-creator/SKILL.md b/skills/common/skill-creator/SKILL.md index 942bfe8..de48aa0 100644 --- a/skills/common/skill-creator/SKILL.md +++ b/skills/common/skill-creator/SKILL.md @@ -1,6 +1,7 @@ --- name: skill-creator description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. +category: Developer Tools --- # Skill Creator diff --git a/skills/common/xlsx/SKILL.md b/skills/common/xlsx/SKILL.md index 22db189..403a45e 100644 --- a/skills/common/xlsx/SKILL.md +++ b/skills/common/xlsx/SKILL.md @@ -2,6 +2,7 @@ name: xlsx description: "Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. When Claude needs to work with spreadsheets (.xlsx, .xlsm, .csv, .tsv, etc) for: (1) Creating new spreadsheets with formulas and formatting, (2) Reading or analyzing data, (3) Modify existing spreadsheets while preserving formulas, (4) Data analysis and visualization in spreadsheets, or (5) Recalculating formulas" license: Proprietary. LICENSE.txt has complete terms +category: Document Processing --- # Requirements for Outputs diff --git a/skills/developing/ai-ppt-generator/SKILL.md b/skills/developing/ai-ppt-generator/SKILL.md new file mode 100644 index 0000000..ef4277f --- /dev/null +++ b/skills/developing/ai-ppt-generator/SKILL.md @@ -0,0 +1,86 @@ +--- +name: ai-ppt-generator +description: Generate PPT with Baidu AI. Smart template selection based on content. +metadata: { "openclaw": { "emoji": "📑", "requires": { "bins": ["python3"], "env":["BAIDU_API_KEY"]},"primaryEnv":"BAIDU_API_KEY" } } +category: Document Processing +--- + +# AI PPT Generator + +Generate PPT using Baidu AI with intelligent template selection. + +## Smart Workflow +1. **User provides PPT topic** +2. **Agent asks**: "Want to choose a template style?" +3. **If yes** → Show styles from `ppt_theme_list.py` → User picks → Use `generate_ppt.py` with chosen `tpl_id` and real `style_id` +4. **If no** → Use `random_ppt_theme.py` (auto-selects appropriate template based on topic content) + +## Intelligent Template Selection +`random_ppt_theme.py` analyzes the topic and suggests appropriate template: +- **Business topics** → 企业商务 style +- **Technology topics** → 未来科技 style +- **Education topics** → 卡通手绘 style +- **Creative topics** → 创意趣味 style +- **Cultural topics** → 中国风 or 文化艺术 style +- **Year-end reports** → 年终总结 style +- **Minimalist design** → 扁平简约 style +- **Artistic content** → 文艺清新 style + +## Scripts +- `scripts/ppt_theme_list.py` - List all available templates with style_id and tpl_id +- `scripts/random_ppt_theme.py` - Smart template selection + generate PPT +- `scripts/generate_ppt.py` - Generate PPT with specific template (uses real style_id and tpl_id from API) + +## Key Features +- **Smart categorization**: Analyzes topic content to suggest appropriate style +- **Fallback logic**: If template not found, automatically uses random selection +- **Complete parameters**: Properly passes both style_id and tpl_id to API + +## Usage Examples +```bash +# List all templates with IDs +python3 scripts/ppt_theme_list.py + +# Smart automatic selection (recommended for most users) +python3 scripts/random_ppt_theme.py --query "人工智能发展趋势报告" + +# Specific template with proper style_id +python3 scripts/generate_ppt.py --query "儿童英语课件" --tpl_id 106 + +# Specific template with auto-suggested category +python3 scripts/random_ppt_theme.py --query "企业年度总结" --category "企业商务" +``` + +## Agent Steps +1. Get PPT topic from user +2. Ask: "Want to choose a template style?" +3. **If user says YES**: + - Run `ppt_theme_list.py` to show available templates + - User selects a template (note the tpl_id) + - Run `generate_ppt.py --query "TOPIC" --tpl_id ID` +4. **If user says NO**: + - Run `random_ppt_theme.py --query "TOPIC"` + - Script will auto-select appropriate template based on topic +5. Set timeout to 300 seconds (PPT generation takes 2-5 minutes) +6. Monitor output, wait for `is_end: true` to get final PPT URL + +## Output Examples +**During generation:** +```json +{"status": "PPT生成中", "run_time": 45} +``` + +**Final result:** +```json +{ + "status": "PPT导出结束", + "is_end": true, + "data": {"ppt_url": "https://image0.bj.bcebos.com/...ppt"} +} +``` + +## Technical Notes +- **API integration**: Fetches real style_id from Baidu API for each template +- **Error handling**: If template not found, falls back to random selection +- **Timeout**: Generation takes 2-5 minutes, set sufficient timeout +- **Streaming**: Uses streaming API, wait for `is_end: true` before considering complete \ No newline at end of file diff --git a/skills/developing/catalog-search-agent/.claude-plugin/plugin.json b/skills/developing/catalog-search-agent/.claude-plugin/plugin.json index 5c0db89..8d4cfcb 100644 --- a/skills/developing/catalog-search-agent/.claude-plugin/plugin.json +++ b/skills/developing/catalog-search-agent/.claude-plugin/plugin.json @@ -8,5 +8,6 @@ }, "skills": [ "./skills/catalog-search-agent" - ] + ], + "category": "Data & Retrieval" } diff --git a/skills/developing/ecommerce-storefront/.claude-plugin/plugin.json b/skills/developing/ecommerce-storefront/.claude-plugin/plugin.json new file mode 100644 index 0000000..ba91756 --- /dev/null +++ b/skills/developing/ecommerce-storefront/.claude-plugin/plugin.json @@ -0,0 +1,23 @@ +{ + "name": "ecommerce-storefront", + "description": "Renders interactive product browsing, selection, and order confirmation UI for e-commerce scenarios.", + "hooks": { + "PrePrompt": [ + { + "type": "command", + "command": "python hooks/pre_prompt.py" + } + ] + }, + "mcpServers": { + "ecommerce_storefront": { + "transport": "stdio", + "command": "python", + "args": [ + "./ecommerce_server.py", + "{bot_id}" + ] + } + }, + "category": "Developer Tools" +} diff --git a/skills/developing/ecommerce-storefront/apps/order-confirm.html b/skills/developing/ecommerce-storefront/apps/order-confirm.html new file mode 100644 index 0000000..bbbfa1d --- /dev/null +++ b/skills/developing/ecommerce-storefront/apps/order-confirm.html @@ -0,0 +1,233 @@ + + + + + +Order Confirmation + + + +
+
+
+
+
+
+
+
+ + + diff --git a/skills/developing/ecommerce-storefront/apps/product-list.html b/skills/developing/ecommerce-storefront/apps/product-list.html new file mode 100644 index 0000000..8e00171 --- /dev/null +++ b/skills/developing/ecommerce-storefront/apps/product-list.html @@ -0,0 +1,288 @@ + + + + + +Product List + + + +

+
+ + + diff --git a/skills/developing/ecommerce-storefront/ecommerce_server.py b/skills/developing/ecommerce-storefront/ecommerce_server.py new file mode 100644 index 0000000..54eb5cf --- /dev/null +++ b/skills/developing/ecommerce-storefront/ecommerce_server.py @@ -0,0 +1,213 @@ +#!/usr/bin/env python3 +""" +E-Commerce Storefront MCP Server - standard MCP Apps protocol (SEP-1865). + +- tools/call returns structured data only (no HTML) +- resources/read returns static HTML App files +- Host renders HTML App in iframe, passes tool data via postMessage +""" + +import asyncio +import json +import os +from typing import Any, Dict + +from mcp_common import ( + create_error_response, + create_ping_response, + create_tools_list_response, + load_tools_from_json, + handle_mcp_streaming, +) + +RESOURCE_MIME_TYPE = "text/html;profile=mcp-app" +APPS_DIR = os.path.join(os.path.dirname(__file__), "apps") + +# Resource URI -> static HTML App file mapping +RESOURCE_MAP = { + "ui://ecommerce-storefront/product-list": "product-list.html", + "ui://ecommerce-storefront/order-confirm": "order-confirm.html", +} + +RESOURCE_DEFINITIONS = [ + { + "uri": "ui://ecommerce-storefront/product-list", + "name": "product-list", + "title": "Product List", + "description": "Interactive product cards with spec selection", + "mimeType": RESOURCE_MIME_TYPE, + }, + { + "uri": "ui://ecommerce-storefront/order-confirm", + "name": "order-confirm", + "title": "Order Confirmation", + "description": "Order summary with payment options", + "mimeType": RESOURCE_MIME_TYPE, + }, +] + + +def _load_app_html(uri: str) -> str: + """Load static HTML App file for the given resource URI.""" + filename = RESOURCE_MAP.get(uri) + if not filename: + raise ValueError(f"Unknown resource URI: {uri}") + filepath = os.path.join(APPS_DIR, filename) + with open(filepath, "r", encoding="utf-8") as f: + return f.read() + + +def _create_app_response(resource_uri: str, data: Dict[str, Any], + width: str = "100%", height: str = "auto") -> Dict[str, Any]: + """Create a tool result for MCP Apps protocol.""" + app_json = json.dumps({ + "type": "app", + "resourceUri": resource_uri, + "data": data, + "_meta": { + "mcpui.dev/ui-preferred-frame-size": [width, height], + }, + }, ensure_ascii=False) + return {"content": [{"type": "text", "text": app_json}]} + + +# --------------------------------------------------------------------------- +# Tool handlers +# --------------------------------------------------------------------------- + +def _handle_render_product_list(arguments: Dict[str, Any]) -> Dict[str, Any]: + title = arguments.get("title", "Products") + products = arguments.get("products", []) + if not products: + raise ValueError("Missing required parameter: products") + return _create_app_response( + "ui://ecommerce-storefront/product-list", + {"title": title, "products": products}, + "100%", "auto", + ) + + +def _handle_render_order_confirm(arguments: Dict[str, Any]) -> Dict[str, Any]: + title = arguments.get("title", "Order Confirmation") + order = arguments.get("order") + payment = arguments.get("payment") + if not order: + raise ValueError("Missing required parameter: order") + if not payment: + raise ValueError("Missing required parameter: payment") + if not order.get("items"): + raise ValueError("Missing required parameter: order.items") + return _create_app_response( + "ui://ecommerce-storefront/order-confirm", + {"title": title, "order": order, "payment": payment}, + "100%", "auto", + ) + + +TOOL_HANDLERS = { + "render_product_list": _handle_render_product_list, + "render_order_confirm": _handle_render_order_confirm, +} + + +async def handle_request(request: Dict[str, Any]) -> Dict[str, Any]: + """Handle an MCP request.""" + try: + method = request.get("method") + params = request.get("params", {}) + request_id = request.get("id") + + if method == "initialize": + return { + "jsonrpc": "2.0", + "id": request_id, + "result": { + "protocolVersion": "2024-11-05", + "capabilities": { + "tools": {}, + "resources": {}, + }, + "serverInfo": { + "name": "ecommerce-storefront", + "version": "1.0.0", + }, + }, + } + + elif method == "ping": + return create_ping_response(request_id) + + elif method == "tools/list": + tools = load_tools_from_json("ecommerce_tools.json") + if not tools: + tools = [ + { + "name": name, + "description": f"Render {name.replace('render_', '')}", + "inputSchema": {"type": "object", "properties": {}, "required": []}, + "_meta": {"ui": {"resourceUri": uri}}, + } + for name, uri in [ + ("render_product_list", "ui://ecommerce-storefront/product-list"), + ("render_order_confirm", "ui://ecommerce-storefront/order-confirm"), + ] + ] + return create_tools_list_response(request_id, tools) + + elif method == "resources/list": + return { + "jsonrpc": "2.0", + "id": request_id, + "result": {"resources": RESOURCE_DEFINITIONS}, + } + + elif method == "resources/read": + uri = params.get("uri", "") + try: + html = _load_app_html(uri) + except (ValueError, FileNotFoundError) as e: + return create_error_response(request_id, -32602, str(e)) + return { + "jsonrpc": "2.0", + "id": request_id, + "result": { + "contents": [ + { + "uri": uri, + "mimeType": RESOURCE_MIME_TYPE, + "text": html, + } + ] + }, + } + + elif method == "tools/call": + tool_name = params.get("name") + arguments = params.get("arguments", {}) + + handler = TOOL_HANDLERS.get(tool_name) + if not handler: + return create_error_response(request_id, -32601, f"Unknown tool: {tool_name}") + + try: + result = handler(arguments) + except ValueError as e: + return create_error_response(request_id, -32602, str(e)) + + return {"jsonrpc": "2.0", "id": request_id, "result": result} + + else: + return create_error_response(request_id, -32601, f"Unknown method: {method}") + + except Exception as e: + return create_error_response( + request.get("id"), -32603, f"Internal error: {str(e)}" + ) + + +async def main(): + await handle_mcp_streaming(handle_request) + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/skills/developing/ecommerce-storefront/ecommerce_tools.json b/skills/developing/ecommerce-storefront/ecommerce_tools.json new file mode 100644 index 0000000..031998b --- /dev/null +++ b/skills/developing/ecommerce-storefront/ecommerce_tools.json @@ -0,0 +1,125 @@ +[ + { + "name": "render_product_list", + "description": "Render an interactive product card list. Users can browse products, select specifications (size/flavor/etc.), and add items to cart. Returns the user's selection via mcp-app-response.", + "inputSchema": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "Title displayed at the top of the product list" + }, + "products": { + "type": "array", + "description": "Array of product objects to display as cards", + "items": { + "type": "object", + "properties": { + "id": { "type": "string", "description": "Unique product identifier" }, + "name": { "type": "string", "description": "Product name" }, + "description": { "type": "string", "description": "Short product description" }, + "image": { "type": "string", "description": "Product image URL" }, + "price": { "type": "number", "description": "Base price" }, + "currency": { "type": "string", "description": "Currency symbol, default: '$'", "default": "$" }, + "specs": { + "type": "array", + "description": "Available specification groups (e.g. size, flavor)", + "items": { + "type": "object", + "properties": { + "label": { "type": "string", "description": "Spec group label, e.g. 'Size'" }, + "options": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { "type": "string", "description": "Option name, e.g. 'Large'" }, + "price_delta": { "type": "number", "description": "Price adjustment, default 0", "default": 0 } + }, + "required": ["name"] + } + } + }, + "required": ["label", "options"] + } + }, + "tags": { + "type": "array", + "items": { "type": "string" }, + "description": "Optional tags like 'Hot', 'New', 'Sale'" + } + }, + "required": ["id", "name", "price"] + } + } + }, + "required": ["title", "products"] + }, + "_meta": { + "ui": { + "resourceUri": "ui://ecommerce-storefront/product-list" + } + } + }, + { + "name": "render_order_confirm", + "description": "Render an order confirmation page with order details, total price, and a payment action button or QR code. Returns 'confirmed' or 'cancelled' via mcp-app-response.", + "inputSchema": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "Page title, e.g. 'Order Confirmation'" + }, + "order": { + "type": "object", + "description": "Order details", + "properties": { + "order_id": { "type": "string", "description": "Order ID" }, + "items": { + "type": "array", + "description": "Ordered items", + "items": { + "type": "object", + "properties": { + "name": { "type": "string", "description": "Product name with specs" }, + "quantity": { "type": "integer", "description": "Quantity", "default": 1 }, + "price": { "type": "number", "description": "Unit price" }, + "image": { "type": "string", "description": "Product image URL" } + }, + "required": ["name", "price"] + } + }, + "subtotal": { "type": "number", "description": "Subtotal before tax/fees" }, + "tax": { "type": "number", "description": "Tax amount", "default": 0 }, + "discount": { "type": "number", "description": "Discount amount", "default": 0 }, + "total": { "type": "number", "description": "Final total" }, + "currency": { "type": "string", "description": "Currency symbol", "default": "$" } + }, + "required": ["order_id", "items", "total"] + }, + "payment": { + "type": "object", + "description": "Payment configuration", + "properties": { + "method": { + "type": "string", + "enum": ["button", "qrcode", "link"], + "description": "Payment UI type: button (confirm button), qrcode (QR code image), link (external payment URL)" + }, + "qrcode_url": { "type": "string", "description": "QR code image URL (when method=qrcode)" }, + "payment_url": { "type": "string", "description": "External payment URL (when method=link)" }, + "button_text": { "type": "string", "description": "Payment button text, default: 'Confirm Payment'", "default": "Confirm Payment" } + }, + "required": ["method"] + } + }, + "required": ["title", "order", "payment"] + }, + "_meta": { + "ui": { + "resourceUri": "ui://ecommerce-storefront/order-confirm" + } + } + } +] diff --git a/skills/developing/ecommerce-storefront/hooks/ecommerce_guide.md b/skills/developing/ecommerce-storefront/hooks/ecommerce_guide.md new file mode 100644 index 0000000..609f5e8 --- /dev/null +++ b/skills/developing/ecommerce-storefront/hooks/ecommerce_guide.md @@ -0,0 +1,102 @@ +## E-Commerce Storefront Tools Usage Guide + +Two tools are available for e-commerce product browsing and ordering: +- `render_product_list` — Display interactive product cards with spec selection +- `render_order_confirm` — Display order confirmation with payment options + +--- + +### 1. render_product_list + +When to use: User wants to browse, search, or buy products. Show product cards with images, prices, and selectable specs (size, flavor, color, etc.). + +The user can select specs and click "Add to Cart" on any product. The selection is returned as an mcp-app-response containing: `{ product_id, product_name, selected_specs: {...}, final_price, quantity }`. + +``` +render_product_list( + title="Coffee Menu", + products=[ + { + "id": "latte-001", + "name": "Caffe Latte", + "description": "Rich espresso with steamed milk", + "image": "https://images.unsplash.com/photo-1572442388796-11668a67e53d?w=300&h=200&fit=crop", + "price": 4.50, + "currency": "$", + "specs": [ + { + "label": "Size", + "options": [ + {"name": "Small", "price_delta": 0}, + {"name": "Medium", "price_delta": 0.5}, + {"name": "Large", "price_delta": 1.0} + ] + }, + { + "label": "Milk", + "options": [ + {"name": "Whole Milk", "price_delta": 0}, + {"name": "Oat Milk", "price_delta": 0.6}, + {"name": "Almond Milk", "price_delta": 0.6} + ] + } + ], + "tags": ["Hot", "Popular"] + } + ] +) +``` + +After receiving the user's selection, proceed to generate an order and call `render_order_confirm`. + +--- + +### 2. render_order_confirm + +When to use: After the user selects a product and you have generated an order. + +Payment method options: +- `"button"` — Simple confirm/cancel buttons (default) +- `"qrcode"` — Show a QR code image for mobile payment +- `"link"` — Provide an external payment URL + +``` +render_order_confirm( + title="Order Confirmation", + order={ + "order_id": "ORD-20260522-001", + "items": [ + {"name": "Caffe Latte (Large, Oat Milk)", "quantity": 1, "price": 6.10} + ], + "subtotal": 6.10, + "tax": 0.49, + "total": 6.59, + "currency": "$" + }, + payment={ + "method": "button", + "button_text": "Confirm Payment" + } +) +``` + +The user response will be: `{ action: "confirm", order_id }` or `{ action: "cancel", order_id }`. + +--- + +### Workflow + +The typical e-commerce flow is: +1. User asks to buy something → call `render_product_list` +2. User selects a product → receive mcp-app-response with selection details +3. Generate order from selection → call `render_order_confirm` +4. User confirms or cancels → receive mcp-app-response with action +5. If confirmed → process payment / show success message +6. If cancelled → ask user what they'd like to do next + +### Tips +- Always include product images when available for better visual experience +- Use tags like "Hot", "New", "Sale" to highlight special products +- Keep product descriptions short (under 50 characters) +- Generate a unique order_id for each order +- Include tax/discount breakdowns when applicable for transparency diff --git a/skills/developing/ecommerce-storefront/hooks/pre_prompt.py b/skills/developing/ecommerce-storefront/hooks/pre_prompt.py new file mode 100644 index 0000000..9703836 --- /dev/null +++ b/skills/developing/ecommerce-storefront/hooks/pre_prompt.py @@ -0,0 +1,8 @@ +#!/usr/bin/env python3 +"""PrePrompt hook - inject ecommerce tool guide into system prompt.""" +import os + +guide_path = os.path.join(os.path.dirname(__file__), "ecommerce_guide.md") +if os.path.exists(guide_path): + with open(guide_path, "r", encoding="utf-8") as f: + print(f.read()) diff --git a/skills/developing/ecommerce-storefront/mcp_common.py b/skills/developing/ecommerce-storefront/mcp_common.py new file mode 100644 index 0000000..0baeb01 --- /dev/null +++ b/skills/developing/ecommerce-storefront/mcp_common.py @@ -0,0 +1,252 @@ +#!/usr/bin/env python3 +""" +Shared utility functions for the MCP server. +Provides common functionality for path handling, file validation, and request processing. +""" + +import json +import os +import sys +import asyncio +from typing import Any, Dict, List, Optional, Union +import re + +def get_allowed_directory(): + """Get the directory that is allowed to be accessed.""" + # Prefer dataset_dir passed through command-line arguments. + if len(sys.argv) > 1: + dataset_dir = sys.argv[1] + return os.path.abspath(dataset_dir) + + # Read the project data directory from the environment variable. + project_dir = os.getenv("PROJECT_DATA_DIR", "./projects/data") + return os.path.abspath(project_dir) + + +def resolve_file_path(file_path: str, default_subfolder: str = "default") -> str: + """ + Resolve a file path, supporting both folder/document.txt and document.txt formats. + + Args: + file_path: Input file path. + default_subfolder: Default subfolder name to use when only a filename is provided. + + Returns: + The resolved full file path. + """ + # If the path contains a folder separator, use it directly. + if '/' in file_path or '\\' in file_path: + clean_path = file_path.replace('\\', '/') + + # Remove the projects/ prefix if it exists. + if clean_path.startswith('projects/'): + clean_path = clean_path[9:] # Remove the 'projects/' prefix. + elif clean_path.startswith('./projects/'): + clean_path = clean_path[11:] # Remove the './projects/' prefix. + else: + # If only a filename is provided, add the default subfolder. + clean_path = f"{default_subfolder}/{file_path}" + + # Get the allowed directory. + project_data_dir = get_allowed_directory() + + # Try to locate the file directly under the project directory. + full_path = os.path.join(project_data_dir, clean_path.lstrip('./')) + if os.path.exists(full_path): + return full_path + + # If the direct path does not exist, try a recursive search. + found = find_file_in_project(clean_path, project_data_dir) + if found: + return found + + # If this is a bare filename and it was not found under the default subfolder, + # try looking in the project root. + if '/' not in file_path and '\\' not in file_path: + root_path = os.path.join(project_data_dir, file_path) + if os.path.exists(root_path): + return root_path + + raise FileNotFoundError(f"File not found: {file_path} (searched in {project_data_dir})") + + +def find_file_in_project(filename: str, project_dir: str) -> Optional[str]: + """Recursively search for a file inside the project directory.""" + # If filename includes a path, only search within the specified path. + if '/' in filename: + parts = filename.split('/') + target_file = parts[-1] + search_dir = os.path.join(project_dir, *parts[:-1]) + + if os.path.exists(search_dir): + target_path = os.path.join(search_dir, target_file) + if os.path.exists(target_path): + return target_path + else: + # For a bare filename, recursively search the whole project directory. + for root, dirs, files in os.walk(project_dir): + if filename in files: + return os.path.join(root, filename) + return None + + +def load_tools_from_json(tools_file_name: str) -> List[Dict[str, Any]]: + """Load tool definitions from a JSON file.""" + try: + tools_file = os.path.join(os.path.dirname(__file__), tools_file_name) + if os.path.exists(tools_file): + with open(tools_file, 'r', encoding='utf-8') as f: + return json.load(f) + else: + # If the JSON file does not exist, use the default definitions. + return [] + except Exception as e: + print(f"Warning: Unable to load tool definition JSON file: {str(e)}") + return [] + + +def create_error_response(request_id: Any, code: int, message: str) -> Dict[str, Any]: + """Create a standardized error response.""" + return { + "jsonrpc": "2.0", + "id": request_id, + "error": { + "code": code, + "message": message + } + } + + +def create_success_response(request_id: Any, result: Any) -> Dict[str, Any]: + """Create a standardized success response.""" + return { + "jsonrpc": "2.0", + "id": request_id, + "result": result + } + + +def create_initialize_response(request_id: Any, server_name: str, server_version: str = "1.0.0") -> Dict[str, Any]: + """Create a standardized initialize response.""" + return { + "jsonrpc": "2.0", + "id": request_id, + "result": { + "protocolVersion": "2024-11-05", + "capabilities": { + "tools": {} + }, + "serverInfo": { + "name": server_name, + "version": server_version + } + } + } + + +def create_ping_response(request_id: Any) -> Dict[str, Any]: + """Create a standardized ping response.""" + return { + "jsonrpc": "2.0", + "id": request_id, + "result": { + "pong": True + } + } + + +def create_tools_list_response(request_id: Any, tools: List[Dict[str, Any]]) -> Dict[str, Any]: + """Create a standardized tools/list response.""" + return { + "jsonrpc": "2.0", + "id": request_id, + "result": { + "tools": tools + } + } + + +def is_regex_pattern(pattern: str) -> bool: + """Check whether a string should be treated as a regular expression pattern.""" + # Check the /pattern/ format. + if pattern.startswith('/') and pattern.endswith('/') and len(pattern) > 2: + return True + + # Check the r"pattern" or r'pattern' format. + if pattern.startswith(('r"', "r'")) and pattern.endswith(('"', "'")) and len(pattern) > 3: + return True + + # Check whether it contains regex metacharacters. + regex_chars = {'*', '+', '?', '|', '(', ')', '[', ']', '{', '}', '^', '$', '\\', '.'} + return any(char in pattern for char in regex_chars) + + +def compile_pattern(pattern: str) -> Union[re.Pattern, str, None]: + """Compile a regex pattern, or return the original string if it is not regex.""" + if not is_regex_pattern(pattern): + return pattern + + try: + # Handle the /pattern/ format. + if pattern.startswith('/') and pattern.endswith('/'): + regex_body = pattern[1:-1] + return re.compile(regex_body) + + # Handle the r"pattern" or r'pattern' format. + if pattern.startswith(('r"', "r'")) and pattern.endswith(('"', "'")): + regex_body = pattern[2:-1] + return re.compile(regex_body) + + # Directly compile strings that contain regex metacharacters. + return re.compile(pattern) + except re.error as e: + # If compilation fails, return None to indicate an invalid regex. + print(f"Warning: Regular expression '{pattern}' compilation failed: {e}") + return None + + +async def handle_mcp_streaming(request_handler): + """Handle the standard main loop for MCP requests.""" + try: + while True: + # Read from stdin + line = await asyncio.get_event_loop().run_in_executor(None, sys.stdin.readline) + if not line: + break + + line = line.strip() + if not line: + continue + + try: + request = json.loads(line) + response = await request_handler(request) + + # Write to stdout + sys.stdout.write(json.dumps(response, ensure_ascii=False) + "\n") + sys.stdout.flush() + + except json.JSONDecodeError: + error_response = { + "jsonrpc": "2.0", + "error": { + "code": -32700, + "message": "Parse error" + } + } + sys.stdout.write(json.dumps(error_response, ensure_ascii=False) + "\n") + sys.stdout.flush() + + except Exception as e: + error_response = { + "jsonrpc": "2.0", + "error": { + "code": -32603, + "message": f"Internal error: {str(e)}" + } + } + sys.stdout.write(json.dumps(error_response, ensure_ascii=False) + "\n") + sys.stdout.flush() + + except KeyboardInterrupt: + pass diff --git a/skills/developing/managing-scripts/SKILL.md b/skills/developing/managing-scripts/SKILL.md index 2288722..05f5ace 100644 --- a/skills/developing/managing-scripts/SKILL.md +++ b/skills/developing/managing-scripts/SKILL.md @@ -1,6 +1,7 @@ --- name: managing-scripts description: Manages shared scripts repository for reusable data analysis tools. Check scripts/README.md before writing, design generalized scripts with parameters, and keep documentation in sync. +category: Data & Retrieval --- # Managing Scripts diff --git a/skills/developing/nfc-medicine-lookup/SKILL.md b/skills/developing/nfc-medicine-lookup/SKILL.md new file mode 100644 index 0000000..451464e --- /dev/null +++ b/skills/developing/nfc-medicine-lookup/SKILL.md @@ -0,0 +1,180 @@ +--- +name: nfc-medicine-lookup +description: 药品检索技能，通过NFC芯片ID或药品名称查询药品信息。当用户提交NFC芯片ID、扫描药品标签、提到药品名称想了解用法、或提到"NFC"+"药"相关词汇时使用此技能。以语音助手身份向老人介绍药名、用途和用法用量。 +category: Developer Tools +--- + +# NFC 药品检索 + +## Skill Structure + +``` +nfc-medicine-lookup/ +├── SKILL.md # Core instruction file (this file) +├── skill.yaml # Skill metadata +├── scripts/ +│ └── nfc_medicine_lookup.py # Main lookup script +``` + +## Overview + +通过 **NFC芯片ID** 或 **药品名称** 查询对应的药品信息。本技能面向老年用户，以**语音助手**的身份，用简洁、亲切、易懂的语言告知： + +1. 药品名称 +2. 这个药是干什么的 +3. 具体用法用量 +4. 注意事项 + +## 查询方式 + +支持两种查询入口，**至少提供一种**即可： + +| Parameter | Description | Type | Required | +|-----------|-------------|------|----------| +| **nfc_id** | NFC芯片ID（如 100000） | string | 二选一 | +| **name** | 药品名称，支持模糊匹配（如"阿莫西林"） | string | 二选一 | + +## Quick Start + +```bash +# 方式一：通过NFC ID查询 +scripts/nfc_medicine_lookup.py --nfc-id "100000" + +# 方式二：通过药品名称查询 +scripts/nfc_medicine_lookup.py --name "阿莫西林" +``` + +## 查询流程 + +请严格按照以下流程执行： + +### Step 1: 本地数据库查询 + +运行脚本查询本地药品库： + +```bash +# 有NFC ID时 +scripts/nfc_medicine_lookup.py --nfc-id "{nfc_id}" + +# 有药品名称时 +scripts/nfc_medicine_lookup.py --name "{药品名称}" +``` + +### Step 2: 判断查询结果 + +- **查到了** → 跳到 Step 4（语音回复） +- **输出包含 `NOT_FOUND`** → 进入 Step 3（网络搜索兜底） + +### Step 3: 网络搜索兜底（本地未命中时） + +当本地药品库中查不到时，使用 WebSearch 工具搜索该药品的信息： + +``` +WebSearch: "{药品名称} 用法用量 注意事项 说明书" +``` + +从搜索结果中提取以下信息： +- 药品全称 +- 药品类别 +- 主要功效/适应症 +- 用法用量 +- 关键注意事项 + +**重要**：网络搜索到的信息，回复时必须在末尾加上免责提醒： +> 以上信息来自网络搜索，仅供参考。具体用药请遵医嘱，或咨询药师确认。 + +### Step 4: 以语音助手身份回复 + +无论信息来自本地库还是网络搜索，都按照下方「语音助手回复规范」进行回复。 + +## 语音助手回复规范 + +查询到药品后，你需要以**关怀老人的语音助手**身份回复。请遵循以下规范： + +### 回复模板 + +``` +您好，这个药叫**{药品名称}**，属于{药品类别}。 + +**它的作用是**：{简洁描述药品用途} + +**怎么吃**：{用法用量，用口语化表达} + +**要注意**：{关键注意事项} + +如果有任何不舒服，一定要及时告诉家人或去看医生哦。 +``` + +### 语言风格要求 + +- 使用口语化、亲切的表达，像家人在旁边叮嘱一样 +- 避免专业术语，用老人能听懂的话 +- 关键信息（药名、用量）要**重点强调** +- 结尾加上一句关心的话 +- 整段回复控制在150字以内，适合语音播报 + +### 示例回复 + +**示例1：NFC ID查询命中** + +输入: NFC ID = 100000 + +> 您好，这个药叫**阿莫西林胶囊**，是一种消炎药。 +> +> **它的作用是**：用来治疗细菌引起的感染，比如嗓子发炎、咳嗽有痰这些情况。 +> +> **怎么吃**：每次吃1粒，每天吃3到4次，每次间隔6到8个小时。记得在饭后吃，用温水把整粒药吞下去，不要嚼碎。 +> +> **要注意**：如果您对青霉素过敏，这个药就不能吃。另外，医生让吃几天就吃几天，不要觉得好了就自己停药。 +> +> 如果吃药后有任何不舒服，一定要及时告诉家人或去看医生哦。 + +**示例2：药品名称查询命中** + +输入: name = "布洛芬" + +> 您好，这个药叫**布洛芬缓释胶囊**，是一种止痛退烧药。 +> +> **它的作用是**：用来缓解头痛、牙痛、关节痛，感冒发烧也可以吃。 +> +> **怎么吃**：每次吃1粒，早晚各一次，饭后用温水整粒吞下去。 +> +> **要注意**：有胃病的人要小心，连续吃不要超过5天，要是还疼就去看医生。 +> +> 如果吃药后有任何不舒服，一定要及时告诉家人或去看医生哦。 + +**示例3：本地未命中，网络搜索兜底** + +输入: name = "氯雷他定"（本地库没有） + +> 您好，这个药叫**氯雷他定片**，是一种抗过敏药。 +> +> **它的作用是**：用来缓解过敏引起的打喷嚏、流鼻涕、皮肤发痒这些症状。 +> +> **怎么吃**：每次吃1片，每天吃1次就行，饭前饭后都可以。 +> +> **要注意**：吃了这个药可能会有点犯困，吃药后尽量别开车。 +> +> 以上信息来自网络搜索，仅供参考。具体用药请遵医嘱，或咨询药师确认。 +> +> 如果有任何不舒服，一定要及时告诉家人或去看医生哦。 + +## NFC ID 药品对照表 + +| NFC ID | 药品名称 | 类别 | +|--------|---------|------| +| 100000 | 阿莫西林胶囊 | 抗生素 | +| 100001 | 硝苯地平控释片 | 降压药 | +| 100002 | 二甲双胍片 | 降糖药 | +| 100003 | 阿司匹林肠溶片 | 抗血小板药 | +| 100004 | 辛伐他汀片 | 降脂药 | +| 100005 | 氨氯地平片 | 降压药 | +| 100006 | 美托洛尔缓释片 | 降压药/心率控制 | +| 100007 | 奥美拉唑肠溶胶囊 | 胃药 | +| 100008 | 氯吡格雷片 | 抗血小板药 | +| 100009 | 螺内酯片 | 利尿药 | +| 100010 | 复方丹参滴丸 | 心血管中成药 | +| 100011 | 蒙脱石散 | 止泻药 | +| 100012 | 布洛芬缓释胶囊 | 解热镇痛药 | +| 100013 | 碳酸钙D3片 | 补钙药 | +| 100014 | 甲钴胺片 | 营养神经药 | diff --git a/skills/developing/novare-context/.claude-plugin/plugin.json b/skills/developing/novare-context/.claude-plugin/plugin.json index 01f0307..dd093df 100644 --- a/skills/developing/novare-context/.claude-plugin/plugin.json +++ b/skills/developing/novare-context/.claude-plugin/plugin.json @@ -8,5 +8,6 @@ "command": "python hooks/pre_prompt.py" } ] - } + }, + "category": "Developer Tools" } diff --git a/skills/developing/pmda-drug-info/.claude-plugin/plugin.json b/skills/developing/pmda-drug-info/.claude-plugin/plugin.json index aa1055c..c709e99 100644 --- a/skills/developing/pmda-drug-info/.claude-plugin/plugin.json +++ b/skills/developing/pmda-drug-info/.claude-plugin/plugin.json @@ -17,5 +17,6 @@ "./pmda_server.py" ] } - } + }, + "category": "Developer Tools" } diff --git a/skills/developing/ppt-outline/SKILL.md b/skills/developing/ppt-outline/SKILL.md new file mode 100644 index 0000000..01940cc --- /dev/null +++ b/skills/developing/ppt-outline/SKILL.md @@ -0,0 +1,57 @@ +--- +name: ppt-outline +description: "PPT outline and HTML presentation generator. PPT大纲、PPT模板、演示文稿、presentation、PowerPoint、幻灯片、slides、HTML演示文稿、HTML slides、浏览器演示、商业路演、pitch deck、BP商业计划书、business plan、工作汇报PPT、培训课件、课件大纲、产品介绍PPT、产品发布、keynote、演讲稿、述职PPT、答辩PPT、竞品分析PPT、毕业答辩、论文答辩、项目复盘、迭代复盘。Generate PPT outlines and standalone HTML presentations (open directly in browser, no dependencies). Use when: (1) creating PPT/presentation outlines, (2) building pitch deck/BP structures, (3) preparing work report slides, (4) designing training course outlines, (5) creating thesis defense PPT outlines, (6) building project review/retrospective PPTs, (7) generating HTML slide decks for browser-based presentations, (8) any PowerPoint/Keynote/Google Slides planning. 适用场景：做PPT大纲、写路演BP、汇报PPT结构、培训课件大纲、毕业答辩PPT、项目复盘PPT、述职答辩PPT、生成HTML演示文稿（浏览器直接打开，支持dark/light/tech/minimal四种风格）。" +category: Document Processing +--- + +# ppt-outline + +PPT大纲和演示文稿结构生成器。商业路演、工作汇报、产品介绍、培训课件。 + +## 为什么用这个 Skill？ / Why This Skill? + +- **场景化大纲**：路演BP有固定结构（痛点→方案→市场→团队→融资），汇报有汇报的逻辑，不是万能模板 +- **每页要点**：不只给标题，每页都有2-4个要点提示，拿来直接填内容 +- **页数控制**：`--slides 10` 控制总页数，按需伸缩 +- Compared to asking AI directly: scenario-specific slide structures (pitch vs report vs training), per-slide talking points, and slide count control + +## Usage + +Run the script at `scripts/ppt.sh`: + +| Command | Description | +|---------|-------------| +| `scripts/ppt.sh outline "主题" [--slides 10]` | 生成PPT大纲（每页标题+要点） | +| `scripts/ppt.sh pitch "项目名"` | 商业路演BP大纲 | +| `scripts/ppt.sh report "汇报主题"` | 工作汇报PPT大纲 | +| `scripts/ppt.sh training "课程主题"` | 培训课件大纲 | +| `scripts/ppt.sh defense "论文题目"` | 毕业答辩PPT大纲 | +| `scripts/ppt.sh review "项目名"` | 项目复盘PPT大纲 | +| `scripts/ppt.sh html "主题" [--style S]` | 生成HTML演示文稿（浏览器直接打开） | +| `scripts/ppt.sh help` | 显示帮助信息 | + +## Examples + +```bash +# 通用PPT大纲（指定页数） +bash scripts/ppt.sh outline "人工智能在医疗领域的应用" --slides 12 + +# 商业路演 +bash scripts/ppt.sh pitch "智能客服SaaS平台" + +# 工作汇报 +bash scripts/ppt.sh report "2024年Q4部门工作总结" + +# 培训课件 +bash scripts/ppt.sh training "新员工入职培训-公司文化" + +# 毕业答辩 +bash scripts/ppt.sh defense "社交媒体对消费行为的影响研究" + +# 项目复盘 +bash scripts/ppt.sh review "双十一大促活动" + +# 生成HTML演示文稿（浏览器直接打开） +bash scripts/ppt.sh html "AI在医疗的应用" --style tech +# 支持风格：dark(默认深色科技) | light(白色商务) | tech(渐变科技) | minimal(极简) +``` diff --git a/skills/developing/rag-retrieve-cli/SKILL.md b/skills/developing/rag-retrieve-cli/SKILL.md index 4584796..f5a7a1a 100644 --- a/skills/developing/rag-retrieve-cli/SKILL.md +++ b/skills/developing/rag-retrieve-cli/SKILL.md @@ -1,6 +1,7 @@ --- name: rag-retrieve description: RAG retrieval skill for querying and retrieving relevant documents from knowledge base. Use this skill when users need to search documentation, retrieve knowledge base articles, or get context from a vector database. Supports semantic search with configurable top-k results. +category: Data & Retrieval --- # RAG Retrieve diff --git a/skills/developing/rag-retrieve-no-citation/.claude-plugin/plugin.json b/skills/developing/rag-retrieve-no-citation/.claude-plugin/plugin.json index 64100ad..5cfef81 100644 --- a/skills/developing/rag-retrieve-no-citation/.claude-plugin/plugin.json +++ b/skills/developing/rag-retrieve-no-citation/.claude-plugin/plugin.json @@ -18,5 +18,6 @@ "{bot_id}" ] } - } + }, + "category": "Data & Retrieval" } diff --git a/skills/developing/static-hosting/SKILL.md b/skills/developing/static-hosting/SKILL.md index c208a00..f664003 100644 --- a/skills/developing/static-hosting/SKILL.md +++ b/skills/developing/static-hosting/SKILL.md @@ -1,6 +1,7 @@ --- name: static-hosting description: Serve static HTML/CSS/JS/images from robot project directories via the built-in FastAPI static file server. Use when generating web pages, reports, or interactive content for a bot. +category: Web Services --- # Static Hosting diff --git a/skills/developing/user-context-loader/.claude-plugin/plugin.json b/skills/developing/user-context-loader/.claude-plugin/plugin.json index 67d3a85..6caddd1 100644 --- a/skills/developing/user-context-loader/.claude-plugin/plugin.json +++ b/skills/developing/user-context-loader/.claude-plugin/plugin.json @@ -30,8 +30,11 @@ "mcpServers": { "user-context-example": { "command": "echo", - "args": ["Example MCP server for user context loader"], + "args": [ + "Example MCP server for user context loader" + ], "comment": "这是一个示例 MCP 配置，实际使用时替换为真实的 MCP 服务器" } - } + }, + "category": "Developer Tools" } diff --git a/skills/developing/z-card-image/SKILL.md b/skills/developing/z-card-image/SKILL.md new file mode 100644 index 0000000..4f96250 --- /dev/null +++ b/skills/developing/z-card-image/SKILL.md @@ -0,0 +1,91 @@ +--- +name: z-card-image +version: 1.1.0 +description: 生成配图、封面图、卡片图、文字海报、公众号文章封面图、微信公众号头图、X 风格帖子分享图、帖子长图、社媒帖子长图。适用于帖子类型数据、post data、social posts、tweet/thread、转发推文、转发帖子、小绿书配图、图片封面、card image。 +metadata: + openclaw: + requires: + bins: + - python3 + - google-chrome +category: Creative Generation +--- + +# z-card-image + +将用户提供的文案渲染成 PNG 卡片图。 +支持短文案封面图、长文分页图、X 风格帖子分享长图，以及公众号文章封面图。只要输入是“帖子类型数据”并希望导出成 X 风格长图，都应走 `x-like-posts`。 + +## 环境要求 + +- Python 3 +- Google Chrome（macOS：`/Applications/Google Chrome.app`；Linux：`chromium` 需修改脚本路径） + +## 执行流程 + +0. **环境提示**（用户触发时检测一次，有问题给提示，不中止流程）： + - `python3 --version` → 失败则告知：「⚠️ 未检测到 Python 3，渲染可能失败」 + - 检查 Chrome 路径 → 失败则提示安装 + +1. **识别场景**： + - 短文案封面图 → `poster-3-4` + - 长文分页图 → `article-3-4` + - X 风格帖子分享图 / 帖子长图 / 帖子类型数据 → `x-like-posts` + - 公众号文章封面图 → `wechat-cover-split` +2. **查模板规则**：根据模板在「模板索引」中找到对应规范文档，读取后按其规则处理文案和参数。**如用户要求高亮：整行用 `--hl1/hl2/hl3`，按词用 `--highlight-words`（逗号分隔），两者可同时使用，不能忽略** +3. **确认署名**：先询问用户底部署名文字（`--footer`），如：「请告诉我你的署名，例如"公众号 · 你的名字"」。用户未回答或要求跳过时，使用脚本默认值。 +4. **确定配色**：拿到署名后，再确定配色方案： + - 用户提到"小红书配图" → 推荐方案 B（热情红） + - 用户提到"小绿书"或"公众号配图" → 推荐方案 A（清新绿） + - 用户提到"推特长图"/"X 风格" → 使用 `render_x_like_posts.py` 自带默认值（Twitter 蓝白灰） + - 其他场景 → 询问用户选择下方配色方案： + + | 方案 | 风格 | `--bg` | `--highlight` | 适用场景 | + |------|------|--------|--------------|---------| + | A. 清新绿 | 公众号/小绿书 | `#e6f5ef` | `#22a854` | 公众号配图、小绿书 | + | B. 热情红 | 小红书 | `#fdecea` | `#e53935` | 小红书配图 | + | C. 科技蓝 | 知乎/技术 | `#e8f4fd` | `#1976d2` | 技术文章、知乎 | + | D. 暖橙黄 | 活力/营销 | `#fff8e1` | `#f57c00` | 活动海报、营销 | + | E. 优雅紫 | 时尚/文艺 | `#f3e5f5` | `#7b1fa2` | 文艺、时尚类 | + | F. 经典黑白 | 极简 | `#f5f5f5` | `#212121` | 极简风格 | + + 用户也可自定义 `--bg` 和 `--highlight`。用户未回答或要求跳过时，使用脚本默认值，不做额外覆盖。 +5. **渲染输出**： + - `poster-3-4` → 执行 `render_card.py` + - `article-3-4` → 执行 `render_article.py` + - `x-like-posts` → 执行 `render_x_like_posts.py` + - `wechat-cover-split` → 执行 `render_card.py` + - 默认 `--out` 填 `tmp/...png`；如用户指定导出位置，可直接传绝对路径或相对路径 +6. **输出产物**：生成 PNG 到指定路径，供后续发送、裁切或复用；如需给外部工具上传，仍应避免写入系统 `/tmp/` + +## x-like-posts 导航 + +`x-like-posts` 用于“帖子类型数据 → X 风格分享长图”。 + +当命中这条路线时，继续读取： + +- [references/x-like-posts.md](references/x-like-posts.md)：输入 JSON 格式、可显示字段、时间规则、导出规则 +- [references/tweet-thread.md](references/tweet-thread.md)：旧命名兼容说明 + +## 输入校验 + +- **比例不存在**：驳回请求，告知当前支持的比例列表，询问是否新增模板 +- **文案超出模板字数上限**：先自动拆分/缩写后再渲染，不要直接塞入 +- **帖子过多**：按规范拆成多张 `Part 1 / Part 2`，不要把超长内容强行塞进一张 +- **公众号封面标题过长**：先压缩成 2~3 行短标题，再渲染，不能把完整长标题硬塞进模板 + +## 模板索引 + +| 模板名 | 比例 | 尺寸 | 用途 | 规范文档 | +|--------|------|------|------|---------| +| `poster-3-4` | 3:4 | 900×1200 | 文字海报（金句/大字报/封面） | [references/poster-3-4.md](references/poster-3-4.md) | +| `article-3-4` | 3:4 | 900×1200 | 长文分页卡片 | [references/article-3-4.md](references/article-3-4.md) | +| `x-like-posts` | 自适应长图 | 900px 宽 | X 风格帖子分享长图 | [references/x-like-posts.md](references/x-like-posts.md) | +| `wechat-cover-split` | 335:100 | 1340×400 | 公众号文章封面长条图（左标题右 icon） | [references/wechat-cover-split.md](references/wechat-cover-split.md) | + +## 新增模板 + +1. 新建 `assets/templates/.html` +2. 在 `render_card.py` 的 `size_map` 里注册尺寸 +3. 在上方模板索引中添加一行 +4. 创建对应 `references/.md`，记录该模板的参数、字数上限、配图选取规则 diff --git a/skills/onprem/kfs-answer/SKILL.md b/skills/onprem/kfs-answer/SKILL.md index 39ab748..24871e2 100644 --- a/skills/onprem/kfs-answer/SKILL.md +++ b/skills/onprem/kfs-answer/SKILL.md @@ -1,6 +1,7 @@ --- name: kfs-answer description: Primary skill for answering ALL questions about the datasets knowledge base. Search files, run queries (SQL / markdown), and return answers with citations. MUST be used first for any data-related question. +category: Data & Retrieval --- # kfs-answer diff --git a/skills/onprem/rag-retrieve-only/.claude-plugin/plugin.json b/skills/onprem/rag-retrieve-only/.claude-plugin/plugin.json index a1a38c5..fe0846f 100644 --- a/skills/onprem/rag-retrieve-only/.claude-plugin/plugin.json +++ b/skills/onprem/rag-retrieve-only/.claude-plugin/plugin.json @@ -18,5 +18,6 @@ "{bot_id}" ] } - } + }, + "category": "Data & Retrieval" } diff --git a/skills/support/board-meeting-pack-helper/SKILL.md b/skills/support/board-meeting-pack-helper/SKILL.md index 6ccbeb5..34c354c 100644 --- a/skills/support/board-meeting-pack-helper/SKILL.md +++ b/skills/support/board-meeting-pack-helper/SKILL.md @@ -1,6 +1,7 @@ --- name: board-meeting-pack-helper description: Assemble board-meeting materials into a coherent pack with agenda logic, board-level KPIs, strategic risks, governance context, and decision-ready content. Use this whenever users ask for board materials, board pack, board meeting agenda, governance updates, director pre-read, 取締役会資料, or resolution-ready content for executive or board review; use it for board-level governance materials, not for generic executive one-pagers. +category: Writing & Reporting --- # Board Meeting Pack Helper diff --git a/skills/support/customer-reply-tone/SKILL.md b/skills/support/customer-reply-tone/SKILL.md index 3bbcf51..3dc315a 100644 --- a/skills/support/customer-reply-tone/SKILL.md +++ b/skills/support/customer-reply-tone/SKILL.md @@ -1,6 +1,7 @@ --- name: customer-reply-tone description: Rewrite customer-facing replies in the right tone while preserving factual accuracy, accountability, and clear next steps across sensitive support, delivery, and account situations. Use this whenever users ask to soften, professionalize, de-escalate, polish, or reframe a customer email or chat response, including complaint reply, support response polish, or クレーム返信; use it for reply rewriting and de-escalation, not for sales follow-up or general Japanese business writing. +category: Writing & Reporting --- # Customer Reply Tone diff --git a/skills/support/exec-brief-1pager/SKILL.md b/skills/support/exec-brief-1pager/SKILL.md index 3f75ed1..c550382 100644 --- a/skills/support/exec-brief-1pager/SKILL.md +++ b/skills/support/exec-brief-1pager/SKILL.md @@ -1,6 +1,7 @@ --- name: exec-brief-1pager description: Turn complex business, product, and operational topics into a one-page executive brief with decision-ready insights, options, and recommended actions. Use this whenever users ask for an executive summary, leadership brief, one-pager, decision memo, CEO brief, or key points at a glance for senior leadership; use it for one-page decision support, not for recurring status updates or board meeting packs. +category: Writing & Reporting --- # Exec Brief 1Pager diff --git a/skills/support/incident-postmortem-ja/SKILL.md b/skills/support/incident-postmortem-ja/SKILL.md index b082f47..a979554 100644 --- a/skills/support/incident-postmortem-ja/SKILL.md +++ b/skills/support/incident-postmortem-ja/SKILL.md @@ -1,6 +1,7 @@ --- name: incident-postmortem-ja description: Create structured postmortems and 障害報告書 for incidents, outages, and service failures with clear timelines, root-cause analysis, and preventive actions. Use this whenever users ask for an incident report, postmortem, RCA, incident review, 障害報告, 障害報告書, 振り返り, or 再発防止計画 focused on system and process improvement; use it for formal incident analysis, not for routine status updates or personal blame. +category: Writing & Reporting --- # Incident Postmortem JA diff --git a/skills/support/japan-compliance-checker/SKILL.md b/skills/support/japan-compliance-checker/SKILL.md index 9284e85..6f659d6 100644 --- a/skills/support/japan-compliance-checker/SKILL.md +++ b/skills/support/japan-compliance-checker/SKILL.md @@ -1,6 +1,7 @@ --- name: japan-compliance-checker description: Review Japan-specific compliance risks in business text, campaign copy, contracts, and operating processes with clear, practical screening guidance. Use this whenever users ask for Japan compliance review, legal review, regulatory check, 法務チェック, コンプラ確認, 契約レビュー, or 広告審査 within the v1 scope of APPI, 景品表示法, and 下請法; use it for risk screening rather than drafting, anonymization, or legal advice. +category: Compliance & Security --- # Japan Compliance Checker diff --git a/skills/support/japanese-business-writer/SKILL.md b/skills/support/japanese-business-writer/SKILL.md index 217179a..ad0f578 100644 --- a/skills/support/japanese-business-writer/SKILL.md +++ b/skills/support/japanese-business-writer/SKILL.md @@ -1,6 +1,7 @@ --- name: japanese-business-writer description: Draft and polish formal Japanese business writing for emails, notices, request letters, cover notes, and workplace communication with clear structure and appropriate 敬語. Use this whenever users ask for Japanese business writing, formal JP writing, 敬語 polishing, 文面添削, 依頼メール, 案内文, 送付状, or 社内通知; use it for writing quality and business tone, not for compliance review or complaint de-escalation. +category: Writing & Reporting --- # Japanese Business Writer diff --git a/skills/support/japanese-pii-redactor/SKILL.md b/skills/support/japanese-pii-redactor/SKILL.md index efb2767..f4e3e6e 100644 --- a/skills/support/japanese-pii-redactor/SKILL.md +++ b/skills/support/japanese-pii-redactor/SKILL.md @@ -1,6 +1,7 @@ --- name: japanese-pii-redactor description: Redact, anonymize, and de-identify personal information in Japanese-language or mixed-language text and tabular data while preserving analytical usefulness. Use this whenever users ask for PII redaction, PII scrub, de-identification, 個人情報匿名化, 匿名加工, 仮名化, 秘匿化, or マスキング; use it for executing anonymization rules, not for legal interpretation or general writing polish. +category: Compliance & Security --- # Japanese PII Redactor diff --git a/skills/support/kfs-answer/SKILL.md b/skills/support/kfs-answer/SKILL.md index 39ab748..24871e2 100644 --- a/skills/support/kfs-answer/SKILL.md +++ b/skills/support/kfs-answer/SKILL.md @@ -1,6 +1,7 @@ --- name: kfs-answer description: Primary skill for answering ALL questions about the datasets knowledge base. Search files, run queries (SQL / markdown), and return answers with citations. MUST be used first for any data-related question. +category: Data & Retrieval --- # kfs-answer diff --git a/skills/support/meeting-minutes-action/SKILL.md b/skills/support/meeting-minutes-action/SKILL.md index ee56b76..0cb36c5 100644 --- a/skills/support/meeting-minutes-action/SKILL.md +++ b/skills/support/meeting-minutes-action/SKILL.md @@ -1,6 +1,7 @@ --- name: meeting-minutes-action description: Turn raw meeting notes, transcripts, and discussion logs into structured meeting minutes, decision summaries, and follow-up action items with owners and deadlines. Use this whenever users ask for meeting minutes, meeting summary, 議事録, 議事メモ整理, 打合せ記録, 決定事項整理, or follow-up tasks from a single meeting; use it for minutes and action tracking, not for periodic project or leadership status reporting. +category: Writing & Reporting --- # Meeting Minutes Action diff --git a/skills/support/proposal-rfp-writer/SKILL.md b/skills/support/proposal-rfp-writer/SKILL.md index 15d6784..316f43c 100644 --- a/skills/support/proposal-rfp-writer/SKILL.md +++ b/skills/support/proposal-rfp-writer/SKILL.md @@ -1,6 +1,7 @@ --- name: proposal-rfp-writer description: Create structured, client-ready proposal and RFP response drafts that map requirements to solutions, differentiate clearly, and stay easy for evaluators to review. Use this whenever users ask to respond to an RFP, RFQ, bid request, tender, vendor questionnaire, procurement questionnaire, 提案書, bid response, or tender response; use it for evaluator-facing requirement mapping, not for quotes, SOWs, or delivery acceptance terms. +category: Writing & Reporting --- # Proposal RFP Writer diff --git a/skills/support/quotation-sow-drafter/SKILL.md b/skills/support/quotation-sow-drafter/SKILL.md index f79f526..41ab513 100644 --- a/skills/support/quotation-sow-drafter/SKILL.md +++ b/skills/support/quotation-sow-drafter/SKILL.md @@ -1,6 +1,7 @@ --- name: quotation-sow-drafter description: Draft coherent quotations and statements of work that align scope, deliverables, milestones, assumptions, and commercial terms without blurring commitments and estimates. Use this whenever users ask for a quote, quote draft, pricing sheet, SOW, scope document, work order, implementation plan draft, 見積書, or 作業範囲定義; use it for pricing, scope, milestones, and acceptance terms, not for RFP questionnaires or evaluator-facing bid responses. +category: Writing & Reporting --- # Quotation SOW Drafter diff --git a/skills/support/rag-retrieve-only/.claude-plugin/plugin.json b/skills/support/rag-retrieve-only/.claude-plugin/plugin.json index a1a38c5..fe0846f 100644 --- a/skills/support/rag-retrieve-only/.claude-plugin/plugin.json +++ b/skills/support/rag-retrieve-only/.claude-plugin/plugin.json @@ -18,5 +18,6 @@ "{bot_id}" ] } - } + }, + "category": "Data & Retrieval" } diff --git a/skills/support/sales-followup/SKILL.md b/skills/support/sales-followup/SKILL.md index 7e2a543..e46ab55 100644 --- a/skills/support/sales-followup/SKILL.md +++ b/skills/support/sales-followup/SKILL.md @@ -1,6 +1,7 @@ --- name: sales-followup description: Draft sales follow-up messages that move deals forward with the right mix of urgency, clarity, and low-friction next steps after calls, demos, proposals, and stalled threads. Use this whenever users ask to follow up, re-engage, nudge, check in, request a decision, client follow-up, 商談フォロー, 提案後フォロー, or 検討状況確認 after a demo, quote, meeting, or proposal; use it for sales progression, not for complaint handling or tone-only rewrites. +category: Writing & Reporting --- # Sales Follow-Up diff --git a/skills/support/stakeholder-update/SKILL.md b/skills/support/stakeholder-update/SKILL.md index cb263d7..0ad21f9 100644 --- a/skills/support/stakeholder-update/SKILL.md +++ b/skills/support/stakeholder-update/SKILL.md @@ -1,6 +1,7 @@ --- name: stakeholder-update description: Produce concise stakeholder updates that summarize status, progress, risks, decisions, and next actions in a format leaders and cross-functional teams can scan quickly. Use this whenever users ask for a status update, progress update, weekly update, monthly update, leadership summary, project brief, 経営報告, or エスカレーション共有; use it for recurring project or business reporting, not for meeting minutes or one-page decision memos. +category: Writing & Reporting --- # Stakeholder Update diff --git a/skills/support/static-hosting/SKILL.md b/skills/support/static-hosting/SKILL.md index 8a4866b..4058cf1 100644 --- a/skills/support/static-hosting/SKILL.md +++ b/skills/support/static-hosting/SKILL.md @@ -1,6 +1,7 @@ --- name: static-hosting description: Serve static HTML/CSS/JS/images from robot project directories via the built-in FastAPI static file server. Use when generating web pages, reports, or interactive content for a bot. +category: Web Services --- # Static Hosting