内容
# 竞争对手促销代理工具包
一个开放的、自托管的工具包，用于当前的竞争对手促销审计：
- 一个 [代理技能](https://openagentskills.dev/) 工作流程；
- 一个 [MCP](https://modelcontextprotocol.io/) 服务器，用于本地和远程代理；
- 一个适用于仅具有 shell 访问权限的代理的 CLI；
- Playwright 证据捕获；
- 带有每个品牌截图嵌入其行的 Excel 报告。
[中文说明](README.zh-CN.md)
该存储库是最低前期成本部署：开源且自托管。它不包括帐户、计费、云存储或托管服务。
## 它如何保持代理中立
| 代理能力 | 集成 |
|---|---|
| 代理技能 + MCP | 安装技能并连接 MCP 服务器 |
| 仅 MCP | 直接调用三个 MCP 工具 |
| 仅 shell 访问权限 | 运行 `promo-audit capture` 和 `promo-audit report` |
| 既没有技能也没有 MCP | 使用可重用的提示并通过代理的执行工具调用 CLI |
没有适用于所有代理产品的通用一键安装程序。代理技能提供工作流程，MCP 提供可互操作的工具，CLI 是备用方案。
测试集成目标：
- Codex 个人技能加本地或远程 MCP；
- Claude 自定义技能上传加远程 OAuth MCP；
- Claude Code 个人/项目技能加本地或远程 MCP；
- OpenClaw 托管技能加本地或 Streamable HTTP MCP；
- 通用代理技能和 MCP 客户端。
## 服务器的作用
服务器故意将证据收集与解释分开：
1. `capture_promotion_pages` 捕获官方网站截图、可见文本、最终 URL、时间戳和促销链接候选者。
2. 连接的代理确定哪些显式声明得到该证据的支持。
3. `build_promotion_report` 创建比较工作簿，并将一到三张截图嵌入每个品牌行。
4. `read_promotion_artifact` 返回一个生成的工件作为嵌入的 MCP 资源，供远程客户端使用。
它不强制关联 Prime Day 或假期。报告使用在最新的捕获官方页面上实际可见的促销活动。
## 一键安装
对于在 macOS 或 Linux 上运行的 Codex、Claude Code 或 OpenClaw，将匹配的命令粘贴到终端中或要求代理运行：
```bash
# Codex
curl -fsSL https://raw.githubusercontent.com/ljh1097912305-wq/competitor-promo-agent-kit/main/install.sh | bash -s -- codex
# Claude Code
curl -fsSL https://raw.githubusercontent.com/ljh1097912305-wq/competitor-promo-agent-kit/main/install.sh | bash -s -- claude-code
# OpenClaw
curl -fsSL https://raw.githubusercontent.com/ljh1097912305-wq/competitor-promo-agent-kit/main/install.sh | bash -s -- openclaw
```
仅运行针对目标代理的命令。安装程序：
1. 在机器没有 Node.js 22 运行环境时安装一个私有的 Node.js 22 运行环境；
2. 下载并验证 `v0.3.0` 运行环境包；
3. 安装生产依赖项和 Playwright Chromium；
4. 在目标的个人技能目录中安装代理技能；
5. 注册并探测本地 stdio MCP 服务器。
命令完成后，重启代理或打开新的会话。重新运行相同的命令会更新安装。
此路径需要具有终端执行权限的代理。Claude web、Cowork 和其他无 shell 云客户端仍然需要技能上传加上可达的远程 MCP 部署。
## 手动本地安装
要求：Node.js 22+ 和 pnpm。
```bash
corepack enable
pnpm install
pnpm exec playwright install chromium
node ./src/cli.mjs --help
```
捕获六个示例电子自行车品牌：
```bash
node ./src/cli.mjs capture \
--input ./examples/inputs/capture-six-ebike-brands.json \
--output ./data/current-audit
```
连接的代理读取 `data/current-audit/capture-manifest.json`，创建经过验证的报告输入，然后运行：
```bash
node ./src/cli.mjs report \
--input ./report.json \
--output ./data/competitor-promotion-comparison.xlsx
```
## 通过 stdio 进行本地 MCP
安装依赖项，然后将 [stdio 示例](examples/mcp-configs/stdio.json) 适配到您的代理使用的 MCP 配置格式。下层过程是：
```bash
node /absolute/path/to/src/cli.mjs mcp \
--data-dir /absolute/path/to/promo-data
```
服务器在 `--data-dir` 下写入所有截图、清单和工作簿。
## 用于云代理的远程 MCP
启动一个受 OAuth 保护的 Streamable HTTP 端点：
```bash
OAUTH_ENABLED=1 \
OAUTH_ADMIN_PASSWORD='replace-with-a-long-random-password' \
HOST=0.0.0.0 \
PORT=3000 \
PUBLIC_BASE_URL='https://promo-mcp.example.com' \
node ./src/cli.mjs serve
```
将云代理连接到：
```text
https://promo-mcp.example.com/mcp
```
客户端发现 OAuth 元数据，动态注册并打开一个同意页面。输入 `OAUTH_ADMIN_PASSWORD` 以授权它。访问和刷新令牌在 `DATA_DIR/.oauth/` 下持久存在，具有仅限所有者的文件权限。
通过反向代理使用 TLS，并遵循 [安全指南](SECURITY.md)。生成的 文件可通过 `read_promotion_artifact` 获取；通过 `/files/` 也可以进行身份验证的 HTTP 下载。
## Docker
包含的 Compose 配置默认情况下仅限本地使用：
```bash
docker compose up --build -d
curl http://127.0.0.1:3000/health
```
输出出现在 `./data` 中。要使服务可被云代理访问，请更改发布的端口，启用 OAuth，设置公共 HTTPS URL，并将其放在 TLS 反向代理后面。
在没有 Compose 的情况下构建：
```bash
docker build -t competitor-promo-agent-kit .
docker run --rm \
-p 127.0.0.1:3000:3000 \
-e ALLOW_INSECURE_REMOTE=1 \
-v "$PWD/data:/data" \
competitor-promo-agent-kit
```
对于公共 HTTPS 部署，将域的 DNS 指向服务器并运行：
```bash
DOMAIN=promo-mcp.example.com \
OAUTH_ADMIN_PASSWORD='replace-with-a-long-random-password' \
docker compose -f compose.remote.yaml up --build -d
```
远程 Compose 文件添加 Caddy 以实现自动 TLS，并将 MCP 容器保留在反向代理后面。
## Claude
Claude web、Cowork 和 Claude Desktop：
1. 在 **自定义 → 技能** 中上传发布文件 `capture-competitor-promotions-claude-skill-v0.3.0.zip`。
2. 添加 `https://promo-mcp.example.com/mcp` 作为自定义连接器。
3. 使用部署密码完成 OAuth 同意页面。
Claude Code：
```bash
curl -fsSL https://raw.githubusercontent.com/ljh1097912305-wq/competitor-promo-agent-kit/main/install.sh | bash -s -- claude-code
```
这安装了个人技能和本地 MCP 服务器。对于项目本地技能或远程 OAuth MCP 部署，请使用上面的手动设置。
## Codex
```bash
curl -fsSL https://raw.githubusercontent.com/ljh1097912305-wq/competitor-promo-agent-kit/main/install.sh | bash -s -- codex
```
这在 `~/.codex/skills/` 中安装了技能，并在 Codex 中注册了本地 MCP 服务器。仅限技能的发布文件是 `capture-competitor-promotions-codex-skill-v0.3.0.zip`。
## OpenClaw
```bash
curl -fsSL https://raw.githubusercontent.com/ljh1097912305-wq/competitor-promo-agent-kit/main/install.sh | bash -s -- openclaw
```
这安装了托管技能，注册了本地 MCP 服务器，并在完成前对其进行了探测。对于远程 OAuth，请使用 [远程配置示例](examples/mcp-configs/openclaw-oauth.json)。
## 其他代理技能客户端
```bash
node ./src/cli.mjs install-skill --path /custom/agent/skills
```
连接相同的远程 MCP 端点。如果代理既不支持技能也不支持 MCP，请使用 [可重用提示](prompts/competitor-promotion-audit.md) 与 CLI。
## MCP 工具摘要
| 工具 | 目的 |
|---|---|
| `capture_promotion_pages` | 捕获每个品牌的一到三个官方网站证据页面 |
| `build_promotion_report` | 创建带有截图嵌入品牌行的比较工作簿 |
| `read_promotion_artifact` | 通过 MCP 传输生成的工件 |
输入和输出示例在 [技能参考](skills/capture-competitor-promotions/references/manifest-schema.md) 中有文档记录。
## 安全默认值
- 正常的截图而不是无边界的全页捕获；
- 每个品牌的三截图硬限制；
- 显式提供的官方 URL；
- 默认情况下阻止 localhost 和私有网络浏览器目标；
- `DATA_DIR` 下的输出路径限制；
- 默认情况下仅限 localhost 的 HTTP 绑定；
- 具有 PKCE、动态客户端注册、刷新令牌轮换和受保护资源发现的 OAuth 2.1；
- 非环回绑定所需的承载者或 OAuth 身份验证，除非显式覆盖。
## 开发
```bash
pnpm run check
pnpm test
```
测试套件涵盖了浏览器证据捕获、嵌入截图的 Excel 生成、技能安装、stdio 和 Streamable HTTP MCP 发现，以及完整的 OAuth 发现/注册/PKCE/令牌/刷新流程。
## 许可证
MIT
