MCP 与 Agent 接入

让支持 MCP 的 Agent 在授权范围内处理 TradeFlow 业务。连接页面显示当前部署的协议与授权；工具能力由服务端实际列表决定。

连接顺序

1. 打开「MCP 接入与使用」，复制当前公司显示的 OAuth 地址或连接配置。
2. 在支持 OAuth 的客户端添加连接，回到 TradeFlow 登录并选择独立凭证。
3. 阅读可用权限与业务范围，确认授权。
4. 连接后先发现工具列表和业务上下文，再读取具体对象；字段以当次工具 schema 为准。
5. 写入前检查预览、版本与对象，完成后回读。删除、外发与其他敏感操作使用工具要求的确认流程。

当前工具与部署范围

网站全产品适配已加入五种角色的OAuth连接：老板、业务员、仓库、会计、社媒运营。按本人岗位、对象归属、字段与平台管理权限执行。连接包的公开版本见下文，实际可用能力以你公司的部署和服务端发现结果为准。

• get_tradeflow_context：读取本人身份、公司范围、契约指纹与限制。
• list_business_operations：分类或关键词分页发现可用业务操作。
• get_business_operation_contract：读取路径、查询、正文、schema和原网站校验说明。
• execute_business_operation：按契约走真实业务路由，写入必须有稳定operationId。
• prepare_business_action：准备内容绑定预览票据；删除、外发、审批等仍需人类明确授权和原网站门禁。
• get_business_operation_result：读取本凭证持久回执，按COMPLETED、REJECTED、PENDING、UNKNOWN分别处理。
• execute_business_batch：最多20项独立顺序操作，不是整体事务；失败不回滚已完成项，UNKNOWN/PENDING停止后续项。
• read_business_response_file：按原回执读取导出文件后续真实字节，不重复执行导出。

旧Alibaba复盘与专项业务工具只在真实岗位和scope允许时出现。详见工具与操作字段参考。

用自然语言交办产品和订单

已请求的普通新建或修改可以连续完成查询、填写、保存与回读。只有真实资料缺失、对象有歧义或涉及删除、外发、付款、审批、归属及权限等敏感动作时，再核对相应事项。以下是任务表达示例，名称、价格与记录均为虚构样本。

新建带规格的产品

可以说：「按照已确认资料新建21V工具，单位台，录入电压规格、两电一充选配、箱规和报关要素。」Agent先检查目录是否重复，读取 post_products 的实时 wireInput.body，按确认资料填单位、规格稳定ID、选配和参数，保存后回读。图片须先取得已保存的上传引用，未知参数留待确认。

修改产品并保留其他配置

可以说：「把指定产品单位改为件，替换这份说明，其他规格和选配保留。」先查唯一型号或ID，按 put_products_by_id 提交授权字段，再回读同一对象。多条同型号记录要先选定；不从当前显示价反算历史订单金额。

新建客户订单

可以说：「给指定客户建立订单，选指定规格与选配，3件、每件18.50美元，运费7美元，按已确认地址交付。」先查真实客户、规格ID、单位及有效付款档案，再读 post_orders.wireInput.body。样本合计62.50美元由网站计算；不能编造银行资料、收款证据或负责人。保存后回读订单号、客户、商品行、金额、币种和状态，PI草稿与正式成交分别核对。

修改订单并核对版本

可以说：「给指定订单增加已确认的包装备注，保留商品和金额。」先读取当前 editVersion，用 put_orders_by_id 修改并回读。409表示版本冲突，先查新状态；PENDING或UNKNOWN保持原operationId查询回执，避免重复写入。修改数量、单价或币种时核对明确的新条款。

连接包、Skill与更新

Skill 是 Agent 的 TradeFlow 操作手册，教它先查资料、使用真实字段、保存后回读，以及遇到错误如何继续。MCP 是调用功能的通道，Skill 不增加权限、也不替代 OAuth 登录。它包含产品与订单、客户复盘、单据、仓库、财务、日程和各平台接入等具体步骤。

公开连接包 @calvinqin/tradeflow-mcp 1.0.4 是已发布的预发布候选，需 Node.js 22以上。MCP页面的「GitHub仓库」可打开公开源码与操作手册，「下载Skill」可进入发布列表。当前同源业务测试147项与单次合成付费月结1项通过；严格全站门禁仍保留Meta实际广告执行与阿里到期续授权两项未验，外部前提检查不代表供应商动作成功。从 v1.0.4预发布页 下载 ZIP连接包与Skill，或取得 TGZ包。先核对同一发布页提供的SHA256SUMS，再安装到当前Agent实际支持的Skill目录；公司网站部署与客户端实际OAuth连接分别验证。

解压ZIP后，在包目录运行：

node bin/tradeflow-mcp.mjs config https://YOUR-COMPANY/api/mcp
node bin/tradeflow-mcp.mjs install-skill --dir /YOUR/AGENT/skills

把生成的HTTP配置导入支持远程MCP/OAuth的Agent，选择OAuth并点击认证。PKCE、令牌存储与续期由接收配置的客户端负责；包本身不代理或保存令牌。

node bin/tradeflow-mcp.mjs update-skill --dir /YOUR/AGENT/skills
node bin/tradeflow-mcp.mjs contract

安装器只更新本包管理的Skill并保留旧目录备份，不覆盖其他Agent配置。update-skill安装的是当前已下载的包，不会自己下载新版。

页面可复制「Skill安装与自动更新提示词」。把它交给支持本地Skill和文件执行的Agent：首次完成安装；以后每次开始TradeFlow任务，先比对包内契约与get_tradeflow_context.contractHash。变化时自动从官方发布页取得匹配的新版包，核对校验和、更新到原目录并重新加载手册；没有匹配版本时使用服务器实时契约并说明。当前Agent不支持Skill或文件执行时，应明确说明，不能声称已经安装或自动更新。这个机制在任务开始时检查，不是后台定时更新服务。

授权失效时重新连接。撤销或删除凭证停止访问，业务历史仍保留。批量、分页和文件读取要继续处理hasMore/nextCursor或offset；第一页不代表全部。文件单块最多256KiB，写导出原件可读取7天；网站业务接口仍有自己的上传与响应限制。

Alibaba 客户复盘

Accio 模板用于指定复盘任务，普通 Agent 连接不必执行该模板。复盘先核对店铺、买家与双方沟通时间，再补充真实背景和标签；无法确定归属的记录先复核，不强行绑定。修正旧复盘时保留版本并回读结果。

排错

• 连接失败：检查公司地址、客户端的 OAuth 支持及页面提示；使用页面提供的连接帮助。
• 缺少工具：重新发现工具列表，检查当前角色和凭证权限，不假定所有工具都会出现。
• 保存结果未知：先查原对象或回执，确认后再决定重试，避免重复创建。
• 更新：先核对服务端指纹，再从公开发布页下载匹配版本，按上文更新Skill。