ppxans-harness 2.4.0

package/src/channels/index.js

@@ -0,0 +1,110 @@
+// src/channels/index.js - 通道管理器 (注册表, config 驱动, 可更换)
+// 每个通道 = Channel 子类 (connect/send/disconnect); 新增通道类型 → 注册进 channelTypes 即可, 不改 manager
+// 使用方: new ChannelManager(agent, config.channels) → await start()
+import { HttpChannel } from "./http.js";
+import { FeishuChannel } from "./feishu.js";
+import { WechatWebhookChannel } from "./wechat.js";
+import { LogChannel } from "./log.js";
+
+// 内置通道类型注册表: name -> 通道类 (构造函数签名: (agent, configObj))
+export const BUILTIN_CHANNEL_TYPES = {
+  http: HttpChannel,
+  feishu: FeishuChannel,
+  wechat: WechatWebhookChannel,
+  log: LogChannel,
+};
+
+// 启停策略: http 默认开, 其余默认关 (config.channels.<name>.enabled)
+function isEnabled(name, cfg) {
+  if (name === "http") return cfg.enabled !== false;
+  return !!cfg.enabled;
+}
+
+export class ChannelManager {
+  constructor(agent, config = {}, channelTypes = null) {
+    this.agent = agent;
+    this.config = config || {};              // config.channels
+    this.channelTypes = channelTypes || BUILTIN_CHANNEL_TYPES; // 可注入自定义类型 (更换通道实现)
+    this.channels = [];
+    this.httpServer = null;
+  }
+
+  // 按注册表顺序启动所有启用的通道 (单个失败不影响其他)
+  // 流程: 全部 connect → 若 HTTP 通道在跑, 给 webhook 型通道挂载路由
+  async start() {
+    const started = [];
+    for (const [name, Ctor] of Object.entries(this.channelTypes)) {
+      const cfg = { ...(this.config[name] || {}) };
+      if (!isEnabled(name, cfg)) continue;
+      try {
+        const ch = new Ctor(this.agent, cfg);
+        await ch.connect();
+        this.channels.push(ch);
+        if (ch.server) this.httpServer = ch.server;
+        started.push(name);
+      } catch (e) {
+        console.warn(`[channels] ${name} 通道启动失败: ${e.message}`);
+      }
+    }
+    // webhook 型通道挂到 HTTP server (若已启动); 传 http 通道实例供 registerWebhook 路由分发
+    if (this.httpServer) {
+      const httpCh = this.get("http") || null;
+      for (const ch of this.channels) {
+        if (ch.name !== "http" && typeof ch.mount === "function") {
+          try { ch.mount(this.httpServer, httpCh); } catch (e) { console.warn(`[channels] ${ch.name} webhook 挂载失败: ${e.message}`); }
+        }
+      }
+    }
+    return started;
+  }
+
+  // 按 name 取已启动通道 (无则 null)
+  get(name) {
+    return this.channels.find((c) => c.name === name) || null;
+  }
+
+  // 列出所有可配置通道的状态 (含未启用的), 供 CLI/UI 展示
+  list() {
+    return Object.entries(this.channelTypes).map(([name, Ctor]) => {
+      const cfg = this.config[name] || {};
+      return { name, enabled: isEnabled(name, cfg), connected: !!this.get(name) };
+    });
+  }
+
+  // 连通性测试: 用独立实例验证某通道配置 (不干扰已启动的通道)
+  async test(name) {
+    const Ctor = this.channelTypes[name];
+    if (!Ctor) return { ok: false, detail: `未知通道类型: ${name}` };
+    const cfg = { ...(this.config[name] || {}) };
+    try {
+      const ch = new Ctor(this.agent, cfg);
+      const r = typeof ch.test === "function" ? await ch.test() : await ch.connect();
+      return typeof r === "object" && r !== null ? r : { ok: true, detail: String(r) };
+    } catch (e) {
+      return { ok: false, detail: e.message };
+    }
+  }
+
+  // 广播到所有已启动通道 (主动提醒/系统消息投递入口)
+  async broadcast(text, { to = "*" } = {}) {
+    const out = [];
+    for (const c of this.channels) {
+      try { out.push(await c.send(to, text)); } catch (e) { console.warn(`[channels] ${c.name} 发送失败: ${e.message}`); }
+    }
+    return out;
+  }
+
+  async stop() {
+    for (const c of this.channels) {
+      try { await c.disconnect?.(); } catch {}
+    }
+    this.channels = [];
+    this.httpServer = null;
+  }
+}
+
+export { Channel } from "./base.js";
+export { HttpChannel } from "./http.js";
+export { FeishuChannel } from "./feishu.js";
+export { WechatWebhookChannel } from "./wechat.js";
+export { LogChannel } from "./log.js";

