项目简介

SideButton 是一个开源的 AI Agent 平台，专注于为 AI 代理提供浏览器自动化能力、工作流编排和领域知识管理。该项目通过 MCP（Model Context Protocol）服务器提供浏览器工具集，支持使用 YAML 定义自动化工作流程，并提供知识包（Knowledge Packs）机制来封装特定 Web 应用的领域专业知识。

资料来源：README.md:1

核心定位

SideButton 的主要目标是为 AI 代理提供与 Web 应用交互的标准化能力，使 AI 代理能够执行以下任务：

• 浏览器操作（导航、点击、输入、截图、提取数据）
• 工作流自动化执行
• 跨平台工具集成
• 领域知识获取与推理

资料来源：AGENTS.md:3

核心特性

主要功能模块

资料来源：README.md:40-44

浏览器自动化能力

SideButton 通过 Chrome 扩展实现真实的 DOM 访问，采用 CSS 选择器而非像素坐标或截图的方式进行元素定位。这种方式确保了自动化脚本的稳定性和可维护性。

支持的浏览器命令包括：

• navigate - 导航到指定 URL
• click - 点击页面元素
• type - 向输入框输入文本
• snapshot - 获取页面可访问性树
• extract / extractAll - 提取文本内容
• screenshot - 页面截图
• scroll - 页面滚动
• hover - 悬停操作

资料来源：README.md:42

系统架构

整体架构图

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 架构组织代码，主要包含以下包：

资料来源：AGENTS.md:17-23

技术栈

核心技术选型

• 语言: TypeScript（严格模式）
• 模块系统: ES modules
• 包管理器: pnpm
• 通信协议: MCP (Model Context Protocol)

MCP 工具集

资料来源：README.md:60-77

安装与部署

环境要求

• Node.js（建议使用最新稳定版本）
• Chrome 浏览器（用于浏览器自动化功能）

安装方式

#### 通过 npm 全局安装

npm install -g sidebutton

#### 通过 npx 直接运行

npx sidebutton@latest

#### 本地开发安装

git clone https://github.com/sidebutton/sidebutton.git
cd sidebutton
pnpm install
pnpm build
pnpm start

资料来源：AGENTS.md:9-15

构建与测试

资料来源：AGENTS.md:12-16

工作流系统

工作流定义

SideButton 使用 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

步骤类型分类

资料来源：packages/core/README.md:25-31

变量插值

工作流支持使用 {{variable}} 语法引用提取的值或参数：

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 应用。

知识包内容

资料来源：README.md:103-111

知识包命令

资料来源：packages/sidebutton/README.md:43-56

MCP 集成配置

Claude Desktop 配置

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "sidebutton": {
      "command": "npx",
      "args": ["sidebutton", "--stdio"]
    }
  }
}

Claude Code 配置

添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "sidebutton": {
      "type": "sse",
      "url": "http://localhost:9876/mcp"
    }
  }
}

Cursor 配置

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "sidebutton": {
      "url": "http://localhost:9876/mcp"
    }
  }
}

资料来源：README.md:25-51

Chrome 扩展

安装方式

从 Chrome Web Store 安装 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

相关资源

资料来源：AGENTS.md:48-51, packages/sidebutton/README.md:64-68

架构概览

SideButton 项目采用 pnpm workspaces 实现多包管理，主要包含以下核心包：

资料来源：pnpm-workspace.yaml

系统架构图

