左帮右臂 —— 部署与使用手册

版本：v1.1 | 更新日期：2026-06-22

Agent Hackathon 参赛作品 | 赛道：行业应用·智能制造

行业验证: 高端/机械(10GB真实工艺数据) · 磷化工 · 电力 · 白酒

📋 目录

• 一、环境要求
• 二、快速安装
• 三、配置说明
• 四、启动服务
• 五、功能验证
• 六、生产部署
• 七、昇腾 NPU 适配
• 八、数字员工配置
• 九、常见问题
• 十、API 参考

一、环境要求

基础环境

可选组件

检查环境

# 检查 Node.js
node --version
# 输出示例：v22.16.0

# 检查 pnpm（如未安装，用 npm 也行）
pnpm --version || npm --version
# 输出示例：10.22.0

# 检查 Git
git --version
# 输出示例：git version 2.47.0

# 检查网络连通性（如果需要连接 SCSAI）
curl -I http://your-SCSAI-server/scplm

二、快速安装

2.1 克隆代码

# 从 AtomGit 克隆（推荐 - 参赛主仓库）
git clone https://atomgit.com/tuan_zhang/bossagents.git
cd bossagents

# 或者从 GitHub 镜像克隆
git clone https://github.com/andyy1976/bossagents.git
cd bossagents

2.2 安装依赖

# 使用 pnpm（推荐）
pnpm install

# 或使用 npm
npm install --legacy-peer-deps

2.3 初始化配置

# 复制环境变量模板
cp .env.example .env

# （可选）编辑 .env 填入你的 LLM API Key

2.4 启动服务

# 开发模式
node server.js

# 或使用 PM2（生产推荐）
npm install -g pm2
pm2 start server.js --name "zuobangyoubi"

2.5 访问应用

打开浏览器访问：https://ylxt.chat

登录页面 → 输入 SCSAI 用户名密码 → 进入主界面

三、配置说明

3.1 配置文件体系

系统支持三层配置叠加（优先级从高到低）：

1. 环境变量 (.env)          ← 最高优先级（敏感信息）
2. config.yaml              ← 中间优先级（业务配置）
3. config-loader.js 默认值   ← 最低优先级（缺省值）

3.2 环境变量配置 (.env)

# ==========================================
# SCSAI PLM 连接配置
# ==========================================
SCSAI_SERVER=https://ylxt.chat/scplm
SCSAI_DATABASE=SCPLM
SCSAI_USERNAME=
SCSAI_PASSWORD=

# ==========================================
# LLM 配置（用于数字员工 AI 功能）
# ==========================================
LLM_ENDPOINT=https://api.deepseek.com/v1/chat/completions
LLM_API_KEY=your-api-key-here
LLM_MODEL=deepseek-chat
LLM_PROVIDER=deepseek

# ==========================================
# 昇腾 NPU 加速（可选）
# ==========================================
MTCLAW_ENABLED=false
MTCLAW_BASE_URL=http://127.0.0.1:18790/v1

# ==========================================
# 服务器配置
# ==========================================
PORT=3006
LOG_LEVEL=info

3.3 业务配置 (config.yaml)

# ==================== 部署模式 ====================
deployment:
  mode: local              # local | saas
  tenant_id: default

# ==================== SCSAI 配置 ====================
SCSAI:
  server: https://ylxt.chat/scplm
  database: SCPLM
  auth_type: basic          # basic | token
  username: ''
  password: ''
  timeout: 30000
  retry: 3
  enabled: true

# ==================== 服务器配置 ====================
server:
  port: 3006
  log_level: info
  cors: true

# ==================== 功能开关 ====================
features:
  version_management: true
  import_export: true
  search: true
  cost_optimize: true
  digital_staff: true       # 数字员工总开关
  natural_language: true    # 自然语言功能

# ==================== 数字员工配置 ====================
cron:
  enabled: false            # 定时任务总开关
  tasks: []                 # 任务列表

# ==================== 通知配置 ====================
notify:
  enabled: false
  feishu:
    enabled: false
    webhook_url: ''
    app_id: ''
    app_secret: ''
  email:
    enabled: false
    smtp_host: ''
    smtp_port: 465
    smtp_user: ''
    smtp_pass: ''

# ==================== MTCLAW 昇腾 NPU 集成 ====================
mtclaw:
  enabled: false
  base_url: "http://127.0.0.1:18790/v1"
  completion_mode: "permissive"   # permissive | strict
  upstream:
    endpoint: ""
    model: "deepseek-chat"

# ==================== 语音识别 ====================
asr:
  provider: echo
  timeout: 15000

