使用说明 · 文殊（Manjusri）

① 系统总览 ② 核心模块 ③ 接入网关 ④ 设备网关 · ws-win ⑤ 外置工具 ⑥ WSP 技能 ⑦ 配置方式 ⑧ 服务启停 ⑨ 工具示例

1系统总览

文殊是一套多智能体协作平台，全部模块为 Go 静态编译二进制（零动态依赖），统一由守护进程 supervisor 管理。安装后布局即运行布局：

/data/app/ws/
├── ws                 # 总入口命令（chat / weixin / supervisor / start / stop …）
├── core/              # 核心模块（ws-core、wsprun、ws-todo、ws-a2a …）
├── gateways/          # 接入网关（weixin / email / qq / feishu / wecom / telegram / device）
├── tools/  ws-tools/  # 外置工具（wst-exec、wst-edit、wst-fetch …）
├── skills/            # WSP 技能库（.wsp 技能文件 + registry）
├── knowledge/         # 企业知识库（enterprise.db + 知识文档）
├── config/            # 运行配置（supervisor.yaml、backup.yaml、token-cache.yaml …）
├── data/              # 数据（各模块 SQLite 数据库）
├── logs/              # 日志
└── .env               # 环境变量（密钥/令牌，不写入配置文件）

安装：curl -fsSL -o /tmp/ws-install https://soft.wsai.chat/release/ws-install && chmod +x /tmp/ws-install && /tmp/ws-install -y，随后注册 systemd 服务 ws-supervisor.service 开机自启。

2核心模块（core/）

模块	作用	常驻
`ws-core`	核心调度大脑：定期刷新技能库/知识库索引、协调各模块、触发自愈。	✅
`supervisor`	守护进程：统一启停/拉起所有子模块，崩溃自动重启（restart 计数可见）。	✅
`wsprun`	WSP 技能执行器：语义路由 `--route`、参数收集 `--collect`、校验 `--validate`、撤销 `--undo`。	按需
`ws-todo`	日程提醒：定时任务、到点/提前提醒，渠道支持微信/chat/API。	✅
`ws-kbs`	企业知识库检索：全量索引 / 增量刷新 / 三层漏斗检索（L1 精确 → L2 关键词 → L3 LLM 精选）。	按需
`ws-a2a`	A2A 智能体互联：身份码、配对、牵线、消息路由（婚恋/交友/招聘/二手共用底座）。	✅
`ws-approve`	审批服务：高危操作（删库/防火墙变更/证书申请/杀进程等）走 L2 人工审批。	✅
`ws-backup`	备份：站点/数据库/云存储（OSS/COS/S3）定时备份与恢复。	✅
`ws-crm`	客户管理：档案、服务、续费、收款、缴费通知（配套 CRM 技能）。	按需
`ws-flea`	二手交易市场：商品上架/下单/支付/发货/收货/退款。	✅
`ws-pay`	云支付：订单支付、退款、支付链接（对接 ws-pay 云支付）。	✅
`ws-transfer`	转账/交易：智能体间经济往来。	按需
`wsa-heal`	自愈守护：周期性检查各模块，异常自动拉起并通知。	✅
`token-cache`	LLM 词元缓存：模型调用经缓存路由，省 token 降延迟。	✅
`memory-service`	记忆服务：短期/长期记忆存取。	✅
`api-server`	HTTP API 服务（通知渠道等）。	✅
`mcp-gateway`	MCP 协议网关（可按需启用）。	—

3接入网关（gateways/）

每个渠道一个独立网关进程，把 IM/邮件/设备消息接入文殊统一消息总线。可通过 ws supervisor start/stop <网关名> 单独启停，互不影响。以下为各网关的配置细节。

3.1 微信（weixin-gateway）

基于 iLink 协议接入微信个人号，配置文件 config/config.yaml（不是 .env）：

gateway:
  platforms:
    weixin:
      account_id: 943880b506c0@im.bot   # 微信机器人账号（iLink）
      base_url: https://ilinkai.weixin.qq.com
      enabled: true
      token: ***@im.bot:060000aa6eda3db6e4b9e8d58e9c5607fa8bcc

启动/验证：ws supervisor start weixin-gateway → ws supervisor status weixin-gateway，日志 logs/weixin-gateway.log。

3.2 邮件（email-gateway）

双通道：AgentMail 共同体邮箱（默认）/ 传统 IMAP。配置在 config/config.yaml：

gateway:
  email_gateway:
    channel: agentmail            # agentmail（推荐）或 imap/smtp
    mode: 1ton                    # 1to1（一对一）或 1ton（群发）
    allowed_domains: [wsai.chat]  # 只处理这些域名的来信
    poll_interval: 30             # 轮询间隔（秒）