graph TB
    subgraph Client["客户端层"]
        CLI[CLI 工具<br/>sidebutton]
        BrowserExt[Chrome 扩展]
        AI_Agent[AI 代理<br/>Claude/Cursor]
    end

    subgraph Server["服务端层"]
        MCP_Server[MCP Server<br/>:9876]
        Dashboard[Web Dashboard<br/>Vite SPA]
        WorkflowEngine[工作流引擎<br/>@sidebutton/core]
        Providers[Providers<br/>GitHub/Browser/Shell]
    end

    subgraph Storage["数据层"]
        DB[(本地数据库<br/>SQLite/JSON)]
        Workflows[工作流定义<br/>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

主要 API 端点：

工作流引擎

工作流引擎负责解析和执行 YAML 格式的工作流定义文件。

执行流程：

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

Step 类型体系：

Provider 架构

Provider 是工作流引擎与外部系统交互的桥梁，采用策略模式设计。

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

// 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

主要功能页面：

CLI 工具

CLI 是用户与系统交互的主要入口之一，整合了所有核心功能。

命令结构：

sidebutton                           # 启动服务器（默认端口 9876）
sidebutton --stdio                   # 以 stdio 传输启动（Claude Desktop 集成）
sidebutton -p 8080                   # 自定义端口

sidebutton list                      # 列出可用工作流
sidebutton run <id>                  # 执行指定工作流
sidebutton status                    # 检查服务器状态

# Knowledge Packs 管理
sidebutton registry add <path|url>   # 添加知识包注册源
sidebutton registry update [name]    # 更新已安装的包
sidebutton publish                   # 发布知识包到远程注册源

资料来源：packages/server/src/cli.ts

MCP 协议集成

SideButton 通过 MCP 协议实现与 AI 助手（Claude Desktop、Cursor 等）的深度集成。

连接配置

Claude Desktop 配置：

{
  "mcpServers": {
    "sidebutton": {
      "command": "npx",
      "args": ["sidebutton", "--stdio"]
    }
  }
}

Cursor 配置：

{
  "mcpServers": {
    "sidebutton": {
      "url": "http://localhost:9876/mcp"
    }
  }
}

资料来源：README.md

MCP 工具集

资料来源：packages/server/src/mcp/handler.ts

工作流执行模型

执行上下文

每个工作流执行都维护一个上下文对象，用于在步骤之间传递数据：

context:
  previousResult: 上一步骤的输出结果
  extracted: 从页面提取的数据
  variables: 用户定义的变量

变量插值

使用 {{variable}} 语法引用上下文中保存的值：

steps:
  - type: browser.extract
    selector: ".username"
    as: user
  - type: shell.run
    cmd: "echo 'Hello, {{user}}!'"

数据存储

系统采用本地文件存储方式：

扩展机制

Knowledge Packs（知识包）

知识包是按领域组织的可安装知识集合：

包含内容：

• Selectors — UI 元素的 CSS 选择器
• Data Models — 实体类型、字段、关系
• State Machines — 状态转换规则
• Role Playbooks — 角色特定的操作流程
• Common Tasks — 常见任务步骤和边界情况

安装命令：

sidebutton install github.com
sidebutton install atlassian.net

自定义 Provider

开发者可以通过扩展 Provider 接口来添加新的系统集成：

// Provider 接口伪代码
interface Provider {
  name: string;
  execute(step: Step, context: Context): Promise<Result>;
}

安全考虑

• MCP 端点支持认证机制（Bearer Token）
• 发布知识包需要验证所有权（通过 403 Permission denied 保护）
• 敏感操作（如 git.createPR）需要明确的参数传递

资料来源：packages/server/src/cli.ts

总结

SideButton 采用清晰的模块化架构：

1. 展示层：CLI 工具、Web Dashboard、Chrome 扩展
2. 服务层：MCP Server 统一入口，路由到工作流引擎
3. 执行层：工作流引擎解析 YAML，调度 Provider 执行
4. 集成层：Provider 封装与外部系统（GitHub、Browser、Shell）的交互

这种架构使得系统既可以通过命令行直接使用，也可以作为 AI 代理的工具后端，实现了灵活性和可扩展性的平衡。

概述

工作流引擎（Workflow Engine）是 SideButton 系统的核心组件，负责解析、调度和执行自动化工作流程。该引擎基于 YAML 配置文件驱动，通过模块化的步骤（Step）架构实现浏览器自动化、Shell 命令执行、LLM 推理以及控制流逻辑。引擎设计遵循声明式优先原则，允许用户通过 YAML 定义复杂的多步骤自动化任务，引擎自动处理变量插值、上下文传递和错误恢复等机制。资料来源：packages/core/README.md:1-10

核心架构

SideButton 工作流引擎采用分层架构，主要包含以下核心模块：

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/README.md:1-15

工作流定义

基本结构

工作流使用 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

字段说明

资料来源：packages/core/README.md:50-70

步骤类型详解

浏览器步骤（Browser Steps）

用于自动化网页操作，支持常见 DOM 交互：

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）

执行本地命令行操作：

steps:
  - type: shell.run
    cmd: "git status"
  - type: shell.run
    cmd: "npm test"

资料来源：packages/core/README.md:26-28

LLM 步骤（LLM Steps）

集成大语言模型进行推理和生成：

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）

管理工作流的执行逻辑：

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）

操作和转换数据：

资料来源：packages/core/README.md:38

变量系统

插值语法

使用双花括号 {{variable}} 语法引用变量：

steps:
  - type: browser.extract
    selector: ".username"
    as: user
  - type: shell.run
    cmd: "echo 'Hello, {{user}}!'"

变量作用域

变量在执行上下文中维护，遵循以下规则：

1. 步骤输出变量：使用 as 参数命名的变量在后续步骤中可用
2. 参数变量：工作流参数通过 {{paramName}} 传入
3. 嵌套属性：支持点号访问，如 {{user.name}}

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. 结果聚合：收集步骤执行日志和输出

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 助手调用：

{
  "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 包部署：

sidebutton                    # 启动服务器（默认端口 9876）
sidebutton --stdio           # 以 stdio 传输模式启动
sidebutton -p 8080           # 自定义端口

执行流程

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 支持扩展，需实现标准接口：

interface LLMProvider {
  classify(prompt: string, classes: string[]): Promise<string>;
  generate(prompt: string): Promise<string>;
}

相关资源

• 完整文档：https://docs.sidebutton.com
• GitHub 仓库：https://github.com/sidebutton/sidebutton
• 官方网站：https://sidebutton.com

概述

MCP（Model Context Protocol）服务器是 SideButton 的核心组件之一，扮演 AI 代理与浏览器自动化能力之间的桥梁角色。作为一个 MCP 兼容的服务器实现，它向 AI 助手（如 Claude Desktop、Cursor 等）暴露了一系列工具，使得 AI 能够通过标准化的协议执行浏览器操作、工作流自动化以及其他系统任务。

SideButton 的 MCP 服务器基于 TypeScript 构建，采用 Fastify 作为底层 HTTP 框架，并支持多种传输协议以适应不同的集成场景。资料来源：packages/server/README.md

架构设计

整体架构

MCP 服务器采用了分层架构设计，主要包含以下几个核心模块：

传输协议支持

MCP 服务器支持两种主要的传输协议：

1. SSE（Server-Sent Events）：基于 HTTP 的长连接推送模式，适用于 Web 应用和远程连接场景
2. STDIO：标准输入输出模式，专为本地 CLI 工具和 AI 桌面应用集成设计

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 暴露功能，所有工具按照功能域进行分类组织。

工具分类总览

工作流工具

资料来源：packages/server/README.md

浏览器自动化工具

浏览器工具提供了对网页的完整控制能力：

集成配置

Cursor IDE 配置

在 ~/.cursor/mcp.json 中添加以下配置：

{
  "mcpServers": {
    "sidebutton": {
      "url": "http://localhost:9876/mcp"
    }
  }
}

Claude Desktop 配置

在 ~/Library/Application Support/Claude/claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "sidebutton": {
      "command": "npx",
      "args": ["sidebutton", "--stdio"]
    }
  }
}

