eCan.ai 用户手册

什么是 eCan.ai？

eCan.ai（电商智能体网络，E-Commerce Agent Network）是一个 AI 原生平台，让电商卖家能够用 AI 智能体自动化业务的每个环节——从商品采购到销售、从营销调研到广告投放、从法律咨询到客户服务——最大程度减少人工干预。

智能体运行在载体（host computer，即主机）上，通过局域网或广域网相互连接。一台电脑充当指挥节点，其他电脑作为承载智能体的载体节点。参谋设备（PC、手机或平板）可通过互联网远程监控和指挥整个智能体网络。

核心概念

智能体（Agent）

智能体是 eCan.ai 中的核心执行者。每个智能体有名称、头像及一组可执行的任务。智能体运行在载体（主机）上，通过渠道与人类或其他智能体进行通信。

任务（Task）与技能（Skill）

任务是分配给智能体的具体工作（例如"每天监控商品价格"）。每个任务都需要一个技能——一个基于 LangGraph 的工作流，描述如何完成这项工作。技能可以在技能编辑器中可视化构建，也可以直接用 Python 编写。

任务可以由人工命令触发、按一次性计划执行，或按周期性计划执行（例如每天 08:00）。

载体（Vehicle）

载体是承载一个或多个智能体的任何计算机（桌面电脑、服务器、虚拟机）。载体加入 eCan.ai 网络后，从指挥节点接收任务分配。

技能（Skill）

技能存储在 $SKILL_ROOT/my_skills/ 目录下。图形化表示存放在 diagram_dir 子目录；直接编写的 LangGraph 技能存放在 code_dir。两者可以共存，并可相互转换。

安装

桌面客户端（Windows / macOS）

从 ecan.ai/download 下载最新安装包。安装程序内置了 Python、所有依赖项及 Chromium 浏览器，无需单独安装 Python。

安装完成后，从应用程序目录或开始菜单启动 eCan.ai。首次启动时会提示创建账户或登录。

无界面服务器模式（Linux / Ubuntu）

对于无 GUI 的服务器部署，eCan.ai 以 Web 模式运行——一个通过 WebSocket/REST 接口交互的后端服务器。

sudo apt-get update
sudo apt-get install -y python3 python3-venv python3-pip \
    libpq-dev gcc libffi-dev tesseract-ocr poppler-utils git

git clone <仓库地址> eCan.ai && cd eCan.ai
chmod +x scripts/deploy-ubuntu.sh
./scripts/deploy-ubuntu.sh setup

# 编辑 .env.web，填入您的大模型提供商密钥：
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
DASHSCOPE_API_KEY=...   # 通义千问 / 阿里云

./scripts/deploy-ubuntu.sh start
# 验证：curl http://localhost:8765/health

快速开始

智能体与任务

管理智能体

每个智能体有名称、描述、头像及默认任务分配。您可以创建多个智能体，并将其分配到网络中的不同载体（机器）上。

任务触发方式

多智能体 · 多任务

多个智能体可以同时运行，每个智能体在独立线程中并行处理不同任务。智能体之间通过 A2A 协议（Agent-to-Agent）进行通信——这是一个正在成为业界标准的开放式智能体间通信协议。

技能编辑器

技能编辑器是构建 LangGraph 工作流的可视化 IDE。它使用流程图画布，您可以在其中放置并连接节点来描述智能体的行为逻辑。

画布基础操作

添加节点

在画布空白处右键（或点击工具栏中的节点图标）打开节点选择菜单。选择节点类型后，点击画布上的目标位置放置节点。双击节点可打开其配置面板。

连接节点

从节点的输出端口拖拽到另一节点的输入端口，即可绘制一条边。将边的端点拖到空白处可删除该边；拖到其他输入端口可重新路由。

画布导航

• 平移：按住鼠标中键拖动，或在小地图中拖动视口。
• 缩放：Ctrl + 鼠标滚轮。
• 多选：按住 Shift，拖拽选择矩形框住多个节点。

多页签工作流

复杂的工作流可以拆分到多个页签（Sheet，即画布）上。使用右上角的页签菜单（图层图标）来添加、删除或重命名页签。

跨页签引用

调用另一个页签的逻辑：

1. 在被调用页签上添加 sheet-inputs 节点（声明输入名称）和 sheet-outputs 节点（声明输出名称）。
2. 在调用方页签上插入 sheet-call 节点，从下拉框中选择目标页签。
3. 在侧边栏中将每个输入/输出映射到常量或本地节点端口。

多页签工作流会保存为一个 -bundle.json 伴生文件。

数据流转 — 映射 DSL

节点之间通过共享的节点状态对象交换数据。由于每个工作流的状态结构各不相同，eCan.ai 使用基于 JSON 的映射 DSL来描述数据在节点间以及外部事件与节点状态之间的流转方式。