package/src/channels/log.js

@@ -0,0 +1,29 @@
+// src/channels/log.js - 日志通道 (dummy): 无网络依赖, 把消息打印到 stdout
+// 用途: 主动提醒/消息先落到本地日志验证契约, 再接真实通道 (webhook/IM) 时只需"换一个 adapter"
+import { Channel } from "./base.js";
+
+export class LogChannel extends Channel {
+  constructor(agent, { target = "console" } = {}) {
+    super("log", agent);
+    this.target = target; // 预留: "console" | 未来文件/远程日志
+  }
+
+  async connect() {
+    this.connected = true;
+    return this;
+  }
+
+  async send(to, text) {
+    const prefix = to && to !== "*" ? `[log:${to}]` : "[log]";
+    console.log(`${prefix} ${String(text)}`);
+    return text;
+  }
+
+  async test() {
+    return { ok: true, detail: "日志通道无需网络, 总是可用" };
+  }
+
+  async disconnect() {
+    this.connected = false;
+  }
+}

package/src/channels/wechat-crypto.js

@@ -0,0 +1,74 @@
+// src/channels/wechat-crypto.js - 微信消息加解密 (企业微信/公众号) 零依赖
+// 参考官方 WXBizMsgCrypt: AES-256-CBC + PKCS7 填充 + SHA1 签名校验
+// 用 Node 原生 crypto, 无任何 npm 依赖。真实联调需企微/公众号凭据 (token + encodingAESKey)。
+import crypto from "node:crypto";
+
+// 43 字符 encodingAESKey → 32 字节 AES key (base64, 补 '=' 凑满 32 字节)
+function keyOf(encodingAESKey) {
+  return Buffer.from(String(encodingAESKey) + "=", "base64");
+}
+
+// SHA1 签名校验: sort([token, timestamp, nonce, encrypt]).join("") 的 sha1 与 signature 比对
+export function verifySignature(token, timestamp, nonce, encrypt, signature) {
+  const arr = [String(token), String(timestamp), String(nonce), String(encrypt)].sort();
+  const sha1 = crypto.createHash("sha1").update(arr.join(""), "utf8").digest("hex");
+  return sha1 === String(signature);
+}
+
+// 生成签名 (加密回包时用, 与 verifySignature 同一算法)
+export function generateSignature(token, timestamp, nonce, encrypt) {
+  const arr = [String(token), String(timestamp), String(nonce), String(encrypt)].sort();
+  return crypto.createHash("sha1").update(arr.join(""), "utf8").digest("hex");
+}
+
+// 解密 <Encrypt> → { msg, receiveId } (receiveId 通常为 corpId)
+export function decryptMsg(encodingAESKey, encryptedXml) {
+  const m = String(encryptedXml).match(/<Encrypt><!\[CDATA\[([\s\S]*?)\]\]><\/Encrypt>/);
+  const enc = m ? m[1] : "";
+  if (!enc) throw new Error("消息体无 <Encrypt>");
+  const key = keyOf(encodingAESKey);
+  const iv = key.slice(0, 16);
+  const decipher = crypto.createDecipheriv("aes-256-cbc", key, iv);
+  decipher.setAutoPadding(false);
+  const dec = Buffer.concat([decipher.update(enc, "base64"), decipher.final()]);
+  // PKCS7 去填充
+  const pad = dec[dec.length - 1];
+  const plain = dec.slice(0, dec.length - pad);
+  // 明文格式: random(16) + msgLen(4, 大端) + msg + receiveId
+  const msgLen = plain.readUInt32BE(16);
+  const msg = plain.slice(20, 20 + msgLen).toString("utf8");
+  const receiveId = plain.slice(20 + msgLen).toString("utf8");
+  return { msg, receiveId };
+}
+
+// 加密回复 → 返回 <Encrypt> 里的 base64 密文 (供拼回复 XML)
+export function encryptMsg(encodingAESKey, msg, receiveId = "") {
+  const key = keyOf(encodingAESKey);
+  const iv = key.slice(0, 16);
+  const msgBuf = Buffer.from(String(msg), "utf8");
+  const idBuf = Buffer.from(String(receiveId), "utf8");
+  const lenBuf = Buffer.alloc(4);
+  lenBuf.writeUInt32BE(msgBuf.length, 0);
+  const plain = Buffer.concat([crypto.randomBytes(16), lenBuf, msgBuf, idBuf]);
+  // PKCS7 填充到 32 字节倍数
+  const padLen = 32 - (plain.length % 32);
+  const padded = Buffer.concat([plain, Buffer.alloc(padLen, padLen)]);
+  const cipher = crypto.createCipheriv("aes-256-cbc", key, iv);
+  cipher.setAutoPadding(false);
+  return Buffer.concat([cipher.update(padded), cipher.final()]).toString("base64");
+}
+
+// 加密被动回复: 生成企业微信加密模式回包 XML (含 MsgSignature/TimeStamp/Nonce)
+// replyXml = 明文回复 XML, receiveId = corpId (解密时拿到的)
+export function encryptReplyXml({ encodingAESKey, token, replyXml, receiveId = "", timestamp = null, nonce = null }) {
+  const enc = encryptMsg(encodingAESKey, replyXml, receiveId);
+  const ts = String(timestamp ?? Math.floor(Date.now() / 1000));
+  const nc = nonce ?? Math.random().toString(36).slice(2, 12);
+  const sig = generateSignature(token, ts, nc, enc);
+  return `<xml>
+  <Encrypt><![CDATA[${enc}]]></Encrypt>
+  <MsgSignature><![CDATA[${sig}]]></MsgSignature>
+  <TimeStamp>${ts}</TimeStamp>
+  <Nonce><![CDATA[${nc}]]></Nonce>
+</xml>`;
+}