资料来源：packages/sidebutton/README.md

工作流引擎集成

MCP 服务器与核心工作流引擎（@sidebutton/core）紧密集成。工作流引擎负责解析和执行 YAML 格式的工作流定义。

支持的步骤类型

资料来源：packages/core/README.md

工作流示例

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 仪表板：

sidebutton                           # 启动服务器（默认端口 9876）
sidebutton -p 8080                   # 自定义端口

STDIO 传输模式

适用于 AI 桌面应用的集成模式：

sidebutton --stdio                   # 启动 stdio 传输模式

服务器端点

与其他组件的关系

graph LR
    A[MCP 服务器] -->|调用| B[核心引擎<br>@sidebutton/core]
    A -->|WebSocket| C[Chrome 扩展]
    A -->|HTTP/WebSocket| D[仪表板 Web UI]
    B -->|执行| E[浏览器自动化]
    B -->|执行| F[Shell 命令]
    B -->|执行| G[LLM 调用]

技术栈

相关资源

• 完整文档
• GitHub 仓库
• 官网
• Chrome 扩展商店

功能概述

Chrome 扩展通过 WebSocket 与本地服务器建立持久连接，实现以下核心功能：

资料来源：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 服务器通信：

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

核心交互流程

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: 展示结果

浏览器命令详解