当工作流中断后需要恢复时（例如等待人工输入或定时器到期），相同的 DSL 也用于处理恢复载荷（resume payload）。

保存与加载

• 在编辑器中创建的技能保存在 $SKILL_ROOT/my_skills/diagram_dir/ 下。
• 手写的 LangGraph 技能存放在 code_dir/ 下。
• 数据映射 JSON 文件与这两个目录并列存放。
• 如需将 Python 编写的 LangGraph 技能可视化，调用 langgraph2flowgram() 生成流程图文件后即可在编辑器中查看和调试。

运行与调试

调试技能时，它作为特殊的开发任务在测试智能体下运行。如果您的工作流涉及聊天，测试消息需以 dev> 前缀开头，以路由到测试智能体。

断点

打开节点右上角菜单，切换断点开关。执行到断点时，流程在该节点执行前暂停。您可以检查和修改节点状态，然后继续运行。

受控执行

使用工具栏控制按钮：暂停 · 单步 · 继续 · 停止。当前正在执行的节点会显示运行动画。

测试运行

点击测试运行，在隔离环境中执行工作流。在输入面板中提供 JSON 输入；在输出面板中查看每个节点的输出及最终 End 节点的结果。

版本控制

• eCan.ai 云端（付费）：在 eCan.ai 的 Git 仓库中对技能进行版本管理，并可选择将技能商业化。
• 本地 Git：技能文件是纯 JSON 格式，直接在技能目录下 git init 即可。

节点参考

浏览器自动化

eCan.ai 集成了多个先进的网页自动化库，能够处理从常规爬取到在反爬电商网站上执行复杂多步骤操作的各类场景。

计算机视觉引导操作

当浏览器内自动化不够用时（弹窗、验证码、非标准 UI），eCan.ai 的 eCanOCR 服务提供屏幕理解和 CV 引导的鼠标/键盘操作——让您完全掌控任何桌面窗口或浏览器。

OCR 服务（eCanOCR）

eCanOCR 是一个将屏幕图像转换为结构化文本的 API 服务。它融合了 Tesseract 的速度与改进版 PaddleOCR 引擎的高精度，自动将原始 OCR 输出重组为层级化的段落、行和词语。

核心能力

• 图像转文本，含段落和行分割
• 图标识别（需配置图标模板）
• 基于锚点的内容提取——在页面上定义关键地标，精确定位动态内容
• 表格、日历和边界框区域提取

内容技能文件（.csk）

.csk 文件使用 JSON 指令集描述预期的页面内容。它定义锚点（独特的文本或图标地标）和信息区域（相对于锚点的感兴趣区域）。这使得智能体能够可靠地从重复出现的页面布局中提取结构化数据。

MCP 工具

eCan.ai 提供一套可流式传输的 HTTP MCP 工具，任何集成了 LLM 的工作流均可调用。这些工具分为五个类别：

多渠道集成

渠道系统让 eCan.ai 智能体能够接收并回复来自外部消息平台的消息。每个渠道适配器将入站消息规范化为统一格式，路由到智能体处理管道，再将回复发送回原始平台。

* 需要可公开访问的端点（例如通过 ngrok 或反向代理）。

快速配置

所有渠道配置位于 agent/agent_files/channels.json。启用渠道、填入凭证，重启 eCan.ai 后渠道管理器会自动启动。

{
  "channels": {
    "telegram": {
      "enabled": true,
      "bot_token": "您的机器人令牌",
      "allowed_chat_ids": [],
      "default_agent_id": ""
    }
  }
}

将 default_agent_id 设置为指定智能体 ID，可将该渠道的消息路由给特定智能体；留空则路由给第一个可用智能体。

Telegram 配置步骤

1. 在 Telegram 上与 @BotFather 对话 → 发送 /newbot → 复制机器人令牌。
2. 将令牌填入 channels.json 的 "telegram" 部分。
3. 重启 eCan.ai — 机器人立即上线。

Slack 配置步骤

1. 在 api.slack.com/apps 创建 Slack 应用。
2. 启用 Socket 模式，订阅 message.* 事件。
3. 将 bot_token 和 app_token 填入 channels.json。
4. 在频道中邀请机器人：/invite @您的机器人名称。

WhatsApp / Messenger / X（Twitter）

这些渠道需要公开可访问的 Webhook 端点。开发阶段可使用 ngrok：

ngrok http 8443   # WhatsApp
ngrok http 8444   # Messenger
ngrok http 8445   # X（Twitter）

在各平台的开发者控制台中注册 ngrok URL 为 Webhook 地址，然后在 channels.json 中填入对应凭证。

钉钉配置步骤

