{ "canonical_name": "sidebutton/sidebutton", "compilation_id": "pack_cd522820949f48fdb11257a638046f92", "created_at": "2026-05-16T13:23:16.963388+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight", "recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `npx sidebutton@latest` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "npx sidebutton@latest", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_8b43c9aa4a504c6b82717ad203463cf6" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_9b94b481e08650701df475201552c189", "canonical_name": "sidebutton/sidebutton", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/sidebutton/sidebutton", "slug": "sidebutton", "source_packet_id": "phit_db724134ae8b4d25b8b04d81038d9dfa", "source_validation_id": "dval_a42593613c7b4563b6a4c76feea2c96f" }, "merchandising": { "best_for": "需要工具连接与集成能力，并使用 mcp_host的用户", "github_forks": 1, "github_stars": 5, "one_liner_en": "Open-source browser automation for AI agents. MCP server + Chrome extension + YAML workflow engine + knowledge packs. Give your AI agent a browser and domain expertise.", "one_liner_zh": "Open-source browser automation for AI agents. MCP server + Chrome extension + YAML workflow engine + knowledge packs. Give your AI agent a browser and domain expertise.", "primary_category": { "category_id": "tool-integrations", "confidence": "high", "name_en": "Tool Integrations", "name_zh": "工具连接与集成", "reason": "strong category phrase match from project identity and outcome" }, "target_user": "使用 mcp_host 等宿主 AI 的用户", "title_en": "sidebutton", "title_zh": "sidebutton 能力包", "visible_tags": [ { "label_en": "Browser Agents", "label_zh": "浏览器 Agent", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-browser-agents", "type": "product_domain" }, { "label_en": "Web Task Automation", "label_zh": "网页任务自动化", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-web-task-automation", "type": "user_job" }, { "label_en": "Structured Data Extraction", "label_zh": "结构化数据提取", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-structured-data-extraction", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Open Source Tool", "label_zh": "开源工具", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-open-source-tool", "type": "selection_signal" } ] }, "packet_id": "phit_db724134ae8b4d25b8b04d81038d9dfa", "page_model": { "artifacts": { "artifact_slug": "sidebutton", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "npx sidebutton@latest", "label": "Node.js / npx · 官方安装入口", "source": "https://github.com/sidebutton/sidebutton#readme", "verified": true } ], "display_tags": [ "浏览器 Agent", "网页任务自动化", "结构化数据提取", "节点式流程编排", "开源工具" ], "eyebrow": "工具连接与集成", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要工具连接与集成能力，并使用 mcp_host的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "Open-source browser automation for AI agents. MCP server + Chrome extension + YAML workflow engine + knowledge packs. Give your AI agent a browser and domain expertise." }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "mcp_host", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "mcp_config, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add control.foreach step type for iterating over lists", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_d7567e53b1794e828bb3342cb0699f6f | https://github.com/sidebutton/sidebutton/issues/1 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Add control.foreach step type for iterating over lists", "user_impact": "可能影响升级、迁移或版本选择。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "No sandbox install has been executed yet; downstream must verify before user use.", "category": "安全/权限坑", "evidence": [ "risks.safety_notes | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | No sandbox install has been executed yet; downstream must verify before user use." ], "severity": "medium", "suggested_check": "转成明确权限清单和安全审查提示。", "title": "存在安全注意事项", "user_impact": "用户安装前需要知道权限边界和敏感操作。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Native elements cannot be programmatically selected via click/type tools", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_a9cfb55ebc664ee99dcc39773859d715 | https://github.com/sidebutton/sidebutton/releases/tag/v1.1.0 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v1.1.0", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "issue_or_pr_quality=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | issue_or_pr_quality=unknown" ], "severity": "low", "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。", "title": "issue/PR 响应质量未知", "user_impact": "用户无法判断遇到问题后是否有人维护。" }, { "body": "release_recency=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | release_recency=unknown" ], "severity": "low", "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。", "title": "发布节奏不明确", "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Add control.foreach step type for iterating over lists。", "title": "踩坑日志" }, "snapshot": { "contributors": 1, "forks": 1, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 5 }, "source_url": "https://github.com/sidebutton/sidebutton", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "Open-source browser automation for AI agents. MCP server + Chrome extension + YAML workflow engine + knowledge packs. Give your AI agent a browser and domain expertise.", "title": "sidebutton 能力包", "trial_prompt": "# sidebutton - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for sidebutton/sidebutton.\n\nProject:\n- Name: sidebutton\n- Repository: https://github.com/sidebutton/sidebutton\n- Summary: Open-source browser automation for AI agents. MCP server + Chrome extension + YAML workflow engine + knowledge packs. Give your AI agent a browser and domain expertise.\n- Host target: mcp_host\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Open-source browser automation for AI agents. MCP server + Chrome extension + YAML workflow engine + knowledge packs. Give your AI agent a browser and domain expertise.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Open-source browser automation for AI agents. MCP server + Chrome extension + YAML workflow engine + knowledge packs. Give your AI agent a browser and domain expertise.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. introduction: Introduction to SideButton. Produce one small intermediate artifact and wait for confirmation.\n2. getting-started: Getting Started. Produce one small intermediate artifact and wait for confirmation.\n3. architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. workflow-engine: Workflow Engine. Produce one small intermediate artifact and wait for confirmation.\n5. step-types: Step Types Reference. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/sidebutton/sidebutton\n- https://github.com/sidebutton/sidebutton#readme\n- README.md\n- LICENSING.md\n- SECURITY.md\n- package.json\n- packages/server/README.md\n- packages/sidebutton/README.md\n- packages/server/src/server.ts\n- packages/core/src/executor.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n", "voices": [ { "body": "来源平台：github。github/github_issue: Add control.foreach step type for iterating over lists（https://github.com/sidebutton/sidebutton/issues/1）；github/github_issue: Native elements cannot be programmatically selected via click/t", "url": "https://github.com/sidebutton/sidebutton/issues/12" }, { "kind": "github_release", "source": "github", "title": "v1.1.0", "url": "https://github.com/sidebutton/sidebutton/releases/tag/v1.1.0" } ], "status": "已收录 3 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "工具连接与集成", "desc": "Open-source browser automation for AI agents. MCP server + Chrome extension + YAML workflow engine + knowledge packs. Give your AI agent a browser and domain expertise.", "effort": "安装已验证", "forks": 1, "icon": "link", "name": "sidebutton 能力包", "risk": "可发布", "slug": "sidebutton", "stars": 5, "tags": [ "浏览器 Agent", "网页任务自动化", "结构化数据提取", "节点式流程编排", "开源工具" ], "thumb": "gray", "type": "MCP 配置" }, "manual": { "markdown": "# https://github.com/sidebutton/sidebutton 项目说明书\n\n生成时间：2026-05-16 13:21:37 UTC\n\n## 目录\n\n- [Introduction to SideButton](#introduction)\n- [Getting Started](#getting-started)\n- [System Architecture](#architecture)\n- [Package Overview](#packages-overview)\n- [Workflow Engine](#workflow-engine)\n- [Step Types Reference](#step-types)\n- [Workflow Examples](#workflow-examples)\n- [MCP Server Integration](#mcp-server)\n- [Chrome Extension](#chrome-extension)\n- [Knowledge Packs](#knowledge-packs)\n\n\n\n## Introduction to SideButton\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started), [System Architecture](#architecture), [MCP Server Integration](#mcp-server)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n- [AGENTS.md](https://github.com/sidebutton/sidebutton/blob/main/AGENTS.md)\n- [CONTRIBUTING.md](https://github.com/sidebutton/sidebutton/blob/main/CONTRIBUTING.md)\n- [packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n- [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n
\n\n# Introduction to SideButton\n\nSideButton is an open-source AI agent platform that combines an MCP (Model Context Protocol) server with browser automation tools, a YAML-based workflow engine, and extensible knowledge packs for domain-specific expertise. It enables autonomous AI agents to interact with web applications through standardized browser controls, CLI operations, and pre-built workflow automations.\n\n资料来源：[AGENTS.md]()\n\n## High-Level Architecture\n\nSideButton follows a modular monorepo architecture with four primary packages working together to provide a complete automation platform.\n\n```mermaid\ngraph TB\n subgraph \"Client Layer\"\n EXT[\"Chrome Extension\"]\n CLI[\"CLI Tool\"]\n MCP[\"MCP Clients
(Claude, Cursor)\"]\n end\n \n subgraph \"packages/server\"\n API[\"REST API & Dashboard\"]\n MCP_SRV[\"MCP Endpoint\"]\n WS[\"WebSocket Bridge\"]\n end\n \n subgraph \"packages/core\"\n PARSER[\"Workflow Parser\"]\n EXEC[\"Step Executor\"]\n end\n \n subgraph \"packages/dashboard\"\n UI[\"Svelte Web UI\"]\n end\n \n EXT --> WS\n CLI --> API\n MCP --> MCP_SRV\n API --> EXEC\n MCP_SRV --> EXEC\n WS --> EXEC\n EXEC --> PARSER\n UI --> API\n```\n\n资料来源：[AGENTS.md](), [CONTRIBUTING.md]()\n\n## Package Structure\n\nThe repository is organized as a monorepo using pnpm workspaces. Each package has a focused responsibility.\n\n| Package | Purpose | Location |\n|---------|---------|----------|\n| `packages/core` | Workflow engine — parser, executor, and step implementations | Workflow execution runtime |\n| `packages/server` | HTTP server, MCP endpoint, CLI, and WebSocket bridge | API layer and server runtime |\n| `packages/dashboard` | Svelte web UI served at `localhost:9876` | User interface |\n| `packages/sidebutton` | CLI entry point for `npx sidebutton@latest` | Command-line interface |\n| `extension/` | Chrome extension (Manifest V3) | Browser automation |\n\n资料来源：[AGENTS.md](), [CONTRIBUTING.md]()\n\n## Core Concepts\n\n### Workflows\n\nWorkflows are YAML files that define sequences of steps for automation tasks. They can include browser interactions, shell commands, LLM calls, and control flow logic.\n\n```yaml\nname: example_workflow\nsteps:\n - type: navigate\n url: https://example.com\n \n - type: click\n selector: \"#submit-button\"\n \n - type: extract\n selector: \".result\"\n as: result\n```\n\n资料来源：[packages/core/README.md]()\n\n### Step Types\n\nSideButton provides multiple categories of steps for different automation needs.\n\n| Category | Steps | Purpose |\n|----------|-------|---------|\n| Browser | `navigate`, `click`, `type`, `scroll`, `hover`, `wait`, `extract`, `extractAll`, `exists`, `key` | Web page interaction |\n| Shell | `shell.run`, `terminal.open`, `terminal.run` | Command execution |\n| LLM | `llm.classify`, `llm.generate` | AI-powered operations |\n| Control | `control.if`, `control.retry`, `control.stop`, `workflow.call` | Flow control |\n| Data | `data.first` | Data manipulation |\n\n资料来源：[packages/core/README.md]()\n\n### Knowledge Packs\n\nKnowledge packs (also called skill packs) teach autonomous AI agents how specific web applications work. They bundle markdown files containing selectors, data models, state definitions, and agentic workflows per web app.\n\nKey capabilities of knowledge packs:\n\n- **Selectors**: CSS/XPath selectors for UI elements\n- **Data Models**: Structured data representations\n- **Agentic Workflows**: Pre-defined sequences for common tasks\n- **Role Playbooks**: Instructions for AI agent behavior\n\n资料来源：[packages/sidebutton/README.md](), [AGENTS.md]()\n\n## MCP Integration\n\nSideButton provides MCP (Model Context Protocol) server functionality for integration with AI coding assistants. The MCP tools allow AI agents to control browser automation and execute workflows programmatically.\n\n### Supported Clients\n\n| Client | Transport | Configuration |\n|--------|-----------|---------------|\n| Claude Desktop | stdio | `npx sidebutton --stdio` |\n| Claude Code | SSE | `http://localhost:9876/mcp` |\n| Cursor | HTTP | `http://localhost:9876/mcp` |\n\n资料来源：[packages/server/README.md](), [packages/sidebutton/README.md]()\n\n### MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `run_workflow` | Execute a workflow by ID |\n| `list_workflows` | List available workflows |\n| `get_workflow` | Get workflow YAML definition |\n| `get_run_log` | Get execution log for a run |\n| `list_run_logs` | List recent workflow executions |\n| `get_browser_status` | Check browser extension connection |\n| `capture_page` | Capture selectors from current page |\n| `navigate` | Navigate browser to URL |\n| `snapshot` | Get page accessibility snapshot |\n| `click` | Click an element |\n| `type` | Type text into an element |\n| `scroll` | Scroll the page |\n| `screenshot` | Capture page screenshot |\n| `hover` | Hover over element |\n| `extract` | Extract text from element |\n| `extract_all` | Extract all matching elements |\n\n资料来源：[packages/server/README.md](), [README.md]()\n\n## CLI Commands\n\nThe SideButton CLI provides commands for managing the server, workflows, and knowledge packs.\n\n```bash\nsidebutton # Start server (default port 9876)\nsidebutton --stdio # Start with stdio transport (Claude Desktop)\nsidebutton -p 8080 # Custom port\n\nsidebutton list # List available workflows\nsidebutton run # Run a workflow by ID\nsidebutton status # Check server status\n```\n\n### Knowledge Pack Management\n\n| Command | Description |\n|---------|-------------|\n| `sidebutton registry add ` | Register and install all knowledge packs |\n| `sidebutton registry update [name]` | Update installed packs from registry |\n| `sidebutton registry remove ` | Uninstall packs and remove registry |\n| `sidebutton registry list` | Show registries and pack counts |\n| `sidebutton search [query]` | Search packs across registries |\n| `sidebutton install ` | One-off knowledge pack install |\n| `sidebutton uninstall ` | Remove an installed knowledge pack |\n| `sidebutton init [domain]` | Scaffold a new knowledge pack |\n| `sidebutton validate [path]` | Lint and validate a knowledge pack |\n\n资料来源：[packages/sidebutton/README.md](), [packages/server/README.md]()\n\n## Quick Start\n\n### Published Package (No Clone Required)\n\n```bash\nnpx sidebutton@latest # starts server + dashboard on port 9876\n```\n\n资料来源：[AGENTS.md]()\n\n### Local Development Setup\n\n```bash\n# Clone the repo\ngit clone https://github.com/sidebutton/sidebutton.git\ncd sidebutton\n\n# Install dependencies\npnpm install\n\n# Build all packages\npnpm build\n\n# Start the server\npnpm start\n# Open http://localhost:9876\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n### Development Prerequisites\n\n| Requirement | Version |\n|-------------|---------|\n| Node.js | 20+ |\n| pnpm | 9.15+ |\n| Chrome | Latest (for browser automation) |\n\n资料来源：[CONTRIBUTING.md]()\n\n## Development Workflow\n\n### Running Components\n\nStart everything in watch mode with hot reload:\n\n```bash\npnpm dev\n```\n\nRun components individually:\n\n| Command | Description |\n|---------|-------------|\n| `pnpm dev:server` | Server with auto-restart on :9876 |\n| `pnpm dev:dashboard` | Dashboard with HMR on :5173 |\n| `pnpm build` | Build all packages |\n| `pnpm test` | Run all tests |\n\n资料来源：[CONTRIBUTING.md]()\n\n## Provider Preference\n\nWhen multiple integration methods exist, SideButton follows this preference order:\n\n```mermaid\ngraph LR\n A[\"API Provider\"] --> B[\"CLI Tool\"] --> C[\"Browser Automation\"]\n style A fill:#90EE90\n style B fill:#FFD700\n style C fill:#FFA07A\n```\n\n- **API** is fastest and most reliable\n- **CLI** provides programmatic access\n- **Browser automation** is the universal fallback\n\n资料来源：[packages/server/defaults/roles/software-engineer.md]()\n\n## Data Directories\n\n| Directory | What it is |\n|-----------|------------|\n| `packages/core/` | Workflow engine — parser, executor, step implementations |\n| `packages/server/` | HTTP server, MCP endpoint, CLI, WebSocket bridge |\n| `packages/dashboard/` | Svelte web UI served at localhost:9876 |\n| `extension/` | Chrome extension for browser automation |\n| `workflows/` | Public workflow library (YAML files) |\n| `actions/` | User-created workflows (gitignored) |\n\n资料来源：[CONTRIBUTING.md]()\n\n## Related Packages\n\n| Package | NPM Link |\n|---------|----------|\n| `@sidebutton/core` | [npmjs.com](https://www.npmjs.com/package/@sidebutton/core) |\n| `@sidebutton/server` | [npmjs.com](https://www.npmjs.com/package/@sidebutton/server) |\n\n资料来源：[packages/core/README.md](), [packages/server/README.md]()\n\n## External Resources\n\n| Resource | URL |\n|----------|-----|\n| Documentation | [docs.sidebutton.com](https://docs.sidebutton.com) |\n| GitHub Repository | [github.com/sidebutton/sidebutton](https://github.com/sidebutton/sidebutton) |\n| Website | [sidebutton.com](https://sidebutton.com) |\n| Knowledge Packs | [sidebutton.com/skills](https://sidebutton.com/skills) |\n\n## License\n\nSideButton is licensed under **Apache-2.0**.\n\n资料来源：[CONTRIBUTING.md](), [packages/core/README.md](), [packages/server/README.md]()\n\n---\n\n\n\n## Getting Started\n\n### 相关页面\n\n相关主题：[Introduction to SideButton](#introduction)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/sidebutton/sidebutton/blob/main/package.json)\n- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n- [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n- [packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n
\n\n# Getting Started\n\nSideButton is a Model Context Protocol (MCP) server that provides browser automation, workflow execution, and knowledge pack management capabilities. It enables AI assistants like Claude Desktop and Cursor to interact with web browsers, execute predefined workflows, and leverage domain-specific knowledge packs.\n\n## Prerequisites\n\nBefore installing SideButton, ensure your environment meets the following requirements:\n\n| Requirement | Version/Details |\n|-------------|-----------------|\n| Node.js | v18 or higher |\n| Package Manager | pnpm (recommended) or npm |\n| Browser | Chrome/Chromium (for browser automation features) |\n| OS | macOS, Windows, Linux |\n\n资料来源：[README.md:1-50](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n## Installation\n\n### Package Manager Installation\n\nInstall the SideButton CLI globally using your preferred package manager:\n\n```bash\n# Using npm\nnpm install -g sidebutton\n\n# Using pnpm\npnpm add -g sidebutton\n\n# Using yarn\nyarn global add sidebutton\n```\n\nVerify the installation:\n\n```bash\nsidebutton --version\n```\n\n### Development Setup (From Source)\n\nFor contributing or running the latest development version:\n\n```bash\n# Clone the repository\ngit clone https://github.com/sidebutton/sidebutton.git\ncd sidebutton\n\n# Install dependencies\npnpm install\n\n# Build all packages\npnpm build\n\n# Run CLI directly\npnpm cli --version\n```\n\n资料来源：[CONTRIBUTING.md:1-20](https://github.com/sidebutton/sidebutton/blob/main/CONTRIBUTING.md)\n\n## Quick Start\n\n### Starting the Server\n\nThe default command starts the SideButton server on port 9876:\n\n```bash\nsidebutton\n```\n\nTo use a custom port:\n\n```bash\nsidebutton -p 8080\n```\n\nThe server provides:\n- REST API endpoint\n- MCP (Model Context Protocol) endpoint\n- WebSocket connection for browser extension\n- Dashboard UI at `http://localhost:9876`\n\n资料来源：[packages/sidebutton/README.md:1-30](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n\n### Architecture Overview\n\n```mermaid\ngraph TD\n A[Claude Desktop / Cursor] -->|MCP Protocol| B[SideButton Server]\n A -->|stdio| B\n B -->|REST API| C[Dashboard UI]\n B -->|WebSocket| D[Chrome Extension]\n B -->|Execute| E[Workflow Engine]\n E -->|Browser Actions| F[Chrome Browser]\n E -->|CLI Tools| G[Shell/CLI]\n E -->|LLM Calls| H[OpenAI/Anthropic/Ollama]\n```\n\n## MCP Integration\n\nSideButton can be integrated with various AI coding assistants through the MCP protocol.\n\n### Claude Desktop\n\nAdd SideButton to your Claude Desktop configuration file at `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"sidebutton\": {\n \"command\": \"npx\",\n \"args\": [\"sidebutton\", \"--stdio\"]\n }\n }\n}\n```\n\nAfter adding the configuration, restart Claude Desktop to load the new MCP server.\n\n资料来源：[README.md:50-70](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n### Cursor\n\nAdd SideButton to your Cursor MCP configuration file at `~/.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"sidebutton\": {\n \"url\": \"http://localhost:9876/mcp\"\n }\n }\n}\n```\n\nEnsure the SideButton server is running before using Cursor with this configuration.\n\n资料来源：[packages/server/README.md:20-35](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n\n### Available MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `run_workflow` | Execute a workflow by ID |\n| `list_workflows` | List all available workflows |\n| `get_workflow` | Get workflow YAML definition |\n| `get_run_log` | Get execution log for a run |\n| `list_run_logs` | List recent workflow executions |\n| `get_browser_status` | Check browser extension connection |\n| `capture_page` | Capture selectors from current page |\n| `navigate` | Navigate browser to URL |\n| `snapshot` | Get page accessibility snapshot |\n| `click` | Click an element |\n| `type` | Type text into an element |\n| `scroll` | Scroll the page |\n| `screenshot` | Capture page screenshot |\n| `hover` | Hover over element |\n| `extract` | Extract text from element |\n| `extract_all` | Extract all matching elements |\n\n资料来源：[packages/server/README.md:40-60](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n\n## CLI Commands\n\n### Basic Commands\n\n```bash\n# Start the server (default port 9876)\nsidebutton\n\n# Start with stdio transport for Claude Desktop\nsidebutton --stdio\n\n# Start on custom port\nsidebutton -p 8080\n\n# List available workflows\nsidebutton list\n\n# Run a specific workflow\nsidebutton run \n\n# Check server status\nsidebutton status\n```\n\n### Knowledge Packs Management\n\n```bash\n# Add a registry\nsidebutton registry add \n\n# Update installed packs\nsidebutton registry update [name]\n\n# Remove a registry\nsidebutton registry remove \n\n# List all registries\nsidebutton registry list\n\n# Search packs across registries\nsidebutton search [query]\n\n# Install a knowledge pack\nsidebutton install \n\n# Uninstall a knowledge pack\nsidebutton uninstall \n```\n\n### Knowledge Pack Development\n\n```bash\n# Scaffold a new knowledge pack\nsidebutton init [domain]\n\n# Validate a knowledge pack\nsidebutton validate [path]\n\n# Publish to registry\nsidebutton publish\n```\n\n资料来源：[packages/sidebutton/README.md:60-100](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n\n## Dashboard\n\nThe SideButton dashboard provides a web-based UI for managing workflows and viewing execution history.\n\nAccess the dashboard at: `http://localhost:9876`\n\n### Dashboard Features\n\n- View and manage shortcuts\n- Browse available workflows\n- View execution logs\n- Add workflows to dashboard\n- Monitor browser extension status\n\n## Chrome Extension\n\nInstall the SideButton Chrome extension from the [Chrome Web Store](https://chromewebstore.google.com/detail/sidebutton/odaefhmdmgijnhdbkfagnlnmobphgkij).\n\n### Extension Features\n\n- 40+ browser commands for navigation, clicking, typing, extraction\n- Real DOM access via CSS selectors\n- Recording mode to capture manual actions as workflows\n- Embed action buttons into web pages\n- WebSocket connection for stable reconnection\n\n资料来源：[README.md:80-100](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n## Workflow Execution\n\n### Running a Workflow via CLI\n\n```bash\n# List all available workflows\nsidebutton list\n\n# Execute a workflow by ID\nsidebutton run \n\n# With parameters\nsidebutton run --param value\n```\n\n### Running a Workflow via MCP\n\nWhen connected to an MCP client like Claude Desktop:\n\n```\n# Use the run_workflow tool\nrun_workflow({ id: \"workflow-id\", params: { key: \"value\" } })\n```\n\n### Workflow Step Types\n\n| Category | Steps |\n|----------|-------|\n| Browser | `navigate`, `click`, `type`, `scroll`, `hover`, `wait`, `extract`, `extractAll`, `exists`, `key` |\n| Shell | `shell.run`, `terminal.open`, `terminal.run` |\n| LLM | `llm.classify`, `llm.generate` |\n| Control | `control.if`, `control.retry`, `control.stop`, `workflow.call` |\n| Data | `data.first` |\n\n资料来源：[packages/core/README.md:20-40](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n\n## Next Steps\n\n- Explore [Workflow Configuration](workflows.md) for creating custom automations\n- Set up [Knowledge Packs](knowledge-packs.md) for domain-specific capabilities\n- Configure [Provider Integrations](providers.md) for GitHub, Jira, and other tools\n- Review [Testing Guide](testing.md) for quality assurance workflows\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Package Overview](#packages-overview), [MCP Server Integration](#mcp-server), [Workflow Engine](#workflow-engine)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n- [packages/server/src/server.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/server.ts)\n- [packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n- [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n- [packages/server/src/mcp/handler.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/handler.ts)\n- [packages/server/src/cli.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)\n
\n\n# System Architecture\n\n## Overview\n\nSideButton is a browser automation and workflow orchestration platform that enables AI agents (such as Claude Desktop, Cursor) to interact with web applications through a unified MCP (Model Context Protocol) interface. The system combines browser automation, CLI tools, LLM capabilities, and external integrations into a coherent workflow execution engine.\n\nThe architecture follows a modular monorepo design with four primary packages:\n\n| Package | Purpose |\n|---------|---------|\n| `packages/sidebutton` | CLI entry point and CLI transport for MCP |\n| `packages/server` | Fastify-based MCP server with REST API and dashboard |\n| `packages/core` | Workflow definition parsing and execution engine |\n| `packages/dashboard` | React-based web UI for workflow management |\n\n资料来源：[README.md:1-50]()\n\n---\n\n## High-Level Architecture\n\n```mermaid\ngraph TB\n subgraph \"Client Layer\"\n CLI[\"CLI Client
sidebutton\"]\n BrowserExt[\"Chrome Extension\"]\n AI[\"AI Agents
(Claude, Cursor)\"]\n end\n\n subgraph \"Transport Layer\"\n Stdio[\"stdio\"]\n SSE[\"Server-Sent Events\"]\n WebSocket[\"WebSocket\"]\n HTTP[\"HTTP/REST\"]\n end\n\n subgraph \"Server Package\"\n MCP[\"MCP Handler
handler.ts\"]\n API[\"REST API
server.ts\"]\n Dashboard[\"Dashboard
React App\"]\n end\n\n subgraph \"Core Package\"\n Executor[\"Workflow Executor
executor.ts\"]\n Workflow[\"Workflow Parser\"]\n Steps[\"Step Handlers\"]\n end\n\n subgraph \"Providers\"\n GitHub[\"GitHub Provider\"]\n Browser[\"Browser Provider\"]\n LLM[\"LLM Provider\"]\n Shell[\"Shell Provider\"]\n end\n\n CLI --> Stdio\n BrowserExt --> WebSocket\n AI --> SSE\n AI --> HTTP\n\n Stdio --> MCP\n SSE --> MCP\n WebSocket --> MCP\n HTTP --> API\n\n MCP --> Executor\n API --> Executor\n\n Executor --> Workflow\n Workflow --> Steps\n\n Steps --> GitHub\n Steps --> Browser\n Steps --> LLM\n Steps --> Shell\n```\n\n资料来源：[packages/server/src/mcp/handler.ts:1-50]()\n\n---\n\n## Package Structure\n\n### CLI Package (`packages/sidebutton`)\n\nThe CLI package serves as the primary entry point for users and as an MCP transport adapter.\n\n**Key responsibilities:**\n\n- Parse CLI arguments and commands\n- Initialize and start the MCP server\n- Provide `stdio` transport for AI agent integration\n- Manage local configuration and authentication\n\n**Transport modes:**\n\n| Mode | Command | Use Case |\n|------|---------|----------|\n| HTTP Server | `sidebutton` | Dashboard + API access |\n| stdio | `sidebutton --stdio` | Claude Desktop integration |\n| Custom Port | `sidebutton -p 8080` | Development/custom deployments |\n\n资料来源：[packages/sidebutton/README.md:1-30]()\n\n### Server Package (`packages/server`)\n\nThe server package implements the MCP protocol and exposes REST APIs for workflow management.\n\n```mermaid\ngraph LR\n subgraph \"Server Components\"\n Fastify[\"Fastify Server\"]\n MCPHandler[\"MCP Handler\"]\n WorkflowManager[\"Workflow Manager\"]\n RunLogManager[\"Run Log Manager\"]\n end\n\n Fastify --> MCPHandler\n Fastify --> RESTAPI[\"REST API\"]\n MCPHandler --> WorkflowManager\n RESTAPI --> WorkflowManager\n WorkflowManager --> RunLogManager\n```\n\n**Core server configuration:**\n\n```typescript\ninterface ServerConfig {\n port: number; // Default: 9876\n actionsDir: string; // User-defined workflows\n workflowsDir: string; // Bundled workflows\n templatesDir: string; // Importable templates\n runLogsDir: string; // Execution logs\n}\n```\n\n资料来源：[packages/server/src/server.ts:1-50]()\n\n**REST API Endpoints:**\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/workflows` | GET | List all workflows |\n| `/api/workflows/:id` | GET | Get workflow definition |\n| `/api/workflows/:id/run` | POST | Execute a workflow |\n| `/api/templates` | GET | List available templates |\n| `/api/templates/:id/import` | POST | Import template to actions |\n| `/api/runs` | GET | List run logs |\n| `/api/runs/:id` | GET/DELETE | Get or delete run log |\n\n资料来源：[packages/server/src/server.ts:100-200]()\n\n### Core Package (`packages/core`)\n\nThe core package contains the workflow execution engine that parses YAML definitions and executes steps sequentially.\n\n**Workflow execution flow:**\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Executor\n participant StepHandler\n participant Provider\n\n Client->>Executor: executeWorkflow(workflow, context)\n Executor->>Executor: Parse YAML definition\n Loop For each step\n Executor->>StepHandler: Execute step\n StepHandler->>Provider: Provider action\n Provider-->>StepHandler: Result\n StepHandler-->>Executor: Step result\n End\n Executor-->>Client: Final result\n```\n\n资料来源：[packages/core/README.md:1-30]()\n\n**Step Types:**\n\n| Category | Steps | Description |\n|----------|-------|-------------|\n| Browser | `navigate`, `click`, `type`, `scroll`, `hover`, `wait`, `extract`, `extractAll`, `exists`, `key` | DOM interaction via Chrome extension |\n| Shell | `shell.run`, `terminal.open`, `terminal.run` | Execute CLI commands |\n| LLM | `llm.classify`, `llm.generate`, `llm.decide` | AI-driven operations |\n| Control | `control.if`, `control.retry`, `control.stop`, `workflow.call` | Flow control |\n| Data | `data.first`, `data.get`, `variable.set` | Data manipulation |\n\n资料来源：[packages/core/README.md:30-60]()\n\n### Dashboard Package (`packages/dashboard`)\n\nThe dashboard is a React/Vite application served by the Fastify server.\n\n**Structure:**\n\n```\npackages/dashboard/\n├── index.html # Entry HTML\n└── src/\n └── main.ts # React mount point\n```\n\nThe dashboard provides:\n\n- Workflow listing and management UI\n- Run log viewer\n- Settings configuration\n- Knowledge pack management\n\n资料来源：[packages/dashboard/index.html:1-20]()\n\n---\n\n## MCP Protocol Integration\n\n### MCP Tools\n\nThe MCP handler exposes tools for AI agent interaction:\n\n| Tool | Parameters | Description |\n|------|------------|-------------|\n| `run_workflow` | `id`, `params?` | Execute a workflow by ID |\n| `list_workflows` | `source?` | List workflows (actions/workflows/all) |\n| `get_workflow` | `id` | Get workflow YAML definition |\n| `get_run_log` | `id` | Get execution log for a run |\n| `list_run_logs` | `limit?` | List recent workflow executions |\n| `get_browser_status` | - | Check Chrome extension connection |\n| `capture_page` | `selectors?` | Capture CSS selectors from current page |\n| `navigate` | `url` | Navigate browser to URL |\n| `snapshot` | - | Get page accessibility snapshot |\n| `click` | `selector` | Click an element |\n| `type` | `selector`, `text` | Type text into an element |\n| `scroll` | `selector?`, `direction?` | Scroll the page |\n\n资料来源：[packages/server/README.md:40-60]()\n\n### MCP Handler Architecture\n\n```mermaid\ngraph TD\n MCP[\"MCP Handler\"]\n Tools[\"Tool Registry\"]\n Actions[\"Actions Loader\"]\n Workflows[\"Workflows Loader\"]\n Templates[\"Templates Loader\"]\n\n MCP --> Tools\n Tools --> Actions\n Tools --> Workflows\n Tools --> Templates\n\n Actions --> YAML[\"YAML Files
(~/.sidebutton/actions/)\"]\n Workflows --> Bundles[\"Bundled Workflows
(bundles/)\"]\n Templates --> Defaults[\"Default Templates
(defaults/templates/)\"]\n```\n\n资料来源：[packages/server/src/mcp/handler.ts:50-100]()\n\n---\n\n## Data Flow\n\n### Workflow Execution Pipeline\n\n```mermaid\ngraph LR\n A[Workflow YAML] --> B[Parse Steps]\n B --> C[Initialize Context]\n C --> D{For Each Step}\n D -->|Browser Step| E[Browser Provider]\n D -->|Shell Step| F[Shell Provider]\n D -->|LLM Step| G[LLM Provider]\n D -->|Control Step| H[Control Handler]\n E --> I[Record Result]\n F --> I\n G --> I\n H --> I\n I -->|More Steps| D\n I -->|Complete| J[Save Run Log]\n J --> K[Return Result]\n```\n\n### Variable Interpolation\n\nWorkflows support variable interpolation using `{{variable}}` syntax:\n\n```yaml\nsteps:\n - type: browser.extract\n selector: \".username\"\n as: user\n - type: shell.run\n cmd: \"echo 'Hello, {{user}}!'\"\n```\n\nVariables are stored in the execution context and can be:\n\n- Extracted from previous steps using `as` attribute\n- Passed as workflow parameters\n- Set explicitly via `variable.set` step\n\n资料来源：[README.md:150-180]()\n\n---\n\n## Provider System\n\nProviders are integration modules that execute specific step types.\n\n### GitHub Provider\n\nLocated at `packages/core/src/providers/github.ts`, the GitHub provider supports:\n\n| Operation | Methods |\n|-----------|---------|\n| Pull Requests | `listPRs`, `getPR`, `createPR` |\n| Issues | `listIssues`, `getIssue`, `createIssue`, `comment`, `transition` |\n| Repository | `getRepoInfo` |\n\n**Configuration:**\n\n```yaml\nproviders:\n github:\n type: github\n # Uses GitHub CLI (gh) for operations\n```\n\n资料来源：[packages/core/src/providers/github.ts:1-50]()\n\n### Browser Provider\n\nBrowser automation is handled via the Chrome extension:\n\n- **Protocol:** WebSocket (stable reconnection)\n- **Access:** Real DOM via CSS selectors (not pixel coordinates)\n- **Features:** Recording mode, embed buttons, page snapshots\n\n**Connection flow:**\n\n```mermaid\nsequenceDiagram\n participant Extension\n participant Server\n participant Browser\n\n Extension->>Server: Connect WebSocket\n Server->>Extension: Connection confirmed\n Extension->>Server: Send browser commands\n Server->>Browser: Execute via CDP\n Browser-->>Server: Result\n Server-->>Extension: Response\n```\n\n资料来源：[README.md:60-90]()\n\n---\n\n## Configuration System\n\n### Server Configuration\n\n```typescript\ninterface Config {\n port: number; // Default: 9876\n host: string; // Default: 'localhost'\n dataDir: string; // ~/.sidebutton\n actionsDir: string; // {dataDir}/actions\n workflowsDir: string; // {dataDir}/workflows\n templatesDir: string; // {dataDir}/templates\n runLogsDir: string; // {dataDir}/run-logs\n mcpPort: number; // Default: 9877\n}\n```\n\n### Environment Variables\n\nThe server supports environment variables for provider configuration:\n\n| Variable | Description |\n|----------|-------------|\n| `GITHUB_TOKEN` | GitHub authentication token |\n| `OPENAI_API_KEY` | OpenAI API key for LLM steps |\n| `ANTHROPIC_API_KEY` | Anthropic API key |\n| `SIDEBUTTON_API_BASE` | API base URL for browser extension |\n\n资料来源：[packages/server/src/server.ts:50-100]()\n\n---\n\n## Knowledge Packs System\n\nKnowledge packs (also called \"skill packs\") are installable domain-specific modules.\n\n### Structure\n\n```\n{domain}/\n├── manifest.yaml # Pack metadata\n├── selectors/ # CSS selectors for UI elements\n├── models/ # Data models and entity types\n├── states/ # State machine definitions\n├── roles/ # Role-specific playbooks\n└── tasks/ # Common task procedures\n```\n\n### Registry Commands\n\n| Command | Description |\n|---------|-------------|\n| `sidebutton registry add ` | Add a registry |\n| `sidebutton registry list` | List installed registries |\n| `sidebutton install ` | Install a knowledge pack |\n| `sidebutton uninstall ` | Remove a knowledge pack |\n| `sidebutton search [query]` | Search packs across registries |\n\n资料来源：[packages/sidebutton/README.md:30-50]()\n\n### Publishing Knowledge Packs\n\n```bash\n# Initialize a new pack\nsidebutton init github.com\n\n# Validate\nsidebutton validate ./github.com\n\n# Publish to registry\nsidebutton publish\n```\n\n资料来源：[packages/server/src/cli.ts:100-150]()\n\n---\n\n## Deployment Modes\n\n### Local Development\n\n```bash\n# Start with dashboard and API\nsidebutton\n\n# Start with stdio for AI agent\nsidebutton --stdio\n```\n\n### AI Agent Integration\n\n**Claude Desktop:**\n\n```json\n{\n \"mcpServers\": {\n \"sidebutton\": {\n \"command\": \"npx\",\n \"args\": [\"sidebutton\", \"--stdio\"]\n }\n }\n}\n```\n\n**Cursor:**\n\n```json\n{\n \"mcpServers\": {\n \"sidebutton\": {\n \"url\": \"http://localhost:9876/mcp\"\n }\n }\n}\n```\n\n资料来源：[packages/sidebutton/README.md:60-90]()\n\n---\n\n## Security Considerations\n\n### Authentication Flow\n\n```mermaid\ngraph TD\n A[Login Command] --> B[Credentials Input]\n B --> C[Validate Credentials]\n C -->|Valid| D[Store Token]\n C -->|Invalid| E[Error]\n D --> F[Attach to Requests]\n\n F --> G[/api/* Requests]\n G --> H{Auth Required?}\n H -->|Yes| I[Verify Token]\n H -->|No| J[Allow]\n I -->|Valid| J\n I -->|Invalid| K[401 Unauthorized]\n```\n\n### Token Storage\n\n- Tokens are stored in `~/.sidebutton/config.json`\n- Not committed to version control\n- Protected by file system permissions\n\n资料来源：[packages/server/src/cli.ts:1-50]()\n\n---\n\n## Summary\n\nThe SideButton system architecture consists of:\n\n1. **CLI Layer** - Entry point for users and AI agents\n2. **Transport Layer** - stdio, SSE, HTTP, WebSocket support\n3. **Server Layer** - Fastify MCP server with REST API\n4. **Execution Layer** - Workflow parsing and step execution\n5. **Provider Layer** - GitHub, Browser, Shell, LLM integrations\n6. **UI Layer** - React dashboard for workflow management\n\nThe modular design allows:\n- AI agents to execute complex browser automation workflows\n- Users to create custom workflows via YAML\n- Extensible provider system for new integrations\n- Installable knowledge packs for domain-specific automation\n\n---\n\n\n\n## Package Overview\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture), [Workflow Engine](#workflow-engine), [Chrome Extension](#chrome-extension)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/package.json](https://github.com/sidebutton/sidebutton/blob/main/packages/core/package.json)\n- [packages/server/package.json](https://github.com/sidebutton/sidebutton/blob/main/packages/server/package.json)\n- [packages/dashboard/package.json](https://github.com/sidebutton/sidebutton/blob/main/packages/dashboard/package.json)\n- [packages/sidebutton/package.json](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/package.json)\n- [packages/core/src/index.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/index.ts)\n- [packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n- [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n
\n\n# Package Overview\n\nSideButton is a browser automation platform organized as a monorepo with four primary packages. The system enables workflow-driven automation through YAML definitions, MCP (Model Context Protocol) integration, a REST API, and a Chrome extension. This document provides a comprehensive overview of each package's architecture, responsibilities, and interdependencies.\n\n## Architecture Overview\n\nSideButton follows a layered architecture pattern with clear separation of concerns across packages. The core workflow engine handles execution logic, the server package provides API endpoints and MCP connectivity, the CLI package offers command-line interaction, and the dashboard provides a web-based user interface.\n\n```mermaid\ngraph TD\n User[User] --> CLI[CLI Package]\n User --> Dashboard[Dashboard Package]\n User --> MCP[MCP Client]\n User --> REST[REST API Client]\n \n CLI --> Server[Server Package]\n Dashboard --> Server\n MCP --> Server\n REST --> Server\n \n Server --> Core[Core Package]\n Server --> BrowserExtension[Chrome Extension]\n \n Core --> WorkflowEngine[Workflow Engine]\n Core --> Providers[Provider Integrations]\n```\n\n## Package Structure\n\nThe repository contains four main packages under the `packages/` directory:\n\n| Package | Description |\n|---------|-------------|\n| `@sidebutton/core` | Core workflow engine and execution runtime |\n| `@sidebutton/server` | MCP server, REST API, and embedded dashboard |\n| `@sidebutton/sidebutton` | Command-line interface |\n| `dashboard` | Frontend React application for the web UI |\n\n## Core Package (`@sidebutton/core`)\n\nThe core package contains the fundamental workflow orchestration engine. It handles parsing, validation, and execution of YAML-based workflow definitions.\n\n### Purpose and Scope\n\nThe core package is responsible for the runtime execution of automations. It provides the foundational primitives that the server package wraps with API endpoints. Workflows are defined in YAML and executed through a step-by-step interpreter that supports multiple action types.\n\n### Core Exports\n\nThe package exposes three primary functions for workflow management:\n\n```typescript\n// packages/core/src/index.ts\nexport { parseWorkflow, validateWorkflow, executeWorkflow }\n```\n\n| Function | Purpose |\n|----------|---------|\n| `parseWorkflow` | Parse YAML workflow definition into internal representation |\n| `validateWorkflow` | Validate workflow structure and step types |\n| `executeWorkflow` | Execute a workflow with provided context and parameters |\n\n### Step Types\n\nThe core package supports multiple categories of step types for workflow construction:\n\n| Category | Steps |\n|----------|-------|\n| **Browser** | `navigate`, `click`, `type`, `scroll`, `hover`, `wait`, `extract`, `extractAll`, `exists`, `key` |\n| **Shell** | `shell.run`, `terminal.open`, `terminal.run` |\n| **LLM** | `llm.classify`, `llm.generate` |\n| **Control** | `control.if`, `control.retry`, `control.stop`, `workflow.call` |\n| **Data** | `data.first` |\n\n### Provider Integrations\n\nThe core package includes provider implementations for external service integration. GitHub integration is implemented in `packages/core/src/providers/github.ts` and provides the following capabilities:\n\n- `listPRs` - List pull requests\n- `getPR` - Get pull request details\n- `createPR` - Create a pull request\n- `listIssues` - List repository issues\n- `getIssue` - Get issue details\n\n资料来源：[packages/core/src/providers/github.ts](packages/core/src/providers/github.ts)\n\n## Server Package (`@sidebutton/server`)\n\nThe server package serves as the central hub for all external interactions with the workflow engine. It wraps the core package with MCP protocol support, REST API endpoints, and embeds the dashboard application.\n\n### MCP Server\n\nThe MCP server implementation exposes workflow execution capabilities to MCP-compatible clients including Claude Desktop and Cursor. The server runs on port 9876 by default and provides the following tools:\n\n| MCP Tool | Description |\n|---------|-------------|\n| `run_workflow` | Execute a workflow by ID |\n| `list_workflows` | List available workflows |\n| `get_workflow` | Get workflow YAML definition |\n| `get_run_log` | Get execution log |\n| `list_run_logs` | List recent executions |\n| `get_browser_status` | Check extension connection |\n| `capture_page` | Capture page selectors |\n| `navigate` | Navigate browser to URL |\n| `snapshot` | Get accessibility tree |\n| `click` | Click element |\n| `type` | Type text |\n| `scroll` | Scroll page |\n| `extract` | Extract text |\n| `screenshot` | Capture screenshot |\n| `hover` | Hover over element |\n\n资料来源：[packages/server/README.md](packages/server/README.md)\n\n### REST API\n\nThe server exposes 60+ JSON endpoints for external integrations. The API supports the same workflow operations available through MCP, enabling programmatic access from any HTTP client.\n\n```bash\n# Run a workflow\ncurl -X POST http://localhost:9876/api/workflows/check_ticket/run \\\n -H \"Content-Type: application/json\" \\\n -d '{\"params\": {\"ticket_id\": \"PROJ-123\"}}'\n\n# List workflows\ncurl http://localhost:9876/api/workflows\n\n# Get run log\ncurl http://localhost:9876/api/runs/latest\n```\n\n资料来源：[README.md](README.md)\n\n### Embedded Dashboard\n\nThe server embeds a React-based dashboard application served from `packages/dashboard/`. The dashboard provides:\n\n- Workflow browsing and execution\n- Run log viewing\n- Shortcut management\n- Action library\n- Workflow recording\n\n### Workflow Engine Extensions\n\nThe server extends the core workflow engine with 34+ step types, providing additional capabilities beyond the core package:\n\n| Extended Category | Additional Steps |\n|-------------------|------------------|\n| **Browser** | `fill`, `press_key`, `scroll_into_view`, `evaluate`, `select_option` |\n| **Extended** | `check_writing_quality`, `capture_page` |\n\n### Knowledge Packs\n\nThe server supports knowledge packs (also called skill packs) that provide domain-specific knowledge for AI-driven tasks. Knowledge packs include:\n\n- **Selectors** — CSS selectors for UI elements\n- **Data models** — entity types, fields, relationships, valid states\n- **State machines** — valid transitions per state\n- **Role playbooks** — role-specific procedures (QA, SE, PM, SD)\n- **Common tasks** — step-by-step procedures, gotchas, edge cases\n\n资料来源：[README.md](README.md)\n\n## CLI Package (`@sidebutton/sidebutton`)\n\nThe CLI package provides command-line interaction with the SideButton platform. It serves as the primary interface for local development and scripting workflows.\n\n### Installation\n\n```bash\nnpm install -g sidebutton\n```\n\n### Core Commands\n\n| Command | Description |\n|---------|-------------|\n| `sidebutton` | Start server (default port 9876) |\n| `sidebutton --stdio` | Start with stdio transport (Claude Desktop) |\n| `sidebutton -p 8080` | Start on custom port |\n\n### Workflow Management\n\n| Command | Description |\n|---------|-------------|\n| `sidebutton list` | List available workflows |\n| `sidebutton run ` | Run a workflow |\n| `sidebutton status` | Check server status |\n\n### Knowledge Pack Commands\n\n```bash\n# Registry management\nsidebutton registry add # Install from registry\nsidebutton registry update [name] # Update installed packs\nsidebutton registry remove # Remove registry and packs\nsidebutton registry list # Show registries\n\n# Search and install\nsidebutton search [query] # Search packs across registries\nsidebutton install # Install a single knowledge pack\nsidebutton uninstall # Remove a knowledge pack\n\n# Development\nsidebutton init [domain] # Scaffold a new knowledge pack\nsidebutton validate [path] # Lint and validate a knowledge pack\nsidebutton publish # Publish to registry\n```\n\n资料来源：[packages/sidebutton/README.md](packages/sidebutton/README.md)\n\n### Publishing Workflows\n\nThe CLI supports publishing skill packs to remote registries via the publish command:\n\n```bash\nsidebutton publish\n```\n\nThis command sends the manifest and all associated files to the configured remote registry at `${REMOTE_BASE_URL}/api/skill-packs/publish`. Authentication is required via bearer token.\n\n## Dashboard Package\n\nThe dashboard is a React-based frontend application that provides the visual interface for managing workflows and viewing execution logs.\n\n### Entry Point\n\nThe dashboard application is mounted in `packages/dashboard/index.html`:\n\n```html\n
\n\n```\n\n### Key Pages\n\n| Page | Route | Purpose |\n|------|-------|---------|\n| Dashboard Home | `/` | Display workflow shortcuts |\n| Actions | `/actions` | Browse and search available workflows |\n| Action Detail | `/actions/:id` | View workflow details and run |\n| Workflows | `/workflows` | Library of workflows |\n| Workflow Detail | `/workflows/:id` | Read-only workflow view |\n| Recordings | `/recordings` | View recorded automations |\n| Run Logs | `/run-logs` | View execution history |\n\n## Chrome Extension\n\nWhile not a separate npm package, the Chrome extension is an integral part of the SideButton ecosystem. It provides browser automation capabilities with:\n\n- 40+ browser commands (navigate, click, type, extract, scroll, wait, snapshot)\n- Real DOM access via CSS selectors\n- Recording mode for capturing manual actions as workflows\n- Embed buttons for injecting action buttons into web pages\n- WebSocket connection with stable reconnection\n\n资料来源：[README.md](README.md)\n\n## Dependency Graph\n\nThe packages have the following dependency relationships:\n\n```mermaid\ngraph LR\n CLI[\"@sidebutton/sidebutton\"] --> Server[\"@sidebutton/server\"]\n Dashboard[\"dashboard\"] --> Server\n Server --> Core[\"@sidebutton/core\"]\n Server --> BrowserExt[\"Chrome Extension\"]\n \n style Core fill:#e1f5fe\n style Server fill:#fff3e0\n style CLI fill:#e8f5e9\n style Dashboard fill:#f3e5f5\n```\n\n| Consumer | Dependency | Relationship |\n|----------|------------|---------------|\n| `@sidebutton/sidebutton` | `@sidebutton/server` | CLI wraps server functionality |\n| `dashboard` | `@sidebutton/server` | Dashboard embeds in server |\n| `@sidebutton/server` | `@sidebutton/core` | Server uses core for workflow execution |\n\n## Technology Stack\n\n| Layer | Technology |\n|-------|------------|\n| Runtime | Node.js |\n| Core Engine | TypeScript |\n| Server | Fastify |\n| API Protocol | MCP (Model Context Protocol) |\n| Dashboard | React, Vite |\n| Browser Automation | Chrome Extension (Manifest V3) |\n| Package Manager | pnpm (monorepo) |\n\n## Quick Start\n\n### Running the Server\n\n```bash\n# Start the server\nsidebutton\n\n# Or with custom port\nsidebutton -p 8080\n```\n\n### Running a Workflow\n\n```bash\n# List available workflows\nsidebutton list\n\n# Run a specific workflow\nsidebutton run \n```\n\n### Integrating with Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"sidebutton\": {\n \"command\": \"npx\",\n \"args\": [\"sidebutton\", \"--stdio\"]\n }\n }\n}\n```\n\n## Related Documentation\n\n- [Full Documentation](https://docs.sidebutton.com)\n- [GitHub Repository](https://github.com/sidebutton/sidebutton)\n- [Website](https://sidebutton.com)\n- [Chrome Web Store](https://chromewebstore.google.com/detail/sidebutton/odaefhmdmgijnhdbkfagnlnmobphgkij)\n\n---\n\n\n\n## Workflow Engine\n\n### 相关页面\n\n相关主题：[Step Types Reference](#step-types), [Workflow Examples](#workflow-examples), [Package Overview](#packages-overview)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n- [packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n- [packages/server/src/server.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/server.ts)\n- [packages/server/src/mcp/handler.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/handler.ts)\n- [packages/core/src/providers/github.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/providers/github.ts)\n- [packages/server/defaults/roles/software-engineer.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/software-engineer.md)\n- [packages/server/defaults/targets/_provider-github-cli.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/targets/_provider-github-cli.md)\n
\n\n# Workflow Engine\n\n## Overview\n\nThe SideButton Workflow Engine is a YAML-first orchestration system that enables automation of complex tasks through a declarative step-based approach. It provides 34+ built-in step types spanning browser automation, shell execution, LLM integration, and programmatic control flow operations.\n\nThe engine executes workflows defined in YAML format, supporting variable interpolation, conditional branching, retry logic, and cross-workflow chaining. Workflows can be triggered via MCP (Model Context Protocol), the REST API, or the dashboard interface.\n\n资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n## Architecture\n\n### Core Components\n\n```mermaid\ngraph TD\n A[Workflow YAML] --> B[Parser]\n B --> C[AST / Step Definitions]\n C --> D[Executor]\n D --> E[Step Handlers]\n \n F[Variables/Context] --> D\n D --> F\n \n G[MCP Client] --> D\n H[REST API] --> D\n I[Dashboard] --> D\n```\n\nThe engine consists of three primary layers:\n\n1. **Parser**: Validates and parses YAML workflow definitions into structured step objects\n2. **Executor**: Orchestrates step execution, manages state, and handles control flow\n3. **Step Handlers**: Provider-specific implementations for each step type\n\n资料来源：[packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n\n### Workflow Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Executor\n participant StepHandler\n participant Context\n \n Client->>Executor: executeWorkflow(workflow, context)\n Executor->>Executor: Parse YAML\n Loop For Each Step\n Executor->>StepHandler: Execute Step\n StepHandler->>Context: Update Variables\n StepHandler-->>Executor: Result\n Executor->>Executor: Check Control Flow\n End\n Executor-->>Client: Execution Result\n```\n\n## Step Types\n\nThe workflow engine supports five major categories of steps:\n\n资料来源：[README.md:1-50]()\n\n### Browser Steps\n\nUsed for web automation tasks. All browser steps require an active browser connection.\n\n| Step Type | Description |\n|-----------|-------------|\n| `browser.navigate` | Open a URL in the browser |\n| `browser.click` | Click an element by CSS selector |\n| `browser.type` | Type text into an input element |\n| `browser.fill` | Fill input value directly (React-compatible) |\n| `browser.scroll` | Scroll the page |\n| `browser.extract` | Extract text from an element into a variable |\n| `browser.extractAll` | Extract all matching elements |\n| `browser.extractMap` | Extract structured data from repeated elements |\n| `browser.wait` | Wait for element or fixed delay |\n| `browser.exists` | Check if element exists (returns boolean) |\n| `browser.hover` | Position cursor over element |\n| `browser.key` | Send keyboard keys |\n| `browser.snapshot` | Capture accessibility tree snapshot |\n| `browser.injectCSS` | Inject CSS styles into page |\n| `browser.injectJS` | Execute JavaScript in page context |\n| `browser.select_option` | Select dropdown option |\n| `browser.scrollIntoView` | Scroll element into viewport |\n\n资料来源：[README.md:44-63]()\n\n### Shell Steps\n\nExecute command-line operations on the host system.\n\n| Step Type | Description |\n|-----------|-------------|\n| `shell.run` | Execute a bash/shell command |\n| `terminal.open` | Open a visible terminal window (macOS) |\n| `terminal.run` | Run command in visible terminal window |\n\n资料来源：[README.md:64-66]()\n\n### LLM Steps\n\nIntegrate with large language models for AI-driven operations.\n\n| Step Type | Description |\n|-----------|-------------|\n| `llm.classify` | Structured classification with predefined categories |\n| `llm.generate` | Free-form text generation |\n| `llm.decide` | Make decisions based on context |\n\nSupported providers include Ollama (local), OpenAI, Anthropic, and Google.\n\n资料来源：[README.md:67-73]()\n\n### Control Flow Steps\n\nManage workflow execution logic and branching.\n\n| Step Type | Description |\n|-----------|-------------|\n| `control.if` | Conditional branching based on expression evaluation |\n| `control.retry` | Retry block with configurable backoff |\n| `control.stop` | End workflow with success/error message |\n| `workflow.call` | Call another workflow with parameters |\n| `variable.set` | Set a variable value |\n\n资料来源：[README.md:74-78]()\n\n### Data Steps\n\nManipulate and transform data between steps.\n\n| Step Type | Description |\n|-----------|-------------|\n| `data.first` | Extract first item from a list |\n| `data.get` | Retrieve stored data value |\n\n资料来源：[README.md:79-82]()\n\n## Variable Interpolation\n\nThe workflow engine uses `{{variable}}` syntax for referencing extracted values and parameters.\n\n```yaml\nsteps:\n - type: browser.extract\n selector: \".username\"\n as: user\n - type: shell.run\n cmd: \"echo 'Hello, {{user}}!'\"\n```\n\nVariables can be:\n- Extracted from page elements using `as` parameter\n- Passed as workflow parameters\n- Set via `variable.set` steps\n- Returned from nested workflow calls\n\n资料来源：[README.md:103-115]()\n\n## Workflow Definition Schema\n\nA workflow is defined with the following structure:\n\n```yaml\nid: workflow_identifier\ntitle: \"Display Title\"\ndescription: \"What this workflow does\"\nparams:\n param_name: string # or number, boolean, array, object\nsteps:\n - type: browser.navigate\n url: \"https://example.com\"\n - type: browser.extract\n selector: \".element\"\n as: extracted_value\n```\n\n### Required Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string | Unique workflow identifier |\n| `title` | string | Human-readable title |\n| `steps` | array | Ordered list of step definitions |\n\n### Optional Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `description` | string | Workflow description |\n| `params` | object | Parameter definitions with types |\n| `category` | string | Workflow category |\n| `platform` | string | Target platform |\n\n资料来源：[packages/server/src/server.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/server.ts)\n\n## Control Flow Patterns\n\n### Conditional Branching\n\n```yaml\n- type: control.if\n condition: \"{{current_status}} != 'Done'\"\n then:\n - type: llm.classify\n prompt: \"Should this ticket be closed?\"\n classes: [close, keep_open]\n as: decision\n```\n\n资料来源：[README.md:117-125]()\n\n### Retry with Backoff\n\n```yaml\n- type: control.retry\n max_attempts: 3\n backoff: 1000 # milliseconds\n steps:\n - type: shell.run\n cmd: \"curl -f https://api.example.com/health\"\n```\n\n### Workflow Chaining\n\n```yaml\n- type: workflow.call\n workflow_id: another_workflow\n params:\n input_value: \"{{extracted_data}}\"\n```\n\n资料来源：[packages/server/defaults/roles/software-engineer.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/software-engineer.md)\n\n## MCP Integration\n\nThe workflow engine exposes functionality through the Model Context Protocol, enabling AI assistants to execute and manage workflows.\n\n资料来源：[packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n\n### Available MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `run_workflow` | Execute a workflow by ID |\n| `list_workflows` | List available workflows |\n| `get_workflow` | Get workflow YAML definition |\n| `get_run_log` | Get execution log for a run |\n| `list_run_logs` | List recent workflow executions |\n| `get_browser_status` | Check browser extension connection |\n| `capture_page` | Capture selectors from current page |\n\n### MCP Tool Handlers\n\n```mermaid\ngraph LR\n A[MCP Request] --> B[Handler]\n B --> C{tool_name}\n C -->|list_workflows| D[toolListWorkflows]\n C -->|get_workflow| E[toolGetWorkflow]\n C -->|list_run_logs| F[toolListRunLogs]\n C -->|run_workflow| G[executeWorkflow]\n```\n\n资料来源：[packages/server/src/mcp/handler.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/handler.ts)\n\n### List Workflows Response Format\n\n```typescript\ninterface WorkflowListItem {\n workflow: Workflow;\n source: 'actions' | 'workflows';\n}\n\n// Response includes:\n// - workflow.id\n// - workflow.title\n// - workflow.params (if any)\n// - source identifier\n```\n\n资料来源：[packages/server/src/mcp/handler.ts:1-50]()\n\n## GitHub Integration\n\nThe engine provides specialized steps for GitHub operations through the GitHub CLI provider.\n\n资料来源：[packages/core/src/providers/github.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/providers/github.ts)\n\n### GitHub Step Types\n\n| Step | Description |\n|------|-------------|\n| `git.listPRs` | List pull requests with state filter |\n| `git.getPR` | Get PR details and diff statistics |\n| `git.createPR` | Create a new pull request |\n| `git.listIssues` | List issues with filters |\n| `git.getIssue` | Get issue details |\n| `issues.create` | Create an issue |\n| `issues.comment` | Add a comment to issue/PR |\n| `issues.transition` | Change issue status |\n\n### Create Pull Request Parameters\n\n```typescript\ninterface CreatePRParams {\n repo?: string; // Repository in format \"owner/repo\"\n title: string; // PR title\n body?: string; // PR description\n head: string; // Head branch name\n base?: string; // Base branch (default: main)\n}\n```\n\n资料来源：[packages/core/src/providers/github.ts:1-50]()\n\n### Common GitHub Workflows\n\n**Review Open PRs:**\n1. `git.listPRs` with `state: \"open\"` — view pending reviews\n2. `git.getPR` with PR number — read details and diff stats\n3. Use browser tools for visual diff review\n\n**Autonomous Development Cycle:**\n1. `git.listIssues` — browse available issues\n2. `git.getIssue` — read candidate details\n3. `llm.decide` — select best issue based on priority\n4. `issues.comment` — signal work is starting\n5. `git.createPR` — submit completed work\n\n资料来源：[packages/server/defaults/targets/_provider-github-cli.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/targets/_provider-github-cli.md)\n\n## Execution Context\n\nEach workflow execution maintains a context object that stores:\n\n- **Variables**: Extracted values and set variables\n- **Parameters**: Input parameters passed to the workflow\n- **Results**: Step execution results\n- **Logs**: Execution logs for debugging\n\n```yaml\n# Context is passed to executeWorkflow\ncontext:\n params:\n ticket_id: \"PROJ-123\"\n variables:\n current_status: \"In Progress\"\n```\n\n## Error Handling\n\nThe engine provides multiple mechanisms for error handling:\n\n1. **control.retry**: Automatically retry failed steps with exponential backoff\n2. **control.stop**: Gracefully end workflow with error message\n3. **Conditional checks**: Use `browser.exists` to verify elements before actions\n\n```yaml\nsteps:\n - type: browser.exists\n selector: \".error-message\"\n as: has_error\n - type: control.if\n condition: \"{{has_error}}\"\n then:\n - type: control.stop\n status: error\n message: \"Error detected on page\"\n```\n\n## Dashboard Integration\n\nThe workflow engine integrates with the SideButton dashboard for:\n\n- **Workflow Library**: Browse and install workflows\n- **Run History**: View execution logs and results\n- **Quick Run**: Execute workflows with parameter inputs\n\n资料来源：[packages/server/src/server.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/server.ts)\n\n### Workflow Installation Flow\n\n1. User navigates to workflow in library\n2. Dashboard renders install confirmation page\n3. POST request submits workflow to local server\n4. Server saves workflow to user's action library\n5. Success page confirms installation\n\n```mermaid\ngraph TD\n A[Browse Workflow] --> B[Click Install]\n B --> C[POST /install/:workflowId]\n C --> D[Server Validates]\n D --> E[Save to Actions Library]\n E --> F[Show Success Page]\n```\n\n## Best Practices\n\n1. **Use extracted variables immediately**: Variable references should occur close to their extraction step\n2. **Add wait conditions**: Use `browser.wait` before extracting dynamic content\n3. **Handle missing elements**: Check existence before interacting\n4. **Limit retry attempts**: Configure appropriate `max_attempts` for unreliable operations\n5. **Keep workflows focused**: Prefer workflow chaining over monolithic single workflows\n\n资料来源：[packages/server/defaults/roles/qa.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/qa.md)\n\n---\n\n\n\n## Step Types Reference\n\n### 相关页面\n\n相关主题：[Workflow Engine](#workflow-engine), [Workflow Examples](#workflow-examples)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n- [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n- [packages/core/src/providers/github.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/providers/github.ts)\n- [packages/server/src/mcp/handler.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/handler.ts)\n
\n\n# Step Types Reference\n\nSideButton workflows are composed of discrete steps that define actions to be executed sequentially. Each step type serves a specific purpose—from interacting with web pages to executing shell commands, making decisions via LLM, or orchestrating control flow. Understanding the available step types is essential for building effective automations.\n\n## Overview\n\nSteps are the fundamental building blocks of SideButton workflows. They are defined within workflow YAML files and specify:\n\n- **What action** to perform (the step type)\n- **What parameters** to use for that action\n- **How to handle results** (variable assignment, conditional logic)\n\n资料来源：[packages/core/README.md]()\n\n```mermaid\ngraph TD\n A[Workflow YAML] --> B[Step Execution Engine]\n B --> C[Browser Steps]\n B --> D[Shell Steps]\n B --> E[LLM Steps]\n B --> F[Control Steps]\n B --> G[Data Steps]\n B --> H[Git Steps]\n B --> I[Issues Steps]\n```\n\n## Step Type Categories\n\nSideButton organizes steps into the following categories:\n\n| Category | Purpose | Primary Use Case |\n|----------|---------|------------------|\n| Browser | Web page interaction | UI automation, data extraction |\n| Shell | Command execution | Build tools, CLI operations |\n| LLM | AI-powered decisions | Classification, content generation |\n| Control | Flow control | Conditionals, retries, sub-workflows |\n| Data | Data manipulation | Variable assignment, extraction |\n| Git | Version control | PRs, issues, repository ops |\n| Issues | Issue tracking | Bug tracking, task management |\n\n资料来源：[packages/core/README.md]()\n\n---\n\n## Browser Steps\n\nBrowser steps interact with web pages through a connected Chrome extension. These steps provide real DOM access via CSS selectors, enabling precise UI automation.\n\n### Available Browser Steps\n\n| Step Type | Description |\n|-----------|-------------|\n| `navigate` | Navigate browser to a URL |\n| `click` | Click an element by selector |\n| `type` | Type text into an input field |\n| `scroll` | Scroll the page |\n| `hover` | Hover over an element |\n| `wait` | Wait for condition or duration |\n| `extract` | Extract text from single element |\n| `extractAll` | Extract text from all matching elements |\n| `extract_map` | Extract structured data from repeated elements |\n| `exists` | Check if element exists |\n| `key` | Press keyboard key |\n| `screenshot` | Capture page screenshot |\n| `snapshot` | Get accessibility tree snapshot |\n| `select_option` | Select dropdown option |\n\n资料来源：[README.md]()\n\n### Common Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `selector` | string | CSS selector for target element |\n| `url` | string | Target URL (for navigate) |\n| `text` | string | Text to type or extract |\n| `timeout` | number | Wait timeout in milliseconds |\n| `as` | string | Variable name to store result |\n\n### Example: Basic Browser Workflow\n\n```yaml\nsteps:\n - type: browser.navigate\n url: \"https://github.com/sidebutton/sidebutton\"\n\n - type: browser.snapshot\n\n - type: browser.extract\n selector: \".readme h1\"\n as: repo_title\n\n - type: browser.extractAll\n selector: \".file-info a\"\n as: file_links\n```\n\n### Example: Form Interaction\n\n```yaml\nsteps:\n - type: browser.navigate\n url: \"https://example.com/search\"\n\n - type: browser.type\n selector: \"#search-input\"\n text: \"{{query}}\"\n\n - type: browser.click\n selector: \"#search-button\"\n\n - type: browser.wait\n selector: \".results\"\n timeout: 5000\n```\n\n---\n\n## Shell Steps\n\nShell steps execute command-line commands on the local system. They support both synchronous execution and interactive terminal sessions.\n\n### Available Shell Steps\n\n| Step Type | Description |\n|-----------|-------------|\n| `shell.run` | Execute a shell command |\n| `terminal.open` | Open an interactive terminal |\n| `terminal.run` | Run command in open terminal |\n\n资料来源：[packages/core/README.md]()\n\n### Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `cmd` | string | Shell command to execute |\n| `cwd` | string | Working directory |\n| `env` | object | Environment variables |\n| `timeout` | number | Execution timeout |\n| `async` | boolean | Run asynchronously |\n\n### Example: Shell Command Execution\n\n```yaml\nsteps:\n - type: shell.run\n cmd: \"pnpm build\"\n cwd: \"/path/to/project\"\n timeout: 120000\n as: build_output\n\n - type: shell.run\n cmd: \"git status --short\"\n as: git_status\n```\n\n---\n\n## LLM Steps\n\nLLM steps leverage AI models for content generation, classification, and decision-making. These steps enable intelligent automation that can adapt to context.\n\n### Available LLM Steps\n\n| Step Type | Description |\n|-----------|-------------|\n| `llm.generate` | Generate content with LLM |\n| `llm.classify` | Classify input into categories |\n| `llm.decide` | Make decisions based on context |\n| `llm.extract` | Extract structured data from unstructured text |\n\n资料来源：[README.md](), [packages/core/README.md]()\n\n### Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `prompt` | string | LLM prompt template |\n| `model` | string | Model to use |\n| `temperature` | number | Sampling temperature |\n| `as` | string | Variable name for result |\n\n### Example: Content Generation\n\n```yaml\nsteps:\n - type: llm.generate\n prompt: |\n Write a concise changelog entry for this commit:\n\n === COMMIT ===\n {{commit_message}}\n\n Format: - {{change_summary}}\n as: changelog_entry\n```\n\n### Example: Classification\n\n```yaml\nsteps:\n - type: llm.classify\n input: \"{{issue_body}}\"\n categories:\n - bug\n - feature\n - documentation\n - question\n as: issue_type\n```\n\n---\n\n## Control Steps\n\nControl steps manage workflow execution flow, enabling conditionals, loops, error handling, and sub-workflow invocation.\n\n### Available Control Steps\n\n| Step Type | Description |\n|-----------|-------------|\n| `control.if` | Conditional execution |\n| `control.retry` | Retry failed steps |\n| `control.stop` | Stop execution with message |\n| `workflow.call` | Call another workflow |\n\n资料来源：[packages/core/README.md]()\n\n### control.if\n\nExecute steps conditionally based on a boolean expression.\n\n```yaml\nsteps:\n - type: control.if\n condition: \"{{is_authenticated}}\"\n then:\n - type: browser.click\n selector: \".dashboard-link\"\n else:\n - type: browser.click\n selector: \".login-button\"\n```\n\n### control.retry\n\nRetry a step or block of steps on failure.\n\n```yaml\nsteps:\n - type: control.retry\n attempts: 3\n delay: 1000\n steps:\n - type: shell.run\n cmd: \"curl -f https://api.example.com/health\"\n```\n\n### control.stop\n\nStop workflow execution and output a message.\n\n```yaml\nsteps:\n - type: control.stop\n message: |\n === Processing Complete ===\n\n Extracted {{item_count}} items\n Status: {{final_status}}\n```\n\n### workflow.call\n\nInvoke another workflow as a subroutine.\n\n```yaml\nsteps:\n - type: workflow.call\n workflow_id: \"send_notification\"\n params:\n channel: \"#alerts\"\n message: \"{{summary}}\"\n```\n\n---\n\n## Data Steps\n\nData steps manipulate variables and extract information for use by subsequent steps.\n\n### Available Data Steps\n\n| Step Type | Description |\n|-----------|-------------|\n| `data.first` | Get first item from array |\n| `data.get` | Get value from object |\n| `data.set` | Set a variable value |\n| `variable.set` | Set a workflow variable |\n\n资料来源：[packages/core/README.md](), [README.md]()\n\n### Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `from` | string | Source variable to extract from |\n| `default` | any | Default value if not found |\n| `as` | string | Variable name for result |\n\n### Example: Data Extraction\n\n```yaml\nsteps:\n - type: browser.extract\n selector: \".user-profile\"\n as: profile_html\n\n - type: data.first\n from: \"{{profile_html}}\"\n as: first_profile\n\n - type: data.set\n key: \"user_name\"\n value: \"{{first_profile.name}}\"\n```\n\n---\n\n## Git Steps\n\nGit steps interact with GitHub repositories via the `gh` CLI tool. These steps support pull requests, issues, and repository operations.\n\n### Available Git Steps\n\n| Step Type | Description |\n|-----------|-------------|\n| `git.listPRs` | List pull requests |\n| `git.getPR` | Get PR details |\n| `git.createPR` | Create pull request |\n| `git.listIssues` | List issues |\n| `git.getIssue` | Get issue details |\n\n资料来源：[packages/core/src/providers/github.ts](), [README.md]()\n\n### Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `repo` | string | Repository (owner/repo) |\n| `state` | string | Issue/PR state (open, closed, all) |\n| `labels` | string | Filter by labels |\n| `limit` | number | Maximum results |\n\n### Example: List Pull Requests\n\n```yaml\nsteps:\n - type: git.listPRs\n repo: \"sidebutton/sidebutton\"\n state: \"open\"\n limit: 10\n as: open_prs\n\n - type: control.stop\n message: |\n === Open PRs ===\n {{open_prs}}\n```\n\n### Example: Create Pull Request\n\n```yaml\nsteps:\n - type: git.createPR\n repo: \"sidebutton/sidebutton\"\n title: \"feat: add new automation step\"\n head: \"feature-branch\"\n base: \"main\"\n body: |\n ## Summary\n This PR adds support for...\n\n ## Testing\n - [ ] Unit tests pass\n - [ ] Manual testing completed\n as: pr_result\n```\n\n---\n\n## Issues Steps\n\nIssues steps manage issue tracking across connected providers. They support searching, creating, and updating issues.\n\n### Available Issues Steps\n\n| Step Type | Description |\n|-----------|-------------|\n| `issues.search` | Search for issues |\n| `issues.get` | Get issue details |\n| `issues.create` | Create new issue |\n| `issues.comment` | Add comment to issue |\n| `issues.transition` | Change issue status |\n| `issues.attach` | Attach file to issue |\n\n资料来源：[README.md]()\n\n### Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `query` | string | Search query |\n| `repo` | string | Repository |\n| `title` | string | Issue title |\n| `body` | string | Issue body |\n| `labels` | array | Issue labels |\n\n### Example: Search and Create Issue\n\n```yaml\nsteps:\n - type: issues.search\n query: \"is:issue is:open label:bug\"\n repo: \"sidebutton/sidebutton\"\n as: existing_bugs\n\n - type: control.if\n condition: \"{{existing_bugs.length}} == 0\"\n then:\n - type: issues.create\n repo: \"sidebutton/sidebutton\"\n title: \"Bug: {{bug_description}}\"\n body: |\n ## Description\n {{bug_description}}\n\n ## Steps to Reproduce\n 1.\n 2.\n 3.\n labels: [\"bug\"]\n as: new_issue\n```\n\n---\n\n## Variable Interpolation\n\nVariables are referenced throughout steps using `{{variable}}` syntax. This enables dynamic values from previous step results.\n\n```yaml\nsteps:\n - type: browser.extract\n selector: \".username\"\n as: user\n\n - type: shell.run\n cmd: \"echo 'Hello, {{user}}!'\"\n\n - type: llm.generate\n prompt: \"Write a welcome message for user: {{user}}\"\n as: welcome_message\n```\n\n### Variable Scoping\n\n| Scope | Description |\n|-------|-------------|\n| `{{step_id.value}}` | Result from specific step |\n| `{{params.name}}` | Workflow parameter value |\n| `{{env.VAR_NAME}}` | Environment variable |\n\n---\n\n## Step Execution Order\n\nSteps execute sequentially by default. The execution order can be controlled through:\n\n1. **Sequential**: Steps run in definition order\n2. **Conditional**: `control.if` skips or executes blocks\n3. **Retry**: `control.retry` repeats failed steps\n4. **Sub-workflow**: `workflow.call` executes external workflows\n\n```mermaid\ngraph LR\n A[Step 1] --> B{control.if}\n B -->|condition true| C[Step 2a]\n B -->|condition false| D[Step 2b]\n C --> E[Step 3]\n D --> E\n E --> F[control.retry]\n F -->|success| G[Step 4]\n F -->|failure| F\n G --> H[workflow.call]\n H --> I[Step 5]\n```\n\n---\n\n## Error Handling\n\n### Retry on Failure\n\n```yaml\nsteps:\n - type: control.retry\n attempts: 3\n delay: 2000\n steps:\n - type: shell.run\n cmd: \"npm test\"\n```\n\n### Conditional Failure Handling\n\n```yaml\nsteps:\n - type: control.if\n condition: \"{{command_success}}\"\n then:\n - type: browser.click\n selector: \".continue-button\"\n else:\n - type: issues.create\n title: \"Deployment failed\"\n body: \"Command exited with error\"\n```\n\n---\n\n## Best Practices\n\n### 1. Use Specific Selectors\n\nPrefer specific CSS selectors over generic ones:\n\n```yaml\n# Good\n- type: browser.click\n selector: \"#main-nav .settings-link\"\n\n# Avoid\n- type: browser.click\n selector: \"a:nth-child(2)\"\n```\n\n### 2. Add Timeouts for Dynamic Content\n\n```yaml\nsteps:\n - type: browser.wait\n selector: \".loading-complete\"\n timeout: 10000\n```\n\n### 3. Store Intermediate Results\n\n```yaml\nsteps:\n - type: browser.extract\n selector: \".data-table tr\"\n as: rows\n\n - type: data.first\n from: \"{{rows}}\"\n as: first_row\n```\n\n### 4. Use LLM for Dynamic Decisions\n\n```yaml\nsteps:\n - type: llm.classify\n input: \"{{user_feedback}}\"\n categories: [\"positive\", \"negative\", \"neutral\"]\n as: sentiment\n\n - type: control.if\n condition: \"{{sentiment}} == 'negative'\"\n then:\n - type: issues.create\n title: \"Negative feedback received\"\n```\n\n---\n\n## Summary\n\nStep types in SideButton provide a comprehensive toolkit for building automations:\n\n| Category | Key Steps |\n|----------|-----------|\n| Browser | `navigate`, `click`, `type`, `extract`, `snapshot` |\n| Shell | `shell.run`, `terminal.open` |\n| LLM | `llm.generate`, `llm.classify`, `llm.decide` |\n| Control | `control.if`, `control.retry`, `workflow.call` |\n| Data | `data.first`, `data.get` |\n| Git | `git.listPRs`, `git.createPR` |\n| Issues | `issues.search`, `issues.create` |\n\nFor more details on workflow configuration and YAML syntax, refer to the [Workflow Configuration Reference](https://docs.sidebutton.com).\n\n---\n\n\n\n## Workflow Examples\n\n### 相关页面\n\n相关主题：[Workflow Engine](#workflow-engine), [Step Types Reference](#step-types)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [bundles/github/workflows/create_release.yaml](https://github.com/sidebutton/sidebutton/blob/main/bundles/github/workflows/create_release.yaml)\n- [bundles/github/workflows/github_pr_claude_review.yaml](https://github.com/sidebutton/sidebutton/blob/main/bundles/github/workflows/github_pr_claude_review.yaml)\n- [workflows/llm_summarize.yaml](https://github.com/sidebutton/sidebutton/blob/main/workflows/llm_summarize.yaml)\n- [workflows/wikipedia_open.yaml](https://github.com/sidebutton/sidebutton/blob/main/workflows/wikipedia_open.yaml)\n- [packages/server/defaults/workflows/llm_summarize.yaml](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/workflows/llm_summarize.yaml)\n
\n\n# Workflow Examples\n\n## Overview\n\nWorkflow Examples in SideButton are pre-built YAML-based automation sequences that demonstrate how to combine different step types to accomplish real-world tasks. These examples serve as both practical utilities and learning references for building custom automations.\n\nThe SideButton workflow system supports multiple integration methods depending on available providers:\n\n| Provider Preference | Method | Reliability |\n|---------------------|--------|-------------|\n| 1st | API Provider | Fastest and most reliable |\n| 2nd | CLI Tool | Good for git operations |\n| 3rd | Browser Automation | Universal fallback |\n\n资料来源：[packages/server/defaults/roles/software-engineer.md]()\n\n## Workflow Structure\n\nEvery workflow in SideButton follows a standardized YAML format with the following core structure:\n\n```yaml\nid: workflow_identifier\ntitle: \"Human Readable Title\"\ndescription: \"What this workflow accomplishes\"\nsteps:\n - type: step.type\n property: value\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n### Basic Anatomy of a Workflow\n\n```mermaid\ngraph TD\n A[YAML Workflow File] --> B[Workflow Engine]\n B --> C{Step Type Router}\n C -->|Browser| D[Browser Tools]\n C -->|Shell| E[Terminal/CLI]\n C -->|LLM| F[AI Provider]\n C -->|Control| G[Flow Control]\n C -->|Data| H[Data Manipulation]\n \n D --> I[Execute Action]\n E --> I\n F --> I\n G --> I\n H --> I\n \n I --> J[Run Log Entry]\n```\n\n## Step Types Reference\n\nSideButton provides five categories of steps that can be combined in workflows:\n\n资料来源：[packages/core/README.md]()\n\n### Browser Steps\n\n| Step | Purpose |\n|------|---------|\n| `navigate` | Navigate browser to URL |\n| `click` | Click an element |\n| `type` | Type text into an element |\n| `scroll` | Scroll the page |\n| `hover` | Hover over element |\n| `wait` | Wait for condition |\n| `extract` | Extract text from element |\n| `extractAll` | Extract all matching elements |\n| `exists` | Check element exists |\n| `key` | Press keyboard key |\n| `snapshot` | Get accessibility tree |\n| `screenshot` | Capture screenshot |\n\n资料来源：[README.md]()\n\n### Shell/Terminal Steps\n\n| Step | Purpose |\n|------|---------|\n| `shell.run` | Execute shell command |\n| `terminal.open` | Open visible terminal window (macOS) |\n| `terminal.run` | Run command in terminal window |\n\n### LLM Steps\n\n| Step | Purpose |\n|------|---------|\n| `llm.classify` | Structured classification with categories |\n| `llm.generate` | Free-form text generation |\n| `llm.decide` | AI-driven decision making |\n\n### Control Flow Steps\n\n| Step | Purpose |\n|------|---------|\n| `control.if` | Conditional branching |\n| `control.retry` | Retry with backoff |\n| `control.stop` | End workflow with message |\n| `workflow.call` | Call another workflow with parameters |\n\n### Data Steps\n\n| Step | Purpose |\n|------|---------|\n| `data.first` | Extract first item from list |\n| `data.get` | Get value from data object |\n\n## GitHub Workflow Examples\n\nSideButton includes pre-built workflows for GitHub automation stored in the `bundles/github/workflows/` directory.\n\n### GitHub PR Claude Review\n\nThis workflow demonstrates how to automate PR review using Claude AI. The workflow follows a typical review pattern:\n\n```mermaid\ngraph LR\n A[List Open PRs] --> B[Get PR Details]\n B --> C[Extract Diff Stats]\n C --> D[Navigate to PR]\n D --> E[Review Files Changed]\n E --> F[Generate Review Comment]\n```\n\n资料来源：[bundles/github/workflows/github_pr_claude_review.yaml]()\n\n**Common PR Review Sequence:**\n\n1. `git.listPRs` with `state: \"open\"` — see what needs review\n2. `git.getPR` with number — read details and diff stats\n3. Use browser tools for visual diff review if needed\n\n资料来源：[packages/server/defaults/targets/_provider-github-cli.md]()\n\n### Create Release Workflow\n\nThe release creation workflow demonstrates orchestrating multiple operations:\n\n1. Open the release page using browser automation\n2. Decide the next version tag based on commit history\n3. Create the release with proper version naming\n\n资料来源：[bundles/github/workflows/create_release.yaml]()\n\n**Creating a PR after coding:**\n\n1. `git.createPR` with title, head branch, base branch\n2. `issues.comment` on related issue linking the PR\n\n资料来源：[packages/server/defaults/targets/_provider-github-cli.md]()\n\n## LLM-Based Workflows\n\n### Summarize Workflow\n\nThe `llm_summarize.yaml` workflow demonstrates integration with AI providers for text processing:\n\n```yaml\nid: llm_summarize\ntitle: \"Summarize Content\"\ndescription: \"Generate a summary using LLM\"\nsteps:\n - type: llm.generate\n prompt: \"{{input_text}}\"\n instruction: \"Provide a concise summary\"\n```\n\n资料来源：[workflows/llm_summarize.yaml]()\n资料来源：[packages/server/defaults/workflows/llm_summarize.yaml]()\n\n**LLM Provider Support:**\n\nLLM steps work with multiple providers:\n- Ollama (local)\n- OpenAI\n- Anthropic\n- Google\n\n资料来源：[README.md]()\n\n### Decision Workflows\n\nThe `llm.decide` step type enables autonomous decision-making:\n\n```mermaid\ngraph TD\n A[Issue Received] --> B{llm.decide}\n B -->|Clear & well-scoped| C[Pick and start work]\n B -->|Ambiguous/blocked| D[Skip, pick next]\n B -->|Same priority| E[Prefer smaller scope]\n B -->|No suitable issues| F[Stop and report]\n```\n\n资料来源：[packages/server/defaults/roles/software-engineer.md]()\n\n## Browser-Based Workflows\n\n### Wikipedia Open Example\n\nThis demonstrates basic browser navigation and content extraction:\n\n```yaml\nid: wikipedia_open\ntitle: \"Open Wikipedia Page\"\nsteps:\n - type: browser.navigate\n url: \"{{wiki_url}}\"\n - type: browser.snapshot\n as: page_content\n - type: browser.extract\n selector: \"{{element_selector}}\"\n as: extracted_text\n```\n\n资料来源：[workflows/wikipedia_open.yaml]()\n\n**Best Practices for Browser Steps:**\n\n1. Use `snapshot` to understand page structure before taking actions\n2. Use `extract` to pull specific content from pages\n3. Use `screenshot` for visual verification\n\n资料来源：[packages/server/defaults/roles/software-engineer.md]()\n\n## Variable Interpolation\n\nAll workflows support variable interpolation using `{{variable}}` syntax:\n\n```yaml\nsteps:\n - type: browser.extract\n selector: \".username\"\n as: user\n - type: shell.run\n cmd: \"echo 'Hello, {{user}}!'\"\n - type: llm.generate\n prompt: \"Write a greeting for {{user}}\"\n```\n\n资料来源：[README.md]()\n\n## Parameterized Workflows\n\nWorkflows can accept parameters for flexibility:\n\n```yaml\nid: check_ticket_status\ntitle: \"Check Ticket Status\"\nparams:\n ticket_id: string\nsteps:\n - type: browser.navigate\n url: \"https://jira.example.com/browse/{{ticket_id}}\"\n - type: browser.extract\n selector: \"[data-testid='status-field']\"\n as: current_status\n```\n\n资料来源：[README.md]()\n\n## Execution Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant MCP as MCP Handler\n participant Engine as Workflow Engine\n participant Steps as Step Executors\n \n User->>MCP: run_workflow(workflow_id, params)\n MCP->>Engine: executeWorkflow(workflow, context)\n Engine->>Steps: Execute Step 1\n Steps-->>Engine: Step Result\n Engine->>Steps: Execute Step 2\n Steps-->>Engine: Step Result\n Engine->>MCP: Run Log Entry\n MCP-->>User: Execution Result\n```\n\n资料来源：[packages/server/src/mcp/handler.ts]()\n资料来源：[packages/core/README.md]()\n\n## Workflow Bundles\n\nSideButton organizes related workflows into bundles. The GitHub bundle includes:\n\n```json\n{\n \"name\": \"sidebutton/github\",\n \"version\": \"1.0.0\",\n \"title\": \"GitHub Automation\",\n \"description\": \"Workflows for GitHub releases, PR reviews, and repository management\",\n \"workflows\": [\n \"open_release_page.yaml\",\n \"decide_next_tag.yaml\",\n \"create_release.yaml\",\n \"github_pr_claude_review.yaml\"\n ],\n \"requires\": {\n \"llm\": true,\n \"browser\": true\n }\n}\n```\n\n资料来源：[bundles/github/bundle.json]()\n\n## Adding Custom Workflows\n\nThe easiest way to contribute is by adding workflows to the `workflows/` directory:\n\n```bash\n# Create a new workflow file\ncat > workflows/my_workflow.yaml << 'EOF'\nid: my_workflow\ntitle: \"My Workflow\"\ndescription: \"What this workflow does\"\nsteps:\n - type: shell.run\n cmd: \"echo 'Hello!'\"\nEOF\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## See Also\n\n- [Step Reference](https://docs.sidebutton.com) — Complete documentation for all step types\n- [MCP Tools](https://docs.sidebutton.com/mcp) — Model Context Protocol integration\n- [Server Documentation](../server/README.md) — Backend workflow execution\n- [Core Engine](../core/README.md) — Workflow engine internals\n\n---\n\n\n\n## MCP Server Integration\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture), [Chrome Extension](#chrome-extension), [Knowledge Packs](#knowledge-packs)\n\n
\nRelated Source Files\n\n以下源码文件用于生成本页说明：\n\n- [packages/server/src/mcp/handler.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/handler.ts)\n- [packages/server/src/mcp/tools.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/tools.ts)\n- [packages/server/src/mcp/stdio.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/stdio.ts)\n- [packages/server/src/server.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/server.ts)\n- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n
\n\n# MCP Server Integration\n\n## Overview\n\nThe SideButton MCP Server is the core integration layer that exposes browser automation tools, workflow execution capabilities, and knowledge pack management through the Model Context Protocol (MCP). This enables AI assistants like Claude Desktop, Claude Code, and Cursor to control web browsers and execute automated workflows using a standardized interface.\n\n**资料来源：** [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n\n## Architecture\n\nThe MCP server is built as part of the `@sidebutton/server` package and supports multiple transport mechanisms for different AI assistant clients.\n\n### Transport Modes\n\n| Transport | Use Case | Configuration |\n|-----------|----------|---------------|\n| **HTTP/SSE** | Claude Code, Cursor | `type: \"sse\"`, `url: \"http://localhost:9876/mcp\"` |\n| **stdio** | Claude Desktop | `command: \"npx\"`, `args: [\"sidebutton\", \"--stdio\"]` |\n| **WebSocket** | Chrome Extension | Automatic reconnection support |\n\n**资料来源：** [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n\n### Component Flow\n\n```mermaid\ngraph TD\n subgraph \"AI Assistant\"\n A[Claude Desktop / Claude Code / Cursor]\n end\n \n subgraph \"MCP Transport\"\n B[stdio / HTTP-SSE]\n end\n \n subgraph \"SideButton Server\"\n C[MCP Handler]\n D[Tool Registry]\n E[Workflow Engine]\n F[Browser Controller]\n end\n \n subgraph \"Browser Layer\"\n G[Chrome Extension]\n H[Real DOM Access]\n end\n \n A --> B\n B --> C\n C --> D\n C --> E\n C --> F\n F <--> G\n G <--> H\n```\n\n## Tool Registry\n\nThe MCP server exposes a comprehensive set of tools organized by functionality. Each tool follows a consistent schema with annotations for the Claude Connectors Directory.\n\n**资料来源：** [packages/server/src/mcp/tools.ts:1-50](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/tools.ts)\n\n### Tool Annotations\n\n| Annotation | Purpose | Example |\n|------------|---------|---------|\n| `title` | Human-readable display name | `\"Run Workflow\"` |\n| `readOnlyHint` | Indicates observation-only tools | `true` for `snapshot` |\n| `destructiveHint` | Indicates state-mutating tools | `true` for `run_workflow` |\n| `openWorldHint` | Indicates external world interaction | `true` for browser tools |\n\n**资料来源：** [packages/server/src/mcp/tools.ts:14-23](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/tools.ts)\n\n## Workflow Tools\n\n### Core Workflow Operations\n\n| Tool | Description | Mutates State |\n|------|-------------|---------------|\n| `run_workflow` | Execute a workflow automation by ID | Yes |\n| `list_workflows` | List all available workflows | No |\n| `get_workflow` | Get workflow YAML definition | No |\n| `list_run_logs` | List recent workflow executions | No |\n| `get_run_log` | Get execution log for a specific run | No |\n\n### run_workflow Parameters\n\n```typescript\n{\n workflow_id: string; // Required: Unique identifier\n params?: { // Optional: Key-value parameters\n [key: string]: string;\n };\n}\n```\n\n**资料来源：** [packages/server/src/mcp/tools.ts:35-52](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/tools.ts)\n\n## Browser Automation Tools\n\nThe MCP server provides direct browser control through the connected Chrome Extension.\n\n### Navigation & State\n\n| Tool | Description |\n|------|-------------|\n| `navigate` | Navigate browser to a URL |\n| `snapshot` | Get page accessibility tree (DOM structure) |\n| `screenshot` | Capture page screenshot |\n| `get_browser_status` | Check extension connection status |\n| `capture_page` | Capture CSS selectors from current page |\n\n### Interaction Tools\n\n| Tool | Description | Read-Only |\n|------|-------------|-----------|\n| `click` | Click an element by selector | No |\n| `type` | Type text into an input element | No |\n| `scroll` | Scroll the page | No |\n| `hover` | Hover over an element | No |\n| `extract` | Extract text from an element | Yes |\n| `extract_all` | Extract text from all matching elements | Yes |\n| `extract_map` | Extract structured data from repeated elements | Yes |\n| `select_option` | Select a dropdown option | No |\n| `wait` | Wait for element or condition | No |\n| `exists` | Check if element exists | Yes |\n| `key` | Press a keyboard key | No |\n\n**资料来源：** [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n\n### Browser Tool Annotations\n\n```typescript\n{\n name: 'snapshot',\n description: 'Get page accessibility snapshot',\n inputSchema: {\n type: 'object',\n properties: {\n // Configuration options\n }\n },\n annotations: {\n title: 'Page Snapshot',\n readOnlyHint: true, // Observation only\n openWorldHint: true // Interacts with browser\n }\n}\n```\n\n## Provider Integration Tools\n\nSideButton integrates with external providers for enhanced functionality:\n\n| Category | Tools |\n|----------|-------|\n| **Git** | `git.listPRs`, `git.getPR`, `git.createPR`, `git.listIssues`, `git.getIssue` |\n| **Issues** | `issues.search`, `issues.get`, `issues.create`, `issues.transition`, `issues.comment`, `issues.attach` |\n| **Chat** | `chat.readChannel`, `chat.readThread`, `chat.listChannels` |\n| **Terminal** | `terminal.open`, `terminal.run` |\n| **LLM** | `llm.generate`, `llm.decide`, `llm.classify` |\n\n### Git Provider Implementation\n\nThe GitHub CLI connector provides programmatic access to GitHub operations:\n\n```typescript\nasync createPullRequest(params: {\n repo?: string;\n title: string;\n body?: string;\n head: string;\n base?: string;\n}): Promise<{ number: number; url: string }>\n```\n\n**资料来源：** [packages/core/src/providers/github.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/providers/github.ts)\n\n## MCP Endpoint Configuration\n\n### Server Endpoints\n\n| Endpoint | Method | Purpose |\n|----------|--------|---------|\n| `/mcp` | SSE | Server-Sent Events for Claude Code/Cursor |\n| `/mcp` | POST | Tool invocation requests |\n| `/mcp` | GET | Server info and capabilities |\n\n**资料来源：** [packages/server/src/server.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/server.ts)\n\n### Client Configuration Examples\n\n#### Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"sidebutton\": {\n \"command\": \"npx\",\n \"args\": [\"sidebutton\", \"--stdio\"]\n }\n }\n}\n```\n\n#### Claude Code\n\n```json\n{\n \"mcpServers\": {\n \"sidebutton\": {\n \"type\": \"sse\",\n \"url\": \"http://localhost:9876/mcp\"\n }\n }\n}\n```\n\n#### Cursor\n\n```json\n{\n \"mcpServers\": {\n \"sidebutton\": {\n \"url\": \"http://localhost:9876/mcp\"\n }\n }\n}\n```\n\n**资料来源：** [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n\n## CLI Commands for MCP\n\nThe `sidebutton` CLI provides workflow management commands:\n\n```bash\nsidebutton list # List available workflows\nsidebutton run # Run a workflow by ID\nsidebutton status # Check server status\n```\n\n**资料来源：** [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n\n## Data Models\n\n### MCP Tool Schema\n\n```typescript\nexport interface McpTool {\n name: string;\n description: string;\n inputSchema: Record;\n annotations?: McpToolAnnotations;\n}\n\nexport interface McpToolAnnotations {\n title: string;\n readOnlyHint?: true;\n destructiveHint?: true;\n openWorldHint?: true;\n}\n```\n\n**资料来源：** [packages/server/src/mcp/tools.ts:7-23](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/tools.ts)\n\n## Quick Start\n\n1. **Start the server:**\n ```bash\n npx sidebutton@latest\n ```\n\n2. **Connect your AI assistant** using the appropriate configuration above\n\n3. **Verify connection:**\n ```bash\n sidebutton status\n ```\n\n4. **Execute a workflow:**\n ```bash\n sidebutton run \n ```\n\n**资料来源：** [AGENTS.md](https://github.com/sidebutton/sidebutton/blob/main/AGENTS.md)\n\n## See Also\n\n- [Core Workflow Engine](../core/README.md) - Workflow execution runtime\n- [Chrome Extension](../extension/) - Browser control implementation\n- [Knowledge Packs](../knowledge-packs/) - Domain-specific automation packs\n\n---\n\n\n\n## Chrome Extension\n\n### 相关页面\n\n相关主题：[MCP Server Integration](#mcp-server), [Step Types Reference](#step-types)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/sidebutton/sidebutton/blob/main/CONTRIBUTING.md)\n- [AGENTS.md](https://github.com/sidebutton/sidebutton/blob/main/AGENTS.md)\n- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n- [packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n- [packages/server/defaults/roles/software-engineer.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/software-engineer.md)\n- [packages/server/defaults/roles/qa.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/qa.md)\n- [packages/server/defaults/targets/_provider-github-browser.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/targets/_provider-github-browser.md)\n
\n\n# Chrome Extension\n\nThe SideButton Chrome Extension is a Manifest V3 browser extension that provides real-time browser automation capabilities through a WebSocket connection to the local MCP server. It enables AI agents and workflows to interact with web pages using real DOM access via CSS selectors.\n\n## Overview\n\nThe Chrome Extension serves as the primary interface between SideButton's workflow engine and web pages. Rather than relying on pixel coordinates or screenshots, it provides direct DOM manipulation capabilities, making browser automation precise and reliable.\n\n**Distribution:** Available on the [Chrome Web Store](https://chromewebstore.google.com/detail/sidebutton/odaefhmdmgijnhdbkfagnlnmobphgkij)\n\n**Source location:** `extension/` directory in the repository\n\n资料来源：[CONTRIBUTING.md](https://github.com/sidebutton/sidebutton/blob/main/CONTRIBUTING.md)\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"Browser Context\"\n CE[Chrome Extension]\n WS[WebSocket Connection]\n end\n \n subgraph \"Local Server\"\n MCP[MCP Server :9876]\n API[REST API]\n end\n \n subgraph \"Workflow Engine\"\n WE[Workflow Executor]\n ST[Step Types]\n end\n \n CE -->|Real DOM Access| PAGE[Web Pages]\n CE -->|WebSocket| WS\n WS --> MCP\n MCP --> WE\n WE --> ST\n ST -->|browser.* steps| CE\n```\n\n### Connection Flow\n\n1. User clicks the SideButton extension icon in Chrome\n2. Extension establishes WebSocket connection to `http://localhost:9876`\n3. MCP server validates the connection and exposes browser tools\n4. Workflows execute browser steps through the extension\n5. Extension interacts with web pages via Chrome DevTools Protocol\n\n资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n## Browser Commands\n\nThe extension supports 40+ browser commands organized into functional categories:\n\n| Command | Description | Use Case |\n|---------|-------------|----------|\n| `navigate` | Navigate browser to URL | Open pages for automation |\n| `click` | Click an element by selector | Interact with buttons, links |\n| `type` | Type text into an element | Form input |\n| `scroll` | Scroll the page | Load more content |\n| `hover` | Hover over element | Trigger hover states |\n| `extract` | Extract text from element | Read page content |\n| `extract_all` | Extract all matching elements | Get lists of items |\n| `extract_map` | Extract structured data from repeated elements | Scrape data tables |\n| `select_option` | Select dropdown option | Choose from selects |\n| `fill` | Fill input value (React-compatible) | Handle React inputs |\n| `press_key` | Send keyboard keys | Keyboard shortcuts |\n| `scroll_into_view` | Scroll element into viewport | Ensure element visible |\n| `evaluate` | Execute JavaScript in browser | Custom interactions |\n| `exists` | Check if element exists | Conditional logic |\n| `wait` | Wait for element or delay | Synchronize with page |\n| `screenshot` | Capture page screenshot | Visual verification |\n| `snapshot` | Get page accessibility tree | Understand page structure |\n| `capture_page` | Capture selectors from current page | Identify elements |\n| `check_writing_quality` | Evaluate text quality | Content validation |\n\n资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n## Key Features\n\n### Real DOM Access\n\nUnlike screen-based automation tools that rely on pixel coordinates or OCR, SideButton uses real DOM access through CSS selectors. This provides:\n\n- Precise element targeting\n- Works with dynamically rendered content\n- Handles SPA (Single Page Applications) correctly\n- Faster execution than vision-based alternatives\n\n资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n### Recording Mode\n\nThe extension includes a recording mode that captures manual actions as reusable workflows. This enables:\n\n1. Manual browsing through desired workflow steps\n2. Extension records each action with selector\n3. Export as YAML workflow definition\n4. Replay with workflow engine\n\n### Embed Buttons\n\nSideButton can inject action buttons into any web page, enabling:\n\n- Quick access to defined actions\n- On-page automation triggers\n- Custom UI integration\n\n### WebSocket Connection\n\nThe extension maintains a stable WebSocket connection with automatic reconnection:\n\n```mermaid\nsequenceDiagram\n participant EXT as Extension\n participant WS as WebSocket\n participant MCP as MCP Server\n participant PAGE as Web Page\n \n EXT->>WS: Connect\n WS->>MCP: Establish Session\n MCP-->>WS: Connected\n WS-->>EXT: Ready\n \n loop On Command\n MCP->>EXT: Execute Tool\n EXT->>PAGE: DOM Action\n PAGE-->>EXT: Result\n EXT-->>MCP: Response\n end\n \n Note over EXT,WS: Auto-reconnect on disconnect\n```\n\n### Stable Reconnection\n\nThe WebSocket implementation handles connection drops gracefully:\n\n- Automatic retry with exponential backoff\n- Works with local server instances\n- Supports remote server connections\n- Maintains session state across reconnections\n\n资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n## Installation\n\n### From Chrome Web Store\n\n1. Visit the [Chrome Web Store listing](https://chromewebstore.google.com/detail/sidebutton/odaefhmdmgijnhdbkfagnlnmobphgkij)\n2. Click \"Add to Chrome\"\n3. Grant necessary permissions\n\n### From Source (Development)\n\n1. Go to `chrome://extensions/`\n2. Enable **Developer mode**\n3. Click **Load unpacked** and select the `extension/` folder\n4. Navigate to any page and click the extension icon to connect\n\n资料来源：[CONTRIBUTING.md](https://github.com/sidebutton/sidebutton/blob/main/CONTRIBUTING.md)\n\n## Connection States\n\n| State | Indicator | Meaning |\n|-------|-----------|---------|\n| Connected | Green dot | Extension linked to server |\n| Disconnected | Red dot | No active connection |\n| Reconnecting | Yellow dot | Attempting to reconnect |\n\nVerify connection status using the MCP `get_browser_status` tool:\n\n```json\n{\n \"tool\": \"get_browser_status\",\n \"expected\": { \"connected\": true }\n}\n```\n\n资料来源：[packages/server/defaults/roles/qa.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/qa.md)\n\n## Usage in Workflows\n\nBrowser steps are defined in YAML workflows:\n\n```yaml\nsteps:\n - type: browser.navigate\n url: \"https://github.com/owner/repo/issues\"\n \n - type: browser.snapshot\n as: page_state\n \n - type: browser.click\n selector: \".btn-primary\"\n \n - type: browser.type\n selector: \"#title\"\n text: \"{{issue_title}}\"\n \n - type: browser.extract\n selector: \".issue-number\"\n as: new_issue_id\n```\n\n### Variable Interpolation\n\nUse `{{variable}}` syntax to reference extracted values:\n\n```yaml\nsteps:\n - type: browser.extract\n selector: \".username\"\n as: user\n - type: shell.run\n cmd: \"echo 'Hello, {{user}}!'\"\n```\n\n资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n## Step Types Reference\n\n### Navigation Steps\n\n| Step Type | Parameters | Description |\n|-----------|------------|-------------|\n| `browser.navigate` | `url` | Open URL in connected browser |\n\n### Interaction Steps\n\n| Step Type | Parameters | Description |\n|-----------|------------|-------------|\n| `browser.click` | `selector` | Click element by CSS selector |\n| `browser.type` | `selector`, `text` | Type text into input |\n| `browser.fill` | `selector`, `value` | Fill input value (React-compatible) |\n| `browser.hover` | `selector` | Hover over element |\n| `browser.select_option` | `selector`, `value` | Select dropdown option |\n| `browser.press_key` | `keys` | Send keyboard keys |\n| `browser.scroll` | `direction`, `amount` | Scroll page |\n| `browser.scroll_into_view` | `selector` | Scroll element into view |\n\n### Extraction Steps\n\n| Step Type | Parameters | Description |\n|-----------|------------|-------------|\n| `browser.extract` | `selector`, `as` | Extract text from single element |\n| `browser.extract_all` | `selector`, `as` | Extract all matching elements |\n| `browser.extract_map` | `selector`, `mapping`, `as` | Extract structured data |\n| `browser.snapshot` | `as` | Get accessibility tree |\n| `browser.screenshot` | `as` | Capture screenshot |\n\n### Verification Steps\n\n| Step Type | Parameters | Description |\n|-----------|------------|-------------|\n| `browser.exists` | `selector` | Check if element exists |\n| `browser.wait` | `selector` or `ms` | Wait for element or delay |\n\n### Advanced Steps\n\n| Step Type | Parameters | Description |\n|-----------|------------|-------------|\n| `browser.capture_page` | - | Capture selectors from current page |\n| `browser.evaluate` | `script` | Execute JavaScript |\n\n资料来源：[packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n\n## Integration with Providers\n\nThe extension works with platform-specific browser providers for deeper integration:\n\n### GitHub Browser Provider\n\nWhen configured with `GITHUB_BROWSER_URL`, the extension can:\n\n1. Navigate to repository pages\n2. Read PR details via snapshot\n3. Review diffs by clicking \"Files changed\" tab\n4. List and filter pull requests\n5. Create issues through the web interface\n\n**Configuration:** Set `GITHUB_BROWSER_URL` in Settings > Environment Variables (e.g., `https://github.com`)\n\n**Requirements:** Must be logged into GitHub in the connected browser session\n\n资料来源：[packages/server/defaults/targets/_provider-github-browser.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/targets/_provider-github-browser.md)\n\n## Provider Preference\n\nWhen multiple integration methods exist, SideButton follows this preference order:\n\n1. **API Provider** — Fastest and most reliable\n2. **CLI Tool** — Good for git operations, builds\n3. **Browser Automation** — Universal fallback for visual tasks\n\n```mermaid\ngraph LR\n A[Task] --> B{API Available?}\n B -->|Yes| C[Use API]\n B -->|No| D{CLI Available?}\n D -->|Yes| E[Use CLI]\n D -->|No| F[Browser Automation]\n \n C -->|Browser needed| G[Browser via Extension]\n E -->|Visual review| G\n```\n\nBrowser tools complement CLI for visual tasks like:\n\n- Diff viewing\n- Board reviews\n- UI bug identification\n- Screenshot evidence\n\n资料来源：[packages/server/defaults/roles/software-engineer.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/software-engineer.md)\n\n## Smoke Test\n\nVerify extension connectivity during deployment testing:\n\n### Step 1: Server Health\n\n```\nGET http://localhost:9876/health\n```\n\nExpected response:\n```json\n{\"status\":\"ok\",\"version\":\"...\",\"browser_connected\":true}\n```\n\nIf `browser_connected: false` — stop, Chrome extension is not connected.\n\n### Step 2: Extension Connection\n\nUse `get_browser_status` tool:\n\nExpected: `{ \"connected\": true }`\n\nIf disconnected:\n1. Open Chrome\n2. Verify SideButton extension is enabled at `chrome://extensions`\n3. Refresh the page\n\n### Step 3: Snapshot Test\n\nNavigate to any page, then use `snapshot`:\n\nVerify: Returns structured YAML with element refs (ref=N), not empty, contains page elements.\n\n资料来源：[packages/server/defaults/roles/qa.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/qa.md)\n\n## Error Handling\n\nCommon extension issues and solutions:\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| `browser_connected: false` | Extension not connected | Click extension icon to connect |\n| WebSocket timeout | Server not running | Start with `pnpm dev:server` |\n| Element not found | Selector changed | Use `capture_page` to refresh selectors |\n| React input issues | Virtual DOM | Use `fill` instead of `type` |\n\n## Security Considerations\n\n- Browser extension requires significant permissions for DOM access\n- WebSocket connection is local by default\n- Remote connections should use authenticated endpoints\n- Never store credentials in workflow definitions\n\n资料来源：[AGENTS.md](https://github.com/sidebutton/sidebutton/blob/main/AGENTS.md)\n\n## Related Documentation\n\n- [MCP Tools Reference](https://docs.sidebutton.com) — Full tool documentation\n- [Workflow Engine](../core/workflow-engine.md) — Workflow execution\n- [REST API](../server/rest-api.md) — HTTP API alternative\n- [Knowledge Packs](../knowledge-packs/overview.md) — Domain-specific extensions\n\n---\n\n\n\n## Knowledge Packs\n\n### 相关页面\n\n相关主题：[MCP Server Integration](#mcp-server), [Getting Started](#getting-started)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/server/src/skill-pack.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/skill-pack.ts)\n- [packages/server/src/registry.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/registry.ts)\n- [packages/server/src/cli.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)\n- [packages/server/defaults/targets/github.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/targets/github.md)\n- [packages/server/defaults/roles/software-engineer.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/software-engineer.md)\n
\n\n# Knowledge Packs\n\nKnowledge Packs (also referred to as **Skill Packs** in CLI commands and code) are installable domain-specific modules that teach autonomous AI agents how specific web applications work. They serve as the foundational knowledge layer powering AI code review, automated testing, and enterprise AI agent deployments.\n\n## Overview\n\nKnowledge Packs provide structured, domain-specific intelligence to the SideButton platform. Rather than requiring AI agents to learn from scratch how to interact with each web application, Knowledge Packs pre-package essential information that enables immediate, accurate automation.\n\nThe SideButton registry currently hosts **11 domains** with **28+ modules** published, and maintains an open registry where anyone can build and share packs for any web application.\n\n资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n## Pack Components\n\nEach Knowledge Pack comprises five core module types that together provide comprehensive domain understanding:\n\n| Component | Description | Purpose |\n|-----------|-------------|---------|\n| **Selectors** | CSS selectors for UI elements | Precise DOM element targeting without pixel coordinates or screenshots |\n| **Data Models** | Entity types, fields, relationships, valid states | Structured understanding of domain objects |\n| **State Machines** | Valid transitions per state | Predictable, safe workflow execution |\n| **Role Playbooks** | Role-specific procedures (QA, SE, PM, SD) | Context-aware guidance for different user roles |\n| **Common Tasks** | Step-by-step procedures, gotchas, edge cases | Handling typical operations with best practices |\n\n资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n### Selector Modules\n\nSelectors provide CSS-based targeting for browser automation, ensuring reliability across different browsers and viewport sizes. Unlike coordinate-based or screenshot-based approaches, CSS selectors remain stable as long as the application's DOM structure is maintained.\n\n### Role Playbooks\n\nRole playbooks define standard operating procedures for specific personas. For example, the `software-engineer` role includes:\n\n- Decision guidance for issue prioritization\n- Step types for common development tasks\n- Integration patterns for git, issues, chat, and terminal operations\n\n资料来源：[packages/server/defaults/roles/software-engineer.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/software-engineer.md)\n\n## Architecture\n\n```mermaid\ngraph TD\n A[User/Agent] -->|sidebutton install| B[CLI]\n B --> C{Source Type}\n C -->|Local Path| D[Local Directory]\n C -->|Git URL| E[Git Repository]\n C -->|Registry Name| F[SideButton Registry]\n \n D --> G[Install Skill Pack]\n E --> G\n F --> H[Fetch from Registry API]\n H --> G\n \n G --> I[Parse Manifest]\n I --> J[Copy to ~/.sidebutton/packs/]\n J --> K[Knowledge Pack Active]\n \n L[Workflow Engine] -->|Uses| K\n M[MCP Tools] -->|Reads| K\n```\n\n## Installation Methods\n\nKnowledge Packs can be installed from multiple sources:\n\n| Source Type | Command Example | Use Case |\n|-------------|-----------------|----------|\n| Local directory | `sidebutton install ./my-pack` | Development and testing |\n| Git URL | `sidebutton install https://github.com/org/skill-packs` | Remote repositories |\n| Registry name | `sidebutton install github.com` | Published registry packs |\n\n```bash\n# Install from registry\nsidebutton install github.com\nsidebutton install atlassian.net\n\n# Install from local path\nsidebutton install ./custom-pack\n\n# Install from Git URL\nsidebutton install https://github.com/org/skill-packs\n\n# Force reinstall\nsidebutton install github.com --force\n```\n\n资料来源：[packages/server/src/cli.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)\n\n## Registry Management\n\nThe registry system allows centralized distribution and discovery of Knowledge Packs.\n\n### Registry CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `sidebutton registry add ` | Register and install all packs from a registry |\n| `sidebutton registry update [name]` | Update installed packs from registry |\n| `sidebutton registry remove ` | Uninstall packs and remove registry |\n| `sidebutton registry list` | Show registries and pack counts |\n| `sidebutton search [query]` | Search packs across registries |\n\n资料来源：[packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n\n### Registry Configuration\n\nRegistries are stored in the SideButton configuration directory (`~/.sidebutton/registries.json`) and contain metadata about available skill pack sources.\n\n## Publishing Knowledge Packs\n\n### Publishing Process\n\n1. **Initialize** a new pack using `sidebutton init [domain]`\n2. **Develop** the pack with manifest and modules\n3. **Validate** using `sidebutton validate [path]`\n4. **Authenticate** with `sidebutton login`\n5. **Publish** via `sidebutton publish`\n\n### Manifest Structure\n\nThe `manifest.json` defines the pack's metadata:\n\n```json\n{\n \"domain\": \"github.com\",\n \"title\": \"GitHub\",\n \"version\": \"1.0.0\",\n \"description\": \"GitHub integration for AI agents\",\n \"tagline\": \"Streamlined GitHub workflows\",\n \"category\": \"development\",\n \"modules\": [\"selectors\", \"data-models\", \"state-machines\"],\n \"roles\": [\"software-engineer\", \"qa\"]\n}\n```\n\n资料来源：[packages/server/src/cli.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)\n\n### Publishing Endpoint\n\n```typescript\nconst res = await fetch(`${REMOTE_BASE_URL}/api/skill-packs/publish`, {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n 'Authorization': `Bearer ${auth.token}`,\n },\n body: JSON.stringify({\n domain: manifest.domain,\n name: manifest.title || manifest.name || manifest.domain,\n version: manifest.version,\n description: manifest.description || '',\n tagline: manifest.tagline || '',\n modules: manifest.modules || [],\n roles: manifest.roles || [],\n category: manifest.category || '',\n manifest,\n files,\n }),\n});\n```\n\n资料来源：[packages/server/src/cli.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)\n\n## Integration with Workflow Engine\n\nKnowledge Packs integrate with the core SideButton workflow engine through step types that reference pack-specific configurations:\n\n```mermaid\ngraph LR\n A[Knowledge Pack] --> B[Step Type Resolution]\n B --> C[Provider Selection]\n C --> D[Git Provider]\n C --> E[Issues Provider]\n C --> F[Chat Provider]\n C --> G[Browser Provider]\n```\n\n### Available Step Types\n\n| Category | Steps |\n|----------|-------|\n| Browser | `navigate`, `click`, `type`, `scroll`, `hover`, `wait`, `extract`, `extractAll`, `exists`, `key` |\n| Shell | `shell.run`, `terminal.open`, `terminal.run` |\n| LLM | `llm.classify`, `llm.generate` |\n| Control | `control.if`, `control.retry`, `control.stop`, `workflow.call` |\n| Data | `data.first` |\n| Git | `git.listPRs`, `git.getPR`, `git.createPR`, `git.listIssues`, `git.getIssue` |\n| Issues | `issues.search`, `issues.get`, `issues.create`, `issues.transition`, `issues.comment` |\n| Chat | `chat.readChannel`, `chat.readThread`, `chat.listChannels` |\n\n资料来源：[packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n\n## Development Workflow\n\n### Creating a New Pack\n\n```bash\n# Initialize a new knowledge pack\nsidebutton init my-app.com\n\n# Scaffolded structure:\n# my-app.com/\n# ├── manifest.json\n# ├── modules/\n# │ ├── selectors/\n# │ ├── data-models/\n# │ └── state-machines/\n# ├── roles/\n# │ └── software-engineer.md\n# └── targets/\n# └── github.md\n```\n\n### Validation\n\nBefore publishing, validate the pack structure:\n\n```bash\nsidebutton validate ./my-app.com\n```\n\nThis command lints and checks:\n- Manifest completeness\n- Module structure validity\n- Selector syntax correctness\n- File integrity\n\n## Configuration Locations\n\n| Path | Purpose |\n|------|---------|\n| `~/.sidebutton/packs/` | Installed Knowledge Pack directories |\n| `~/.sidebutton/registries.json` | Registry configurations |\n| `~/.sidebutton/config.json` | Main SideButton configuration |\n\n## Best Practices\n\n1. **Selector Stability**: Use semantic CSS selectors that won't change with visual updates\n2. **Versioning**: Follow semantic versioning for pack updates\n3. **Error Handling**: Include edge case documentation in Common Tasks\n4. **Role Coverage**: Provide at least one role playbook for each major user persona\n5. **State Documentation**: Clearly define all valid state transitions\n\n## Available Packs\n\nThe SideButton registry includes Knowledge Packs for popular platforms:\n\n| Domain | Category | Modules |\n|--------|----------|---------|\n| github.com | Development | Selectors, Data Models, SE Role |\n| atlassian.net | Development | Selectors, Data Models |\n| *(10 more domains)* | Various | Various |\n\n资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n## See Also\n\n- [Core Workflow Engine](../core/README.md) - `@sidebutton/core` package\n- [MCP Server](../server/README.md) - `@sidebutton/server` package with REST API\n- [Chrome Extension](../extension/README.md) - Browser extension integration\n- [Full Documentation](https://docs.sidebutton.com)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：sidebutton/sidebutton\n\n摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Add control.foreach step type for iterating over lists。\n\n## 1. 安装坑 · 来源证据：Add control.foreach step type for iterating over lists\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add control.foreach step type for iterating over lists\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d7567e53b1794e828bb3342cb0699f6f | https://github.com/sidebutton/sidebutton/issues/1 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 来源证据：Native elements cannot be programmatically selected via click/type tools\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a2eadefee45c45b2be1b8501c1a0724f | https://github.com/sidebutton/sidebutton/issues/12 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 8. 安全/权限坑 · 来源证据：v1.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a9cfb55ebc664ee99dcc39773859d715 | https://github.com/sidebutton/sidebutton/releases/tag/v1.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | issue_or_pr_quality=unknown\n\n## 10. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | release_recency=unknown\n\n\n", "markdown_key": "sidebutton", "pages": "draft", "source_refs": [ { "evidence_id": "github_repo:1124378210", "kind": "repo", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/sidebutton/sidebutton" }, { "evidence_id": "art_6d90ca67b4e441d1911c7e58394e188d", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/sidebutton/sidebutton#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "sidebutton 说明书", "toc": [ "https://github.com/sidebutton/sidebutton 项目说明书", "目录", "Introduction to SideButton", "High-Level Architecture", "Package Structure", "Core Concepts", "MCP Integration", "CLI Commands", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": true, "repo_commit": "8259d7558b61af849e5da2c71659cc1136064a99", "repo_inspection_error": null, "repo_inspection_files": [ "pnpm-lock.yaml", "package.json", "README.md", "packages/dashboard/vite.config.ts", "packages/dashboard/svelte.config.js", "packages/dashboard/package.json", "packages/dashboard/tsconfig.json", "packages/server/server.json", "packages/server/package.json", "packages/server/tsup.config.ts", "packages/server/README.md", "packages/server/tsconfig.json", "packages/core/package-lock.json", "packages/core/package.json", "packages/core/tsup.config.ts", "packages/core/README.md", "packages/core/tsconfig.json", "packages/sidebutton/package.json", "packages/sidebutton/README.md", "packages/dashboard/src/main.ts", "packages/dashboard/src/vite-env.d.ts", "packages/dashboard/src/lib/router.ts", "packages/dashboard/src/lib/stores.ts", "packages/dashboard/src/lib/websocket.ts", "packages/dashboard/src/lib/api.ts", "packages/dashboard/src/lib/types.ts", "packages/dashboard/src/lib/theme.ts", "packages/dashboard/src/lib/utils/stepFormatters.ts", "packages/server/bin/sidebutton.js", "packages/server/src/skill-pack.ts", "packages/server/src/version.ts", "packages/server/src/matching.ts", "packages/server/src/registry.ts", "packages/server/src/index.ts", "packages/server/src/server.ts", "packages/server/src/extension.ts", "packages/server/src/cli.ts", "packages/server/src/context.ts", "packages/server/src/stdio-mode.ts", "packages/server/src/sentry.ts" ], "repo_inspection_verified": true, "review_reasons": [], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# sidebutton - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 sidebutton 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`AGENTS.md`, `README.md`, `packages/core/README.md`, `packages/server/README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npx sidebutton@latest` 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0010` supported 0.86\n- `curl -X POST http://localhost:9876/api/workflows/check_ticket/run \\` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `curl http://localhost:9876/api/workflows` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `curl http://localhost:9876/api/runs/latest` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npm install @sidebutton/core` 证据：`packages/core/README.md` Claim：`clm_0007` supported 0.86\n- `npm install @sidebutton/server` 证据：`packages/server/README.md` Claim：`clm_0008` supported 0.86\n- `npx sidebutton` 证据：`packages/server/README.md` Claim：`clm_0003` supported 0.86, `clm_0009` supported 0.86, `clm_0010` supported 0.86\n- `npx sidebutton@latest # starts server + dashboard on port 9876` 证据：`AGENTS.md` Claim：`clm_0010` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`AGENTS.md`, `README.md`, `packages/core/README.md`, `packages/server/README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0010` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`AGENTS.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`AGENTS.md`, `README.md`, `packages/core/README.md`, `packages/server/README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`AGENTS.md`, `README.md`, `packages/core/README.md`, `packages/server/README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `docs-site/docs/features/llm.md`, `docs-site/docs/first-workflow.md`, `docs-site/docs/plugins/available.md` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0011` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`AGENTS.md`, `README.md`, `packages/core/README.md`, `packages/server/README.md` Claim：`clm_0012` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`AGENTS.md`, `README.md`, `packages/core/README.md`, `packages/server/README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：281\n- 重要文件覆盖：40/281\n- 证据索引条目：80\n- 角色 / Skill 条目：71\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 sidebutton 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 sidebutton 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 sidebutton 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 71 个角色 / Skill / 项目文档条目。\n\n- **Contributing**（project_doc）：Thank you for your interest in contributing to SideButton! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/contributing.md`\n- **AGENTS.md**（project_doc）：SideButton is an open-source AI agent platform: MCP server with browser tools, YAML workflow engine, and knowledge packs that bundle domain expertise per web app. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`AGENTS.md`\n- **SideButton**（project_doc）：Open-source AI agent platform — MCP server, knowledge packs, and workflow automation tools. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **SideButton Browser Extension**（project_doc）：The SideButton browser extension connects your browser to the SideButton server, enabling browser automation, workflow execution, and MCP tool access. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`extension/README.md`\n- **@sidebutton/core**（project_doc）：Core workflow engine for SideButton https://sidebutton.com - YAML-based browser and shell automation. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/core/README.md`\n- **@sidebutton/server**（project_doc）：SideButton https://sidebutton.com server with MCP integration, REST API, and web dashboard for workflow automation. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/README.md`\n- **SideButton**（project_doc）：Open source AI agent platform — MCP server with knowledge packs skill packs , AI agent tools, and workflow automation. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/sidebutton/README.md`\n- **Contributing to SideButton**（project_doc）：Thanks for your interest in contributing. SideButton is an open-source workflow automation tool licensed under Apache-2.0 LICENSE . Contributions of all kinds are welcome — bug reports, workflow additions, feature ideas, and code changes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **REST API**（project_doc）：HTTP endpoints for mobile apps and external integrations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/api/rest.md`\n- **Changelog**（project_doc）：- MCP OAuth 2.1 — full OAuth discovery and registration for Claude Code 2.1.84+ compatibility - Temporal orchestration panel — real-time workflow execution visibility in job detail view - Mobile-responsive portal — Fleet Control pages adapt to mobile/tablet viewports - Plugin system — extend the MCP server with custom tools via handler scripts in any language - 45 step types — added issues, git, chat, and data step… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/changelog.md`\n- **Community Roles**（project_doc）：SideButton ships with reusable role templates that teach AI agents specific job functions. Roles inject behavioral context into every LLM call — they define when and why an agent should act, not just how . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/community-roles.md`\n- **Extension Setup**（project_doc）：The Chrome extension enables browser automation — clicking, typing, scrolling, and extracting data from web pages. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/extension.md`\n- **Dashboard**（project_doc）：SideButton's web dashboard for managing workflows, recordings, and settings. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/features/dashboard.md`\n- **Embed Buttons**（project_doc）：Inject automation buttons directly into web pages — one-click actions right where you need them. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/features/embed.md`\n- **LLM Integration**（project_doc）：Use AI for text classification and generation within your workflows. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/features/llm.md`\n- **Recording Mode**（project_doc）：Create workflows by clicking through tasks — no coding required. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/features/recording.md`\n- **First Workflow**（project_doc）：Run your first automation in under 2 minutes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/first-workflow.md`\n- **SideButton MCP Server**（project_doc）：Open source platform for AI agents with structured roles, skills, and domain knowledge. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/index.md`\n- **Installation**（project_doc）：Get SideButton running on your computer in under 2 minutes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/installation.md`\n- **Jira Integration Setup**（project_doc）：This guide explains how to set up SideButton's Jira integration for creating tickets from any webpage. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/jira-setup.md`\n- **Knowledge Packs CLI Reference**（project_doc）：All commands for installing, managing, and searching knowledge packs. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/knowledge-packs/cli.md`\n- **Creating Knowledge Packs**（project_doc）：This guide covers how to build, test, and publish knowledge packs. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/knowledge-packs/creating.md`\n- **Skills and Knowledge Packs**（project_doc）：Knowledge packs are installable bundles of workflows, roles, and targets for a specific domain — like a plugin that teaches SideButton how to automate a web application. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/knowledge-packs/overview.md`\n- **Host Your Own Skill Pack Repository**（project_doc）：Host Your Own Skill Pack Repository 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/knowledge-packs/registries.md`\n- **MCP Setup**（project_doc）：Connect AI tools like Claude Code, Cursor, VS Code, and Windsurf to SideButton via the Model Context Protocol MCP . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/mcp-setup.md`\n- **Browser Tools**（project_doc）：Direct browser control via MCP for AI-assisted automation. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/mcp/browser.md`\n- **MCP Overview**（project_doc）：The Model Context Protocol MCP enables AI assistants to connect to SideButton for browser automation. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/mcp/overview.md`\n- **MCP Tools Reference**（project_doc）：Complete reference for all MCP tools available in SideButton. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/mcp/tools.md`\n- **Available Plugins**（project_doc）：Official SideButton plugins maintained by the team. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/plugins/available.md`\n- **Plugin CLI Reference**（project_doc）：Manage plugins from the command line. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/plugins/cli.md`\n- **Creating Plugins**（project_doc）：Build a SideButton plugin that adds custom MCP tools. Plugins can be written in any language — bash, Node.js, Python, or anything that reads stdin and writes stdout. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/plugins/creating.md`\n- **Plugins Overview**（project_doc）：Plugins extend SideButton's MCP server with custom tools — without modifying core code. Each plugin is a standalone directory containing a plugin.json manifest and one or more handler scripts in any language. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/plugins/overview.md`\n- **Cli**（project_doc）：window.location.replace '/knowledge-packs/cli' + window.location.hash 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/skill-packs/cli.md`\n- **Creating**（project_doc）：window.location.replace '/knowledge-packs/creating' + window.location.hash 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/skill-packs/creating.md`\n- **Overview**（project_doc）：window.location.replace '/knowledge-packs/overview' + window.location.hash 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/skill-packs/overview.md`\n- **Troubleshooting**（project_doc）：bash Find what's using the port lsof -i :9876 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/troubleshooting.md`\n- **DSL Reference**（project_doc）：Complete reference for the workflow YAML syntax. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/workflows/dsl.md`\n- **Workflow Examples**（project_doc）：Copy-paste these examples to get started quickly. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/workflows/examples.md`\n- **Workflows Overview**（project_doc）：Workflows are the heart of SideButton — reusable automation recipes defined in YAML. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/workflows/overview.md`\n- **Step Types**（project_doc）：Complete reference for all 45 step types available in SideButton 42 implemented, 3 chat types pending . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/workflows/steps.md`\n- **Variables**（project_doc）：Variables allow data to flow between workflow steps. Extract values from pages, use them in commands, and pass them between workflows. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs-site/docs/workflows/variables.md`\n- **What**（project_doc）：Brief description of what this PR does. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/PULL_REQUEST_TEMPLATE.md`\n- **Contributor Covenant Code of Conduct**（project_doc）：Contributor Covenant Code of Conduct 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CODE_OF_CONDUCT.md`\n- **Licensing**（project_doc）：SideButton uses a mixed licensing model. Most of the codebase is open source under Apache-2.0. Certain components use the Functional Source License FSL-1.1-Apache-2.0 . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`LICENSING.md`\n- **Security Policy**（project_doc）：Version Supported --------- ----------- 1.0.x Yes 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`\n- **Persona**（project_doc）：This file describes who you are. SideButton injects it into every LLM call so the AI knows your identity, preferences, and context. Edit this to match your real situation. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/persona.md`\n- **AI Tools**（project_doc）：Working with AI assistants, coding tools, and automated development workflows. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/roles/ai.md`\n- **DevOps Engineer**（project_doc）：Building and maintaining CI/CD pipelines, infrastructure, and developer tooling. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/roles/devops.md`\n- **Finance**（project_doc）：Managing invoicing, reconciliation, and financial reporting. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/roles/finance.md`\n- **HR & People Ops**（project_doc）：Managing onboarding, benefits, compliance, and people operations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/roles/hr.md`\n- **Marketing**（project_doc）：Creating content, managing brand awareness, and driving organic growth. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/roles/marketing.md`\n- **Operations**（project_doc）：Managing workflows, tracking work, and keeping teams aligned. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/roles/operations.md`\n- **Personal**（project_doc）：Managing personal tasks, entertainment, and productivity automations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/roles/personal.md`\n- **Product Manager**（project_doc）：Defining what to build, why, and in what order. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/roles/product-manager.md`\n- **QA Engineer**（project_doc）：Testing, verifying, and logging issues for app quality and stability. You validate solutions by using the real app in a browser — navigating pages, clicking buttons, filling forms, and verifying that features work as expected. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/roles/qa.md`\n- **Technical Recruiter**（project_doc）：Evaluating candidates for engineering roles. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/roles/recruiting.md`\n- **Researcher**（project_doc）：Gathering intelligence, synthesizing information, and producing actionable insights. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/roles/research.md`\n- **Sales**（project_doc）：Building relationships and closing deals through personalized outreach. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/roles/sales.md`\n- **Social Media Manager**（project_doc）：Managing social media presence, community engagement, and organic growth across platforms. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/roles/smm.md`\n- **Software Engineer**（project_doc）：Writing, reviewing, and shipping production code. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/roles/software-engineer.md`\n- **Customer Support**（project_doc）：Resolving customer issues quickly and empathetically. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/roles/support.md`\n- **General**（project_doc）：When unsure about tone, default to professional but casual. Prefer bullet points. Keep everything under 3 paragraphs. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/targets/_global.md`\n- **Bitbucket (REST API)**（project_doc）：Bitbucket Integration — REST API 2.0 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/targets/_provider-bitbucket-api.md`\n- **Bitbucket (Browser)**（project_doc）：Bitbucket is connected via browser automation. Use SideButton browser tools to navigate pull requests and review code. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/targets/_provider-bitbucket-browser.md`\n- **GitHub (Browser)**（project_doc）：GitHub is connected via browser automation. Use SideButton browser tools to navigate PRs, review diffs, and manage issues. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/targets/_provider-github-browser.md`\n- **GitHub (CLI)**（project_doc）：GitHub is connected via the gh CLI. You can manage pull requests and issues directly without opening a browser. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/targets/_provider-github-cli.md`\n- **Jira (REST API)**（project_doc）：Jira is connected via direct REST API. You can create, search, read, transition, and comment on issues without opening a browser. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/targets/_provider-jira-api.md`\n- **Jira (Browser)**（project_doc）：Jira is connected via browser automation. Use SideButton browser tools navigate , snapshot , click , type to interact with Jira boards and issues. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/targets/_provider-jira-browser.md`\n- **Jira (CLI)**（project_doc）：Jira Integration — Atlassian CLI acli 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/targets/_provider-jira-cli.md`\n- **Slack (Bot API)**（project_doc）：Slack is connected via Bot Token API. Use chat. step types for direct channel reads without opening a browser. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/targets/_provider-slack-api.md`\n- **Slack (Browser)**（project_doc）：Slack is connected via browser automation. Use SideButton browser tools to read and interact with messages. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/defaults/targets/_provider-slack-browser.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Contributing**（documentation）：Thank you for your interest in contributing to SideButton! 证据：`docs-site/docs/contributing.md`\n- **AGENTS.md**（documentation）：SideButton is an open-source AI agent platform: MCP server with browser tools, YAML workflow engine, and knowledge packs that bundle domain expertise per web app. 证据：`AGENTS.md`\n- **SideButton**（documentation）：Open-source AI agent platform — MCP server, knowledge packs, and workflow automation tools. 证据：`README.md`\n- **SideButton Browser Extension**（documentation）：The SideButton browser extension connects your browser to the SideButton server, enabling browser automation, workflow execution, and MCP tool access. 证据：`extension/README.md`\n- **@sidebutton/core**（documentation）：Core workflow engine for SideButton https://sidebutton.com - YAML-based browser and shell automation. 证据：`packages/core/README.md`\n- **@sidebutton/server**（documentation）：SideButton https://sidebutton.com server with MCP integration, REST API, and web dashboard for workflow automation. 证据：`packages/server/README.md`\n- **SideButton**（documentation）：Open source AI agent platform — MCP server with knowledge packs skill packs , AI agent tools, and workflow automation. 证据：`packages/sidebutton/README.md`\n- **Package**（package_manifest）：{ \"name\": \"@sidebutton/docs\", \"version\": \"1.0.0\", \"private\": true, \"type\": \"module\", \"scripts\": { \"dev\": \"vitepress dev docs\", \"build\": \"vitepress build docs\", \"preview\": \"vitepress preview docs\" }, \"devDependencies\": { \"vitepress\": \"^1.5.0\" } } 证据：`docs-site/package.json`\n- **Package**（package_manifest）：{ \"name\": \"sidebutton\", \"version\": \"1.0.0\", \"private\": true, \"type\": \"module\", \"scripts\": { \"build\": \"turbo build\", \"dev\": \"turbo dev\", \"dev:server\": \"pnpm --filter @sidebutton/server dev\", \"dev:dashboard\": \"pnpm --filter @sidebutton/dashboard dev\", \"dev:core\": \"pnpm --filter @sidebutton/core dev\", \"lint\": \"turbo lint\", \"test\": \"turbo test\", \"clean\": \"rm -rf node modules packages/ /node modules packages/ /dist\", \"start\": \"node packages/server/bin/sidebutton.js serve\", \"cli\": \"node packages/server/bin/sidebutton.js\", \"desktop\": \"pnpm --filter @sidebutton/desktop start\", \"desktop:build\": \"pnpm --filter @sidebutton/desktop make\" }, \"devDependencies\": { \"turbo\": \"^2.3.0\", \"typescript\": \"^5.7.2\"… 证据：`package.json`\n- **Contributing to SideButton**（documentation）：Thanks for your interest in contributing. SideButton is an open-source workflow automation tool licensed under Apache-2.0 LICENSE . Contributions of all kinds are welcome — bug reports, workflow additions, feature ideas, and code changes. 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"type\": \"module\" } 证据：`docs-site/docs/.vitepress/cache/deps/package.json`\n- **Package**（package_manifest）：{ \"type\": \"module\" } 证据：`docs-site/docs/.vitepress/cache/deps_temp_36d1e2cb/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@sidebutton/core\", \"version\": \"1.1.2\", \"description\": \"Core workflow automation engine for AI agents — agentic workflows in YAML\", \"keywords\": \"workflow\", \"automation\", \"yaml\", \"mcp\", \"ai-agents\", \"knowledge-packs\", \"browser-automation\", \"llm\", \"model-context-protocol\", \"open-source\" , \"type\": \"module\", \"main\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\", \"exports\": { \".\": { \"import\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" } }, \"files\": \"dist\" , \"scripts\": { \"build\": \"tsup\", \"dev\": \"tsup --watch\", \"test\": \"vitest run\", \"lint\": \"tsc --noEmit\" }, \"dependencies\": { \"js-yaml\": \"^4.1.1\", \"zod\": \"^4.3.6\" }, \"license\": \"Apache-2.0\", \"repository\": { \"type\": \"git\", \"url\": \"gi… 证据：`packages/core/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@sidebutton/dashboard\", \"version\": \"1.1.2\", \"license\": \"Apache-2.0\", \"type\": \"module\", \"scripts\": { \"dev\": \"vite build --watch\", \"dev:server\": \"vite\", \"build\": \"vite build\", \"preview\": \"vite preview\", \"lint\": \"tsc --noEmit\" }, \"dependencies\": { \"@sentry/svelte\": \"^10.48.0\", \"@sidebutton/core\": \"workspace: \", \"navaid\": \"^1.2.0\", \"svelte\": \"^5.55.3\" }, \"devDependencies\": { \"@sentry/vite-plugin\": \"^5.2.0\", \"@sveltejs/vite-plugin-svelte\": \"^7.0.0\", \"typescript\": \"^6.0.2\", \"vite\": \"^8.0.8\" } } 证据：`packages/dashboard/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@sidebutton/server\", \"version\": \"1.1.2\", \"mcpName\": \"io.github.sidebutton/sidebutton\", \"description\": \"SideButton MCP server for AI agents — REST API, web dashboard, knowledge packs, and workflow engine\", \"keywords\": \"mcp\", \"mcp-server\", \"model-context-protocol\", \"ai-agents\", \"knowledge-packs\", \"workflow\", \"automation\", \"browser-automation\", \"chrome-extension\", \"claude-code\", \"cursor\", \"open-source\" , \"type\": \"module\", \"main\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\", \"bin\": { \"sidebutton\": \"./bin/sidebutton.js\" }, \"exports\": { \".\": { \"import\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" }, \"./cli\": \"./dist/cli.js\" }, \"files\": \"dist\", \"bin\", \"dashboard\", \"defaults\" , \"… 证据：`packages/server/package.json`\n- **Package**（package_manifest）：{ \"name\": \"sidebutton\", \"version\": \"1.1.2\", \"description\": \"AI agent platform and MCP server — knowledge packs, AI agent tools, workflow automation, and CLI\", \"keywords\": \"mcp\", \"mcp-server\", \"model-context-protocol\", \"ai-agents\", \"knowledge-packs\", \"workflow\", \"automation\", \"browser-automation\", \"claude-code\", \"cursor\", \"sidebutton\", \"open-source\" , \"type\": \"module\", \"bin\": { \"sidebutton\": \"./bin/sidebutton.js\" }, \"files\": \"bin\" , \"license\": \"Apache-2.0\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/sidebutton/sidebutton.git\", \"directory\": \"packages/sidebutton\" }, \"homepage\": \"https://sidebutton.com\", \"bugs\": { \"url\": \"https://github.com/sidebutton/sidebutton/issues\" }, \"d… 证据：`packages/sidebutton/package.json`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **REST API**（documentation）：HTTP endpoints for mobile apps and external integrations. 证据：`docs-site/docs/api/rest.md`\n- **Changelog**（documentation）：- MCP OAuth 2.1 — full OAuth discovery and registration for Claude Code 2.1.84+ compatibility - Temporal orchestration panel — real-time workflow execution visibility in job detail view - Mobile-responsive portal — Fleet Control pages adapt to mobile/tablet viewports - Plugin system — extend the MCP server with custom tools via handler scripts in any language - 45 step types — added issues, git, chat, and data step categories 42 implemented, 3 chat pending - Knowledge pack CLI — sidebutton init , validate , and publish for creating and sharing knowledge packs - Context system — persona, roles, and targets injected into every LLM call via both REST and MCP - Community roles — 15 built-in rol… 证据：`docs-site/docs/changelog.md`\n- **Community Roles**（documentation）：SideButton ships with reusable role templates that teach AI agents specific job functions. Roles inject behavioral context into every LLM call — they define when and why an agent should act, not just how . 证据：`docs-site/docs/community-roles.md`\n- **Extension Setup**（documentation）：The Chrome extension enables browser automation — clicking, typing, scrolling, and extracting data from web pages. 证据：`docs-site/docs/extension.md`\n- **Dashboard**（documentation）：SideButton's web dashboard for managing workflows, recordings, and settings. 证据：`docs-site/docs/features/dashboard.md`\n- **Embed Buttons**（documentation）：Inject automation buttons directly into web pages — one-click actions right where you need them. 证据：`docs-site/docs/features/embed.md`\n- **LLM Integration**（documentation）：Use AI for text classification and generation within your workflows. 证据：`docs-site/docs/features/llm.md`\n- **Recording Mode**（documentation）：Create workflows by clicking through tasks — no coding required. 证据：`docs-site/docs/features/recording.md`\n- **First Workflow**（documentation）：Run your first automation in under 2 minutes. 证据：`docs-site/docs/first-workflow.md`\n- **SideButton MCP Server**（documentation）：Open source platform for AI agents with structured roles, skills, and domain knowledge. 证据：`docs-site/docs/index.md`\n- **Installation**（documentation）：Get SideButton running on your computer in under 2 minutes. 证据：`docs-site/docs/installation.md`\n- **Jira Integration Setup**（documentation）：This guide explains how to set up SideButton's Jira integration for creating tickets from any webpage. 证据：`docs-site/docs/jira-setup.md`\n- **Knowledge Packs CLI Reference**（documentation）：All commands for installing, managing, and searching knowledge packs. 证据：`docs-site/docs/knowledge-packs/cli.md`\n- **Creating Knowledge Packs**（documentation）：This guide covers how to build, test, and publish knowledge packs. 证据：`docs-site/docs/knowledge-packs/creating.md`\n- **Skills and Knowledge Packs**（documentation）：Knowledge packs are installable bundles of workflows, roles, and targets for a specific domain — like a plugin that teaches SideButton how to automate a web application. 证据：`docs-site/docs/knowledge-packs/overview.md`\n- **Host Your Own Skill Pack Repository**（documentation）：Host Your Own Skill Pack Repository 证据：`docs-site/docs/knowledge-packs/registries.md`\n- **MCP Setup**（documentation）：Connect AI tools like Claude Code, Cursor, VS Code, and Windsurf to SideButton via the Model Context Protocol MCP . 证据：`docs-site/docs/mcp-setup.md`\n- **Browser Tools**（documentation）：Direct browser control via MCP for AI-assisted automation. 证据：`docs-site/docs/mcp/browser.md`\n- **MCP Overview**（documentation）：The Model Context Protocol MCP enables AI assistants to connect to SideButton for browser automation. 证据：`docs-site/docs/mcp/overview.md`\n- **MCP Tools Reference**（documentation）：Complete reference for all MCP tools available in SideButton. 证据：`docs-site/docs/mcp/tools.md`\n- **Available Plugins**（documentation）：Official SideButton plugins maintained by the team. 证据：`docs-site/docs/plugins/available.md`\n- **Plugin CLI Reference**（documentation）：Manage plugins from the command line. 证据：`docs-site/docs/plugins/cli.md`\n- **Creating Plugins**（documentation）：Build a SideButton plugin that adds custom MCP tools. Plugins can be written in any language — bash, Node.js, Python, or anything that reads stdin and writes stdout. 证据：`docs-site/docs/plugins/creating.md`\n- **Plugins Overview**（documentation）：Plugins extend SideButton's MCP server with custom tools — without modifying core code. Each plugin is a standalone directory containing a plugin.json manifest and one or more handler scripts in any language. 证据：`docs-site/docs/plugins/overview.md`\n- **Cli**（documentation）：window.location.replace '/knowledge-packs/cli' + window.location.hash 证据：`docs-site/docs/skill-packs/cli.md`\n- **Creating**（documentation）：window.location.replace '/knowledge-packs/creating' + window.location.hash 证据：`docs-site/docs/skill-packs/creating.md`\n- **Overview**（documentation）：window.location.replace '/knowledge-packs/overview' + window.location.hash 证据：`docs-site/docs/skill-packs/overview.md`\n- **Troubleshooting**（documentation）：bash Find what's using the port lsof -i :9876 证据：`docs-site/docs/troubleshooting.md`\n- **DSL Reference**（documentation）：Complete reference for the workflow YAML syntax. 证据：`docs-site/docs/workflows/dsl.md`\n- **Workflow Examples**（documentation）：Copy-paste these examples to get started quickly. 证据：`docs-site/docs/workflows/examples.md`\n- **Workflows Overview**（documentation）：Workflows are the heart of SideButton — reusable automation recipes defined in YAML. 证据：`docs-site/docs/workflows/overview.md`\n- **Step Types**（documentation）：Complete reference for all 45 step types available in SideButton 42 implemented, 3 chat types pending . 证据：`docs-site/docs/workflows/steps.md`\n- **Variables**（documentation）：Variables allow data to flow between workflow steps. Extract values from pages, use them in commands, and pass them between workflows. 证据：`docs-site/docs/workflows/variables.md`\n- **What**（documentation）：Brief description of what this PR does. 证据：`.github/PULL_REQUEST_TEMPLATE.md`\n- **Contributor Covenant Code of Conduct**（documentation）：Contributor Covenant Code of Conduct 证据：`CODE_OF_CONDUCT.md`\n- **Licensing**（documentation）：SideButton uses a mixed licensing model. Most of the codebase is open source under Apache-2.0. Certain components use the Functional Source License FSL-1.1-Apache-2.0 . 证据：`LICENSING.md`\n- **Security Policy**（documentation）：Version Supported --------- ----------- 1.0.x Yes 证据：`SECURITY.md`\n- **Persona**（documentation）：This file describes who you are. SideButton injects it into every LLM call so the AI knows your identity, preferences, and context. Edit this to match your real situation. 证据：`packages/server/defaults/persona.md`\n- **AI Interaction**（documentation）：Working with AI assistants, coding tools, and automated development workflows. 证据：`packages/server/defaults/roles/ai.md`\n- **Code Review**（documentation）：Building and maintaining CI/CD pipelines, infrastructure, and developer tooling. 证据：`packages/server/defaults/roles/devops.md`\n- **Data Handling**（documentation）：Managing invoicing, reconciliation, and financial reporting. 证据：`packages/server/defaults/roles/finance.md`\n- **Communication**（documentation）：Managing onboarding, benefits, compliance, and people operations. 证据：`packages/server/defaults/roles/hr.md`\n- **Content**（documentation）：Creating content, managing brand awareness, and driving organic growth. 证据：`packages/server/defaults/roles/marketing.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs-site/docs/contributing.md`, `AGENTS.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs-site/docs/contributing.md`, `AGENTS.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Introduction to SideButton**：importance `high`\n - source_paths: README.md, LICENSING.md, SECURITY.md\n- **Getting Started**：importance `high`\n - source_paths: package.json, packages/server/README.md, packages/sidebutton/README.md\n- **System Architecture**：importance `high`\n - source_paths: README.md, packages/server/src/server.ts, packages/core/src/executor.ts\n- **Package Overview**：importance `medium`\n - source_paths: packages/core/package.json, packages/server/package.json, packages/dashboard/package.json, packages/sidebutton/package.json, packages/core/src/index.ts\n- **Workflow Engine**：importance `high`\n - source_paths: packages/core/src/parser.ts, packages/core/src/executor.ts, packages/core/src/interpolate.ts, packages/core/src/types.ts\n- **Step Types Reference**：importance `high`\n - source_paths: packages/core/src/steps/browser.ts, packages/core/src/steps/shell.ts, packages/core/src/steps/llm.ts, packages/core/src/steps/control.ts, packages/core/src/steps/data.ts\n- **Workflow Examples**：importance `medium`\n - source_paths: bundles/github/workflows/create_release.yaml, bundles/github/workflows/github_pr_claude_review.yaml, workflows/llm_summarize.yaml, workflows/wikipedia_open.yaml, packages/server/defaults/workflows/llm_summarize.yaml\n- **MCP Server Integration**：importance `high`\n - source_paths: packages/server/src/mcp/handler.ts, packages/server/src/mcp/tools.ts, packages/server/src/mcp/stdio.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `8259d7558b61af849e5da2c71659cc1136064a99`\n- inspected_files: `pnpm-lock.yaml`, `package.json`, `README.md`, `packages/dashboard/vite.config.ts`, `packages/dashboard/svelte.config.js`, `packages/dashboard/package.json`, `packages/dashboard/tsconfig.json`, `packages/server/server.json`, `packages/server/package.json`, `packages/server/tsup.config.ts`, `packages/server/README.md`, `packages/server/tsconfig.json`, `packages/core/package-lock.json`, `packages/core/package.json`, `packages/core/tsup.config.ts`, `packages/core/README.md`, `packages/core/tsconfig.json`, `packages/sidebutton/package.json`, `packages/sidebutton/README.md`, `packages/dashboard/src/main.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：Add control.foreach step type for iterating over lists\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add control.foreach step type for iterating over lists\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_d7567e53b1794e828bb3342cb0699f6f | https://github.com/sidebutton/sidebutton/issues/1 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | No sandbox install has been executed yet; downstream must verify before user use.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：Native elements cannot be programmatically selected via click/type tools\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_a2eadefee45c45b2be1b8501c1a0724f | https://github.com/sidebutton/sidebutton/issues/12 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：v1.1.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_a9cfb55ebc664ee99dcc39773859d715 | https://github.com/sidebutton/sidebutton/releases/tag/v1.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n", "summary": "给宿主 AI 的上下文和工作边界。", "title": "AI Context Pack / 带给我的 AI" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：sidebutton/sidebutton\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Add control.foreach step type for iterating over lists（medium）：可能影响升级、迁移或版本选择。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在安全注意事项（medium）：用户安装前需要知道权限边界和敏感操作。 建议检查：转成明确权限清单和安全审查提示。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n", "summary": "安装、权限、验证和推荐前风险。", "title": "Boundary & Risk Card / 边界与风险卡" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/sidebutton/sidebutton 项目说明书\n\n生成时间：2026-05-16 13:21:37 UTC\n\n## 目录\n\n- [Introduction to SideButton](#introduction)\n- [Getting Started](#getting-started)\n- [System Architecture](#architecture)\n- [Package Overview](#packages-overview)\n- [Workflow Engine](#workflow-engine)\n- [Step Types Reference](#step-types)\n- [Workflow Examples](#workflow-examples)\n- [MCP Server Integration](#mcp-server)\n- [Chrome Extension](#chrome-extension)\n- [Knowledge Packs](#knowledge-packs)\n\n\n\n## Introduction to SideButton\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started), [System Architecture](#architecture), [MCP Server Integration](#mcp-server)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n- [AGENTS.md](https://github.com/sidebutton/sidebutton/blob/main/AGENTS.md)\n- [CONTRIBUTING.md](https://github.com/sidebutton/sidebutton/blob/main/CONTRIBUTING.md)\n- [packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n- [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n
\n\n# Introduction to SideButton\n\nSideButton is an open-source AI agent platform that combines an MCP (Model Context Protocol) server with browser automation tools, a YAML-based workflow engine, and extensible knowledge packs for domain-specific expertise. It enables autonomous AI agents to interact with web applications through standardized browser controls, CLI operations, and pre-built workflow automations.\n\n资料来源：[AGENTS.md]()\n\n## High-Level Architecture\n\nSideButton follows a modular monorepo architecture with four primary packages working together to provide a complete automation platform.\n\n```mermaid\ngraph TB\n subgraph \"Client Layer\"\n EXT[\"Chrome Extension\"]\n CLI[\"CLI Tool\"]\n MCP[\"MCP Clients
(Claude, Cursor)\"]\n end\n \n subgraph \"packages/server\"\n API[\"REST API & Dashboard\"]\n MCP_SRV[\"MCP Endpoint\"]\n WS[\"WebSocket Bridge\"]\n end\n \n subgraph \"packages/core\"\n PARSER[\"Workflow Parser\"]\n EXEC[\"Step Executor\"]\n end\n \n subgraph \"packages/dashboard\"\n UI[\"Svelte Web UI\"]\n end\n \n EXT --> WS\n CLI --> API\n MCP --> MCP_SRV\n API --> EXEC\n MCP_SRV --> EXEC\n WS --> EXEC\n EXEC --> PARSER\n UI --> API\n```\n\n资料来源：[AGENTS.md](), [CONTRIBUTING.md]()\n\n## Package Structure\n\nThe repository is organized as a monorepo using pnpm workspaces. Each package has a focused responsibility.\n\n| Package | Purpose | Location |\n|---------|---------|----------|\n| `packages/core` | Workflow engine — parser, executor, and step implementations | Workflow execution runtime |\n| `packages/server` | HTTP server, MCP endpoint, CLI, and WebSocket bridge | API layer and server runtime |\n| `packages/dashboard` | Svelte web UI served at `localhost:9876` | User interface |\n| `packages/sidebutton` | CLI entry point for `npx sidebutton@latest` | Command-line interface |\n| `extension/` | Chrome extension (Manifest V3) | Browser automation |\n\n资料来源：[AGENTS.md](), [CONTRIBUTING.md]()\n\n## Core Concepts\n\n### Workflows\n\nWorkflows are YAML files that define sequences of steps for automation tasks. They can include browser interactions, shell commands, LLM calls, and control flow logic.\n\n```yaml\nname: example_workflow\nsteps:\n - type: navigate\n url: https://example.com\n \n - type: click\n selector: \"#submit-button\"\n \n - type: extract\n selector: \".result\"\n as: result\n```\n\n资料来源：[packages/core/README.md]()\n\n### Step Types\n\nSideButton provides multiple categories of steps for different automation needs.\n\n| Category | Steps | Purpose |\n|----------|-------|---------|\n| Browser | `navigate`, `click`, `type`, `scroll`, `hover`, `wait`, `extract`, `extractAll`, `exists`, `key` | Web page interaction |\n| Shell | `shell.run`, `terminal.open`, `terminal.run` | Command execution |\n| LLM | `llm.classify`, `llm.generate` | AI-powered operations |\n| Control | `control.if`, `control.retry`, `control.stop`, `workflow.call` | Flow control |\n| Data | `data.first` | Data manipulation |\n\n资料来源：[packages/core/README.md]()\n\n### Knowledge Packs\n\nKnowledge packs (also called skill packs) teach autonomous AI agents how specific web applications work. They bundle markdown files containing selectors, data models, state definitions, and agentic workflows per web app.\n\nKey capabilities of knowledge packs:\n\n- **Selectors**: CSS/XPath selectors for UI elements\n- **Data Models**: Structured data representations\n- **Agentic Workflows**: Pre-defined sequences for common tasks\n- **Role Playbooks**: Instructions for AI agent behavior\n\n资料来源：[packages/sidebutton/README.md](), [AGENTS.md]()\n\n## MCP Integration\n\nSideButton provides MCP (Model Context Protocol) server functionality for integration with AI coding assistants. The MCP tools allow AI agents to control browser automation and execute workflows programmatically.\n\n### Supported Clients\n\n| Client | Transport | Configuration |\n|--------|-----------|---------------|\n| Claude Desktop | stdio | `npx sidebutton --stdio` |\n| Claude Code | SSE | `http://localhost:9876/mcp` |\n| Cursor | HTTP | `http://localhost:9876/mcp` |\n\n资料来源：[packages/server/README.md](), [packages/sidebutton/README.md]()\n\n### MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `run_workflow` | Execute a workflow by ID |\n| `list_workflows` | List available workflows |\n| `get_workflow` | Get workflow YAML definition |\n| `get_run_log` | Get execution log for a run |\n| `list_run_logs` | List recent workflow executions |\n| `get_browser_status` | Check browser extension connection |\n| `capture_page` | Capture selectors from current page |\n| `navigate` | Navigate browser to URL |\n| `snapshot` | Get page accessibility snapshot |\n| `click` | Click an element |\n| `type` | Type text into an element |\n| `scroll` | Scroll the page |\n| `screenshot` | Capture page screenshot |\n| `hover` | Hover over element |\n| `extract` | Extract text from element |\n| `extract_all` | Extract all matching elements |\n\n资料来源：[packages/server/README.md](), [README.md]()\n\n## CLI Commands\n\nThe SideButton CLI provides commands for managing the server, workflows, and knowledge packs.\n\n```bash\nsidebutton # Start server (default port 9876)\nsidebutton --stdio # Start with stdio transport (Claude Desktop)\nsidebutton -p 8080 # Custom port\n\nsidebutton list # List available workflows\nsidebutton run # Run a workflow by ID\nsidebutton status # Check server status\n```\n\n### Knowledge Pack Management\n\n| Command | Description |\n|---------|-------------|\n| `sidebutton registry add ` | Register and install all knowledge packs |\n| `sidebutton registry update [name]` | Update installed packs from registry |\n| `sidebutton registry remove ` | Uninstall packs and remove registry |\n| `sidebutton registry list` | Show registries and pack counts |\n| `sidebutton search [query]` | Search packs across registries |\n| `sidebutton install ` | One-off knowledge pack install |\n| `sidebutton uninstall ` | Remove an installed knowledge pack |\n| `sidebutton init [domain]` | Scaffold a new knowledge pack |\n| `sidebutton validate [path]` | Lint and validate a knowledge pack |\n\n资料来源：[packages/sidebutton/README.md](), [packages/server/README.md]()\n\n## Quick Start\n\n### Published Package (No Clone Required)\n\n```bash\nnpx sidebutton@latest # starts server + dashboard on port 9876\n```\n\n资料来源：[AGENTS.md]()\n\n### Local Development Setup\n\n```bash\n# Clone the repo\ngit clone https://github.com/sidebutton/sidebutton.git\ncd sidebutton\n\n# Install dependencies\npnpm install\n\n# Build all packages\npnpm build\n\n# Start the server\npnpm start\n# Open http://localhost:9876\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n### Development Prerequisites\n\n| Requirement | Version |\n|-------------|---------|\n| Node.js | 20+ |\n| pnpm | 9.15+ |\n| Chrome | Latest (for browser automation) |\n\n资料来源：[CONTRIBUTING.md]()\n\n## Development Workflow\n\n### Running Components\n\nStart everything in watch mode with hot reload:\n\n```bash\npnpm dev\n```\n\nRun components individually:\n\n| Command | Description |\n|---------|-------------|\n| `pnpm dev:server` | Server with auto-restart on :9876 |\n| `pnpm dev:dashboard` | Dashboard with HMR on :5173 |\n| `pnpm build` | Build all packages |\n| `pnpm test` | Run all tests |\n\n资料来源：[CONTRIBUTING.md]()\n\n## Provider Preference\n\nWhen multiple integration methods exist, SideButton follows this preference order:\n\n```mermaid\ngraph LR\n A[\"API Provider\"] --> B[\"CLI Tool\"] --> C[\"Browser Automation\"]\n style A fill:#90EE90\n style B fill:#FFD700\n style C fill:#FFA07A\n```\n\n- **API** is fastest and most reliable\n- **CLI** provides programmatic access\n- **Browser automation** is the universal fallback\n\n资料来源：[packages/server/defaults/roles/software-engineer.md]()\n\n## Data Directories\n\n| Directory | What it is |\n|-----------|------------|\n| `packages/core/` | Workflow engine — parser, executor, step implementations |\n| `packages/server/` | HTTP server, MCP endpoint, CLI, WebSocket bridge |\n| `packages/dashboard/` | Svelte web UI served at localhost:9876 |\n| `extension/` | Chrome extension for browser automation |\n| `workflows/` | Public workflow library (YAML files) |\n| `actions/` | User-created workflows (gitignored) |\n\n资料来源：[CONTRIBUTING.md]()\n\n## Related Packages\n\n| Package | NPM Link |\n|---------|----------|\n| `@sidebutton/core` | [npmjs.com](https://www.npmjs.com/package/@sidebutton/core) |\n| `@sidebutton/server` | [npmjs.com](https://www.npmjs.com/package/@sidebutton/server) |\n\n资料来源：[packages/core/README.md](), [packages/server/README.md]()\n\n## External Resources\n\n| Resource | URL |\n|----------|-----|\n| Documentation | [docs.sidebutton.com](https://docs.sidebutton.com) |\n| GitHub Repository | [github.com/sidebutton/sidebutton](https://github.com/sidebutton/sidebutton) |\n| Website | [sidebutton.com](https://sidebutton.com) |\n| Knowledge Packs | [sidebutton.com/skills](https://sidebutton.com/skills) |\n\n## License\n\nSideButton is licensed under **Apache-2.0**.\n\n资料来源：[CONTRIBUTING.md](), [packages/core/README.md](), [packages/server/README.md]()\n\n---\n\n\n\n## Getting Started\n\n### 相关页面\n\n相关主题：[Introduction to SideButton](#introduction)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/sidebutton/sidebutton/blob/main/package.json)\n- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n- [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n- [packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n
\n\n# Getting Started\n\nSideButton is a Model Context Protocol (MCP) server that provides browser automation, workflow execution, and knowledge pack management capabilities. It enables AI assistants like Claude Desktop and Cursor to interact with web browsers, execute predefined workflows, and leverage domain-specific knowledge packs.\n\n## Prerequisites\n\nBefore installing SideButton, ensure your environment meets the following requirements:\n\n| Requirement | Version/Details |\n|-------------|-----------------|\n| Node.js | v18 or higher |\n| Package Manager | pnpm (recommended) or npm |\n| Browser | Chrome/Chromium (for browser automation features) |\n| OS | macOS, Windows, Linux |\n\n资料来源：[README.md:1-50](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n## Installation\n\n### Package Manager Installation\n\nInstall the SideButton CLI globally using your preferred package manager:\n\n```bash\n# Using npm\nnpm install -g sidebutton\n\n# Using pnpm\npnpm add -g sidebutton\n\n# Using yarn\nyarn global add sidebutton\n```\n\nVerify the installation:\n\n```bash\nsidebutton --version\n```\n\n### Development Setup (From Source)\n\nFor contributing or running the latest development version:\n\n```bash\n# Clone the repository\ngit clone https://github.com/sidebutton/sidebutton.git\ncd sidebutton\n\n# Install dependencies\npnpm install\n\n# Build all packages\npnpm build\n\n# Run CLI directly\npnpm cli --version\n```\n\n资料来源：[CONTRIBUTING.md:1-20](https://github.com/sidebutton/sidebutton/blob/main/CONTRIBUTING.md)\n\n## Quick Start\n\n### Starting the Server\n\nThe default command starts the SideButton server on port 9876:\n\n```bash\nsidebutton\n```\n\nTo use a custom port:\n\n```bash\nsidebutton -p 8080\n```\n\nThe server provides:\n- REST API endpoint\n- MCP (Model Context Protocol) endpoint\n- WebSocket connection for browser extension\n- Dashboard UI at `http://localhost:9876`\n\n资料来源：[packages/sidebutton/README.md:1-30](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n\n### Architecture Overview\n\n```mermaid\ngraph TD\n A[Claude Desktop / Cursor] -->|MCP Protocol| B[SideButton Server]\n A -->|stdio| B\n B -->|REST API| C[Dashboard UI]\n B -->|WebSocket| D[Chrome Extension]\n B -->|Execute| E[Workflow Engine]\n E -->|Browser Actions| F[Chrome Browser]\n E -->|CLI Tools| G[Shell/CLI]\n E -->|LLM Calls| H[OpenAI/Anthropic/Ollama]\n```\n\n## MCP Integration\n\nSideButton can be integrated with various AI coding assistants through the MCP protocol.\n\n### Claude Desktop\n\nAdd SideButton to your Claude Desktop configuration file at `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"sidebutton\": {\n \"command\": \"npx\",\n \"args\": [\"sidebutton\", \"--stdio\"]\n }\n }\n}\n```\n\nAfter adding the configuration, restart Claude Desktop to load the new MCP server.\n\n资料来源：[README.md:50-70](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n### Cursor\n\nAdd SideButton to your Cursor MCP configuration file at `~/.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"sidebutton\": {\n \"url\": \"http://localhost:9876/mcp\"\n }\n }\n}\n```\n\nEnsure the SideButton server is running before using Cursor with this configuration.\n\n资料来源：[packages/server/README.md:20-35](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n\n### Available MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `run_workflow` | Execute a workflow by ID |\n| `list_workflows` | List all available workflows |\n| `get_workflow` | Get workflow YAML definition |\n| `get_run_log` | Get execution log for a run |\n| `list_run_logs` | List recent workflow executions |\n| `get_browser_status` | Check browser extension connection |\n| `capture_page` | Capture selectors from current page |\n| `navigate` | Navigate browser to URL |\n| `snapshot` | Get page accessibility snapshot |\n| `click` | Click an element |\n| `type` | Type text into an element |\n| `scroll` | Scroll the page |\n| `screenshot` | Capture page screenshot |\n| `hover` | Hover over element |\n| `extract` | Extract text from element |\n| `extract_all` | Extract all matching elements |\n\n资料来源：[packages/server/README.md:40-60](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n\n## CLI Commands\n\n### Basic Commands\n\n```bash\n# Start the server (default port 9876)\nsidebutton\n\n# Start with stdio transport for Claude Desktop\nsidebutton --stdio\n\n# Start on custom port\nsidebutton -p 8080\n\n# List available workflows\nsidebutton list\n\n# Run a specific workflow\nsidebutton run \n\n# Check server status\nsidebutton status\n```\n\n### Knowledge Packs Management\n\n```bash\n# Add a registry\nsidebutton registry add \n\n# Update installed packs\nsidebutton registry update [name]\n\n# Remove a registry\nsidebutton registry remove \n\n# List all registries\nsidebutton registry list\n\n# Search packs across registries\nsidebutton search [query]\n\n# Install a knowledge pack\nsidebutton install \n\n# Uninstall a knowledge pack\nsidebutton uninstall \n```\n\n### Knowledge Pack Development\n\n```bash\n# Scaffold a new knowledge pack\nsidebutton init [domain]\n\n# Validate a knowledge pack\nsidebutton validate [path]\n\n# Publish to registry\nsidebutton publish\n```\n\n资料来源：[packages/sidebutton/README.md:60-100](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n\n## Dashboard\n\nThe SideButton dashboard provides a web-based UI for managing workflows and viewing execution history.\n\nAccess the dashboard at: `http://localhost:9876`\n\n### Dashboard Features\n\n- View and manage shortcuts\n- Browse available workflows\n- View execution logs\n- Add workflows to dashboard\n- Monitor browser extension status\n\n## Chrome Extension\n\nInstall the SideButton Chrome extension from the [Chrome Web Store](https://chromewebstore.google.com/detail/sidebutton/odaefhmdmgijnhdbkfagnlnmobphgkij).\n\n### Extension Features\n\n- 40+ browser commands for navigation, clicking, typing, extraction\n- Real DOM access via CSS selectors\n- Recording mode to capture manual actions as workflows\n- Embed action buttons into web pages\n- WebSocket connection for stable reconnection\n\n资料来源：[README.md:80-100](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n## Workflow Execution\n\n### Running a Workflow via CLI\n\n```bash\n# List all available workflows\nsidebutton list\n\n# Execute a workflow by ID\nsidebutton run \n\n# With parameters\nsidebutton run --param value\n```\n\n### Running a Workflow via MCP\n\nWhen connected to an MCP client like Claude Desktop:\n\n```\n# Use the run_workflow tool\nrun_workflow({ id: \"workflow-id\", params: { key: \"value\" } })\n```\n\n### Workflow Step Types\n\n| Category | Steps |\n|----------|-------|\n| Browser | `navigate`, `click`, `type`, `scroll`, `hover`, `wait`, `extract`, `extractAll`, `exists`, `key` |\n| Shell | `shell.run`, `terminal.open`, `terminal.run` |\n| LLM | `llm.classify`, `llm.generate` |\n| Control | `control.if`, `control.retry`, `control.stop`, `workflow.call` |\n| Data | `data.first` |\n\n资料来源：[packages/core/README.md:20-40](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n\n## Next Steps\n\n- Explore [Workflow Configuration](workflows.md) for creating custom automations\n- Set up [Knowledge Packs](knowledge-packs.md) for domain-specific capabilities\n- Configure [Provider Integrations](providers.md) for GitHub, Jira, and other tools\n- Review [Testing Guide](testing.md) for quality assurance workflows\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Package Overview](#packages-overview), [MCP Server Integration](#mcp-server), [Workflow Engine](#workflow-engine)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n- [packages/server/src/server.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/server.ts)\n- [packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n- [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n- [packages/server/src/mcp/handler.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/handler.ts)\n- [packages/server/src/cli.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)\n
\n\n# System Architecture\n\n## Overview\n\nSideButton is a browser automation and workflow orchestration platform that enables AI agents (such as Claude Desktop, Cursor) to interact with web applications through a unified MCP (Model Context Protocol) interface. The system combines browser automation, CLI tools, LLM capabilities, and external integrations into a coherent workflow execution engine.\n\nThe architecture follows a modular monorepo design with four primary packages:\n\n| Package | Purpose |\n|---------|---------|\n| `packages/sidebutton` | CLI entry point and CLI transport for MCP |\n| `packages/server` | Fastify-based MCP server with REST API and dashboard |\n| `packages/core` | Workflow definition parsing and execution engine |\n| `packages/dashboard` | React-based web UI for workflow management |\n\n资料来源：[README.md:1-50]()\n\n---\n\n## High-Level Architecture\n\n```mermaid\ngraph TB\n subgraph \"Client Layer\"\n CLI[\"CLI Client
sidebutton\"]\n BrowserExt[\"Chrome Extension\"]\n AI[\"AI Agents
(Claude, Cursor)\"]\n end\n\n subgraph \"Transport Layer\"\n Stdio[\"stdio\"]\n SSE[\"Server-Sent Events\"]\n WebSocket[\"WebSocket\"]\n HTTP[\"HTTP/REST\"]\n end\n\n subgraph \"Server Package\"\n MCP[\"MCP Handler
handler.ts\"]\n API[\"REST API
server.ts\"]\n Dashboard[\"Dashboard
React App\"]\n end\n\n subgraph \"Core Package\"\n Executor[\"Workflow Executor
executor.ts\"]\n Workflow[\"Workflow Parser\"]\n Steps[\"Step Handlers\"]\n end\n\n subgraph \"Providers\"\n GitHub[\"GitHub Provider\"]\n Browser[\"Browser Provider\"]\n LLM[\"LLM Provider\"]\n Shell[\"Shell Provider\"]\n end\n\n CLI --> Stdio\n BrowserExt --> WebSocket\n AI --> SSE\n AI --> HTTP\n\n Stdio --> MCP\n SSE --> MCP\n WebSocket --> MCP\n HTTP --> API\n\n MCP --> Executor\n API --> Executor\n\n Executor --> Workflow\n Workflow --> Steps\n\n Steps --> GitHub\n Steps --> Browser\n Steps --> LLM\n Steps --> Shell\n```\n\n资料来源：[packages/server/src/mcp/handler.ts:1-50]()\n\n---\n\n## Package Structure\n\n### CLI Package (`packages/sidebutton`)\n\nThe CLI package serves as the primary entry point for users and as an MCP transport adapter.\n\n**Key responsibilities:**\n\n- Parse CLI arguments and commands\n- Initialize and start the MCP server\n- Provide `stdio` transport for AI agent integration\n- Manage local configuration and authentication\n\n**Transport modes:**\n\n| Mode | Command | Use Case |\n|------|---------|----------|\n| HTTP Server | `sidebutton` | Dashboard + API access |\n| stdio | `sidebutton --stdio` | Claude Desktop integration |\n| Custom Port | `sidebutton -p 8080` | Development/custom deployments |\n\n资料来源：[packages/sidebutton/README.md:1-30]()\n\n### Server Package (`packages/server`)\n\nThe server package implements the MCP protocol and exposes REST APIs for workflow management.\n\n```mermaid\ngraph LR\n subgraph \"Server Components\"\n Fastify[\"Fastify Server\"]\n MCPHandler[\"MCP Handler\"]\n WorkflowManager[\"Workflow Manager\"]\n RunLogManager[\"Run Log Manager\"]\n end\n\n Fastify --> MCPHandler\n Fastify --> RESTAPI[\"REST API\"]\n MCPHandler --> WorkflowManager\n RESTAPI --> WorkflowManager\n WorkflowManager --> RunLogManager\n```\n\n**Core server configuration:**\n\n```typescript\ninterface ServerConfig {\n port: number; // Default: 9876\n actionsDir: string; // User-defined workflows\n workflowsDir: string; // Bundled workflows\n templatesDir: string; // Importable templates\n runLogsDir: string; // Execution logs\n}\n```\n\n资料来源：[packages/server/src/server.ts:1-50]()\n\n**REST API Endpoints:**\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/workflows` | GET | List all workflows |\n| `/api/workflows/:id` | GET | Get workflow definition |\n| `/api/workflows/:id/run` | POST | Execute a workflow |\n| `/api/templates` | GET | List available templates |\n| `/api/templates/:id/import` | POST | Import template to actions |\n| `/api/runs` | GET | List run logs |\n| `/api/runs/:id` | GET/DELETE | Get or delete run log |\n\n资料来源：[packages/server/src/server.ts:100-200]()\n\n### Core Package (`packages/core`)\n\nThe core package contains the workflow execution engine that parses YAML definitions and executes steps sequentially.\n\n**Workflow execution flow:**\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Executor\n participant StepHandler\n participant Provider\n\n Client->>Executor: executeWorkflow(workflow, context)\n Executor->>Executor: Parse YAML definition\n Loop For each step\n Executor->>StepHandler: Execute step\n StepHandler->>Provider: Provider action\n Provider-->>StepHandler: Result\n StepHandler-->>Executor: Step result\n End\n Executor-->>Client: Final result\n```\n\n资料来源：[packages/core/README.md:1-30]()\n\n**Step Types:**\n\n| Category | Steps | Description |\n|----------|-------|-------------|\n| Browser | `navigate`, `click`, `type`, `scroll`, `hover`, `wait`, `extract`, `extractAll`, `exists`, `key` | DOM interaction via Chrome extension |\n| Shell | `shell.run`, `terminal.open`, `terminal.run` | Execute CLI commands |\n| LLM | `llm.classify`, `llm.generate`, `llm.decide` | AI-driven operations |\n| Control | `control.if`, `control.retry`, `control.stop`, `workflow.call` | Flow control |\n| Data | `data.first`, `data.get`, `variable.set` | Data manipulation |\n\n资料来源：[packages/core/README.md:30-60]()\n\n### Dashboard Package (`packages/dashboard`)\n\nThe dashboard is a React/Vite application served by the Fastify server.\n\n**Structure:**\n\n```\npackages/dashboard/\n├── index.html # Entry HTML\n└── src/\n └── main.ts # React mount point\n```\n\nThe dashboard provides:\n\n- Workflow listing and management UI\n- Run log viewer\n- Settings configuration\n- Knowledge pack management\n\n资料来源：[packages/dashboard/index.html:1-20]()\n\n---\n\n## MCP Protocol Integration\n\n### MCP Tools\n\nThe MCP handler exposes tools for AI agent interaction:\n\n| Tool | Parameters | Description |\n|------|------------|-------------|\n| `run_workflow` | `id`, `params?` | Execute a workflow by ID |\n| `list_workflows` | `source?` | List workflows (actions/workflows/all) |\n| `get_workflow` | `id` | Get workflow YAML definition |\n| `get_run_log` | `id` | Get execution log for a run |\n| `list_run_logs` | `limit?` | List recent workflow executions |\n| `get_browser_status` | - | Check Chrome extension connection |\n| `capture_page` | `selectors?` | Capture CSS selectors from current page |\n| `navigate` | `url` | Navigate browser to URL |\n| `snapshot` | - | Get page accessibility snapshot |\n| `click` | `selector` | Click an element |\n| `type` | `selector`, `text` | Type text into an element |\n| `scroll` | `selector?`, `direction?` | Scroll the page |\n\n资料来源：[packages/server/README.md:40-60]()\n\n### MCP Handler Architecture\n\n```mermaid\ngraph TD\n MCP[\"MCP Handler\"]\n Tools[\"Tool Registry\"]\n Actions[\"Actions Loader\"]\n Workflows[\"Workflows Loader\"]\n Templates[\"Templates Loader\"]\n\n MCP --> Tools\n Tools --> Actions\n Tools --> Workflows\n Tools --> Templates\n\n Actions --> YAML[\"YAML Files
(~/.sidebutton/actions/)\"]\n Workflows --> Bundles[\"Bundled Workflows
(bundles/)\"]\n Templates --> Defaults[\"Default Templates
(defaults/templates/)\"]\n```\n\n资料来源：[packages/server/src/mcp/handler.ts:50-100]()\n\n---\n\n## Data Flow\n\n### Workflow Execution Pipeline\n\n```mermaid\ngraph LR\n A[Workflow YAML] --> B[Parse Steps]\n B --> C[Initialize Context]\n C --> D{For Each Step}\n D -->|Browser Step| E[Browser Provider]\n D -->|Shell Step| F[Shell Provider]\n D -->|LLM Step| G[LLM Provider]\n D -->|Control Step| H[Control Handler]\n E --> I[Record Result]\n F --> I\n G --> I\n H --> I\n I -->|More Steps| D\n I -->|Complete| J[Save Run Log]\n J --> K[Return Result]\n```\n\n### Variable Interpolation\n\nWorkflows support variable interpolation using `{{variable}}` syntax:\n\n```yaml\nsteps:\n - type: browser.extract\n selector: \".username\"\n as: user\n - type: shell.run\n cmd: \"echo 'Hello, {{user}}!'\"\n```\n\nVariables are stored in the execution context and can be:\n\n- Extracted from previous steps using `as` attribute\n- Passed as workflow parameters\n- Set explicitly via `variable.set` step\n\n资料来源：[README.md:150-180]()\n\n---\n\n## Provider System\n\nProviders are integration modules that execute specific step types.\n\n### GitHub Provider\n\nLocated at `packages/core/src/providers/github.ts`, the GitHub provider supports:\n\n| Operation | Methods |\n|-----------|---------|\n| Pull Requests | `listPRs`, `getPR`, `createPR` |\n| Issues | `listIssues`, `getIssue`, `createIssue`, `comment`, `transition` |\n| Repository | `getRepoInfo` |\n\n**Configuration:**\n\n```yaml\nproviders:\n github:\n type: github\n # Uses GitHub CLI (gh) for operations\n```\n\n资料来源：[packages/core/src/providers/github.ts:1-50]()\n\n### Browser Provider\n\nBrowser automation is handled via the Chrome extension:\n\n- **Protocol:** WebSocket (stable reconnection)\n- **Access:** Real DOM via CSS selectors (not pixel coordinates)\n- **Features:** Recording mode, embed buttons, page snapshots\n\n**Connection flow:**\n\n```mermaid\nsequenceDiagram\n participant Extension\n participant Server\n participant Browser\n\n Extension->>Server: Connect WebSocket\n Server->>Extension: Connection confirmed\n Extension->>Server: Send browser commands\n Server->>Browser: Execute via CDP\n Browser-->>Server: Result\n Server-->>Extension: Response\n```\n\n资料来源：[README.md:60-90]()\n\n---\n\n## Configuration System\n\n### Server Configuration\n\n```typescript\ninterface Config {\n port: number; // Default: 9876\n host: string; // Default: 'localhost'\n dataDir: string; // ~/.sidebutton\n actionsDir: string; // {dataDir}/actions\n workflowsDir: string; // {dataDir}/workflows\n templatesDir: string; // {dataDir}/templates\n runLogsDir: string; // {dataDir}/run-logs\n mcpPort: number; // Default: 9877\n}\n```\n\n### Environment Variables\n\nThe server supports environment variables for provider configuration:\n\n| Variable | Description |\n|----------|-------------|\n| `GITHUB_TOKEN` | GitHub authentication token |\n| `OPENAI_API_KEY` | OpenAI API key for LLM steps |\n| `ANTHROPIC_API_KEY` | Anthropic API key |\n| `SIDEBUTTON_API_BASE` | API base URL for browser extension |\n\n资料来源：[packages/server/src/server.ts:50-100]()\n\n---\n\n## Knowledge Packs System\n\nKnowledge packs (also called \"skill packs\") are installable domain-specific modules.\n\n### Structure\n\n```\n{domain}/\n├── manifest.yaml # Pack metadata\n├── selectors/ # CSS selectors for UI elements\n├── models/ # Data models and entity types\n├── states/ # State machine definitions\n├── roles/ # Role-specific playbooks\n└── tasks/ # Common task procedures\n```\n\n### Registry Commands\n\n| Command | Description |\n|---------|-------------|\n| `sidebutton registry add ` | Add a registry |\n| `sidebutton registry list` | List installed registries |\n| `sidebutton install ` | Install a knowledge pack |\n| `sidebutton uninstall ` | Remove a knowledge pack |\n| `sidebutton search [query]` | Search packs across registries |\n\n资料来源：[packages/sidebutton/README.md:30-50]()\n\n### Publishing Knowledge Packs\n\n```bash\n# Initialize a new pack\nsidebutton init github.com\n\n# Validate\nsidebutton validate ./github.com\n\n# Publish to registry\nsidebutton publish\n```\n\n资料来源：[packages/server/src/cli.ts:100-150]()\n\n---\n\n## Deployment Modes\n\n### Local Development\n\n```bash\n# Start with dashboard and API\nsidebutton\n\n# Start with stdio for AI agent\nsidebutton --stdio\n```\n\n### AI Agent Integration\n\n**Claude Desktop:**\n\n```json\n{\n \"mcpServers\": {\n \"sidebutton\": {\n \"command\": \"npx\",\n \"args\": [\"sidebutton\", \"--stdio\"]\n }\n }\n}\n```\n\n**Cursor:**\n\n```json\n{\n \"mcpServers\": {\n \"sidebutton\": {\n \"url\": \"http://localhost:9876/mcp\"\n }\n }\n}\n```\n\n资料来源：[packages/sidebutton/README.md:60-90]()\n\n---\n\n## Security Considerations\n\n### Authentication Flow\n\n```mermaid\ngraph TD\n A[Login Command] --> B[Credentials Input]\n B --> C[Validate Credentials]\n C -->|Valid| D[Store Token]\n C -->|Invalid| E[Error]\n D --> F[Attach to Requests]\n\n F --> G[/api/* Requests]\n G --> H{Auth Required?}\n H -->|Yes| I[Verify Token]\n H -->|No| J[Allow]\n I -->|Valid| J\n I -->|Invalid| K[401 Unauthorized]\n```\n\n### Token Storage\n\n- Tokens are stored in `~/.sidebutton/config.json`\n- Not committed to version control\n- Protected by file system permissions\n\n资料来源：[packages/server/src/cli.ts:1-50]()\n\n---\n\n## Summary\n\nThe SideButton system architecture consists of:\n\n1. **CLI Layer** - Entry point for users and AI agents\n2. **Transport Layer** - stdio, SSE, HTTP, WebSocket support\n3. **Server Layer** - Fastify MCP server with REST API\n4. **Execution Layer** - Workflow parsing and step execution\n5. **Provider Layer** - GitHub, Browser, Shell, LLM integrations\n6. **UI Layer** - React dashboard for workflow management\n\nThe modular design allows:\n- AI agents to execute complex browser automation workflows\n- Users to create custom workflows via YAML\n- Extensible provider system for new integrations\n- Installable knowledge packs for domain-specific automation\n\n---\n\n\n\n## Package Overview\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture), [Workflow Engine](#workflow-engine), [Chrome Extension](#chrome-extension)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/package.json](https://github.com/sidebutton/sidebutton/blob/main/packages/core/package.json)\n- [packages/server/package.json](https://github.com/sidebutton/sidebutton/blob/main/packages/server/package.json)\n- [packages/dashboard/package.json](https://github.com/sidebutton/sidebutton/blob/main/packages/dashboard/package.json)\n- [packages/sidebutton/package.json](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/package.json)\n- [packages/core/src/index.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/index.ts)\n- [packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n- [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n
\n\n# Package Overview\n\nSideButton is a browser automation platform organized as a monorepo with four primary packages. The system enables workflow-driven automation through YAML definitions, MCP (Model Context Protocol) integration, a REST API, and a Chrome extension. This document provides a comprehensive overview of each package's architecture, responsibilities, and interdependencies.\n\n## Architecture Overview\n\nSideButton follows a layered architecture pattern with clear separation of concerns across packages. The core workflow engine handles execution logic, the server package provides API endpoints and MCP connectivity, the CLI package offers command-line interaction, and the dashboard provides a web-based user interface.\n\n```mermaid\ngraph TD\n User[User] --> CLI[CLI Package]\n User --> Dashboard[Dashboard Package]\n User --> MCP[MCP Client]\n User --> REST[REST API Client]\n \n CLI --> Server[Server Package]\n Dashboard --> Server\n MCP --> Server\n REST --> Server\n \n Server --> Core[Core Package]\n Server --> BrowserExtension[Chrome Extension]\n \n Core --> WorkflowEngine[Workflow Engine]\n Core --> Providers[Provider Integrations]\n```\n\n## Package Structure\n\nThe repository contains four main packages under the `packages/` directory:\n\n| Package | Description |\n|---------|-------------|\n| `@sidebutton/core` | Core workflow engine and execution runtime |\n| `@sidebutton/server` | MCP server, REST API, and embedded dashboard |\n| `@sidebutton/sidebutton` | Command-line interface |\n| `dashboard` | Frontend React application for the web UI |\n\n## Core Package (`@sidebutton/core`)\n\nThe core package contains the fundamental workflow orchestration engine. It handles parsing, validation, and execution of YAML-based workflow definitions.\n\n### Purpose and Scope\n\nThe core package is responsible for the runtime execution of automations. It provides the foundational primitives that the server package wraps with API endpoints. Workflows are defined in YAML and executed through a step-by-step interpreter that supports multiple action types.\n\n### Core Exports\n\nThe package exposes three primary functions for workflow management:\n\n```typescript\n// packages/core/src/index.ts\nexport { parseWorkflow, validateWorkflow, executeWorkflow }\n```\n\n| Function | Purpose |\n|----------|---------|\n| `parseWorkflow` | Parse YAML workflow definition into internal representation |\n| `validateWorkflow` | Validate workflow structure and step types |\n| `executeWorkflow` | Execute a workflow with provided context and parameters |\n\n### Step Types\n\nThe core package supports multiple categories of step types for workflow construction:\n\n| Category | Steps |\n|----------|-------|\n| **Browser** | `navigate`, `click`, `type`, `scroll`, `hover`, `wait`, `extract`, `extractAll`, `exists`, `key` |\n| **Shell** | `shell.run`, `terminal.open`, `terminal.run` |\n| **LLM** | `llm.classify`, `llm.generate` |\n| **Control** | `control.if`, `control.retry`, `control.stop`, `workflow.call` |\n| **Data** | `data.first` |\n\n### Provider Integrations\n\nThe core package includes provider implementations for external service integration. GitHub integration is implemented in `packages/core/src/providers/github.ts` and provides the following capabilities:\n\n- `listPRs` - List pull requests\n- `getPR` - Get pull request details\n- `createPR` - Create a pull request\n- `listIssues` - List repository issues\n- `getIssue` - Get issue details\n\n资料来源：[packages/core/src/providers/github.ts](packages/core/src/providers/github.ts)\n\n## Server Package (`@sidebutton/server`)\n\nThe server package serves as the central hub for all external interactions with the workflow engine. It wraps the core package with MCP protocol support, REST API endpoints, and embeds the dashboard application.\n\n### MCP Server\n\nThe MCP server implementation exposes workflow execution capabilities to MCP-compatible clients including Claude Desktop and Cursor. The server runs on port 9876 by default and provides the following tools:\n\n| MCP Tool | Description |\n|---------|-------------|\n| `run_workflow` | Execute a workflow by ID |\n| `list_workflows` | List available workflows |\n| `get_workflow` | Get workflow YAML definition |\n| `get_run_log` | Get execution log |\n| `list_run_logs` | List recent executions |\n| `get_browser_status` | Check extension connection |\n| `capture_page` | Capture page selectors |\n| `navigate` | Navigate browser to URL |\n| `snapshot` | Get accessibility tree |\n| `click` | Click element |\n| `type` | Type text |\n| `scroll` | Scroll page |\n| `extract` | Extract text |\n| `screenshot` | Capture screenshot |\n| `hover` | Hover over element |\n\n资料来源：[packages/server/README.md](packages/server/README.md)\n\n### REST API\n\nThe server exposes 60+ JSON endpoints for external integrations. The API supports the same workflow operations available through MCP, enabling programmatic access from any HTTP client.\n\n```bash\n# Run a workflow\ncurl -X POST http://localhost:9876/api/workflows/check_ticket/run \\\n -H \"Content-Type: application/json\" \\\n -d '{\"params\": {\"ticket_id\": \"PROJ-123\"}}'\n\n# List workflows\ncurl http://localhost:9876/api/workflows\n\n# Get run log\ncurl http://localhost:9876/api/runs/latest\n```\n\n资料来源：[README.md](README.md)\n\n### Embedded Dashboard\n\nThe server embeds a React-based dashboard application served from `packages/dashboard/`. The dashboard provides:\n\n- Workflow browsing and execution\n- Run log viewing\n- Shortcut management\n- Action library\n- Workflow recording\n\n### Workflow Engine Extensions\n\nThe server extends the core workflow engine with 34+ step types, providing additional capabilities beyond the core package:\n\n| Extended Category | Additional Steps |\n|-------------------|------------------|\n| **Browser** | `fill`, `press_key`, `scroll_into_view`, `evaluate`, `select_option` |\n| **Extended** | `check_writing_quality`, `capture_page` |\n\n### Knowledge Packs\n\nThe server supports knowledge packs (also called skill packs) that provide domain-specific knowledge for AI-driven tasks. Knowledge packs include:\n\n- **Selectors** — CSS selectors for UI elements\n- **Data models** — entity types, fields, relationships, valid states\n- **State machines** — valid transitions per state\n- **Role playbooks** — role-specific procedures (QA, SE, PM, SD)\n- **Common tasks** — step-by-step procedures, gotchas, edge cases\n\n资料来源：[README.md](README.md)\n\n## CLI Package (`@sidebutton/sidebutton`)\n\nThe CLI package provides command-line interaction with the SideButton platform. It serves as the primary interface for local development and scripting workflows.\n\n### Installation\n\n```bash\nnpm install -g sidebutton\n```\n\n### Core Commands\n\n| Command | Description |\n|---------|-------------|\n| `sidebutton` | Start server (default port 9876) |\n| `sidebutton --stdio` | Start with stdio transport (Claude Desktop) |\n| `sidebutton -p 8080` | Start on custom port |\n\n### Workflow Management\n\n| Command | Description |\n|---------|-------------|\n| `sidebutton list` | List available workflows |\n| `sidebutton run ` | Run a workflow |\n| `sidebutton status` | Check server status |\n\n### Knowledge Pack Commands\n\n```bash\n# Registry management\nsidebutton registry add # Install from registry\nsidebutton registry update [name] # Update installed packs\nsidebutton registry remove # Remove registry and packs\nsidebutton registry list # Show registries\n\n# Search and install\nsidebutton search [query] # Search packs across registries\nsidebutton install # Install a single knowledge pack\nsidebutton uninstall # Remove a knowledge pack\n\n# Development\nsidebutton init [domain] # Scaffold a new knowledge pack\nsidebutton validate [path] # Lint and validate a knowledge pack\nsidebutton publish # Publish to registry\n```\n\n资料来源：[packages/sidebutton/README.md](packages/sidebutton/README.md)\n\n### Publishing Workflows\n\nThe CLI supports publishing skill packs to remote registries via the publish command:\n\n```bash\nsidebutton publish\n```\n\nThis command sends the manifest and all associated files to the configured remote registry at `${REMOTE_BASE_URL}/api/skill-packs/publish`. Authentication is required via bearer token.\n\n## Dashboard Package\n\nThe dashboard is a React-based frontend application that provides the visual interface for managing workflows and viewing execution logs.\n\n### Entry Point\n\nThe dashboard application is mounted in `packages/dashboard/index.html`:\n\n```html\n
\n\n```\n\n### Key Pages\n\n| Page | Route | Purpose |\n|------|-------|---------|\n| Dashboard Home | `/` | Display workflow shortcuts |\n| Actions | `/actions` | Browse and search available workflows |\n| Action Detail | `/actions/:id` | View workflow details and run |\n| Workflows | `/workflows` | Library of workflows |\n| Workflow Detail | `/workflows/:id` | Read-only workflow view |\n| Recordings | `/recordings` | View recorded automations |\n| Run Logs | `/run-logs` | View execution history |\n\n## Chrome Extension\n\nWhile not a separate npm package, the Chrome extension is an integral part of the SideButton ecosystem. It provides browser automation capabilities with:\n\n- 40+ browser commands (navigate, click, type, extract, scroll, wait, snapshot)\n- Real DOM access via CSS selectors\n- Recording mode for capturing manual actions as workflows\n- Embed buttons for injecting action buttons into web pages\n- WebSocket connection with stable reconnection\n\n资料来源：[README.md](README.md)\n\n## Dependency Graph\n\nThe packages have the following dependency relationships:\n\n```mermaid\ngraph LR\n CLI[\"@sidebutton/sidebutton\"] --> Server[\"@sidebutton/server\"]\n Dashboard[\"dashboard\"] --> Server\n Server --> Core[\"@sidebutton/core\"]\n Server --> BrowserExt[\"Chrome Extension\"]\n \n style Core fill:#e1f5fe\n style Server fill:#fff3e0\n style CLI fill:#e8f5e9\n style Dashboard fill:#f3e5f5\n```\n\n| Consumer | Dependency | Relationship |\n|----------|------------|---------------|\n| `@sidebutton/sidebutton` | `@sidebutton/server` | CLI wraps server functionality |\n| `dashboard` | `@sidebutton/server` | Dashboard embeds in server |\n| `@sidebutton/server` | `@sidebutton/core` | Server uses core for workflow execution |\n\n## Technology Stack\n\n| Layer | Technology |\n|-------|------------|\n| Runtime | Node.js |\n| Core Engine | TypeScript |\n| Server | Fastify |\n| API Protocol | MCP (Model Context Protocol) |\n| Dashboard | React, Vite |\n| Browser Automation | Chrome Extension (Manifest V3) |\n| Package Manager | pnpm (monorepo) |\n\n## Quick Start\n\n### Running the Server\n\n```bash\n# Start the server\nsidebutton\n\n# Or with custom port\nsidebutton -p 8080\n```\n\n### Running a Workflow\n\n```bash\n# List available workflows\nsidebutton list\n\n# Run a specific workflow\nsidebutton run \n```\n\n### Integrating with Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"sidebutton\": {\n \"command\": \"npx\",\n \"args\": [\"sidebutton\", \"--stdio\"]\n }\n }\n}\n```\n\n## Related Documentation\n\n- [Full Documentation](https://docs.sidebutton.com)\n- [GitHub Repository](https://github.com/sidebutton/sidebutton)\n- [Website](https://sidebutton.com)\n- [Chrome Web Store](https://chromewebstore.google.com/detail/sidebutton/odaefhmdmgijnhdbkfagnlnmobphgkij)\n\n---\n\n\n\n## Workflow Engine\n\n### 相关页面\n\n相关主题：[Step Types Reference](#step-types), [Workflow Examples](#workflow-examples), [Package Overview](#packages-overview)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n- [packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n- [packages/server/src/server.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/server.ts)\n- [packages/server/src/mcp/handler.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/handler.ts)\n- [packages/core/src/providers/github.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/providers/github.ts)\n- [packages/server/defaults/roles/software-engineer.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/software-engineer.md)\n- [packages/server/defaults/targets/_provider-github-cli.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/targets/_provider-github-cli.md)\n
\n\n# Workflow Engine\n\n## Overview\n\nThe SideButton Workflow Engine is a YAML-first orchestration system that enables automation of complex tasks through a declarative step-based approach. It provides 34+ built-in step types spanning browser automation, shell execution, LLM integration, and programmatic control flow operations.\n\nThe engine executes workflows defined in YAML format, supporting variable interpolation, conditional branching, retry logic, and cross-workflow chaining. Workflows can be triggered via MCP (Model Context Protocol), the REST API, or the dashboard interface.\n\n资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n## Architecture\n\n### Core Components\n\n```mermaid\ngraph TD\n A[Workflow YAML] --> B[Parser]\n B --> C[AST / Step Definitions]\n C --> D[Executor]\n D --> E[Step Handlers]\n \n F[Variables/Context] --> D\n D --> F\n \n G[MCP Client] --> D\n H[REST API] --> D\n I[Dashboard] --> D\n```\n\nThe engine consists of three primary layers:\n\n1. **Parser**: Validates and parses YAML workflow definitions into structured step objects\n2. **Executor**: Orchestrates step execution, manages state, and handles control flow\n3. **Step Handlers**: Provider-specific implementations for each step type\n\n资料来源：[packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n\n### Workflow Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Executor\n participant StepHandler\n participant Context\n \n Client->>Executor: executeWorkflow(workflow, context)\n Executor->>Executor: Parse YAML\n Loop For Each Step\n Executor->>StepHandler: Execute Step\n StepHandler->>Context: Update Variables\n StepHandler-->>Executor: Result\n Executor->>Executor: Check Control Flow\n End\n Executor-->>Client: Execution Result\n```\n\n## Step Types\n\nThe workflow engine supports five major categories of steps:\n\n资料来源：[README.md:1-50]()\n\n### Browser Steps\n\nUsed for web automation tasks. All browser steps require an active browser connection.\n\n| Step Type | Description |\n|-----------|-------------|\n| `browser.navigate` | Open a URL in the browser |\n| `browser.click` | Click an element by CSS selector |\n| `browser.type` | Type text into an input element |\n| `browser.fill` | Fill input value directly (React-compatible) |\n| `browser.scroll` | Scroll the page |\n| `browser.extract` | Extract text from an element into a variable |\n| `browser.extractAll` | Extract all matching elements |\n| `browser.extractMap` | Extract structured data from repeated elements |\n| `browser.wait` | Wait for element or fixed delay |\n| `browser.exists` | Check if element exists (returns boolean) |\n| `browser.hover` | Position cursor over element |\n| `browser.key` | Send keyboard keys |\n| `browser.snapshot` | Capture accessibility tree snapshot |\n| `browser.injectCSS` | Inject CSS styles into page |\n| `browser.injectJS` | Execute JavaScript in page context |\n| `browser.select_option` | Select dropdown option |\n| `browser.scrollIntoView` | Scroll element into viewport |\n\n资料来源：[README.md:44-63]()\n\n### Shell Steps\n\nExecute command-line operations on the host system.\n\n| Step Type | Description |\n|-----------|-------------|\n| `shell.run` | Execute a bash/shell command |\n| `terminal.open` | Open a visible terminal window (macOS) |\n| `terminal.run` | Run command in visible terminal window |\n\n资料来源：[README.md:64-66]()\n\n### LLM Steps\n\nIntegrate with large language models for AI-driven operations.\n\n| Step Type | Description |\n|-----------|-------------|\n| `llm.classify` | Structured classification with predefined categories |\n| `llm.generate` | Free-form text generation |\n| `llm.decide` | Make decisions based on context |\n\nSupported providers include Ollama (local), OpenAI, Anthropic, and Google.\n\n资料来源：[README.md:67-73]()\n\n### Control Flow Steps\n\nManage workflow execution logic and branching.\n\n| Step Type | Description |\n|-----------|-------------|\n| `control.if` | Conditional branching based on expression evaluation |\n| `control.retry` | Retry block with configurable backoff |\n| `control.stop` | End workflow with success/error message |\n| `workflow.call` | Call another workflow with parameters |\n| `variable.set` | Set a variable value |\n\n资料来源：[README.md:74-78]()\n\n### Data Steps\n\nManipulate and transform data between steps.\n\n| Step Type | Description |\n|-----------|-------------|\n| `data.first` | Extract first item from a list |\n| `data.get` | Retrieve stored data value |\n\n资料来源：[README.md:79-82]()\n\n## Variable Interpolation\n\nThe workflow engine uses `{{variable}}` syntax for referencing extracted values and parameters.\n\n```yaml\nsteps:\n - type: browser.extract\n selector: \".username\"\n as: user\n - type: shell.run\n cmd: \"echo 'Hello, {{user}}!'\"\n```\n\nVariables can be:\n- Extracted from page elements using `as` parameter\n- Passed as workflow parameters\n- Set via `variable.set` steps\n- Returned from nested workflow calls\n\n资料来源：[README.md:103-115]()\n\n## Workflow Definition Schema\n\nA workflow is defined with the following structure:\n\n```yaml\nid: workflow_identifier\ntitle: \"Display Title\"\ndescription: \"What this workflow does\"\nparams:\n param_name: string # or number, boolean, array, object\nsteps:\n - type: browser.navigate\n url: \"https://example.com\"\n - type: browser.extract\n selector: \".element\"\n as: extracted_value\n```\n\n### Required Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string | Unique workflow identifier |\n| `title` | string | Human-readable title |\n| `steps` | array | Ordered list of step definitions |\n\n### Optional Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `description` | string | Workflow description |\n| `params` | object | Parameter definitions with types |\n| `category` | string | Workflow category |\n| `platform` | string | Target platform |\n\n资料来源：[packages/server/src/server.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/server.ts)\n\n## Control Flow Patterns\n\n### Conditional Branching\n\n```yaml\n- type: control.if\n condition: \"{{current_status}} != 'Done'\"\n then:\n - type: llm.classify\n prompt: \"Should this ticket be closed?\"\n classes: [close, keep_open]\n as: decision\n```\n\n资料来源：[README.md:117-125]()\n\n### Retry with Backoff\n\n```yaml\n- type: control.retry\n max_attempts: 3\n backoff: 1000 # milliseconds\n steps:\n - type: shell.run\n cmd: \"curl -f https://api.example.com/health\"\n```\n\n### Workflow Chaining\n\n```yaml\n- type: workflow.call\n workflow_id: another_workflow\n params:\n input_value: \"{{extracted_data}}\"\n```\n\n资料来源：[packages/server/defaults/roles/software-engineer.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/software-engineer.md)\n\n## MCP Integration\n\nThe workflow engine exposes functionality through the Model Context Protocol, enabling AI assistants to execute and manage workflows.\n\n资料来源：[packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n\n### Available MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `run_workflow` | Execute a workflow by ID |\n| `list_workflows` | List available workflows |\n| `get_workflow` | Get workflow YAML definition |\n| `get_run_log` | Get execution log for a run |\n| `list_run_logs` | List recent workflow executions |\n| `get_browser_status` | Check browser extension connection |\n| `capture_page` | Capture selectors from current page |\n\n### MCP Tool Handlers\n\n```mermaid\ngraph LR\n A[MCP Request] --> B[Handler]\n B --> C{tool_name}\n C -->|list_workflows| D[toolListWorkflows]\n C -->|get_workflow| E[toolGetWorkflow]\n C -->|list_run_logs| F[toolListRunLogs]\n C -->|run_workflow| G[executeWorkflow]\n```\n\n资料来源：[packages/server/src/mcp/handler.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/handler.ts)\n\n### List Workflows Response Format\n\n```typescript\ninterface WorkflowListItem {\n workflow: Workflow;\n source: 'actions' | 'workflows';\n}\n\n// Response includes:\n// - workflow.id\n// - workflow.title\n// - workflow.params (if any)\n// - source identifier\n```\n\n资料来源：[packages/server/src/mcp/handler.ts:1-50]()\n\n## GitHub Integration\n\nThe engine provides specialized steps for GitHub operations through the GitHub CLI provider.\n\n资料来源：[packages/core/src/providers/github.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/providers/github.ts)\n\n### GitHub Step Types\n\n| Step | Description |\n|------|-------------|\n| `git.listPRs` | List pull requests with state filter |\n| `git.getPR` | Get PR details and diff statistics |\n| `git.createPR` | Create a new pull request |\n| `git.listIssues` | List issues with filters |\n| `git.getIssue` | Get issue details |\n| `issues.create` | Create an issue |\n| `issues.comment` | Add a comment to issue/PR |\n| `issues.transition` | Change issue status |\n\n### Create Pull Request Parameters\n\n```typescript\ninterface CreatePRParams {\n repo?: string; // Repository in format \"owner/repo\"\n title: string; // PR title\n body?: string; // PR description\n head: string; // Head branch name\n base?: string; // Base branch (default: main)\n}\n```\n\n资料来源：[packages/core/src/providers/github.ts:1-50]()\n\n### Common GitHub Workflows\n\n**Review Open PRs:**\n1. `git.listPRs` with `state: \"open\"` — view pending reviews\n2. `git.getPR` with PR number — read details and diff stats\n3. Use browser tools for visual diff review\n\n**Autonomous Development Cycle:**\n1. `git.listIssues` — browse available issues\n2. `git.getIssue` — read candidate details\n3. `llm.decide` — select best issue based on priority\n4. `issues.comment` — signal work is starting\n5. `git.createPR` — submit completed work\n\n资料来源：[packages/server/defaults/targets/_provider-github-cli.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/targets/_provider-github-cli.md)\n\n## Execution Context\n\nEach workflow execution maintains a context object that stores:\n\n- **Variables**: Extracted values and set variables\n- **Parameters**: Input parameters passed to the workflow\n- **Results**: Step execution results\n- **Logs**: Execution logs for debugging\n\n```yaml\n# Context is passed to executeWorkflow\ncontext:\n params:\n ticket_id: \"PROJ-123\"\n variables:\n current_status: \"In Progress\"\n```\n\n## Error Handling\n\nThe engine provides multiple mechanisms for error handling:\n\n1. **control.retry**: Automatically retry failed steps with exponential backoff\n2. **control.stop**: Gracefully end workflow with error message\n3. **Conditional checks**: Use `browser.exists` to verify elements before actions\n\n```yaml\nsteps:\n - type: browser.exists\n selector: \".error-message\"\n as: has_error\n - type: control.if\n condition: \"{{has_error}}\"\n then:\n - type: control.stop\n status: error\n message: \"Error detected on page\"\n```\n\n## Dashboard Integration\n\nThe workflow engine integrates with the SideButton dashboard for:\n\n- **Workflow Library**: Browse and install workflows\n- **Run History**: View execution logs and results\n- **Quick Run**: Execute workflows with parameter inputs\n\n资料来源：[packages/server/src/server.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/server.ts)\n\n### Workflow Installation Flow\n\n1. User navigates to workflow in library\n2. Dashboard renders install confirmation page\n3. POST request submits workflow to local server\n4. Server saves workflow to user's action library\n5. Success page confirms installation\n\n```mermaid\ngraph TD\n A[Browse Workflow] --> B[Click Install]\n B --> C[POST /install/:workflowId]\n C --> D[Server Validates]\n D --> E[Save to Actions Library]\n E --> F[Show Success Page]\n```\n\n## Best Practices\n\n1. **Use extracted variables immediately**: Variable references should occur close to their extraction step\n2. **Add wait conditions**: Use `browser.wait` before extracting dynamic content\n3. **Handle missing elements**: Check existence before interacting\n4. **Limit retry attempts**: Configure appropriate `max_attempts` for unreliable operations\n5. **Keep workflows focused**: Prefer workflow chaining over monolithic single workflows\n\n资料来源：[packages/server/defaults/roles/qa.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/qa.md)\n\n---\n\n\n\n## Step Types Reference\n\n### 相关页面\n\n相关主题：[Workflow Engine](#workflow-engine), [Workflow Examples](#workflow-examples)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n- [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n- [packages/core/src/providers/github.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/providers/github.ts)\n- [packages/server/src/mcp/handler.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/handler.ts)\n
\n\n# Step Types Reference\n\nSideButton workflows are composed of discrete steps that define actions to be executed sequentially. Each step type serves a specific purpose—from interacting with web pages to executing shell commands, making decisions via LLM, or orchestrating control flow. Understanding the available step types is essential for building effective automations.\n\n## Overview\n\nSteps are the fundamental building blocks of SideButton workflows. They are defined within workflow YAML files and specify:\n\n- **What action** to perform (the step type)\n- **What parameters** to use for that action\n- **How to handle results** (variable assignment, conditional logic)\n\n资料来源：[packages/core/README.md]()\n\n```mermaid\ngraph TD\n A[Workflow YAML] --> B[Step Execution Engine]\n B --> C[Browser Steps]\n B --> D[Shell Steps]\n B --> E[LLM Steps]\n B --> F[Control Steps]\n B --> G[Data Steps]\n B --> H[Git Steps]\n B --> I[Issues Steps]\n```\n\n## Step Type Categories\n\nSideButton organizes steps into the following categories:\n\n| Category | Purpose | Primary Use Case |\n|----------|---------|------------------|\n| Browser | Web page interaction | UI automation, data extraction |\n| Shell | Command execution | Build tools, CLI operations |\n| LLM | AI-powered decisions | Classification, content generation |\n| Control | Flow control | Conditionals, retries, sub-workflows |\n| Data | Data manipulation | Variable assignment, extraction |\n| Git | Version control | PRs, issues, repository ops |\n| Issues | Issue tracking | Bug tracking, task management |\n\n资料来源：[packages/core/README.md]()\n\n---\n\n## Browser Steps\n\nBrowser steps interact with web pages through a connected Chrome extension. These steps provide real DOM access via CSS selectors, enabling precise UI automation.\n\n### Available Browser Steps\n\n| Step Type | Description |\n|-----------|-------------|\n| `navigate` | Navigate browser to a URL |\n| `click` | Click an element by selector |\n| `type` | Type text into an input field |\n| `scroll` | Scroll the page |\n| `hover` | Hover over an element |\n| `wait` | Wait for condition or duration |\n| `extract` | Extract text from single element |\n| `extractAll` | Extract text from all matching elements |\n| `extract_map` | Extract structured data from repeated elements |\n| `exists` | Check if element exists |\n| `key` | Press keyboard key |\n| `screenshot` | Capture page screenshot |\n| `snapshot` | Get accessibility tree snapshot |\n| `select_option` | Select dropdown option |\n\n资料来源：[README.md]()\n\n### Common Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `selector` | string | CSS selector for target element |\n| `url` | string | Target URL (for navigate) |\n| `text` | string | Text to type or extract |\n| `timeout` | number | Wait timeout in milliseconds |\n| `as` | string | Variable name to store result |\n\n### Example: Basic Browser Workflow\n\n```yaml\nsteps:\n - type: browser.navigate\n url: \"https://github.com/sidebutton/sidebutton\"\n\n - type: browser.snapshot\n\n - type: browser.extract\n selector: \".readme h1\"\n as: repo_title\n\n - type: browser.extractAll\n selector: \".file-info a\"\n as: file_links\n```\n\n### Example: Form Interaction\n\n```yaml\nsteps:\n - type: browser.navigate\n url: \"https://example.com/search\"\n\n - type: browser.type\n selector: \"#search-input\"\n text: \"{{query}}\"\n\n - type: browser.click\n selector: \"#search-button\"\n\n - type: browser.wait\n selector: \".results\"\n timeout: 5000\n```\n\n---\n\n## Shell Steps\n\nShell steps execute command-line commands on the local system. They support both synchronous execution and interactive terminal sessions.\n\n### Available Shell Steps\n\n| Step Type | Description |\n|-----------|-------------|\n| `shell.run` | Execute a shell command |\n| `terminal.open` | Open an interactive terminal |\n| `terminal.run` | Run command in open terminal |\n\n资料来源：[packages/core/README.md]()\n\n### Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `cmd` | string | Shell command to execute |\n| `cwd` | string | Working directory |\n| `env` | object | Environment variables |\n| `timeout` | number | Execution timeout |\n| `async` | boolean | Run asynchronously |\n\n### Example: Shell Command Execution\n\n```yaml\nsteps:\n - type: shell.run\n cmd: \"pnpm build\"\n cwd: \"/path/to/project\"\n timeout: 120000\n as: build_output\n\n - type: shell.run\n cmd: \"git status --short\"\n as: git_status\n```\n\n---\n\n## LLM Steps\n\nLLM steps leverage AI models for content generation, classification, and decision-making. These steps enable intelligent automation that can adapt to context.\n\n### Available LLM Steps\n\n| Step Type | Description |\n|-----------|-------------|\n| `llm.generate` | Generate content with LLM |\n| `llm.classify` | Classify input into categories |\n| `llm.decide` | Make decisions based on context |\n| `llm.extract` | Extract structured data from unstructured text |\n\n资料来源：[README.md](), [packages/core/README.md]()\n\n### Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `prompt` | string | LLM prompt template |\n| `model` | string | Model to use |\n| `temperature` | number | Sampling temperature |\n| `as` | string | Variable name for result |\n\n### Example: Content Generation\n\n```yaml\nsteps:\n - type: llm.generate\n prompt: |\n Write a concise changelog entry for this commit:\n\n === COMMIT ===\n {{commit_message}}\n\n Format: - {{change_summary}}\n as: changelog_entry\n```\n\n### Example: Classification\n\n```yaml\nsteps:\n - type: llm.classify\n input: \"{{issue_body}}\"\n categories:\n - bug\n - feature\n - documentation\n - question\n as: issue_type\n```\n\n---\n\n## Control Steps\n\nControl steps manage workflow execution flow, enabling conditionals, loops, error handling, and sub-workflow invocation.\n\n### Available Control Steps\n\n| Step Type | Description |\n|-----------|-------------|\n| `control.if` | Conditional execution |\n| `control.retry` | Retry failed steps |\n| `control.stop` | Stop execution with message |\n| `workflow.call` | Call another workflow |\n\n资料来源：[packages/core/README.md]()\n\n### control.if\n\nExecute steps conditionally based on a boolean expression.\n\n```yaml\nsteps:\n - type: control.if\n condition: \"{{is_authenticated}}\"\n then:\n - type: browser.click\n selector: \".dashboard-link\"\n else:\n - type: browser.click\n selector: \".login-button\"\n```\n\n### control.retry\n\nRetry a step or block of steps on failure.\n\n```yaml\nsteps:\n - type: control.retry\n attempts: 3\n delay: 1000\n steps:\n - type: shell.run\n cmd: \"curl -f https://api.example.com/health\"\n```\n\n### control.stop\n\nStop workflow execution and output a message.\n\n```yaml\nsteps:\n - type: control.stop\n message: |\n === Processing Complete ===\n\n Extracted {{item_count}} items\n Status: {{final_status}}\n```\n\n### workflow.call\n\nInvoke another workflow as a subroutine.\n\n```yaml\nsteps:\n - type: workflow.call\n workflow_id: \"send_notification\"\n params:\n channel: \"#alerts\"\n message: \"{{summary}}\"\n```\n\n---\n\n## Data Steps\n\nData steps manipulate variables and extract information for use by subsequent steps.\n\n### Available Data Steps\n\n| Step Type | Description |\n|-----------|-------------|\n| `data.first` | Get first item from array |\n| `data.get` | Get value from object |\n| `data.set` | Set a variable value |\n| `variable.set` | Set a workflow variable |\n\n资料来源：[packages/core/README.md](), [README.md]()\n\n### Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `from` | string | Source variable to extract from |\n| `default` | any | Default value if not found |\n| `as` | string | Variable name for result |\n\n### Example: Data Extraction\n\n```yaml\nsteps:\n - type: browser.extract\n selector: \".user-profile\"\n as: profile_html\n\n - type: data.first\n from: \"{{profile_html}}\"\n as: first_profile\n\n - type: data.set\n key: \"user_name\"\n value: \"{{first_profile.name}}\"\n```\n\n---\n\n## Git Steps\n\nGit steps interact with GitHub repositories via the `gh` CLI tool. These steps support pull requests, issues, and repository operations.\n\n### Available Git Steps\n\n| Step Type | Description |\n|-----------|-------------|\n| `git.listPRs` | List pull requests |\n| `git.getPR` | Get PR details |\n| `git.createPR` | Create pull request |\n| `git.listIssues` | List issues |\n| `git.getIssue` | Get issue details |\n\n资料来源：[packages/core/src/providers/github.ts](), [README.md]()\n\n### Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `repo` | string | Repository (owner/repo) |\n| `state` | string | Issue/PR state (open, closed, all) |\n| `labels` | string | Filter by labels |\n| `limit` | number | Maximum results |\n\n### Example: List Pull Requests\n\n```yaml\nsteps:\n - type: git.listPRs\n repo: \"sidebutton/sidebutton\"\n state: \"open\"\n limit: 10\n as: open_prs\n\n - type: control.stop\n message: |\n === Open PRs ===\n {{open_prs}}\n```\n\n### Example: Create Pull Request\n\n```yaml\nsteps:\n - type: git.createPR\n repo: \"sidebutton/sidebutton\"\n title: \"feat: add new automation step\"\n head: \"feature-branch\"\n base: \"main\"\n body: |\n ## Summary\n This PR adds support for...\n\n ## Testing\n - [ ] Unit tests pass\n - [ ] Manual testing completed\n as: pr_result\n```\n\n---\n\n## Issues Steps\n\nIssues steps manage issue tracking across connected providers. They support searching, creating, and updating issues.\n\n### Available Issues Steps\n\n| Step Type | Description |\n|-----------|-------------|\n| `issues.search` | Search for issues |\n| `issues.get` | Get issue details |\n| `issues.create` | Create new issue |\n| `issues.comment` | Add comment to issue |\n| `issues.transition` | Change issue status |\n| `issues.attach` | Attach file to issue |\n\n资料来源：[README.md]()\n\n### Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `query` | string | Search query |\n| `repo` | string | Repository |\n| `title` | string | Issue title |\n| `body` | string | Issue body |\n| `labels` | array | Issue labels |\n\n### Example: Search and Create Issue\n\n```yaml\nsteps:\n - type: issues.search\n query: \"is:issue is:open label:bug\"\n repo: \"sidebutton/sidebutton\"\n as: existing_bugs\n\n - type: control.if\n condition: \"{{existing_bugs.length}} == 0\"\n then:\n - type: issues.create\n repo: \"sidebutton/sidebutton\"\n title: \"Bug: {{bug_description}}\"\n body: |\n ## Description\n {{bug_description}}\n\n ## Steps to Reproduce\n 1.\n 2.\n 3.\n labels: [\"bug\"]\n as: new_issue\n```\n\n---\n\n## Variable Interpolation\n\nVariables are referenced throughout steps using `{{variable}}` syntax. This enables dynamic values from previous step results.\n\n```yaml\nsteps:\n - type: browser.extract\n selector: \".username\"\n as: user\n\n - type: shell.run\n cmd: \"echo 'Hello, {{user}}!'\"\n\n - type: llm.generate\n prompt: \"Write a welcome message for user: {{user}}\"\n as: welcome_message\n```\n\n### Variable Scoping\n\n| Scope | Description |\n|-------|-------------|\n| `{{step_id.value}}` | Result from specific step |\n| `{{params.name}}` | Workflow parameter value |\n| `{{env.VAR_NAME}}` | Environment variable |\n\n---\n\n## Step Execution Order\n\nSteps execute sequentially by default. The execution order can be controlled through:\n\n1. **Sequential**: Steps run in definition order\n2. **Conditional**: `control.if` skips or executes blocks\n3. **Retry**: `control.retry` repeats failed steps\n4. **Sub-workflow**: `workflow.call` executes external workflows\n\n```mermaid\ngraph LR\n A[Step 1] --> B{control.if}\n B -->|condition true| C[Step 2a]\n B -->|condition false| D[Step 2b]\n C --> E[Step 3]\n D --> E\n E --> F[control.retry]\n F -->|success| G[Step 4]\n F -->|failure| F\n G --> H[workflow.call]\n H --> I[Step 5]\n```\n\n---\n\n## Error Handling\n\n### Retry on Failure\n\n```yaml\nsteps:\n - type: control.retry\n attempts: 3\n delay: 2000\n steps:\n - type: shell.run\n cmd: \"npm test\"\n```\n\n### Conditional Failure Handling\n\n```yaml\nsteps:\n - type: control.if\n condition: \"{{command_success}}\"\n then:\n - type: browser.click\n selector: \".continue-button\"\n else:\n - type: issues.create\n title: \"Deployment failed\"\n body: \"Command exited with error\"\n```\n\n---\n\n## Best Practices\n\n### 1. Use Specific Selectors\n\nPrefer specific CSS selectors over generic ones:\n\n```yaml\n# Good\n- type: browser.click\n selector: \"#main-nav .settings-link\"\n\n# Avoid\n- type: browser.click\n selector: \"a:nth-child(2)\"\n```\n\n### 2. Add Timeouts for Dynamic Content\n\n```yaml\nsteps:\n - type: browser.wait\n selector: \".loading-complete\"\n timeout: 10000\n```\n\n### 3. Store Intermediate Results\n\n```yaml\nsteps:\n - type: browser.extract\n selector: \".data-table tr\"\n as: rows\n\n - type: data.first\n from: \"{{rows}}\"\n as: first_row\n```\n\n### 4. Use LLM for Dynamic Decisions\n\n```yaml\nsteps:\n - type: llm.classify\n input: \"{{user_feedback}}\"\n categories: [\"positive\", \"negative\", \"neutral\"]\n as: sentiment\n\n - type: control.if\n condition: \"{{sentiment}} == 'negative'\"\n then:\n - type: issues.create\n title: \"Negative feedback received\"\n```\n\n---\n\n## Summary\n\nStep types in SideButton provide a comprehensive toolkit for building automations:\n\n| Category | Key Steps |\n|----------|-----------|\n| Browser | `navigate`, `click`, `type`, `extract`, `snapshot` |\n| Shell | `shell.run`, `terminal.open` |\n| LLM | `llm.generate`, `llm.classify`, `llm.decide` |\n| Control | `control.if`, `control.retry`, `workflow.call` |\n| Data | `data.first`, `data.get` |\n| Git | `git.listPRs`, `git.createPR` |\n| Issues | `issues.search`, `issues.create` |\n\nFor more details on workflow configuration and YAML syntax, refer to the [Workflow Configuration Reference](https://docs.sidebutton.com).\n\n---\n\n\n\n## Workflow Examples\n\n### 相关页面\n\n相关主题：[Workflow Engine](#workflow-engine), [Step Types Reference](#step-types)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [bundles/github/workflows/create_release.yaml](https://github.com/sidebutton/sidebutton/blob/main/bundles/github/workflows/create_release.yaml)\n- [bundles/github/workflows/github_pr_claude_review.yaml](https://github.com/sidebutton/sidebutton/blob/main/bundles/github/workflows/github_pr_claude_review.yaml)\n- [workflows/llm_summarize.yaml](https://github.com/sidebutton/sidebutton/blob/main/workflows/llm_summarize.yaml)\n- [workflows/wikipedia_open.yaml](https://github.com/sidebutton/sidebutton/blob/main/workflows/wikipedia_open.yaml)\n- [packages/server/defaults/workflows/llm_summarize.yaml](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/workflows/llm_summarize.yaml)\n
\n\n# Workflow Examples\n\n## Overview\n\nWorkflow Examples in SideButton are pre-built YAML-based automation sequences that demonstrate how to combine different step types to accomplish real-world tasks. These examples serve as both practical utilities and learning references for building custom automations.\n\nThe SideButton workflow system supports multiple integration methods depending on available providers:\n\n| Provider Preference | Method | Reliability |\n|---------------------|--------|-------------|\n| 1st | API Provider | Fastest and most reliable |\n| 2nd | CLI Tool | Good for git operations |\n| 3rd | Browser Automation | Universal fallback |\n\n资料来源：[packages/server/defaults/roles/software-engineer.md]()\n\n## Workflow Structure\n\nEvery workflow in SideButton follows a standardized YAML format with the following core structure:\n\n```yaml\nid: workflow_identifier\ntitle: \"Human Readable Title\"\ndescription: \"What this workflow accomplishes\"\nsteps:\n - type: step.type\n property: value\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n### Basic Anatomy of a Workflow\n\n```mermaid\ngraph TD\n A[YAML Workflow File] --> B[Workflow Engine]\n B --> C{Step Type Router}\n C -->|Browser| D[Browser Tools]\n C -->|Shell| E[Terminal/CLI]\n C -->|LLM| F[AI Provider]\n C -->|Control| G[Flow Control]\n C -->|Data| H[Data Manipulation]\n \n D --> I[Execute Action]\n E --> I\n F --> I\n G --> I\n H --> I\n \n I --> J[Run Log Entry]\n```\n\n## Step Types Reference\n\nSideButton provides five categories of steps that can be combined in workflows:\n\n资料来源：[packages/core/README.md]()\n\n### Browser Steps\n\n| Step | Purpose |\n|------|---------|\n| `navigate` | Navigate browser to URL |\n| `click` | Click an element |\n| `type` | Type text into an element |\n| `scroll` | Scroll the page |\n| `hover` | Hover over element |\n| `wait` | Wait for condition |\n| `extract` | Extract text from element |\n| `extractAll` | Extract all matching elements |\n| `exists` | Check element exists |\n| `key` | Press keyboard key |\n| `snapshot` | Get accessibility tree |\n| `screenshot` | Capture screenshot |\n\n资料来源：[README.md]()\n\n### Shell/Terminal Steps\n\n| Step | Purpose |\n|------|---------|\n| `shell.run` | Execute shell command |\n| `terminal.open` | Open visible terminal window (macOS) |\n| `terminal.run` | Run command in terminal window |\n\n### LLM Steps\n\n| Step | Purpose |\n|------|---------|\n| `llm.classify` | Structured classification with categories |\n| `llm.generate` | Free-form text generation |\n| `llm.decide` | AI-driven decision making |\n\n### Control Flow Steps\n\n| Step | Purpose |\n|------|---------|\n| `control.if` | Conditional branching |\n| `control.retry` | Retry with backoff |\n| `control.stop` | End workflow with message |\n| `workflow.call` | Call another workflow with parameters |\n\n### Data Steps\n\n| Step | Purpose |\n|------|---------|\n| `data.first` | Extract first item from list |\n| `data.get` | Get value from data object |\n\n## GitHub Workflow Examples\n\nSideButton includes pre-built workflows for GitHub automation stored in the `bundles/github/workflows/` directory.\n\n### GitHub PR Claude Review\n\nThis workflow demonstrates how to automate PR review using Claude AI. The workflow follows a typical review pattern:\n\n```mermaid\ngraph LR\n A[List Open PRs] --> B[Get PR Details]\n B --> C[Extract Diff Stats]\n C --> D[Navigate to PR]\n D --> E[Review Files Changed]\n E --> F[Generate Review Comment]\n```\n\n资料来源：[bundles/github/workflows/github_pr_claude_review.yaml]()\n\n**Common PR Review Sequence:**\n\n1. `git.listPRs` with `state: \"open\"` — see what needs review\n2. `git.getPR` with number — read details and diff stats\n3. Use browser tools for visual diff review if needed\n\n资料来源：[packages/server/defaults/targets/_provider-github-cli.md]()\n\n### Create Release Workflow\n\nThe release creation workflow demonstrates orchestrating multiple operations:\n\n1. Open the release page using browser automation\n2. Decide the next version tag based on commit history\n3. Create the release with proper version naming\n\n资料来源：[bundles/github/workflows/create_release.yaml]()\n\n**Creating a PR after coding:**\n\n1. `git.createPR` with title, head branch, base branch\n2. `issues.comment` on related issue linking the PR\n\n资料来源：[packages/server/defaults/targets/_provider-github-cli.md]()\n\n## LLM-Based Workflows\n\n### Summarize Workflow\n\nThe `llm_summarize.yaml` workflow demonstrates integration with AI providers for text processing:\n\n```yaml\nid: llm_summarize\ntitle: \"Summarize Content\"\ndescription: \"Generate a summary using LLM\"\nsteps:\n - type: llm.generate\n prompt: \"{{input_text}}\"\n instruction: \"Provide a concise summary\"\n```\n\n资料来源：[workflows/llm_summarize.yaml]()\n资料来源：[packages/server/defaults/workflows/llm_summarize.yaml]()\n\n**LLM Provider Support:**\n\nLLM steps work with multiple providers:\n- Ollama (local)\n- OpenAI\n- Anthropic\n- Google\n\n资料来源：[README.md]()\n\n### Decision Workflows\n\nThe `llm.decide` step type enables autonomous decision-making:\n\n```mermaid\ngraph TD\n A[Issue Received] --> B{llm.decide}\n B -->|Clear & well-scoped| C[Pick and start work]\n B -->|Ambiguous/blocked| D[Skip, pick next]\n B -->|Same priority| E[Prefer smaller scope]\n B -->|No suitable issues| F[Stop and report]\n```\n\n资料来源：[packages/server/defaults/roles/software-engineer.md]()\n\n## Browser-Based Workflows\n\n### Wikipedia Open Example\n\nThis demonstrates basic browser navigation and content extraction:\n\n```yaml\nid: wikipedia_open\ntitle: \"Open Wikipedia Page\"\nsteps:\n - type: browser.navigate\n url: \"{{wiki_url}}\"\n - type: browser.snapshot\n as: page_content\n - type: browser.extract\n selector: \"{{element_selector}}\"\n as: extracted_text\n```\n\n资料来源：[workflows/wikipedia_open.yaml]()\n\n**Best Practices for Browser Steps:**\n\n1. Use `snapshot` to understand page structure before taking actions\n2. Use `extract` to pull specific content from pages\n3. Use `screenshot` for visual verification\n\n资料来源：[packages/server/defaults/roles/software-engineer.md]()\n\n## Variable Interpolation\n\nAll workflows support variable interpolation using `{{variable}}` syntax:\n\n```yaml\nsteps:\n - type: browser.extract\n selector: \".username\"\n as: user\n - type: shell.run\n cmd: \"echo 'Hello, {{user}}!'\"\n - type: llm.generate\n prompt: \"Write a greeting for {{user}}\"\n```\n\n资料来源：[README.md]()\n\n## Parameterized Workflows\n\nWorkflows can accept parameters for flexibility:\n\n```yaml\nid: check_ticket_status\ntitle: \"Check Ticket Status\"\nparams:\n ticket_id: string\nsteps:\n - type: browser.navigate\n url: \"https://jira.example.com/browse/{{ticket_id}}\"\n - type: browser.extract\n selector: \"[data-testid='status-field']\"\n as: current_status\n```\n\n资料来源：[README.md]()\n\n## Execution Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant MCP as MCP Handler\n participant Engine as Workflow Engine\n participant Steps as Step Executors\n \n User->>MCP: run_workflow(workflow_id, params)\n MCP->>Engine: executeWorkflow(workflow, context)\n Engine->>Steps: Execute Step 1\n Steps-->>Engine: Step Result\n Engine->>Steps: Execute Step 2\n Steps-->>Engine: Step Result\n Engine->>MCP: Run Log Entry\n MCP-->>User: Execution Result\n```\n\n资料来源：[packages/server/src/mcp/handler.ts]()\n资料来源：[packages/core/README.md]()\n\n## Workflow Bundles\n\nSideButton organizes related workflows into bundles. The GitHub bundle includes:\n\n```json\n{\n \"name\": \"sidebutton/github\",\n \"version\": \"1.0.0\",\n \"title\": \"GitHub Automation\",\n \"description\": \"Workflows for GitHub releases, PR reviews, and repository management\",\n \"workflows\": [\n \"open_release_page.yaml\",\n \"decide_next_tag.yaml\",\n \"create_release.yaml\",\n \"github_pr_claude_review.yaml\"\n ],\n \"requires\": {\n \"llm\": true,\n \"browser\": true\n }\n}\n```\n\n资料来源：[bundles/github/bundle.json]()\n\n## Adding Custom Workflows\n\nThe easiest way to contribute is by adding workflows to the `workflows/` directory:\n\n```bash\n# Create a new workflow file\ncat > workflows/my_workflow.yaml << 'EOF'\nid: my_workflow\ntitle: \"My Workflow\"\ndescription: \"What this workflow does\"\nsteps:\n - type: shell.run\n cmd: \"echo 'Hello!'\"\nEOF\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## See Also\n\n- [Step Reference](https://docs.sidebutton.com) — Complete documentation for all step types\n- [MCP Tools](https://docs.sidebutton.com/mcp) — Model Context Protocol integration\n- [Server Documentation](../server/README.md) — Backend workflow execution\n- [Core Engine](../core/README.md) — Workflow engine internals\n\n---\n\n\n\n## MCP Server Integration\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture), [Chrome Extension](#chrome-extension), [Knowledge Packs](#knowledge-packs)\n\n
\nRelated Source Files\n\n以下源码文件用于生成本页说明：\n\n- [packages/server/src/mcp/handler.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/handler.ts)\n- [packages/server/src/mcp/tools.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/tools.ts)\n- [packages/server/src/mcp/stdio.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/stdio.ts)\n- [packages/server/src/server.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/server.ts)\n- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n
\n\n# MCP Server Integration\n\n## Overview\n\nThe SideButton MCP Server is the core integration layer that exposes browser automation tools, workflow execution capabilities, and knowledge pack management through the Model Context Protocol (MCP). This enables AI assistants like Claude Desktop, Claude Code, and Cursor to control web browsers and execute automated workflows using a standardized interface.\n\n**资料来源：** [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n\n## Architecture\n\nThe MCP server is built as part of the `@sidebutton/server` package and supports multiple transport mechanisms for different AI assistant clients.\n\n### Transport Modes\n\n| Transport | Use Case | Configuration |\n|-----------|----------|---------------|\n| **HTTP/SSE** | Claude Code, Cursor | `type: \"sse\"`, `url: \"http://localhost:9876/mcp\"` |\n| **stdio** | Claude Desktop | `command: \"npx\"`, `args: [\"sidebutton\", \"--stdio\"]` |\n| **WebSocket** | Chrome Extension | Automatic reconnection support |\n\n**资料来源：** [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n\n### Component Flow\n\n```mermaid\ngraph TD\n subgraph \"AI Assistant\"\n A[Claude Desktop / Claude Code / Cursor]\n end\n \n subgraph \"MCP Transport\"\n B[stdio / HTTP-SSE]\n end\n \n subgraph \"SideButton Server\"\n C[MCP Handler]\n D[Tool Registry]\n E[Workflow Engine]\n F[Browser Controller]\n end\n \n subgraph \"Browser Layer\"\n G[Chrome Extension]\n H[Real DOM Access]\n end\n \n A --> B\n B --> C\n C --> D\n C --> E\n C --> F\n F <--> G\n G <--> H\n```\n\n## Tool Registry\n\nThe MCP server exposes a comprehensive set of tools organized by functionality. Each tool follows a consistent schema with annotations for the Claude Connectors Directory.\n\n**资料来源：** [packages/server/src/mcp/tools.ts:1-50](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/tools.ts)\n\n### Tool Annotations\n\n| Annotation | Purpose | Example |\n|------------|---------|---------|\n| `title` | Human-readable display name | `\"Run Workflow\"` |\n| `readOnlyHint` | Indicates observation-only tools | `true` for `snapshot` |\n| `destructiveHint` | Indicates state-mutating tools | `true` for `run_workflow` |\n| `openWorldHint` | Indicates external world interaction | `true` for browser tools |\n\n**资料来源：** [packages/server/src/mcp/tools.ts:14-23](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/tools.ts)\n\n## Workflow Tools\n\n### Core Workflow Operations\n\n| Tool | Description | Mutates State |\n|------|-------------|---------------|\n| `run_workflow` | Execute a workflow automation by ID | Yes |\n| `list_workflows` | List all available workflows | No |\n| `get_workflow` | Get workflow YAML definition | No |\n| `list_run_logs` | List recent workflow executions | No |\n| `get_run_log` | Get execution log for a specific run | No |\n\n### run_workflow Parameters\n\n```typescript\n{\n workflow_id: string; // Required: Unique identifier\n params?: { // Optional: Key-value parameters\n [key: string]: string;\n };\n}\n```\n\n**资料来源：** [packages/server/src/mcp/tools.ts:35-52](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/tools.ts)\n\n## Browser Automation Tools\n\nThe MCP server provides direct browser control through the connected Chrome Extension.\n\n### Navigation & State\n\n| Tool | Description |\n|------|-------------|\n| `navigate` | Navigate browser to a URL |\n| `snapshot` | Get page accessibility tree (DOM structure) |\n| `screenshot` | Capture page screenshot |\n| `get_browser_status` | Check extension connection status |\n| `capture_page` | Capture CSS selectors from current page |\n\n### Interaction Tools\n\n| Tool | Description | Read-Only |\n|------|-------------|-----------|\n| `click` | Click an element by selector | No |\n| `type` | Type text into an input element | No |\n| `scroll` | Scroll the page | No |\n| `hover` | Hover over an element | No |\n| `extract` | Extract text from an element | Yes |\n| `extract_all` | Extract text from all matching elements | Yes |\n| `extract_map` | Extract structured data from repeated elements | Yes |\n| `select_option` | Select a dropdown option | No |\n| `wait` | Wait for element or condition | No |\n| `exists` | Check if element exists | Yes |\n| `key` | Press a keyboard key | No |\n\n**资料来源：** [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n\n### Browser Tool Annotations\n\n```typescript\n{\n name: 'snapshot',\n description: 'Get page accessibility snapshot',\n inputSchema: {\n type: 'object',\n properties: {\n // Configuration options\n }\n },\n annotations: {\n title: 'Page Snapshot',\n readOnlyHint: true, // Observation only\n openWorldHint: true // Interacts with browser\n }\n}\n```\n\n## Provider Integration Tools\n\nSideButton integrates with external providers for enhanced functionality:\n\n| Category | Tools |\n|----------|-------|\n| **Git** | `git.listPRs`, `git.getPR`, `git.createPR`, `git.listIssues`, `git.getIssue` |\n| **Issues** | `issues.search`, `issues.get`, `issues.create`, `issues.transition`, `issues.comment`, `issues.attach` |\n| **Chat** | `chat.readChannel`, `chat.readThread`, `chat.listChannels` |\n| **Terminal** | `terminal.open`, `terminal.run` |\n| **LLM** | `llm.generate`, `llm.decide`, `llm.classify` |\n\n### Git Provider Implementation\n\nThe GitHub CLI connector provides programmatic access to GitHub operations:\n\n```typescript\nasync createPullRequest(params: {\n repo?: string;\n title: string;\n body?: string;\n head: string;\n base?: string;\n}): Promise<{ number: number; url: string }>\n```\n\n**资料来源：** [packages/core/src/providers/github.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/core/src/providers/github.ts)\n\n## MCP Endpoint Configuration\n\n### Server Endpoints\n\n| Endpoint | Method | Purpose |\n|----------|--------|---------|\n| `/mcp` | SSE | Server-Sent Events for Claude Code/Cursor |\n| `/mcp` | POST | Tool invocation requests |\n| `/mcp` | GET | Server info and capabilities |\n\n**资料来源：** [packages/server/src/server.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/server.ts)\n\n### Client Configuration Examples\n\n#### Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"sidebutton\": {\n \"command\": \"npx\",\n \"args\": [\"sidebutton\", \"--stdio\"]\n }\n }\n}\n```\n\n#### Claude Code\n\n```json\n{\n \"mcpServers\": {\n \"sidebutton\": {\n \"type\": \"sse\",\n \"url\": \"http://localhost:9876/mcp\"\n }\n }\n}\n```\n\n#### Cursor\n\n```json\n{\n \"mcpServers\": {\n \"sidebutton\": {\n \"url\": \"http://localhost:9876/mcp\"\n }\n }\n}\n```\n\n**资料来源：** [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n\n## CLI Commands for MCP\n\nThe `sidebutton` CLI provides workflow management commands:\n\n```bash\nsidebutton list # List available workflows\nsidebutton run # Run a workflow by ID\nsidebutton status # Check server status\n```\n\n**资料来源：** [packages/sidebutton/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/sidebutton/README.md)\n\n## Data Models\n\n### MCP Tool Schema\n\n```typescript\nexport interface McpTool {\n name: string;\n description: string;\n inputSchema: Record;\n annotations?: McpToolAnnotations;\n}\n\nexport interface McpToolAnnotations {\n title: string;\n readOnlyHint?: true;\n destructiveHint?: true;\n openWorldHint?: true;\n}\n```\n\n**资料来源：** [packages/server/src/mcp/tools.ts:7-23](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/mcp/tools.ts)\n\n## Quick Start\n\n1. **Start the server:**\n ```bash\n npx sidebutton@latest\n ```\n\n2. **Connect your AI assistant** using the appropriate configuration above\n\n3. **Verify connection:**\n ```bash\n sidebutton status\n ```\n\n4. **Execute a workflow:**\n ```bash\n sidebutton run \n ```\n\n**资料来源：** [AGENTS.md](https://github.com/sidebutton/sidebutton/blob/main/AGENTS.md)\n\n## See Also\n\n- [Core Workflow Engine](../core/README.md) - Workflow execution runtime\n- [Chrome Extension](../extension/) - Browser control implementation\n- [Knowledge Packs](../knowledge-packs/) - Domain-specific automation packs\n\n---\n\n\n\n## Chrome Extension\n\n### 相关页面\n\n相关主题：[MCP Server Integration](#mcp-server), [Step Types Reference](#step-types)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/sidebutton/sidebutton/blob/main/CONTRIBUTING.md)\n- [AGENTS.md](https://github.com/sidebutton/sidebutton/blob/main/AGENTS.md)\n- [packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n- [packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n- [packages/server/defaults/roles/software-engineer.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/software-engineer.md)\n- [packages/server/defaults/roles/qa.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/qa.md)\n- [packages/server/defaults/targets/_provider-github-browser.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/targets/_provider-github-browser.md)\n
\n\n# Chrome Extension\n\nThe SideButton Chrome Extension is a Manifest V3 browser extension that provides real-time browser automation capabilities through a WebSocket connection to the local MCP server. It enables AI agents and workflows to interact with web pages using real DOM access via CSS selectors.\n\n## Overview\n\nThe Chrome Extension serves as the primary interface between SideButton's workflow engine and web pages. Rather than relying on pixel coordinates or screenshots, it provides direct DOM manipulation capabilities, making browser automation precise and reliable.\n\n**Distribution:** Available on the [Chrome Web Store](https://chromewebstore.google.com/detail/sidebutton/odaefhmdmgijnhdbkfagnlnmobphgkij)\n\n**Source location:** `extension/` directory in the repository\n\n资料来源：[CONTRIBUTING.md](https://github.com/sidebutton/sidebutton/blob/main/CONTRIBUTING.md)\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"Browser Context\"\n CE[Chrome Extension]\n WS[WebSocket Connection]\n end\n \n subgraph \"Local Server\"\n MCP[MCP Server :9876]\n API[REST API]\n end\n \n subgraph \"Workflow Engine\"\n WE[Workflow Executor]\n ST[Step Types]\n end\n \n CE -->|Real DOM Access| PAGE[Web Pages]\n CE -->|WebSocket| WS\n WS --> MCP\n MCP --> WE\n WE --> ST\n ST -->|browser.* steps| CE\n```\n\n### Connection Flow\n\n1. User clicks the SideButton extension icon in Chrome\n2. Extension establishes WebSocket connection to `http://localhost:9876`\n3. MCP server validates the connection and exposes browser tools\n4. Workflows execute browser steps through the extension\n5. Extension interacts with web pages via Chrome DevTools Protocol\n\n资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n## Browser Commands\n\nThe extension supports 40+ browser commands organized into functional categories:\n\n| Command | Description | Use Case |\n|---------|-------------|----------|\n| `navigate` | Navigate browser to URL | Open pages for automation |\n| `click` | Click an element by selector | Interact with buttons, links |\n| `type` | Type text into an element | Form input |\n| `scroll` | Scroll the page | Load more content |\n| `hover` | Hover over element | Trigger hover states |\n| `extract` | Extract text from element | Read page content |\n| `extract_all` | Extract all matching elements | Get lists of items |\n| `extract_map` | Extract structured data from repeated elements | Scrape data tables |\n| `select_option` | Select dropdown option | Choose from selects |\n| `fill` | Fill input value (React-compatible) | Handle React inputs |\n| `press_key` | Send keyboard keys | Keyboard shortcuts |\n| `scroll_into_view` | Scroll element into viewport | Ensure element visible |\n| `evaluate` | Execute JavaScript in browser | Custom interactions |\n| `exists` | Check if element exists | Conditional logic |\n| `wait` | Wait for element or delay | Synchronize with page |\n| `screenshot` | Capture page screenshot | Visual verification |\n| `snapshot` | Get page accessibility tree | Understand page structure |\n| `capture_page` | Capture selectors from current page | Identify elements |\n| `check_writing_quality` | Evaluate text quality | Content validation |\n\n资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n## Key Features\n\n### Real DOM Access\n\nUnlike screen-based automation tools that rely on pixel coordinates or OCR, SideButton uses real DOM access through CSS selectors. This provides:\n\n- Precise element targeting\n- Works with dynamically rendered content\n- Handles SPA (Single Page Applications) correctly\n- Faster execution than vision-based alternatives\n\n资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n### Recording Mode\n\nThe extension includes a recording mode that captures manual actions as reusable workflows. This enables:\n\n1. Manual browsing through desired workflow steps\n2. Extension records each action with selector\n3. Export as YAML workflow definition\n4. Replay with workflow engine\n\n### Embed Buttons\n\nSideButton can inject action buttons into any web page, enabling:\n\n- Quick access to defined actions\n- On-page automation triggers\n- Custom UI integration\n\n### WebSocket Connection\n\nThe extension maintains a stable WebSocket connection with automatic reconnection:\n\n```mermaid\nsequenceDiagram\n participant EXT as Extension\n participant WS as WebSocket\n participant MCP as MCP Server\n participant PAGE as Web Page\n \n EXT->>WS: Connect\n WS->>MCP: Establish Session\n MCP-->>WS: Connected\n WS-->>EXT: Ready\n \n loop On Command\n MCP->>EXT: Execute Tool\n EXT->>PAGE: DOM Action\n PAGE-->>EXT: Result\n EXT-->>MCP: Response\n end\n \n Note over EXT,WS: Auto-reconnect on disconnect\n```\n\n### Stable Reconnection\n\nThe WebSocket implementation handles connection drops gracefully:\n\n- Automatic retry with exponential backoff\n- Works with local server instances\n- Supports remote server connections\n- Maintains session state across reconnections\n\n资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n## Installation\n\n### From Chrome Web Store\n\n1. Visit the [Chrome Web Store listing](https://chromewebstore.google.com/detail/sidebutton/odaefhmdmgijnhdbkfagnlnmobphgkij)\n2. Click \"Add to Chrome\"\n3. Grant necessary permissions\n\n### From Source (Development)\n\n1. Go to `chrome://extensions/`\n2. Enable **Developer mode**\n3. Click **Load unpacked** and select the `extension/` folder\n4. Navigate to any page and click the extension icon to connect\n\n资料来源：[CONTRIBUTING.md](https://github.com/sidebutton/sidebutton/blob/main/CONTRIBUTING.md)\n\n## Connection States\n\n| State | Indicator | Meaning |\n|-------|-----------|---------|\n| Connected | Green dot | Extension linked to server |\n| Disconnected | Red dot | No active connection |\n| Reconnecting | Yellow dot | Attempting to reconnect |\n\nVerify connection status using the MCP `get_browser_status` tool:\n\n```json\n{\n \"tool\": \"get_browser_status\",\n \"expected\": { \"connected\": true }\n}\n```\n\n资料来源：[packages/server/defaults/roles/qa.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/qa.md)\n\n## Usage in Workflows\n\nBrowser steps are defined in YAML workflows:\n\n```yaml\nsteps:\n - type: browser.navigate\n url: \"https://github.com/owner/repo/issues\"\n \n - type: browser.snapshot\n as: page_state\n \n - type: browser.click\n selector: \".btn-primary\"\n \n - type: browser.type\n selector: \"#title\"\n text: \"{{issue_title}}\"\n \n - type: browser.extract\n selector: \".issue-number\"\n as: new_issue_id\n```\n\n### Variable Interpolation\n\nUse `{{variable}}` syntax to reference extracted values:\n\n```yaml\nsteps:\n - type: browser.extract\n selector: \".username\"\n as: user\n - type: shell.run\n cmd: \"echo 'Hello, {{user}}!'\"\n```\n\n资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n## Step Types Reference\n\n### Navigation Steps\n\n| Step Type | Parameters | Description |\n|-----------|------------|-------------|\n| `browser.navigate` | `url` | Open URL in connected browser |\n\n### Interaction Steps\n\n| Step Type | Parameters | Description |\n|-----------|------------|-------------|\n| `browser.click` | `selector` | Click element by CSS selector |\n| `browser.type` | `selector`, `text` | Type text into input |\n| `browser.fill` | `selector`, `value` | Fill input value (React-compatible) |\n| `browser.hover` | `selector` | Hover over element |\n| `browser.select_option` | `selector`, `value` | Select dropdown option |\n| `browser.press_key` | `keys` | Send keyboard keys |\n| `browser.scroll` | `direction`, `amount` | Scroll page |\n| `browser.scroll_into_view` | `selector` | Scroll element into view |\n\n### Extraction Steps\n\n| Step Type | Parameters | Description |\n|-----------|------------|-------------|\n| `browser.extract` | `selector`, `as` | Extract text from single element |\n| `browser.extract_all` | `selector`, `as` | Extract all matching elements |\n| `browser.extract_map` | `selector`, `mapping`, `as` | Extract structured data |\n| `browser.snapshot` | `as` | Get accessibility tree |\n| `browser.screenshot` | `as` | Capture screenshot |\n\n### Verification Steps\n\n| Step Type | Parameters | Description |\n|-----------|------------|-------------|\n| `browser.exists` | `selector` | Check if element exists |\n| `browser.wait` | `selector` or `ms` | Wait for element or delay |\n\n### Advanced Steps\n\n| Step Type | Parameters | Description |\n|-----------|------------|-------------|\n| `browser.capture_page` | - | Capture selectors from current page |\n| `browser.evaluate` | `script` | Execute JavaScript |\n\n资料来源：[packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n\n## Integration with Providers\n\nThe extension works with platform-specific browser providers for deeper integration:\n\n### GitHub Browser Provider\n\nWhen configured with `GITHUB_BROWSER_URL`, the extension can:\n\n1. Navigate to repository pages\n2. Read PR details via snapshot\n3. Review diffs by clicking \"Files changed\" tab\n4. List and filter pull requests\n5. Create issues through the web interface\n\n**Configuration:** Set `GITHUB_BROWSER_URL` in Settings > Environment Variables (e.g., `https://github.com`)\n\n**Requirements:** Must be logged into GitHub in the connected browser session\n\n资料来源：[packages/server/defaults/targets/_provider-github-browser.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/targets/_provider-github-browser.md)\n\n## Provider Preference\n\nWhen multiple integration methods exist, SideButton follows this preference order:\n\n1. **API Provider** — Fastest and most reliable\n2. **CLI Tool** — Good for git operations, builds\n3. **Browser Automation** — Universal fallback for visual tasks\n\n```mermaid\ngraph LR\n A[Task] --> B{API Available?}\n B -->|Yes| C[Use API]\n B -->|No| D{CLI Available?}\n D -->|Yes| E[Use CLI]\n D -->|No| F[Browser Automation]\n \n C -->|Browser needed| G[Browser via Extension]\n E -->|Visual review| G\n```\n\nBrowser tools complement CLI for visual tasks like:\n\n- Diff viewing\n- Board reviews\n- UI bug identification\n- Screenshot evidence\n\n资料来源：[packages/server/defaults/roles/software-engineer.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/software-engineer.md)\n\n## Smoke Test\n\nVerify extension connectivity during deployment testing:\n\n### Step 1: Server Health\n\n```\nGET http://localhost:9876/health\n```\n\nExpected response:\n```json\n{\"status\":\"ok\",\"version\":\"...\",\"browser_connected\":true}\n```\n\nIf `browser_connected: false` — stop, Chrome extension is not connected.\n\n### Step 2: Extension Connection\n\nUse `get_browser_status` tool:\n\nExpected: `{ \"connected\": true }`\n\nIf disconnected:\n1. Open Chrome\n2. Verify SideButton extension is enabled at `chrome://extensions`\n3. Refresh the page\n\n### Step 3: Snapshot Test\n\nNavigate to any page, then use `snapshot`:\n\nVerify: Returns structured YAML with element refs (ref=N), not empty, contains page elements.\n\n资料来源：[packages/server/defaults/roles/qa.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/qa.md)\n\n## Error Handling\n\nCommon extension issues and solutions:\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| `browser_connected: false` | Extension not connected | Click extension icon to connect |\n| WebSocket timeout | Server not running | Start with `pnpm dev:server` |\n| Element not found | Selector changed | Use `capture_page` to refresh selectors |\n| React input issues | Virtual DOM | Use `fill` instead of `type` |\n\n## Security Considerations\n\n- Browser extension requires significant permissions for DOM access\n- WebSocket connection is local by default\n- Remote connections should use authenticated endpoints\n- Never store credentials in workflow definitions\n\n资料来源：[AGENTS.md](https://github.com/sidebutton/sidebutton/blob/main/AGENTS.md)\n\n## Related Documentation\n\n- [MCP Tools Reference](https://docs.sidebutton.com) — Full tool documentation\n- [Workflow Engine](../core/workflow-engine.md) — Workflow execution\n- [REST API](../server/rest-api.md) — HTTP API alternative\n- [Knowledge Packs](../knowledge-packs/overview.md) — Domain-specific extensions\n\n---\n\n\n\n## Knowledge Packs\n\n### 相关页面\n\n相关主题：[MCP Server Integration](#mcp-server), [Getting Started](#getting-started)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/server/src/skill-pack.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/skill-pack.ts)\n- [packages/server/src/registry.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/registry.ts)\n- [packages/server/src/cli.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)\n- [packages/server/defaults/targets/github.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/targets/github.md)\n- [packages/server/defaults/roles/software-engineer.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/software-engineer.md)\n
\n\n# Knowledge Packs\n\nKnowledge Packs (also referred to as **Skill Packs** in CLI commands and code) are installable domain-specific modules that teach autonomous AI agents how specific web applications work. They serve as the foundational knowledge layer powering AI code review, automated testing, and enterprise AI agent deployments.\n\n## Overview\n\nKnowledge Packs provide structured, domain-specific intelligence to the SideButton platform. Rather than requiring AI agents to learn from scratch how to interact with each web application, Knowledge Packs pre-package essential information that enables immediate, accurate automation.\n\nThe SideButton registry currently hosts **11 domains** with **28+ modules** published, and maintains an open registry where anyone can build and share packs for any web application.\n\n资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n## Pack Components\n\nEach Knowledge Pack comprises five core module types that together provide comprehensive domain understanding:\n\n| Component | Description | Purpose |\n|-----------|-------------|---------|\n| **Selectors** | CSS selectors for UI elements | Precise DOM element targeting without pixel coordinates or screenshots |\n| **Data Models** | Entity types, fields, relationships, valid states | Structured understanding of domain objects |\n| **State Machines** | Valid transitions per state | Predictable, safe workflow execution |\n| **Role Playbooks** | Role-specific procedures (QA, SE, PM, SD) | Context-aware guidance for different user roles |\n| **Common Tasks** | Step-by-step procedures, gotchas, edge cases | Handling typical operations with best practices |\n\n资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n### Selector Modules\n\nSelectors provide CSS-based targeting for browser automation, ensuring reliability across different browsers and viewport sizes. Unlike coordinate-based or screenshot-based approaches, CSS selectors remain stable as long as the application's DOM structure is maintained.\n\n### Role Playbooks\n\nRole playbooks define standard operating procedures for specific personas. For example, the `software-engineer` role includes:\n\n- Decision guidance for issue prioritization\n- Step types for common development tasks\n- Integration patterns for git, issues, chat, and terminal operations\n\n资料来源：[packages/server/defaults/roles/software-engineer.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/defaults/roles/software-engineer.md)\n\n## Architecture\n\n```mermaid\ngraph TD\n A[User/Agent] -->|sidebutton install| B[CLI]\n B --> C{Source Type}\n C -->|Local Path| D[Local Directory]\n C -->|Git URL| E[Git Repository]\n C -->|Registry Name| F[SideButton Registry]\n \n D --> G[Install Skill Pack]\n E --> G\n F --> H[Fetch from Registry API]\n H --> G\n \n G --> I[Parse Manifest]\n I --> J[Copy to ~/.sidebutton/packs/]\n J --> K[Knowledge Pack Active]\n \n L[Workflow Engine] -->|Uses| K\n M[MCP Tools] -->|Reads| K\n```\n\n## Installation Methods\n\nKnowledge Packs can be installed from multiple sources:\n\n| Source Type | Command Example | Use Case |\n|-------------|-----------------|----------|\n| Local directory | `sidebutton install ./my-pack` | Development and testing |\n| Git URL | `sidebutton install https://github.com/org/skill-packs` | Remote repositories |\n| Registry name | `sidebutton install github.com` | Published registry packs |\n\n```bash\n# Install from registry\nsidebutton install github.com\nsidebutton install atlassian.net\n\n# Install from local path\nsidebutton install ./custom-pack\n\n# Install from Git URL\nsidebutton install https://github.com/org/skill-packs\n\n# Force reinstall\nsidebutton install github.com --force\n```\n\n资料来源：[packages/server/src/cli.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)\n\n## Registry Management\n\nThe registry system allows centralized distribution and discovery of Knowledge Packs.\n\n### Registry CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `sidebutton registry add ` | Register and install all packs from a registry |\n| `sidebutton registry update [name]` | Update installed packs from registry |\n| `sidebutton registry remove ` | Uninstall packs and remove registry |\n| `sidebutton registry list` | Show registries and pack counts |\n| `sidebutton search [query]` | Search packs across registries |\n\n资料来源：[packages/server/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/server/README.md)\n\n### Registry Configuration\n\nRegistries are stored in the SideButton configuration directory (`~/.sidebutton/registries.json`) and contain metadata about available skill pack sources.\n\n## Publishing Knowledge Packs\n\n### Publishing Process\n\n1. **Initialize** a new pack using `sidebutton init [domain]`\n2. **Develop** the pack with manifest and modules\n3. **Validate** using `sidebutton validate [path]`\n4. **Authenticate** with `sidebutton login`\n5. **Publish** via `sidebutton publish`\n\n### Manifest Structure\n\nThe `manifest.json` defines the pack's metadata:\n\n```json\n{\n \"domain\": \"github.com\",\n \"title\": \"GitHub\",\n \"version\": \"1.0.0\",\n \"description\": \"GitHub integration for AI agents\",\n \"tagline\": \"Streamlined GitHub workflows\",\n \"category\": \"development\",\n \"modules\": [\"selectors\", \"data-models\", \"state-machines\"],\n \"roles\": [\"software-engineer\", \"qa\"]\n}\n```\n\n资料来源：[packages/server/src/cli.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)\n\n### Publishing Endpoint\n\n```typescript\nconst res = await fetch(`${REMOTE_BASE_URL}/api/skill-packs/publish`, {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n 'Authorization': `Bearer ${auth.token}`,\n },\n body: JSON.stringify({\n domain: manifest.domain,\n name: manifest.title || manifest.name || manifest.domain,\n version: manifest.version,\n description: manifest.description || '',\n tagline: manifest.tagline || '',\n modules: manifest.modules || [],\n roles: manifest.roles || [],\n category: manifest.category || '',\n manifest,\n files,\n }),\n});\n```\n\n资料来源：[packages/server/src/cli.ts](https://github.com/sidebutton/sidebutton/blob/main/packages/server/src/cli.ts)\n\n## Integration with Workflow Engine\n\nKnowledge Packs integrate with the core SideButton workflow engine through step types that reference pack-specific configurations:\n\n```mermaid\ngraph LR\n A[Knowledge Pack] --> B[Step Type Resolution]\n B --> C[Provider Selection]\n C --> D[Git Provider]\n C --> E[Issues Provider]\n C --> F[Chat Provider]\n C --> G[Browser Provider]\n```\n\n### Available Step Types\n\n| Category | Steps |\n|----------|-------|\n| Browser | `navigate`, `click`, `type`, `scroll`, `hover`, `wait`, `extract`, `extractAll`, `exists`, `key` |\n| Shell | `shell.run`, `terminal.open`, `terminal.run` |\n| LLM | `llm.classify`, `llm.generate` |\n| Control | `control.if`, `control.retry`, `control.stop`, `workflow.call` |\n| Data | `data.first` |\n| Git | `git.listPRs`, `git.getPR`, `git.createPR`, `git.listIssues`, `git.getIssue` |\n| Issues | `issues.search`, `issues.get`, `issues.create`, `issues.transition`, `issues.comment` |\n| Chat | `chat.readChannel`, `chat.readThread`, `chat.listChannels` |\n\n资料来源：[packages/core/README.md](https://github.com/sidebutton/sidebutton/blob/main/packages/core/README.md)\n\n## Development Workflow\n\n### Creating a New Pack\n\n```bash\n# Initialize a new knowledge pack\nsidebutton init my-app.com\n\n# Scaffolded structure:\n# my-app.com/\n# ├── manifest.json\n# ├── modules/\n# │ ├── selectors/\n# │ ├── data-models/\n# │ └── state-machines/\n# ├── roles/\n# │ └── software-engineer.md\n# └── targets/\n# └── github.md\n```\n\n### Validation\n\nBefore publishing, validate the pack structure:\n\n```bash\nsidebutton validate ./my-app.com\n```\n\nThis command lints and checks:\n- Manifest completeness\n- Module structure validity\n- Selector syntax correctness\n- File integrity\n\n## Configuration Locations\n\n| Path | Purpose |\n|------|---------|\n| `~/.sidebutton/packs/` | Installed Knowledge Pack directories |\n| `~/.sidebutton/registries.json` | Registry configurations |\n| `~/.sidebutton/config.json` | Main SideButton configuration |\n\n## Best Practices\n\n1. **Selector Stability**: Use semantic CSS selectors that won't change with visual updates\n2. **Versioning**: Follow semantic versioning for pack updates\n3. **Error Handling**: Include edge case documentation in Common Tasks\n4. **Role Coverage**: Provide at least one role playbook for each major user persona\n5. **State Documentation**: Clearly define all valid state transitions\n\n## Available Packs\n\nThe SideButton registry includes Knowledge Packs for popular platforms:\n\n| Domain | Category | Modules |\n|--------|----------|---------|\n| github.com | Development | Selectors, Data Models, SE Role |\n| atlassian.net | Development | Selectors, Data Models |\n| *(10 more domains)* | Various | Various |\n\n资料来源：[README.md](https://github.com/sidebutton/sidebutton/blob/main/README.md)\n\n## See Also\n\n- [Core Workflow Engine](../core/README.md) - `@sidebutton/core` package\n- [MCP Server](../server/README.md) - `@sidebutton/server` package with REST API\n- [Chrome Extension](../extension/README.md) - Browser extension integration\n- [Full Documentation](https://docs.sidebutton.com)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：sidebutton/sidebutton\n\n摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Add control.foreach step type for iterating over lists。\n\n## 1. 安装坑 · 来源证据：Add control.foreach step type for iterating over lists\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add control.foreach step type for iterating over lists\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d7567e53b1794e828bb3342cb0699f6f | https://github.com/sidebutton/sidebutton/issues/1 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 来源证据：Native elements cannot be programmatically selected via click/type tools\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a2eadefee45c45b2be1b8501c1a0724f | https://github.com/sidebutton/sidebutton/issues/12 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 8. 安全/权限坑 · 来源证据：v1.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a9cfb55ebc664ee99dcc39773859d715 | https://github.com/sidebutton/sidebutton/releases/tag/v1.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | issue_or_pr_quality=unknown\n\n## 10. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | release_recency=unknown\n\n\n", "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "Human Manual / 人类版说明书" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log / 踩坑日志\n\n项目：sidebutton/sidebutton\n\n摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Add control.foreach step type for iterating over lists。\n\n## 1. 安装坑 · 来源证据：Add control.foreach step type for iterating over lists\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add control.foreach step type for iterating over lists\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d7567e53b1794e828bb3342cb0699f6f | https://github.com/sidebutton/sidebutton/issues/1 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 来源证据：Native elements cannot be programmatically selected via click/type tools\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a2eadefee45c45b2be1b8501c1a0724f | https://github.com/sidebutton/sidebutton/issues/12 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 8. 安全/权限坑 · 来源证据：v1.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a9cfb55ebc664ee99dcc39773859d715 | https://github.com/sidebutton/sidebutton/releases/tag/v1.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | issue_or_pr_quality=unknown\n\n## 10. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1124378210 | https://github.com/sidebutton/sidebutton | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# sidebutton - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for sidebutton/sidebutton.\n\nProject:\n- Name: sidebutton\n- Repository: https://github.com/sidebutton/sidebutton\n- Summary: Open-source browser automation for AI agents. MCP server + Chrome extension + YAML workflow engine + knowledge packs. Give your AI agent a browser and domain expertise.\n- Host target: mcp_host\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Open-source browser automation for AI agents. MCP server + Chrome extension + YAML workflow engine + knowledge packs. Give your AI agent a browser and domain expertise.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Open-source browser automation for AI agents. MCP server + Chrome extension + YAML workflow engine + knowledge packs. Give your AI agent a browser and domain expertise.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. introduction: Introduction to SideButton. Produce one small intermediate artifact and wait for confirmation.\n2. getting-started: Getting Started. Produce one small intermediate artifact and wait for confirmation.\n3. architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. workflow-engine: Workflow Engine. Produce one small intermediate artifact and wait for confirmation.\n5. step-types: Step Types Reference. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/sidebutton/sidebutton\n- https://github.com/sidebutton/sidebutton#readme\n- README.md\n- LICENSING.md\n- SECURITY.md\n- package.json\n- packages/server/README.md\n- packages/sidebutton/README.md\n- packages/server/src/server.ts\n- packages/core/src/executor.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：sidebutton/sidebutton\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx sidebutton@latest\n```\n\n来源：https://github.com/sidebutton/sidebutton#readme\n\n## 来源\n\n- repo: https://github.com/sidebutton/sidebutton\n- docs: https://github.com/sidebutton/sidebutton#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_a42593613c7b4563b6a4c76feea2c96f" }