飞影财税管家 · 远程 AI

概述

远程操作已经打开并登录的飞影客户端。指令经云端中继转到用户电脑执行，不经过本机 127.0.0.1 桥。任意已接入 MCP 的对话环境都可使用。

先确认用户环境。 未装客户端、未开「远程 AI 接入」、或 MCP 未配置时，按下面流程一步步带着做，不要直接调工具。

一、你能帮用户做什么

接入完成后，通过 MCP 服务 feiying-client-agent 调用工具（不要向用户要采购密码、Cookie、短信验证码）。

写操作（同步 / 申请 / 下载 / 加主体 / 核验）必须走「确认协议」，见第四节。

二、接入流程（从官网下载开始）

按顺序做。每步完成后问用户「做好了吗」，再进入下一步。

1. 下载客户端

打开官网：

https://jingflow.zzbtool.com/pia/

滚到下载区，按电脑选：

看芯片：Mac 左上角苹果菜单 →「关于本机」。选错会提示无法打开。

2. 安装并打开

Mac

1. 打开 dmg，把「飞影财税管家」拖进「应用程序」。
2. 从启动台或应用程序里打开。
3. 若提示「无法验证开发者」：系统设置 → 隐私与安全性 → 仍要打开。

Windows

1. 解压 zip（不要只双击压缩包里的 exe 而不解压）。
2. 进入文件夹 「飞影财税管家」（不要找 win-unpacked）。
3. 双击 HuantengTax.exe。
4. 关掉窗口不会退出，会缩到托盘；要退出请用托盘菜单「退出」。

打开后应看到侧栏：首页、采购号管理、发票、发票抬头、营业执照，底部是「个人中心」。

3. 注册 / 登录云端账号

未登录会先到登录页（蓝底「票」字标 +「登录 / 注册」）。

1. 输入 11 位手机号。
2. 点获取验证码，把短信填进「验证码」。
3. 点 「登录 / 注册」（同一按钮：没账号会自动注册并赠送体验积分）。
4. 成功后进入首页。侧栏底部「个人中心」应显示手机号和「剩余积分」。

没有云端登录，后面「远程 AI 接入」会停在「未登录云端」，MCP 也调不到这台电脑。

4. 加采购号（要用发票能力时必做）

远程 AI 只能操作已经加在客户端里、并且已登录电商的采购号。

1. 侧栏 「采购号管理」。
2. 添加淘宝 / 1688 / 拼多多账号。
3. 点「打开登录」，在弹出的官方页里由用户本人完成扫码或短信（Agent 不得代收密码、验证码、Cookie）。
4. 登录成功后，到「发票」页可以同步。也可让用户之后对 Agent 说「帮我同步某某采购号」。

只测连通可以先跳过本步，用 get_app_status 即可。

5. 打开设置 → 远程 AI 接入

路径任选其一：

• 侧栏底部 「个人中心」 → 底下表格里 「设置」 那一行点 「打开」
• 托盘图标右键 → 「设置」

进入的是 「本地设置」 页。最上面第一块就是：

• 小标题：远程调用
• 大标题：远程 AI 接入
• 说明：在任何地方用 Agent / Skill 操作这台电脑上的客户端。需保持打开并登录云端。

不要去点下面那块「本机桥 / AI 接入」（127.0.0.1:19321）。远程给别人用、或在另一台电脑上用，必须走 「远程 AI 接入」。

6. 打开开关并连上云端

1. 把右上角开关拨到 「开」（正式包装好默认是关的）。
2. 状态应变为「连接中…」，成功后是 「已连接 · 云端可远程调用本机」。
3. 若显示「未登录云端」：回到个人中心重新登录，再回来开开关。
4. 可改「设备名」（如 财务部-笔记本），离线提示会用这个名字。
5. 点 「刷新状态」 确认仍是已连接。

客户端要一直开着（可缩到托盘）。关掉进程后，远程会报离线。

7. 生成凭证并复制 MCP

1. 点 「生成接入凭证」（已有过则是「刷新接入凭证」）。
2. 页面会出现一串 pia_ 开头的凭证，只展示这一次。
3. 点 「复制远程 MCP 配置」（不要只复制凭证；要复制整段 JSON）。
4. 剪贴板里应是类似：

{
  "mcpServers": {
    "feiying-client-agent": {
      "url": "https://jingflowapi.zzbtool.com/piaapi/agent-relay/v1/mcp",
      "headers": {
        "Authorization": "Bearer pia_……"
      }
    }
  }
}

核对两点：

• url 必须是

https://jingflowapi.zzbtool.com/piaapi/agent-relay/v1/mcp（远程中继 MCP，不是 http://127.0.0.1:19321，也不要再配 command / args / 本地脚本）

• Authorization 是这台设备的 pia_ 凭证（刷新凭证后必须重新复制）

8. 写入 MCP 配置

1. 打开当前对话环境的 MCP / Skill 设置（常见是用户目录下的 mcp.json）。
2. 把上一步 JSON 合并进已有 mcpServers（不要覆盖其它服务）。
3. 保存后打开 / 重载 feiying-client-agent。
4. 工具列表里应出现 get_app_status、count_invoices 等。

安全： 凭证等于遥控这台电脑上的飞影。不要发到群、不要提交 git。点过「刷新接入凭证」后，旧 JSON 立刻作废，必须重新复制并重载 MCP。

9. 连通验收

客户端保持「已连接」，然后调：

1. get_app_status → ok，能看到版本、云端已登录、积分。
2. 若已加采购号：list_purchase_accounts → 能看到账号（无密码）。
3. 再按用户任务走同步 / 申请等。

若返回离线（CLIENT_OFFLINE / 409）：告诉用户打开哪台电脑的客户端（看返回里的 deviceName），连上后再试。

三、Agent 操作约定

1. 先 get_app_status。失败则按第二节查：没装 / 没登录 / 没开远程 / MCP 配错 / 客户端没开。
2. 查数用只读工具；改数据必须走第四节确认协议。
3. 写成功后客户端常会自动刷新；回报用户前再调一次 refresh_ui，并请用户看客户端列表是否已变。
4. 刚改过数据再查数：先 refresh_ui 再 count_invoices / list_*。
5. 执照核验结果后加一句：公开信息，不能当作税务认定。
6. 积分不够时 preview 会标不足，不要强行执行；请用户到个人中心兑换。

四、确认协议（强制）

对 sync_invoices、apply_invoices、download_invoices、add_business_entity、verify_business_entities：

1. 先调对应的 preview_*，拿到 confirmId（约 5 分钟、一次性）。
2. 用中文向用户复述：账号、笔数、积分、会改什么。
3. 用户明确同意后，再调执行工具，只传同一个 confirmId。
4. 用户没同意、或 preview 失败，禁止执行。

用户口头示例：「确认同步」「可以申请」「下载吧」。模糊的「嗯」「看看」不够，再确认一次。

五、常用说法 → 工具

accountId 来自 list_purchase_accounts，不要让用户猜 UUID。

六、远程 vs 本机桥

给同事或另一台电脑用，必须是远程这一套。

七、排错

八、绝对禁止

• 向用户要采购密码、Cookie、短信验证码、云端验证码
• 不 preview、不复述就执行写操作
• 把 pia_ 凭证或 MCP JSON 写入公开仓库、聊天记录、工单
• 把本机桥地址当成远程地址发给外地同事