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

tasks 服务内部由"代理"(Agent)构成,代理以节点(Node)形式在流程(Flow)中执行。每个代理都继承自 BaseAgent,并通过 jarvis.endNodejarvis.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 暴露 BrowserableConfigTaskTaskRunTaskRunStatus 等类型,并支持 pollIntervaltimeoutonStatusChange 回调,简化客户端轮询 资料来源:sdk/browserable-js/src/types.ts:1-60

LLM 兼容性与社区关注点

默认支持 OpenAI 兼容协议,Tasks 服务在多模型之间按顺序回退,候选列表包括 gemini-2.0-flashdeepseek-chatgpt-4o-miniclaude-3-5-haikuqwen-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://github.com/browserable/browserable / 项目说明书

核心功能与浏览器代理系统

Browserable 的核心是一个浏览器代理系统,由 Browserable Agent、Base Agent 与 Jarvis 三大模块协作完成"代替用户在浏览器内完成任务"的使命。Browserable Agent 的 CODE 与 DETAILS 明确描述其作用:提供可在浏览器中代替用户执行点击、输入、抽取等操作的智能体,并通过远程浏览器会话与 Playwright...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 2.1 BaseAgent 基类

继续阅读本节完整说明和来源证据。

章节 2.2 Browserable Agent

继续阅读本节完整说明和来源证据。

章节 2.3 Jarvis 协调器

继续阅读本节完整说明和来源证据。

一、目标与定位

Browserable 的核心是一个浏览器代理系统,由 Browserable AgentBase AgentJarvis 三大模块协作完成"代替用户在浏览器内完成任务"的使命。Browserable AgentCODEDETAILS 明确描述其作用:提供可在浏览器中代替用户执行点击、输入、抽取等操作的智能体,并通过远程浏览器会话与 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_tabread_tabact_on_tabextract_from_tab,理论上能完成任何网站交互 资料来源:tasks/agents/browserable.js。

2.3 Jarvis 协调器

Jarvis 是任务调度与上下文管理中枢。它通过 convertMessageLogsToLLMFormatbrowserable.message_logs 表按 run_idnode_idthread_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。截图通过 imageUrlprivateImageUrl 暴露给下游 LLM,便于多模态决策。

3.2 内容抽取与分块合并

extractPrompts.js 中的 buildExtractLLMPrompt 提供两种模式:useTextExtract=true 时基于文本化网页,false 时基于 DOM 元素列表。系统提示词强制要求"不要假设、不要幻觉",并要求输出 justificationextractedContent 字段 资料来源: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.jsactionExtractLLMHelper 内置的"下拉框需先键入再选择"等 SPECIAL ELEMENTS 规则体现了对真实网站交互细节的考虑 资料来源:tasks/agents/browserable.js。

四、LLM 多模型与失败兜底

callOpenAICompatibleLLMWithRetry 内置一组回退模型:gemini-2.0-flashdeepseek-chatgpt-4o-miniclaude-3-5-haikuqwen-plusmax_attempts=3,按列表顺序尝试以保证可用性 资料来源:tasks/agents/browserable.js。

需要替换 OpenAI 时,可在社区指引下将 OpenAI 兼容 URL 切换为 Groq 等第三方端点;本地 LLM(如 Ollama)支持尚未内置进 Admin UI 资料来源:issues/9issues/3issues/5

五、SDK 与对外契约

browserable-js 通过 CreateTaskOptionsTaskTaskRunStatus 等 TypeScript 类型对外暴露运行生命周期;TaskRunStatus 状态枚举为 scheduled | running | completed | errorTaskRunResult 增加 outputdataTable 字段 资料来源:sdk/browserable-js/src/types.tsWaitForRunOptions 默认 1 秒轮询、5 分钟超时,便于在 JS 端稳定等待 run 完成。

六、汇总输出与社区已知问题

任务收尾时,richOutputPromptoutputData 模板逐字段累计 outputGenerated,并以 4000 词为上限强制截断 资料来源:tasks/prompts/agents/jarvis/richOutputPrompt.js。后端依赖 Playwright、steel-sdksharp 等图形与浏览器栈 资料来源:tasks/package.json

常见故障包括:首次安装 Initial Setup 卡住,多为 tasks 服务未启动(docker ps 检查);npx browserable 在 fnm 多 shell 场景下出现 node --no-warnings shebang 错误 资料来源:issues/6issues/20。截图、任务 GIF、日志 API 已在路线图中陆续上线 资料来源:issues/13issues/14issues/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-jssdk/browserable-js/package.json)。
  • CLInpx browserable 命令行入口,用于一键拉起本地 Docker 部署。

