适用场景
手上有一批只能在网页上操作的内部系统或第三方后台（工单、订单、报表、内容后台），希望智能体能直接读取和操作，而不是靠人复制粘贴。Pomerado 的思路是把网站的登录态、页面操作和数据结构封装成一个 MCP 服务，让任何支持 MCP 的客户端把网站当成一组工具来调用。这套方案适合想快速验证"智能体 + 网页能力"的中小团队，也适合运维同学给自己搭一个能查监控面板、查发布系统的助手。
环境与前置条件
- 操作系统：macOS、Linux 均可；Windows 建议在 WSL2 里操作，避免路径与进程管理差异带来的额外排查成本。
- 运行时：Pomerado 及其依赖的运行时版本以官方文档当前版本为准。安装完成后至少要能执行
pomerado --version且不报错。 - 硬件：纯 HTTP 抽取模式 2 GB 内存足够；如果开启浏览器内核渲染（需要执行 JavaScript 的站点），建议 4 GB 以上内存，磁盘预留 1 GB 给缓存与日志。
- 一个可登录的目标网站账号。强烈建议单独申请一个只读权限的账号专供智能体使用，不要用管理员账号。
- 一个 MCP 客户端：Claude Desktop、Cursor、或任何支持标准 MCP 配置的客户端，用于验证工具是否被正确暴露。
- 能访问目标网站的网络环境。如果目标站在内网，Pomerado 要部署在能通内网的机器上。
分步骤部署
第 1 步：安装并确认命令可用
按官方文档给出的方式安装（通常是语言生态的包管理器或容器镜像，具体形式以官方文档为准）。安装后先做一次最小验证：
```bash
pomerado --version
pomerado --help
```
--version 有输出、--help 能列出子命令，说明二进制已就位。如果提示 command not found，先确认安装路径是否在 PATH 里：
```bash
which pomerado
echo $PATH
```
后面写 MCP 客户端配置时，建议直接使用 which 输出的绝对路径，可以绕开客户端与终端 PATH 不一致的问题。
第 2 步：初始化项目与站点配置
为每个目标网站建一个独立目录，配置、日志、登录态缓存都放在里面，后续备份和排错会清晰很多。
```bash
mkdir -p ~/pomerado-sites/example && cd ~/pomerado-sites/example
pomerado init
```
init 会生成一份配置模板（文件名可能是 pomerado.yaml 或类似名称，以实际生成为准）。核心要做三件事：
1. 站点入口：填写目标网站的基地址，例如 https://example.com。
2. 能力定义：把你真正需要的一到两个动作先定义清楚，比如"查询工单列表""读取某张报表"，不要一上来就把整站都封装进去。
3. 参数与返回结构：给每个能力声明参数（关键词、时间范围、分页）和希望返回的字段。返回字段越精简，智能体调用越稳定。
示意结构如下（字段名以官方文档示例为准，把 example.com 换成你的目标站点）：
```yaml
site:
name: example
base_url: https://example.com
tools:
- name: list_tickets
description: 按关键词查询工单列表，返回标题、状态、负责人
params:
keyword: string
limit: integer
entry: /tickets/search
```
description 是给智能体看的，写清楚"什么时候该用这个工具"比写技术细节更有用。
第 3 步：配置鉴权
这一步是整个流程里最容易卡住的地方。网页类工具的鉴权通常落在三种形态上：
- Cookie / Session：最普遍。用浏览器登录后，从开发者工具的 Network 面板复制会话 Cookie。
- Bearer AI 词典：Token">Token：多见于前后端分离的系统，登录接口返回一个 token，放在
Authorization头里。 - API Key Header：少数后台提供的固定密钥头。
无论哪种，都不要把凭据明文写进配置文件，更不要提交到 Git 仓库。用环境变量注入：
```bash
export POMERADO_SITE_COOKIE='session=xxxx; token=yyyy'
export POMERADO_SITE_TOKEN='your-bearer-token'
```
配置文件里只引用变量名，不写值。同时在项目目录里放一个 .gitignore：
```bash
printf '.env\n*.log\n.cache/\n' > .gitignore
```
如果要把凭据长期保存，用系统钥匙串或密钥管理服务，临时写进 .env 也只用于本机调试。
另外两点容易被忽略：
- 登录态会过期。先手动跑一次确认当前 Cookie 有效，并记下大概的有效期。后续可以在定时任务里定期更新，或者在智能体的系统提示里加一句"如果返回 401/403，停止重试并告知用户需要刷新登录态"。
- 权限要收敛。给智能体的账号只开需要的那几个页面，写操作（提交、删除）默认不封装，确需开放时单独定义工具并加二次确认。
第 4 步：本地跑通一次，先不接智能体
在接入客户端之前，先在终端里把"能不能拿到数据"这件事验证掉，否则出了问题无法判断是网站侧、Pomerado 侧还是客户端侧。
```bash
cd ~/pomerado-sites/example
pomerado run --tool list_tickets --param keyword=测试 --param limit=3
```
成功的标志是终端打印出结构化的 JSON（或表格），里面能看到真实业务字段。如果这一步返回空数组，先别怀疑鉴权，检查关键词或时间范围是否真的能命中数据。
把标准错误单独重定向到文件，排错时非常有用：
```bash
pomerado run --tool list_tickets --param keyword=测试 2> run.err.log
tail -n 50 run.err.log
```
第 5 步：以 MCP 服务方式启动
确认单次调用没问题后，用服务模式把能力暴露出去。常见做法是 stdio 模式（由客户端拉起进程）或本地 HTTP 模式（自己常驻、多个客户端共用）。stdio 模式上手更快，HTTP 模式更适合团队共享。
先用 stdio 模式手动验证一次进程能正常握手：
```bash
pomerado serve --config ~/pomerado-sites/example/pomerado.yaml
```
进程如果没有立刻退出、并且日志里出现 "listening" / "ready" 一类的字样，说明服务本身是健康的。按 Ctrl+C 退出，交给客户端托管。
第 6 步：接入 MCP 客户端
MCP 的标准配置结构基本一致，各客户端的配置文件位置不同（以各客户端官方文档为准）。以 Claude Desktop 为例，配置文件在 macOS 上是 ~/Library/Application Support/Claude/claude_desktop_config.json。
```json
{
"mcpServers": {
"pomerado-example": {
"command": "/usr/local/bin/pomerado",
"args": ["serve", "--config", "/Users/you/pomerado-sites/example/pomerado.yaml"],
"env": {
"POMERADO_SITE_COOKIE": "session=xxxx; token=yyyy"
}
}
}
}
```
三个关键点：
command用绝对路径，别写pomerado。args的具体子命令以官方文档为准，配置文件名也按你本机实际生成的改。- 凭据写在
env里，让客户端在拉起进程时注入，不依赖你当前 shell 的环境变量——客户端通常读不到你终端里的export。
改完配置必须重启客户端，很多"工具没出现"的问题都是没重启。
第 7 步：让智能体真正调用
重启后在对话里先问一句："你现在有哪些可用的工具？" 确认列表里出现了 list_tickets 之类的名字，再提业务问题：
> 帮我查一下标题里带"测试"的工单，最多三条，按状态分组告诉我。
观察三点：智能体是否选中了正确的工具、参数是否填对、返回结果是否被正确复述。如果智能体总是自己编答案而不调用工具，回头把工具的 description 改得更明确，比如写成"当用户询问工单状态时使用本工具，不要凭记忆回答"。
验证部署是否成功
按顺序执行，四条都过就算部署完成：
1. pomerado --version 有输出。
2. pomerado run --tool list_tickets --param keyword=测试 返回非空 JSON，字段与预期一致。
3. 客户端重启后，工具列表中出现配置里声明的全部工具，数量对得上。
4. 让智能体连续做两次调用（先查列表、再针对某一条追问细节），两次都能拿到真实数据，而不是模型自行编造的内容。
再补一条反向验证：临时把环境变量里的 Cookie 改错，重新提问，智能体应当明确报告鉴权失败，而不是返回空结果或瞎猜。这说明错误处理链路是通的。
常见报错与解决
报错：spawn pomerado ENOENT 或客户端里工具列表为空
→ 原因：客户端找不到可执行文件，或配置文件路径写错、改完没重启。
→ 解决：
```bash
which pomerado
把输出的绝对路径填回 mcpServers.<name>.command
改完后完全退出客户端再启动
```
报错：401 Unauthorized / 403 Forbidden，或返回登录页 HTML
→ 原因：Cookie 或 token 过期；或凭据只写在了终端环境变量里，客户端拉起的进程读不到。
→ 解决：重新登录导出 Cookie，写入客户端配置的 env 字段；或先手动验证一次。
```bash
export POMERADO_SITE_COOKIE='新的cookie值'
pomerado run --tool list_tickets --param keyword=测试
```
报错：Connection closed / 客户端提示 MCP 服务启动失败
→ 原因：服务进程启动即崩溃，常见于配置文件语法错误或路径不存在；客户端只显示结果，真正的报错在 stderr。
→ 解决：手动跑一次并把 stderr 存下来。
```bash
pomerado serve --config ~/pomerado-sites/example/pomerado.yaml 2> serve.err.log
cat serve.err.log
```
报错：工具调用成功但返回空数据
→ 原因：页面改版导致选择器或字段映射失效；也可能是筛选条件本身没命中。
→ 解决：先用不带筛选的参数跑一次，确认能拿到全量；再对照页面结构调整字段映射。
```bash
pomerado run --tool list_tickets --param limit=1
```
报错：429 Too Many Requests 或目标站返回限流页
→ 原因：智能体在循环调用，或并发过高。智能体遇到空结果时容易反复重试。
→ 解决：降低并发和重试次数，在工具描述里写明"单次对话最多调用两次"，并对返回空结果的情况做显式提示。
后续维护
备份：需要备份的是站点配置目录（pomerado.yaml、字段映射、工具定义），凭据本身不进备份包，单独存密钥管理。建议把配置目录纳入 Git，.gitignore 里排除 .env、*.log、.cache/。
升级：升级前先看官方 changelog，重点确认配置格式和子命令是否有变化。升级顺序是先在测试目录跑通第 4 步的单次调用，再替换生产配置，避免直接升级导致智能体侧全部失效。
日志：把服务日志按天切分并设置保留周期，至少保留两周。日志里至少要能看到每次调用的工具名、参数、耗时和状态码，这四样是排障的主要依据。
监控：关注三个指标——调用成功率、平均耗时、鉴权失败次数。鉴权失败突然上升通常意味着会话策略变了；成功率下降而耗时不变，多半是页面结构改版。给关键站点配一条每日巡检任务，定时跑一次只读工具，失败了就告警，比等用户反馈要快得多。
权限复核：每季度复核一次智能体账号的权限范围，把验证阶段临时开放的写操作收回去。MCP 工具本质上是把账号能力交给了模型，收敛权限永远是性价比最高的一步。