package/src/channels/wechat.js

@@ -0,0 +1,197 @@
+// src/channels/wechat.js - 微信通道适配器 (企业微信/公众号 webhook)
+// 已实现:
+//   - 加密消息解密 (AES-256-CBC) + 验签 (wechat-crypto.js)
+//   - 明文/加密模式被动回复 (加密模式回包 encryptReplyXml)
+//   - 主动推送 send(): 企业微信应用消息 API (corp_id + corp_secret + agent_id)
+// 凭据: 接收回调用 token + encodingAESKey; 主动推送用 corp_id + corp_secret + agent_id
+//   (config.channels.wechat 或环境变量 WECHAT_*)
+import { Channel } from "./base.js";
+import { decryptMsg, verifySignature, encryptReplyXml } from "./wechat-crypto.js";
+
+export class WechatWebhookChannel extends Channel {
+  constructor(agent, {
+    path = "/wechat/webhook",
+    token = "",
+    encodingAESKey = "",
+    corpId = "",
+    corpSecret = "",
+    agentId = "",
+  } = {}) {
+    super("wechat", agent);
+    this.path = path;
+    this.token = token || process.env.WECHAT_WEBHOOK_TOKEN || "";
+    this.encodingAESKey = encodingAESKey || process.env.WECHAT_ENCODING_AES_KEY || "";
+    // 主动推送凭据 (企业微信应用消息)
+    this.corpId = corpId || process.env.WECHAT_CORP_ID || "";
+    this.corpSecret = corpSecret || process.env.WECHAT_CORP_SECRET || "";
+    this.agentId = agentId || process.env.WECHAT_AGENT_ID || "";
+    this.accessToken = null;
+    this.tokenExpire = 0;
+    this.lastUser = null; // 最近收到消息的用户 ID, 供主动提醒(广播)回发
+  }
+
+  async connect() {
+    this.connected = true;
+    return this;
+  }
+
+  // 连通性测试: 配置了主动推送凭据则验证 access_token; 仅回调模式返回提示
+  async test() {
+    if (!this.corpId || !this.corpSecret) {
+      return { ok: true, detail: "回调模式配置完整 (回调无法离线探测, 需公网/平台侧验证); 未配置主动推送凭据 (corp_id/corp_secret/agent_id)" };
+    }
+    try {
+      const token = await this._getAccessToken();
+      return { ok: true, detail: `企业微信推送通道通 (access_token 获取成功, ${String(token).slice(0, 6)}...)` };
+    } catch (e) {
+      return { ok: false, detail: e.message };
+    }
+  }
+
+  // 把 /wechat/webhook 挂到 HTTP server (webhook 型通道, 支持明文/加密回包 + GET echostr URL 验证)
+  // v1.0.8: 注册到 HttpChannel 的 webhook 路由 (单一 request handler 分发); 支持 GET echostr
+  mount(server, httpChannel = null) {
+    const register = httpChannel && typeof httpChannel.registerWebhook === "function"
+      ? (path, fn) => httpChannel.registerWebhook(path, fn)
+      : (path, fn) => { server && server.on?.("request", fn); };
+    register(this.path, async (req, res) => {
+      const u = new URL(req.url || "/", "http://localhost");
+      let body = "";
+      if (req.method === "POST") {
+        for await (const c of req) body += c;
+      }
+      const query = {
+        msg_signature: u.searchParams.get("msg_signature") || "",
+        timestamp: u.searchParams.get("timestamp") || "",
+        nonce: u.searchParams.get("nonce") || "",
+        echostr: u.searchParams.get("echostr") || "",
+      };
+      try {
+        const out = await this.handleWebhook(body, query);
+        if (out.xml) { res.writeHead(200, { "Content-Type": "text/xml" }); res.end(out.xml); }
+        else if (typeof out === "string") { res.writeHead(200, { "Content-Type": "text/plain" }); res.end(out); } // echostr 明文回显 (企业微信 URL 验证要求)
+        else { res.writeHead(200, { "Content-Type": "application/json" }); res.end(JSON.stringify(out)); }
+      } catch (e) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: e.message }));
+      }
+    });
+  }
+
+  // 企业微信回调: URL query 带 msg_signature/timestamp/nonce; body 为 XML
+  // 加密模式: 外层 XML 含 <Encrypt>, 解密得内层明文消息
+  // v1.0.8 安全加固: 配置了 token 时所有模式都必须验签 (明文/加密/echostr), 防伪造消息驱动 agent
+  async handleWebhook(body, query = {}) {
+    const raw = typeof body === "string" ? body : JSON.stringify(body);
+    const { msg_signature, timestamp, nonce } = query;
+
+    // URL 验证 (GET echostr, 明文模式验签后直接回显)
+    if (query.echostr) {
+      if (this.token) {
+        if (!msg_signature) return { error: "缺少 msg_signature" };
+        const ok = verifySignature(this.token, timestamp || "", nonce || "", query.echostr, msg_signature);
+        if (!ok) return { error: "签名校验失败" };
+      }
+      return query.echostr;
+    }
+
+    // 加密消息: 验签 + 解密 + 加密回包
+    if (/<Encrypt>/.test(raw)) {
+      const enc = (raw.match(/<Encrypt><!\[CDATA\[([\s\S]*?)\]\]><\/Encrypt>/) || [])[1] || "";
+      // 配置了 token 就必须验签 (防无 token 时跳过)
+      if (this.token) {
+        if (!msg_signature) return { error: "缺少 msg_signature" };
+        const ok = verifySignature(this.token, timestamp || "", nonce || "", enc, msg_signature);
+        if (!ok) return { error: "签名校验失败" };
+      }
+      if (!this.encodingAESKey) return { error: "未配置 encodingAESKey, 无法解密" };
+      const { msg, receiveId } = decryptMsg(this.encodingAESKey, raw);
+      const reply = await this._replyFromXml(msg);
+      // 加密模式: 把明文回复 XML 加密成回包 (含签名/时间戳/随机数)
+      if (reply.xml) {
+        return { xml: encryptReplyXml({
+          encodingAESKey: this.encodingAESKey,
+          token: this.token,
+          replyXml: reply.xml,
+          receiveId,
+          timestamp: timestamp || null,
+          nonce: nonce || null,
+        }) };
+      }
+      return reply;
+    }
+
+    // 明文 XML 模式: 配置了 token 就必须验签 (防伪造消息)
+    if (/<Content>/.test(raw)) {
+      if (this.token) {
+        if (!msg_signature) return { error: "缺少 msg_signature" };
+        const ok = verifySignature(this.token, timestamp || "", nonce || "", raw, msg_signature);
+        if (!ok) return { error: "签名校验失败" };
+      }
+      return this._replyFromXml(raw);
+    }
+
+    return { error: "未识别的微信消息" };
+  }
+
+  // 从明文 XML 提取文本并生成被动回复
+  async _replyFromXml(xml) {
+    const g = (tag) => ((String(xml).match(new RegExp(`<${tag}><!\\[CDATA\\[([\\s\\S]*?)\\]\\]></${tag}>`)) || [])[1] || "").trim();
+    const text = g("Content");
+    if (!text) return { error: "无文本内容" };
+    const reply = await this.agent.chat(text);
+    const toUser = g("FromUserName");
+    if (toUser) this.lastUser = toUser; // 记录最近联系人, 供主动提醒回发
+    const fromUser = g("ToUserName");
+    return {
+      xml: `<xml>
+  <ToUserName><![CDATA[${toUser}]]></ToUserName>
+  <FromUserName><![CDATA[${fromUser}]]></FromUserName>
+  <CreateTime>${Math.floor(Date.now() / 1000)}</CreateTime>
+  <MsgType><![CDATA[text]]></MsgType>
+  <Content><![CDATA[${reply}]]></Content>
+</xml>`,
+    };
+  }
+
+  // 获取企业微信 access_token (主动推送用), 带缓存
+  async _getAccessToken() {
+    if (this.accessToken && Date.now() < this.tokenExpire) return this.accessToken;
+    if (!this.corpId || !this.corpSecret) {
+      throw new Error("微信主动推送未配置: 需 corp_id + corp_secret (config.channels.wechat 或环境变量 WECHAT_CORP_ID/WECHAT_CORP_SECRET)");
+    }
+    const r = await fetch(
+      `https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=${encodeURIComponent(this.corpId)}&corpsecret=${encodeURIComponent(this.corpSecret)}`,
+      { signal: AbortSignal.timeout(15000) },
+    );
+    const data = await r.json();
+    if (data.errcode !== 0) throw new Error(`微信 access_token 失败: ${data.errmsg} (errcode=${data.errcode})`);
+    this.accessToken = data.access_token;
+    this.tokenExpire = Date.now() + (data.expires_in - 60) * 1000;
+    return this.accessToken;
+  }
+
+  // 主动推送 (企业微信应用消息): 需 corp_id + corp_secret + agent_id; to="*" 时回最近联系人
+  async send(to, text) {
+    const token = await this._getAccessToken();
+    if (!this.agentId) {
+      throw new Error("微信主动推送未配置 agent_id (config.channels.wechat.agent_id 或环境变量 WECHAT_AGENT_ID)");
+    }
+    const target = !to || to === "*" ? this.lastUser : to;
+    if (!target) throw new Error("微信主动推送缺接收人: 先收到过一条用户消息记录用户 ID, 或用 send(userId, ...)");
+    const r = await fetch(`https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=${encodeURIComponent(token)}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        touser: String(target),
+        msgtype: "text",
+        agentid: Number(this.agentId),
+        text: { content: String(text) },
+      }),
+      signal: AbortSignal.timeout(15000),
+    });
+    const data = await r.json();
+    if (data.errcode !== 0) throw new Error(`微信发送失败: ${data.errmsg} (errcode=${data.errcode})`);
+    return data;
+  }
+}

package/src/channels-cli.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// src/channels-cli.js - `ppx channels` 通道管理 CLI (借鉴 openclaw `channels add`)
+// 让用户自己连通道: 交互式配置 → 写 config/ppx.json → 测试连通性 → 重启服务生效
+//
+// 用法:
+//   ppx-channels list                    列出全部通道 + 启用状态
+//   ppx-channels add <name>              交互式配置通道 (默认写盘并启用)
+//   ppx-channels test <name>             测试连通性 (网络探测)
+//   ppx-channels enable|disable <name>   启用/禁用
+//   ppx-channels remove <name>           移除配置 (恢复默认)
+//   ppx-channels --root <dir> ...        指定项目根目录 (默认当前目录)
+import { ensureUTF8Console } from "./utils/winutf8.js";
+import path from "node:path";
+import readline from "node:readline/promises";
+import {
+ensureUTF8Console();
+  CHANNEL_SCHEMAS, readChannels, listChannels,
+  updateChannel, setChannelEnabled, removeChannel,
+} from "./config/channels.js";
+import { ChannelManager } from "./channels/index.js";
+
+const args = process.argv.slice(2);
+let root = process.cwd();
+if (args[0] === "--root") { root = path.resolve(args[1]); args.splice(0, 2); }
+const [cmd, name] = args;
+
+const HELP = `ppx-channels - 皮皮虾通道管理 (让用户自己连)
+用法:
+  ppx-channels list                   列出全部通道 + 启用状态
+  ppx-channels add <name>             交互式配置通道
+  ppx-channels test <name>            测试连通性
+  ppx-channels enable <name>          启用通道
+  ppx-channels disable <name>         禁用通道
+  ppx-channels remove <name>          移除配置 (恢复默认)
+  ppx-channels --root <dir> <cmd>     指定项目根目录
+可用通道: ${Object.keys(CHANNEL_SCHEMAS).join(" / ")}`;
+
+// ---- list ----
+function doList() {
+  const rows = listChannels(root);
+  for (const r of rows) {
+    const marks = Object.entries(r.fields)
+      .map(([k, v]) => (k.endsWith("_set") ? `${k}=✓` : `${k}=${v}`))
+      .join(" ");
+    console.log(`${r.enabled ? "✓ 启用" : "· 禁用"}  ${r.name}${marks ? "   " + marks : ""}`);
+  }
+  const enabled = rows.filter((r) => r.enabled).map((r) => r.name);
+  console.log(`\n${enabled.length ? "已启用: " + enabled.join(", ") : "全部未启用 — 用 add <name> 配置一个"}`);
+}
+
+// ---- add (交互式引导, 借鉴 openclaw channels add) ----
+async function doAdd(name) {
+  const schema = CHANNEL_SCHEMAS[name];
+  if (!schema) {
+    console.error(`未知通道: ${name} (可用: ${Object.keys(CHANNEL_SCHEMAS).join(", ")})`);
+    process.exit(1);
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const existing = readChannels(root).channels[name] || {};
+  const patch = {};
+  console.log(`\n配置 ${name} 通道 (回车用默认值, 需要密码的字段直接粘贴):`);
+  for (const key of Object.keys(schema).filter((k) => k !== "enabled")) {
+    const f = schema[key];
+    const def = existing[key] ?? f.def ?? "";
+    const defHint = def !== "" ? ` [${def}]` : "";
+    const prompt = f.prompt ? `  ${f.label} — ${f.prompt}${defHint}: ` : `  ${f.label}${defHint}: `;
+    const ans = (await rl.question(prompt)).trim();
+    const val = ans === "" ? def : ans;
+    if (val !== "") patch[key] = f.type === "number" ? Number(val) : val;
+  }
+  rl.close();
+  try {
+    updateChannel(root, name, { ...patch, enabled: true });
+    console.log(`\n✓ ${name} 已配置并启用 (config/ppx.json 已原子写盘, 原文件已备份).`);
+    console.log(`  重启服务生效: ppx-serve`);
+    console.log(`  验证连通性: ppx-channels test ${name}`);
+  } catch (e) {
+    console.error(`✗ 保存失败: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+// ---- test (连通性) ----
+async function doTest(name) {
+  if (!(name in CHANNEL_SCHEMAS)) {
+    console.error(`未知通道: ${name} (可用: ${Object.keys(CHANNEL_SCHEMAS).join(", ")})`);
+    process.exit(1);
+  }
+  const { channels } = readChannels(root);
+  // 轻量 agent stub: 通道 test() 只用 root 构造, 不触发完整 agent 启动
+  const mgr = new ChannelManager({ root, config: { agent: {} } }, channels);
+  const r = await mgr.test(name);
+  console.log(`${r.ok ? "✓" : "✗"} ${name}: ${r.detail}`);
+  process.exit(r.ok ? 0 : 1);
+}
+
+// ---- enable/disable/remove ----
+function doToggle(name, enabled) {
+  if (!(name in CHANNEL_SCHEMAS)) { console.error(`未知通道: ${name}`); process.exit(1); }
+  try {
+    const out = setChannelEnabled(root, name, enabled);
+    console.log(`✓ ${name} 已${enabled ? "启用" : "禁用"}${Object.keys(out).length ? ` (${Object.keys(out).join(", ")})` : ""}`);
+  } catch (e) { console.error(`✗ 操作失败: ${e.message}`); process.exit(1); }
+}
+
+function doRemove(name) {
+  if (!(name in CHANNEL_SCHEMAS)) { console.error(`未知通道: ${name}`); process.exit(1); }
+  const ok = removeChannel(root, name);
+  console.log(ok ? `✓ ${name} 配置已移除 (恢复默认, 默认禁用)` : `${name} 本来就没有自定义配置`);
+}
+
+// ---- main ----
+(async () => {
+  if (!cmd || cmd === "-h" || cmd === "--help") { console.log(HELP); return; }
+  switch (cmd) {
+    case "list": doList(); break;
+    case "add": await doAdd(name); break;
+    case "test": await doTest(name); break;
+    case "enable": doToggle(name, true); break;
+    case "disable": doToggle(name, false); break;
+    case "remove": doRemove(name); break;
+    default: console.error(`未知命令: ${cmd}\n${HELP}`); process.exit(1);
+  }
+})();

package/src/cli.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// src/cli.js - 皮皮虾 CLI 交互入口 (readline 历史 + interrupt 中断)
+import { ensureUTF8Console } from "./utils/winutf8.js";
+import path from "node:path";
+import readline from "node:readline";
+import { fileURLToPath } from "node:url";
+import { PPXAgent } from "./agent/index.js";
+import { suggestProactive } from "./ans/proactive.js";
+
+ensureUTF8Console();
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+const agent = new PPXAgent({ root: ROOT });
+
+console.log("======================================");
+console.log("  皮皮虾 (PPX) - 自我修复·自我学习 Agent");
+console.log(`  记忆:${agent.facts.count()}条 | 经验:${agent.experience.lessons.length}条`);
+console.log(`  模型: ${agent.llm ? "已配置" : "未配置(离线记忆模式)"}`);
+console.log("  命令: quit/exit 退出 | /stop 中断当前任务 | /reset 清空会话");
+console.log("        /proactive 主动提醒(扫描记忆待办) | /proactive-done <id> 标记待办完成 | ↑↓ 浏览历史 | Ctrl+C 中断(再按一次退出)");
+console.log("======================================");
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+  prompt: "皮皮虾> ",
+  terminal: true,
+});
+
+let busy = false; // 防止任务执行中重复输入
+
+// 主动任务生成定时器 (ANS 自主性): config.agent.proactive.enabled 时启动
+// 有待办信号才推送 (suggestProactive 无信号返回 null 不打扰), 输出到 stdout
+if (agent.config.agent?.proactive?.enabled) {
+  agent.startProactiveTicker((payload) => {
+    console.log("\n[主动提醒] " + payload.text);
+    rl.prompt();
+  });
+  console.log(`  (主动提醒已开启: 每 ${Math.round(agent.config.agent.proactive.interval_ms / 60000)} 分钟扫描记忆待办)`);
+}
+
+rl.on("line", async (line) => {
+  const text = line.trim();
+  if (!text) return rl.prompt();
+  if (busy) return rl.prompt(); // 上一轮任务未结束, 忽略输入 (可用 /stop 或 Ctrl+C 打断)
+
+  // 退出
+  if (["quit", "exit", "q"].includes(text.toLowerCase())) {
+    agent.shutdown();
+    console.log("皮皮虾 收工, 已保存记忆。");
+    process.exit(0);
+  }
+  // 中断当前任务 (Human-in-the-loop)
+  if (text === "/stop") {
+    agent.interrupt();
+    console.log("(已发送中断信号, 当前任务将尽快停下)");
+    return rl.prompt();
+  }
+  // 清空会话
+  if (text === "/reset") {
+    agent.resetSession("default");
+    console.log("(会话已清空)");
+    return rl.prompt();
+  }
+  // 主动任务生成: 扫描记忆里的待办/偏好, 给出主动提醒 (ANS 自主性)
+  // 输出含 id, 可用 /proactive-done <id> 标记完成 (窗口去重, 24h 内不重复提醒)
+  if (text === "/proactive") {
+    busy = true;
+    try {
+      const out = await suggestProactive(agent);
+      if (out) {
+        console.log("\n" + out.text + "\n");
+        for (const it of out.items) console.log(`  [${it.id}] ${it.content}`);
+        console.log("\n(用 /proactive-done <id> 标记完成, 之后不再提醒)\n");
+      } else {
+        console.log("\n(暂时没有需要提醒的事项)\n");
+      }
+    } catch (e) {
+      console.log("\n[错误] " + e.message + "\n");
+    } finally {
+      busy = false;
+    }
+    return rl.prompt();
+  }
+  // 标记待办完成: /proactive-done <factId>
+  if (text.startsWith("/proactive-done")) {
+    const id = text.replace("/proactive-done", "").trim();
+    const ok = agent.proactiveMarkDone(id);
+    console.log(ok ? "(已标记完成, 之后不再提醒)" : "(待办不存在: " + id + ")");
+    return rl.prompt();
+  }
+
+  busy = true;
+  try {
+    const r = await agent.chat(text);
+    console.log("\n" + r + "\n");
+  } catch (e) {
+    console.log("\n[错误] " + e.message + "\n");
+  } finally {
+    busy = false;
+  }
+  rl.prompt();
+});
+
+// Ctrl+C: 第一次中断任务, 第二次退出
+let ctrlC = 0;
+rl.on("SIGINT", () => {
+  ctrlC += 1;
+  if (ctrlC >= 2) {
+    agent.shutdown();
+    console.log("\n皮皮虾 收工。");
+    process.exit(0);
+  }
+  agent.interrupt();
+  console.log("\n(已中断, 再按一次 Ctrl+C 退出)");
+  rl.prompt();
+  // 重置计数 (若任务继续则允许再次单次中断)
+  setTimeout(() => { ctrlC = 0; }, 1000);
+});
+
+rl.prompt();