启动：ws supervisor start email-gateway。AgentMail 无密码，只有 REST API；传统邮箱需在 config.yaml 补 smtp/imap 主机、端口、账号。

3.3 QQ（qq-gateway）

在 QQ 开放平台创建机器人应用后，凭据写入 .env（敏感值加密存储，ws config 写入时自动加密）：

QQ_APP_ID=102xxxxxx
QQ_APP_SECRET=你的应用密钥
QQ_OWNER_OPENID=机器人管理员 openid

启动：ws supervisor start qq-gateway。可加 QQ_ALLOWED_OPENIDS 限定可用用户。

3.4 飞书（feishu-gateway）

长连接模式，零公网回调（不需要域名和公网端口，出站 HTTPS 可达 open.feishu.cn 即可）。.env 键：

FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=你的应用密钥
FEISHU_ALLOWED_OPENIDS=ou_xxx,ou_yyy   # 可选，限定可用用户

飞书开放平台侧（缺一不可）：

创建企业自建应用，拿到 App ID / App Secret
事件订阅 → 订阅方式选 「使用长连接接收事件」（不是 webhook）
添加事件 im.message.receive_v1（收消息核心事件，必选）
权限管理开通 im:message.p2p_msg + im:message（图片/文件再加 im:resource）
版本管理与发布 → 创建版本，可用范围含自己 → 发布后配置才生效

启动：ws supervisor start feishu-gateway；日志出现 connected to wss://msg-frontier.feishu.cn 即长连接建立。完整部署文档见 /data/app/ws/飞书网关部署说明.md（含常见错误对照表）。

3.5 企业微信（wecom-gateway）

企业微信智能机器人。.env 键：

WECOM_CORP_ID=ww21fef11da7474571        # 企业 ID
WECOM_BOT_ID=aibHd5kY4KM04CCwM6m_lY...   # 机器人 ID
WECOM_BOT_SECRET=你的机器人密钥
WECOM_ALLOWED_USERIDS=user1,user2        # 可选，限定可用用户

3.6 Telegram（telegram-gateway）

国际化对外信道。找 @BotFather 创建机器人拿 token，写入 .env：

TELEGRAM_TOKEN=123456:ABC-DEF...        # BotFather 给的 bot token
TELEGRAM_ALLOWED_USERS=8708785703       # 限定可用用户 ID（逗号分隔）

安全约定：所有密钥/令牌只放 .env 环境变量，绝不出现在配置文件、代码或日志中；敏感值加密存储（*_ENCRYPTED）。

4设备网关 · ws-win（device-gateway）

让客户 Windows 电脑成为文殊的"手脚"：端侧只跑一个轻量绿色程序 ws-win.exe，由设备主动反向连接云端（WebSocket :9519，应用层 AES-256-GCM 加密），云端 LLM 生成指令回传，驱动设备执行 PowerShell 命令、读写文件、监控状态。

4.1 下载与部署（Windows）

下载：ws-win.exe（绿色单 exe，约 6.2MB，Windows x64，无需安装、无服务注册）。放到任意目录双击运行，随目录便携：配置与对话文件都在 exe 所在目录创建读取，移动整个目录 = 便携迁移。

4.2 首次配对（4 步）

双击 ws-win.exe → 自动生成设备 ID（8 位大写，如 W7K3-9Q2M），显示在运行窗口与 智能体回复.txt
在文殊任意通道（微信/邮件/QQ/飞书/chat）发送：设备配对 W7K3-9Q2M（命中 WSP 技能「设备配对」，云端生成对称密钥与连接密文）
把返回的「密钥内容」保存为运行目录 device.key，「连接密文」保存为 server.key
ws-win 检测到两个文件后自动连接（无需重启），连接后运行窗口显示 [系统] 已连接

4.3 日常使用

# 交互方式：文件对话
1. 在 客户输入.txt 输入内容，按 Ctrl+S 保存即自动发送
   （ws-win 比较新旧内容，只发新增部分，无需额外结束符）
2. 智能体回复实时显示在运行窗口（角色：[用户]/[智能体]/[系统]/[执行]），
   同时追加写入 智能体回复.txt（完整对话留档）
3. 云端需要执行命令时，窗口以 [执行] 角色显示命令与输出

4.4 安全与运行参数

项	说明
加密	普通 WebSocket + 应用层 AES-256-GCM（对称密钥 K），两步握手：hello → challenge → register
防拷贝	本地硬件指纹绑定 device.key + 服务端指纹登记比对（两层），复制到别的电脑解不开
有效期	连接续期 7 天；7 天未连接自动过期，重新配对即可
控制模型	仅设备主动；被动控制默认关（allow_passive 开关预留）
PowerShell	自动适配：优先 pwsh.exe（7+），其次 powershell.exe（5.1）；UTF-8 编码 + Bypass 策略 + EncodedCommand 防转义