页面导航与快照

snapshot 命令返回结构化的 YAML 格式数据，每个可交互元素都有对应的引用编号，可用于后续的 click、type 等操作：

- ref: 1
  role: button
  name: "提交"
  focused: false
- ref: 2
  role: textbox
  name: "用户名"
  focused: true

资料来源：packages/server/defaults/roles/qa.md:68-74

元素定位与交互

SideButton 使用 CSS 选择器 进行元素定位，而非像素坐标或截图方式：

所有浏览器操作均基于真实 DOM 访问，确保与 React、Vue 等现代前端框架的完全兼容性。

资料来源：packages/server/README.md:44-53

表单处理

fill 命令专为 React 等虚拟 DOM 框架设计，能够正确触发 onChange 事件：

steps:
  - type: browser.fill
    selector: "#search-input"
    value: "SideButton"

资料来源：README.md:80-81

高级操作

evaluate 命令允许执行任意 JavaScript，可用于复杂的前端交互场景：

steps:
  - type: browser.evaluate
    script: "document.querySelector('.modal').style.display = 'none'"

扩展状态指示

Chrome 扩展图标会显示当前连接状态：

• 已连接：扩展图标高亮，浏览器扩展已成功连接服务器
• 未连接：扩展图标灰显，无法执行浏览器命令

验证连接状态

通过 MCP 工具 get_browser_status 可检查扩展连接：

{
  "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 浏览器操作示例

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 详情：

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 扩展命令通常作为工作流步骤的一部分执行：

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 可以在工作流中链式调用其他工作流，实现复杂的浏览器自动化场景。

相关文档

• 核心包文档 - 工作流引擎与步骤类型
• 服务器文档 - MCP 服务器与 REST API
• 贡献指南 - 开发工作流
• 完整文档 - 官方文档站点

概述

Dashboard 是 SideButton 项目的可视化控制中心，为用户提供工作流（Workflow）和快捷方式（Shortcut）的集中管理界面。它作为 Web 前端应用运行在浏览器中，通过 REST API 与后端服务器通信，实现工作流的创建、编辑、执行和监控功能。

资料来源：packages/dashboard/index.html:1-11

技术架构

组件结构

Dashboard 采用 Svelte 框架构建，核心组件结构如下：

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<br/>localhost:9876]
    H --> I[Workflow Engine<br/>@sidebutton/core]

入口文件

Dashboard 的入口点是 packages/dashboard/index.html，它加载 Svelte 应用并挂载到 #app 容器中：

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>SideButton</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

资料来源：packages/dashboard/index.html:1-11

核心视图

DashboardView 工作流视图

DashboardView 是仪表盘的主页面，负责展示快捷方式网格和工作流卡片。每个快捷方式卡片显示工作流标题和运行按钮，点击运行按钮可打开参数模态框（如果工作流需要参数）或立即执行。

资料来源：packages/server/defaults/roles/qa.md:32-45

#### 页面验证清单

WorkflowsView 工作流库视图

WorkflowsView 展示工作流库中的所有可用工作流，提供搜索、排序和分类筛选功能。

#### 功能特性

资料来源：packages/server/defaults/roles/qa.md:58-73

其他视图页面

