From 99293aa39ddafc2bb843c6cd5483d7ea78589942 Mon Sep 17 00:00:00 2001 From: kicer Date: Mon, 28 Sep 2026 07:57:30 +0800 Subject: [PATCH] =?UTF-8?q?=E9=87=8D=E5=81=9A=E9=85=8D=E7=BD=AE=E8=BE=B9?= =?UTF-8?q?=E7=95=8C=EF=BC=88=E6=92=A4=E9=94=80=209b6bfff=20=E6=80=9D?= =?UTF-8?q?=E8=B7=AF=EF=BC=89=EF=BC=9Aconfig.example.yml=20=E5=9B=9E?= =?UTF-8?q?=E5=BD=92=20app/=E2=80=94=E2=80=94config.yml=20=E6=98=AF=20core?= =?UTF-8?q?=20=E4=B8=93=E5=B1=9E=EF=BC=88=E5=86=85=E5=90=AB=E5=B9=B3?= =?UTF-8?q?=E5=8F=B0=E5=AF=86=E9=92=A5/=E7=99=BB=E5=BD=95=20secret?= =?UTF-8?q?=EF=BC=89=EF=BC=8Cexecutor/wxbot=20=E4=B8=80=E5=BE=8B=E4=B8=8D?= =?UTF-8?q?=E6=8C=82=E4=B8=8D=E8=AF=BB=EF=BC=9Bexecutor=20=E4=B8=8E=20wxbo?= =?UTF-8?q?t=20=E6=8E=A5=E7=BA=BF=E7=BA=AF=20env=EF=BC=88EXECUTOR=5FURL/EX?= =?UTF-8?q?ECUTOR=5FTOKEN=E3=80=81WXBOT=5FURL/WXBOT=5FTOKEN=EF=BC=8Ccompos?= =?UTF-8?q?e=20=E7=BB=8F=E6=A0=B9=20.env=20=E6=B3=A8=E5=85=A5=EF=BC=8C?= =?UTF-8?q?=E6=97=A7=E6=96=87=E4=BB=B6=E6=AE=B5=E5=BF=BD=E7=95=A5=EF=BC=89?= =?UTF-8?q?=EF=BC=8Cconfig.example.yml=20=E4=B8=A4=E6=AE=B5=E9=9A=8F?= =?UTF-8?q?=E4=B9=8B=E5=88=A0=E9=99=A4=EF=BC=9Bwxbot=20=E6=97=A5=E5=BF=97?= =?UTF-8?q?=E7=AD=89=E7=BA=A7=E6=94=B9=20env=20WXBOT=5FLOG=5FLEVEL?= =?UTF-8?q?=EF=BC=88compose=20=E6=B3=A8=E5=85=A5=EF=BC=8C=E5=90=8C=20EXECU?= =?UTF-8?q?TOR=5FLOG=5FLEVEL=20=E6=A8=A1=E5=BC=8F=EF=BC=9Bnone/off?= =?UTF-8?q?=E2=86=92silent=EF=BC=8Cdebug=20=E6=89=93=E5=8D=B0=E6=94=B6?= =?UTF-8?q?=E4=BF=A1=E5=8E=9F=E5=A7=8B=E7=BB=93=E6=9E=84=E4=BF=9D=E7=95=99?= =?UTF-8?q?=EF=BC=89=EF=BC=9B.env.example=20=E6=94=B6=E6=95=9B=E4=B8=BA?= =?UTF-8?q?=E5=AF=86=E9=92=A5+=E5=9C=B0=E5=9D=80=E7=B1=BB=E5=8F=98?= =?UTF-8?q?=E9=87=8F=EF=BC=8C=E5=85=B6=E4=BD=99=E6=97=8B=E9=92=AE=E5=BD=92?= =?UTF-8?q?=20compose=EF=BC=9Bcompose=20=E6=92=A4=E6=8E=89=20wxbot=20?= =?UTF-8?q?=E7=9A=84=20config.yml=20=E5=8F=AA=E8=AF=BB=E6=8C=82=E8=BD=BD?= =?UTF-8?q?=E3=80=81=E6=96=B0=E5=A2=9E=20WXBOT=5FLOG=5FLEVEL=E3=80=81WXBOT?= =?UTF-8?q?=5FURL=20=E4=BF=9D=E7=95=99=E5=8D=95=E6=A8=AA=E7=BA=BF=E4=BF=AE?= =?UTF-8?q?=E5=A4=8D=EF=BC=88=E8=AF=A5=E6=96=87=E4=BB=B6=E4=BB=8D=E6=9C=89?= =?UTF-8?q?=E4=B8=BB=E4=BA=BA=20WIP=EF=BC=8C=E6=9C=AA=E9=9A=8F=E6=9C=AC?= =?UTF-8?q?=E6=8F=90=E4=BA=A4=EF=BC=89=EF=BC=9B=E6=96=87=E6=A1=A3=E5=90=8C?= =?UTF-8?q?=E6=AD=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 25 ++++++++++++++++++++++--- README.md | 2 +- app/README.md | 2 +- app/config.example.yml | 20 +++++++++----------- app/server/config.js | 28 +++++++++++++++------------- app/server/routes/wechat.js | 4 ++-- app/server/server.js | 4 ++-- app/server/wechat.js | 8 ++++---- docs/ARCHITECTURE.md | 18 +++++++++--------- docs/DEPLOY.md | 4 ++-- wxbot/README.md | 12 ++++++++---- wxbot/app/src/server.js | 37 +++++++++++++++++++++++++++++++++---- 12 files changed, 108 insertions(+), 56 deletions(-) diff --git a/.env.example b/.env.example index 487284f..1c4ece9 100644 --- a/.env.example +++ b/.env.example @@ -1,6 +1,25 @@ -# 复制为 .env 并填入真实值(.env 已在 .gitignore,不会被提交)。 -# 生成 token:openssl rand -hex 32 +# .env.example — 仓库根 .env 模板(.env 已 gitignore,不会被提交)。 +# 标准路径是跑 ./scripts/init.sh:自动生成下面全部密钥并幂等复用(重跑不掉登录态、不换 token)。 +# 本文件仅作手动部署参考;手动生成 token:openssl rand -hex 32。 +# 其余部署旋钮(EXECUTOR_URL、*_LOG_LEVEL、VIRTUAL_HOST 等)都在 docker-compose.yml 里改,不放这里。 + +# ---- 必填(compose 用 ${VAR:?} 检查,缺失则 docker compose up 直接报错)---- + +# core ↔ executor 调用鉴权(compose 注入两侧同值) EXECUTOR_TOKEN=change-me-openssl-rand-hex-32 -# 选填:agent-core 在宿主机上的端口(默认 8090),改这里就不用改 docker-compose.yml。 +# core ↔ wxbot 微信接入服务 token(compose 注入两侧同值;未就位 = 微信入口整体静默关闭) +WXBOT_TOKEN=change-me-openssl-rand-hex-32 + +# ---- 建议填 ---- + +# 登录态签名密钥:init.sh 写进 config.yml 的 auth.secret 并在此复用;缺失则每次重启随机(全员重新登录) +AUTH_SECRET=change-me-openssl-rand-hex-32 + +# ---- 可选 ---- + +# agent-core 映射到宿主机的端口(默认 8090),改这里就不用动 docker-compose.yml # AGENT_PORT=8090 + +# core 调 wxbot 的地址:不写 = compose 默认 http://wxbot:8093;显式置空(WXBOT_URL=)= 关闭微信入口 +# WXBOT_URL=http://wxbot:8093 diff --git a/README.md b/README.md index d50509f..6a5e9d2 100644 --- a/README.md +++ b/README.md @@ -811,7 +811,7 @@ HTTP 直连时浏览器不认为这是“安全上下文”:PWA/Service Worker ## 十四、配置文件示例 -完整字段与默认值见 `app/config.example.yml`(与 `server/config.js` 的 `DEFAULTS` 一一对应); +完整字段与默认值见 `app/config.example.yml`(core 专属,与 `server/config.js` 的 `DEFAULTS` 一一对应); 部署时由 `scripts/init.sh` 生成的顶层 `config.yml` 只覆盖 `platforms` / `auth` / `mcp_servers`。 ```yaml diff --git a/app/README.md b/app/README.md index 0b73d6e..4083630 100644 --- a/app/README.md +++ b/app/README.md @@ -24,7 +24,7 @@ app/ │ ├── templates/system-prompt.txt # System prompt 模板(直接编辑) │ └── public/ # H5 前端(Vanilla JS + SSE;无构建,index.html + js/ 六模块按序加载) ├── test/ # mock 上游 + 端到端冒烟测试 -├── config.example.yml +├── config.example.yml # core 专属配置模板(部署时生成/复制为仓库根 config.yml 挂进容器) ├── Dockerfile / docker-compose.yml ``` diff --git a/app/config.example.yml b/app/config.example.yml index 7d575e1..9db5689 100644 --- a/app/config.example.yml +++ b/app/config.example.yml @@ -1,5 +1,8 @@ -# config.example.yml — 配置模板:与 server/config.js 的 DEFAULTS 一一对应。 -# 复制为 config.yml 即可启动;platforms 为空则无模型可用,可在前端设置页添加后重启。 +# config.example.yml —— agent-core 专属配置模板:与 server/config.js 的 DEFAULTS 一一对应。 +# ⚠️ 本文件(及其生成物 config.yml)只给 core 进程读:内含平台 api_key / 登录 secret, +# executor、wxbot 等其他组件一律不挂、不读(bind mount 只挂给 agent-core),它们的接线全部由根 compose 经 .env 注入 env。 +# 部署推荐用 scripts/init.sh 生成 config.yml(只写 platforms/auth/mcp_servers/public_link,其余走默认值); +# 手动部署才整份复制本文件。platforms 为空则无模型可用,可在前端设置页添加后重启。 # 模型平台池:每平台 {name, url, type?, models:[{id, ...}], keys:[{api_key, concurrency?}]}。 platforms: [] @@ -27,16 +30,11 @@ port: 8090 # 服务监听端口 workspace_root: "/workspace/tasks" # 任务工作区根目录,AI 文件操作限制在此 data_root: "/workspace/data" # 数据根目录:SQLite 与 prompt dump db_path: "" # 留空取 data_root/.agent.db -log_level: "info" # debug < info < warn < error < none +log_level: "info" # debug < info < warn < error < none(仅 core 自身;executor/wxbot 的日志等级另走 EXECUTOR_LOG_LEVEL / WXBOT_LOG_LEVEL env,compose 注) -executor: # 独立命令执行服务;两侧需同路径挂载 tasks/skills - url: "" # 非空走远端执行;留空读 env EXECUTOR_URL 或本地 spawn - token: "" # 与 executor 侧同值;留空读 env EXECUTOR_TOKEN - -wxbot: # 微信接入(可选;仓库 wxbot/ 子项目,只挂内网,不入 git) - url: "" # 非空才启用;留空读 env WXBOT_URL(compose 注 http://wxbot:8093); - # 留空 = 功能整体静默关闭;填了但 wxbot 没起也不报错,设置页显示未连接 - token: "" # core ↔ wxbot 共享服务 token,两侧同值;留空读 env WXBOT_TOKEN +# executor(命令执行)与 wxbot(微信接入)均**不是本文件的配置项**,接线全走根 compose 注入的 env(见 .env.example): +# EXECUTOR_URL / EXECUTOR_TOKEN;WXBOT_URL(默认 http://wxbot:8093,置空=微信入口静默关闭)/ WXBOT_TOKEN(init.sh 生成,两侧同值)。 +# 详见 docs/ARCHITECTURE.md §5.13。 terminal: default_timeout_ms: 30000 # 命令默认超时(ms) diff --git a/app/server/config.js b/app/server/config.js index b0b24bd..e46a34e 100644 --- a/app/server/config.js +++ b/app/server/config.js @@ -74,11 +74,8 @@ const DEFAULTS = { data_root: '/workspace/data', // 缺省 data_root/.agent.db。 db_path: '', - // 命令执行服务:url 非空走远端 executor,留空本地 spawn;留空时回退 env EXECUTOR_URL / EXECUTOR_TOKEN。 - executor: { url: '', token: '' }, - // 微信接入(可选能力):url 非空才启用(留空时整个微信功能静默下线,不影响其他一切); - // 留空时回退 env WXBOT_URL / WXBOT_TOKEN(compose 注入,同 executor 模式;wxbot 只在内网,走容器名)。 - wxbot: { url: '', token: '' }, + // executor / 微信接入(wxbot)均不占配置字段:两组件接线纯 env(compose 经根 .env 注入,见 parseAndValidate); + // 本配置文件内含密钥,只给 core 进程读,executor/wxbot 一律不挂不读。 terminal: { default_timeout_ms: 30000, max_output_chars: 10000 }, // fetch:timeout_ms 覆盖请求发出到 body 读完的全生命周期;max_bytes 为流式抓取字节上限(超限即断开)。 fetch: { timeout_ms: 30000, max_bytes: 1048576 }, @@ -268,15 +265,20 @@ function parseAndValidate(rawText, configPath) { cfg.data_root = path.resolve(cfg.data_root); if (!cfg.db_path) cfg.db_path = path.join(cfg.data_root, '.agent.db'); - // executor 远程执行:配置优先,env 兑底(compose 注入 EXECUTOR_URL/EXECUTOR_TOKEN);url 去尾部斜杠(拼 /exec 用)。 - if (!cfg.executor || typeof cfg.executor !== 'object') cfg.executor = {}; - cfg.executor.url = String(cfg.executor.url || process.env.EXECUTOR_URL || '').trim().replace(/\/+$/, ''); - cfg.executor.token = String(cfg.executor.token || process.env.EXECUTOR_TOKEN || '').trim(); + // executor 远程执行:纯 env 接线(compose 注 EXECUTOR_URL/EXECUTOR_TOKEN;未注 = 本地 spawn,单机调试形态)。 + // cfg.executor 仍作运行期访问器供 remote-exec 读取;url 去尾部斜杠(拼 /exec 用)。executor 进程不读本配置文件(防密钥外泄)。 + cfg.executor = { + url: String(process.env.EXECUTOR_URL || '').trim().replace(/\/+$/, ''), + token: String(process.env.EXECUTOR_TOKEN || '').trim(), + }; - // 微信接入(wechat.js):同上模式;url 留空 = 功能关闭(不报错、不建实例、面板隐藏)。 - if (!cfg.wxbot || typeof cfg.wxbot !== 'object') cfg.wxbot = {}; - cfg.wxbot.url = String(cfg.wxbot.url || process.env.WXBOT_URL || '').trim().replace(/\/+$/, ''); - cfg.wxbot.token = String(cfg.wxbot.token || process.env.WXBOT_TOKEN || '').trim(); + // 微信接入(wechat.js):纯 env 接线(wxbot 为栈内组件,不再是 config.yml 字段;旧文件里的 wxbot: 段直接忽略)。 + // WXBOT_URL 缺省 http://wxbot:8093(compose 注同名 env,置空 = 微信入口整体静默关闭); + // WXBOT_TOKEN 未配 = 关闭(init.sh 生成,core ↔ wxbot 两侧同值)。cfg.wxbot 仍作为运行期访问器供 wechat/routes 读取。 + cfg.wxbot = { + url: String(process.env.WXBOT_URL != null ? process.env.WXBOT_URL : 'http://wxbot:8093').trim().replace(/\/+$/, ''), + token: String(process.env.WXBOT_TOKEN || '').trim(), + }; // 日志等级:只认 debug/info/warn/error/none(off 是 none 别名),非法值按 info(不影响启动) cfg.log_level = String(cfg.log_level || 'info').trim().toLowerCase(); diff --git a/app/server/routes/wechat.js b/app/server/routes/wechat.js index 5a2778e..dc7f96d 100644 --- a/app/server/routes/wechat.js +++ b/app/server/routes/wechat.js @@ -41,7 +41,7 @@ function timingEqual(a, b) { function requireService(req, res, next) { const cfg = engine.getConfig(); const token = (cfg.wxbot && cfg.wxbot.token) || ''; - if (!token) return res.status(503).json({ error: '微信接入服务 token 未配置(config wxbot.token / env WXBOT_TOKEN)' }); + if (!token) return res.status(503).json({ error: '微信接入服务 token 未配置(env WXBOT_TOKEN)' }); const h = String(req.headers.authorization || ''); if (!h.startsWith('Bearer ') || !timingEqual(h.slice(7).trim(), token)) { return res.status(401).json({ error: 'invalid service token' }); @@ -69,7 +69,7 @@ function rowFor(req) { return b; } -// 面板总览:enabled=false(wxbot.url 未配)时前端整卡隐藏——没配置就当功能不存在; +// 面板总览:enabled=false(WXBOT_URL/WXBOT_TOKEN 未就位)时前端整卡隐藏——没配置就当功能不存在; // alive/has_qr 与状态自愈全在 wechat.overview()(hook 丢事件也能从实例快照纠回来)。 router.get('/', wrap(async (req, res) => { res.json(await wechat.overview(String(req.user || ''))); diff --git a/app/server/server.js b/app/server/server.js index 9810cc8..a2b43f8 100644 --- a/app/server/server.js +++ b/app/server/server.js @@ -27,7 +27,7 @@ engine.init(); //(active/遗留 queued → held),首轮 tick 才不会看到脏状态。 scheduler.start(engine); -// 微信接入(wechat.js,可选能力):wxbot.url 未配 = 全部静默关闭;配了但 wxbot 没起 = +// 微信接入(wechat.js,可选能力):env WXBOT_URL/WXBOT_TOKEN 未就位 = 全部静默关闭;配了但 wxbot 没起 = // restore 只留一行日志,不重试不报错(用户在设置页点刷新自愈),不影响 Web 主流程。 wechat.init(cfg, db, bus); @@ -175,7 +175,7 @@ mcp.init(cfg).then(async () => { const mcpList = (cfg.mcp_servers || []).map(s => s.name + '@' + s.url + (s.enable === false ? '(禁用)' : '')).join(', '); log.info('startup', ' mcp_servers=' + (mcpList || '(none)')); log.info('startup', ' auth=' + (auth.enabled ? 'login: ' + cfg.auth.users.map(u => u.user).join(', ') : '(disabled)')); - log.info('startup', ' wxbot=' + (cfg.wxbot.url ? cfg.wxbot.url : '(未启用)')); + log.info('startup', ' wxbot=' + (cfg.wxbot.url && cfg.wxbot.token ? cfg.wxbot.url : '(未启用)')); log.info('startup', ' log_level=' + cfg.log_level); // 微信实例恢复 fire-and-forget:wxbot 没起只留日志,绝不阻塞/抛错影响启动。 wechat.restore().catch(e => log.warn('wechat', '启动恢复异常:' + (e && e.message || e))); diff --git a/app/server/wechat.js b/app/server/wechat.js index 5bb16e5..1541f89 100644 --- a/app/server/wechat.js +++ b/app/server/wechat.js @@ -10,7 +10,7 @@ // wxbot → core /wxhook/{inbox,hook}(Bearer 服务 token,挂在 auth.middleware 之前) // core → wxbot /api/deliver(assistant 最终回复推送;总线内部监听驱动,游标落库不重发) // + /api/deliver_media(正文里的 /p/ 链接→本地读字节→微信文件/图片卡片,尽力而为) -// 降级承诺:wxbot.url 未配置 = 功能整体静默关闭;配置了但 wxbot 没起 = 启动只留一行日志, +// 降级承诺:微信接入未配置(env WXBOT_URL 置空或未配 WXBOT_TOKEN)= 功能整体静默关闭;配了但 wxbot 没起 = 启动只留一行日志, // 面板显示「未连接」、操作时报可读错误,绝不抛出未捕获异常影响 Web 主流程。 const crypto = require('crypto'); const fs = require('fs'); @@ -32,13 +32,13 @@ const now = () => Date.now(); const msg = e => String((e && e.message) || e || 'unknown'); // ---------- 开关与 wxbot 客户端 ---------- -function enabled() { return !!(cfg && cfg.wxbot && cfg.wxbot.url); } +function enabled() { return !!(cfg && cfg.wxbot && cfg.wxbot.url && cfg.wxbot.token); } function wxUrl() { return (cfg.wxbot && cfg.wxbot.url) || ''; } function wxToken() { return (cfg.wxbot && cfg.wxbot.token) || ''; } async function wxbotApi(method, path, body, timeoutMs) { - if (!enabled()) throw Object.assign(new Error('微信接入未配置:wxbot.url 为空'), { status_code: 409 }); + if (!enabled()) throw Object.assign(new Error('微信接入未配置:env WXBOT_URL / WXBOT_TOKEN 未就位'), { status_code: 409 }); const res = await fetch(wxUrl() + path, { method, headers: Object.assign( @@ -94,7 +94,7 @@ function touchBinding(id, fields) { // 一人一绑(自用形态;换微信号走「解绑→重绑」);id 兼作 channel 后缀与 wxbot 存储目录名 → 只允许安全字符。 async function createBinding(user) { - if (!enabled()) throw Object.assign(new Error('微信接入未配置(wxbot.url 为空),请联系管理员在 config.yml / 环境变量 WXBOT_URL 启用后重启'), { status_code: 409 }); + if (!enabled()) throw Object.assign(new Error('微信接入未配置(WXBOT_URL/WXBOT_TOKEN 未就位),请联系管理员运行 scripts/init.sh 后 docker compose up -d 重建'), { status_code: 409 }); const dup = db.prepare('SELECT id FROM wechat_bindings WHERE user = ?').get(user); if (dup) throw Object.assign(new Error('你已绑定微信(' + dup.id + '),请先解绑'), { status_code: 409 }); const id = 'wx' + crypto.randomBytes(5).toString('hex'); diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index daf6a26..b41e481 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -15,7 +15,7 @@ agent/ ├── README.md 设计文档(API/数据模型/部署总览) ├── docker-compose.yml 编排:agent-core / agent-executor(+init) / wxbot(微信接入) -├── config.yml 运行时配置(含密钥,已 .gitignore) +├── config.yml 运行时配置(含密钥,已 .gitignore;只给 agent-core 进程读,其他组件禁挂禁读) ├── data/ 默认数据卷(任务目录、SQLite、prompt dump) ├── tasks/ 任务目录挂载点(同 ./data 顶层等价,二选一) ├── skills/ 技能目录(用户维护的 SKILL.md/run.py) @@ -23,7 +23,7 @@ agent/ ├── app/ ── Core 服务容器 ── │ ├── Dockerfile node:20-slim,npm install only prod │ │ ├── package.json 依赖:express / better-sqlite3 / multer / sharp / yaml / minimatch / cron-parser -│ ├── config.example.yml 配置模板(被复制为顶层 config.yml) +│ ├── config.example.yml core 专属配置模板(复制/生成为顶层 config.yml) │ ├── scripts/ │ │ └── init.sh 部署入口:生成 .env + config.yml → 起 agent/mcp 服务 │ ├── server/ 后端代码 @@ -153,7 +153,7 @@ graph LR 3. `initDb(cfg.db_path)` 建表 + 增量迁移(`db.js`,含 `held_at` / `last_model_id` / `assistant_type` / `user` / `profile` 等历史升级)。 4. `createBus()` 建 SSE 事件总线(`sse.js`)。 5. `engine.setModelPool(cfg, db, bus); engine.init()`:按 cfg.models 重建 `model_pool` 槽位表;会话状态归位(active/遗留 queued → held,绑定不清);指向已删/禁用模型的绑定在下次发言时由 `ensureBinding` 自动改选。 -6. `scheduler.start(engine)`:启动定时任务轮询(30s 一次,`unref`)。**必须在 engine.init() 之后**——先让会话状态归位,首轮 tick 才看不到脏状态(见 §5.12)。随后 `wechat.init(cfg, db, bus)` 挂上总线内部订阅(微信接入,§5.13;`wxbot.url` 未配时全程静默)。 +6. `scheduler.start(engine)`:启动定时任务轮询(30s 一次,`unref`)。**必须在 engine.init() 之后**——先让会话状态归位,首轮 tick 才看不到脏状态(见 §5.12)。随后 `wechat.init(cfg, db, bus)` 挂上总线内部订阅(微信接入,§5.13;env WXBOT_URL/WXBOT_TOKEN 未就位时全程静默)。 7. `createAuth(cfg)` 装配登录中间件;未配 `auth.users` 则认证关闭(可交给前置 nginx-proxy basic auth)。 8. `express.static(public)` + 路由挂载(`/api/sessions`、`/api/skills`、`/api/config`、`/api/platforms`、`/api/system`、`/api/channel`、`/api/wechat`);`auth.middleware` 之前另挂两个内网/匿名入口:`/p`(公网临时文件)与 `/wxhook`(wxbot 回调,共享服务 token 把门)。 9. `mcp.init(cfg).then(...)`:对每个 MCP 服务 initialize → tools/list,发现的工具存在 `mcp` 模块内。 @@ -430,12 +430,12 @@ AI 通过 `schedule` 工具为所在会话建周期性任务(`scheduled_tasks` 背景:仓库内 `wxbot/`(已入库,作为根 compose 的 `wxbot` 服务)是基于官方 iLink 协议 SDK 的微信「调制解调器」,只挂 `agent-mcp-net` 内网、不暴露公网;身份权威与全部会话逻辑在 core,引擎不感知微信。 - **模型**:一条 `wechat_bindings` = 一个 core 用户 = 一个 bot 实例(一人一绑,换号先解绑)。binding id 三用:实例控制/投递的寻址键、wxbot 凭证目录名、channel 键(`channel='wx:'+id`,因此命令层、会话自动新建、投递游标查询全部白借 §5.4 的 channel 机制,零新逻辑)。iLink 协议保证扫码登录后仅本人可与 bot 单线对话,无陌生人入口,故无联系人授权面。 -- **方向三条线**:① Web(设置页→账户→微信内联卡)→ `/api/wechat` → wxbot `/api/instances*`(实例控制;QR SVG 代理内联渲染,只在 has_qr 就绪后取码,服务 token 不出内网);② wxbot 收信 → `POST core:/wxhook/inbox` → 直调 `channel.handleSend()`(文本;image/video/file 媒体先落会话任务目录:带说明文字的拼「用户上传了文件」告知行+正文并进一回合,单发媒体只补一行 `wx_media` 留痕不触发回合(下次真实对话模型自然看到,「刚才那张图」指代不断),同 web 附件链路,voice 二期——命令回执同步回文本;普通消息不回执,等异步投递);③ core 总线监听 assistant_message → 分段(~1800 字/段,行优先聚合)→ `POST wxbot:/api/deliver` → `bot.send`;wxbot 出口统一 stripMarkdown(微信不渲染 markdown);tool_call/tool_result 事件另发 `/api/typing` sendTyping 心跳(每绑定 2s 冷却、失败静默),长工具回合里微信持续显示「正在输入」,文本投递后自动取消。 +- **方向三条线**:① Web(设置页→账户→微信内联卡)→ `/api/wechat` → wxbot `/api/instances*`(实例控制;QR SVG 代理内联渲染,只在 has_qr 就绪后取码,服务 token 不出内网);② wxbot 收信 → `POST core:/wxhook/inbox` → 直调 `channel.handleSend()`(文本;image/video/file 媒体先落会话任务目录:带说明文字的拼「用户上传了文件」告知行+正文并进一回合,单发媒体只补一行 `wx_media` 留痕不触发回合(下次真实对话模型自然看到,「刚才那张图」指代不断),同 web 附件链路;voice 走 iLink 服务端自动转写(msg.text 即识别文字),按文本类转发——命令回执同步回文本;普通消息不回执,等异步投递);③ core 总线监听 assistant_message → 分段(~1800 字/段,行优先聚合)→ `POST wxbot:/api/deliver` → `bot.send`;wxbot 出口统一 stripMarkdown(微信不渲染 markdown);tool_call/tool_result 事件另发 `/api/typing` sendTyping 心跳(每绑定 2s 冷却、失败静默),长工具回合里微信持续显示「正在输入」,文本投递后自动取消。 - **渠道上下文**(ensureChannelContext,普通/媒体/带尾随文本的 /new 收信时幂等确保,先于首条消息入库):微信会话直接落 executing(跳过顾问 handoff,与定时任务同理由)+ 注入一条 `channel_note` user 行(微信环境说明:单线纯文本、给链接即交付卡片、入站文件已存工作目录等,AI 第一回合即知);/clear 删光历史后下条消息自动重注入。 - **出站文件(链接→卡片)**:deliverNow 扫正文 `/p/<22位id>` 链 → 同进程 `publicFiles.resolve` + 归属硬校验(只转本会话签发的链接,防外流)→ 本地读字节(单文件≤20MB、每条回复最多 5 个)→ `POST wxbot:/api/deliver_media` → SDK 按扩展名自动路由 image/video/file 卡片;尽力而为:失败只 warn,链接文字留在正文作兜底(AI 无需感知卡片机制,channel_note 已告知「给链接即交付」)。 - **投递游标** `last_msg_id` 落库 + 每绑定串行队列:重启不重发旧回复,wxbot 短暂不可达不丢(下一条连带补齐);errAck/纯工具轮(空文本)不进微信,`__blocks__` 图消息降级为占位文案。文本投递经 wxbot 出口统一 stripMarkdown(微信不渲染 markdown)。 -- **降级承诺**:`wxbot.url` 未配 = 功能整体静默关闭(启动零日志噪声、设置页入口隐藏);配了但 wxbot 没起 = restore 只留一行 info,面板显示未连接,所有外呼失败只 warn,绝不阻塞/抛出未捕获异常影响 Web 主流程(鉴权/探活失败同样只降级)。绑定/刷新/解绑对 wxbot 均 **fire-and-forget**(点击秒回,不拿 wxbot 网络往返卡按钮;失败落 note 由轮询/刷新按钮恢复);`overview()` 每轮访问拿实例快照双向纠偏(补建缺失实例/纠正丢的 hook),`restore()` 启动对账兼清孤儿实例;前端内联卡按渲染串比对增量更新,QR 只在 has_qr 就绪后才取码,无闪烁无坏图帧。 -- 鉴权:双向共用一个服务 token(根 .env `WXBOT_TOKEN`,init.sh 生成/复用)——core→wxbot 时 wxbot 把该 env 自动并入 /api 白名单;wxbot→core 走 `/wxhook`(挂 auth.middleware 之前,Bearer 哈希后定长比较,token 未配一律 503 fail-closed)。wxbot 零配置文件(同 executor 模式),接线全靠 env,config.yml 仅作可选覆盖。 +- **降级承诺**:微信接入未配置(env `WXBOT_URL` 置空或未配 `WXBOT_TOKEN`)= 功能整体静默关闭(启动零日志噪声、设置页入口隐藏);配了但 wxbot 没起 = restore 只留一行 info,面板显示未连接,所有外呼失败只 warn,绝不阻塞/抛出未捕获异常影响 Web 主流程(鉴权/探活失败同样只降级)。绑定/刷新/解绑对 wxbot 均 **fire-and-forget**(点击秒回,不拿 wxbot 网络往返卡按钮;失败落 note 由轮询/刷新按钮恢复);`overview()` 每轮访问拿实例快照双向纠偏(补建缺失实例/纠正丢的 hook),`restore()` 启动对账兼清孤儿实例;前端内联卡按渲染串比对增量更新,QR 只在 has_qr 就绪后才取码,无闪烁无坏图帧。 +- 鉴权:双向共用一个服务 token(根 .env `WXBOT_TOKEN`,init.sh 生成/复用)——core→wxbot 时 wxbot 把该 env 自动并入 /api 白名单;wxbot→core 走 `/wxhook`(挂 auth.middleware 之前,Bearer 哈希后定长比较,token 未配一律 503 fail-closed)。wxbot 零配置文件(同 executor 模式):接线全靠 env(`WXBOT_TOKEN` / `CORE_URL` / `WXBOT_LOG_LEVEL`,none/off→silent;debug 原样打印收信消息结构),**不挂不读 core 的 config.yml**(密钥只给 core 进程)。 --- @@ -540,7 +540,7 @@ AI 通过 `schedule` 工具为所在会话建周期性任务(`scheduled_tasks` ## 9. 配置 -详见 `app/config.example.yml`(字段与 `server/config.js` 的 `DEFAULTS` 一一对应;顶层 `config.yml` 由 `scripts/init.sh` 生成或手建,**已 gitignore**)。要点: +详见 `app/config.example.yml`(core 专属;字段与 `server/config.js` 的 `DEFAULTS` 一一对应;顶层 `config.yml` 由 `scripts/init.sh` 生成或手建,**已 gitignore**)。要点: - `platforms[].keys[].models[]` —— 三层层级。内部唯一键 = `平台名/模型id`(用于历史会话回绑、用量统计),**改名等于重建其下所有模型**。 - `model_profiles`(顶层)—— 多套可复用的 prompt+tools 组合(`{tools_allow?, tools_deny?, system_prompt_file?}`);模型层用 `profile: <名>` 引用,不配 = 默认全量(仍受顶层 `tools_deny` 屏蔽)。内置 `advising`/`lab`/`zero` 三套默认组合,可用同名覆盖;`advising` 不经模型引用——会话处于顾问阶段时强制命中(见 §4.1 phase 状态机)。元工具自测/纯文本场景用,详见 §5.8;运行期手动切换已全部移除(消息级参数与会话绑定均废弃)。 @@ -555,8 +555,8 @@ AI 通过 `schedule` 工具为所在会话建周期性任务(`scheduled_tasks` - `mcp_servers[].enable: false` —— 启动不加载该服务(配置保留),其余工具不受影响。 - `mcp_servers[].timeout_ms` —— 该服务单次 `tools/call` 的最大等待,默认 60000(夹在 1s~10min);工具发现/握手用固定 15s,不受本项影响。 - `mcp_servers[].tools_allow` / `tools_deny` —— 发现阶段的工具名单(字符串数组,按服务端原始名):allow 白名单,deny 在其后叠加(deny 优先);用于压低发给模型的工具数(如浏览器类服务)。 -- `executor.url` / `executor.token` —— 留空走环境变量 `EXECUTOR_URL` / `EXECUTOR_TOKEN`(compose 默认注入)。 -- `wxbot.url` / `wxbot.token` —— 微信接入(§5.13,可选):url 留空/未配时功能整体静默关闭;留空时读 env `WXBOT_URL` / `WXBOT_TOKEN`(compose 默认注 `http://wxbot:8093`;根 .env 置 `WXBOT_URL=` 可关);`WXBOT_TOKEN` 由 scripts/init.sh 生成/复用,同一值注进 core 与 wxbot 两侧双向互信(wxbot 零配置文件,同 EXECUTOR_TOKEN 模式)。 +- executor 接线 —— **不占配置字段**,纯 env(compose 从根 .env 注入 `EXECUTOR_URL` / `EXECUTOR_TOKEN`;未注 = 本地 spawn,单机调试形态);executor 进程不读本配置文件,日志等级走 `EXECUTOR_LOG_LEVEL`。 +- 微信接入(§5.13)—— **不占 config.yml 字段**(wxbot 已是栈内组件):接线纯 env,`WXBOT_URL`(缺省 `http://wxbot:8093`;根 .env 显式置空 = 微信入口整体静默关闭)与 `WXBOT_TOKEN`(init.sh 生成/复用,同一值注进 core 与 wxbot 两侧双向互信;未配 = 关闭)。旧 config.yml 里的 `wxbot:` 段直接忽略。 --- diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md index 46243ee..9ea65d4 100644 --- a/docs/DEPLOY.md +++ b/docs/DEPLOY.md @@ -68,11 +68,11 @@ cd ../mcp && docker compose up -d --build ```bash cp app/config.example.yml config.yml cp .env.example .env -vi .env # 填 EXECUTOR_TOKEN,生成:openssl rand -hex 32 +vi .env # 填 EXECUTOR_TOKEN / WXBOT_TOKEN(或直接跑 scripts/init.sh 自动生成) vi config.yml ``` -`config.example.yml` 与 `server/config.js` 的默认值一一对应,容器内可直接用(路径默认 +`app/config.example.yml` 与 `server/config.js` 的默认值一一对应,容器内可直接用(路径默认 `/workspace/tasks`、`/workspace/data`)。`config.yml` 里至少要配: ```yaml diff --git a/wxbot/README.md b/wxbot/README.md index 38c6821..b65488b 100644 --- a/wxbot/README.md +++ b/wxbot/README.md @@ -39,9 +39,12 @@ agent-core 的 `wechat_bindings` 表;扫码二维码呈现在 agent-core 的 W | --- | --- | --- | | `WXBOT_TOKEN` | 根 `.env`(`scripts/init.sh` 生成/复用) | 本服务 `/api/*` 鉴权白名单(自动并入)+ 回调 core `/wxhook/*` 的凭据,与 core 侧同一值双向互信 | | `CORE_URL` | compose 静态注 `http://agent-core:8090` | 转发目标 | +| `WXBOT_LOG_LEVEL` | compose 静态注 `info` | 日志等级(debug 原样打印收信消息结构;none/off→silent) | -端口、日志等级、非文本消息占位文案等次要旋钮走 `src/server.js` 内置 DEFAULTS; -确需覆盖时按 `config.yml.example` 头部三步说明操作(建文件 + 解开 compose 里注释的挂载行)。 +端口、非文本消息占位文案等次要旋钮走 `src/server.js` 内置 DEFAULTS;日志等级由 env `WXBOT_LOG_LEVEL` +决定(compose 注入,同 executor 的 `EXECUTOR_LOG_LEVEL` 约定;`debug` 原样打印收信消息结构, +长文本截断、Buffer 只记大小,便于观察新消息类型字段)。 +本服务**不挂不读 core 的 `config.yml`**(内含平台密钥/登录 secret,只给 core 进程)。 ## 部署 @@ -80,8 +83,9 @@ WXBOT_TOKEN=$WXBOT_TOKEN CORE_URL=http://127.0.0.1:8090 \ ## 已知边界 / 后续扩展 -- 语音消息目前回 `bot.empty_hint` 占位(二期:SDK `bot.download(msg)` 拿 WAV(需 `silk-wasm`) - → tools/asr `/api/transcribe` 转写后进会话)。 +- 语音消息已接入:iLink 服务端自动转写(`msg.text` 即识别文字),按普通文本转发进会话—— + 语音说 `/new` 这类命令也能用;转写为空(环境噪音等)时回 `bot.empty_hint` 占位提示。 + 原始 silk 音频不下载,无需本地 ASR。 - 出站文件/图片已实现「链接→卡片」:AI 在回复正文里给 mint 链接,core 自动换成微信文件卡片 (链接文字保留兜底);AI 侧约定见 core 注入的 channel_note。 - core 未配 `WXBOT_URL` 时微信功能整体静默关闭(设置页不出现入口,服务零报错)。 diff --git a/wxbot/app/src/server.js b/wxbot/app/src/server.js index f27bd10..09cb2b1 100644 --- a/wxbot/app/src/server.js +++ b/wxbot/app/src/server.js @@ -7,8 +7,8 @@ // - 凭证按实例隔离在 bot.storage_dir//(compose 卷 ./data),重启自动恢复登录免扫码; // 启动时扫描目录逐个拉起实例(core 起来与否不影响;上线状态经 /wxhook/hook 回报 core,core 不在线则丢弃, // 首条消息的 inbox 会顺带把状态纠回 online)。 -// - 零配置文件:必需接线全走 compose env(WXBOT_TOKEN / CORE_URL,同 executor 的 EXECUTOR_* 模式), -// config.yml 降级为「可选覆盖」(端口/日志等级/占位文案),不存在就用内置默认值。 +// - 零配置文件:必需接线全走 compose env(WXBOT_TOKEN / CORE_URL / WXBOT_LOG_LEVEL,同 executor 的 EXECUTOR_* 模式); +// 不读 core 的 config.yml(内含平台密钥/登录 secret,只给 core 进程),日志等级只认 env,避免两处配置漂移与信息泄漏。 // - 鉴权:/api/* 需 Bearer token;env WXBOT_TOKEN 自动并入白名单,与 core 侧同一值即双向打通; // 仅 /health 开放。凭证 = 微信账号权限,./wxbot/data 卷勿外泄。 import express from "express"; @@ -28,7 +28,7 @@ const DEFAULTS = { }, bot: { storage_dir: "/data/bots", // 每绑定一个子目录(目录名 = binding id) - log_level: "info", // debug | info | warn | error | silent + log_level: "info", // debug | info | warn | error | silent;运行期被 env WXBOT_LOG_LEVEL 覆盖(compose 注入,同 EXECUTOR_LOG_LEVEL 模式) empty_hint: "(这条消息类型暂时接不住——支持文字/图片/视频/文件;指令可发 /help)", // 未接入类型(voice/贴纸等)的本地兑底回执 }, }; @@ -103,6 +103,14 @@ if (!CONFIG.core.url) { } fs.mkdirSync(CONFIG.bot.storage_dir, { recursive: true }); +// 日志等级:env WXBOT_LOG_LEVEL(compose 注入,与 EXECUTOR_LOG_LEVEL 同模式;none/off → SDK 词表的 silent), +// 未注入/非法值走 DEFAULTS(或可选覆盖文件)的值,不影响启动。debug 时收信消息原始结构会原样打印(见 describeMsg)。 +{ + const map = { debug: "debug", info: "info", warn: "warn", error: "error", none: "silent", off: "silent" }; + const lv = String(process.env.WXBOT_LOG_LEVEL || "").trim().toLowerCase(); + CONFIG.bot.log_level = map[lv] || String(CONFIG.bot.log_level || "info").toLowerCase(); +} + // ── 鉴权 ───────────────────────────────────────────────────────────────────── function requireAuth(req, res, next) { if (!CONFIG.auth.enabled) return next(); @@ -220,7 +228,28 @@ function createInstance(id) { const MEDIA_KINDS = new Set(["image", "video", "file"]); const TEXT_LIKE_KINDS = new Set(["text", "voice"]); +// log_level=debug 时打印收信消息的原始结构(长文本截断、Buffer 只记大小、数组只记个数): +// 用于观察新消息类型/未接入类型的字段形态(如 voice 转写文字、混合消息等)。 +function describeMsg(msg) { + const cut = (s) => (s.length > 300 ? s.slice(0, 300) + `…(${s.length})` : s); + const out = {}; + for (const [k, v] of Object.entries(msg || {})) { + if (v === undefined) continue; + if (v === null || typeof v === "number" || typeof v === "boolean") { out[k] = v; continue; } + if (Buffer.isBuffer(v)) { out[k] = ``; continue; } + if (typeof v === "string") { out[k] = cut(v); continue; } + if (Array.isArray(v)) { out[k] = ``; continue; } + let s; + try { s = cut(JSON.stringify(v)); } catch { s = "[object]"; } + out[k] = s === undefined ? "[unserializable]" : s; + } + return out; +} + async function onIncoming(inst, msg) { + if (CONFIG.bot.log_level === "debug") { + try { console.log(`[wxbot:${inst.id}] recv: ${JSON.stringify(describeMsg(msg))}`); } catch { /* 调试日志不进主链路 */ } + } const type = String(msg?.type || "text"); const text = TEXT_LIKE_KINDS.has(type) ? String(msg?.text ?? "").trim() : ""; const userId = String(msg?.userId ?? ""); @@ -375,5 +404,5 @@ for (const ent of fs.readdirSync(CONFIG.bot.storage_dir, { withFileTypes: true } } app.listen(CONFIG.server.port, "0.0.0.0", () => { - console.log(`[wxbot] listening on :${CONFIG.server.port}, core=${CONFIG.core.url || "(未配置)"}, 恢复实例 ${instances.size} 个`); + console.log(`[wxbot] listening on :${CONFIG.server.port}, core=${CONFIG.core.url || "(未配置)"}, log_level=${CONFIG.bot.log_level}, 恢复实例 ${instances.size} 个`); });