企业官网建设流程全解析

本文讲解 OpenAlice 项目（default/skills/opencli-reader/SKILL.md）中定义的opencli-reader技能：它如何通过可选的社区工具opencli以只读方式访问各类网站数据，包括命令发现、适配器注册表解析、浏览器桥接设置、读写边界的判断与失败降级策略。读完本文，你将掌握在 OpenAlice 的研究工作流中如何合规、高效地调用opencli <site> <command>，并在适配器不可用或失败时用其他可用工具继续研究而不中断任务。

定位：一个可选的只读数据访问通道

opencli（独立开源项目，非 OpenAlice 自带）通过opencli <site> <command>提供面向不同网站的适配器（adapter），例如 Yahoo Finance 行情、Hacker News 榜单、雪球个股讨论、Barchart 期权流等。在 OpenAlice 的研究链路中，它是 Coding Agent 浏览器、搜索引擎及其他可用工具之外的一个来源访问选项——任何研究任务都不强制依赖它。

这一点从仓库的技能组织结构可以得到印证：default/skills/下每个技能是一个独立目录，包含SKILL.md与references/子目录，例如alice技能负责通过aliceCLI 完成行情搜索、K 线分析、工作区协作等主要研究接口，而opencli-reader技能只覆盖"通过 opencli 只读访问网站"这一补充场景。项目通过 default/alice-harness.json 打包这些技能（schemaVersion: 1、version: 1.0.4），并可在工作区注入时按需启用或排除。

使用边界：只读，且不改变外部状态

opencli-reader技能明确限定为只读用途：

• 不得调用会发布（post）、发送（send）、订阅（subscribe）或以其他方式改变外部状态的适配器动作；
• 输出中不得包含凭据和浏览器会话细节；
• 执行价格与交易写入仍归配置的 broker/UTA 通道所有——opencli 不参与交易侧操作。

命令发现：永远以实时帮助为准

使用 opencli 时，先检查已安装命令的实际能力与参数，而不是依赖记忆或过时清单：

command -v opencli # 确认 opencli 已安装且位于 PATH opencli <site> --help # 查看某个站点适配器的全部子命令 opencli <site> <command> --help # 查看具体命令的参数

opencli list -f json以 JSON 形式列出当前可用的适配器清单。适配器注册表是事实来源（source of truth），绝不要手写维护一份站点清单——注册表字段与浏览器设置细节见 default/skills/opencli-reader/references/discovery.md；命令清单本身每周都会变化，选择适配器时必须来自实时的opencli list输出。

适配器不可用时的处理原则

• 若某个适配器不可用，其他合适的数据源仍可完成该任务；
• 安装 opencli 或配置账号需要用户授权；仅缺少 opencli 本身不构成中断研究的理由；
• 应当如实报告证据缺口（material evidence gaps），而不是把某个具体工具当作前置条件。

注册表发现：读懂 JSON 条目

opencli list -f json输出的每个条目大致形状如下（摘自 discovery.md）：

{ "site": "yahoo-finance", "name": "quote", "aliases": [], "description": "Yahoo Finance stock quote", "strategy": "PUBLIC", "browser": false, "args": [ { "name": "symbol", "type": "string", "required": true, "positional": true } ], "columns": ["symbol", "name", "price", "change", "changePercent", "volume"] }

各字段含义：

六种策略：各自的成本与前置条件

注意：并非所有适配器都需要浏览器——strategy: PUBLIC的适配器不需要任何浏览器桥接。这一点在"Don'ts"清单中被单列提醒，是新手最容易踩的坑。

浏览器桥接与opencli doctor

浏览器支撑的策略（COOKIE/HEADER/INTERCEPT/UI）需要：

1. Chrome 已登录目标站点；
2. 安装了 OpenCLI 浏览器扩展。

此时用opencli doctor验证"守护进程 + 扩展 + Chrome"整条桥接链路是否可用；该检查不适用于PUBLIC/LOCAL适配器。此外，面向 Electron 桌面应用的适配器（例如discord-app、chatgpt-app）通过 CDP 附着到正在运行的桌面应用——应用必须处于运行状态才能使用。

判断读写边界：没有只读标志，靠三层判据

opencli 注册表没有正式的readonly标志，判断一个命令是否会改写外部状态需要按以下顺序：

1. 名称启发式——含变更性动词的一律视为写操作，绝不调用：post、reply、comment、like、unlike、upvote、downvote、save、unsave、subscribe、unsubscribe、follow、unfollow、block、unblock、delete、bookmark、unbookmark、send、create-draft、reply-dm、accept、hide-reply；
2. description字段——含 "fetch / read / get / list / search" 的是读；含 "post / send / submit / create" 的是写；
3. 不确定就不执行——询问用户或直接跳过该命令。

实战：从需求到命令的工作示例

以下完整示例来自 discovery.md，展示"先--help探路，再-f json取结构化输出"的标准流程：

# 需求："读取 Hacker News 首页" opencli hackernews --help opencli hackernews top --limit 20 -f json # 需求："雪球上关于比亚迪的讨论" opencli xueqiu --help opencli xueqiu stock SZ002594 -f json opencli xueqiu comments SZ002594 --limit 30 -f json # 需求："NVDA 是否有异常期权流" opencli barchart --help opencli barchart flow NVDA -f json

-f json输出与注册表中的columns定义保持一致，可直接交给下游的jq、Python 或 shell 管道做进一步加工。

故障诊断与降级：研究不因单一工具中断

• 适配器失败时，设置环境变量OPENCLI_DIAGNOSTIC=1可辅助诊断问题；分享诊断输出前务必检查其中是否含有私有数据；
• 无论 opencli 可用与否，研究都可以通过 Coding Agent 的其他可用工具（浏览器、搜索等）继续推进；
• 与 OpenAlice 自身的aliceCLI 相比，alice是内置的、输出 JSON 到 stdout 的主力研究接口（如alice market search --query AAPL），而 opencli 是外部的、可选的补充来源——两者分工不同，不应混淆。

禁止事项清单（Don'ts）

• 不要把一份手写的适配器清单粘贴进计划——它很快就会过时；选择适配器请使用实时的命令帮助输出；
• 不要假设每个适配器都需要浏览器——strategy: PUBLIC的适配器不需要；
• OPENCLI_DIAGNOSTIC=1可用于诊断失败的适配器，但其他可用工具仍是访问该数据源的可选路径；
• 不要调用任何名称或描述暗示会变更状态（mutation）的命令。

与 OpenAlice 技能体系的配合

opencli-reader技能随 OpenAlice 的 Skills 包一起分发。根据 docs/alice-harness.md，Alice Project 通过 default/alice-harness.json 提供 Skills 文件包，工作区注入时会分别写入.agents/skills（主目录）与.claude/skills（运行时镜像），并支持按技能粒度的启用/排除/更新/恢复（skills为可选的名字到布尔值的包含映射）。这意味着：

• 技能文件只会在显式更新后发生变化，Agent 需要重读变更后的技能才能使用新指令；
• 若研究流程不需要网站适配器，可以排除该技能而不影响主研究链路；
• 技能修订通过内容指纹（fingerprint）记录在注入清单中，便于追溯每次技能变更。

因此在实际使用中，opencli-reader的正确打开方式是：确认 opencli 已安装 →opencli list -f json查看实时注册表 → 用--help探明参数 → 依据三层判据确认只读 → 执行并解析 JSON 输出；整个过程以"只读、可降级、不泄密"为底线，与 OpenAlice 自身的alice研究接口形成互补。