资料来源:README.mdsdk/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-60sdk/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-30sdk/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_tabread_tabact_on_tabextract_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 回放)、screenshotslogs 等(见 Issue #13、#14、#12),使用前请先确认官方 REST 文档是否已上线对应接口。

资料来源:tasks/agents/browserable.js:1-120、tasks/agents/base.js:1-90sdk/browserable-js/src/types.ts:60-80

四、CLI 安装与常见问题

CLI 入口为 npx browserable,由 Issue #8 跟踪的命令行能力(--helpdown 等)已合入 1.0.13。常见使用步骤:

  1. npx browserable 启动本地 Docker Compose 栈;
  2. 等待 Initial setup is in progress 提示消失;
  3. 通过 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-60README.mdtasks/package.json:1-30

参见

资料来源:README.mdsdk/browserable-js/package.json:1-30

部署、自托管、扩展与故障排查

本文面向希望自行部署、扩展或排查浏览器自动化平台 Browserable 的工程师与运维人员。Browserable 是一个由多个协同 Agent 组成的浏览器任务执行系统,包含任务调度 (tasks)、管理员界面 (ui) 与官方 JavaScript SDK (sdk/browserable-js)。本页围绕部署架构、安装流程、扩展点与常见故障展开,所有结论均基于仓库源...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 3.1 LLM 提供商

继续阅读本节完整说明和来源证据。

章节 3.2 自定义工具与本地浏览器

继续阅读本节完整说明和来源证据。

章节 3.3 SDK 与 REST API

继续阅读本节完整说明和来源证据。

本文面向希望自行部署、扩展或排查浏览器自动化平台 Browserable 的工程师与运维人员。Browserable 是一个由多个协同 Agent 组成的浏览器任务执行系统,包含任务调度 (tasks)、管理员界面 (ui) 与官方 JavaScript SDK (sdk/browserable-js)。本页围绕部署架构、安装流程、扩展点与常见故障展开,所有结论均基于仓库源码与社区讨论记录。

一、部署架构概览

Browserable 通过 Docker Compose 启动一组协同服务,核心组件包括后端任务服务、数据库与本地浏览器运行时。任务服务通过 pgredisplaywrightsteel-sdk 等依赖与外部世界交互,分别承担持久化、队列调度、浏览器自动化与远程浏览器连接等职责 资料来源:tasks/package.json:1-30

后端任务服务通过 browserable PostgreSQL schema 存储运行日志,典型的查询会写入 browserable.message_logs 表,字段涵盖 run_idnode_idthread_idsegmentmessagescreated_at,分别用于标识运行、节点、线程、消息段、消息内容与时间戳 资料来源:tasks/agents/jarvis.js:1-50。运行时还会调用 isRunActiveupdateNodeLiveStatusscheduleQueueJob 等函数来判断运行是否仍然有效,并在 Agent 节点结束时通过 endNodeerrorAtNode 更新状态 资料来源: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 增加了 --helpdown 等子命令,用于查看帮助与停止所有服务 资料来源:issue #8

安装步骤大致为:

  1. 在主机上安装 Node.js(建议使用 LTS 版本)与 Docker Engine;
  2. 执行 npx browserable 拉起 tasksui 等容器;
  3. 通过浏览器访问 ui 容器暴露的端口,使用 OpenAI 兼容 LLM 的 API Key 完成初始配置;
  4. 等待"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-flashdeepseek-chatgpt-4o-miniclaude-3-5-haikuqwen-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_tabread_tabact_on_tabextract_from_tab 四类核心动作,并在执行过程中调用 browserService.getPlaywrightBrowser 申请浏览器会话,支持本地浏览器会话与远程会话两种模式 资料来源:tasks/agents/browserable.js:60-140。

3.3 SDK 与 REST API

官方 JavaScript SDK 暴露 CreateTaskOptionsTaskRunStatusTaskRunResult 等类型,运行状态枚举为 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 #6tasks/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

来源:https://github.com/browserable/browserable / 项目说明书

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险,不把社区讨论只当作装饰信息。

medium 来源证据:npx browserable returns error `/usr/bin/env: ‘node --no-warnings’: No such file or directory`

可能增加新用户试用和生产接入成本。

medium 可能修改宿主 AI 配置

安装可能改变本机 AI 工具行为,用户需要知道写入位置和回滚方法。

medium 能力判断依赖假设

假设不成立时,用户拿不到承诺的能力。

medium 维护活跃度未知

新项目、停更项目和活跃项目会被混在一起,推荐信任度下降。

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 发现、验证与编译记录