# https://github.com/sidebutton/sidebutton 项目说明书
生成时间：2026-05-13 19:19:28 UTC
## 目录
- [项目概述](#project-overview)
- [系统架构](#system-architecture)
- [工作流引擎](#workflow-engine)
- [MCP 服务器](#mcp-server)
- [Chrome 扩展](#chrome-extension)
- [Dashboard 仪表盘](#dashboard)
- [步骤类型参考](#step-types)
- [知识包系统](#knowledge-packs)
- [REST API](#rest-api)
- [工作流定义语法](#workflow-definition)
## 项目概述
### 相关页面
相关主题：[系统架构](#system-architecture), [MCP 服务器](#mcp-server)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)
- [AGENTS.md](https://github.com/sidebutton/sidebutton/blob/main/AGENTS.md)
- [CONTRIBUTING.md](https://github.com/sidebutton/sidebutton/blob/main/CONTRIBUTING.md)
- [packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)
- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)
- [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)
# 项目概述
## 项目简介
SideButton 是一个开源的 AI Agent 平台，专注于为 AI 代理提供浏览器自动化能力、工作流编排和领域知识管理。该项目通过 MCP（Model Context Protocol）服务器提供浏览器工具集，支持使用 YAML 定义自动化工作流程，并提供知识包（Knowledge Packs）机制来封装特定 Web 应用的领域专业知识。
资料来源：[README.md:1]()
### 核心定位
SideButton 的主要目标是为 AI 代理提供与 Web 应用交互的标准化能力，使 AI 代理能够执行以下任务：
- 浏览器操作（导航、点击、输入、截图、提取数据）
- 工作流自动化执行
- 跨平台工具集成
- 领域知识获取与推理
资料来源：[AGENTS.md:3]()
## 核心特性
### 主要功能模块
| 功能模块 | 描述 |
|---------|------|
| **浏览器工具** | 40+ 浏览器命令，包括 navigate、click、type、extract、scroll、wait、snapshot |
| **工作流引擎** | YAML 驱动的多步骤自动化编排 |
| **知识包系统** | 可安装的领域知识（选择器、数据模型、状态机、角色剧本） |
| **MCP 集成** | 支持 Claude Desktop、Claude Code、Cursor 等主流 AI 平台 |
| **Chrome 扩展** | 实时 DOM 访问、CSS 选择器操作、WebSocket 连接 |
资料来源：[README.md:40-44]()
### 浏览器自动化能力
SideButton 通过 Chrome 扩展实现真实的 DOM 访问，采用 CSS 选择器而非像素坐标或截图的方式进行元素定位。这种方式确保了自动化脚本的稳定性和可维护性。
支持的浏览器命令包括：
- `navigate` - 导航到指定 URL
- `click` - 点击页面元素
- `type` - 向输入框输入文本
- `snapshot` - 获取页面可访问性树
- `extract` / `extractAll` - 提取文本内容
- `screenshot` - 页面截图
- `scroll` - 页面滚动
- `hover` - 悬停操作
资料来源：[README.md:42]()
## 系统架构
### 整体架构图
```mermaid
graph TD
A[AI 代理 Client] --> B[MCP Server]
B --> C[浏览器工具]
B --> D[工作流引擎]
B --> E[知识包系统]
C --> F[Chrome 扩展]
F --> G[浏览器页面]
D --> H[YAML 工作流定义]
E --> I[领域知识存储]
```
### 组件结构
SideButton 采用 Monorepo 架构组织代码，主要包含以下包：
| 包名 | 用途 |
|-----|------|
| `packages/server` | MCP 服务器 - 浏览器工具、工作流运行器、REST API |
| `packages/core` | 工作流引擎 - 步骤执行器、共享类型定义 |
| `packages/dashboard` | Web UI - 工作流管理、运行日志、设置页面 |
| `packages/sidebutton` | CLI 入口 - `npx sidebutton@latest` 命令行工具 |
| `extension/` | Chrome 扩展 (Manifest V3) - 通过 Chrome Web Store 分发 |
资料来源：[AGENTS.md:17-23]()
## 技术栈
### 核心技术选型
- **语言**: TypeScript（严格模式）
- **模块系统**: ES modules
- **包管理器**: pnpm
- **通信协议**: MCP (Model Context Protocol)
### MCP 工具集
| 工具 | 功能描述 |
|-----|---------|
| `run_workflow` | 按 ID 执行工作流 |
| `list_workflows` | 列出可用工作流 |
| `get_workflow` | 获取工作流 YAML 定义 |
| `get_run_log` | 获取运行日志 |
| `list_run_logs` | 列出最近执行记录 |
| `get_browser_status` | 检查浏览器扩展连接状态 |
| `capture_page` | 捕获页面选择器 |
| `navigate` | 导航到指定 URL |
| `snapshot` | 获取页面可访问性快照 |
| `click` | 点击元素 |
| `type` | 输入文本 |
| `scroll` | 滚动页面 |
| `extract` | 提取文本 |
| `screenshot` | 截图 |
资料来源：[README.md:60-77]()
## 安装与部署
### 环境要求
- Node.js（建议使用最新稳定版本）
- Chrome 浏览器（用于浏览器自动化功能）
### 安装方式
#### 通过 npm 全局安装
```bash
npm install -g sidebutton
```
#### 通过 npx 直接运行
```bash
npx sidebutton@latest
```
#### 本地开发安装
```bash
git clone https://github.com/sidebutton/sidebutton.git
cd sidebutton
pnpm install
pnpm build
pnpm start
```
资料来源：[AGENTS.md:9-15]()
### 构建与测试
| 命令 | 功能 |
|-----|------|
| `pnpm install` | 安装依赖 |
| `pnpm build` | 构建所有包 |
| `pnpm start` | 启动服务器 |
| `pnpm dev` | 开发模式运行 |
| `pnpm test` | 运行所有测试 |
| `pnpm test --filter server` | 测试指定包 |
资料来源：[AGENTS.md:12-16]()
## 工作流系统
### 工作流定义
SideButton 使用 YAML 格式定义工作流，支持多种步骤类型：
```yaml
steps:
- type: browser.navigate
url: "https://example.com"
- type: browser.click
selector: "#submit-btn"
- type: browser.extract
selector: ".result"
as: result
```
资料来源：[README.md:86-92]()
### 步骤类型分类
| 类别 | 支持的步骤 |
|-----|-----------|
| **浏览器** | `navigate`, `click`, `type`, `scroll`, `hover`, `wait`, `extract`, `extractAll`, `exists`, `key` |
| **Shell** | `shell.run`, `terminal.open`, `terminal.run` |
| **LLM** | `llm.classify`, `llm.generate` |
| **控制流** | `control.if`, `control.retry`, `control.stop`, `workflow.call` |
| **数据** | `data.first` |
资料来源：[packages/core/README.md:25-31]()
### 变量插值
工作流支持使用 `{{variable}}` 语法引用提取的值或参数：
```yaml
steps:
- type: browser.extract
selector: ".username"
as: user
- type: shell.run
cmd: "echo 'Hello, {{user}}!'"
```
资料来源：[README.md:94-99]()
## 知识包系统
### 概念定义
知识包（Knowledge Packs）是 SideButton 的核心特性之一，它封装了特定 Web 应用的领域专业知识，使 AI 代理能够理解并操作各类 Web 应用。
### 知识包内容
| 内容类型 | 描述 |
|---------|------|
| **选择器** | UI 元素的 CSS 选择器 |
| **数据模型** | 实体类型、字段、关系、有效状态 |
| **状态机** | 各状态间的有效转换 |
| **角色剧本** | 角色特定的操作流程（QA、SE、PM、SD） |
| **常见任务** | 分步操作流程、注意事项、边缘情况 |
资料来源：[README.md:103-111]()
### 知识包命令
| 命令 | 功能 |
|-----|------|
| `sidebutton registry add ` | 从注册表安装所有知识包 |
| `sidebutton registry update [name]` | 更新已安装的知识包 |
| `sidebutton registry remove ` | 卸载知识包并移除注册表 |
| `sidebutton registry list` | 显示注册表和包数量 |
| `sidebutton search [query]` | 跨注册表搜索包 |
| `sidebutton install ` | 单个知识包安装 |
| `sidebutton uninstall ` | 移除已安装的知识包 |
| `sidebutton init [domain]` | 脚手架新知识包 |
| `sidebutton validate [path]` | 验证知识包定义 |
资料来源：[packages/sidebutton/README.md:43-56]()
## MCP 集成配置
### Claude Desktop 配置
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"sidebutton": {
"command": "npx",
"args": ["sidebutton", "--stdio"]
}
}
}
```
### Claude Code 配置
添加到 `~/.claude/settings.json`：
```json
{
"mcpServers": {
"sidebutton": {
"type": "sse",
"url": "http://localhost:9876/mcp"
}
}
}
```
### Cursor 配置
添加到 `~/.cursor/mcp.json`：
```json
{
"mcpServers": {
"sidebutton": {
"url": "http://localhost:9876/mcp"
}
}
}
```
资料来源：[README.md:25-51]()
## Chrome 扩展
### 安装方式
从 [Chrome Web Store](https://chromewebstore.google.com/detail/sidebutton/odaefhmdmgijnhdbkfagnlnmobphgkij) 安装 SideButton 扩展。
### 主要功能
- **40+ 浏览器命令**: navigate、click、type、extract、scroll、wait、snapshot 等
- **真实 DOM 访问**: 通过 CSS 选择器而非像素坐标或截图
- **录制模式**: 捕获手动操作并转换为工作流
- **嵌入按钮**: 向任意网页注入操作按钮
- **WebSocket 连接**: 稳定的重连机制，支持本地或远程连接
资料来源：[README.md:113-119]()
## 许可证
SideButton 采用 Apache-2.0 开源许可证。
资料来源：[packages/core/README.md:45](), [packages/server/README.md:46](), [packages/sidebutton/README.md:70]()
## 相关资源
| 资源类型 | 链接 |
|---------|------|
| 官方文档 | https://docs.sidebutton.com |
| GitHub 仓库 | https://github.com/sidebutton/sidebutton |
| 官方网站 | https://sidebutton.com |
| 知识包市场 | https://sidebutton.com/skills |
| Chrome 扩展 | https://chromewebstore.google.com/detail/sidebutton/odaefhmdmgijnhdbkfagnlnmobphgkij |
资料来源：[AGENTS.md:48-51](), [packages/sidebutton/README.md:64-68]()
---
## 系统架构
### 相关页面
相关主题：[工作流引擎](#workflow-engine), [MCP 服务器](#mcp-server), [Dashboard 仪表盘](#dashboard)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/core/src/index.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/index.ts)
- [packages/server/src/server.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/server.ts)
- [packages/server/src/mcp/handler.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/handler.ts)
- [packages/server/src/cli.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)
- [packages/core/src/providers/github.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/providers/github.ts)
- [packages/dashboard/index.html](https://github.com/sidebutton/sidebutton/blob/main/packages/dashboard/index.html)
- [pnpm-workspace.yaml](https://github.com/sidebutton/sidebutton/blob/main/pnpm-workspace.yaml)
# 系统架构
SideButton 是一个基于工作流（Workflow）的浏览器自动化与 AI 任务执行框架，采用模块化单体架构（modular monorepo）设计。本文详细介绍其整体系统架构、核心组件及其交互关系。
## 架构概览
SideButton 项目采用 pnpm workspaces 实现多包管理，主要包含以下核心包：
| 包名 | 说明 |
|------|------|
| `@sidebutton/core` | 工作流引擎核心，提供工作流执行引擎和基础工具集 |
| `@sidebutton/server` | MCP 服务器，提供 REST API 和 MCP 协议接口 |
| `@sidebutton/dashboard` | Web 管理界面，基于 Vite + TypeScript 构建 |
| `@sidebutton/sidebutton` | CLI 工具，整合所有功能提供命令行入口 |
资料来源：[pnpm-workspace.yaml](https://github.com/sidebutton/sidebutton/blob/main/pnpm-workspace.yaml)
## 系统架构图
```mermaid
graph TB
subgraph Client["客户端层"]
CLI[CLI 工具
sidebutton]
BrowserExt[Chrome 扩展]
AI_Agent[AI 代理
Claude/Cursor]
end
subgraph Server["服务端层"]
MCP_Server[MCP Server
:9876]
Dashboard[Web Dashboard
Vite SPA]
WorkflowEngine[工作流引擎
@sidebutton/core]
Providers[Providers
GitHub/Browser/Shell]
end
subgraph Storage["数据层"]
DB[(本地数据库
SQLite/JSON)]
Workflows[工作流定义
YAML]
end
CLI --> MCP_Server
BrowserExt --> MCP_Server
AI_Agent --> MCP_Server
MCP_Server --> Dashboard
MCP_Server --> WorkflowEngine
WorkflowEngine --> Providers
MCP_Server --> DB
WorkflowEngine --> Workflows
```
## 核心组件详解
### MCP 服务器
MCP（Model Context Protocol）服务器是系统的核心通信枢纽，负责接收外部请求并调度工作流执行。
**技术实现：**
- 基于 Fastify 框架构建，提供高性能 HTTP 服务
- 支持 SSE（Server-Sent Events）传输协议
- 默认端口：9876
资料来源：[packages/server/src/server.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/server.ts)
**主要 API 端点：**
| 端点 | 方法 | 说明 |
|------|------|------|
| `/mcp` | GET/POST | MCP 协议主端点 |
| `/workflows` | GET | 列出所有工作流 |
| `/workflows/:id/run` | POST | 执行指定工作流 |
| `/run-logs` | GET | 查看执行日志 |
| `/settings` | GET/POST | 系统设置 |
### 工作流引擎
工作流引擎负责解析和执行 YAML 格式的工作流定义文件。
**执行流程：**
```mermaid
sequenceDiagram
participant User as 用户/AI Agent
participant MCP as MCP Server
participant Engine as Workflow Engine
participant Provider as Provider
participant Target as 目标系统
User->>MCP: run_workflow(workflowId)
MCP->>Engine: executeWorkflow(workflow, context)
Engine->>Engine: 解析 YAML 定义
loop 遍历每个 Step
Engine->>Provider: 调用对应 Provider
Provider->>Target: 执行实际操作
Target-->>Provider: 返回结果
Provider-->>Engine: 返回 Step 结果
end
Engine-->>MCP: 返回执行结果
MCP-->>User: 返回格式化输出
```
资料来源：[packages/core/src/index.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/index.ts)
**Step 类型体系：**
| 类别 | Step 类型 | 说明 |
|------|-----------|------|
| Browser | `navigate`, `click`, `type`, `scroll`, `hover`, `wait`, `extract`, `extractAll`, `exists`, `key` | 浏览器自动化操作 |
| Shell | `shell.run`, `terminal.open`, `terminal.run` | 命令行/终端操作 |
| LLM | `llm.classify`, `llm.generate`, `llm.decide` | AI 大模型交互 |
| Control | `control.if`, `control.retry`, `control.stop`, `workflow.call` | 流程控制 |
| Data | `data.first`, `variable.set`, `data.get` | 数据处理 |
### Provider 架构
Provider 是工作流引擎与外部系统交互的桥梁，采用策略模式设计。
```mermaid
graph LR
subgraph Providers["Providers"]
GitHub[GitHub Provider]
Browser[Browser Provider]
Shell[Shell Provider]
LLM[LLM Provider]
end
subgraph Actions["工作流 Actions"]
git[git.*]
browser[browser.*]
terminal[terminal.*]
llm[llm.*]
end
git --> GitHub
browser --> Browser
terminal --> Shell
llm --> LLM
```
**GitHub Provider 示例：**
资料来源：[packages/core/src/providers/github.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/providers/github.ts)
```typescript
// GitHub Provider 支持的操作
- git.listPRs // 列出 Pull Requests
- git.getPR // 获取 PR 详情
- git.createPR // 创建 Pull Request
- git.listIssues // 列出 Issues
- git.getIssue // 获取 Issue 详情
- issues.comment // 添加评论
- issues.transition // 状态流转
```
### Dashboard 前端
Dashboard 是一个基于 Vite + TypeScript 构建的单页应用（SPA），提供可视化的管理工作流界面。
**技术栈：**
- 构建工具：Vite
- 框架：React（推断自 SPA 架构）
- 入口文件：`packages/dashboard/index.html`
资料来源：[packages/dashboard/index.html](https://github.com/sidebutton/sidebutton/blob/main/packages/dashboard/index.html)
**主要功能页面：**
| 页面 | 路由 | 说明 |
|------|------|------|
| 首页 | `/` | 显示工作流快捷方式卡片 |
| Actions | `/actions` | 管理工作流定义 |
| Workflows | `/workflows` | 浏览和执行工作流 |
| Run Logs | `/run-logs` | 查看执行历史和日志 |
| Settings | `/settings` | 系统配置（AI 上下文、LLM、集成等） |
### CLI 工具
CLI 是用户与系统交互的主要入口之一，整合了所有核心功能。
**命令结构：**
```bash
sidebutton # 启动服务器（默认端口 9876）
sidebutton --stdio # 以 stdio 传输启动（Claude Desktop 集成）
sidebutton -p 8080 # 自定义端口
sidebutton list # 列出可用工作流
sidebutton run # 执行指定工作流
sidebutton status # 检查服务器状态
# Knowledge Packs 管理
sidebutton registry add # 添加知识包注册源
sidebutton registry update [name] # 更新已安装的包
sidebutton publish # 发布知识包到远程注册源
```
资料来源：[packages/server/src/cli.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)
## MCP 协议集成
SideButton 通过 MCP 协议实现与 AI 助手（Claude Desktop、Cursor 等）的深度集成。
### 连接配置
**Claude Desktop 配置：**
```json
{
"mcpServers": {
"sidebutton": {
"command": "npx",
"args": ["sidebutton", "--stdio"]
}
}
}
```
**Cursor 配置：**
```json
{
"mcpServers": {
"sidebutton": {
"url": "http://localhost:9876/mcp"
}
}
}
```
资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)
### MCP 工具集
| 工具 | 说明 |
|------|------|
| `run_workflow` | 按 ID 执行工作流 |
| `list_workflows` | 列出所有可用工作流 |
| `get_workflow` | 获取工作流 YAML 定义 |
| `get_run_log` | 获取执行日志 |
| `list_run_logs` | 列出最近执行记录 |
| `get_browser_status` | 检查浏览器扩展连接状态 |
| `capture_page` | 捕获页面选择器 |
| `navigate` | 导航到指定 URL |
| `snapshot` | 获取页面无障碍树 |
| `click` | 点击元素 |
| `type` | 输入文本 |
| `scroll` | 滚动页面 |
| `extract` | 提取文本 |
| `screenshot` | 截取页面截图 |
资料来源：[packages/server/src/mcp/handler.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/handler.ts)
## 工作流执行模型
### 执行上下文
每个工作流执行都维护一个上下文对象，用于在步骤之间传递数据：
```yaml
context:
previousResult: 上一步骤的输出结果
extracted: 从页面提取的数据
variables: 用户定义的变量
```
### 变量插值
使用 `{{variable}}` 语法引用上下文中保存的值：
```yaml
steps:
- type: browser.extract
selector: ".username"
as: user
- type: shell.run
cmd: "echo 'Hello, {{user}}!'"
```
## 数据存储
系统采用本地文件存储方式：
| 数据类型 | 存储位置 |
|----------|----------|
| 工作流定义 | YAML 文件 |
| 执行日志 | 本地数据库/JSON 文件 |
| 用户配置 | 设置页面数据 |
| 知识包 | `~/.sidebutton/` 目录 |
## 扩展机制
### Knowledge Packs（知识包）
知识包是按领域组织的可安装知识集合：
**包含内容：**
- **Selectors** — UI 元素的 CSS 选择器
- **Data Models** — 实体类型、字段、关系
- **State Machines** — 状态转换规则
- **Role Playbooks** — 角色特定的操作流程
- **Common Tasks** — 常见任务步骤和边界情况
**安装命令：**
```bash
sidebutton install github.com
sidebutton install atlassian.net
```
### 自定义 Provider
开发者可以通过扩展 Provider 接口来添加新的系统集成：
```typescript
// Provider 接口伪代码
interface Provider {
name: string;
execute(step: Step, context: Context): Promise;
}
```
## 安全考虑
- MCP 端点支持认证机制（Bearer Token）
- 发布知识包需要验证所有权（通过 `403 Permission denied` 保护）
- 敏感操作（如 `git.createPR`）需要明确的参数传递
资料来源：[packages/server/src/cli.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)
## 总结
SideButton 采用清晰的模块化架构：
1. **展示层**：CLI 工具、Web Dashboard、Chrome 扩展
2. **服务层**：MCP Server 统一入口，路由到工作流引擎
3. **执行层**：工作流引擎解析 YAML，调度 Provider 执行
4. **集成层**：Provider 封装与外部系统（GitHub、Browser、Shell）的交互
这种架构使得系统既可以通过命令行直接使用，也可以作为 AI 代理的工具后端，实现了灵活性和可扩展性的平衡。
---
## 工作流引擎
### 相关页面
相关主题：[系统架构](#system-architecture), [步骤类型参考](#step-types), [工作流定义语法](#workflow-definition)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/core/src/parser.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/parser.ts)
- [packages/core/src/executor.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/executor.ts)
- [packages/core/src/interpolate.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/interpolate.ts)
- [packages/core/src/context.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/context.ts)
- [packages/core/src/types.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/types.ts)
- [packages/server/src/mcp/handler.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/handler.ts)
# 工作流引擎
## 概述
工作流引擎（Workflow Engine）是 SideButton 系统的核心组件，负责解析、调度和执行自动化工作流程。该引擎基于 YAML 配置文件驱动，通过模块化的步骤（Step）架构实现浏览器自动化、Shell 命令执行、LLM 推理以及控制流逻辑。引擎设计遵循声明式优先原则，允许用户通过 YAML 定义复杂的多步骤自动化任务，引擎自动处理变量插值、上下文传递和错误恢复等机制。资料来源：[packages/core/README.md:1-10]()
## 核心架构
SideButton 工作流引擎采用分层架构，主要包含以下核心模块：
```mermaid
graph TD
A[工作流 YAML 配置] --> B[解析器 Parser]
B --> C[工作流对象 Workflow]
C --> D[执行器 Executor]
D --> E[执行上下文 Context]
E --> F[步骤处理器 Step Handlers]
F --> G[Browser 步骤]
F --> H[Shell 步骤]
F --> I[LLM 步骤]
F --> J[Control 步骤]
F --> K[Data 步骤]
G --> L[浏览器连接]
H --> M[终端会话]
I --> N[LLM Provider]
```
### 模块职责
| 模块 | 文件路径 | 职责说明 |
|------|----------|----------|
| 解析器 | `packages/core/src/parser.ts` | 解析 YAML 配置文件，验证结构，生成工作流对象 |
| 执行器 | `packages/core/src/executor.ts` | 遍历步骤数组，调用对应处理器，收集执行结果 |
| 变量插值器 | `packages/core/src/interpolate.ts` | 处理 `{{variable}}` 语法，执行变量替换 |
| 执行上下文 | `packages/core/src/context.ts` | 管理步骤间的状态传递和变量共享 |
| 类型定义 | `packages/core/src/types.ts` | 定义工作流、步骤、结果的 TypeScript 接口 |
资料来源：[packages/core/README.md:1-15]()
## 工作流定义
### 基本结构
工作流使用 YAML 格式定义，包含唯一标识、标题和步骤数组：
```yaml
id: check_ticket_status
title: "检查 Jira 工单状态"
steps:
- type: browser.navigate
url: "https://your-org.atlassian.net/browse/{{ticket_id}}"
- type: browser.extract
selector: "[data-testid='status-field']"
as: current_status
```
### 字段说明
| 字段 | 必填 | 类型 | 说明 |
|------|------|------|------|
| `id` | 是 | string | 工作流唯一标识符，用于调用和引用 |
| `title` | 是 | string | 显示名称，呈现于仪表盘和列表 |
| `description` | 否 | string | 工作流功能描述 |
| `params` | 否 | object | 输入参数定义，键为参数名，值为类型 |
| `steps` | 是 | array | 步骤数组，按顺序执行 |
资料来源：[packages/core/README.md:50-70]()
## 步骤类型详解
### 浏览器步骤（Browser Steps）
用于自动化网页操作，支持常见 DOM 交互：
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `navigate` | `url` | 导航到指定 URL |
| `click` | `selector` | 点击匹配元素 |
| `type` | `selector`, `text` | 向输入框输入文本 |
| `scroll` | `direction`, `amount` | 滚动页面 |
| `hover` | `selector` | 鼠标悬停 |
| `wait` | `selector` 或 `ms` | 等待元素或时间 |
| `extract` | `selector`, `as` | 提取单个元素文本 |
| `extractAll` | `selector`, `as` | 提取所有匹配元素 |
| `exists` | `selector`, `as` | 检查元素是否存在 |
```yaml
steps:
- type: browser.navigate
url: "https://example.com"
- type: browser.extract
selector: ".username"
as: user
- type: browser.click
selector: "#submit-btn"
```
资料来源：[packages/core/README.md:20-25]()
### Shell 步骤（Shell Steps）
执行本地命令行操作：
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `shell.run` | `cmd` | 执行 shell 命令 |
| `terminal.open` | - | 打开可见终端窗口（macOS） |
| `terminal.run` | `cmd` | 在终端窗口中运行命令 |
```yaml
steps:
- type: shell.run
cmd: "git status"
- type: shell.run
cmd: "npm test"
```
资料来源：[packages/core/README.md:26-28]()
### LLM 步骤（LLM Steps）
集成大语言模型进行推理和生成：
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `llm.classify` | `prompt`, `classes`, `as` | 结构化分类，返回预定义类别之一 |
| `llm.generate` | `prompt`, `as` | 自由文本生成 |
```yaml
steps:
- type: llm.classify
prompt: "判断此工单是否紧急：{{description}}"
classes: [urgent, normal, low]
as: priority
- type: llm.generate
prompt: "为以下功能写一份简洁的发布说明：{{changes}}"
as: release_notes
```
LLM 支持多个 Provider，包括 Ollama（本地）、OpenAI、Anthropic 和 Google。资料来源：[packages/core/README.md:29-32]()
### 控制流步骤（Control Steps）
管理工作流的执行逻辑：
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `control.if` | `condition`, `then`, `else` | 条件分支 |
| `control.retry` | `times`, `step` | 重试机制 |
| `control.stop` | `message` | 终止工作流并输出消息 |
| `workflow.call` | `id`, `params` | 调用其他工作流 |
```yaml
steps:
- type: browser.extract
selector: ".status"
as: current_status
- type: control.if
condition: "{{current_status}} != 'Done'"
then:
- type: llm.classify
prompt: "判断是否需要关闭工单"
classes: [close, keep_open]
as: decision
```
资料来源：[packages/core/README.md:33-37]()
### 数据处理步骤（Data Steps）
操作和转换数据：
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `data.first` | `from`, `as` | 从列表提取第一个元素 |
资料来源：[packages/core/README.md:38]()
## 变量系统
### 插值语法
使用双花括号 `{{variable}}` 语法引用变量：
```yaml
steps:
- type: browser.extract
selector: ".username"
as: user
- type: shell.run
cmd: "echo 'Hello, {{user}}!'"
```
### 变量作用域
变量在执行上下文中维护，遵循以下规则：
1. **步骤输出变量**：使用 `as` 参数命名的变量在后续步骤中可用
2. **参数变量**：工作流参数通过 `{{paramName}}` 传入
3. **嵌套属性**：支持点号访问，如 `{{user.name}}`
```yaml
id: example_workflow
params:
ticket_id: string
steps:
- type: browser.navigate
url: "https://jira.com/browse/{{ticket_id}}"
```
资料来源：[packages/core/README.md:55-65]()
## 执行上下文
执行上下文（Context）在整个工作流执行期间维护状态，负责：
1. **变量存储**：保存每个步骤的输出结果
2. **参数传递**：管理输入参数和默认值
3. **错误传播**：记录失败步骤并支持重试逻辑
4. **结果聚合**：收集步骤执行日志和输出
```mermaid
sequenceDiagram
participant U as 用户调用
participant C as 执行上下文
participant S1 as 步骤 1
participant S2 as 步骤 2
participant S3 as 步骤 3
U->>C: 初始化（参数、环境）
C->>S1: 执行 navigate
S1-->>C: 存储结果 var1
C->>S2: 执行 extract
S2-->>C: 存储结果 var2
C->>S3: 执行 llm.classify
S3-->>C: 存储结果 decision
C-->>U: 返回执行结果
```
## MCP 工具集成
工作流引擎通过 MCP（Model Context Protocol）暴露工具接口，支持外部 AI 助手调用：
| MCP 工具 | 功能 |
|----------|------|
| `run_workflow` | 根据 ID 执行工作流 |
| `list_workflows` | 列出所有可用工作流 |
| `get_workflow` | 获取工作流 YAML 定义 |
| `get_run_log` | 获取执行日志 |
| `list_run_logs` | 列出最近执行记录 |
```json
{
"mcpServers": {
"sidebutton": {
"command": "npx",
"args": ["sidebutton", "--stdio"]
}
}
}
```
资料来源：[packages/server/README.md:40-55]()
## 配置与部署
### 工作流存储
工作流文件存储在配置的 `actions` 目录中，使用 YAML 格式：
```
actions/
├── check_ticket.yaml
├── create_issue.yaml
└── news_daily.yaml
```
### 服务器配置
SideButton 服务器默认监听 9876 端口，通过 `@sidebutton/server` 包部署：
```bash
sidebutton # 启动服务器（默认端口 9876）
sidebutton --stdio # 以 stdio 传输模式启动
sidebutton -p 8080 # 自定义端口
```
## 执行流程
```mermaid
graph LR
A[解析 YAML] --> B[验证结构]
B --> C[初始化上下文]
C --> D{遍历步骤}
D -->|有步骤| E[解析步骤类型]
E --> F[插值变量]
F --> G[执行处理器]
G --> H{成功?}
H -->|是| I[更新上下文]
I --> D
H -->|否| J{支持重试?}
J -->|是| G
J -->|否| K[记录错误]
K --> L[终止执行]
D -->|无步骤| M[返回结果]
```
## 扩展工作流引擎
### 添加新步骤类型
1. 在 `types.ts` 中定义新的步骤接口
2. 在解析器中添加类型验证
3. 在执行器中注册处理器
4. 实现具体的执行逻辑
### 自定义 Provider
LLM Provider 支持扩展，需实现标准接口：
```typescript
interface LLMProvider {
classify(prompt: string, classes: string[]): Promise;
generate(prompt: string): Promise;
}
```
## 相关资源
- 完整文档：[https://docs.sidebutton.com](https://docs.sidebutton.com)
- GitHub 仓库：[https://github.com/sidebutton/sidebutton](https://github.com/sidebutton/sidebutton)
- 官方网站：[https://sidebutton.com](https://sidebutton.com)
---
## MCP 服务器
### 相关页面
相关主题：[系统架构](#system-architecture), [步骤类型参考](#step-types), [REST API](#rest-api)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/server/src/mcp/handler.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/handler.ts)
- [packages/server/src/mcp/stdio.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/stdio.ts)
- [packages/server/src/mcp/tools.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/tools.ts)
- [packages/server/src/stdio-mode.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/stdio-mode.ts)
- [packages/server/src/server.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/server.ts)
- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)
- [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)
- [packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)
# MCP 服务器
## 概述
MCP（Model Context Protocol）服务器是 SideButton 的核心组件之一，扮演 AI 代理与浏览器自动化能力之间的桥梁角色。作为一个 MCP 兼容的服务器实现，它向 AI 助手（如 Claude Desktop、Cursor 等）暴露了一系列工具，使得 AI 能够通过标准化的协议执行浏览器操作、工作流自动化以及其他系统任务。
SideButton 的 MCP 服务器基于 TypeScript 构建，采用 Fastify 作为底层 HTTP 框架，并支持多种传输协议以适应不同的集成场景。资料来源：[packages/server/README.md]()
## 架构设计
### 整体架构
MCP 服务器采用了分层架构设计，主要包含以下几个核心模块：
| 模块 | 文件路径 | 职责 |
|------|----------|------|
| MCP Handler | `packages/server/src/mcp/handler.ts` | 处理 MCP 协议消息的接收和响应 |
| STDIO 传输 | `packages/server/src/mcp/stdio.ts` | 支持标准输入输出的传输模式 |
| 工具注册 | `packages/server/src/mcp/tools.ts` | 定义和注册所有可用的 MCP 工具 |
| 服务器入口 | `packages/server/src/server.ts` | 主服务器启动和路由配置 |
| STDIO 模式 | `packages/server/src/stdio-mode.ts` | CLI 模式下的独立 STDIO 进程 |
### 传输协议支持
MCP 服务器支持两种主要的传输协议：
1. **SSE（Server-Sent Events）**：基于 HTTP 的长连接推送模式，适用于 Web 应用和远程连接场景
2. **STDIO**：标准输入输出模式，专为本地 CLI 工具和 AI 桌面应用集成设计
```mermaid
graph TD
A[AI 助手] -->|MCP 协议| B{MCP 服务器}
B -->|SSE| C[Web/远程连接]
B -->|STDIO| D[本地 CLI]
B --> E[工具执行层]
E --> F[浏览器自动化]
E --> G[工作流引擎]
E --> H[Shell 命令]
```
## 工具体系
MCP 服务器通过工具（Tools）向 AI 暴露功能，所有工具按照功能域进行分类组织。
### 工具分类总览
| 类别 | 工具列表 | 说明 |
|------|----------|------|
| 工作流 | `run_workflow`, `list_workflows`, `get_workflow` | 工作流的执行和查询 |
| 运行日志 | `get_run_log`, `list_run_logs` | 查看工作流执行历史 |
| 浏览器 | `navigate`, `snapshot`, `click`, `type`, `scroll`, `hover`, `screenshot`, `extract`, `extract_all`, `extract_map`, `wait`, `key`, `exists`, `select_option` | 浏览器页面操作 |
| 浏览器元数据 | `get_browser_status`, `capture_page` | 浏览器连接状态和元素捕获 |
### 工作流工具
| 工具名称 | 功能描述 |
|----------|----------|
| `run_workflow` | 根据工作流 ID 执行预构建的工作流自动化 |
| `list_workflows` | 列出所有可用的工作流 |
| `get_workflow` | 获取工作流的 YAML 定义内容 |
| `get_run_log` | 获取指定运行的执行日志详情 |
| `list_run_logs` | 列出最近的工作流执行记录 |
资料来源：[packages/server/README.md]()
### 浏览器自动化工具
浏览器工具提供了对网页的完整控制能力：
| 工具 | 参数示例 | 功能 |
|------|----------|------|
| `navigate` | `{ url: string }` | 导航浏览器到指定 URL |
| `snapshot` | `{ ref?: string }` | 获取页面可访问性快照 |
| `click` | `{ ref: string }` | 点击指定元素 |
| `type` | `{ ref: string, text: string }` | 向输入框输入文本 |
| `scroll` | `{ direction: 'up' \| 'down', amount?: number }` | 滚动页面 |
| `hover` | `{ ref: string }` | 鼠标悬停在元素上 |
| `extract` | `{ selector: string }` | 从页面提取文本内容 |
| `extract_all` | `{ selector: string }` | 提取所有匹配元素的内容 |
| `extract_map` | `{ selector: string, fields: object }` | 从重复元素提取结构化数据 |
| `screenshot` | `{ name?: string }` | 捕获页面截图 |
| `select_option` | `{ ref: string, option: string }` | 选择下拉选项 |
| `get_browser_status` | 无参数 | 检查浏览器扩展连接状态 |
| `capture_page` | 无参数 | 捕获页面选择器信息 |
## 集成配置
### Cursor IDE 配置
在 `~/.cursor/mcp.json` 中添加以下配置：
```json
{
"mcpServers": {
"sidebutton": {
"url": "http://localhost:9876/mcp"
}
}
}
```
### Claude Desktop 配置
在 `~/Library/Application Support/Claude/claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"sidebutton": {
"command": "npx",
"args": ["sidebutton", "--stdio"]
}
}
}
```
资料来源：[packages/sidebutton/README.md]()
## 工作流引擎集成
MCP 服务器与核心工作流引擎（`@sidebutton/core`）紧密集成。工作流引擎负责解析和执行 YAML 格式的工作流定义。
### 支持的步骤类型
| 类别 | 步骤类型 | 说明 |
|------|----------|------|
| 浏览器 | `navigate`, `click`, `type`, `scroll`, `hover`, `wait`, `extract`, `extractAll`, `exists`, `key` | 页面交互操作 |
| Shell | `shell.run`, `terminal.open`, `terminal.run` | 命令行执行 |
| LLM | `llm.classify`, `llm.generate` | AI 生成和分类 |
| 控制流 | `control.if`, `control.retry`, `control.stop`, `workflow.call` | 流程控制 |
| 数据 | `data.first`, `variable.set`, `data.get` | 数据操作 |
资料来源：[packages/core/README.md]()
### 工作流示例
```yaml
steps:
- type: browser.navigate
url: "https://github.com"
- type: browser.extract
selector: ".username"
as: user
- type: shell.run
cmd: "echo 'Hello, {{user}}!'"
```
## 浏览器扩展集成
MCP 服务器通过 WebSocket 与 Chrome 扩展保持稳定连接，实现真正的 DOM 访问能力。这与传统的基于像素坐标或截图的方法有本质区别。
### 扩展功能特性
- **40+ 浏览器命令**：包括导航、点击、输入、提取、滚动、等待、快照等
- **真实 DOM 访问**：通过 CSS 选择器精确定位元素
- **录制模式**：捕获手动操作并转换为工作流
- **嵌入按钮**：向任意网页注入操作按钮
- **WebSocket 连接**：支持自动重连，适用于本地或远程部署
资料来源：[README.md]()
## 部署模式
### 独立服务器模式
默认情况下，启动 MCP 服务器会同时启动 Web UI 仪表板：
```bash
sidebutton # 启动服务器（默认端口 9876）
sidebutton -p 8080 # 自定义端口
```
### STDIO 传输模式
适用于 AI 桌面应用的集成模式：
```bash
sidebutton --stdio # 启动 stdio 传输模式
```
### 服务器端点
| 端点 | 方法 | 功能 |
|------|------|------|
| `/` | GET | Web UI 仪表板 |
| `/mcp` | GET/POST | MCP 协议端点（SSE） |
| `/api/workflows` | GET | REST API - 获取工作流列表 |
| `/api/workflows/:id/run` | POST | REST API - 执行工作流 |
| `/api/run-logs` | GET | REST API - 获取运行日志 |
## 与其他组件的关系
```mermaid
graph LR
A[MCP 服务器] -->|调用| B[核心引擎
@sidebutton/core]
A -->|WebSocket| C[Chrome 扩展]
A -->|HTTP/WebSocket| D[仪表板 Web UI]
B -->|执行| E[浏览器自动化]
B -->|执行| F[Shell 命令]
B -->|执行| G[LLM 调用]
```
## 技术栈
| 组件 | 技术选型 | 说明 |
|------|----------|------|
| 运行时 | Node.js / TypeScript | 严格模式 + ES 模块 |
| HTTP 框架 | Fastify | 高性能 Web 框架 |
| 包管理 | pnpm | Monorepo 支持 |
| 协议 | MCP (Model Context Protocol) | AI 工具交互标准 |
## 相关资源
- [完整文档](https://docs.sidebutton.com)
- [GitHub 仓库](https://github.com/sidebutton/sidebutton)
- [官网](https://sidebutton.com)
- [Chrome 扩展商店](https://chromewebstore.google.com/detail/sidebutton/odaefhmdmgijnhdbkfagnlnmobphgkij)
---
## Chrome 扩展
### 相关页面
相关主题：[系统架构](#system-architecture), [步骤类型参考](#step-types)
相关源码文件
以下源码文件用于生成本页说明：
- [CONTRIBUTING.md](https://github.com/sidebutton/sidebutton/blob/main/CONTRIBUTING.md)
- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)
- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)
- [packages/server/src/server.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/server.ts)
- [packages/server/defaults/targets/_provider-github-browser.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/targets/_provider-github-browser.md)
- [packages/server/defaults/roles/qa.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/qa.md)
# Chrome 扩展
SideButton Chrome 扩展是连接用户浏览器与本地工作流引擎的核心桥梁，提供基于真实 DOM 的浏览器自动化能力。
## 功能概述
Chrome 扩展通过 WebSocket 与本地服务器建立持久连接，实现以下核心功能：
| 功能类别 | 具体能力 |
|---------|---------|
| **页面导航** | `navigate` 打开 URL 地址 |
| **元素交互** | `click` 点击、`type` 输入文本、`hover` 悬停 |
| **内容提取** | `extract` 提取文本、`extract_all` 批量提取、`extract_map` 结构化提取 |
| **页面分析** | `snapshot` 获取无障碍树、`screenshot` 截图 |
| **表单操作** | `fill` 填充表单值（兼容 React）、`select_option` 选择下拉选项 |
| **元素状态** | `exists` 检查元素是否存在、`wait` 等待元素或延迟 |
| **高级能力** | `scroll` 滚动页面、`scroll_into_view` 滚动到可视区域、`evaluate` 执行 JavaScript、`press_key` 发送键盘事件 |
资料来源：[README.md:70-81]()
## 安装方式
### 从 Chrome 应用商店安装
SideButton 扩展已发布至 Chrome Web Store，可直接安装：
> **安装地址**: https://chromewebstore.google.com/detail/sidebutton/odaefhmdmgijnhdbkfagnlnmobphgkij
### 本地加载开发版本
如需开发或测试最新功能，可加载未打包的扩展程序：
1. 打开 `chrome://extensions/`
2. 启用右上角的 **Developer mode（开发者模式）**
3. 点击 **Load unpacked（加载已解压的扩展程序）**
4. 选择项目根目录下的 `extension/` 文件夹
资料来源：[CONTRIBUTING.md:28-35]()
## 技术架构
### 连接架构
SideButton 采用客户端-服务器架构，Chrome 扩展作为客户端通过 WebSocket 与本地 MCP 服务器通信：
```mermaid
graph LR
A[Chrome 浏览器] -->|WebSocket| B[SideButton 扩展]
B -->|WebSocket| C[本地服务器 :9876]
C --> D[MCP 工具层]
D --> E[Core 工作流引擎]
C --> F[REST API]
```
### 通信协议
扩展与服务器之间使用 WebSocket 协议，支持稳定重连机制，无论服务器运行在本地还是远程均可正常工作。
资料来源：[README.md:52-54]()
### 核心交互流程
```mermaid
sequenceDiagram
participant User as 用户
participant Extension as Chrome 扩展
participant Server as 本地服务器
participant Browser as 目标网页
User->>Extension: 点击扩展图标
Extension->>Server: 建立 WebSocket 连接
Server-->>Extension: 连接确认
User->>Extension: 执行浏览器命令
Extension->>Browser: DOM 操作
Browser-->>Extension: 操作结果
Extension-->>User: 展示结果
```
## 浏览器命令详解
### 页面导航与快照
| 命令 | 参数 | 说明 |
|-----|------|------|
| `navigate` | `url` | 导航至指定 URL |
| `snapshot` | - | 获取页面无障碍快照（YAML 格式），返回元素引用 `ref=N` |
| `screenshot` | - | 捕获页面截图 |
| `capture_page` | - | 捕获当前页面的 CSS 选择器 |
`snapshot` 命令返回结构化的 YAML 格式数据，每个可交互元素都有对应的引用编号，可用于后续的 `click`、`type` 等操作：
```yaml
- ref: 1
role: button
name: "提交"
focused: false
- ref: 2
role: textbox
name: "用户名"
focused: true
```
资料来源：[packages/server/defaults/roles/qa.md:68-74]()
### 元素定位与交互
SideButton 使用 **CSS 选择器** 进行元素定位，而非像素坐标或截图方式：
| 命令 | 参数 | 说明 |
|-----|------|------|
| `click` | `selector` | 点击匹配选择器的元素 |
| `type` | `selector`, `text` | 向匹配的元素输入文本 |
| `hover` | `selector` | 悬停至匹配的元素 |
| `scroll` | `direction` | 滚动页面（up/down） |
| `extract` | `selector` | 从匹配的元素提取文本 |
| `exists` | `selector` | 检查元素是否存在 |
所有浏览器操作均基于真实 DOM 访问，确保与 React、Vue 等现代前端框架的完全兼容性。
资料来源：[packages/server/README.md:44-53]()
### 表单处理
| 命令 | 参数 | 说明 |
|-----|------|------|
| `fill` | `selector`, `value` | 直接填充输入值（React 友好） |
| `select_option` | `selector`, `value` | 选择下拉选项 |
| `press_key` | `keys` | 发送键盘组合键 |
`fill` 命令专为 React 等虚拟 DOM 框架设计，能够正确触发 `onChange` 事件：
```yaml
steps:
- type: browser.fill
selector: "#search-input"
value: "SideButton"
```
资料来源：[README.md:80-81]()
### 高级操作
| 命令 | 参数 | 说明 |
|-----|------|------|
| `evaluate` | `script` | 在浏览器上下文中执行 JavaScript |
| `scroll_into_view` | `selector` | 将元素滚动到可视区域 |
| `wait` | `selector` 或 `ms` | 等待元素出现或延时 |
| `extract_all` | `selector` | 提取所有匹配元素的文本 |
| `extract_map` | `selector` | 从重复元素提取结构化数据 |
`evaluate` 命令允许执行任意 JavaScript，可用于复杂的前端交互场景：
```yaml
steps:
- type: browser.evaluate
script: "document.querySelector('.modal').style.display = 'none'"
```
## 扩展状态指示
Chrome 扩展图标会显示当前连接状态：
- **已连接**：扩展图标高亮，浏览器扩展已成功连接服务器
- **未连接**：扩展图标灰显，无法执行浏览器命令
### 验证连接状态
通过 MCP 工具 `get_browser_status` 可检查扩展连接：
```json
{
"connected": true,
"url": "https://github.com"
}
```
资料来源：[packages/server/README.md:42-43]()
## 录制模式
扩展内置录制功能，可将用户在浏览器中的手动操作捕获为工作流 YAML：
1. 启用录制模式
2. 在目标页面上执行操作
3. 停止录制
4. 导出的 YAML 可直接作为工作流使用
录制模式大幅降低了自动化脚本的创建门槛，非技术用户也能快速生成浏览器自动化流程。
资料来源：[README.md:51]()
## 嵌入按钮
SideButton 支持向任意网页注入自定义操作按钮（Embed Buttons），适用于：
- 在第三方网站中注入快捷操作
- 为特定业务场景定制操作入口
- 扩展现有网站的功能
资料来源：[README.md:51]()
## 与 GitHub 浏览器集成的目标配置
SideButton 提供专门针对 GitHub 的浏览器目标配置，可通过设置环境变量配置：
| 环境变量 | 说明 | 示例值 |
|---------|------|--------|
| `GITHUB_BROWSER_URL` | GitHub 网站地址 | `https://github.com` |
### GitHub 浏览器操作示例
```mermaid
graph TD
A[打开 PR 页面] --> B[使用 snapshot 读取详情]
B --> C[点击 Files changed 标签]
C --> D[查看 diff 内容]
E[列出 PR 列表] --> F[导航到 /owner/repo/pulls]
F --> G[使用 snapshot 读取列表]
H[创建 Issue] --> I[运行 github_browser_create_issue 工作流]
I --> J[或直接导航到 /owner/repo/issues/new]
```
使用浏览器工具查看 PR 详情：
```yaml
steps:
- type: browser.navigate
url: "{GITHUB_BROWSER_URL}/owner/repo/pull/123"
- type: browser.snapshot
as: pr_details
- type: browser.click
selector: ".tabnav-tab[href*='files']"
```
资料来源：[packages/server/defaults/targets/_provider-github-browser.md]()
## 常见问题排查
### 扩展显示未连接
1. 确认本地服务器已启动（运行 `pnpm dev:server` 或 `sidebutton start`）
2. 验证服务器端口为 9876
3. 在 Chrome 中检查扩展是否已启用
4. 刷新扩展页面或重启服务器
### 浏览器命令执行失败
1. 使用 `snapshot` 检查页面是否正确加载
2. 确认选择器是否仍然有效（页面结构可能已变化）
3. 添加 `wait` 步骤等待页面元素加载
4. 检查服务器日志获取详细错误信息
### 录制模式无法捕获操作
1. 确保选择正确的标签页
2. 某些 iframe 内容可能无法录制
3. 检查是否有 JavaScript 错误阻止事件监听
## 工作流集成
Chrome 扩展命令通常作为工作流步骤的一部分执行：
```yaml
id: github_review_pr
title: "Review GitHub PR"
steps:
- type: browser.navigate
url: "{{pr_url}}"
- type: browser.snapshot
as: page_structure
- type: browser.extract
selector: ".pr-description"
as: description
- type: llm.classify
input: "{{description}}"
categories:
- bug
- feature
- refactor
as: type
- type: browser.click
selector: "button[data-tab='files']"
```
通过 `workflow.call` 可以在工作流中链式调用其他工作流，实现复杂的浏览器自动化场景。
## 相关文档
- [核心包文档](../core/README.md) - 工作流引擎与步骤类型
- [服务器文档](./README.md) - MCP 服务器与 REST API
- [贡献指南](../CONTRIBUTING.md) - 开发工作流
- [完整文档](https://docs.sidebutton.com) - 官方文档站点
---
## Dashboard 仪表盘
### 相关页面
相关主题：[系统架构](#system-architecture), [REST API](#rest-api)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/dashboard/index.html](https://github.com/sidebutton/sidebutton/blob/main/packages/dashboard/index.html)
- [packages/dashboard/src/App.svelte](https://github.com/sidebutton/sidebutton/blob/main/packages/dashboard/src/App.svelte)
- [packages/dashboard/src/lib/views/DashboardView.svelte](https://github.com/sidebutton/sidebutton/blob/main/packages/dashboard/src/lib/views/DashboardView.svelte)
- [packages/dashboard/src/lib/views/WorkflowsView.svelte](https://github.com/sidebutton/sidebutton/blob/main/packages/dashboard/src/lib/views/WorkflowsView.svelte)
- [packages/dashboard/src/lib/api.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/dashboard/src/lib/api.ts)
- [packages/server/defaults/roles/qa.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/qa.md)
# Dashboard 仪表盘
## 概述
Dashboard 是 SideButton 项目的可视化控制中心，为用户提供工作流（Workflow）和快捷方式（Shortcut）的集中管理界面。它作为 Web 前端应用运行在浏览器中，通过 REST API 与后端服务器通信，实现工作流的创建、编辑、执行和监控功能。
资料来源：[packages/dashboard/index.html:1-11]()
## 技术架构
### 组件结构
Dashboard 采用 Svelte 框架构建，核心组件结构如下：
```mermaid
graph TD
A[App.svelte] --> B[DashboardView.svelte]
A --> C[WorkflowsView.svelte]
A --> D[ActionsView.svelte]
A --> E[RunLogsView.svelte]
A --> F[SettingsView.svelte]
B --> G[api.ts]
C --> G
D --> G
E --> G
G --> H[Server API
localhost:9876]
H --> I[Workflow Engine
@sidebutton/core]
```
### 入口文件
Dashboard 的入口点是 `packages/dashboard/index.html`，它加载 Svelte 应用并挂载到 `#app` 容器中：
```html
SideButton
```
资料来源：[packages/dashboard/index.html:1-11]()
## 核心视图
### DashboardView 工作流视图
DashboardView 是仪表盘的主页面，负责展示快捷方式网格和工作流卡片。每个快捷方式卡片显示工作流标题和运行按钮，点击运行按钮可打开参数模态框（如果工作流需要参数）或立即执行。
资料来源：[packages/server/defaults/roles/qa.md:32-45]()
#### 页面验证清单
| 验证项 | 预期结果 |
|--------|----------|
| 快捷方式网格显示 | 显示工作流标题和运行按钮 |
| 参数模态框 | 需要参数的工作流打开参数输入界面 |
| 立即执行 | 无参数工作流点击后直接执行 |
| 添加到仪表盘 | 从 Actions/Workflows 页面可添加快捷方式 |
### WorkflowsView 工作流库视图
WorkflowsView 展示工作流库中的所有可用工作流，提供搜索、排序和分类筛选功能。
#### 功能特性
| 功能 | 说明 |
|------|------|
| 搜索过滤 | 按标题和描述文本过滤工作流卡片 |
| 分类筛选 | 按类别（Category）筛选工作流 |
| 排序选项 | 支持按名称A-Z、运行次数、成功率、最近验证时间排序 |
| 详情查看 | 点击卡片查看工作流详细信息（只读视图） |
资料来源：[packages/server/defaults/roles/qa.md:58-73]()
### 其他视图页面
| 页面路由 | 功能描述 |
|----------|----------|
| `/actions` | 动作管理页面，展示所有自定义动作 |
| `/actions/:id` | 动作详情页，显示步骤和参数配置 |
| `/recordings` | 录制回放页面 |
| `/run-logs` | 运行日志页面，展示执行历史和统计 |
| `/settings` | 设置页面，包含 AI 上下文、LLM 提供商配置 |
资料来源：[packages/server/defaults/roles/qa.md:48-67]()
## API 集成
### API 模块结构
`packages/dashboard/src/lib/api.ts` 封装了所有与后端服务器的通信接口，提供类型安全的 API 调用方法。
### 核心 API 端点
| 端点 | 方法 | 描述 |
|------|------|------|
| `/health` | GET | 服务器健康状态检查 |
| `/api/workflows` | GET | 获取工作流列表 |
| `/api/workflows/:id` | GET | 获取单个工作流详情 |
| `/api/workflows/:id/run` | POST | 执行工作流 |
| `/api/run-logs` | GET | 获取运行日志列表 |
| `/api/run-logs/:id` | GET | 获取单条运行日志详情 |
| `/api/shortcuts` | GET/POST/DELETE | 快捷方式管理 |
资料来源：[packages/dashboard/src/lib/api.ts]()
### 健康检查流程
```mermaid
sequenceDiagram
participant D as Dashboard
participant S as Server
participant B as Browser Extension
D->>S: GET /health
S-->>D: {status: "ok", version: "...", browser_connected: true}
alt browser_connected: false
D->>D: 显示连接警告
D->>B: 提示用户检查扩展状态
end
```
资料来源：[packages/server/defaults/roles/qa.md:24-30]()
## 运行日志与监控
### 运行日志页面
Run Logs 页面展示工作流执行的历史记录，包含以下信息：
- KPI 统计栏（总执行次数、成功率、平均执行时间）
- 执行状态（成功、失败、进行中）
- 步骤级执行详情
| 指标 | 说明 |
|------|------|
| 执行总数 | 累计执行的工作流数量 |
| 成功率 | 成功执行占总执行的比例 |
| 平均耗时 | 所有执行步骤的平均时间 |
| 清空日志 | 提供一键清空所有运行日志功能 |
资料来源：[packages/server/defaults/roles/qa.md:48-52]()
### 执行详情
每个运行日志条目包含：
1. 工作流 ID 和名称
2. 开始和结束时间戳
3. 每一步的输入输出数据
4. 错误信息和堆栈跟踪（如有）
5. 最终状态（success/failure/running）
## 设置页面
Settings 页面提供系统配置功能，包含多个子选项卡：
### 子选项卡结构
| 选项卡 | 功能 |
|--------|------|
| AI Context | 全局 AI 上下文配置 |
| Persona | AI 角色扮演 persona 文本编辑 |
| Roles | 角色定义和开关管理 |
| Targets | 目标网站匹配规则配置 |
| Integrations | 第三方提供商连接状态 |
| Inline | 内联上下文和环境变量 |
资料来源：[packages/server/defaults/roles/qa.md:54-67]()
## 开发与部署
### 开发环境启动
```bash
pnpm dev # 启动所有组件（热重载）
pnpm dev:server # 仅启动服务器 :9876
pnpm dev:dashboard # 仅启动仪表盘 :5173
pnpm dev:core # 核心库监视构建
```
资料来源：[CONTRIBUTING.md]()
### 生产构建
Dashboard 作为 Vite 构建的单页应用，输出静态资源供服务器托管。
## 烟雾测试清单
在部署或更新后，应验证以下功能正常工作：
| 步骤 | 测试项 | 验证方法 |
|------|--------|----------|
| 1 | 服务器健康 | `GET /health` 返回 `status: "ok"` |
| 2 | 扩展连接 | `get_browser_status` 返回 `connected: true` |
| 3 | 仪表盘首页 | 导航栏、快捷方式网格正常显示 |
| 4 | Actions 页面 | 动作卡片、搜索、筛选功能正常 |
| 5 | Library 页面 | 工作流卡片、排序、搜索正常 |
| 6 | Run Logs 页面 | 统计栏、日志列表正常 |
| 7 | Settings 页面 | 所有子选项卡加载正常 |
| 8 | 工作流执行 | 成功运行工作流并生成日志 |
| 9 | MCP 快照 | `snapshot` 返回结构化数据 |
资料来源：[packages/server/defaults/roles/qa.md:18-85]()
## 故障排除
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 页面空白 | 服务器未启动 | 执行 `pnpm dev` 启动服务 |
| 快捷方式不显示 | 数据库未初始化 | 检查 `browser_connected` 状态 |
| 工作流执行失败 | 扩展未连接 | 在 Chrome 扩展页面验证 SideButton 扩展已启用 |
| API 调用超时 | 端口冲突或防火墙 | 检查 9876 端口占用情况 |
---
## 步骤类型参考
### 相关页面
相关主题：[工作流引擎](#workflow-engine), [工作流定义语法](#workflow-definition)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/core/src/steps/browser.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/steps/browser.ts)
- [packages/core/src/steps/shell.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/steps/shell.ts)
- [packages/core/src/steps/llm.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/steps/llm.ts)
- [packages/core/src/steps/control.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/steps/control.ts)
- [packages/core/src/steps/data.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/steps/data.ts)
- [packages/core/src/steps/git.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/steps/git.ts)
- [packages/core/src/steps/issues.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/steps/issues.ts)
# 步骤类型参考
本文档详细介绍 SideButton 工作流引擎支持的所有步骤类型。步骤是工作流的基本构建单元，每个步骤执行特定的操作并可产生输出供后续步骤使用。
## 概述
SideButton 工作流采用 YAML 格式定义步骤，支持七大类步骤类型：
| 类别 | 用途 | 示例步骤 |
|------|------|----------|
| **Browser** | 浏览器自动化操作 | `navigate`, `click`, `type`, `extract` |
| **Shell** | 命令行和终端操作 | `shell.run`, `terminal.open`, `terminal.run` |
| **LLM** | AI 驱动的决策和生成 | `llm.generate`, `llm.decide`, `llm.classify` |
| **Control** | 工作流控制流 | `control.if`, `control.retry`, `control.stop`, `workflow.call` |
| **Data** | 数据操作和变量管理 | `variable.set`, `data.first`, `data.get` |
| **Git** | GitHub/GitLab 操作 | `git.getPR`, `git.createPR`, `git.listIssues` |
| **Issues** | 任务追踪系统操作 | `issues.search`, `issues.create`, `issues.transition` |
## Browser 步骤类型
Browser 步骤用于自动化浏览器操作，是 SideButton 的核心功能之一。通过 Chrome 扩展连接浏览器后，可以执行各种 DOM 操作。
### 页面导航与交互
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `browser.navigate` | `url` (必需) | 导航到指定 URL |
| `browser.click` | `selector` (必需) | 点击匹配选择器的元素 |
| `browser.type` | `selector`, `text` (必需) | 向输入框输入文本 |
| `browser.hover` | `selector` (必需) | 鼠标悬停在元素上 |
| `browser.key` | `keys` (必需) | 模拟键盘按键 |
| `browser.scroll` | `direction`, `amount` | 滚动页面 |
```yaml
# 示例：导航并登录
steps:
- type: browser.navigate
url: "https://github.com/login"
- type: browser.type
selector: "#login_field"
text: "user@example.com"
- type: browser.type
selector: "#password"
text: "{{password}}"
- type: browser.click
selector: "[type='submit']"
```
### 内容提取
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `browser.extract` | `selector` (必需), `as` | 从单个元素提取文本 |
| `browser.extract_all` | `selector` (必需), `as` | 提取所有匹配元素的文本 |
| `browser.extract_map` | `selector`, `as` | 从重复元素提取结构化数据 |
| `browser.snapshot` | - | 获取页面可访问性树 |
| `browser.screenshot` | - | 捕获页面截图 |
```yaml
# 示例：提取页面数据
steps:
- type: browser.extract
selector: ".username"
as: user
- type: browser.extract_all
selector: ".comment"
as: comments
- type: browser.extract_map
selector: ".repo-card"
as: repos
fields:
- selector: ".repo-name"
as: name
- selector: ".repo-stars"
as: stars
```
### 状态检查
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `browser.exists` | `selector` (必需), `as` | 检查元素是否存在 |
| `browser.wait` | `selector`, `timeout` | 等待元素出现 |
```yaml
# 示例：等待并验证
steps:
- type: browser.wait
selector: "#loading-complete"
timeout: 5000
- type: browser.exists
selector: ".error-message"
as: hasError
```
## Shell 步骤类型
Shell 步骤用于执行命令行操作，支持 shell 命令和交互式终端会话。
### 命令执行
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `shell.run` | `cmd` (必需), `cwd`, `env` | 执行单条 shell 命令 |
| `shell.exec` | `script` (必需) | 执行多行脚本 |
```yaml
# 示例：执行 shell 命令
steps:
- type: shell.run
cmd: "git status"
cwd: "/path/to/repo"
- type: shell.run
cmd: "npm test -- --coverage"
env:
CI: "true"
```
### 交互式终端
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `terminal.open` | `cmd` (必需) | 打开新的终端会话 |
| `terminal.run` | `cmd` (必需), `session` | 在终端会话中执行命令 |
```yaml
# 示例：交互式终端
steps:
- type: terminal.open
cmd: "ssh user@server"
- type: terminal.run
session: ssh_session
cmd: "ls -la"
```
## LLM 步骤类型
LLM 步骤利用 AI 能力进行内容生成、决策判断和文本分类。
### 内容生成
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `llm.generate` | `prompt` (必需), `as` | 根据提示词生成内容 |
| `llm.complete` | `text` (必需), `as` | 补全给定文本 |
```yaml
# 示例：生成内容
steps:
- type: llm.generate
prompt: |
为以下代码写一个简洁的提交信息：
{{diff}}
as: commit_message
- type: shell.run
cmd: "git commit -m '{{commit_message}}'"
```
### AI 决策
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `llm.decide` | `options` (必需), `context`, `as` | 从多个选项中选择 |
| `llm.classify` | `categories` (必需), `text`, `as` | 将文本分类到预定义类别 |
```yaml
# 示例：AI 决策
steps:
- type: llm.decide
context: "Issue 描述：{{issue.description}}"
options:
- value: bug
label: "Bug 修复"
- value: feature
label: "新功能"
- value: refactor
label: "代码重构"
as: issue_type
# 示例：文本分类
steps:
- type: llm.classify
text: "{{user_feedback}}"
categories:
- positive
- negative
- neutral
as: sentiment
```
## Control 步骤类型
Control 步骤用于控制工作流的执行流程，实现条件分支、重试机制和子工作流调用。
### 条件执行
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `control.if` | `condition` (必需), `then`, `else` | 条件分支执行 |
```yaml
# 示例：条件分支
steps:
- type: control.if
condition: "{{has_error}} == true"
then:
- type: issues.create
title: "Build Failed"
body: "Error: {{error_message}}"
else:
- type: shell.run
cmd: "echo 'Build successful'"
```
### 重试机制
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `control.retry` | `max_attempts` (必需), `steps`, `on_error` | 重试失败的步骤 |
```yaml
# 示例：重试机制
steps:
- type: control.retry
max_attempts: 3
steps:
- type: shell.run
cmd: "curl -f https://api.example.com/data"
on_error:
- type: llm.generate
prompt: "分析错误：{{error}}"
as: error_analysis
```
### 工作流停止与调用
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `control.stop` | `message` (必需), `status` | 停止工作流并返回消息 |
| `workflow.call` | `workflow_id` (必需), `params` | 调用子工作流 |
```yaml
# 示例：调用子工作流
steps:
- type: workflow.call
workflow_id: "send-notification"
params:
channel: "slack"
message: "部署完成"
```
## Data 步骤类型
Data 步骤用于变量管理和数据操作，实现工作流各步骤间的数据流转。
### 变量管理
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `variable.set` | `name` (必需), `value` (必需) | 设置变量值 |
| `variable.get` | `name` (必需), `as` | 获取变量值 |
```yaml
# 示例：变量操作
steps:
- type: variable.set
name: "counter"
value: 0
- type: variable.set
name: "counter"
value: "{{counter}} + 1"
```
### 数据提取
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `data.first` | `items` (必需), `as` | 获取数组第一个元素 |
| `data.get` | `path` (必需), `from`, `as` | 从嵌套数据结构获取值 |
```yaml
# 示例：数据提取
steps:
- type: data.first
items: "{{users}}"
as: first_user
- type: data.get
path: "user.profile.name"
from: "{{response}}"
as: user_name
```
## Git 步骤类型
Git 步骤通过 GitHub CLI (`gh`) 与 GitHub 平台交互，实现 PR 和 Issue 的自动化管理。
### Pull Request 操作
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `git.listPRs` | `repo`, `state`, `limit` | 列出 Pull Requests |
| `git.getPR` | `repo` (必需), `number` (必需) | 获取 PR 详情 |
| `git.createPR` | `title`, `head`, `base`, `body`, `repo` | 创建 Pull Request |
```yaml
# 示例：获取并创建 PR
steps:
- type: git.getPR
repo: "owner/repo"
number: 123
as: pr_details
- type: git.createPR
repo: "owner/repo"
title: "Add new feature"
head: "feature-branch"
base: "main"
body: "## Changes\n\n- Feature implementation"
```
### Issue 操作
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `git.listIssues` | `repo`, `state`, `labels`, `limit` | 列出 Issues |
| `git.getIssue` | `repo` (必需), `number` (必需) | 获取 Issue 详情 |
```yaml
# 示例：列出 Issues
steps:
- type: git.listIssues
repo: "owner/repo"
state: "open"
labels: "bug,high-priority"
limit: 10
as: issues
```
## Issues 步骤类型
Issues 步骤用于与任务追踪系统交互，支持多种提供商（GitHub Issues、Jira 等）。
### 搜索与获取
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `issues.search` | `query` (必需), `provider`, `as` | 搜索 Issues |
| `issues.get` | `id` (必需), `provider`, `as` | 获取 Issue 详情 |
```yaml
# 示例：搜索 Issues
steps:
- type: issues.search
query: "is:issue is:open label:bug"
provider: "github"
as: bug_issues
```
### 创建与管理
| 步骤类型 | 参数 | 说明 |
|----------|------|------|
| `issues.create` | `title` (必需), `body`, `labels`, `provider` | 创建 Issue |
| `issues.comment` | `id`, `body`, `provider` | 添加评论 |
| `issues.transition` | `id`, `status`, `provider` | 状态转换 |
| `issues.attach` | `id`, `file`, `provider` | 添加附件 |
```yaml
# 示例：创建 Issue 并添加评论
steps:
- type: issues.create
title: "Login button not working"
body: |
## Description
The login button doesn't respond on the dashboard page.
## Steps to Reproduce
1. Navigate to /dashboard
2. Click the login button
3. Nothing happens
labels:
- bug
- priority:high
as: created_issue
- type: issues.comment
id: "{{created_issue.id}}"
body: "This issue has been assigned to the engineering team."
```
## 变量插值
SideButton 支持 `{{variable}}` 语法在步骤间传递数据：
```yaml
steps:
- type: browser.extract
selector: ".title"
as: page_title
- type: llm.generate
prompt: "Summarize: {{page_title}}"
as: summary
- type: shell.run
cmd: "echo '{{summary}}' > /tmp/summary.txt"
```
## 步骤执行顺序
```
┌─────────────────────────────────────────┐
│ 工作流执行流程 │
├─────────────────────────────────────────┤
│ 1. 解析 YAML 定义 │
│ 2. 按顺序执行步骤（除非 control.* 改变） │
│ 3. 每个步骤产出输出到上下文 │
│ 4. 后续步骤通过 {{}} 引用前序输出 │
│ 5. 异常处理（根据 control.retry 配置） │
└─────────────────────────────────────────┘
```
## 最佳实践
### 1. 选择合适的步骤类型
优先使用专用 API 步骤而非浏览器自动化：
| 场景 | 推荐步骤 | 原因 |
|------|----------|------|
| 获取 PR 列表 | `git.listPRs` | API 调用更快、更可靠 |
| 文件修改 | `shell.run` | 直接操作文件系统 |
| 复杂交互 | `browser.*` | 通用浏览器控制 |
### 2. 错误处理
使用 `control.retry` 处理瞬时失败：
```yaml
steps:
- type: control.retry
max_attempts: 3
steps:
- type: shell.run
cmd: "curl -X POST https://api.example.com/upload"
```
### 3. 数据提取模式
使用结构化提取提高数据质量：
```yaml
steps:
- type: browser.extract_map
selector: ".item-card"
as: items
fields:
- selector: ".item-title"
as: title
- selector: ".item-price"
as: price
transform: "parseFloat"
```
## 相关资源
- [核心包文档](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)
- [服务器包文档](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)
- [工作流示例](../workflows/)
---
## 知识包系统
### 相关页面
相关主题：[MCP 服务器](#mcp-server), [工作流引擎](#workflow-engine)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/server/src/cli.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)
- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)
- [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)
- [packages/server/defaults/roles/software-engineer.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/software-engineer.md)
- [packages/server/defaults/roles/qa.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/qa.md)
- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)
# 知识包系统
## 概述
知识包（Knowledge Pack）是 SideButton 项目中用于向 AI 代理传授特定 Web 应用操作知识的可安装模块。知识包使 AI 代理能够理解目标应用的结构、交互方式和业务流程，从而执行自动化任务、代码审查、软件工程等复杂工作。
资料来源：[README.md:45-52](https://github.com/sidebutton/sidebutton/blob/main/README.md)
## 核心概念
### 什么是知识包
知识包是一种结构化的知识载体，包含以下关键组件：
| 组件类型 | 说明 |
|---------|------|
| **选择器（Selectors）** | UI 元素的 CSS 选择器 |
| **数据模型（Data Models）** | 实体类型、字段、关系、有效状态 |
| **状态机（State Machines）** | 各状态间的有效转换 |
| **角色剧本（Role Playbooks）** | 角色特定的操作流程（QA、SE、PM、SD） |
| **常见任务（Common Tasks）** | 分步骤操作流程、注意事项和边界情况 |
资料来源：[README.md:53-61](https://github.com/sidebutton/sidebutton/blob/main/README.md)
### 术语对应关系
在代码和 CLI 命令中，知识包也被称为 **Skill Packs**（技能包）。两者指代同一概念：
- CLI 命令使用 `skill-packs` 作为 API 端点
- 配置字段如 `installedAt` 用于跟踪安装时间
- 配置文件使用 `manifest` 元数据格式
资料来源：[packages/server/src/cli.ts:89-97](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)
## 系统架构
### 整体架构图
```mermaid
graph TD
A[用户/AI Agent] --> B[SideButton CLI]
A --> C[Web Dashboard]
A --> D[MCP Client]
B --> E[CLI 命令处理]
C --> F[Web UI]
D --> G[MCP Protocol]
E --> H[知识包管理模块]
G --> H
H --> I[本地存储]
H --> J[远程注册表]
H --> K[Workflow 引擎]
I --> L[~/.sidebutton]
J --> M[sidebutton.com registry]
K --> N[浏览器自动化]
K --> O[Shell 执行]
K --> P[LLM 交互]
```
### 知识包安装流程
```mermaid
sequenceDiagram
participant User as 用户
participant CLI as SideButton CLI
participant Local as 本地存储
participant Remote as 远程注册表
User->>CLI: sidebutton install
CLI->>CLI: 检测源类型
alt 本地路径
CLI->>Local: 读取本地目录
else Git URL / 远程名称
CLI->>Remote: 获取知识包
end
Remote-->>CLI: 返回 manifest + files
CLI->>Local: 安装到配置目录
CLI->>User: 显示安装结果
```
## CLI 命令参考
### 安装命令
```bash
# 从本地目录安装
sidebutton install ./my-pack
# 从 Git URL 安装
sidebutton install https://github.com/org/skill-packs
# 从注册表名称安装
sidebutton install app.example.com
# 查看已安装列表
sidebutton install --list
```
资料来源：[packages/server/src/cli.ts:125-135](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)
### 注册表管理命令
```bash
# 添加注册表并安装所有知识包
sidebutton registry add
# 更新已安装的包
sidebutton registry update [name]
# 移除注册表及关联的知识包
sidebutton registry remove
# 列出所有注册表及包数量
sidebutton registry list
```
资料来源：[packages/server/README.md:35-40](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)
### 搜索与发布命令
```bash
# 跨注册表搜索知识包
sidebutton search [query]
# 发布知识包到注册表
sidebutton publish
```
资料来源：[packages/sidebutton/README.md:28-30](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)
### 知识包开发命令
```bash
# 初始化新的知识包
sidebutton init [domain]
# 验证知识包配置
sidebutton validate [path]
```
资料来源：[packages/sidebutton/README.md:33-37](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)
## 发布 API
知识包通过 REST API 发布到远程注册表：
```typescript
POST /api/skill-packs/publish
Headers:
Content-Type: application/json
Authorization: Bearer
Body:
{
domain: string, // 域名，如 "github.com"
name: string, // 显示名称
version: string, // 版本号
description: string, // 描述
tagline: string, // 简短标语
modules: array, // 模块列表
roles: array, // 角色定义
category: string, // 分类
manifest: object, // 完整元数据
files: array // 知识包文件
}
```
资料来源：[packages/server/src/cli.ts:89-110](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)
### 发布响应处理
| HTTP 状态码 | 含义 | 处理方式 |
|------------|------|---------|
| 200 | 发布成功 | 输出版本号和地址 |
| 401 | 未认证 | 提示运行 `sidebutton login` |
| 403 | 无权限 | 提示你不是该域名的所有者 |
| 其他 | 发布失败 | 显示错误信息 |
资料来源：[packages/server/src/cli.ts:111-125](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)
## 角色与知识包的关系
### 软件工程师角色
知识包为 AI 软件工程师角色提供以下能力：
**可用步骤类型：**
| 类别 | 步骤 |
|------|------|
| Issues | `issues.search`, `issues.get`, `issues.create`, `issues.transition`, `issues.comment`, `issues.attach` |
| Git | `git.listPRs`, `git.getPR`, `git.createPR`, `git.listIssues`, `git.getIssue` |
| 聊天 | `chat.readChannel`, `chat.readThread`, `chat.listChannels` |
| 终端 | `terminal.open`, `terminal.run` |
| LLM | `llm.generate`, `llm.decide`, `llm.classify` |
| 浏览器 | `navigate`, `snapshot`, `click`, `type`, `scroll`, `extract` |
| 工作流 | `workflow.call` |
| 数据 | `variable.set`, `data.first`, `data.get` |
资料来源：[packages/server/defaults/roles/software-engineer.md:45-55](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/software-engineer.md)
### QA 角色
知识包支持 QA 角色执行测试验证流程：
**测试流程：**
1. 导航到目标页面 (`navigate`)
2. 获取页面快照 (`snapshot`)
3. 验证元素存在
4. 测试交互（点击、输入）
5. 截图取证 (`screenshot`)
6. 执行工作流 (`run_workflow`)
7. 检查运行日志 (`get_run_log`)
资料来源：[packages/server/defaults/roles/qa.md:25-45](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/qa.md)
## 配置与存储
### 安装状态追踪
知识包安装后会记录以下元数据：
```json
{
"name": "github.com",
"title": "GitHub",
"version": "1.0.0",
"installedAt": "2024-01-15T10:30:00.000Z"
}
```
### 存储位置
- **Linux/macOS**: `~/.sidebutton/`
- **Windows**: `%USERPROFILE%\.sidebutton\`
### 安装结果输出格式
```
✓ github.com v1.2.0 — GitHub Integration
Installed: 2024/1/15
```
资料来源：[packages/server/src/cli.ts:140-148](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)
## 源类型检测
CLI 根据输入自动检测知识包来源类型：
```mermaid
graph TD
A[输入 source] --> B{包含 :// 或 .git 或 git@?}
B -->|是| C[Git URL]
B -->|否| D{以 . / ~ / \\ 开头或路径存在?}
D -->|是| E[本地路径]
D -->|否| F[注册表名称]
C --> G[克隆远程仓库]
E --> H[读取本地目录]
F --> I[查询远程注册表]
```
检测优先级：
1. Git URL（最高优先级）
2. 本地路径
3. 注册表名称
资料来源：[packages/server/src/cli.ts:149-155](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)
## 与其他系统的集成
### MCP 工具支持
知识包提供的知识可被 MCP 客户端使用：
| MCP 工具 | 用途 |
|---------|------|
| `run_workflow` | 按 ID 执行工作流 |
| `list_workflows` | 列出可用工作流 |
| `get_workflow` | 获取工作流 YAML 定义 |
| `snapshot` | 获取页面无障碍树 |
| `click`, `type`, `scroll` | 浏览器交互 |
| `extract`, `extract_all` | 内容提取 |
### 浏览器自动化
知识包中的选择器和数据模型驱动浏览器自动化操作：
```yaml
steps:
- type: browser.extract
selector: ".username"
as: user
- type: shell.run
cmd: "echo 'Hello, {{user}}!'"
```
## 常见工作流程
### 安装新知识包
```bash
# 1. 搜索可用的知识包
sidebutton search github
# 2. 安装
sidebutton install github.com
# 3. 验证安装
sidebutton install --list
```
### 开发自定义知识包
```bash
# 1. 初始化新知识包
sidebutton init myapp.com
# 2. 编辑 manifest.yaml 和模块文件
# 3. 验证配置
sidebutton validate ./myapp.com
# 4. 发布到注册表
sidebutton publish
```
### 管理注册表
```bash
# 添加团队注册表
sidebutton registry add https://github.com/team/skill-packs
# 更新所有包
sidebutton registry update
# 更新特定包
sidebutton registry update myapp.com
# 查看已注册表
sidebutton registry list
# 移除注册表
sidebutton registry remove myapp.com
```
## 错误处理
| 错误场景 | 错误信息 | 解决方案 |
|---------|---------|---------|
| 目录不存在 | `Directory not found: /path/to/pack` | 检查路径是否正确 |
| 未认证 | `Not authenticated. Run 'sidebutton login' first.` | 执行登录命令 |
| 无发布权限 | `Permission denied — you are not the owner of this domain.` | 联系域名所有者 |
| 连接失败 | `Failed to connect to ` | 检查网络连接 |
资料来源：[packages/server/src/cli.ts:116-130](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)
## 相关资源
- [官方文档](https://docs.sidebutton.com)
- [知识包市场](https://sidebutton.com/skills)
- [GitHub 仓库](https://github.com/sidebutton/sidebutton)
- [Chrome 扩展商店](https://chromewebstore.google.com/detail/sidebutton/odaefhmdmgijnhdbkfagnlnmobphgkij)
---
## REST API
### 相关页面
相关主题：[MCP 服务器](#mcp-server), [工作流引擎](#workflow-engine)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)
- [packages/server/src/server.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/server.ts)
- [packages/server/src/cli.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)
- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)
- [packages/core/src/steps/llm.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/steps/llm.ts)
# REST API
SideButton 提供了一套完整的 REST API，用于外部系统集成和工作流远程执行。该 API 与本地 MCP（Model Context Protocol）提供相同的功能，支持从任何可以发送 HTTP 请求的环境触发工作流。
## 概述
REST API 是 SideButton 对外暴露的核心接口之一，提供 **60+ 个 JSON 端点**，支持以下主要功能：
- 工作流远程执行
- 运行日志查询
- 浏览器自动化操作
- MCP 工具调用
- 技能包发布与安装
通过 REST API，用户可以从 Webhook、Cron 任务、移动应用或其他运行在不同机器上的代理触发工作流，实现跨平台的自动化编排。
## 基础配置
### 服务地址
默认服务地址为 `http://localhost:9876`，可通过配置文件修改端口号：
```json
{
"port": 9876
}
```
### 认证方式
部分端点需要身份验证，使用 Bearer Token 方式：
```http
Authorization: Bearer
```
获取认证令牌：`sidebutton login`
## 核心端点
### 工作流执行
#### 运行工作流
执行指定 ID 的工作流：
```http
POST /api/workflows/{workflow_id}/run
Content-Type: application/json
{
"params": {
"ticket_id": "PROJ-123"
}
}
```
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| workflow_id | string | 是 | 工作流唯一标识符 |
| params | object | 否 | 传递给工作流的参数 |
#### 列出所有工作流
```http
GET /api/workflows
```
返回服务器上所有可用的工作流定义列表。
#### 获取工作流定义
```http
GET /api/workflows/{workflow_id}
```
获取指定工作流的完整 YAML 定义。
### 运行日志
#### 获取最新运行日志
```http
GET /api/runs/latest
```
返回最近一次工作流执行的完整日志。
#### 列出运行日志
```http
GET /api/runs
```
列出最近的工作流执行记录。
## MCP 端点
SideButton 服务器同时提供 MCP（Model Context Protocol）端点，支持 SSE（Server-Sent Events）连接：
```http
GET /localhost:9876/mcp
```
### MCP 工具列表
| 工具 | 功能 |
|------|------|
| `run_workflow` | 按 ID 执行工作流 |
| `list_workflows` | 列出所有可用工作流 |
| `get_workflow` | 获取工作流 YAML 定义 |
| `get_run_log` | 获取运行执行日志 |
| `list_run_logs` | 列出最近的工作流执行 |
| `get_browser_status` | 检查浏览器扩展连接状态 |
| `capture_page` | 捕获页面选择器 |
| `navigate` | 导航浏览器到指定 URL |
| `snapshot` | 获取页面可访问性快照 |
| `click` | 点击页面元素 |
| `type` | 向元素输入文本 |
| `scroll` | 滚动页面 |
| `screenshot` | 捕获页面截图 |
| `hover` | 鼠标悬停到元素 |
## 技能包发布
SideButton 支持将工作流发布到远程服务器进行共享。
### 发布端点
```http
POST /api/skill-packs/publish
Authorization: Bearer
Content-Type: application/json
{
"domain": "string",
"name": "string",
"version": "string",
"description": "string",
"tagline": "string",
"modules": [],
"roles": [],
"category": "string",
"manifest": {},
"files": []
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| domain | string | 技能包唯一域名 |
| name | string | 显示名称 |
| version | string | 版本号（语义化版本） |
| description | string | 详细描述 |
| tagline | string | 简短标语 |
| modules | array | 包含的工作流模块 |
| roles | array | 关联的角色定义 |
| category | string | 分类标签 |
| manifest | object | 完整清单对象 |
| files | array | 附加文件列表 |
### 错误处理
| 状态码 | 说明 |
|--------|------|
| 401 | 未认证，需先运行 `sidebutton login` |
| 403 | 无权限，非技能包所有者 |
| 其他 | 发布失败，显示具体错误信息 |
成功响应示例：
```json
{
"version": "1.0.0"
}
```
## 安装流程
### 安装工作流页面
```http
GET /install/{workflow_id}
```
返回安装确认页面，提示用户工作流已成功安装到库中。
### 安装成功页面
显示 HTML 成功页面，包含以下元素：
- 成功图标
- 工作流标题
- 返回网站按钮
- 打开仪表板链接
## 使用示例
### cURL
```bash
# 运行工作流
curl -X POST http://localhost:9876/api/workflows/check_ticket/run \
-H "Content-Type: application/json" \
-d '{"params": {"ticket_id": "PROJ-123"}}'
# 列出所有工作流
curl http://localhost:9876/api/workflows
# 获取最新运行日志
curl http://localhost:9876/api/runs/latest
```
### MCP 客户端配置
#### Claude Desktop
```json
{
"mcpServers": {
"sidebutton": {
"command": "npx",
"args": ["sidebutton", "--stdio"]
}
}
}
```
#### Cursor
```json
{
"mcpServers": {
"sidebutton": {
"url": "http://localhost:9876/mcp"
}
}
}
```
## 架构图
```mermaid
graph TD
A[外部系统] -->|HTTP Request| B[REST API]
A -->|MCP Protocol| C[MCP Endpoint]
B --> D{端点路由}
C --> D
D -->|/api/workflows| E[工作流控制器]
D -->|/api/runs| F[运行日志控制器]
D -->|/api/skill-packs| G[技能包控制器]
D -->|/install| H[安装页面]
E --> I[工作流引擎]
F --> J[日志存储]
G --> K[远程服务器]
I --> L[核心执行器]
L --> M[浏览器自动化]
L --> N[Shell 执行]
L --> O[LLM 调用]
```
## 集成场景
| 场景 | 说明 |
|------|------|
| Webhook 触发 | 接收外部事件自动执行工作流 |
| Cron 定时任务 | 定时执行数据采集或报告生成 |
| 移动应用 | 从移动端触发自动化任务 |
| 跨机器协同 | 在不同机器上运行工作流共享结果 |
| CI/CD 集成 | 在持续集成流程中调用自动化步骤 |
## 相关文档
- [工作流引擎](workflows.md) - 了解工作流的 YAML 编排
- [MCP 工具](mcp-tools.md) - 完整的 MCP 工具参考
- [浏览器自动化](browser.md) - 页面交互操作指南
- [LLM 集成](llm.md) - 大语言模型调用配置
---
## 工作流定义语法
### 相关页面
相关主题：[工作流引擎](#workflow-engine), [步骤类型参考](#step-types)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)
- [packages/server/defaults/roles/software-engineer.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/software-engineer.md)
- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)
- [packages/server/src/mcp/handler.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/handler.ts)
- [packages/server/src/providers/github.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/providers/github.ts)
- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)
# 工作流定义语法
## 概述
工作流定义语法（Workflow Definition Syntax）是 SideButton 自动化引擎的核心部分，用于以声明式 YAML 格式描述可执行的自动化步骤序列。每个工作流由唯一标识符、标题、参数定义和步骤数组组成，支持变量插值、控制流、条件分支和嵌套调用等高级特性。资料来源：[packages/core/README.md]()
## 工作流基本结构
工作流采用 YAML 格式定义，文件结构包含以下核心字段：
```yaml
id: workflow_unique_id # 唯一标识符（小写字母、数字、连字符）
title: "工作流显示名称" # 人类可读标题
description: "工作流描述" # 可选描述
category: "category_name" # 可选分类
params: # 可选参数定义
param_name: param_type
steps:
- type: step_type # 步骤类型
# 步骤配置...
```
### 核心字段说明
| 字段 | 必填 | 类型 | 说明 |
|------|------|------|------|
| `id` | 是 | string | 工作流唯一标识符 |
| `title` | 是 | string | 显示名称 |
| `description` | 否 | string | 工作流描述 |
| `category` | 否 | string | 分类标签 |
| `params` | 否 | object | 参数定义，键为参数名，值为参数类型 |
| `steps` | 是 | array | 步骤数组 |
资料来源：[packages/server/src/mcp/handler.ts]()
资料来源：[README.md]()
## 步骤类型体系
SideButton 将步骤分为六大类别，每个类别提供不同的自动化能力：
### 步骤类型总览
| 类别 | 步骤类型 | 说明 |
|------|----------|------|
| **Browser 浏览器** | `navigate`, `click`, `type`, `scroll`, `hover`, `wait`, `extract`, `extractAll`, `exists`, `key` | 网页自动化操作 |
| **Shell 终端** | `shell.run`, `terminal.open`, `terminal.run` | 命令行和终端操作 |
| **LLM 大语言模型** | `llm.classify`, `llm.generate` | AI 驱动的决策和生成 |
| **Control 控制流** | `control.if`, `control.retry`, `control.stop`, `workflow.call` | 流程控制 |
| **Data 数据处理** | `data.first` | 数据提取和转换 |
资料来源：[packages/core/README.md]()
资料来源：[packages/server/defaults/roles/software-engineer.md]()
## 浏览器步骤
浏览器步骤提供对网页的完全自动化控制，通过 CSS 选择器精确定位元素：
### 基础导航与交互
```yaml
steps:
- type: browser.navigate
url: "https://example.com/page"
- type: browser.click
selector: "#submit-button"
- type: browser.type
selector: "input[name='username']"
text: "user@example.com"
- type: browser.scroll
direction: down
amount: 300
- type: browser.hover
selector: ".menu-item"
```
### 内容提取
```yaml
steps:
- type: browser.extract
selector: ".status-field"
as: current_status # 将结果存储为变量
- type: browser.extractAll
selector: "table tr"
as: table_rows
- type: browser.extract_map
selector: ".card"
map:
title: ".card-title"
url: "a@href"
as: cards
```
### 条件检查
```yaml
steps:
- type: browser.exists
selector: "#error-message"
as: has_error
```
资料来源：[packages/server/defaults/roles/software-engineer.md]()
资料来源：[packages/server/README.md]()
## Shell 步骤
Shell 步骤用于执行命令行操作和脚本：
```yaml
steps:
- type: shell.run
cmd: "git status"
- type: shell.run
cmd: "npm run build"
cwd: "/path/to/project"
- type: terminal.open
- type: terminal.run
cmd: "echo 'Hello World'"
```
## LLM 步骤
LLM 步骤集成了大语言模型能力，支持本地 Ollama 或云端服务商（OpenAI、Anthropic、Google）：
### 文本生成
```yaml
steps:
- type: llm.generate
prompt: "为以下功能写一段简洁的描述：{{feature_name}}"
as: description
```
### 分类决策
```yaml
steps:
- type: llm.classify
prompt: "这个 Issue 应该关闭还是保持开放？上下文：{{issue_status}}"
classes: [close, keep_open]
as: decision
```
资料来源：[README.md]()
## 控制流步骤
### 条件分支
```yaml
steps:
- type: control.if
condition: "{{current_status}} != 'Done'"
then:
- type: llm.classify
prompt: "应该关闭这个工单吗？"
classes: [close, keep_open]
as: decision
```
### 重试机制
```yaml
steps:
- type: control.retry
max_attempts: 3
delay: 1000
steps:
- type: shell.run
cmd: "curl -f https://api.example.com/health"
```
### 停止工作流
```yaml
steps:
- type: control.stop
message: "前置条件未满足，终止执行"
```
### 嵌套调用
```yaml
steps:
- type: workflow.call
workflow_id: "send_notification"
params:
message: "{{notification_message}}"
```
资料来源：[packages/server/defaults/roles/software-engineer.md]()
## 数据处理步骤
```yaml
steps:
- type: data.first
from: "{{table_rows}}"
as: first_row
```
## 变量系统
### 变量插值语法
使用双花括号 `{{variable}}` 语法引用变量：
```yaml
steps:
- type: browser.extract
selector: ".username"
as: user
- type: shell.run
cmd: "echo 'Hello, {{user}}!'"
```
### 变量来源
变量可通过以下方式定义：
| 来源 | 说明 |
|------|------|
| `extract` 步骤的 `as` 参数 | 从页面提取的内容 |
| `params` 参数 | 工作流调用时传入的参数 |
| `llm.classify` 的 `as` 参数 | LLM 分类结果 |
| 前序步骤输出 | 任何返回数据的步骤 |
资料来源：[README.md]()
## 工作流示例
### GitHub 创建 Release 工作流
```yaml
id: github-create-release
title: "创建 GitHub Release"
description: "在 GitHub 仓库创建一个新的 Release"
category: GitHub
params:
repo: string
tag: string
name: string
body: string
steps:
- type: git.createRelease
repo: "{{repo}}"
tag: "{{tag}}"
name: "{{name}}"
body: "{{body}}"
```
### Jira 工单状态检查与分类
```yaml
id: check_ticket_status
title: "检查 Jira 工单并分类"
category: Jira
params:
ticket_id: string
steps:
- type: browser.navigate
url: "https://your-org.atlassian.net/browse/{{ticket_id}}"
- type: browser.extract
selector: "[data-testid='status-field']"
as: current_status
- type: control.if
condition: "{{current_status}} != 'Done'"
then:
- type: llm.classify
prompt: "应该关闭这个工单吗？上下文：{{current_status}}"
classes: [close, keep_open]
as: decision
```
资料来源：[README.md]()
## 工作流执行流程
```mermaid
graph TD
A[开始执行工作流] --> B[加载工作流定义]
B --> C{检查参数}
C -->|参数完整| D[执行步骤 1]
C -->|参数缺失| E[报告错误并终止]
D --> F{步骤类型}
F -->|Browser| G[浏览器自动化]
F -->|Shell| H[执行命令]
F -->|LLM| I[调用 AI]
F -->|Control| J[控制流处理]
F -->|Data| K[数据处理]
G --> L[提取变量]
H --> L
I --> L
J --> M{控制类型}
M -->|if| N[条件判断]
M -->|retry| O[重试循环]
M -->|stop| P[终止工作流]
M -->|call| Q[嵌套调用]
N --> R{条件结果}
R -->|true| S[执行 then 分支]
R -->|false| T[跳过或执行 else]
K --> U{还有更多步骤?}
L --> U
S --> U
T --> U
Q --> U
U -->|是| D
U -->|否| V[记录执行日志]
P --> V
E --> W[输出错误信息]
```
## 参数类型
| 类型 | 说明 | 示例 |
|------|------|------|
| `string` | 字符串文本 | `"hello"` |
| `number` | 数值 | `42` |
| `boolean` | 布尔值 | `true` |
| `array` | 数组 | `[item1, item2]` |
## 最佳实践
1. **使用描述性 ID**：工作流 ID 应简洁明了，便于 MCP 调用
2. **参数验证**：在 `params` 中明确定义参数类型，确保输入正确
3. **变量命名**：使用有意义的变量名，如 `current_status` 而非 `val1`
4. **条件分支**：复杂条件使用 `control.if`，避免嵌套过深
5. **错误处理**：使用 `control.retry` 处理可能失败的步骤
## 相关资源
- [完整文档](https://docs.sidebutton.com)
- [@sidebutton/core](https://www.npmjs.com/package/@sidebutton/core) - 核心工作流引擎
- [@sidebutton/server](https://www.npmjs.com/package/@sidebutton/server) - MCP 服务器与 REST API
---
---
## Doramagic 踩坑日志
项目：sidebutton/sidebutton
摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Add control.foreach step type for iterating over lists。
## 1. 安装坑 · 来源证据：Add control.foreach step type for iterating over lists
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add control.foreach step type for iterating over lists
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d7567e53b1794e828bb3342cb0699f6f | https://github.com/sidebutton/sidebutton/issues/1 | 来源类型 github_issue 暴露的待验证使用条件。
## 2. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | README/documentation is current enough for a first validation pass.
## 3. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | last_activity_observed missing
## 4. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | no_demo; severity=medium
## 5. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | No sandbox install has been executed yet; downstream must verify before user use.
## 6. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | no_demo; severity=medium
## 7. 安全/权限坑 · 来源证据：Native