1. 在钉钉开放平台创建机器人应用。
2. 启用 Stream 模式，记录 AppKey（client_id）和 AppSecret（client_secret）。
3. 将凭证填入 channels.json 的 "dingtalk" 部分。
4. 在群聊中 @ 提及机器人，或通过单聊直接与其对话（单聊无需 @）。

头像系统

每个智能体可以设置静态图片头像或动态视频头像。头像文件存储在本地，并在后台自动同步到 AWS S3。

支持格式

S3 云端同步

上传后，文件先保存到本地，然后在后台线程中上传到 AWS S3，不阻塞界面操作。S3 URL 存入数据库，在智能体数据同步到云端时使用。

CLI 命令行参考

eCan.ai CLI 在无界面模式下提供对服务器和所有资源的完整控制，无需 GUI。

python ecan_cli.py --help          # 全局帮助
python ecan_cli.py version         # 显示版本
python ecan_cli.py status          # 系统状态

身份验证

python ecan_cli.py auth login -u 用户名 -p 密码
python ecan_cli.py auth status
python ecan_cli.py auth logout

资源命令

服务器管理

python ecan_cli.py server start                        # 后台启动
python ecan_cli.py server start --host 0.0.0.0 --port 8080
python ecan_cli.py server start --foreground           # 前台运行（调试用）
python ecan_cli.py server logs --follow                # 跟踪日志
python ecan_cli.py server stop

输出格式

大多数列表命令支持 --output table（默认）和 --output json（用于脚本化处理）：

python ecan_cli.py agents list --output json | jq '.agents[0].name'

服务器部署

环境变量

Docker 部署

docker-compose -f docker-compose.web.yml up -d
docker-compose -f docker-compose.web.yml logs -f

Nginx 反向代理（生产环境）

server {
    listen 80;
    server_name your-domain.com;
    location / {
        proxy_pass http://127.0.0.1:8765;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400;
    }
}

Systemd 服务（生产环境）

[Unit]
Description=eCan.ai Web Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/eCan.ai
EnvironmentFile=/opt/eCan.ai/.env.web
ExecStart=/opt/eCan.ai/venv/bin/python -m uvicorn web_server:app \
          --host 127.0.0.1 --port 8765
Restart=always

[Install]
WantedBy=multi-user.target

Web 模式限制

代理管理

eCan.ai 内置代理管理系统，支持通过 HTTP/SOCKS 代理路由浏览器自动化流量——这对于需要 IP 轮换或地理位置访问的电商工作流至关重要。

代理可以按智能体或按任务进行配置，自动应用于 Playwright、Selenium 及 HTTP 请求节点。

设置与 API 密钥

大模型提供商

为您希望使用的大模型提供商添加 API 密钥。密钥存储在 .env（桌面模式）或 .env.web（服务器模式）中。

应用内设置

从侧边栏打开设置，可配置大模型默认选项、浏览器自动化选项、内存限制、更新偏好等。更改无需重启即可生效。

键盘快捷键

技能编辑器

通用快捷键

常见问题与故障排查

技能编辑器无法加载

刷新页面，并确保 eCan.ai 后端服务器正在运行。在桌面模式下，检查系统托盘图标——如果显示错误，请重启应用。

智能体在渠道上无响应

1. 确认 channels.json 中已设置 "enabled": true。
2. 确保至少有一个智能体有正在运行的任务，且该任务的技能包含聊天节点或等待事件节点。
3. 查看应用日志中的 [ChannelBridge] 条目，查找"No agent available"或"dispatch_inbound error"等错误信息。
4. 对于 Webhook 类渠道（WhatsApp、Messenger、X）：确认 Webhook URL 可公开访问，且验证令牌与配置一致。

服务器无法启动

# 检查端口是否被占用
netstat -an | grep 8765
# 或使用不同端口
./scripts/deploy-ubuntu.sh start -- --port 8080
# 查看日志
./scripts/deploy-ubuntu.sh logs

LLM 调用失败

• 确认 .env / .env.web 中的 API 密钥已正确设置且有效。
• 检查提供商的 Token 配额是否充足。
• 对于本地 Ollama：确认模型已下载（ollama pull <模型名>），且设置中的 Base URL 正确。

浏览器自动化报错

• 运行 playwright install chromium --with-deps，确保内置浏览器存在。
• 对于 Selenium 工具：确认 ChromeDriver 版本与已安装的 Chrome/Chromium 版本匹配。
• 在无界面服务器上：屏幕截图和桌面自动化工具不可用——请改用 Playwright 或 Crawl4ai。

如何在代码节点中切换语言？

使用代码节点编辑器面板中 Monaco 编辑器上方的语言下拉框。支持 Python、JavaScript 和 TypeScript。

全部文档

各子系统的详细参考文档：

用户指南

部署与运维

架构与内部设计