资料来源：packages/server/defaults/roles/qa.md:48-67

API 集成

API 模块结构

packages/dashboard/src/lib/api.ts 封装了所有与后端服务器的通信接口，提供类型安全的 API 调用方法。

核心 API 端点

资料来源：packages/dashboard/src/lib/api.ts

健康检查流程

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 页面提供系统配置功能，包含多个子选项卡：

子选项卡结构

资料来源：packages/server/defaults/roles/qa.md:54-67

开发与部署

开发环境启动

pnpm dev           # 启动所有组件（热重载）
pnpm dev:server    # 仅启动服务器 :9876
pnpm dev:dashboard # 仅启动仪表盘 :5173
pnpm dev:core      # 核心库监视构建

资料来源：CONTRIBUTING.md

生产构建

Dashboard 作为 Vite 构建的单页应用，输出静态资源供服务器托管。

烟雾测试清单

在部署或更新后，应验证以下功能正常工作：

资料来源：packages/server/defaults/roles/qa.md:18-85

故障排除

概述

SideButton 工作流采用 YAML 格式定义步骤，支持七大类步骤类型：

Browser 步骤类型

Browser 步骤用于自动化浏览器操作，是 SideButton 的核心功能之一。通过 Chrome 扩展连接浏览器后，可以执行各种 DOM 操作。

页面导航与交互

# 示例：导航并登录
steps:
  - type: browser.navigate
    url: "https://github.com/login"
  - type: browser.type
    selector: "#login_field"
    text: "[email protected]"
  - type: browser.type
    selector: "#password"
    text: "{{password}}"
  - type: browser.click
    selector: "[type='submit']"

内容提取

# 示例：提取页面数据
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

状态检查

# 示例：等待并验证
steps:
  - type: browser.wait
    selector: "#loading-complete"
    timeout: 5000
  - type: browser.exists
    selector: ".error-message"
    as: hasError

Shell 步骤类型

Shell 步骤用于执行命令行操作，支持 shell 命令和交互式终端会话。

命令执行

# 示例：执行 shell 命令
steps:
  - type: shell.run
    cmd: "git status"
    cwd: "/path/to/repo"
  - type: shell.run
    cmd: "npm test -- --coverage"
    env:
      CI: "true"

交互式终端

# 示例：交互式终端
steps:
  - type: terminal.open
    cmd: "ssh user@server"
  - type: terminal.run
    session: ssh_session
    cmd: "ls -la"

LLM 步骤类型

LLM 步骤利用 AI 能力进行内容生成、决策判断和文本分类。

内容生成

# 示例：生成内容
steps:
  - type: llm.generate
    prompt: |
      为以下代码写一个简洁的提交信息：
      {{diff}}
    as: commit_message
  - type: shell.run
    cmd: "git commit -m '{{commit_message}}'"

AI 决策

# 示例：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 步骤用于控制工作流的执行流程，实现条件分支、重试机制和子工作流调用。

条件执行

# 示例：条件分支
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'"

重试机制

# 示例：重试机制
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

工作流停止与调用

# 示例：调用子工作流
steps:
  - type: workflow.call
    workflow_id: "send-notification"
    params:
      channel: "slack"
      message: "部署完成"

Data 步骤类型

Data 步骤用于变量管理和数据操作，实现工作流各步骤间的数据流转。

变量管理

# 示例：变量操作
steps:
  - type: variable.set
    name: "counter"
    value: 0
  - type: variable.set
    name: "counter"
    value: "{{counter}} + 1"

数据提取

# 示例：数据提取
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 操作

# 示例：获取并创建 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 操作

# 示例：列出 Issues
steps:
  - type: git.listIssues
    repo: "owner/repo"
    state: "open"
    labels: "bug,high-priority"
    limit: 10
    as: issues

Issues 步骤类型

Issues 步骤用于与任务追踪系统交互，支持多种提供商（GitHub Issues、Jira 等）。

搜索与获取

# 示例：搜索 Issues
steps:
  - type: issues.search
    query: "is:issue is:open label:bug"
    provider: "github"
    as: bug_issues

