Doramagic 项目包 · 项目说明书
browserable 项目
面向 AI 智能体的开源、可自托管的浏览器自动化库
项目概览与系统架构
Browserable 是一个面向 AI Agent 的开源浏览器自动化库,旨在帮助开发者构建能够在真实网站中导航、填写表单、点击按钮并提取结构化信息的浏览器代理。官方数据表明,该项目在 Web Voyager 基准测试上已达到 90.4% 的通过率 资料来源:[README.md:9-11]()。本仓库同时提供管理后台、任务调度服务、远程浏览器服务与 JavaScript...
继续阅读本节完整说明和来源证据。
Browserable 是一个面向 AI Agent 的开源浏览器自动化库,旨在帮助开发者构建能够在真实网站中导航、填写表单、点击按钮并提取结构化信息的浏览器代理。官方数据表明,该项目在 Web Voyager 基准测试上已达到 90.4% 的通过率 资料来源:README.md:9-11。本仓库同时提供管理后台、任务调度服务、远程浏览器服务与 JavaScript SDK,构成一套端到端的"代理化浏览器"解决方案 资料来源:README.md:1-30。
定位与核心能力
项目的核心定位是"为 AI 代理提供可编程的浏览器" 资料来源:README.md:7-13。在实现层面,Browserable 暴露了四种原子能力:打开新标签页(open_new_tab)、读取标签页(read_tab)、在标签页上执行操作(act_on_tab)以及从标签页中提取内容(extract_from_tab)。复杂任务都可以通过这四种能力的组合来表达 资料来源:tasks/agents/browserable.js:1-50。
为了让代理能够"看见"网页,Browserable 同时使用文本/DOM 渲染与截图两种通道。LLM 在收到图像后会优先基于图像理解页面,再与 DOM 元素进行对照决策 资料来源:tasks/prompts/agents/browserable/actionPrompts.js:1-30。当网页较长时,系统会按块(chunk)滚动页面,循环调用提取流程并合并多次结果,最终输出符合用户自定义 schema 的结构化数据 资料来源:tasks/agents/browserable.js:100-200。
系统架构
项目主要由三个独立的服务组成:管理后台 UI、任务调度与代理执行服务(tasks)、远程浏览器服务(browser)。三者通过 Docker Compose 在本地编排启动,统一监听在 http://localhost:2001 资料来源:README.md:15-30。
flowchart LR
User[用户] --> AdminUI[Admin UI<br/>ui/*]
AdminUI -->|REST / SDK| TasksService[Tasks Service<br/>tasks/*]
TasksService -->|CDP| BrowserService[Browser Service<br/>browser/*]
TasksService -->|OpenAI 兼容协议| LLM[LLM Provider]
SDK[JS SDK<br/>sdk/browserable-js] -->|HTTP| TasksServicetasks 服务内部由"代理"(Agent)构成,代理以节点(Node)形式在流程(Flow)中执行。每个代理都继承自 BaseAgent,并通过 jarvis.endNode 与 jarvis.errorAtNode 等方法向编排层汇报生命周期状态 资料来源:tasks/agents/base.js:1-60。其中 Jarvis 是顶层编排代理,负责子任务拆分、消息日志聚合与结果表处理;代理在决策时会通过 work_on_subtask_before_deciding 等动作码控制执行节奏 资料来源:tasks/agents/jarvis.js:1-50。管理端 UI 通过 FlowContainer 把代理运行过程中产生的文本、Markdown、图片与代码片段渲染成可折叠的对话流 资料来源:ui/src/containers/FlowContainer.jsx:1-40。对外,JS SDK 暴露 BrowserableConfig、Task、TaskRun、TaskRunStatus 等类型,并支持 pollInterval、timeout 与 onStatusChange 回调,简化客户端轮询 资料来源:sdk/browserable-js/src/types.ts:1-60。
LLM 兼容性与社区关注点
默认支持 OpenAI 兼容协议,Tasks 服务在多模型之间按顺序回退,候选列表包括 gemini-2.0-flash、deepseek-chat、gpt-4o-mini、claude-3-5-haiku 与 qwen-plus 资料来源:tasks/agents/browserable.js:50-80。社区中关于 Groq 与 OpenRouter 的支持已被列入路线图(issue #5),Ollama 等本地 LLM 的支持也在持续讨论中(issue #9);目前若希望切换到非 OpenAI 提供方,需手动将 https://api.openai.com/v1/chat/completions 替换为对应提供方的兼容 URL(issue #3 维护者回复)。
启动方式上,npx browserable 是一键入口,但部分使用 fnm 的用户在 Ubuntu/WSL 环境下会遇到 /usr/bin/env: 'node --no-warnings': No such file or directory 错误(issue #20),此时可改用 git clone + docker-compose -f docker-compose.dev.yml up 的手动方式 资料来源:README.md:23-30。若管理后台一直停留在 "Initial setup is in progress" 提示(issue #6),通常意味着 tasks 容器未健康启动,可通过 docker ps 检查容器状态并查看对应日志进行排查。
See Also
- 官方文档:https://docs.browserable.ai — REST API、JS SDK、Custom Functions 与 Troubleshooting 详细说明
- Web Voyager 基准(issue #17) — 与项目宣传中 90.4% 通过率对应的发布博客进度跟踪
- Public Roadmap(issue #7) — 通过 GitHub Issues 维护的 1:1 公开路线图
来源:https://github.com/browserable/browserable / 项目说明书
核心功能与浏览器代理系统
Browserable 的核心是一个浏览器代理系统,由 Browserable Agent、Base Agent 与 Jarvis 三大模块协作完成"代替用户在浏览器内完成任务"的使命。Browserable Agent 的 CODE 与 DETAILS 明确描述其作用:提供可在浏览器中代替用户执行点击、输入、抽取等操作的智能体,并通过远程浏览器会话与 Playwright...
继续阅读本节完整说明和来源证据。
继续阅读本节完整说明和来源证据。
继续阅读本节完整说明和来源证据。
继续阅读本节完整说明和来源证据。
一、目标与定位
Browserable 的核心是一个浏览器代理系统,由 Browserable Agent、Base Agent 与 Jarvis 三大模块协作完成"代替用户在浏览器内完成任务"的使命。Browserable Agent 的 CODE 与 DETAILS 明确描述其作用:提供可在浏览器中代替用户执行点击、输入、抽取等操作的智能体,并通过远程浏览器会话与 Playwright 完成实际交互 资料来源:tasks/agents/browserable.js。
当用户明确要求"在浏览器里完成某事"时,系统会优先选用浏览器代理;当存在更专用的 Agent(如 Google Sheets Agent)时,应使用专用 Agent 代替 资料来源:tasks/agents/browserable.js。
二、代理分层架构
2.1 BaseAgent 基类
BaseAgent 定义了 Agent 的生命周期:_action_end 负责汇总 reasoning 与 output 并调用 jarvis.endNode() 结束节点;_action_irrecoverable_error 则把错误日志写入 user/debug log 并调用 jarvis.errorAtNode() 终结节点 资料来源:tasks/agents/base.js。
2.2 Browserable Agent
继承自 BaseAgent,其 this.CODE = "BROWSER_AGENT"。它使用四种基础动作:open_new_tab、read_tab、act_on_tab、extract_from_tab,理论上能完成任何网站交互 资料来源:tasks/agents/browserable.js。
2.3 Jarvis 协调器
Jarvis 是任务调度与上下文管理中枢。它通过 convertMessageLogsToLLMFormat 从 browserable.message_logs 表按 run_id、node_id、thread_id 维度回捞历史消息,向 LLM 提供统一上下文 资料来源:tasks/agents/jarvis.js。
flowchart LR
User[用户任务] --> Jarvis
Jarvis -->|调度| BrowserAgent[Browserable Agent]
BrowserAgent -->|open_new_tab| Playwright[Playwright/Steel SDK]
BrowserAgent -->|act_on_tab| Playwright
BrowserAgent -->|extract_from_tab| LLM
LLM -->|多模型回退| BrowserAgent
BrowserAgent --> Jarvis
Jarvis --> RichOutput[richOutputPrompt 汇总]
RichOutput --> User三、关键工作流
3.1 打开标签页与截图
执行 open_new_tab 时,Agent 调用 browserService.getPlaywrightBrowser() 获取 Playwright 会话,并通过 screenshotHelper 抓取截图存入运行私有数据;随后立即调用 waitForSettledDom(page) 与 debugDom(page) 等待 DOM 稳定 资料来源:tasks/agents/browserable.js。截图通过 imageUrl 与 privateImageUrl 暴露给下游 LLM,便于多模态决策。
3.2 内容抽取与分块合并
extractPrompts.js 中的 buildExtractLLMPrompt 提供两种模式:useTextExtract=true 时基于文本化网页,false 时基于 DOM 元素列表。系统提示词强制要求"不要假设、不要幻觉",并要求输出 justification 与 extractedContent 字段 资料来源:tasks/prompts/agents/browserable/extractPrompts.js。
抽取按"分块滚动"方式循环:每次滚动到新 chunk 后截图并请求 LLM,再调用 buildRefineExtractedContentPrompt 合并 previouslyExtractedContent 与新内容,去重数组、扩展文本、更新数值字段 资料来源:tasks/agents/browserable.js 与 tasks/prompts/agents/browserable/extractPrompts.js。
3.3 行为决策
actionPrompts.js 定义三类动作:doAction(执行点击、输入等)、skipSection(跳过无法在此完成的部分)、actionCompleted(标记完成)。当附图时,提示词明确要求"以图像为主、DOM 为辅"进行判断 资料来源:tasks/prompts/agents/browserable/actionPrompts.js。actionExtractLLMHelper 内置的"下拉框需先键入再选择"等 SPECIAL ELEMENTS 规则体现了对真实网站交互细节的考虑 资料来源:tasks/agents/browserable.js。
四、LLM 多模型与失败兜底
callOpenAICompatibleLLMWithRetry 内置一组回退模型:gemini-2.0-flash、deepseek-chat、gpt-4o-mini、claude-3-5-haiku、qwen-plus,max_attempts=3,按列表顺序尝试以保证可用性 资料来源:tasks/agents/browserable.js。
需要替换 OpenAI 时,可在社区指引下将 OpenAI 兼容 URL 切换为 Groq 等第三方端点;本地 LLM(如 Ollama)支持尚未内置进 Admin UI 资料来源:issues/9、issues/3、issues/5。
五、SDK 与对外契约
browserable-js 通过 CreateTaskOptions、Task、TaskRunStatus 等 TypeScript 类型对外暴露运行生命周期;TaskRunStatus 状态枚举为 scheduled | running | completed | error,TaskRunResult 增加 output 与 dataTable 字段 资料来源:sdk/browserable-js/src/types.ts。WaitForRunOptions 默认 1 秒轮询、5 分钟超时,便于在 JS 端稳定等待 run 完成。
六、汇总输出与社区已知问题
任务收尾时,richOutputPrompt 按 outputData 模板逐字段累计 outputGenerated,并以 4000 词为上限强制截断 资料来源:tasks/prompts/agents/jarvis/richOutputPrompt.js。后端依赖 Playwright、steel-sdk、sharp 等图形与浏览器栈 资料来源:tasks/package.json。
常见故障包括:首次安装 Initial Setup 卡住,多为 tasks 服务未启动(docker ps 检查);npx browserable 在 fnm 多 shell 场景下出现 node --no-warnings shebang 错误 资料来源:issues/6、issues/20。截图、任务 GIF、日志 API 已在路线图中陆续上线 资料来源:issues/13、issues/14、issues/12。
See Also
- 浏览器自动化与 Playwright 集成
- Jarvis 任务调度与消息日志
- LLM 多模型回退与本地化
- browserable-js SDK 使用指南
来源:https://github.com/browserable/browserable / 项目说明书
REST API、JS SDK 与 CLI 使用指南
Browserable 是一个开源、可自托管的浏览器自动化平台,提供三层对外接口:REST API、JavaScript/TypeScript SDK(browserable-js)以及 npx browserable CLI。三个接口最终都对接同一个后端任务服务(tasks),用户可以根据使用场景选择最合适的入口。
继续阅读本节完整说明和来源证据。
继续阅读本节完整说明和来源证据。
继续阅读本节完整说明和来源证据。
继续阅读本节完整说明和来源证据。
一、概述与定位
Browserable 是一个开源、可自托管的浏览器自动化平台,提供三层对外接口:REST API、JavaScript/TypeScript SDK(browserable-js)以及 npx browserable CLI。三个接口最终都对接同一个后端任务服务(tasks),用户可以根据使用场景选择最合适的入口。
- REST API:HTTP 接口,适合任意语言或无语言偏好的服务端集成;官方文档为
https://docs.browserable.ai/rest-api/introduction。 - JS SDK:基于
axios封装的 TypeScript 包,包名为browserable-js(sdk/browserable-js/package.json)。 - CLI:
npx browserable命令行入口,用于一键拉起本地 Docker 部署。
资料来源:README.md、sdk/browserable-js/package.json:1-30
二、JS SDK 使用详解
browserable-js 通过 Browserable 类暴露所有方法,初始化时需要 apiKey,可选 baseURL(默认 https://api.browserable.ai/api/v1)。
import { Browserable } from 'browserable-js';
const browserable = new Browserable({
apiKey: 'your-api-key',
// baseURL: 'http://localhost:2003/api/v1' // 本地自托管示例
});
核心方法
| 方法 | 用途 | 关键参数 |
|---|---|---|
createTask | 创建任务 | task: string,可选 agent |
listTasks | 分页列出任务 | page, limit |
getTaskRunStatus | 查询运行状态 | taskId, runId? |
getTaskRunResult | 获取运行结果 | taskId, runId? |
stopRun | 停止运行 | taskId, runId? |
资料来源:sdk/browserable-js/README.md:1-60、sdk/browserable-js/src/types.ts:1-90
类型与状态机
任务状态在 Task.status 中定义为 'active' | 'inactive';任务运行状态在 TaskRunStatus.status 中定义为 'scheduled' | 'running' | 'completed' | 'error'。运行结果可能附带 output 与结构化的 dataTable,用于二次处理。轮询工具 waitForRun 接受 pollInterval(默认 1000ms)、timeout(默认 300000ms)和 onStatusChange 回调。
资料来源:sdk/browserable-js/src/types.ts:18-80
端到端示例
sdk/examples/js-sdk-test 演示了调用流程:先获取用户档案,再列出可用浏览器,最后创建浏览器会话。该示例默认指向本地 http://localhost:2003/api/v1,便于在自托管环境下联调。
cd sdk/examples/js-sdk-test
npm install
npm test
资料来源:sdk/examples/js-sdk-test/README.md:1-30、sdk/examples/js-sdk-test/package.json:1-18
三、REST API 与后端任务流
REST API 端点的请求/响应模型与 SDK 保持一致,均遵循 ApiResponse<T> 统一结构(success + data + error + 分页字段)。从后端代码看,任务执行由 tasks/agents/browserable.js 中的 BrowserAgent 驱动,浏览器操作以工具调用(open_new_tab、read_tab、act_on_tab、extract_from_tab)的形式编排,每次操作都会向 jarvis 写入节点日志(updateNodeUserLog / updateNodeAgentLog / updateNodeDebugLog)。
sequenceDiagram
participant Client as 客户端(SDK/CLI/cURL)
participant API as REST API
participant Tasks as tasks 服务
participant Browser as 远程浏览器
Client->>API: createTask / 触发器
API->>Tasks: 调度 run
Tasks->>Browser: 工具调用(open/read/act/extract)
Browser-->>Tasks: 页面/截图
Tasks-->>API: 更新 status / output
Client->>API: getTaskRunStatus / getTaskRunResult
API-->>Client: ApiResponse<T>社区已规划但尚未完全交付的端点包括 task-run-gif(GIF 回放)、screenshots、logs 等(见 Issue #13、#14、#12),使用前请先确认官方 REST 文档是否已上线对应接口。
资料来源:tasks/agents/browserable.js:1-120、tasks/agents/base.js:1-90、sdk/browserable-js/src/types.ts:60-80
四、CLI 安装与常见问题
CLI 入口为 npx browserable,由 Issue #8 跟踪的命令行能力(--help、down 等)已合入 1.0.13。常见使用步骤:
npx browserable启动本地 Docker Compose 栈;- 等待
Initial setup is in progress提示消失; - 通过
http://localhost:2003访问管理 UI,复制 API Key 用于 SDK/REST 集成。
常见故障
/usr/bin/env: 'node --no-warnings': No such file or directory:出现在 Ubuntu/WSL 等使用fnm多 shell 的环境,原因是 shebang 中node解析失败(Issue #20)。临时方案:在普通终端(非fnm_multishells)下运行npx browserable,或将 Node 路径加入/usr/bin/env查找列表。- 初始化卡在 “reload this page in a minute”:通常是后端
tasks容器未健康启动。先执行docker ps检查browserable_tasks状态,再docker exec -it browserable_tasks sh查看日志(Issue #6)。 - 想使用非 OpenAI 提供方(Groq / OpenRouter / Ollama):当前 Admin UI 与 Docker Compose 未直接支持,需要在代码中替换
https://api.openai.com/v1/chat/completions为兼容端点(Issue #3、#5、#9)。ui/src/containers/SettingsContainer.jsx中的userApiKeys仅识别openai/claude/gemini,新增提供方需要扩展该表单。
资料来源:ui/src/containers/SettingsContainer.jsx:1-60、README.md、tasks/package.json:1-30
参见
部署、自托管、扩展与故障排查
本文面向希望自行部署、扩展或排查浏览器自动化平台 Browserable 的工程师与运维人员。Browserable 是一个由多个协同 Agent 组成的浏览器任务执行系统,包含任务调度 (tasks)、管理员界面 (ui) 与官方 JavaScript SDK (sdk/browserable-js)。本页围绕部署架构、安装流程、扩展点与常见故障展开,所有结论均基于仓库源...
继续阅读本节完整说明和来源证据。
继续阅读本节完整说明和来源证据。
继续阅读本节完整说明和来源证据。
继续阅读本节完整说明和来源证据。
本文面向希望自行部署、扩展或排查浏览器自动化平台 Browserable 的工程师与运维人员。Browserable 是一个由多个协同 Agent 组成的浏览器任务执行系统,包含任务调度 (tasks)、管理员界面 (ui) 与官方 JavaScript SDK (sdk/browserable-js)。本页围绕部署架构、安装流程、扩展点与常见故障展开,所有结论均基于仓库源码与社区讨论记录。
一、部署架构概览
Browserable 通过 Docker Compose 启动一组协同服务,核心组件包括后端任务服务、数据库与本地浏览器运行时。任务服务通过 pg、redis、playwright、steel-sdk 等依赖与外部世界交互,分别承担持久化、队列调度、浏览器自动化与远程浏览器连接等职责 资料来源:tasks/package.json:1-30。
后端任务服务通过 browserable PostgreSQL schema 存储运行日志,典型的查询会写入 browserable.message_logs 表,字段涵盖 run_id、node_id、thread_id、segment、messages 与 created_at,分别用于标识运行、节点、线程、消息段、消息内容与时间戳 资料来源:tasks/agents/jarvis.js:1-50。运行时还会调用 isRunActive、updateNodeLiveStatus、scheduleQueueJob 等函数来判断运行是否仍然有效,并在 Agent 节点结束时通过 endNode、errorAtNode 更新状态 资料来源:tasks/agents/base.js:1-80。
flowchart LR
A[npx browserable / Docker] --> B[tasks 服务]
B --> C[PostgreSQL<br/>browserable schema]
B --> D[Redis 队列]
B --> E[Playwright 浏览器]
B --> F[Steel SDK 远程浏览器]
B --> G[OpenAI 兼容 LLM]
B --> H[ui 管理后台]
H --> I[JS SDK / REST API]部署时各组件以容器方式运行,管理员通过 Web UI 提交任务,JS SDK 或 REST API 触发任务运行;任务节点在完成后将状态写回数据库并通过 WebSocket/轮询向前端反馈 资料来源:sdk/browserable-js/src/types.ts:1-60。
二、自托管安装流程
社区文档推荐的安装方式为 npx browserable,该命令会拉取并启动所需的 Docker 容器。1.0.13 版本起,npx browserable 增加了 --help 与 down 等子命令,用于查看帮助与停止所有服务 资料来源:issue #8。
安装步骤大致为:
- 在主机上安装 Node.js(建议使用 LTS 版本)与 Docker Engine;
- 执行
npx browserable拉起tasks、ui等容器; - 通过浏览器访问
ui容器暴露的端口,使用 OpenAI 兼容 LLM 的 API Key 完成初始配置; - 等待"Initial setup is in progress. Please reload this page in a minute." 提示消失即代表后端任务服务就绪 资料来源:issue #6。
值得注意的是,部分用户在 WSL/Ubuntu 环境下执行 npx browserable 会遇到 /usr/bin/env: ‘node --no-warnings’: No such file or directory 错误,根因是 fnm/nvm 等工具的临时 shell 目录未进入 PATH,需要在普通 shell 中执行,或将 Node 装入系统级路径 资料来源:issue #20。
三、扩展能力
3.1 LLM 提供商
Browserable 默认通过 OpenAI 兼容接口调用大模型,源码中可见 callOpenAICompatibleLLMWithRetry 这一通用入口,其 models 数组按顺序回退尝试 gemini-2.0-flash、deepseek-chat、gpt-4o-mini、claude-3-5-haiku、qwen-plus 等多种模型 资料来源:tasks/agents/browserable.js:1-60。该设计天然支持任意 OpenAI 兼容服务,社区已验证通过替换 https://api.openai.com/v1/chat/completions 为 Groq 端点即可临时启用 Groq 资料来源:issue #3。
| 能力 | 状态 | 备注 |
|---|---|---|
| OpenAI 兼容多模型回退 | 已上线 | 见 callOpenAICompatibleLLMWithRetry |
| Groq 直连 | 实验性 | 需手动替换请求端点 |
| OpenRouter | 计划中 | 见 issue #5 |
| 本地 LLM(Ollama) | 计划中 | 见 issue #9 |
3.2 自定义工具与本地浏览器
用户可通过自定义函数(custom functions)扩展 Agent 能力,V1 版本已上线相关接口 资料来源:issue #10。同时,BROWSER_AGENT 类提供 open_new_tab、read_tab、act_on_tab、extract_from_tab 四类核心动作,并在执行过程中调用 browserService.getPlaywrightBrowser 申请浏览器会话,支持本地浏览器会话与远程会话两种模式 资料来源:tasks/agents/browserable.js:60-140。
3.3 SDK 与 REST API
官方 JavaScript SDK 暴露 CreateTaskOptions、TaskRunStatus、TaskRunResult 等类型,运行状态枚举为 scheduled | running | completed | error,并提供 WaitForRunOptions 用于轮询与超时控制 资料来源:sdk/browserable-js/src/types.ts:1-60。后台还可生成任务运行 GIF(TaskRunGifResult,枚举为 pending | error | completed),用于可视化浏览器交互过程 资料来源:issue #13。
四、故障排查
4.1 后端服务未启动
若管理界面长时间停留在 "Initial setup is in progress",通常意味着 tasks 服务未就绪。建议执行:
docker ps # 检查 tasks 容器是否 unhealthy
docker exec -it browserable ... # 进入容器查看日志
若容器处于重启循环,可结合 updateNodeDebugLog 中的错误信息进一步定位 资料来源:issue #6 与 tasks/agents/base.js:40-80。
4.2 npx 启动失败
如遇 shebang 解析错误 /usr/bin/env: ‘node --no-warnings’: No such file or directory,说明 Node 可执行文件未在当前 PATH 中。可在常规 shell(非 fnm 多 shell 临时环境)重新执行 资料来源:issue #20。
4.3 Agent 节点错误
Agent 在执行过程中若发生不可恢复异常,会通过 errorAtNode 将错误上报,并将状态写入 browserable.message_logs 表,便于后续审计。BaseAgent 的 _action_end 与错误处理分支展示了完整的成功/失败生命周期 资料来源:tasks/agents/base.js:1-80。
4.4 LLM 调用失败
由于多模型回退机制的存在,单一模型失败通常不会中断任务;建议在自托管环境中预先在管理面板配置至少两个 OpenAI 兼容提供方(如 OpenAI + 自托管网关),以提高稳定性 资料来源:tasks/agents/browserable.js:1-60。
更多排障手册可参考官方 troubleshooting 文档 资料来源:issue #15。
See Also
- 浏览器 Agent 内部动作与抽取流程:tasks/agents/browserable.js
- 抽取内容合并与去重策略:tasks/prompts/agents/browserable/extractPrompts.js
- 任务调度与日志持久化:tasks/agents/jarvis.js
- JS SDK 类型定义:sdk/browserable-js/src/types.ts
来源:https://github.com/browserable/browserable / 项目说明书
失败模式与踩坑日记
保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险,不把社区讨论只当作装饰信息。
可能增加新用户试用和生产接入成本。
安装可能改变本机 AI 工具行为,用户需要知道写入位置和回滚方法。
假设不成立时,用户拿不到承诺的能力。
新项目、停更项目和活跃项目会被混在一起,推荐信任度下降。
Pitfall Log / 踩坑日志
项目:browserable/browserable
摘要:发现 8 个潜在踩坑项,其中 0 个为 high/blocking;最高优先级:安装坑 - 来源证据:npx browserable returns error /usr/bin/env: ‘node --no-warnings’: No such file or directory。
1. 安装坑 · 来源证据:npx browserable returns error `/usr/bin/env: ‘node --no-warnings’: No such file or directory`
- 严重度:medium
- 证据强度:source_linked
- 发现:GitHub 社区证据显示该项目存在一个安装相关的待验证问题:npx browserable returns error
/usr/bin/env: ‘node --no-warnings’: No such file or directory - 对用户的影响:可能增加新用户试用和生产接入成本。
- 证据:community_evidence:github | https://github.com/browserable/browserable/issues/20 | 来源讨论提到 node 相关条件,需在安装/试用前复核。
2. 配置坑 · 可能修改宿主 AI 配置
- 严重度:medium
- 证据强度:source_linked
- 发现:项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主,或安装命令涉及用户配置目录。
- 对用户的影响:安装可能改变本机 AI 工具行为,用户需要知道写入位置和回滚方法。
- 证据:capability.host_targets | https://github.com/browserable/browserable | host_targets=claude
3. 能力坑 · 能力判断依赖假设
- 严重度:medium
- 证据强度:source_linked
- 发现:README/documentation is current enough for a first validation pass.
- 对用户的影响:假设不成立时,用户拿不到承诺的能力。
- 证据:capability.assumptions | https://github.com/browserable/browserable | README/documentation is current enough for a first validation pass.
4. 维护坑 · 维护活跃度未知
- 严重度:medium
- 证据强度:source_linked
- 发现:未记录 last_activity_observed。
- 对用户的影响:新项目、停更项目和活跃项目会被混在一起,推荐信任度下降。
- 证据:evidence.maintainer_signals | https://github.com/browserable/browserable | last_activity_observed missing
- 严重度:medium
- 证据强度:source_linked
- 发现:no_demo
- 证据:downstream_validation.risk_items | https://github.com/browserable/browserable | no_demo; severity=medium
6. 安全/权限坑 · 存在评分风险
- 严重度:medium
- 证据强度:source_linked
- 发现:no_demo
- 对用户的影响:风险会影响是否适合普通用户安装。
- 证据:risks.scoring_risks | https://github.com/browserable/browserable | no_demo; severity=medium
7. 维护坑 · issue/PR 响应质量未知
- 严重度:low
- 证据强度:source_linked
- 发现:issue_or_pr_quality=unknown。
- 对用户的影响:用户无法判断遇到问题后是否有人维护。
- 证据:evidence.maintainer_signals | https://github.com/browserable/browserable | issue_or_pr_quality=unknown
8. 维护坑 · 发布节奏不明确
- 严重度:low
- 证据强度:source_linked
- 发现:release_recency=unknown。
- 对用户的影响:安装命令和文档可能落后于代码,用户踩坑概率升高。
- 证据:evidence.maintainer_signals | https://github.com/browserable/browserable | release_recency=unknown
来源:Doramagic 发现、验证与编译记录