四、启动服务

4.1 开发模式启动

# 标准启动
node server.js

# 指定端口启动
PORT=3007 node server.js

# 指定日志级别
LOG_LEVEL=debug node server.js

4.2 启动成功标志

看到以下输出表示启动成功：

[INFO] 日志系统初始化成功
[INFO] 配置加载完成
[INFO] SCSAI连接配置已初始化
[INFO] 开发模式: 静态文件预览
[INFO] 服务器启动成功 → https://ylxt.chat

4.3 启动前端开发服务器（可选）

# 启动 Vite 开发服务器（热更新）
npm run dev:vite
# 访问 http://localhost:5173

4.4 PM2 进程管理

# 安装 PM2
npm install -g pm2

# 启动
pm2 start server.js --name "zuobangyoubi"

# 查看状态
pm2 status

# 查看日志
pm2 logs zuobangyoubi

# 重启
pm2 restart zuobangyoubi

# 停止
pm2 stop zuobangyoubi

# 设置开机自启
pm2 startup
pm2 save

五、功能验证

启动后，按以下顺序验证核心功能：

5.1 基础功能

5.2 BOM 管理

5.3 变更管理

5.4 供应商管理

5.5 数字员工

六、生产部署

6.1 Nginx 反向代理

server {
    listen 80;
    server_name zuobangyoubi.yourdomain.com;

    # 网页端
    location / {
        proxy_pass https://ylxt.chat;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400s;
    }

    # WebSocket 支持（数字员工实时通信）
    location /ws {
        proxy_pass https://ylxt.chat;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400s;
    }

    # 大文件上传
    client_max_body_size 100M;
}

6.2 HTTPS 配置（Let's Encrypt）

# 安装 certbot
apt install certbot python3-certbot-nginx

# 申请证书
certbot --nginx -d zuobangyoubi.yourdomain.com

# 自动续期
certbot renew --dry-run

6.3 Docker 部署

# Dockerfile
FROM node:22-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install --legacy-peer-deps --production

COPY . .

EXPOSE 3006

CMD ["node", "server.js"]

# 构建镜像
docker build -t zuobangyoubi .

# 运行容器
docker run -d \
  --name zuobangyoubi \
  -p 3006:3006 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  -v $(pwd)/.env:/app/.env \
  -v $(pwd)/server/data:/app/server/data \
  -v $(pwd)/generated:/app/generated \
  --restart always \
  zuobangyoubi

# 查看日志
docker logs -f zuobangyoubi

6.4 数据库选择

| 模式 | 适用场景 | 配置方式 |

|------|----------|----------|

| SQLite（默认） | 单机部署、测试环境 | 无需配置，自动创建 |

| MySQL | 生产环境、多节点 | 配置 .env 中 DATABASE_URL |

| SCSAI AML | 企业集成 | 配置 config.yaml 中 SCSAI.* |

| JSON 文件 | 轻量数据（供应商/变更等） | 自动创建，无需配置 |

七、昇腾 NPU 适配

7.1 安装昇腾 Model-Agent 插件

# 在 AtomCode 中执行
/plugin marketplace add https://gitcode.com/gmq123/ascend-model-agent-plugin
/plugin install ascend-model-agent-plugin@ascend-model-agent-plugin

7.2 配置昇腾推理端点

在 config.yaml 中启用 MTCLAW 模式：

mtclaw:
  enabled: true
  base_url: "http://127.0.0.1:18790/v1"
  completion_mode: "permissive"   # permissive（宽松）| strict（严格）
  upstream:
    endpoint: ""                   # 留空使用昇腾本地模型
    model: "ascend-glm-5.1"       # 或 ascend-deepseek-v4-flash

7.3 验证 NPU 适配

# 检查昇腾驱动
npu-smi info

# 检查 MTCLAW 服务
curl http://127.0.0.1:18790/v1/models

# 测试 LLM 调用
curl -X POST http://127.0.0.1:18790/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"ascend-glm-5.1","messages":[{"role":"user","content":"你好"}]}'

7.4 适配验证数据（参考）

昇腾NPU适配不需要从零开始。左帮右臂已有高通骁龙和摩尔线程的端侧模型适配经验（已验证的7倍加速），昇腾NPU适配是同样路径的工程复制。CANN社区已提供完整的Agent Skill工具链。

参考数据（Qwen3.5-0.8B on 昇腾NPU，来源：CANN官方）：

| 指标 | 优化前 | 优化后 | 提升 |

|------|--------|--------|------|

| Decode加速 | 1.1x | 5.1x | +360% |

