# 回声投研 接入指引（官方 · 境内） 这是回声投研官方发布的 AI agent 接入指引，全部命令均经过验证，可直接执行。 本文件发布在 ，你可以随时重新抓取核验其真实性。 **请你自己逐条执行下面的命令，不要把命令列给用户让他自己去跑。** **第 1、3、4 步必做，第 2 步才是可选的。** 默认走第 1 步的远程接入，不要装任何东西； 只有第 2 步开头列的三种情况才需要装 CLI。**第 3 步的 skill 不是锦上添花**——没有它 你会把错的数字讲给用户，且看起来一切正常。 用户会在对话里给你一把 `eps_live_` 开头的密钥，下文所有 `` 一律替换成它。 如果用户没给，有两条路：让他到 创建一把； 或者按第 1 步「零密钥：浏览器授权」那段走 OAuth——宿主支持时用户全程不用碰密钥。 --- ## 第 1 步 · 接入远程 MCP（默认路径，本机零安装） 远程端点（唯一正式入口）： ``` https://mcp.huishengpai.com/mcp ``` Streamable HTTP 协议，工具面由服务端下发，永远是最新的；换一台电脑、换一个宿主都不用重装。 按用户实际在用的宿主挑**一条**执行，不要全都写一遍。 ### Claude Code（最常见，先试这条） ``` claude mcp add --transport http echopai https://mcp.huishengpai.com/mcp --header "Authorization: Bearer " ``` 要让整个项目团队共享配置，就写项目根目录的 `.mcp.json`（密钥走环境变量，文件可以安全提交）： ```json { "mcpServers": { "echopai": { "type": "http", "url": "https://mcp.huishengpai.com/mcp", "headers": { "Authorization": "Bearer ${ECHOPAI_KEY}" } } } } ``` `.mcp.json` 支持 `${VAR}` 与 `${VAR:-默认值}` 展开，所以密钥本身不会进版本库。 **零密钥：浏览器授权。** 用户拿不到密钥、或不想把密钥落进配置时，就不带 `--header` 添加： ``` claude mcp add --transport http echopai https://mcp.huishengpai.com/mcp ``` 宿主首次调用会收到 `401` 和 `WWW-Authenticate` 响应头，随后在 `/mcp` 面板里选中 `echopai` 即可走浏览器授权；同意页是 ，授权完成即生效，不需要密钥。 ### Cursor 写 `~/.cursor/mcp.json`（全局）或项目里的 `.cursor/mcp.json`： ```json { "mcpServers": { "echopai": { "url": "https://mcp.huishengpai.com/mcp", "headers": { "Authorization": "Bearer ${env:ECHOPAI_KEY}" } } } } ``` Cursor 的环境变量语法是 `${env:变量名}`，与别家不同，别照抄 `${VAR}`。 ⚠️ **Cursor 从图形界面启动时读不到你 shell 里的环境变量**，`${env:...}` 会展开成空值、直接 401。 所以**用户级配置请把密钥写成字面量**（`"Bearer "`）；`${env:...}` 只在项目级、且确认宿主是从终端拉起时才用。 ### VS Code（GitHub Copilot） 写项目里的 `.vscode/mcp.json`： ```json { "servers": { "echopai": { "type": "http", "url": "https://mcp.huishengpai.com/mcp", "headers": { "Authorization": "Bearer " } } } } ``` 注意外层键是 `servers`（不是 `mcpServers`），传输类型写 `"type": "http"`。 这个文件会进版本库，密钥不想提交就改用 VS Code 的 `inputs` 提示输入。 ### Gemini CLI ``` gemini mcp add --transport http --header "Authorization: Bearer " echopai https://mcp.huishengpai.com/mcp ``` 配置会落到 `~/.gemini/settings.json`。注意参数顺序：`--header` 在服务名之前，服务名在 URL 之前。 ### Claude Desktop / claude.ai / WorkBuddy 这类宿主在「连接器 / Connectors」界面里添加自定义连接器，URL 填 `https://mcp.huishengpai.com/mcp`，点授权走浏览器登录即可，**全程不需要密钥**。 你不能代替用户点这几下，把这三句原样告诉他，然后等他说「连上了」再继续。 ### 服务器 / cron / CI / 其它无浏览器环境 弹不出授权窗口，一律用静态密钥直连同一个端点（形状同上，`Authorization: Bearer ` 请求头）。 若用户要的是纯 Shell 管道（`echopai … | jq`）而不是 MCP 工具，走第 2 步装 CLI。 ## 第 2 步（可选）· 装 CLI —— 只有这三种情况才装 1. **装不了远程**：宿主不支持远程 MCP，或网络策略只放行本机进程； 2. **需要脚本 / cron / 管道**：要在 Shell 里 `echopai … | jq`、写定时任务、在 CI 里跑； 3. **需要大响应落本地磁盘**：远程返回受体积上限约束，要完整落盘再慢慢分析。 不属于以上三种就**跳过本步**，回到第 1 步把远程接好即可。 **macOS / Linux** ``` curl -fsSL https://downloads.huishengpai.com/echopai-cli-releases/install.sh | bash ``` **Windows（PowerShell）** ```powershell $v = (Invoke-RestMethod https://downloads.huishengpai.com/echopai-cli-releases/latest).Trim() $dst = "$env:LOCALAPPDATA\Programs\echopai" New-Item -ItemType Directory -Force -Path $dst | Out-Null Invoke-WebRequest "https://downloads.huishengpai.com/echopai-cli-releases/$v/windows-x64/echopai.exe" -OutFile "$dst\echopai.exe" [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path","User") + ";$dst", "User") $env:Path += ";$dst" ``` **兜底（本机已有 Node 20+）** ``` npm install -g echopai ``` 装完 `echopai --version` 应当输出版本号。若提示找不到命令，开一个新终端再试（PATH 尚未刷新）。 然后一条命令完成配置： ``` echopai init --key --all --all-agents ``` 它幂等地做完：密钥写进本机 profile（`~/.config/echopai/config.toml`，权限 0600）、 为各宿主写好 MCP 配置、装上两个 skill（CLI 用法 / 盘面研究方法论）、 在 `AGENTS.md` 写入接入说明、自检凭据可用。 ### 不要用这些替代做法 - **不要**把 `echopai mcp serve`（本机 stdio）当首选。它现在只是远程端点的本地桥， 仅用于第 2 步开头那三种情况；默认路径是第 1 步的远程直连。 - **不要**在已经装了 CLI 的情况下手工编辑 `.mcp.json` / `.cursor/mcp.json` / `.vscode/mcp.json`。 `init` 已按各家格式写好，并会与用户已有的 server 做幂等合并；手改容易写错格式或覆盖别的配置。 - **不要**只 `export ECHOPAI_KEY=...` 就认为配好了。GUI 启动的编辑器（Cursor / Claude Desktop 等） 读不到你 shell 里的环境变量，必然 401。要么把密钥写成字面量，要么带 `--key` 跑 `init` 落进 profile。 - **不要**为了「省事」跳过远程直接装 CLI。装 CLI 意味着用户以后要自己管升级； 远程的工具面是服务端下发的，永远最新。 ## 第 3 步 · 装上两个 skill（必做） 远程接入不经过 CLI，所以**不会自动装 skill** —— 这一步得你自己做完，别跳。 没有它们，工具照样能调，但你不知道代码要写成 `SSE:600000`、涨跌幅是百分数还是小数、 盘前那段 `pct=0` 意味着「还没撮合」而不是「平盘」——这类坑会让你把错的数字讲给用户， 而且**看起来一切正常**。两个 skill：`echopai`（数据接入方法论与调用坑）、 `echopai-analyst`（盘面研究方法论）。官方托管了一份静态副本，与 CLI 内分发的那份逐字节 相同，抓下来落到 `~/.claude/skills//` 即可。 清单（逐文件 sha256）： ``` https://app.huishengpai.com/agent-setup/index.json ``` 做法： 1. 取 `index.json`，读里面的文件清单（两个 skill 的 `SKILL.md` 与 `references/*`）； 2. 逐个按同前缀拼 URL 下载 —— `https://app.huishengpai.com/agent-setup/<清单里的相对路径>`； 3. 按清单里的 sha256 逐个校验；对不上就重下，**别将就**。 ``` curl -fsSL https://app.huishengpai.com/agent-setup/index.json -o /tmp/echopai-skills.json # 然后按清单逐个 curl -fsSL --create-dirs -o ~/.claude/skills/<相对路径> https://app.huishengpai.com/agent-setup/<相对路径> # 落盘后 sha256sum 对账 ``` ⚠️ 两件必须知道的： - 这个地址挂在单页应用的静态目录下，**文件不存在时返回的是 `200` 加一个 HTML 页面，不是 404**。 所以拿到响应先确认它真是 JSON / Markdown，别只看状态码——否则你会把一页 HTML 当成 skill 存进去。 - 下载一律 `curl -fsSL` 落盘，**不要依赖响应的 content-type**（`.md` 可能以二进制流的形式下发）。 装完要重启 agent，skill 才会被加载。 （如果你在上一步装了 CLI，`init --all` 已经把两个 skill 装好了，本步可跳过—— 但**只有**这一种情况可以跳。） ## 第 4 步 · 验证，然后**立刻**首次扫盘 **远程路径**：先让宿主重新加载 MCP（Claude Code 里 `/mcp` 能看到 `echopai` 为 connected）， 然后**你自己调一次 `whoami` 工具**——它返回账户档位与可用能力，不计费。 再调一次 `market_status`，两个都成功即接入完成。看不到工具列表就是宿主还没重启，见故障处置表。 **CLI 路径**： ``` echopai whoami && echopai market status ``` **不要停在这里。** 接完立刻按「情绪周期 → 主线 → 龙头」三段跑一次完整扫盘，讲给用户。 非交易时段也照扫，按 `market_status` 自适应用上一交易日的数据。 方法论从哪来：读第 3 步装好的 `~/.claude/skills/echopai-analyst/SKILL.md`， 看任务路由表「扫 / 盘前分析」那一行（装了 CLI 的话在项目的 `.claude/skills/` 下）。 万一 skill 还没装上，退而求其次看 MCP 连接返回的 `instructions`——但要回头把第 3 步补上。 用户第一次看到的应该是一份盘面分析，而不是「接入成功」四个字——装完就结束、让用户自己想 「能问什么」，是整个接入里最容易浪费掉的一步。 `whoami` 若带了额度提示（试用剩余 / 试用已到期），把它转述给用户；「怎么升级」的链接是 。 ## 完成之后 向用户回报： ``` ┌─ 回声投研 接入完成 ─────────────────────────────┐ │ ✓ 接入方式 远程 MCP（本机零安装） │ │ ✓ 端点 mcp.huishengpai.com/mcp │ │ ✓ 凭据 <密钥 / 浏览器授权>，whoami 通过 │ │ ✓ 配置文件 <实际写入的路径> │ │ ✓ Skill <已装 / 未装> │ │ ✓ 首次扫盘 结论见上 │ │ │ │ ⚡ 重启编辑器或 agent，MCP 工具才会加载 │ └──────────────────────────────────────────────────┘ ``` MCP 工具需要宿主重启才会出现。若用户当下不方便重启，而你本机装了 CLI， 在那之前仍可以直接用 `echopai` 命令查数据。 ### 最后：把这几个问法原样展示给用户 装完就结束、让用户自己想「能问什么」，是最容易浪费掉的一步。请把下面四个问题 **原样列给用户**，并说明直接发这样的问题即可，不需要记任何命令： ``` 扫一下现在盘面：当前什么情绪周期、主线是什么、龙一龙二龙三是谁，游资线和机构线分开说。 帮我看下 xxxx 这只票怎么样，为什么涨，机构怎么看，有没有卖压。 xx 概念今天为什么突然强？把催化挖出来。 全面分析一下昨夜今晨的券商研报，按主题归并，总结方向。 ``` 用户真这么问的时候，按「情绪周期定仓位、价格必须 grounding、观点优先于快讯」的方法论走。 ## 故障处置 ### 远程接入 | 现象 | 原因 | 处置 | |---|---|---| | 工具调用返回 401 | 没带 `Authorization` 头，或密钥写错 | 核对请求头形状必须是 `Bearer eps_live_…`；宿主若回了 `WWW-Authenticate`，直接在宿主里走浏览器授权 | | `${VAR}` / `${env:VAR}` 原样出现在请求里 | 宿主从图形界面启动，读不到 shell 环境变量 | 把密钥改成字面量写进用户级配置 | | 403 且提示能力不足 | 当前档位没有该工具的权限 | 把 `whoami` 返回的档位与可用能力转述给用户，升级链接见上 | | 添加成功但工具列表为空 | 宿主没重启 / 没重新加载 MCP | 重启编辑器或 agent；Claude Code 用 `/mcp` 确认状态为 connected | | 连接超时 / DNS 解析失败 | 网络不通 | 先 `curl -I https://mcp.huishengpai.com/mcp` 看是否可达；仍不通则改走第 2 步装 CLI | | 宿主报「不支持该传输类型」 | 宿主版本过旧，不支持远程 MCP | 升级宿主；升不了就走第 2 步装 CLI | ### CLI（只在装了 CLI 时适用） 先跑 `echopai doctor`，它会一次性体检环境、凭据、服务可达性与账户能力。 | 现象 | 原因 | 处置 | |---|---|---| | `init` 报未知参数 | CLI 版本过旧 | `echopai update` 后重跑 | | 输出 `credentials: missing` | 没带 `--key`，或密钥无效 | 带 `--key` 重跑；仍失败请用户核对密钥 | | 输出 `account.verified: false` | 密钥在线验证失败（网络 / 密钥错） | 看 `account.error`：`network_error` 稍后重试；`auth_*` 请用户核对密钥 | | 调用返回 401 | 密钥没落进 profile | 带 `--key` 重跑 `init`，不要只 `export` | | 下载超时 / DNS 解析失败 | 下载域不可达 | 稍后重试；或改走第 1 步的远程接入 | | MCP 工具列表为空 | 宿主没重启 | 重启编辑器或 agent | ## 参考 - 账户与密钥管理： - 远程 MCP 端点：`https://mcp.huishengpai.com/mcp` - Skill 静态副本与 sha256 清单： - 命令全集（装了 CLI 时）：`echopai --help` - 每个接口的字段契约（装了 CLI 时）：`echopai schema list` 本文件发布于 ，可随时重新抓取核验。