ws-win.exe                          # 正常使用：无需任何参数
ws-win.exe -v                       # 调试模式：显示内部日志
ws-win.exe -server ws://host:9519/agent   # 覆盖连接地址（测试用）
# 参数：-server（默认从 server.key 解密获得）/ -dir（默认 exe 所在目录）/ -debounce 500 / -v

云端侧：device-gateway 由 supervisor 托管（config/supervisor.yaml 预置条目，配对技能触发时自动启动并置 auto_start）。配对技能「设备配对」在任意通道说"设备配对 <设备ID>"即可调用。

5外置工具（wst-*）

外置工具是原子能力，供智能体在执行任务时调用，也支持命令行直接使用（ws cmd 工具名 或直接运行二进制）。

工具	用途
`wst-exec`	执行 shell 命令，返回输出（运行程序/检查状态/操作文件）。
`wst-edit`	编辑文件：文本替换、正则替换、YAML 安全编辑（set/append/del）。
`wst-fetch`	HTTP 请求（GET/POST/PUT/DELETE），调用 API、检查服务、抓取网页。
`wst-browser`	无头 Chrome 浏览器自动化：打开网页、搜索、提取内容、截图。
`wst-email`	邮件：发送 EML、列邮件、读详情、删除、搜索、查看配置。
`wst-excel`	Excel 处理：创建（表头/列宽）、读取 JSON、更新单元格、追加行。
`wst-ocr`	图片文字识别（离线，中英文，返回坐标与置信度）。
`wst-media`	媒体分析：图片描述、音频识别、视频分析（经 token-cache 路由大模型）。
`wst-voice`	语音：文本合成语音（TTS）、语音识别（ASR）、列出音色。
`wst-image`	大模型生成图片。
`wst-ppt` / `wst-word`	生成 PowerPoint / Word 文档（完整定义 JSON、快捷模式、Markdown 转文档）。
`wst-s3`	对象存储：ls/tree/rm/upload/download/genlink/verify/sync/cp。
`wst-search`	文件系统搜索：按文件名/内容关键词，通配符过滤。
`wst-websearch`	互联网搜索（Bing/Google），支持 cookie 导入与代理。
`wst-ssh`	SSH 远程执行命令（多节点运维，9322 端口 + 密钥）。
`wst-tasks` / `wst-plan` / `wst-plan-check`	执行 .ws 微任务文件 / 项目设计拆分为微任务 / 计划自检。
`wst-sendfile`	发送文件到微信用户（iLink 协议）。
`wst-mail-handle`	智能体邮件处理：身份码识别、交易指令执行、通用回执。
`wst-ident` / `wst-trade` / `wst-transfer`	身份码 / 交易 / 转账。

6WSP 技能（wsprun）

WSP 是第四种能力类型——可执行复合技能（区别于内置工具的原子操作、外置工具的分发清单、skills 的知识文档）。技能库涵盖：

运维：一键建站 SSL 证书（Let's Encrypt）防火墙/白名单数据库建删/备份/恢复定时备份监控告警安全加固/fail2ban Nginx/PHP/LNMP Docker 管理业务：婚恋会员/配对/牵线招聘求职匹配二手交易 CRM 客户管理

# 查看全部能力（路由预览，不执行）
wsprun --route "你有什么能力？" --dry-run

# 语义路由：自然语言自动匹配技能并执行
wsprun --route "帮我放行 1.2.3.4 的 8081 端口"

# 参数收集：先问用户缺哪些必填参数（不执行）
wsprun --route "帮我建一个网站" --collect

# 参数校验：只校验不执行
wsprun --route "帮我建一个网站" --validate

# 直接指定技能文件精确执行
wsprun skills/security/firewall_whitelist/firewall_whitelist.wsp --action query --ip 127.0.0.1

# 撤销上次技能执行（幂等回滚）
wsprun <技能.wsp> --undo

# 刷新技能库索引（ws-core 默认每 60 分钟自动调用）
wsprun --refresh

说明：技能库索引由 ws-core 定期刷新，--route / --query 纯读 SQLite，不实时扫描磁盘。高风险操作（删库/防火墙变更/证书申请等）执行前会走人工审批。

7配置方式

环境变量（.env）：密钥/令牌一律经环境变量传递，由 ws 启动时加载（supervisor 启动时把 .env 全量注入所有子进程环境）。主要键名（不展示值）：