创建与管理

# 示例：创建 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}} 语法在步骤间传递数据：

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 步骤而非浏览器自动化：

2. 错误处理

使用 control.retry 处理瞬时失败：

steps:
  - type: control.retry
    max_attempts: 3
    steps:
      - type: shell.run
        cmd: "curl -X POST https://api.example.com/upload"

3. 数据提取模式

使用结构化提取提高数据质量：

steps:
  - type: browser.extract_map
    selector: ".item-card"
    as: items
    fields:
      - selector: ".item-title"
        as: title
      - selector: ".item-price"
        as: price
        transform: "parseFloat"

相关资源

• 核心包文档
• 服务器包文档
• 工作流示例

概述

知识包（Knowledge Pack）是 SideButton 项目中用于向 AI 代理传授特定 Web 应用操作知识的可安装模块。知识包使 AI 代理能够理解目标应用的结构、交互方式和业务流程，从而执行自动化任务、代码审查、软件工程等复杂工作。

资料来源：README.md:45-52

核心概念

什么是知识包

知识包是一种结构化的知识载体，包含以下关键组件：

资料来源：README.md:53-61

术语对应关系

在代码和 CLI 命令中，知识包也被称为 Skill Packs（技能包）。两者指代同一概念：

• CLI 命令使用 skill-packs 作为 API 端点
• 配置字段如 installedAt 用于跟踪安装时间
• 配置文件使用 manifest 元数据格式

资料来源：packages/server/src/cli.ts:89-97

系统架构

整体架构图

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 交互]

知识包安装流程

sequenceDiagram
    participant User as 用户
    participant CLI as SideButton CLI
    participant Local as 本地存储
    participant Remote as 远程注册表
    
    User->>CLI: sidebutton install <source>
    CLI->>CLI: 检测源类型
    alt 本地路径
        CLI->>Local: 读取本地目录
    else Git URL / 远程名称
        CLI->>Remote: 获取知识包
    end
    Remote-->>CLI: 返回 manifest + files
    CLI->>Local: 安装到配置目录
    CLI->>User: 显示安装结果

CLI 命令参考

安装命令

# 从本地目录安装
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

注册表管理命令

# 添加注册表并安装所有知识包
sidebutton registry add <path|url>

# 更新已安装的包
sidebutton registry update [name]

# 移除注册表及关联的知识包
sidebutton registry remove <name>

# 列出所有注册表及包数量
sidebutton registry list

资料来源：packages/server/README.md:35-40

搜索与发布命令

# 跨注册表搜索知识包
sidebutton search [query]

# 发布知识包到注册表
sidebutton publish

资料来源：packages/sidebutton/README.md:28-30

知识包开发命令

# 初始化新的知识包
sidebutton init [domain]

# 验证知识包配置
sidebutton validate [path]

资料来源：packages/sidebutton/README.md:33-37

发布 API

知识包通过 REST API 发布到远程注册表：

POST /api/skill-packs/publish

Headers:
  Content-Type: application/json
  Authorization: Bearer <token>

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

发布响应处理

资料来源：packages/server/src/cli.ts:111-125

角色与知识包的关系

软件工程师角色

知识包为 AI 软件工程师角色提供以下能力：

可用步骤类型：

资料来源：packages/server/defaults/roles/software-engineer.md:45-55

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

配置与存储

安装状态追踪

知识包安装后会记录以下元数据：

