diff --git a/app/config.example.yml b/app/config.example.yml
index 810e4c3..afada90 100644
--- a/app/config.example.yml
+++ b/app/config.example.yml
@@ -33,6 +33,11 @@ executor: # 独立命令执行服务;
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
+
terminal:
default_timeout_ms: 30000 # 命令默认超时(ms)
max_output_chars: 10000 # 回传模型的最大输出字符数
diff --git a/app/server/config.js b/app/server/config.js
index 1fe0bb0..cc3e484 100644
--- a/app/server/config.js
+++ b/app/server/config.js
@@ -76,6 +76,9 @@ const DEFAULTS = {
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: '' },
terminal: { default_timeout_ms: 30000, max_output_chars: 10000 },
// fetch:timeout_ms 覆盖请求发出到 body 读完的全生命周期;max_bytes 为流式抓取字节上限(超限即断开)。
fetch: { timeout_ms: 30000, max_bytes: 1048576 },
@@ -269,6 +272,11 @@ function parseAndValidate(rawText, configPath) {
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();
+ // 微信接入(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();
+
// 日志等级:只认 debug/info/warn/error/none(off 是 none 别名),非法值按 info(不影响启动)
cfg.log_level = String(cfg.log_level || 'info').trim().toLowerCase();
if (cfg.log_level === 'off') cfg.log_level = 'none';
diff --git a/app/server/db.js b/app/server/db.js
index dccfe91..498b9de 100644
--- a/app/server/db.js
+++ b/app/server/db.js
@@ -116,6 +116,21 @@ function initDb(dbPath) {
PRIMARY KEY (user, channel)
);
+ -- 微信绑定(wechat.js):一条 core 用户 ↔ 一个 wxbot iLink bot 实例(扫码登录后仅本人可与 bot 单线对话,
+ -- 协议保证无陌生人入口)。binding id 同时用作 channel 键('wx:'+id,走 routes/channel.js 同一套命令层)
+ -- 和 wxbot 凭证目录名,权威在本表;投递游标 last_msg_id 落库,重启不重发旧回复。
+ CREATE TABLE IF NOT EXISTS wechat_bindings (
+ id TEXT PRIMARY KEY,
+ user TEXT NOT NULL,
+ status TEXT NOT NULL DEFAULT 'pending', -- pending 等扫码 | online | expired | error
+ note TEXT, -- 错误/状态说明,面板原样展示
+ bot_account_id TEXT, -- bot 上线后的微信账号标识(登录回调带回,展示用)
+ wx_to_user TEXT, -- 最近来话人 userId(deliver 回发对象;实际上只会是主人自己)
+ last_msg_id INTEGER NOT NULL DEFAULT 0, -- 投递游标:id ≤ 此值的 assistant 消息已送过微信
+ created_at INTEGER NOT NULL,
+ updated_at INTEGER NOT NULL
+ );
+
-- 模型 token 用量流水(每次模型回合一条)。故意不建会话外键:
-- 删会话后累计统计仍需保留
CREATE TABLE IF NOT EXISTS model_usage (
diff --git a/app/server/public/js/core.js b/app/server/public/js/core.js
index 25764a6..80c74f2 100644
--- a/app/server/public/js/core.js
+++ b/app/server/public/js/core.js
@@ -24,6 +24,7 @@
* GET/POST/PUT/DELETE /api/skills[/:name][/file|/upload|/rename] 技能·技能与文件管理
* GET /api/me | POST /api/password | GET /logout 账户·信息/改密/退出
* GET/PUT /api/profile 账户·用户画像(可见/可改/可关)
+ * GET/POST/DELETE /api/wechat[/:id][/qr|/refresh] 账户·微信绑定(未配 wxbot 时入口自动隐藏)
*
* 后端已有但 v2 尚未接入 UI 的接口(先列出,不实现):
* PATCH /api/sessions/:id 重命名(后端已支持)
diff --git a/app/server/public/js/settings.js b/app/server/public/js/settings.js
index 97f309b..753392d 100644
--- a/app/server/public/js/settings.js
+++ b/app/server/public/js/settings.js
@@ -250,6 +250,7 @@
const ctx = () => tok === setTok && setTop() === p; // 异步回包时页面可能已切走
if (p === 'home') return setPageHome(ctx);
if (p === 'account') return setPageAccount(ctx);
+ if (p === 'wechat') return setPageWechat(ctx);
if (p === 'service') return setPageService(ctx);
if (p === 'cfg-editor') return setPageCfgEditor(ctx);
if (p === 'skills') return setPageSkills(ctx);
@@ -344,12 +345,17 @@
try { const r = await req('GET', '/api/me'); if (r && r.user) me = r; } catch (_) { /* 404 等一律按无账户信息处理 */ }
let p = null, pErr = '';
try { p = await req('GET', '/api/profile'); } catch (e) { pErr = String((e && e.message) || e); }
+ // 微信入口:未配置(wxbot.url 空)或「未配 wxbot 容器」时整卡隐藏,普通用户零打扰;
+ // 已有绑定时即使 wxbot 没起也要展示(否则用户看不到自己的绑定状态)。
+ let wx = null;
+ try { const r = await req('GET', '/api/wechat'); if (r && r.enabled && (r.alive || (r.bindings || []).length)) wx = r; } catch (_) { /* 旧后端/异常隐藏 */ }
if (!ctx()) return;
let html = '
');
}
async function changePassword() {
@@ -388,6 +394,88 @@
catch (e) { toast('保存失败:' + e.message); }
}
+ // ---------- 页:微信绑定(后端 wechat.js + wxbot iLink;一人一绑,扫码后仅本人可与 bot 单线对话) ----------
+ const WX_STATUS = { pending: ['待扫码', 'held'], online: ['已连接', 'active'], expired: ['二维码过期', 'held'], error: ['异常', 'cancelled'] };
+ let wxTimer = null;
+ function stopWxPoll() { if (wxTimer) { clearInterval(wxTimer); wxTimer = null; } }
+
+ function wechatCardHtml(w) {
+ const n = (w.bindings || []).length;
+ const sum = n ? ('已绑定 ' + n + ' 个 · ' + (w.alive ? '服务在线' : '服务未连接')) : (w.alive ? '未绑定' : '服务未连接');
+ return '微信绑定 ' + esc(sum) + '
' +
+ '
' +
+ '
微信里给 bot 好友发文字即与 Agent 对话;发送 /help 查看全部命令。会话与网页端同源。
';
+ }
+
+ async function setPageWechat(ctx) {
+ setTitle('微信绑定');
+ setActions('');
+ setBody('');
+ await renderWechatPage(ctx);
+ }
+
+ async function renderWechatPage(ctx) {
+ stopWxPoll();
+ let w = null, err = '';
+ try { w = await req('GET', '/api/wechat'); } catch (e) { err = String(e && e.message || e); }
+ if (!ctx()) return;
+ if (!w) { setBody(''); return; }
+ if (!w.enabled) { setBody(''); return; }
+ const bindings = w.bindings || [];
+ let html = '');
+ return;
+ }
+ for (const b of bindings) {
+ const st = WX_STATUS[b.status] || [b.status || '-', 'held'];
+ html += '' + esc(b.id) + ' ' + esc(st[0]) + '
';
+ if (b.note) html += '
' + esc(b.note) + '
';
+ if (b.bot_account_id) html += '
' + esc(b.bot_account_id) + '
';
+ if (b.status === 'pending') {
+ // ts 参数防缓存;二维码过期时 wxbot 侧无码 → 404,img 加载失败不致命,轮询到状态变 expired 后换成刷新按钮
+ html += '
' +
+ '
微信「扫一扫」扫码并在手机上确认;没反应就点下方刷新。
';
+ } else if (b.status === 'expired' || b.status === 'error') {
+ html += '
';
+ } else if (b.status === 'online') {
+ html += '
已在线:直接给微信里的 bot 好友发消息开始对话(/help 看命令)。在网页端也能看到同一个会话。
';
+ }
+ html += '
';
+ }
+ setBody(html + '');
+ // 待扫码时轮询状态(上线/过期都要即时换画面);页面切走后 ctx 失效自停
+ if (bindings.some(b => b.status === 'pending')) {
+ wxTimer = setInterval(() => {
+ if (!ctx()) { stopWxPoll(); return; }
+ renderWechatPage(ctx);
+ }, 2500);
+ }
+ }
+
+ async function wxBind() {
+ try { await req('POST', '/api/wechat'); toast('已生成,请微信扫码'); renderWechatPage(() => true); }
+ catch (e) { toast('绑定失败:' + e.message); }
+ }
+ async function wxRefresh(id) {
+ try { await req('POST', '/api/wechat/' + encodeURIComponent(id) + '/refresh'); renderWechatPage(() => true); }
+ catch (e) { toast('刷新失败:' + e.message); }
+ }
+ async function wxUnbind(id) {
+ if (!await confirmModal('解绑微信', '解绑后该微信 bot 实例与登录凭证将被销毁,需重新扫码才能恢复;会话记录保留。', '解绑', true)) return;
+ try { await req('DELETE', '/api/wechat/' + encodeURIComponent(id)); toast('已解绑'); renderWechatPage(() => true); }
+ catch (e) { toast('解绑失败:' + e.message); }
+ }
+
// ---------- 页:服务(服务状态 + 系统配置;搬自 settings.js) ----------
const CFG_FORM = [
{ group: 'Agent 会话', items: [
@@ -1418,6 +1506,10 @@
// 账户
changePassword: changePassword,
saveProfile: saveProfile,
+ // 微信绑定
+ wxBind: wxBind,
+ wxRefresh: wxRefresh,
+ wxUnbind: wxUnbind,
logout: async function () {
sessionStorage.removeItem('agent_creds'); // 旧版本遗留的 Basic 凭据,顺带清理
localStorage.removeItem('agent_token'); // 清 autoRestore token,防止自动恢复旧用户
diff --git a/app/server/routes/channel.js b/app/server/routes/channel.js
index 3f58853..d84c192 100644
--- a/app/server/routes/channel.js
+++ b/app/server/routes/channel.js
@@ -113,17 +113,15 @@ function statusReply(db, s) {
}
// ---------- 入口 ----------
-// POST /api/channel/send {channel?, text} → {kind, reply, session_id, message_id?}
-// - kind='message':普通消息已入会话开跑;kind='command':reply 即命令回执(纯文本,IM 直接转发)。
-// - AI 的正式回复不在本接口返回:接入端复用 SSE GET /api/sessions/:id/stream 或轮询会话详情。
-// - 引擎主动拒绝的(回合进行中点压缩/清空)走 HTTP 4xx {error},语义与 Web 路由一致。
-router.post('/send', wrap((req, res) => {
- const db = engine.getDb();
- const user = String(req.user || '').trim().slice(0, 64); // 认证用户;未开认证为空串(自用单用户)
- const channel = String((req.body || {}).channel || '').trim().slice(0, 64);
- const text = String((req.body || {}).text || '').trim();
+// 命令主流程:Web 接入(POST /api/channel/send)与微信桥接(wechat.js 直调)共用同一函数,
+// 命令表/会话绑定/自动建会话只有一份实现;来源差异(日志前缀 tag、身份解析)由调用方注入。
+// 返回 {kind, reply, session_id, message_id?};引擎拒绝的(回合进行中压缩/清空)抛 {status_code},由调用方映射。
+function handleSend(db, opts) {
+ const user = String(opts.user || '').trim().slice(0, 64);
+ const channel = String(opts.channel || '').trim().slice(0, 64);
+ const text = String(opts.text || '').trim();
if (!text) throw Object.assign(new Error('text 不能为空'), { status_code: 400 });
- const tag = (user || '-') + ' [' + (channel || 'default') + ']';
+ const tag = opts.tag || ((user || '-') + ' [' + (channel || 'default') + ']');
const parsed = parseCommand(text);
@@ -138,63 +136,76 @@ router.post('/send', wrap((req, res) => {
sent = engine.postUserMessage(s.id, text);
}
log.info('msg', tag + ' channel 消息 → ' + s.id);
- return res.json({ kind: 'message', reply: '已发送到会话 ' + s.id, session_id: s.id, message_id: sent.message_id });
+ return { kind: 'message', reply: '已发送到会话 ' + s.id, session_id: s.id, message_id: sent.message_id };
}
if (parsed.unknown) {
const s = boundSession(db, user, channel);
- return res.json({ kind: 'command', reply: '/' + parsed.unknown + ' 不是有效命令,发送 /help 查看清单', session_id: s ? s.id : null });
+ return { kind: 'command', reply: '/' + parsed.unknown + ' 不是有效命令,发送 /help 查看清单', session_id: s ? s.id : null };
}
const cmd = parsed.cmd;
if (cmd === 'help') {
const s = boundSession(db, user, channel);
- return res.json({ kind: 'command', reply: HELP_TEXT, session_id: s ? s.id : null });
+ return { kind: 'command', reply: HELP_TEXT, session_id: s ? s.id : null };
}
if (cmd === 'new') {
const r = newSessionFor(db, user, channel, parsed.rest);
log.info('task', tag + ' channel /new → ' + r.s.id + (parsed.rest ? '(含首条消息)' : ''));
- return res.json({
+ return {
kind: 'command',
reply: '已新建会话 ' + r.s.id + (parsed.rest ? ',首条消息已发出' : '(发普通消息或 /status 查看状态)'),
session_id: r.s.id,
message_id: r.sent ? r.sent.message_id : undefined,
- });
+ };
}
// 其余命令都作用于当前会话;无绑定时不隐式新建(那不是用户点这条命令的意图)
const s = boundSession(db, user, channel);
if (!s) {
- return res.json({ kind: 'command', reply: '当前没有会话(先 /new,或直接发一条普通消息自动新建)', session_id: null });
+ return { kind: 'command', reply: '当前没有会话(先 /new,或直接发一条普通消息自动新建)', session_id: null };
}
if (cmd === 'stop') {
// 与 Web 按钮语义对齐:只有回合真在跑才停,idle 不误伤(stop 会把 held 刷成 cancelled)
const run = engine.getRun(s.id);
if (!(run && run.looping)) {
- return res.json({ kind: 'command', reply: '当前没有进行中的回合(无需终止)', session_id: s.id });
+ return { kind: 'command', reply: '当前没有进行中的回合(无需终止)', session_id: s.id };
}
engine.stop(s.id);
log.info('msg', tag + ' channel /stop ' + s.id);
- return res.json({ kind: 'command', reply: '已发送终止指令,回合收尾中', session_id: s.id });
+ return { kind: 'command', reply: '已发送终止指令,回合收尾中', session_id: s.id };
}
if (cmd === 'compact') {
engine.summarizeContext(s.id); // 回合进行中 engine 抛 409(请先终止),冒给调用方
log.info('msg', tag + ' channel /compact ' + s.id);
- return res.json({ kind: 'command', reply: '已发起上下文压缩,摘要稍后会作为一条回复出现在会话里', session_id: s.id });
+ return { kind: 'command', reply: '已发起上下文压缩,摘要稍后会作为一条回复出现在会话里', session_id: s.id };
}
if (cmd === 'clear') {
engine.clearSessionMessages(s.id); // 同上,回合进行中 409
log.info('msg', tag + ' channel /clear ' + s.id);
- return res.json({ kind: 'command', reply: '已清空当前会话(回到顾问模式),继续发消息即从零开始', session_id: s.id });
+ return { kind: 'command', reply: '已清空当前会话(回到顾问模式),继续发消息即从零开始', session_id: s.id };
}
// cmd === 'status'
- return res.json({ kind: 'command', reply: statusReply(db, s), session_id: s.id });
+ return { kind: 'command', reply: statusReply(db, s), session_id: s.id };
+}
+
+// HTTP 入口:POST /api/channel/send {channel?, text} → handleSend 结果。
+// - kind='message':普通消息已入会话开跑;kind='command':reply 即命令回执(纯文本,IM 直接转发)。
+// - AI 的正式回复不在本接口返回:接入端复用 SSE GET /api/sessions/:id/stream 或轮询会话详情。
+// - 引擎主动拒绝的走 HTTP 4xx {error},语义与 Web 路由一致。
+router.post('/send', wrap((req, res) => {
+ res.json(handleSend(engine.getDb(), {
+ user: String(req.user || '').trim(), // 认证用户;未开认证为空串(自用单用户)
+ channel: (req.body || {}).channel,
+ text: (req.body || {}).text,
+ }));
}));
module.exports = router;
+module.exports.handleSend = handleSend;
diff --git a/app/server/routes/wechat.js b/app/server/routes/wechat.js
new file mode 100644
index 0000000..66c976a
--- /dev/null
+++ b/app/server/routes/wechat.js
@@ -0,0 +1,105 @@
+// 微信接入路由:
+// - 本文件默认导出 = Web 侧 router(挂在 auth.middleware 之后,cookie 鉴权 + req.user 隔离);
+// - 具名导出 hookRouter = wxbot → core 的内网回调入口(/wxhook/*),挂在 auth.middleware 之前,
+// 形态同 GET /p/(Core 上除登录外的匿名入口家族),靠共享服务 token(Bearer,常量时间比较)把门。
+// 业务全部在 wechat.js,这里只做鉴权、归属过滤与 HTTP 形状。
+const crypto = require('crypto');
+const express = require('express');
+const engine = require('../engine');
+const wechat = require('../wechat');
+
+const router = express.Router();
+const hookRouter = express.Router();
+
+function wrap(fn) {
+ return function (req, res) {
+ try {
+ const r = fn(req, res);
+ if (r && typeof r.catch === 'function') r.catch(err => sendErr(res, err));
+ } catch (err) {
+ sendErr(res, err);
+ }
+ };
+}
+
+function sendErr(res, err) {
+ const code = err && err.status_code || 500;
+ res.status(code).json({ error: String(err && err.message || err) });
+}
+
+// 先哈希再定长比较(同 auth.js timingEqual):避免长度旁路与提前返回侧信道
+function timingEqual(a, b) {
+ const ha = crypto.createHash('sha256').update(String(a)).digest();
+ const hb = crypto.createHash('sha256').update(String(b)).digest();
+ return crypto.timingSafeEqual(ha, hb);
+}
+
+// ---------- wxbot 内网回调 ----------
+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)' });
+ 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' });
+ }
+ next();
+}
+
+// 来消息 → channel 层。非 2xx 时 wxbot 会把 {error} 文案回给微信用户(出错出声)。
+hookRouter.post('/inbox', requireService, wrap((req, res) => {
+ res.json(wechat.handleInbox(req.body) || { ok: true });
+}));
+
+// 实例状态回调(online/expired/error/offline):失败只当丢弃(绑定行没了 = 已解绑)。
+hookRouter.post('/hook', requireService, wrap((req, res) => {
+ const hit = wechat.handleHook(req.body);
+ res.json({ ok: true, ignored: !hit });
+}));
+
+// ---------- Web API ----------
+function rowFor(req) {
+ const b = wechat.getBinding(String(req.params.id || ''));
+ if (!b || b.user !== String(req.user || '')) {
+ throw Object.assign(new Error('绑定不存在'), { status_code: 404 });
+ }
+ return b;
+}
+
+// 面板总览:enabled=false(wxbot.url 未配)时前端整卡隐藏——没配置就当功能不存在。
+router.get('/', wrap(async (req, res) => {
+ const user = String(req.user || '');
+ const alive = await wechat.wxbotAlive();
+ res.json({ enabled: wechat.enabled(), alive, bindings: wechat.listBindings(user) });
+}));
+
+router.post('/', wrap(async (req, res) => {
+ const b = await wechat.createBinding(String(req.user || ''));
+ res.json(b);
+}));
+
+router.get('/:id', wrap((req, res) => {
+ res.json(rowFor(req));
+}));
+
+// QR 代理:wxbot SVG 原样透传(前端
带 cookie 即可,服务 token 不出内网)。
+// 无码可给(已上线/未生成/wxbot 不可达)统一 404 {error},前端按绑定状态渲染占位,不出红叉。
+router.get('/:id/qr', wrap(async (req, res) => {
+ const b = rowFor(req);
+ const r = await wechat.qrSvg(b);
+ if (r.none) return res.status(404).json({ error: '当前没有待扫二维码(可能已上线,或点「刷新」重新获取)' });
+ res.type('image/svg+xml').send(r.svg);
+}));
+
+router.post('/:id/refresh', wrap(async (req, res) => {
+ const b = rowFor(req);
+ res.json(await wechat.refreshBinding(b.id));
+}));
+
+router.delete('/:id', wrap(async (req, res) => {
+ const b = rowFor(req);
+ res.json(await wechat.deleteBinding(b.id));
+}));
+
+module.exports = router;
+module.exports.hookRouter = hookRouter;
diff --git a/app/server/server.js b/app/server/server.js
index bba121e..e6b1c89 100644
--- a/app/server/server.js
+++ b/app/server/server.js
@@ -10,6 +10,7 @@ const { createBus } = require('./sse');
const { createAuth } = require('./auth');
const engine = require('./engine');
const scheduler = require('./scheduler');
+const wechat = require('./wechat');
const llm = require('./llm');
const mcp = require('./mcp');
const skills = require('./tools/skills');
@@ -26,6 +27,10 @@ engine.init();
//(active/遗留 queued → held),首轮 tick 才不会看到脏状态。
scheduler.start(engine);
+// 微信接入(wechat.js,可选能力):wxbot.url 未配 = 全部静默关闭;配了但 wxbot 没起 =
+// restore 只留一行日志,不重试不报错(用户在设置页点刷新自愈),不影响 Web 主流程。
+wechat.init(cfg, db, bus);
+
const app = express();
const server = http.createServer(app);
@@ -40,6 +45,10 @@ app.use(auth.router); // /login、/logout、/api/login 等免认证端点
// 安全性来自“22 字符随机 ID + 服务端过期”,详见 routes/public-files.js 头注释。
app.use('/p', require('./routes/public-files'));
+// wxbot 内网回调(/wxhook/inbox|hook):同在 auth.middleware 之前,凭共享服务 token(Bearer)把门,
+// 微信用户永远不该直接碰这两个端点(wxbot 只挂内网,不暴露公网)。
+app.use('/wxhook', require('./routes/wechat').hookRouter);
+
app.use(auth.middleware); // 其余请求需登录态(cookie 或 Basic 头)
app.use(express.static(path.join(__dirname, 'public')));
@@ -53,6 +62,8 @@ app.use('/api/platforms', require('./routes/platforms'));
app.use('/api/system', require('./routes/system'));
// 用户画像(账户设置):读写按登录用户隔离,逻辑在 user-profile.js
app.use('/api/profile', require('./routes/profile'));
+// 微信绑定管理(设置页→账户→微信绑定),业务在 wechat.js;未配置时接口返回 enabled:false,前端整卡隐藏
+app.use('/api/wechat', require('./routes/wechat'));
// 文本命令接入端(IM/CLI 等无 UI 客户端):命令解析 + (user, channel) 当前会话绑定,见 routes/channel.js
app.use('/api/channel', require('./routes/channel'));
// data-page 技能配套:任务 app/ 子树页面向导 /app/{task_id}/ + 数据 API /api/db/{task_id}/query。
@@ -163,7 +174,10 @@ 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', ' log_level=' + cfg.log_level);
+ // 微信实例恢复 fire-and-forget:wxbot 没起只留日志,绝不阻塞/抛错影响启动。
+ wechat.restore().catch(e => log.warn('wechat', '启动恢复异常:' + (e && e.message || e)));
// prompt dump 失败不影响服务:只是核对用产物。
try {
dumpPromptBundle();
diff --git a/app/server/sse.js b/app/server/sse.js
index 1c19e09..c4692dc 100644
--- a/app/server/sse.js
+++ b/app/server/sse.js
@@ -1,6 +1,14 @@
// 按会话分组的 SSE 事件总线;前端通过 GET /api/sessions/:id/stream 订阅。
+// 另有一组「内部订阅者」(onInternal):同进程的桥接功能(如微信推送 wechat.js)监听回合事件;
+// 与 HTTP 客户端不同,内部订阅者不受「无观看者早退」影响——微信会话常常没有任何 Web 页面在看。
function createBus() {
const clients = new Map(); // session_id -> Set
+ const internal = new Set(); // fn(sessionId, event, data)
+
+ function onInternal(fn) {
+ internal.add(fn);
+ return () => internal.delete(fn);
+ }
function addClient(sessionId, res) {
if (!clients.has(sessionId)) clients.set(sessionId, new Set());
@@ -15,7 +23,13 @@ function createBus() {
}
// event 名称 + 任意 JSON data。无客户端时静默丢弃(消息本身已持久化,重连可回放)。
+ // 内部订阅者先跑(单个抛错不影响投递其余),再发 HTTP 客户端。
function emit(sessionId, event, data) {
+ if (internal.size) {
+ for (const fn of Array.from(internal)) {
+ try { fn(sessionId, event, data); } catch (_) { /* 内部监听不干扰正常广播 */ }
+ }
+ }
const set = clients.get(sessionId);
if (!set || set.size === 0) return;
const payload = 'event: ' + event + '\ndata: ' + JSON.stringify(data) + '\n\n';
@@ -44,7 +58,7 @@ function createBus() {
for (const sessionId of Array.from(clients.keys())) closeAll(sessionId);
}
- return { addClient, removeClient, emit, closeAll, closeAllSessions, clientCount };
+ return { addClient, removeClient, emit, closeAll, closeAllSessions, clientCount, onInternal };
}
module.exports = { createBus };
diff --git a/app/server/wechat.js b/app/server/wechat.js
new file mode 100644
index 0000000..7d10cec
--- /dev/null
+++ b/app/server/wechat.js
@@ -0,0 +1,272 @@
+// 微信接入桥接(core 侧大脑)。信任与分工模型(设计讨论见 docs/ARCHITECTURE.md §5.13):
+// - wxbot(独立容器,只挂 agent-mcp-net)= 纯微信「调制解调器」:iLink SDK 多实例、收信转发、外发投递;
+// 对 core 的一切认知只有共享服务 token,不持有任何用户凭据。
+// - core = 身份与调度的唯一权威:wechat_bindings 表维护 (core 用户 ↔ binding ↔ 微信 bot 账号);
+// 微信会话复用 routes/channel.js 同一套命令层(channel = 'wx:'+binding_id),引擎不感知微信。
+// - 扫码登录的呈现挪进 core 的 Web 设置页(QR 经本模块代理 wxbot 的 SVG);
+// iLink 协议保证扫码后仅本人可与 bot 单线对话,故无联系人授权面。
+// 方向:
+// Web → routes/wechat.js → 本模块 → wxbot /api/instances*(实例控制 / QR 代理)
+// wxbot → core /wxhook/{inbox,hook}(Bearer 服务 token,挂在 auth.middleware 之前)
+// core → wxbot /api/deliver(assistant 最终回复推送;总线内部监听驱动,游标落库不重发)
+// 降级承诺:wxbot.url 未配置 = 功能整体静默关闭;配置了但 wxbot 没起 = 启动只留一行日志,
+// 面板显示「未连接」、操作时报可读错误,绝不抛出未捕获异常影响 Web 主流程。
+const crypto = require('crypto');
+const engine = require('./engine');
+const log = require('./log');
+const channel = require('./routes/channel'); // 只用 handleSend(模块加载无副作用;engine 不 require 本模块,无环)
+
+let cfg, db, bus;
+let busAttached = false;
+
+function init(cfg_, db_, bus_) {
+ cfg = cfg_; db = db_; bus = bus_;
+ attachBus();
+}
+
+const now = () => Date.now();
+const msg = e => String((e && e.message) || e || 'unknown');
+
+// ---------- 开关与 wxbot 客户端 ----------
+function enabled() { return !!(cfg && cfg.wxbot && cfg.wxbot.url); }
+
+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 });
+ const res = await fetch(wxUrl() + path, {
+ method,
+ headers: Object.assign(
+ { Authorization: 'Bearer ' + wxToken() },
+ body ? { 'Content-Type': 'application/json' } : {}
+ ),
+ body: body ? JSON.stringify(body) : undefined,
+ signal: AbortSignal.timeout(timeoutMs || 8000),
+ });
+ const text = await res.text();
+ if (!res.ok) {
+ let detail = text;
+ try { detail = (JSON.parse(text) || {}).error || text; } catch (_) {}
+ throw Object.assign(new Error('wxbot ' + res.status + ': ' + String(detail).slice(0, 200)), { status_code: 502 });
+ }
+ if (!text) return null;
+ try { return JSON.parse(text); } catch (_) { return text; }
+}
+
+// 存活探测(GET /wxbot 面板用):带 5s 缓存,wxbot 挂掉只表现为 false,绝不外抛。
+let aliveCache = { at: 0, ok: false };
+async function wxbotAlive() {
+ if (!enabled()) return false;
+ if (now() - aliveCache.at < 5000) return aliveCache.ok;
+ let ok = false;
+ try {
+ const r = await fetch(wxUrl() + '/health', { signal: AbortSignal.timeout(2500) });
+ ok = r.ok;
+ } catch (_) { /* 不在线 */ }
+ aliveCache = { at: now(), ok };
+ return ok;
+}
+
+// ---------- 绑定表 ----------
+const BIND_COLS = 'id, user, status, note, bot_account_id, wx_to_user, last_msg_id, created_at, updated_at';
+
+function getBinding(id) {
+ return db.prepare('SELECT * FROM wechat_bindings WHERE id = ?').get(id);
+}
+
+function touchBinding(id, fields) {
+ const sets = ['updated_at = ?'];
+ const vals = [now()];
+ for (const [k, v] of Object.entries(fields || {})) { sets.push(k + ' = ?'); vals.push(v); }
+ vals.push(id);
+ db.prepare('UPDATE wechat_bindings SET ' + sets.join(', ') + ' WHERE id = ?').run(...vals);
+}
+
+// 一人一绑(自用形态;换微信号走「解绑→重绑」);id 兼作 channel 后缀与 wxbot 存储目录名 → 只允许安全字符。
+async function createBinding(user) {
+ if (!enabled()) throw Object.assign(new Error('微信接入未配置(wxbot.url 为空),请联系管理员在 config.yml / 环境变量 WXBOT_URL 启用后重启'), { 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');
+ db.prepare(
+ "INSERT INTO wechat_bindings (id, user, status, last_msg_id, created_at, updated_at) VALUES (?,?,'pending',0,?,?)"
+ ).run(id, user, now(), now());
+ try {
+ await wxbotApi('POST', '/api/instances', { id });
+ } catch (e) {
+ touchBinding(id, { status: 'error', note: msg(e) });
+ log.warn('wechat', id + ' 创建绑定成功但 wxbot 实例启动失败:' + msg(e));
+ }
+ log.info('wechat', (user || '-') + ' 新建微信绑定 ' + id);
+ return getBinding(id);
+}
+
+// 重发登录(二维码过期/失败后用):清状态 → wxbot 重起登录流程。
+async function refreshBinding(id) {
+ const b = mustBinding(id);
+ await wxbotApi('POST', '/api/instances/' + encodeURIComponent(b.id) + '/refresh');
+ touchBinding(b.id, { status: 'pending', note: null });
+ return getBinding(b.id);
+}
+
+// 解绑:wxbot 停实例并删凭证(尽力而为,网络断了本地也必须删干净)。
+async function deleteBinding(id) {
+ const b = mustBinding(id);
+ try { await wxbotApi('DELETE', '/api/instances/' + encodeURIComponent(b.id)); }
+ catch (e) { log.warn('wechat', b.id + ' 通知 wxbot 销毁实例失败(本地继续解绑):' + msg(e)); }
+ db.prepare('DELETE FROM wechat_bindings WHERE id = ?').run(b.id);
+ db.prepare("DELETE FROM channel_sessions WHERE channel = ?").run('wx:' + b.id);
+ log.info('wechat', (b.user || '-') + ' 解绑微信 ' + b.id);
+ return { ok: true };
+}
+
+function mustBinding(id) {
+ const b = getBinding(id);
+ if (!b) throw Object.assign(new Error('绑定不存在'), { status_code: 404 });
+ return b;
+}
+
+function listBindings(user) {
+ return db.prepare('SELECT ' + BIND_COLS + ' FROM wechat_bindings WHERE user = ? ORDER BY created_at DESC').all(user);
+}
+
+// QR 代理:wxbot 的 SVG 原样透传给 core 前端
(cookie 鉴权在路由层,wxbot token 只在内网)。
+// wxbot 404(无待扫二维码)翻译成 {none:true},前端按状态渲染,避免 img 报错红叉。
+async function qrSvg(b) {
+ if (!enabled()) return { none: true };
+ try {
+ const res = await fetch(wxUrl() + '/api/instances/' + encodeURIComponent(b.id) + '/qr.svg', {
+ headers: { Authorization: 'Bearer ' + wxToken() },
+ signal: AbortSignal.timeout(8000),
+ });
+ if (!res.ok) return { none: true };
+ return { svg: await res.text() };
+ } catch (_) { return { none: true }; }
+}
+
+// 启动恢复:把表里的 binding 逐个 POST 到 wxbot(幂等,wxbot 端 Map 去重)。
+// wxbot 不在线只留一行 info(它起来后用户点一次「刷新」或重新绑定即可自愈,不追着重试)。
+async function restore() {
+ if (!enabled()) return;
+ const rows = db.prepare('SELECT id FROM wechat_bindings').all();
+ if (!rows.length) return;
+ let ok = 0, fail = 0;
+ for (const r of rows) {
+ try { await wxbotApi('POST', '/api/instances', { id: r.id }, 4000); ok++; }
+ catch (_) { fail++; }
+ }
+ if (fail) log.info('wechat', '启动恢复:' + ok + '/' + rows.length + ' 个实例已确保存在,' + fail + ' 个失败(wxbot 未启动?可在设置页刷新重试)');
+ else log.info('wechat', '启动恢复:' + ok + ' 个微信实例已确保存在');
+}
+
+// ---------- wxbot → core 回调(/wxhook,Bearer 服务 token,auth.middleware 之前挂载) ----------
+function handleHook(body) {
+ const b = getBinding(String((body || {}).id || ''));
+ if (!b) return false;
+ const event = String(body.event || '');
+ if (event === 'online') touchBinding(b.id, { status: 'online', bot_account_id: body.accountId || b.bot_account_id, note: null });
+ else if (event === 'expired') touchBinding(b.id, { status: 'expired', note: String(body.note || '二维码已过期').slice(0, 200) });
+ else if (event === 'error') touchBinding(b.id, { status: 'error', note: String(body.note || '实例异常').slice(0, 200) });
+ else if (event === 'offline') touchBinding(b.id, { status: 'error', note: '实例已离线' });
+ else return false;
+ log.info('wechat', b.id + ' 状态 → ' + event);
+ return true;
+}
+
+// 微信来消息 → channel 层同一入口。返回 handleSend 结果;抛错冒给 hook 路由映射成非 2xx,
+// wxbot 会把 error 文案直接回给用户(IM 里「出错要出声」)。
+function handleInbox(body) {
+ const b = getBinding(String((body || {}).id || ''));
+ if (!b) throw Object.assign(new Error('绑定不存在(可能已解绑)'), { status_code: 404 });
+ const from = String((body || {}).from || '').trim().slice(0, 128);
+ if (from && from !== b.wx_to_user) touchBinding(b.id, { wx_to_user: from });
+ // 能收到消息就说明实例活着;漏收 online 回调(core 重启窗口)时顺带纠偏
+ if (b.status !== 'online') touchBinding(b.id, { status: 'online', note: null });
+ return channel.handleSend(db, {
+ user: b.user,
+ channel: 'wx:' + b.id,
+ text: (body || {}).text,
+ tag: (b.user || '-') + ' [微信 ' + b.id + ']',
+ });
+}
+
+// ---------- 投递:进程内总线监听 → 分段 push wxbot /api/deliver ----------
+// 只推最终 assistant 文本(type=errAck / 纯工具轮空文本 / 存档类事件都不进微信);
+// 游标 last_msg_id 落库:core 重启不补发历史,wxbot 短暂不可达时不丢(下一条事件连带补齐)。
+function attachBus() {
+ if (busAttached || !bus) return;
+ busAttached = true;
+ bus.onInternal((sessionId, event, data) => {
+ if (event !== 'assistant_message' || !data) return;
+ try {
+ const cs = db.prepare('SELECT user, channel FROM channel_sessions WHERE session_id = ?').get(sessionId);
+ if (!cs || !String(cs.channel || '').startsWith('wx:')) return;
+ enqueueDelivery(cs.channel.slice(3), () => deliverNow(cs.channel.slice(3), data));
+ } catch (e) {
+ log.warn('wechat', '投递监听异常:' + msg(e));
+ }
+ });
+}
+
+// 每绑定一条串行链:assistant 事件按序到达也按序投递,且防并发推进游标互相覆盖。
+const deliveryQ = new Map();
+function enqueueDelivery(key, fn) {
+ const prev = deliveryQ.get(key) || Promise.resolve();
+ const next = prev.then(fn, fn).catch(() => {});
+ deliveryQ.set(key, next);
+ next.then(() => { if (deliveryQ.get(key) === next) deliveryQ.delete(key); });
+}
+
+async function deliverNow(bid, m) {
+ const b = getBinding(bid);
+ if (!b || b.status !== 'online' || !b.wx_to_user) return;
+ if (m.type === 'errAck') return;
+ let content = String(m.content || '').trim();
+ if (!content) return; // 纯工具调用轮(无文本)不打扰微信
+ if (content.startsWith('{"__blocks__"')) content = '【富文本消息,请到网页端查看】';
+ const id = Number(m.id) || 0;
+ if (id && id <= (b.last_msg_id || 0)) return;
+ const segs = splitText(content);
+ for (const s of segs) {
+ try { await wxbotApi('POST', '/api/deliver', { id: b.id, to: b.wx_to_user, text: s }, 15000); }
+ catch (e) {
+ log.warn('wechat', b.id + ' 投递失败,游标未推进(下次回复连带补齐):' + msg(e));
+ return;
+ }
+ }
+ if (id > (b.last_msg_id || 0)) touchBinding(b.id, { last_msg_id: id });
+ log.info('wechat', b.id + ' 已投递消息 ' + id + '(' + segs.length + ' 段)→ 微信');
+}
+
+// 微信单条上限按 ~1800 字保守分段:先按行聚合,超长行硬切。
+function splitText(text, max = 1800) {
+ const out = [];
+ let cur = '';
+ for (const line of String(text).split('\n')) {
+ if (line.length > max) {
+ if (cur) { out.push(cur); cur = ''; }
+ for (let i = 0; i < line.length; i += max) out.push(line.slice(i, i + max));
+ continue;
+ }
+ if (cur && (cur.length + 1 + line.length) > max) { out.push(cur); cur = line; }
+ else cur = cur ? cur + '\n' + line : line;
+ }
+ if (cur) out.push(cur);
+ return out;
+}
+
+module.exports = {
+ init,
+ restore,
+ enabled,
+ wxbotAlive,
+ getBinding,
+ listBindings,
+ createBinding,
+ refreshBinding,
+ deleteBinding,
+ qrSvg,
+ handleHook,
+ handleInbox,
+};
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 75dc053..0eb4f27 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -38,6 +38,7 @@ agent/
│ │ ├── llm.js 上游 OpenAI 兼容 /chat/completions 流式调用 + 消息组装
│ │ ├── mcp.js 极简 MCP 客户端(Streamable HTTP,init→tools/list→tools/call)
│ │ ├── remote-exec.js agent-executor 远端执行客户端(SSE 收流)
+│ │ ├── wechat.js 微信接入桥接(wechat_bindings 权威 / 实例控制 / inbox / 总线投递;wxbot 为仓库内私有组件不入 git,见 §5.13)
│ │ ├── balance.js 余额查询适配器(按 platform.type 分发)
│ │ ├── version.js 版本信息(package.json + git 短提交号)
│ │ ├── tools/
@@ -52,6 +53,7 @@ agent/
│ │ │ ├── messages.js /api/sessions/:id/messages + SSE 流 + stop/release
│ │ │ ├── files.js /api/sessions/:id/files 上传/列表/下载/删除
│ │ │ ├── channel.js /api/channel/send 文本命令接入(IM/CLI 等无 UI 端;当前会话绑定 + /new /stop /compact /clear /status /help)
+│ │ │ ├── wechat.js /api/wechat 绑定管理(设置页)+ /wxhook 内网回调(微信接入,见 §5.13)
│ │ │ ├── config.js /api/config 读写(含 api_key/password 脱敏)
│ │ │ ├── platforms.js /api/platforms/balance 余额查询
│ │ │ ├── skills.js /api/skills 技能文件管理
@@ -146,9 +148,9 @@ 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)。
+6. `scheduler.start(engine)`:启动定时任务轮询(30s 一次,`unref`)。**必须在 engine.init() 之后**——先让会话状态归位,首轮 tick 才看不到脏状态(见 §5.12)。随后 `wechat.init(cfg, db, bus)` 挂上总线内部订阅(微信接入,§5.13;`wxbot.url` 未配时全程静默)。
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`)。
+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` 模块内。
10. `skills.listSkills(...)` → `llm.setSkillListText(...)` 快照注入 system prompt(`llm.js`)。
11. `server.listen(PORT)`,打 startup 行:workspace_root / data_root / models / mcp_servers / auth / log_level。
@@ -203,6 +205,12 @@ channel_sessions user + channel 复合 PK / session_id / updated_at
# 文本命令接入端(routes/channel.js)的「当前会话」映射:接入端无会话列表 UI,
# 普通消息与 /new 等命令都路由到绑定的会话;无外键,删会话后懒解析自愈;
# /api/channel/send 是唯一读写方,Web 路由不碰这张表
+
+wechat_bindings id PK(wx+10hex)/ user / status (pending|online|expired|error) / note /
+ bot_account_id / wx_to_user / last_msg_id / created_at / updated_at
+ # 微信绑定权威表(§5.13):一条 core 用户 ↔ 一个 wxbot iLink bot 实例(一人一绑,换号先解绑);
+ # id 兼作 channel 键(channel='wx:'+id,复用 channel_sessions 全套机制)与 wxbot 凭证目录名;
+ # last_msg_id 是投递游标(assistant 消息 id ≤ 此值已送微信),落库防 core 重启重发
```
**session.status 状态机**(`engine.js`,无排队版):
@@ -385,6 +393,7 @@ stateDiagram-v2
- `Map>`。
- `emit(sessionId, event, data)` 拼 `event: \ndata: \n\n`;无客户端静默丢弃(消息本身已持久化,重连可回放)。
+- 进程内内部订阅 `onInternal(fn)`:先于 HTTP 客户端触发、不受「无观看者早退」影响、单个监听抛错不影响其余——微信投递(wechat.js)靠它拿 assistant_message(微信会话常常没有任何 Web 页面在看)。
- SSE 心跳:路由层 15s 一次 `: ping\n\n` 注释行(`X-Accel-Buffering: no` 是给 nginx-proxy 看的)。
### 5.11 `balance.js` —— 余额查询
@@ -407,6 +416,18 @@ AI 通过 `schedule` 工具为所在会话建周期性任务(`scheduled_tasks`
---
+### 5.13 `wechat.js` —— 微信接入桥接(wxbot 为私有组件,不入 git)
+
+背景:仓库内 `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 代理给页面 `
`,服务 token 不出内网);② wxbot 收信 → `POST core:/wxhook/inbox` → 直调 `channel.handleSend()`(命令回执同步回文本;普通消息不回执,等异步投递);③ core 总线监听 assistant_message → 分段(~1800 字/段,行优先聚合)→ `POST wxbot:/api/deliver` → `bot.send`。
+- **投递游标** `last_msg_id` 落库 + 每绑定串行队列:重启不重发旧回复,wxbot 短暂不可达不丢(下一条连带补齐);errAck/纯工具轮(空文本)不进微信,`__blocks__` 图消息降级为占位文案。
+- **降级承诺**:`wxbot.url` 未配 = 功能整体静默关闭(启动零日志噪声、设置页入口隐藏);配了但 wxbot 没起 = restore 只留一行 info,面板显示未连接,所有外呼失败只 warn,绝不阻塞/抛出未捕获异常影响 Web 主流程(鉴权/探活失败同样只降级)。
+- 鉴权:core→wxbot = wxbot 自身 auth.tokens 白名单(模板直接引用 `${WXBOT_TOKEN}`);wxbot→core = `/wxhook` 挂 auth.middleware 之前,Bearer 服务 token 哈希后定长比较(同 auth.js 形态),token 未配一律 503(fail closed)。
+
+---
+
## 6. agent-executor 容器
单文件 Node HTTP 服务(`executor/server.js`),零依赖。镜像 `executor/Dockerfile` 分两阶段:`base`(M,长期不变)与 `skills`(M' = M + 技能系统层依赖,管理员改 skills 后重建)。端点:
@@ -462,7 +483,9 @@ AI 通过 `schedule` 工具为所在会话建周期性任务(`scheduled_tasks`
| `/api/platforms` | `routes/platforms.js` | `GET /balance?pi=&ki=` 余额 |
| `/api/system` | `routes/system.js` | `GET /status` + `/restart?force=...`(原 `model_profiles` 可用名单字段已删,前端无消费方) |
| `/api/profile` | `routes/profile.js` | `GET /` 读画像、`PUT /` 保存(三字段 + enabled);按 `req.user` 隔离,逻辑全在 `user-profile.js`(快照冻结见 engine `createSession`/`clearSessionMessages`,提取见 `enterExecuting`) |
-| `/api/channel` | `routes/channel.js` | `POST /send {channel, text}` 文本命令接入端(IM/CLI 等无 UI 客户端,走 Basic/cookie 鉴权):命令仅在本入口解析(Web 消息路由不受影响,防误伤路径/代码文本);严格匹配白名单 `/new[文本] /stop /compact /clear /status /help`,未知斜杠词回提示、不像命令的当普通消息;(user,channel) 经 `channel_sessions` 表绑定当前会话(普通消息无绑定自动建);命令动作不落消息行(与 Web 按钮对称),AI 回复由接入端复用既有 SSE/详情接口获取 |
+| `/api/channel` | `routes/channel.js` | `POST /send {channel, text}` 文本命令接入端(IM/CLI 等无 UI 客户端,走 Basic/cookie 鉴权):命令仅在本入口解析(Web 消息路由不受影响,防误伤路径/代码文本);严格匹配白名单 `/new[文本] /stop /compact /clear /status /help`,未知斜杠词回提示、不像命令的当普通消息;(user,channel) 经 `channel_sessions` 表绑定当前会话(普通消息无绑定自动建);命令动作不落消息行(与 Web 按钮对称),AI 回复由接入端复用既有 SSE/详情接口获取;`handleSend()` 另供微信桥接直调 |
+| `/api/wechat` | `routes/wechat.js` | 微信绑定管理(设置页,cookie 鉴权 + req.user 隔离):`GET /`(enabled/alive/我的绑定)、`POST /`(新建绑定,一人一绑)、`GET /:id/qr`(登录二维码 SVG 代理)、`POST /:id/refresh`(重发登录)、`DELETE /:id`(解绑,销毁实例与凭证);业务全在 `wechat.js`(§5.13) |
+| `/wxhook` | `routes/wechat.js`(hookRouter) | wxbot → core 内网回调(**挂 auth.middleware 之前**,形态同 `/p`):`POST /inbox {id, from, text}` 收信转 channel 层(非 2xx 时 wxbot 把 error 文案回给微信用户);`POST /hook {id, event}` 实例状态回报;Bearer 共享服务 token(哈希后定长比较,未配一律 503) |
| `/api/models` | `server.js` | 模型池(在用会话数 slots_used / 在用会话列表,非独占展示)+ token 用量 |
| `/api/health` | `server.js` | 健康检查 |
| `/api/login` `/api/login_restore` `/api/logout` `/api/password` `/api/me` | `auth.js` | 认证路由(认证前) |
@@ -522,6 +545,7 @@ AI 通过 `schedule` 工具为所在会话建周期性任务(`scheduled_tasks`
- `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=` 可关);token 与 wxbot 侧 `.env` 同值,双向共用(出向控制 + 入向 /wxhook 回调)。
---
@@ -742,6 +766,8 @@ sequenceDiagram
15. **`pids_limit` 与 `ulimit` 区别** —— 前者是 cgroup pids 控制器算整个容器的进程+线程;后者是 per-process `RLIMIT_FSIZE` 等。被杀时 OOM kill vs SIGXFSZ 行为不同。
16. **浏览器内双凭据身份分裂** —— 前端 `req()` 曾附加 sessionStorage 里的 Basic 头兜底 cookie,但 sessionStorage 按标签页隔离、刷新后残留(新标签页不继承,复制标签页则继承),cookie 是浏览器全局:A/B 切号登录后刷新旧标签页,会出现 `/api/me`(读 cookie)是 A、会话列表(Basic 优先于 cookie)是 B 的不一致,SSE(EventSource 只能带 cookie)又跟着 A。现已统一:浏览器身份只认 cookie(`req()` 不带 Basic 头,登录页不再存明文口令),服务端 `authUser` 也是 cookie 优先;Basic 仅供 curl/脚本无 cookie 时使用。
+17. **微信功能必须静默降级** —— wxbot 是可选依赖:未配置/未启动/网络断开时,core 启动与 Web 主流程必须零报错(restore 只留日志、外呼失败只 warn、设置页自动隐藏入口);改 wechat.js 时不得引入任何会冒到主流程的同步抛错或未 catch 的 promise。
+
---
## 15. 进一步阅读