| name | bycli |
| description | byCLI 全能力 skill — 统一管理 bycli 命令执行、浏览器驱动、适配器自修复、适配器编写、Markdown 入库。当用户需要运行 bycli 命令、驱动浏览器完成任务、修复失败的 adapter、编写新 adapter、查询 bycli 用法、将内容存入知识库，或发起搜索 / 采集 / 抓取 / 爬取 / 网站操作类任务时使用。触发短语："bycli"、"浏览器操作"、"adapter 坏了"、"写个 adapter"、"爬取数据"、"修复命令"、"browser open"、"autofix"、"open cli"、"驱动浏览器"、"写爬虫"、"browser driving"、"fix adapter"、"write adapter"、"搜索"、"查找"、"采集"、"抓取"、"爬取"、"获取"、"打开网站"、"访问网页"、"登录"、"操作网站"、"scrape"、"crawl"、"browse"、"open URL"、"存到知识库"、"入库"、"导入知识库"、"保存到知识库"、"沉淀到知识库"、"收藏到知识库"、"归档"。 Use when this capability is needed. |
| metadata | {"author":"beyonai"} |
byCLI Skill
byCLI skill 封装 byCLI —— byCLI 把任意网站、Electron 桌面应用或外部 CLI 统一为 bycli <site> <command> 接口，agent 无需 screen-scraping 即可驱动。
本 skill 是唯一入口——根据意图路由到对应工作流，详细参考按需加载。
严格禁止 (NEVER DO)
- 不要硬编码 adapter 列表，始终用
bycli list -f json 动态发现
- 不要在
browser eval 中执行写操作（submit/click/navigate），用 click/type/select 结构化命令
- 不要跨页面复用 numeric ref，页面变化后必须 re-
state
- 不要在修复 adapter 时修改
src/、extension/、tests/、package.json、tsconfig.json
- 不要放宽
verify/<cmd>.json fixture 来掩盖失败——修 adapter 让输出正确
- 不要猜测字段含义——猜错了 verify 通过但数据是错的
- 不要在 repo 根目录 /
clis/<site>/ 留临时 dump 文件（.dbg-*.html / raw-*.json）
- AUTH_REQUIRED（exit 77）/ BROWSER_CONNECT（exit 69）/ CAPTCHA / 限流 → 不修改代码，报告用户
- 不要绕过入库脚本手写
curl、fetch 或自行拼签名头
- 不要把 token、SESSION、Cookie、Beyond-Token、签名盐写入技能文件、命令参数或对话回复
- 非 bycli 采集收尾场景下，不要在用户未明确表达入库意图时主动建议入库（采集收尾必须主动问一次，属例外）
- 不要采集成功后不主动询问是否入库，也不要采集完不落盘就询问
- 不要把采集产物落到
/tmp/ 或工作区根目录，不要让入参与正文分在不同目录，不要覆盖已有时间戳目录
- 不要在入库失败时清理产物、Session 结束时自动清理、未列清单未确认就清理、删除
audit_required=true 目录
- 不要无 adapter 时绕过
bycli browser 直接用 web_fetch / browser 通用工具
- 不要向用户输出本 skill 的内部决策逻辑（步骤编号、流程名称、路由分支）——直接执行
严格要求 (MUST DO)
- Agent 调用 bycli 时始终加
-f json 获取可解析输出
- 浏览器操作前确认
bycli doctor 通过（仅 COOKIE/INTERCEPT/UI 策略需要）
- 每次执行
bycli doctor 后（无论成功与否）必须紧接着执行 bycli daemon status，确认 daemon 处于 running 且 Extension 为 connected，据此判断桥接是否正常；任一不满足则视为桥接异常，按以下阶梯升级处理：
- 桥接异常 → 先按冷启动流程重启（
openclaw browser start → bycli doctor → bycli daemon status）
- 仍异常 →
bycli daemon restart，再 bycli daemon status 复检
bycli daemon restart 后仍连接不上（daemon 未 running 或 Extension 未 connected）→ STOP，停止一切浏览器动作，提示用户检查 Chrome 是否正常启动、byCLI 扩展插件是否已安装并启用，恢复后再重试；不得继续驱动或降级到通用工具
- 修复 adapter 时仅修改 trace
summary.md 里 adapterSourcePath 指向的文件
- 修复预算：每次失败最多 3 轮 trace → fix → retry
- 写 adapter 后必须
bycli browser verify 通过 + 字段值与网页肉眼比对
- 采集 / 获取数据成功后必须做收尾两问（见「Browser 驱动成功后 — 强制两问收尾」）：①「复用」——仅当本次走了
bycli browser 降级驱动（无现成 adapter）时，问是否把过程存为 adapter；②「归档」——无论用何种方式采集成功，都按「采集后入库衔接」问是否入库。两问按各自触发条件该问必问，都不自动执行，须等用户答复
- 浏览器 session 结束后执行 cleanup（close tab → stop daemon → stop browser）
- Login/Auth 页面例外：不关闭 session，报告 session name + URL 给用户
- 入库必须通过
node scripts/bycli-markdown-ingest.mjs 执行，不得旁路
- 入库前必须先
list-kb 查询知识库并让用户选择目标
- 对用户展示入库摘要并获得确认后再执行真实
ingest
意图决策树
关键区分：
- 有现成 adapter → 直接用
bycli <site> <command>
- 没有 adapter 但需要一次性数据 → Browser 驱动（采集成功后走「强制两问收尾」：问①复用 adapter + 问②入库）
- 没有 adapter 且需要复用 → 写新 adapter
- 现有 adapter 报错 → AutoFix
- 已有 Markdown 内容 + 用户说"入库" → Markdown 入库
收到搜索 / 采集 / 抓取 / 网站操作 / 入库类任务时，先按本决策树路由，未确定路径前不直接调用通用 web_fetch / browser 工具。本 skill 不匹配时再评估其他 skill（如 dws），全部不匹配才兜底通用工具。
适配器缺失降级（强制）
bycli list -f json 无对应适配器时：
- 用
bycli browser 系列命令完成任务，不跳到通用工具
- 按下方浏览器生命周期 + browser.md 规范执行
- 驱动前先
bycli doctor 确认桥接，紧接着 bycli daemon status 确认 daemon running + Extension connected
- 采集 / 获取数据成功后，必须按下方「Browser 驱动成功后 — 强制两问收尾」执行：降级驱动场景先问①「复用」再问②「归档」（仅询问，不自动执行）
Browser 驱动成功后 — 强制两问收尾（不可跳过）
采集 / 获取数据成功后做收尾两问。两问触发条件不同，各自该问必问：
问题 ①「复用」— 是否保存为 adapter（仅降级驱动时问）：
触发条件：本次数据通过 bycli browser 降级驱动获取（即 bycli list -f json 无现成 adapter）。已有现成 adapter（直接 bycli <site> <command>）则跳过此问——本来就有 adapter，无需再造。
在返回数据的同一轮回复里问：
「本次数据是通过浏览器实时驱动获取的。是否把刚才的获取过程保存成一个专用 adapter（适配器）？保存后下次同类请求可直接 bycli <site> <command> 快速获取，无需再驱动浏览器。（是 / 否）」
- 用户答是 / 需要 / 保存 / 可以等肯定意图 → 进入 adapter-author.md 流程，把本次驱动过程（站点、命令、抓到的接口 / DOM、字段）沉淀为 adapter（含 verify、原始请求重放、交付，均按该流程 runbook 执行）
- 用户答否 / 不用 / 跳过 → 不写 adapter
问题 ②「归档」— 是否存入知识库（任何采集方式都问）：
触发条件：无论用现成 adapter 还是降级驱动，只要采集成功就问。具体落盘时机、话术、入库流程一律以下方「采集后入库衔接」章节为准，此处不重述——即先自动落盘再询问，确认后 list-kb 选库 → normalize 预览 → ingest。
强制约束：
- 问①与问②相互独立：①问「过程要不要复用」（仅降级驱动），②问「数据要不要归档」（所有采集）。二者互不替代，也不互为前提
- 当本次是降级驱动时，①②都要问，顺序先①后②，不得问了一个省另一个
- 当本次用现成 adapter 时，只问②
- 都不自动执行，必须等用户对每一问分别答复后才进入对应流程
- 不向用户暴露本收尾的内部触发条件（步骤编号、流程名）
Markdown 入库 — 触发边界（最高优先级）
区分两个场景，规则不同：
场景 A — bycli 采集收尾（主动问）： 本 skill 通过 bycli 采集 / 获取数据成功后，必须按「采集后入库衔接」自动落盘并主动询问一次是否入库。这是采集流程的固定收尾，不受下方「明确意图」约束——即使用户没说「入库」，也要主动问这一次（用户答跳过即停，不重复纠缠）。
场景 B — 已有内容直接入库（需明确意图）： 当不是 bycli 采集收尾、而是用户拿着已有内容请求归档时，仅在用户明确表达入库意图时才进入。以下情况不触发、也不主动建议：
- 用户只是在查数据 / 读网页 / 浏览内容（且非 bycli 采集收尾场景）
- 用户说"保存文件" / "下载"——这是本地文件操作，不是知识库入库
- 用户说"记住这个" / "记一下"——这是对话记忆，不是知识库入库
- 没有明确入库目标，且不属于场景 A 时，不要主动建议入库
基础用法
安装
npm install -g @sovovs/bycli
bycli doctor
bycli daemon status
命令发现
bycli list
bycli list -f json
bycli list | grep -i <site>
bycli <site> --help
bycli <site> <command> --help
通用 flag
| flag | 说明 |
|---|
-f, --format <fmt> | json(agent 首选) / table / yaml / plain / md / csv |
-v, --verbose | 调试日志 + 堆栈跟踪 |
策略与前置条件
| 策略 | 需要什么 |
|---|
PUBLIC | 无需浏览器，纯 HTTP |
COOKIE | Chrome 已登录目标站 + byCLI 扩展 |
INTERCEPT | 同 COOKIE，额外打开自动化窗口捕获签名请求 |
UI | 同 COOKIE，全 DOM 交互 |
LOCAL | 无需浏览器，访问本地/开发端点 |
外部 CLI 透传
bycli external install gh
bycli gh pr list --limit 5
自修复入口
命令失败时加 --trace retain-on-failure 重跑，读取 trace summary.md，进入 AutoFix 流程。
错误处理
| 错误类型 | Agent 行为 |
|---|
| AUTH_REQUIRED (exit 77) | STOP，提示用户登录 |
| BROWSER_CONNECT (exit 69) | STOP，运行 bycli doctor + bycli daemon status 诊断；bycli daemon restart 后仍连不上则停止一切动作，提示用户检查 Chrome 与 byCLI 扩展插件是否正常启动 |
| CAPTCHA / 限流 | STOP，不是 adapter 问题 |
| SELECTOR / EMPTY_RESULT / API_ERROR | 进入 AutoFix 流程 |
| TIMEOUT / PAGE_CHANGED | 进入 AutoFix 流程 |
| 3 轮修复仍失败 | 报告尝试过的方法，停止 |
| 站点大改需要重写 | 转 Adapter 编写流程 |
| 入库 HTTP 401/403 | 门户登录态不可用，停止入库，提示用户恢复会话 |
浏览器生命周期（OpenClaw 托管环境）
在 OpenClaw 托管环境中，浏览器进程由三个独立组件管理：
| 组件 | 归属 | 控制方式 |
|---|
| Chromium 进程树 | OpenClaw browser plugin | openclaw browser --browser-profile openclaw start/stop/status |
| byCLI Browser Bridge daemon (port 19825) | bycli 自身 | bycli daemon start/restart/stop |
| Browser tab lease (CDP target) | bycli session name | bycli browser <sess> open/close |
| Extension 握手 | 两侧都需要 | bycli doctor 检查 |
冷启动
openclaw browser --browser-profile openclaw start
bycli doctor
bycli daemon status
bycli browser <session> open <url>
bycli browser <session> state
注意：bycli browser <sess> open 是 CDP 客户端，不能冷启动 Chromium。未运行时报 Browser profile "<id>" is not connected，必须先 openclaw browser start。
关闭流程（非登录页）
何时执行三层关闭（以下条件同时满足）：
- 当前浏览器任务链已完成（数据已获取 / 操作已完成）
- 当前页面不是 login/SSO/MFA 页面
- 没有后续操作需要复用同一 session
何时不关闭：
- 页面仍在 login/SSO/MFA → 保持 session，报告 session name + URL
- 用户后续任务明确需要继续使用同一浏览器上下文
- 多步操作未完成（如「采集多页 → 入库」是连续动作，中间不关）
关闭粒度：
| 场景 | 操作 |
|---|
| 单次任务完成，无后续 | 三层全关（下方流程） |
| 任务完成但可能继续操作同站点 | 仅 browser close 释放 tab，保留 daemon + Chromium |
| 异常 / 卡死 | Kill-all-Chrome（见下方） |
三层关闭，顺序重要：
bycli browser <session> close
bycli daemon stop
openclaw browser --browser-profile openclaw stop
关键事实：
browser close 只释放 tab，不停 daemon 或 Chromedaemon stop 只断 CDP 连接，Chromium 仍在运行- 只有
openclaw browser stop 才能真正释放 Chromium 进程
Login/Auth 页面例外
页面仍在 login/SSO/MFA 状态时，不执行任何关闭操作。保持 session 存活，向用户报告 session name + URL。
Kill-all-Chrome
bycli browser <sess> close 2>/dev/null || true
bycli daemon stop 2>/dev/null || true
openclaw browser --browser-profile openclaw stop
pkill -f chromium 2>/dev/null || true
采集后入库衔接（强制）
本章节是「强制两问收尾」中问②（归档/入库）的权威定义——无论用现成 adapter 还是降级驱动，bycli 成功采集到数据后都按此执行，问②不在别处重复询问。
1. 自动落盘（采集完成时立即执行，无需等用户确认）
- 将采集结果完整内容（Markdown 正文 + 元数据）自动落盘到会话目录，最多落盘 10 篇
- 同时写入
bycli-output.json（含全部结果索引，包括未落盘文章的标题 / URL）
- 落盘后向用户展示采集摘要并询问：
「本次成功采集到 X 条数据（已预存 N 篇正文），是否需要保存到您的知识库？（全部 / 部分 / 跳过）」
2. 用户确认入库后
- 已落盘文章 → 直接用落盘文件入库，不重新采集
- 超出 10 篇的剩余文章 → 此时再逐篇采集正文并追加落盘，然后一并入库
- 入库范围以用户选择为准（全部 / 指定篇目 / 仅前 N 篇）
- 入库成功后 → 自动删除该时间戳目录下的落盘文件（已归档至知识库，本地无需保留）
3. 用户拒绝 / 跳过
- 返回采集结果，已落盘产物保留（不主动删除）
- 用户后续可再发起入库，届时直接复用已落盘文件 + 补采剩余
禁止
- 用户未明确同意前执行入库脚本
- 自动落盘超过 10 篇正文（控制磁盘占用，超出部分按需采集）
- 采集完成后不落盘就直接询问入库（必须先落盘再询问）
采集产物落盘约定（强制）
所有 bycli 采集的原始产物必须落盘到会话专属目录，严禁落到 /tmp/、工作区根目录或 references/ 同级位置。
路径模板
/by/.sessions/<sessionId>/<bycliSessionName>/<YYYYMMDD_HHMMSS>/
<sessionId>：本会话 ID<bycliSessionName>：bycli browser <name> open 时使用的 session 名<YYYYMMDD_HHMMSS>：本次采集起始时间戳（Asia/Shanghai）
必含文件
| 文件 | 说明 |
|---|
bycli-output.json | 规范化入参，结构 {title, url, items:[{title, url, author, publish_time, markdown, fileName}]} |
<fileName>.md | 原始 Markdown 正文（与 items[].fileName 一致） |
可选文件
| 文件 | 说明 |
|---|
search-results.json | 多结果采集的原始结果快照 |
metadata.json | 来源、点赞 / 评论 / 阅读数、采集时间、策略、session 信息 |
pages/<slug>.html / pages/<slug>.json | 原始抓取页（事后回放） |
调用入库
SESSION_DIR=/by/.sessions/<sessionId>/<bycliSessionName>/$(date +%Y%m%d_%H%M%S)
mkdir -p "$SESSION_DIR"
node scripts/bycli-markdown-ingest.mjs ingest \
--bycli-json-file "$SESSION_DIR/bycli-output.json" \
--task-name "生态采集-<source>" \
--connector-code <source> \
--source-name "<source>" \
--source-url "<原文链接>" \
--knowledge-base-resource-id <resourceId> \
--knowledge-base-name "<知识库名>"
采集产物保留策略
生命周期
| 时机 | 行为 |
|---|
| 落盘完成 | 保留 |
| 入库成功 | 清理该时间戳目录内容（已归档至知识库） |
| 入库失败 | 保留（审计与重试） |
| 用户说"跳过入库" | 保留（后续可再发起） |
| 用户说"保留 / 不清理" | 即使入库成功也保留 |
| Session 结束 | 不主动清理（由会话清理策略统一处理） |
用户显式清理
仅在用户明确说出清理意图时执行：
- 列出目标目录下所有时间戳子目录（降序）
- 按用户指定策略保留（默认保留最近 10 次）
audit_required=true 的目录不可删- 清理前列清单二次确认
- 只删目录内容，不删目录本身
详细参考（按需读取）
Don't
- 不要把本 skill 的命令列表粘贴到计划中——它会过期。用
bycli list -f json。
- 不要假设所有 adapter 都需要浏览器——
PUBLIC/LOCAL 不需要。
- 不要从失败的 adapter 默默 fallback 到手写
fetch——先走 --trace retain-on-failure。
- 不要在
bycli browser 中硬编码 CSS selector——用 state/find 获取 numeric ref。
- 不要在用户只是浏览内容时自动触发入库——但 bycli 采集成功后必须主动问一次（采集收尾例外）。
Source: beyonai/ByClaw — distributed by TomeVault.