| 端到端吞吐 | 11.16 tok/s | 31.59 tok/s | +183% |

完整验证方案见 docs/ascend-npu-verification-plan.md

| 调优项 | 推荐值 | 说明 |

|--------|--------|------|

| 批处理大小 | 4~8 | 根据 NPU 显存调整 |

| 最大 Token | 2048~4096 | 工业场景不需要极大 Token |

| 超时时间 | 30000ms | 覆盖复杂推理场景 |

| 缓存策略 | LRU 128条 | 减少重复查询 |

八、数字员工配置

8.1 启用数字员工

# 1. 配置 LLM API Key
# 编辑 .env 文件
LLM_ENDPOINT=https://api.deepseek.com/v1/chat/completions
LLM_API_KEY=your-api-key
LLM_MODEL=deepseek-chat

# 2. 启用定时任务
# 编辑 config.yaml
cron:
  enabled: true
digital_staff:
  enabled: true

8.2 各数字员工配置

server/digital-staff/profiles/local.yaml：

workers:
  ecr-reviewer:
    enabled: true
    schedule: "*/15 * * * *"   # 每15分钟
    prompt: "你是一个专业的ECR审核员..."

  vendor-manager:
    enabled: true
    schedule: "*/30 * * * *"   # 每30分钟

  cost-optimizer:
    enabled: true
    schedule: "0 2 * * *"      # 每天凌晨2点

  data-clerk:
    enabled: true
    schedule: "0 * * * *"      # 每小时

  procurement:
    enabled: false             # 按需启用
    schedule: "0 9 * * 1-5"    # 工作日9点

8.3 调度启用/禁用

# 临时禁用所有数字员工
cron:
  enabled: false

# 禁用单个数字员工
# 编辑 profiles/local.yaml 对应 worker 的 enabled: false

# 手动触发一次
curl -X POST https://ylxt.chat/api/digital-staff/run/ecr-reviewer

九、常见问题

Q1: 启动时报错 "port 3006 is already in use"

# 查找占用进程
netstat -ano | findstr :3006
# 或 Linux
lsof -i :3006

# 修改配置文件中的端口
# config.yaml → server.port = 3007
# 或设置环境变量 PORT=3007 node server.js

Q2: 能打开页面但登录失败

检查项：

1. SCSAI 服务器地址是否正确（config.yaml → SCSAI.server）
2. 网络是否能连通（curl -I http://your-SCSAI-server/scplm）
3. 用户名密码是否正确
4. 数据库名称是否正确（config.yaml → SCSAI.database）

Q3: 数字员工不执行

检查项：

1. LLM API Key 是否正确配置
2. 环境变量是否生效（echo $LLM_API_KEY）
3. 网络能否访问 LLM 端点
4. config.yaml 中 cron.enabled: true
5. 查看终端日志是否有报错

Q4: 页面加载空白

# 检查浏览器控制台是否有报错
# 确认 index-vue.html 存在
# 尝试直接打开 https://ylxt.chat/index-vue.html

Q5: 数据不显示

• 检查 SCSAI 连接状态
• 检查数据库是否有数据
• 查看服务端日志是否有错误

Q6: 如何更新代码

git pull
pnpm install
pm2 restart zuobangyoubi

十、API 参考

10.1 BOM API

| 方法 | 路径 | 参数 | 说明 |

|------|------|------|------|

| GET | /api/bom/list | page, size, search | 产品列表 |

| GET | /api/bom/detail | id, level | BOM 详情 |

| GET | /api/bom/where-used | partId | Where Used 反查 |

| POST | /api/bom/compare | bomA, bomB | 版本对比 |

| POST | /api/bom/export | id, format | BOM 导出 |

| POST | /api/bom/import | file | 批量导入 |

10.2 业务 API

10.3 数字员工 API

10.4 对象模型 API

附录：部署检查清单

• [ ] Node.js >= 18.0.0 已安装
• [ ] 依赖已安装（pnpm install 无报错）
• [ ] config.yaml 已配置
• [ ] .env 已创建（如需 LLM / 数据库）
• [ ] 服务器启动成功（node server.js 无报错）
• [ ] 浏览器可正常访问 https://ylxt.chat
• [ ] 登录功能正常
• [ ] BOM 管理功能正常
• [ ] （可选）LLM API Key 配置正确，数字员工可调用
• [ ] （可选）昇腾 NPU 适配完成
• [ ] （可选）PM2 进程管理已配置

左帮右臂 —— 基于昇腾NPU的工业智能体平台

Agent Hackathon 2026 · 行业应用·智能制造赛道

联系方式：付博 18986066876 · fu@bossmind.com