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