类别	键名
运行	`WS_PATH`（运行目录）、`WS_SOCK_DIR`、`WS_DEV_MODE`、`WS_AUTO_UPDATE`
LLM	`DEEPSEEK_API_KEY`、`DEEPSEEK_BASE_URL`、`WS_TASK_MODEL`
渠道凭证	`FEISHU_`（飞书）、`QQ_`（QQ）、`WECOM_`（企业微信）、`TELEGRAM_`（Telegram）——敏感值加密存储
安全	`WS_ADMIN_TOKEN`、`WS_BACKUP_KEY`、`WS_PAY_TOKEN`、`WS_PUSH_TOKEN`、`WS_TOKEN_CACHE_TOKEN`
自愈	`WSA_HEAL_*`（各节点 token、巡检时间、启动延迟）
智能体	`WS_AGENT_ID`（本智能体身份）

配置文件（config/）：非密钥类配置放 YAML/JSON，与 .env 分离。

文件	用途
`supervisor.yaml`	守护进程模块清单与启动参数（增删模块改这里）。
`backup.yaml`	备份任务配置（站点/数据库/云存储、保留轮转）。
`token-cache.yaml` 等	LLM 词元缓存（模型、计费、embedding、redis）。
`approval_rules.json`	审批规则（哪些操作需要 L2 审批）。
`a2a.json` / `ws-pay.json` / `ws-flea.json` / `agents.yaml`	A2A 互联、云支付、二手市场、智能体注册配置。
`config.yaml`	邮件网关 SMTP/IMAP 配置、各平台账号（weixin/telegram/feishu/wecom 等）。

8服务启停

整体启停：systemd 管理守护进程，ws 命令管理全部模块。

# systemd（开机自启）
systemctl enable --now ws-supervisor.service
systemctl status ws-supervisor.service

# 整体启停/重启/更新
ws start          # 启动全部模块
ws stop           # 停止全部模块
ws restart        # 先停全部，再统一启动
ws update         # 更新全部模块（或 ws update 模块名）
ws coreup         # 更新内核（core/gateways/supervisor/ws，单模块停换、统一重启）

单模块启停（推荐）：部署/重启/更换任何网关或模块二进制时，用 supervisor 单模块操作，避免整机重启。

ws supervisor list                    # 列出全部模块与状态
ws supervisor status <名称>            # 查看单个模块状态（如 feishu-gateway）
ws supervisor start  <名称>            # 启动单个模块
ws supervisor stop   <名称>            # 停止单个模块
ws supervisor restart <名称>           # 重启单个模块（换二进制后用它）

实时状态：模块崩溃 supervisor 自动拉起（restarts 计数增长，可在 list 中看到）；wsa-heal 周期性巡检，异常自动通知。

约定：部署/重启/更换任何网关或模块二进制时，一律用 ws supervisor restart <名称>，严禁整体重启全家（会把微信/邮件/QQ 等其他网关一起搞停）。

9工具使用示例

ws-todo — 日程提醒

# 添加一条日程：明天 09:00 提醒，提前 30 分钟，走微信渠道
ws-todo -add "检查服务器磁盘空间" -due "2026-09-03 09:00" -channel weixin -lead 30

# 添加带执行指令的日程（到点后把 action 交给智能体执行，渠道 chat）
ws-todo -add "巡检 ws-sec 安全服务" -due "2026-09-03 09:00" -channel chat \
        -action "检查 ws-secd 状态并汇报"

# 列出待办 / 全部
ws-todo -list pending
ws-todo -list all

# 标记完成 / 取消（软删除）
ws-todo -done 7
ws-todo -del 7

# 常驻服务（supervisor 已托管，带 HTTP API 127.0.0.1:9523）
ws supervisor status ws-todo

ws-kbs — 企业知识库

# 全量重建 / 增量刷新索引
ws-kbs --index
ws-kbs --refresh

# 三层漏斗检索（L1 精确 → L2 关键词 → L3 LLM 精选）
ws-kbs --query "文殊节点有哪些"

# 列出节点/模块/知识条目，查看详情
ws-kbs --list --category node
ws-kbs --list --category module
ws-kbs --get <id>

# 维护节点/模块登记
ws-kbs --add-node "name=文殊,domain=ws.wsai.chat,port=9322"
ws-kbs --add-module "name=feishu-gateway,category=gateway,status=running"

ws 总入口 — 常用子命令

ws chat          # 启动聊天窗口
ws weixin        # 启动微信网关
ws apptoken      # 生成 8 位配对验证码（手机客户端绑定，5 分钟有效）
ws cmd wst-exec "uptime"   # 直接调用外置工具
ws cmdhelp wst-exec        # 查看工具参数 schema
ws -v             # 版本号

提示：日常使用建议直接用自然语言告诉智能体（如"帮我把张三的状态改成已签约"），智能体会自动路由到对应 WSP 技能或外置工具；命令行方式适合运维人员手工操作与排查。

文殊系统使用说明