{
  "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

源类型检测

CLI 根据输入自动检测知识包来源类型：

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

与其他系统的集成

MCP 工具支持

知识包提供的知识可被 MCP 客户端使用：

浏览器自动化

知识包中的选择器和数据模型驱动浏览器自动化操作：

steps:
  - type: browser.extract
    selector: ".username"
    as: user
  - type: shell.run
    cmd: "echo 'Hello, {{user}}!'"

常见工作流程

安装新知识包

# 1. 搜索可用的知识包
sidebutton search github

# 2. 安装
sidebutton install github.com

# 3. 验证安装
sidebutton install --list

开发自定义知识包

# 1. 初始化新知识包
sidebutton init myapp.com

# 2. 编辑 manifest.yaml 和模块文件

# 3. 验证配置
sidebutton validate ./myapp.com

# 4. 发布到注册表
sidebutton publish

管理注册表

# 添加团队注册表
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

错误处理

资料来源：packages/server/src/cli.ts:116-130

相关资源

• 官方文档
• 知识包市场
• GitHub 仓库
• Chrome 扩展商店

概述

REST API 是 SideButton 对外暴露的核心接口之一，提供 60+ 个 JSON 端点，支持以下主要功能：

• 工作流远程执行
• 运行日志查询
• 浏览器自动化操作
• MCP 工具调用
• 技能包发布与安装

通过 REST API，用户可以从 Webhook、Cron 任务、移动应用或其他运行在不同机器上的代理触发工作流，实现跨平台的自动化编排。

基础配置

服务地址

默认服务地址为 http://localhost:9876，可通过配置文件修改端口号：

{
  "port": 9876
}

认证方式

部分端点需要身份验证，使用 Bearer Token 方式：

Authorization: Bearer <auth_token>

获取认证令牌：sidebutton login

核心端点

工作流执行

#### 运行工作流

执行指定 ID 的工作流：

POST /api/workflows/{workflow_id}/run
Content-Type: application/json

{
  "params": {
    "ticket_id": "PROJ-123"
  }
}

#### 列出所有工作流

GET /api/workflows

返回服务器上所有可用的工作流定义列表。

#### 获取工作流定义

GET /api/workflows/{workflow_id}

获取指定工作流的完整 YAML 定义。

运行日志

#### 获取最新运行日志

GET /api/runs/latest

返回最近一次工作流执行的完整日志。

#### 列出运行日志

GET /api/runs

列出最近的工作流执行记录。

MCP 端点

SideButton 服务器同时提供 MCP（Model Context Protocol）端点，支持 SSE（Server-Sent Events）连接：

GET /localhost:9876/mcp

MCP 工具列表

技能包发布

SideButton 支持将工作流发布到远程服务器进行共享。

发布端点

POST /api/skill-packs/publish
Authorization: Bearer <token>
Content-Type: application/json

{
  "domain": "string",
  "name": "string",
  "version": "string",
  "description": "string",
  "tagline": "string",
  "modules": [],
  "roles": [],
  "category": "string",
  "manifest": {},
  "files": []
}

错误处理

成功响应示例：

{
  "version": "1.0.0"
}

安装流程

安装工作流页面

GET /install/{workflow_id}

返回安装确认页面，提示用户工作流已成功安装到库中。

安装成功页面

显示 HTML 成功页面，包含以下元素：

• 成功图标
• 工作流标题
• 返回网站按钮
• 打开仪表板链接

使用示例

cURL

# 运行工作流
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

{
  "mcpServers": {
    "sidebutton": {
      "command": "npx",
      "args": ["sidebutton", "--stdio"]
    }
  }
}

#### Cursor

{
  "mcpServers": {
    "sidebutton": {
      "url": "http://localhost:9876/mcp"
    }
  }
}

架构图

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 调用]

集成场景

相关文档

• 工作流引擎 - 了解工作流的 YAML 编排
• MCP 工具 - 完整的 MCP 工具参考
• 浏览器自动化 - 页面交互操作指南
• LLM 集成 - 大语言模型调用配置

概述

工作流定义语法（Workflow Definition Syntax）是 SideButton 自动化引擎的核心部分，用于以声明式 YAML 格式描述可执行的自动化步骤序列。每个工作流由唯一标识符、标题、参数定义和步骤数组组成，支持变量插值、控制流、条件分支和嵌套调用等高级特性。资料来源：packages/core/README.md

工作流基本结构

工作流采用 YAML 格式定义，文件结构包含以下核心字段：

id: workflow_unique_id          # 唯一标识符（小写字母、数字、连字符）
title: "工作流显示名称"         # 人类可读标题
description: "工作流描述"       # 可选描述
category: "category_name"       # 可选分类
params:                         # 可选参数定义
  param_name: param_type
steps:
  - type: step_type             # 步骤类型
    # 步骤配置...

核心字段说明

资料来源：packages/server/src/mcp/handler.ts 资料来源：README.md

步骤类型体系

SideButton 将步骤分为六大类别，每个类别提供不同的自动化能力：

步骤类型总览

资料来源：packages/core/README.md 资料来源：packages/server/defaults/roles/software-engineer.md

浏览器步骤

浏览器步骤提供对网页的完全自动化控制，通过 CSS 选择器精确定位元素：

基础导航与交互

steps:
  - type: browser.navigate
    url: "https://example.com/page"
  
  - type: browser.click
    selector: "#submit-button"
  
  - type: browser.type
    selector: "input[name='username']"
    text: "[email protected]"
  
  - type: browser.scroll
    direction: down
    amount: 300
  
  - type: browser.hover
    selector: ".menu-item"

内容提取

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

条件检查

steps:
  - type: browser.exists
    selector: "#error-message"
    as: has_error

资料来源：packages/server/defaults/roles/software-engineer.md 资料来源：packages/server/README.md

Shell 步骤

Shell 步骤用于执行命令行操作和脚本：

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）：

文本生成

steps:
  - type: llm.generate
    prompt: "为以下功能写一段简洁的描述：{{feature_name}}"
    as: description

分类决策

steps:
  - type: llm.classify
    prompt: "这个 Issue 应该关闭还是保持开放？上下文：{{issue_status}}"
    classes: [close, keep_open]
    as: decision

资料来源：README.md

控制流步骤

条件分支

steps:
  - type: control.if
    condition: "{{current_status}} != 'Done'"
    then:
      - type: llm.classify
        prompt: "应该关闭这个工单吗？"
        classes: [close, keep_open]
        as: decision

重试机制

steps:
  - type: control.retry
    max_attempts: 3
    delay: 1000
    steps:
      - type: shell.run
        cmd: "curl -f https://api.example.com/health"

停止工作流

steps:
  - type: control.stop
    message: "前置条件未满足，终止执行"

嵌套调用

steps:
  - type: workflow.call
    workflow_id: "send_notification"
    params:
      message: "{{notification_message}}"

资料来源：packages/server/defaults/roles/software-engineer.md

数据处理步骤

steps:
  - type: data.first
    from: "{{table_rows}}"
    as: first_row

变量系统

变量插值语法

使用双花括号 {{variable}} 语法引用变量：

steps:
  - type: browser.extract
    selector: ".username"
    as: user
  
  - type: shell.run
    cmd: "echo 'Hello, {{user}}!'"

变量来源

变量可通过以下方式定义：

资料来源：README.md

工作流示例

GitHub 创建 Release 工作流

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 工单状态检查与分类

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

工作流执行流程

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[输出错误信息]

参数类型

最佳实践

1. 使用描述性 ID：工作流 ID 应简洁明了，便于 MCP 调用
2. 参数验证：在 params 中明确定义参数类型，确保输入正确
3. 变量命名：使用有意义的变量名，如 current_status 而非 val1
4. 条件分支：复杂条件使用 control.if，避免嵌套过深
5. 错误处理：使用 control.retry 处理可能失败的步骤

相关资源

• 完整文档
• @sidebutton/core - 核心工作流引擎
• @sidebutton/server - MCP 服务器与 REST API

Pitfall Log / 踩坑日志

项目：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 <select> elements cannot be programmatically selected via click/type tools

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Native <select> elements cannot be programmatically selected via click/type tools
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_a2eadefee45c45b2be1b8501c1a0724f | https://github.com/sidebutton/sidebutton/issues/12 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

8. 安全/权限坑 · 来源证据：v1.1.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_a9cfb55ebc664ee99dcc39773859d715 | https://github.com/sidebutton/sidebutton/releases/tag/v1.1.0 | 来源类型 github_release 暴露的待验证使用条件。

9. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | issue_or_pr_quality=unknown

10. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | release_recency=unknown