ppxans-harness 2.4.0 → 3.2.0

package/src/channels/http.js

@@ -1,592 +1,1090 @@
-// src/channels/http.js - HTTP 通道 (零依赖)
-// 起一个本地 HTTP server, 接收 POST /message 消息, 调 agent 回复
-import http from "node:http";
-import fs from "node:fs";
-import path from "node:path";
-import crypto from "node:crypto";
-import { Channel } from "./base.js";
-import {
-  listProviders, addProvider, updateProvider, removeProvider, reorderProviders,
-} from "../config/providers.js";
-import { getSettings, updateSettings } from "../config/settings.js";
-import { suggestProactive } from "../ans/proactive.js";
-import { ensureDir, atomicWrite, readText } from "../utils/store.js";
-
-const MAX_BODY = 1024 * 1024;          // 请求体上限 1MB
-const RATE_PER_MIN = 60;               // 每 IP 每分钟最大请求数 (令牌桶)
-const RATE_WINDOW_MS = 60_000;
-const MAX_INFLIGHT = 4;                // 同时处理的最大对话请求数 (超出立即 429, 防单 agent 被并发压垮)
-
-// HTTP 鉴权 token 解析 / 生成 (v1.0.9 起持久化, 重启复用, 免去 Web 前端每次重贴 token)
-// 优先级: 1) 显式配置 (env/ppx.json 的 channels.http.auth_token) > 2) 数据目录持久化文件复用 > 3) 新生成并原子落盘
-// @param {object} opts
-// @param {string}       opts.configured    显式配置的 token (PPX_AUTH_TOKEN 或 config 里的 auth_token; 空串视为未配置)
-// @param {string|null}  opts.persistedFile 自动生成 token 的持久化文件路径 (无则仅返回生成, 不落盘)
-// @returns {{ token:string, source:"configured"|"persisted"|"generated", generated:boolean }}
-// 纯函数, 便于单测: 不依赖 agent/实例状态, 全部副作用 (读/写文件) 走参数传入的路径
-export function resolveAuthToken({ configured = "", persistedFile = null } = {}) {
-  const explicit = String(configured || "").trim();
-  // 优先级 1: 显式配置 (env/config) — 以身作则, 不读写持久化文件
-  if (explicit) return { token: explicit, source: "configured", generated: false };
-
-  // 优先级 2: 复用持久化文件里的旧 token (非空)
-  if (persistedFile) {
-    const old = String(readText(persistedFile, "") || "").trim();
-    if (old) return { token: old, source: "persisted", generated: false };
-  }
-
-  // 优先级 3: 新生成随机 token; 若有持久化路径则原子落盘 (写 .tmp 再 rename, 全程目录存在)
-  const token = crypto.randomBytes(24).toString("hex");
-  if (persistedFile) {
-    try {
-      ensureDir(path.dirname(persistedFile));
-      atomicWrite(persistedFile, token); // .tmp + rename: 原子替换, 并发/崩溃不损坏
-    } catch {
-      // token 已生成但在内存可用; 落盘失败仅丢失"跨重启复用", 不阻断启动
-    }
-  }
-  return { token, source: "generated", generated: true };
-}
-
-export class HttpChannel extends Channel {
-  constructor(agent, { port = 8899, host = "127.0.0.1" } = {}) {
-    super("http", agent);
-    this.port = port;
-    this.host = host;
-    this.server = null;
-    this.agent = agent;
-    this.publicDir = path.join(this.agent.root, "public");
-    // v1.0.9: token 解析延迟到 connect() 的 _ensureToken, 以便持久化文件与 agent.dataDir 就绪
-    // 这里只缓存显式配置 (env/config), 交给 _ensureToken 走"显式 > 持久化 > 新生成"的优先级
-    this.authToken = process.env.PPX_AUTH_TOKEN || this._tokenFromConfig();
-    this._persistedTokenFile = agent.dataDir ? path.join(agent.dataDir, "http-token") : null;
-    this._buckets = new Map(); // ip -> {tokens, last}
-    // v1.0.8: webhook 路由注册表 (feishu/wechat 通道挂载), 单一 request handler 分发, 无多 listener 竞态
-    this.webhookRoutes = new Map(); // path -> async (req, res) => void
-    // CORS 来源白名单 (v1.0.7): channels.http.cors_origin 数组; 未配置默认 * (向后兼容)
-    // 配置后仅放行白名单 origin, 其余跨域请求 403 (token 泄露时降低任意跨站读取风险)
-    this.corsOrigins = this._corsFromConfig();
-    this._inFlight = 0; // 当前处理中的对话请求数
-  }
-
-  // 简单并发护栏: 用计数信号量限制同时处理的对话请求, 超出立即 429
-  // 防止多个慢请求无限叠加占用单线程主 agent (可选的背压层, 区别于每 IP 令牌桶限流)
-  _acquire(res) {
-    if (this._inFlight >= MAX_INFLIGHT) {
-      res.writeHead(429, { "Content-Type": "application/json", "Retry-After": "5" });
-      res.end(JSON.stringify({ error: "too many concurrent requests, retry shortly" }));
-      return false;
-    }
-    this._inFlight += 1;
-    return true;
-  }
-  _release() { if (this._inFlight > 0) this._inFlight -= 1; }
-
-  // v1.0.8: webhook 通道注册路由 (路径匹配即由该通道处理, 不经过主逻辑)
-  registerWebhook(path, handler) {
-    if (typeof handler === "function") this.webhookRoutes.set(path, handler);
-    return () => this.webhookRoutes.delete(path);
-  }
-
-  _corsFromConfig() {
-    try {
-      const c = this.agent?.config?.channels?.http?.cors_origin;
-      if (c === undefined || c === null || c === "*") return [];
-      if (Array.isArray(c)) return c.filter(Boolean);
-      if (typeof c === "string") return [c];
-    } catch { /* 配置异常回退默认 */ }
-    return [];
-  }
-
-  _tokenFromConfig() {
-    try {
-      const p = path.join(this.agent.root, "config", "ppx.json");
-      if (fs.existsSync(p)) {
-        const cfg = JSON.parse(fs.readFileSync(p, "utf8"));
-        return (cfg.channels && cfg.channels.http && cfg.channels.http.auth_token) || "";
-      }
-    } catch {}
-    return "";
-  }
-
-  // 若未配置 token: 复用持久化文件(重启不变)或自动生成并原子落盘 (类似 Jupyter token)
-  _ensureToken() {
-    if (this.authToken) return this.authToken;
-    const r = resolveAuthToken({ configured: process.env.PPX_AUTH_TOKEN || "", persistedFile: this._persistedTokenFile });
-    this.authToken = r.token;
-    if (r.source === "persisted") {
-      console.log("  ℹ  HTTP 认证 token 复用自持久化文件 (重启不更换, 前端无需重贴)");
-    } else {
-      console.log("");
-      console.log("  ⚠️  HTTP 认证 token 未配置, 已自动生成并持久化 (重启复用):");
-      console.log(`       PPX_AUTH_TOKEN=${this.authToken}`);
-      console.log(`     用法: Authorization: Bearer ${this.authToken}`);
-      console.log(`     token 已保存到 ${this._persistedTokenFile}, 重启不再更换`);
-      console.log("      (或设置 config/ppx.json 的 channels.http.auth_token)");
-      console.log("");
-    }
-    return this.authToken;
-  }
-
-  _authed(req, res) {
-    if (!this.authToken) return true; // 兼容旧调用: _ensureToken 在 connect 时已执行
-    const h = req.headers["authorization"] || "";
-    return h === "Bearer " + this.authToken;
-  }
-
-  // 简单令牌桶限流: 每 IP 60 req/min
-  _rateLimit(req, res) {
-    const ip = req.socket?.remoteAddress || "unknown";
-    const now = Date.now();
-    let b = this._buckets.get(ip);
-    if (!b) {
-      b = { tokens: RATE_PER_MIN, last: now };
-      this._buckets.set(ip, b);
-    }
-    const refill = Math.floor((now - b.last) / RATE_WINDOW_MS);
-    if (refill > 0) {
-      b.tokens = Math.min(RATE_PER_MIN, b.tokens + refill * RATE_PER_MIN);
-      b.last = now;
-    }
-    if (b.tokens <= 0) {
-      res.writeHead(429, { "Content-Type": "application/json", "Retry-After": "60" });
-      res.end(JSON.stringify({ error: "rate limited" }));
-      return false;
-    }
-    b.tokens -= 1;
-    return true;
-  }
-
-  // 读取请求体, 限制大小
-  async _readBody(req, res) {
-    let body = "";
-    for await (const chunk of req) {
-      body += chunk;
-      if (body.length > MAX_BODY) {
-        res.writeHead(413, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "request too large" }));
-        return null;
-      }
-    }
-    return body;
-  }
-
-  async connect() {
-    this._ensureToken(); // 启动时确保有 token
-    this.server = http.createServer(async (req, res) => {
-      // v1.0.8: webhook 路由分发 (feishu/wechat 等): 匹配路径交给对应通道, 不走主逻辑
-      const reqPath0 = (req.url || "/").split("?")[0];
-      const wh = this.webhookRoutes.get(reqPath0);
-      if (wh) {
-        try { await wh(req, res); } catch (e) {
-          try { if (!res.writableEnded) { res.writeHead(500, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: e.message })); } } catch {}
-        }
-        return;
-      }
-      // CORS (v1.0.7): 默认 * (兼容); 配置 cors_origin 白名单时校验浏览器来源 (无 Origin 的非浏览器请求不受 CORS 约束)
-      const origin = req.headers.origin;
-      let allowOrigin = "*";
-      if (this.corsOrigins.length) {
-        allowOrigin = !origin ? "*" : (this.corsOrigins.includes(origin) ? origin : null);
-      }
-      if (!allowOrigin) {
-        res.writeHead(403, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "origin not allowed" }));
-        return;
-      }
-      res.setHeader("Access-Control-Allow-Origin", allowOrigin);
-      if (allowOrigin !== "*") res.setHeader("Vary", "Origin");
-      res.setHeader("Access-Control-Allow-Methods", "POST, GET, OPTIONS");
-      res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
-      if (req.method === "OPTIONS") { res.writeHead(204); res.end(); return; }
-
-      // 静态页面与 /health 不设限, 其余 API 限流
-      const reqPath = (req.url || "/").split("?")[0];
-      if (!(req.method === "GET" && (reqPath === "/" || reqPath === "/index.html" || reqPath === "/health"))) {
-        if (!this._rateLimit(req, res)) return;
-      }
-
-      if (req.method === "GET" && req.url === "/health") {
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ status: "ok", agent: this.agent.config.agent?.name || "ppx" }));
-        return;
-      }
-
-      if (req.method === "POST" && req.url === "/message") {
-        if (!this._authed(req, res)) { res.writeHead(401, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "unauthorized" })); return; }
-        const body = await this._readBody(req, res);
-        if (body === null) return;
-        try {
-          const data = JSON.parse(body);
-          const text = data.message || data.text || "";
-          if (!text) { res.writeHead(400); res.end(JSON.stringify({ error: "missing message" })); return; }
-          const sessionKey = data.sessionId || "default";
-          if (!this._acquire(res)) return;
-          try {
-            const reply = await this.agent.chat(String(text), { sessionKey });
-            res.writeHead(200, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ reply, sessionId: sessionKey, agent: this.agent.config.agent?.name || "ppx" }));
-          } finally { this._release(); }
-        } catch (e) {
-          res.writeHead(500, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: e.message }));
-        }
-        return;
-      }
-
-      // SSE 流式对话
-      if (req.method === "POST" && (req.url === "/message/stream" || req.url === "/chat")) {
-        if (!this._authed(req, res)) { res.writeHead(401, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "unauthorized" })); return; }
-        const body = await this._readBody(req, res);
-        if (body === null) return;
-        try {
-          const data = JSON.parse(body);
-          const text = data.message || data.text || "";
-          if (!text) { res.writeHead(400); res.end(JSON.stringify({ error: "missing message" })); return; }
-          const sessionKey = data.sessionId || "default";
-          res.writeHead(200, {
-            "Content-Type": "text/event-stream",
-            "Cache-Control": "no-cache",
-            "Connection": "keep-alive",
-            "X-Accel-Buffering": "no",
-          });
-          if (!this._acquire(res)) { try { res.end(); } catch {} return; }
-          try {
-            const send = (obj) => res.write("data: " + JSON.stringify(obj) + "\n\n");
-            let full = "";
-            const reply = await this.agent.chatStream(String(text), {
-              sessionKey,
-              onDelta: (d) => { full += d; try { send({ type: "delta", content: d }); } catch {} },
-              onTool: (ev) => { try { send({ type: "tool", tool: ev.tool, status: ev.type, args: ev.args, ok: ev.ok, durationMs: ev.durationMs }); } catch {} }, // 工具调用可视化
-              onStep: (ev) => { try { send({ type: "step", round: ev.round, maxRounds: ev.maxRounds }); } catch {} }, // turn/step 推理轮次进度
-            });
-            const finalContent = full || reply;
-            send({ type: "done", content: finalContent, sessionId: sessionKey });
-            res.end();
-          } finally { this._release(); }
-        } catch (e) {
-          try { res.write("data: " + JSON.stringify({ type: "error", error: e.message }) + "\n\n"); } catch {}
-          try { res.end(); } catch {}
-        }
-        return;
-      }
-
-      // 会话列表 (Web UI 多会话管理) [P1#6]
-      if (req.method === "GET" && req.url === "/sessions") {
-        if (!this._authed(req, res)) { res.writeHead(401, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "unauthorized" })); return; }
-        const list = (this.agent.sessionStore && this.agent.sessionStore.list) ? this.agent.sessionStore.list() : [];
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ sessions: list }));
-        return;
-      }
-
-      // 会话历史 (Web UI 切换会话时恢复消息显示): GET /sessions/:key/history
-      if (req.method === "GET" && /^\/sessions\/[^/]+\/history$/.test(reqPath)) {
-        if (!this._authed(req, res)) { res.writeHead(401, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "unauthorized" })); return; }
-        const key = decodeURIComponent(reqPath.split("/")[2]);
-        const msgs = this.agent.sessionStore && typeof this.agent.sessionStore.deriveMessages === "function"
-          ? this.agent.sessionStore.deriveMessages(key)
-          : [];
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ sessionId: key, messages: msgs }));
-        return;
-      }
-
-      // 会话重命名 [P1#6]
-      if (req.method === "POST" && req.url === "/sessions/rename") {
-        if (!this._authed(req, res)) { res.writeHead(401, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "unauthorized" })); return; }
-        const body = await this._readBody(req, res);
-        if (body === null) return;
-        const ok = this.agent.sessionStore && typeof this.agent.sessionStore.rename === "function"
-          ? this.agent.sessionStore.rename(body.from, body.to) : false;
-        res.writeHead(ok ? 200 : 404, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ ok }));
-        return;
-      }
-      // 会话删除 [P1#6]
-      if (req.method === "POST" && req.url === "/sessions/delete") {
-        if (!this._authed(req, res)) { res.writeHead(401, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "unauthorized" })); return; }
-        const body = await this._readBody(req, res);
-        if (body === null) return;
-        if (this.agent.sessionStore) this.agent.sessionStore.delete(body.key || "default");
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ ok: true }));
-        return;
-      }
-
-      // 会话重置
-      if (req.method === "POST" && req.url === "/reset") {
-        if (!this._authed(req, res)) { res.writeHead(401, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "unauthorized" })); return; }
-        const body = await this._readBody(req, res);
-        if (body === null) return;
-        try {
-          const data = JSON.parse(body || "{}");
-          this.agent.resetSession(data.sessionId || "default");
-        } catch {}
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ ok: true }));
-        return;
-      }
-
-      // ---- 静态界面 + 可观测 API ----
-      // 通用静态文件服务 (public/ 下任意文件, 含 vendor/ 资源, 防路径穿越)
-      if (req.method === "GET" && !reqPath.startsWith("/api/") && !["/message","/message/stream","/chat","/reset"].some(p=>reqPath===p)) {
-        const rel = reqPath === "/" ? "index.html" : reqPath.replace(/^\//, "");
-        const file = path.resolve(this.publicDir, rel);
-        if (file.startsWith(this.publicDir + path.sep) && fs.existsSync(file) && fs.statSync(file).isFile()) {
-          const ext = path.extname(file).toLowerCase();
-          const mime = { ".html":"text/html; charset=utf-8", ".js":"text/javascript", ".css":"text/css", ".json":"application/json", ".png":"image/png", ".jpg":"image/jpeg", ".svg":"image/svg+xml", ".ico":"image/x-icon" }[ext] || "application/octet-stream";
-          res.writeHead(200, { "Content-Type": mime });
-          res.end(fs.readFileSync(file));
-          return;
-        }
-        if (reqPath !== "/") { res.writeHead(404); res.end("not found"); return; }
-      }
-      // 静态页面
-      if (req.method === "GET" && (reqPath === "/" || reqPath === "/index.html")) {
-        const html = path.join(this.publicDir, "index.html");
-        if (fs.existsSync(html)) {
-          res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-          res.end(fs.readFileSync(html, "utf8"));
-        } else {
-          res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
-          res.end("皮皮虾服务已启动。public/index.html 未找到。");
-        }
-        return;
-      }
-      // API 端点认证
-      const protectedApi = reqPath.startsWith("/api/");
-      if (protectedApi && !this._authed(req, res)) { res.writeHead(401, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "unauthorized" })); return; }
-      // 轨迹 API
-      if (req.method === "GET" && reqPath === "/api/traces") {
-        const limit = Number((req.url.split("limit=")[1] || "").split("&")[0] || 50);
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify(this.agent.traces.read(undefined, limit)));
-        return;
-      }
-      // 统计 API (聚合记忆/轨迹/工具/经验/自愈)
-      if (req.method === "GET" && reqPath === "/api/stats") {
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify(this.agent.stats ? this.agent.stats() : this.agent.traces.stats()));
-        return;
-      }
-      // 记忆 API
-      if (req.method === "GET" && reqPath === "/api/memory") {
-        res.writeHead(200, { "Content-Type": "application/json" });
-        const facts = this.agent.facts ? this.agent.facts.list().slice(0, 20).map((f) => ({ content: f.content, score: f.score, type: f.type })) : [];
-        const scenes = this.agent.scenes ? this.agent.scenes.listWithDesc().slice(-10) : [];
-        res.end(JSON.stringify({ facts, scenes }));
-        return;
-      }
-      // 主动任务生成 API (ANS 自主性): 扫描记忆待办/偏好, 返回主动提醒 + 结构化 items (含 id)
-      if (req.method === "GET" && reqPath === "/api/proactive") {
-        res.writeHead(200, { "Content-Type": "application/json" });
-        try {
-          const out = await suggestProactive(this.agent);
-          res.end(JSON.stringify({ message: out ? out.text : null, items: out ? out.items : [] }));
-        } catch (e) {
-          res.end(JSON.stringify({ message: null, items: [], error: e.message }));
-        }
-        return;
-      }
-      // 标记待办完成 (ANS): POST /api/proactive/done { id } → 之后不再主动提醒
-      if (req.method === "POST" && reqPath === "/api/proactive/done") {
-        if (!this._authed(req, res)) { res.writeHead(401, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "unauthorized" })); return; }
-        const body = await this._readBody(req, res);
-        if (body === null) return;
-        try {
-          const data = JSON.parse(body || "{}");
-          const ok = this.agent.proactiveMarkDone(data.id);
-          res.writeHead(ok ? 200 : 404, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ ok }));
-        } catch (e) {
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: e.message }));
-        }
-        return;
-      }
-      // 生命周期状态 API (ANS): 阶段/年龄/进化/繁衍
-      if (req.method === "GET" && reqPath === "/api/lifecycle") {
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify(this.agent.lifecycleStatus ? this.agent.lifecycleStatus() : {}));
-        return;
-      }
-
-      // 提供方 API [本轮新增] - 模型配置 Web UI 后端
-      // GET    /api/providers        列出全部提供方 (key 抹掉, 只返 api_key_set 标志)
-      // POST   /api/providers        新增 (body: { provider: {...} })
-      // PUT    /api/providers        更新 (body: { id, patch: {...} })
-      // DELETE /api/providers        删除 (body: { id })
-      // POST   /api/providers/test   健康探测 (body: { id }), 复用 LLMClient.health()
-      // POST   /api/providers/reorder 重排 (body: { order: [id1, id2, ...] })
-      if (req.method === "GET" && reqPath === "/api/providers") {
-        if (!this._authed(req, res)) { res.writeHead(401, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "unauthorized" })); return; }
-        const providers = listProviders(this.agent.root);
-        const defaultId = providers[0] ? providers[0].id : null;
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ providers, default_id: defaultId }));
-        return;
-      }
-      if (req.method === "POST" && reqPath === "/api/providers") {
-        if (!this._authed(req, res)) { res.writeHead(401, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "unauthorized" })); return; }
-        const body = await this._readBody(req, res);
-        if (body === null) return;
-        try {
-          const data = JSON.parse(body || "{}");
-          const raw = data.provider || data;
-          const created = addProvider(this.agent.root, raw);
-          // 热重载 (新增默认时让 agent 立即可用)
-          this.agent.reloadProviders();
-          res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ ok: true, provider: created }));
-        } catch (e) {
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: e.message }));
-        }
-        return;
-      }
-      if (req.method === "PUT" && reqPath === "/api/providers") {
-        if (!this._authed(req, res)) { res.writeHead(401, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "unauthorized" })); return; }
-        const body = await this._readBody(req, res);
-        if (body === null) return;
-        try {
-          const data = JSON.parse(body || "{}");
-          if (!data.id) throw new Error("缺少 id");
-          const updated = updateProvider(this.agent.root, data.id, data.patch || {});
-          this.agent.reloadProviders();
-          res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ ok: true, provider: updated }));
-        } catch (e) {
-          const code = /不存在|缺少/.test(e.message) ? 404 : 400;
-          res.writeHead(code, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: e.message }));
-        }
-        return;
-      }
-      if (req.method === "DELETE" && reqPath === "/api/providers") {
-        if (!this._authed(req, res)) { res.writeHead(401, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "unauthorized" })); return; }
-        const body = await this._readBody(req, res);
-        if (body === null) return;
-        try {
-          const data = JSON.parse(body || "{}");
-          if (!data.id) throw new Error("缺少 id");
-          const removed = removeProvider(this.agent.root, data.id);
-          this.agent.reloadProviders();
-          res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ ok: true, provider: removed }));
-        } catch (e) {
-          const code = /不存在|缺少/.test(e.message) ? 404 : 400;
-          res.writeHead(code, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: e.message }));
-        }
-        return;
-      }
-      if (req.method === "POST" && reqPath === "/api/providers/test") {
-        if (!this._authed(req, res)) { res.writeHead(401, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "unauthorized" })); return; }
-        const body = await this._readBody(req, res);
-        if (body === null) return;
-        try {
-          const data = JSON.parse(body || "{}");
-          if (!data.id) throw new Error("缺少 id");
-          // 优先复用 agent 已有的 LLM 客户端 (含测试注入的 stub), 避免对磁盘配置的真实网络探测
-          // 兜底顺序: allProviders → agent.llm → 磁盘临时构造
-          let client = (this.agent.allProviders || []).find((c) => c.providerId === data.id);
-          let fromCache = !!client;
-          if (!client && this.agent.llm && this.agent.llm.providerId === data.id) {
-            client = this.agent.llm;
-            fromCache = true;
-          }
-          if (!client) {
-            const { readConfig } = await import("../config/providers.js");
-            const { providers } = readConfig(this.agent.root);
-            const p = providers.find((x) => x.id === data.id);
-            if (!p) throw new Error("提供方不存在");
-            const { LLMClient } = await import("../llm/client.js");
-            client = new LLMClient(p);
-          }
-          const healthy = await client.health();
-          const detail = healthy
-            ? `${client.backend === "openclaw" ? "openclaw 后端: Node 版本满足" : client.backend === "deepseek" ? "dsh 源码就绪" : fromCache ? "复用 agent 客户端, 探测通过" : "API 端点可达"}`
-            : "探测失败, 请检查 key/base_url/engine 路径/Node 版本";
-          res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ ok: true, healthy, detail, source: fromCache ? "agent-cache" : "disk-config" }));
-        } catch (e) {
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: e.message }));
-        }
-        return;
-      }
-      if (req.method === "POST" && reqPath === "/api/providers/reorder") {
-        if (!this._authed(req, res)) { res.writeHead(401, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "unauthorized" })); return; }
-        const body = await this._readBody(req, res);
-        if (body === null) return;
-        try {
-          const data = JSON.parse(body || "{}");
-          const providers = reorderProviders(this.agent.root, data.order || []);
-          this.agent.reloadProviders();
-          res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ ok: true, providers }));
-        } catch (e) {
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: e.message }));
-        }
-        return;
-      }
-
-      // 通用设置 API: 用户名 / HTTP 端口 / 安全 / agent 预设
-      // GET /api/settings    返回可编辑设置 (敏感字段只回 set 标志)
-      // PUT /api/settings    更新 (body: { patch: { user?, http?, security?, agent? } })
-      if (req.method === "GET" && reqPath === "/api/settings") {
-        if (!this._authed(req, res)) { res.writeHead(401, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "unauthorized" })); return; }
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ settings: getSettings(this.agent.root) }));
-        return;
-      }
-      if (req.method === "PUT" && reqPath === "/api/settings") {
-        if (!this._authed(req, res)) { res.writeHead(401, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "unauthorized" })); return; }
-        const body = await this._readBody(req, res);
-        if (body === null) return;
-        try {
-          const data = JSON.parse(body || "{}");
-          const settings = updateSettings(this.agent.root, data.patch || {});
-          // 热重载: 用户名/安全/agent 预设立即生效
-          this.agent.reloadSettings();
-          res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ ok: true, settings }));
-        } catch (e) {
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: e.message }));
-        }
-        return;
-      }
-
-      res.writeHead(404); res.end("not found");
-
-    });
-
-    await new Promise((resolve, reject) => {
-      this.server.once("error", reject);
-      this.server.listen(this.port, this.host, resolve);
-    });
-    this.connected = true;
-    return this;
-  }
-
-  async send(to, text) { return text; } // HTTP 是请求-响应, 直接返回
-
-  // 连通性测试: 用独立实例起临时 server 验证端口可绑定
-  async test() {
-    try {
-      await this.connect();
-      await this.disconnect();
-      return { ok: true, detail: `HTTP 通道可启动: http://${this.host}:${this.port}` };
-    } catch (e) {
-      return { ok: false, detail: e.message };
-    }
-  }
-
-  async disconnect() {
-    if (this.server) { await new Promise((r) => this.server.close(r)); this.server = null; }
-    this.connected = false;
-  }
-}
+// src/channels/http.js - HTTP 通道 (零依赖)
+// 起一个本地 HTTP server, 接收 POST /message 消息, 调 agent 回复
+//
+// 2026-09-18 重构: 路由主体原先是一个 ~530 行的巨型 handler, 其中
+//   - 「鉴权失败写 401」重复 18 次
+//   - 「writeHead + Content-Type + JSON.stringify + end」重复 40+ 次
+//   - 「读 body → JSON.parse」重复 12 次
+// 现收敛为 5 个私有工具方法 (_json / _unauthorized / _requireAuth / _readJson / _fail),
+// 并按「CORS → MCP → webhook → 限流 → 路由」分层拆成若干具名方法;
+// 对外接口 (类/方法/路径/状态码/响应体) 完全不变。
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { Channel } from "./base.js";
+import { readBody, sendJson, SSE_HEADERS } from "../utils/http.js";
+import {
+  listProviders, addProvider, updateProvider, removeProvider, reorderProviders, readConfig,
+} from "../config/providers.js";
+import { getSettings, updateSettings } from "../config/settings.js";
+import { suggestProactive } from "../ans/proactive.js";
+import { ensureDir, atomicWrite, readText } from "../utils/store.js";
+import { TokenBucket } from "../utils/rate-limit.js";
+import { createMcpEndpoint } from "../mcp/http.js";
+import { createAdminTools } from "../mcp/admin.js";
+import { buildTree, readWorkspaceFile } from "./workspace.js";
+import { debug } from "../utils/logger.js";
+
+const MAX_BODY = 1024 * 1024;          // 请求体上限 1MB
+const RATE_PER_MIN = 60;               // 每 IP 每分钟最大请求数 (令牌桶)
+const MAX_INFLIGHT = 4;                // 同时处理的最大对话请求数 (超出立即 429, 防单 agent 被并发压垮)
+
+// REST 端点退役开关覆盖的路径 (channels.http.mcp.legacy_rest = false 时统一 410)
+const LEGACY_REST_PATHS = ["/message", "/message/stream", "/chat", "/sessions", "/reset", "/interrupt"];
+
+// 恒定时间字符串比较 (2026-09-17 安全修复):
+// 直接 `a === b` 会在首个不同字节处提前返回, 理论上是可观测的计时侧信道。
+// 先把两侧都摘要成定长 32 字节再比对, 长度差异也被消除。
+// @param {string} a
+// @param {string} b
+// @returns {boolean}
+export function safeEqual(a, b) {
+  const ha = crypto.createHash("sha256").update(String(a ?? "")).digest();
+  const hb = crypto.createHash("sha256").update(String(b ?? "")).digest();
+  try { return crypto.timingSafeEqual(ha, hb); } catch { return false; }
+}
+
+// 面向客户端的错误文案净化: 只保留业务语义, 屏蔽 Node/流内部实现细节
+// (避免把 "Cannot write headers after they are sent to the client" 这类内部错误原文回给前端)
+const INTERNAL_ERR_RE = /ERR_HTTP_HEADERS_SENT|ERR_STREAM_|Cannot (write headers|call write after)|write after end|EPIPE|ECONNRESET/i;
+export function publicErrorMessage(e) {
+  // 兼容三种入参: Error 实例 / 字符串 / 任意对象 (对象且无 message 时不该退化成 "[object Object]")
+  const raw = (e && typeof e === "object" && typeof e.message === "string") ? e.message
+    : (typeof e === "string" ? e : "");
+  const msg = raw.trim();
+  if (!msg) return "服务内部错误";
+  if (INTERNAL_ERR_RE.test(msg)) return "连接状态异常, 请重试";
+  return msg.slice(0, 300);
+}
+
+// HTTP 鉴权 token 解析 / 生成 (v1.0.9 起持久化, 重启复用, 免去 Web 前端每次重贴 token)
+// 优先级: 1) 显式配置 (env/ppx.json 的 channels.http.auth_token) > 2) 数据目录持久化文件复用 > 3) 新生成并原子落盘
+// @param {object} opts
+// @param {string}       opts.configured    显式配置的 token (PPX_AUTH_TOKEN 或 config 里的 auth_token; 空串视为未配置)
+// @param {string|null}  opts.persistedFile 自动生成 token 的持久化文件路径 (无则仅返回生成, 不落盘)
+// @returns {{ token:string, source:"configured"|"persisted"|"generated", generated:boolean }}
+// 纯函数, 便于单测: 不依赖 agent/实例状态, 全部副作用 (读/写文件) 走参数传入的路径
+export function resolveAuthToken({ configured = "", persistedFile = null } = {}) {
+  const explicit = String(configured || "").trim();
+  // 优先级 1: 显式配置 (env/config) — 以身作则, 不读写持久化文件
+  if (explicit) return { token: explicit, source: "configured", generated: false };
+
+  // 优先级 2: 复用持久化文件里的旧 token (非空)
+  if (persistedFile) {
+    const old = String(readText(persistedFile, "") || "").trim();
+    if (old) return { token: old, source: "persisted", generated: false };
+  }
+
+  // 优先级 3: 新生成随机 token; 若有持久化路径则原子落盘 (写 .tmp 再 rename, 全程目录存在)
+  const token = crypto.randomBytes(24).toString("hex");
+  if (persistedFile) {
+    try {
+      ensureDir(path.dirname(persistedFile));
+      atomicWrite(persistedFile, token); // .tmp + rename: 原子替换, 并发/崩溃不损坏
+    } catch {
+      // token 已生成但在内存可用; 落盘失败仅丢失"跨重启复用", 不阻断启动
+    }
+  }
+  return { token, source: "generated", generated: true };
+}
+
+export class HttpChannel extends Channel {
+  constructor(agent, { port = 8899, host = "127.0.0.1" } = {}) {
+    super("http", agent);
+    this.port = port;
+    this.host = host;
+    this.server = null;
+    this.agent = agent;
+    this.publicDir = path.join(this.agent.root, "public");
+    // v1.0.9: token 解析延迟到 connect() 的 _ensureToken, 以便持久化文件与 agent.dataDir 就绪
+    // 这里只缓存显式配置 (env/config), 交给 _ensureToken 走"显式 > 持久化 > 新生成"的优先级
+    this.authToken = process.env.PPX_AUTH_TOKEN || this._tokenFromConfig();
+    this._persistedTokenFile = agent.dataDir ? path.join(agent.dataDir, "http-token") : null;
+    this._rateLimiter = new TokenBucket({ perMin: RATE_PER_MIN });
+    this._buckets = this._rateLimiter.buckets; // ip -> {tokens, last} (可观测, 与限流器同一 Map)
+    // v1.0.8: webhook 路由注册表 (feishu/wechat 通道挂载), 单一 request handler 分发, 无多 listener 竞态
+    this.webhookRoutes = new Map(); // path -> async (req, res) => void
+    // CORS 来源白名单 (v1.0.7): channels.http.cors_origin 数组; 未配置默认 * (向后兼容)
+    // 配置后仅放行白名单 origin, 其余跨域请求 403 (token 泄露时降低任意跨站读取风险)
+    this.corsOrigins = this._corsFromConfig();
+    this._inFlight = 0; // 当前处理中的对话请求数
+    // 2026-10-03: 主动提醒 SSE 中枢 —— GET /events 长连接客户端集合;
+    // send() 广播 {type:"reminder"} 给所有在线 Web UI (修复 server.js broadcast 落 no-op 的断链)
+    this._sseClients = new Set();
+    this._sseBeat = null; // 心跳定时器 (有客户端时启动, 全部断开后自动清)
+    // 2026-10-03 接线 (P2): 协议总线 EQ 此前零消费者 —— 订阅后经 SSE /events 广播给
+    // Web UI 时间线 (TASK_TURN_*/APPROVAL_REQUESTED 等结构化事件实时到达前端)。
+    this._unsubBus = null;
+    if (this.agent?.protocolBus?.eq?.subscribe) {
+      this._unsubBus = this.agent.protocolBus.eq.subscribe((ev) => this._broadcastEvent(ev));
+    }
+    // v2.6.0: MCP 标准端点 (Streamable HTTP) — 默认开启, 路径 /mcp
+    const mcpCfg = (this.agent?.config?.channels?.http?.mcp) || {};
+    this.mcpEnabled = mcpCfg.enabled !== false;
+    this.mcpPath = mcpCfg.path || "/mcp";
+    // v2.6.0: 产品壳已全部走 MCP (前端不再调用 REST)。服务端默认保留 REST 兼容 (旧脚本/测试不受影响);
+    // 想彻底退役可设 channels.http.mcp.legacy_rest=false → /api/* 与 /message* 返回 410 并引导 /mcp
+    this.mcpLegacyRest = mcpCfg.legacy_rest !== false;
+    if (this.mcpEnabled) {
+      // v2.6.0: admin 虚拟工具 (会话/提供方/设置/任务面板) 注入 MCP 端点, 供 web 前端替代 REST /api/*
+      const admin = createAdminTools(agent);
+      this.mcpAdmin = admin;
+      const { server: mcpServer, handler: mcpHandler } = createMcpEndpoint(agent, {
+        name: agent.config?.agent?.name || "ppxans-harness",
+        // 版本由 createMcpEndpoint -> McpServer 默认读 package.json (不再硬编码)
+        supportedVersions: mcpCfg.supported_versions,
+        extraTools: admin.tools,
+        authenticated: (req, res) => {
+          if (this._authed(req, res)) return true;
+          // _authed 只做判断不写响应, 这里补 401 (否则客户端永远挂等)
+          this._unauthorized(res);
+          return false;
+        },
+        rateLimit: (req, res) => this._rateLimit(req, res),
+        // 2026-10-03 修复 (P2): 原 skipOriginCheck:true 被工厂吞参且语义本身危险 ——
+        // 宿主 _applyCors 对恶意 Origin 只是"不回显 ACAO"并不拒绝, 无法防 DNS rebinding;
+        // 真正防线是 handler 内 origin 校验。改为与宿主共享同一白名单 (未配置时 handler
+        // 走安全默认: 仅回环 Origin 放行)。
+        allowedOrigins: this.corsOrigins.length ? this.corsOrigins : undefined,
+      });
+      this.mcpServer = mcpServer;
+      this.mcpHandler = mcpHandler;
+    }
+  }
+
+  // ==================== 请求/响应工具 (消除路由层重复样板) ====================
+
+  // 统一 JSON 响应 (writeHead + Content-Type + 序列化 + end); headers 用于 Retry-After / Cache-Control
+  _json(res, code, obj, headers = {}) {
+    sendJson(res, code, obj, { headers });
+  }
+
+  // 鉴权失败响应
+  _unauthorized(res) {
+    this._json(res, 401, { error: "unauthorized" });
+  }
+
+  // 鉴权门禁: 通过返回 true; 未通过则已写 401 并返回 false
+  // 用法: `if (!this._requireAuth(req, res)) return true;`
+  _requireAuth(req, res) {
+    if (this._authed(req, res)) return true;
+    this._unauthorized(res);
+    return false;
+  }
+
+  // 读 body 并解析 JSON (缺省 "{}")。体超限时 _readBody 已写 413 并返回 null → 这里也返回 null。
+  // JSON 解析失败向上抛错, 由调用方 try/catch 转 400 (保持各路由既有错误语义)。
+  async _readJson(req, res) {
+    const body = await this._readBody(req, res);
+    if (body === null) return null;
+    return JSON.parse(body || "{}");
+  }
+
+  // 统一错误响应 (2026-10-03 修复): 原样回传 e.message 会把内部错误原文
+  // (ERR_HTTP_HEADERS_SENT / 文件路径等) 泄露给客户端, 统一过 publicErrorMessage 净化
+  _fail(res, e, code = 400) {
+    this._json(res, code, { error: publicErrorMessage(e) });
+  }
+
+  // 对话类路由的公共前置 (原 /message 与 /message/stream 各抄一份):
+  //   鉴权 → 读 JSON (超限时 _readJson 已回 413) → 抽取消息文本与会话键。
+  //   任一步失败时响应已写出, 返回 null, 调用方统一 `return true`。
+  async _readChatRequest(req, res) {
+    if (!this._requireAuth(req, res)) return null;
+    const data = await this._readJson(req, res);
+    if (data === null) return null;
+    const text = data.message || data.text || "";
+    if (!text) { this._json(res, 400, { error: "missing message" }); return null; }
+    return { text, sessionKey: data.sessionId || "default" };
+  }
+
+  // 简单并发护栏: 用计数信号量限制同时处理的对话请求, 超出立即 429
+  // 防止多个慢请求无限叠加占用单线程主 agent (可选的背压层, 区别于每 IP 令牌桶限流)
+  _acquire(res) {
+    if (this._inFlight >= MAX_INFLIGHT) {
+      this._json(res, 429, { error: "too many concurrent requests, retry shortly" }, { "Retry-After": "5" });
+      return false;
+    }
+    this._inFlight += 1;
+    return true;
+  }
+  _release() { if (this._inFlight > 0) this._inFlight -= 1; }
+
+  // v1.0.8: webhook 通道注册路由 (路径匹配即由该通道处理, 不经过主逻辑)
+  registerWebhook(path, handler) {
+    if (typeof handler === "function") this.webhookRoutes.set(path, handler);
+    return () => this.webhookRoutes.delete(path);
+  }
+
+  _corsFromConfig() {
+    try {
+      const c = this.agent?.config?.channels?.http?.cors_origin;
+      if (c === undefined || c === null || c === "*") return [];
+      if (Array.isArray(c)) return c.filter(Boolean);
+      if (typeof c === "string") return [c];
+    } catch { /* 配置异常回退默认 */ }
+    return [];
+  }
+
+  // 判断请求是否来自本机回环 (127.0.0.1/::1) —— 只有本机才允许把 token 注入首页
+  // 安全边界: 服务默认只绑 127.0.0.1; 即使绑到 0.0.0.0, 局域网访问者拿不到注入的 token,
+  // 前端会退化为"手填 token"形态, 而恶意网页因 CORS 读不到首页响应, 无法窃取 token。
+  _isLoopback(req) {
+    const a = (req.socket && req.socket.remoteAddress) || "";
+    return a === "127.0.0.1" || a === "::1" || a === "::ffff:127.0.0.1";
+  }
+
+  // 来源是否可信 (2026-09-17 安全修复, P0-1):
+  // 仅靠 remoteAddress 判断"本机"是不够的 —— 浏览器里任意网站发起的请求, 其源地址同样是 127.0.0.1。
+  // 配合默认 `Access-Control-Allow-Origin: *`, 恶意页面可以 fetch('http://127.0.0.1:8899/api/bootstrap')
+  // 并把响应体读走, 从而拿到本地 API token (实测可复现)。
+  // 因此对"下发 token"的路径追加两道浏览器侧的来源判据:
+  //   1) Origin 头存在时, 其 hostname 必须是本机回环 (同源导航不带 Origin → 放行)
+  //   2) Sec-Fetch-Site 为 cross-site → 一律拒绝 (现代浏览器的强信号)
+  // v3.0.1 (P1#9): 追加第 3 道判据 —— Origin 端口必须等于本服务端口。
+  //   原实现只看 hostname: 同机恶意端口 (127.0.0.1:9999) 的页面 hostname 也是 127.0.0.1, 被误判可信。
+  _originTrusted(req) {
+    const sfs = String(req.headers["sec-fetch-site"] || "").toLowerCase();
+    if (sfs === "cross-site") return false;
+    const origin = req.headers["origin"];
+    if (!origin) return true; // 非浏览器请求 (curl/脚本) 或同源导航
+    try {
+      const u = new URL(origin);
+      const host = u.hostname.replace(/^\[|\]$/g, "");
+      if (!(host === "127.0.0.1" || host === "localhost" || host === "::1")) return false;
+      // 端口必须与本服务一致 (Origin 未写端口时按协议默认 80/443 折算)
+      const originPort = u.port || (u.protocol === "https:" ? "443" : "80");
+      const myPort = String(this.port || "");
+      if (myPort && originPort !== myPort) return false;
+      return true;
+    } catch {
+      return false; // Origin 畸形 → 不予信任
+    }
+  }
+
+  // 可信本地请求 = 回环地址 + 可信来源 (下发 token 的唯一条件)
+  _isTrustedLocal(req) {
+    return this._isLoopback(req) && this._originTrusted(req);
+  }
+
+  // 版本号取自 package.json (不硬编码, 与 McpServer 同源策略)
+  // 2026-09-18: 结果缓存 —— /health 与 /api/bootstrap 每次请求都重读磁盘无必要 (版本运行期不变)
+  _pkgVersion() {
+    if (this._pkgVersionCache) return this._pkgVersionCache;
+    try {
+      const p = path.join(this.agent.root, "package.json");
+      if (fs.existsSync(p)) {
+        const v = JSON.parse(fs.readFileSync(p, "utf8")).version || "0.0.0";
+        this._pkgVersionCache = v;
+        return v;
+      }
+    } catch { /* 读不到就用占位 */ }
+    return "0.0.0";
+  }
+
+  // Web 前端引导数据 (注入首页 <head>, 本地零配置可用)
+  // authToken 仅在"可信本地请求"时下发 (回环 + 来源可信, 见 _isTrustedLocal);
+  // 非回环 / 跨站来源只给 token_required 标志, 不下发任何凭据
+  bootstrapPayload(req) {
+    const loopback = this._isLoopback(req);
+    const trusted = this._isTrustedLocal(req);
+    // 2026-10-03: 补充 model/toolsCount/root —— 设置面板此前读 ag.llm.model / j.tools /
+    // j.root 三个 bootstrap 从未返回的字段, 永远显示 "-" (死绑定)。
+    let toolsCount = null;
+    try { toolsCount = this.agent?.tools?.list?.().length ?? null; } catch { toolsCount = null; }
+    const model = this.agent?.config?.providers?.[0]?.model
+      || this.agent?.config?.agent?.model_preference || "";
+    return {
+      app: "ppxans-harness",
+      version: this._pkgVersion(),
+      agent: (this.agent?.config?.agent?.name) || "皮皮虾",
+      user: (this.agent?.config?.user?.name) || "",
+      port: this.port,
+      host: this.host,
+      base: `http://${this.host === "0.0.0.0" ? "127.0.0.1" : this.host}:${this.port}`,
+      authToken: trusted ? (this.authToken || "") : "",
+      tokenLoopback: loopback,
+      tokenTrusted: trusted,
+      tokenRequired: Boolean(this.authToken),
+      mcpPath: this.mcpPath,
+      legacyRest: this.mcpLegacyRest,
+      model,
+      toolsCount,
+      root: this.agent?.root || "",
+      time: new Date().toISOString(),
+    };
+  }
+
+  // 读取首页 HTML 并注入 window.__PPX_BOOTSTRAP__ (找不到文件返回 null)
+  renderIndex(req) {
+    const htmlPath = path.join(this.publicDir, "index.html");
+    if (!fs.existsSync(htmlPath)) return null;
+    let html = fs.readFileSync(htmlPath, "utf8");
+    const cfg = JSON.stringify(this.bootstrapPayload(req)).replace(/</g, "\\u003c");
+    const tag = `<script>window.__PPX_BOOTSTRAP__=${cfg};</script>`;
+    // 优先插在 </head> 前; 模板没有 head 就退化为插到 </body> 前
+    if (html.includes("</head>")) html = html.replace("</head>", `${tag}\n</head>`);
+    else if (html.includes("</body>")) html = html.replace("</body>", `${tag}\n</body>`);
+    else html = tag + html;
+    return html;
+  }
+
+  _tokenFromConfig() {
+    try {
+      const p = path.join(this.agent.root, "config", "ppx.json");
+      if (fs.existsSync(p)) {
+        const cfg = JSON.parse(fs.readFileSync(p, "utf8"));
+        return (cfg.channels && cfg.channels.http && cfg.channels.http.auth_token) || "";
+      }
+    } catch (e) { debug(`[channels/http] 已忽略异常: ${e && e.message ? e.message : e}`); }
+    return "";
+  }
+
+  // 若未配置 token: 复用持久化文件(重启不变)或自动生成并原子落盘 (类似 Jupyter token)
+  _ensureToken() {
+    if (this.authToken) return this.authToken;
+    const r = resolveAuthToken({ configured: process.env.PPX_AUTH_TOKEN || "", persistedFile: this._persistedTokenFile });
+    this.authToken = r.token;
+    if (r.source === "persisted") {
+      console.log("  ℹ  HTTP 认证 token 复用自持久化文件 (重启不更换, 前端无需重贴)");
+    } else {
+      console.log("");
+      console.log("  ⚠️  HTTP 认证 token 未配置, 已自动生成并持久化 (重启复用):");
+      console.log(`       PPX_AUTH_TOKEN=${this.authToken}`);
+      console.log(`     用法: Authorization: Bearer ${this.authToken}`);
+      console.log(`     token 已保存到 ${this._persistedTokenFile}, 重启不再更换`);
+      console.log("      (或设置 config/ppx.json 的 channels.http.auth_token)");
+      console.log("");
+    }
+    return this.authToken;
+  }
+
+  _authed(req, res) {
+    if (!this.authToken) return true; // 兼容旧调用: _ensureToken 在 connect 时已执行
+    const h = req.headers["authorization"] || "";
+    return safeEqual(h, "Bearer " + this.authToken);
+  }
+
+  // 简单令牌桶限流: 每 IP 60 req/min (实现共用 utils/rate-limit, 含过期桶回收)
+  // 2026-09-17: 桶表原本只增不减 —— 长期运行 + 多变源地址会持续吃内存; 现由 TokenBucket.sweep 摊还回收。
+  // this._buckets 仍指向限流器内部 Map, 保持可观测性 (测试据此注入过期桶)。
+  _rateLimit(req, res) {
+    const ip = req.socket?.remoteAddress || "unknown";
+    if (this._rateLimiter.take(ip)) return true;
+    this._json(res, 429, { error: "rate limited" }, { "Retry-After": "60" });
+    return false;
+  }
+
+  // 读取请求体, 限制大小 (超限写 413 并返回 null)
+  async _readBody(req, res) {
+    const body = await readBody(req, { maxBytes: MAX_BODY });
+    if (body === null) {
+      this._json(res, 413, { error: "request too large" });
+      return null;
+    }
+    return body;
+  }
+
+  // ==================== 路由 ====================
+
+  async connect() {
+    this._ensureToken(); // 启动时确保有 token
+    this.server = http.createServer((req, res) => this._dispatch(req, res));
+
+    await new Promise((resolve, reject) => {
+      this.server.once("error", reject);
+      this.server.listen(this.port, this.host, resolve);
+    });
+    // v3.0.1 (P1#9): port=0 (临时端口) 时回填真实端口 —— Origin 同端口判据依赖 this.port
+    try {
+      const addr = this.server.address();
+      if (addr && typeof addr === "object" && addr.port) this.port = addr.port;
+    } catch (e) { debug(`[channels/http] 已忽略异常: ${e && e.message ? e.message : e}`); }
+    this.connected = true;
+    return this;
+  }
+
+  // 单入口分发: CORS/OPTIONS → MCP 端点 → webhook → 限流 → 业务路由, 最后兜底 404/500
+  async _dispatch(req, res) {
+    try {
+      const reqPath = (req.url || "/").split("?")[0];
+      if (!this._applyCors(req, res, reqPath)) return;
+
+      // v2.6.0: MCP 标准端点优先 (Streamable HTTP, 单端点 POST)
+      if (this.mcpEnabled && this.mcpHandler && req.method === "POST" && reqPath === this.mcpPath) {
+        return this._runHandler(this.mcpHandler, req, res);
+      }
+      // v1.0.8: webhook 路由分发 (feishu/wechat 等): 匹配路径交给对应通道, 不走主逻辑
+      const wh = this.webhookRoutes.get(reqPath);
+      if (wh) return this._runHandler(wh, req, res);
+
+      // 2026-10-03: 主动提醒 SSE 端点 (GET /events)。独立于 /api/* 是因为 legacy_rest=false
+      // 时 API 全部 410, 而事件流是 Web UI 实时能力不属于退役面。长连接只建一次, 走正常限流。
+      if (req.method === "GET" && reqPath === "/events") return this._handleEvents(req, res);
+
+      // 静态页面与 /health 不设限, 其余 API 限流
+      const isOpenGet = req.method === "GET" && (reqPath === "/" || reqPath === "/index.html" || reqPath === "/health");
+      if (!isOpenGet && !this._rateLimit(req, res)) return;
+
+      // v2.6.0 REST 退役开关: /message* /sessions* /reset 与 /api/* 同受 mcp.legacy_rest 控制
+      // (默认关闭: 全部走标准 MCP 端点 /mcp; 旧脚本可配置 legacy_rest: true 恢复)
+      if (!this.mcpLegacyRest && LEGACY_REST_PATHS.some((p) => reqPath === p || reqPath.startsWith(p + "/"))) {
+        return this._json(res, 410, { error: "REST 端点已退役, 请使用标准 MCP 端点 POST /mcp (channels.http.mcp.legacy_rest=true 可恢复)" });
+      }
+
+      if (await this._route(req, res, reqPath)) return;
+      res.writeHead(404); res.end("not found");
+    } catch (e) {
+      // 兜底: 路由内异常不应泄漏内部实现细节, 也不应让连接悬空
+      try {
+        if (!res.writableEnded) this._json(res, 500, { error: publicErrorMessage(e) });
+      } catch (e) { debug(`[channels/http] 已忽略异常: ${e && e.message ? e.message : e}`); }
+    }
+  }
+
+  // 执行「自行写响应」的子 handler (MCP / webhook): 失败时若尚未写头则补 500
+  async _runHandler(fn, req, res) {
+    try {
+      await fn(req, res);
+    } catch (e) {
+      try {
+        if (!res.writableEnded) this._json(res, 500, { error: e.message });
+      } catch (e) { debug(`[channels/http] 已忽略异常: ${e && e.message ? e.message : e}`); }
+    }
+  }
+
+  // 来源 host 是否本机回环 (不校验端口 —— 浏览器 MCP 客户端场景用, 见 _applyCors)
+  _loopbackOrigin(req) {
+    const origin = req.headers["origin"];
+    if (!origin) return false;
+    try {
+      const host = new URL(origin).hostname.replace(/^\[|\]$/g, "");
+      return host === "127.0.0.1" || host === "localhost" || host === "::1";
+    } catch { return false; }
+  }
+
+  // 统一 CORS 响应头 (所有路由含 /mcp 共用)。返回 false 表示本次请求无需继续 (已响应或来源被拒)。
+  // v3.0.1 (P1#9) 收紧默认语义: 原默认 `*` 把所有 API 响应对任意跨域页面开放。
+  //   自带 Web UI 与服务同源, 根本不需要 ACAO; 非浏览器客户端没有 Origin 头, 也不需要。
+  //   现默认只回显「本机回环 + 同端口」来源 (即自带 UI);
+  //   例外: /mcp 端点对本机回环任意端口回显 —— 浏览器形态 MCP 客户端 (MCP Inspector 等)
+  //   是正当场景, 且 /mcp 有 Bearer 门禁, 跨域可读的只是 401 拒绝体, 不泄任何凭据。
+  //   其余跨域需求显式配 channels.http.cors_origin 白名单。
+  _applyCors(req, res, reqPath = "") {
+    const reqOrigin = req.headers.origin;
+    let allowOrigin = null;
+    if (this.corsOrigins.length) {
+      allowOrigin = reqOrigin && this.corsOrigins.includes(reqOrigin) ? reqOrigin : null;
+      if (reqOrigin && !allowOrigin) {
+        this._json(res, 403, { error: "origin not allowed" });
+        return false;
+      }
+    } else if (reqOrigin) {
+      if (this._originTrusted(req)) allowOrigin = reqOrigin;
+      else if (reqPath === this.mcpPath && this._loopbackOrigin(req)) allowOrigin = reqOrigin;
+    }
+    if (allowOrigin) {
+      res.setHeader("Access-Control-Allow-Origin", allowOrigin);
+      res.setHeader("Vary", "Origin");
+    }
+    res.setHeader("Access-Control-Allow-Methods", "POST, GET, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, MCP-Protocol-Version, Mcp-Method, Mcp-Name");
+    if (req.method === "OPTIONS") { res.writeHead(204); res.end(); return false; }
+    return true;
+  }
+
+  // 业务路由。返回 true 表示已处理 (响应已写); false 交给 404 兜底。
+  // 2026-09-18 重构: 原为一个 161 行的巨型分支链, 现按域拆成 4 个具名子路由 + 1 个 API 门禁,
+  // 每个子路由「不匹配 → undefined/false, 匹配 → 已写响应并返回 true」。分支顺序与语义完全不变。
+  async _route(req, res, reqPath) {
+    const get = req.method === "GET";
+    const post = req.method === "POST";
+
+    if (this._routeHealth(req, res, get, reqPath)) return true;
+    if (await this._routeChat(req, res, post, reqPath)) return true;
+    if (await this._routeSessions(req, res, get, post, reqPath)) return true;
+
+    // 静态界面三态: undefined = 不匹配, true/false = 已匹配且该值即路由结果
+    const stat = this._routeStatic(req, res, get, reqPath);
+    if (stat !== undefined) return stat;
+
+    // API 门禁 (REST 退役开关 + 鉴权); 返回 true 表示已拦下并写响应
+    if (this._gateApi(req, res, reqPath)) return true;
+    return this._apiRoute(req, res, reqPath);
+  }
+
+  // ---- 路由域 1: 健康检查 ----
+  _routeHealth(req, res, get, reqPath) {
+    if (!get || reqPath !== "/health") return false;
+    this._json(res, 200, {
+      status: "ok",
+      agent: this.agent.config.agent?.name || "ppx",
+      app: "ppxans-harness",
+      version: this._pkgVersion(),
+      web: "/",
+      mcp: this.mcpEnabled ? this.mcpPath : null,
+      uptime_ms: Math.round(process.uptime() * 1000),
+    });
+    return true;
+  }
+
+  // ---- 路由域 2: 对话 (POST /message 与 SSE 流式) ----
+  async _routeChat(req, res, post, reqPath) {
+    if (!post) return false;
+
+    // 非流式对话: POST /message
+    if (reqPath === "/message") {
+      const req0 = await this._readChatRequest(req, res);
+      if (!req0) return true;
+      const { text, sessionKey } = req0;
+      if (!this._acquire(res)) return true;
+      try {
+        const reply = await this.agent.chat(String(text), { sessionKey });
+        this._json(res, 200, { reply, sessionId: sessionKey, agent: this.agent.config.agent?.name || "ppx" });
+      } catch (e) {
+        this._fail(res, e, 500);
+      } finally { this._release(); }
+      return true;
+    }
+
+    // SSE 流式对话: POST /message/stream 或 /chat
+    if (reqPath === "/message/stream" || reqPath === "/chat") {
+      const req0 = await this._readChatRequest(req, res);
+      if (!req0) return true;
+      const { text, sessionKey } = req0;
+      // 2026-09-17 修复 (P0-3 / P1-1):
+      //   ① 并发护栏必须在 writeHead(200) 之前判定 —— 原先先发 200 SSE 头再 _acquire,
+      //      超限时 _acquire 内的 writeHead(429) 抛 ERR_HTTP_HEADERS_SENT, 被外层 catch
+      //      转成一条 SSE error 事件, 客户端拿到 "HTTP 200 + text/event-stream" 却永远等不到
+      //      内容 (实测可复现), 同时把 Node 内部错误原文泄漏给了客户端。
+      //   ② 发完 200 后立刻 flushHeaders() —— 否则响应头要等到第一次 res.write 才下发,
+      //      LLM 慢首包时客户端迟迟收不到任何响应头 (实测 6s 无任何响应)。
+      if (!this._acquire(res)) return true;
+      res.writeHead(200, SSE_HEADERS);
+      if (typeof res.flushHeaders === "function") res.flushHeaders();
+      // v3.0.1 (P0#2): 客户端中途断连 → res 变 destroyed, 后续 write 触发 ERR_STREAM_DESTROYED
+      // 且 res 无 error 监听器 → 每个 delta 炸一次 uncaughtException (错误风暴)。
+      //   ① 挂 error 监听兜底; ② close 且响应未正常结束时中断上游生成 (按会话, P1#3);
+      //   ③ send 前检查 destroyed (writableEnded 不覆盖 destroy 场景)
+      res.on("error", (e) => debug(`[channels/http] SSE 流错误(已忽略): ${e && e.message ? e.message : e}`));
+      res.on("close", () => {
+        if (!res.writableEnded && typeof this.agent.interrupt === "function") {
+          try { this.agent.interrupt(sessionKey); } catch (e) { debug(`[channels/http] 已忽略异常: ${e && e.message ? e.message : e}`); }
+          debug("[channels/http] SSE 客户端断连, 已中断上游生成 (sessionKey=" + sessionKey + ")");
+        }
+      });
+      try {
+        const send = (obj) => {
+          if (res.writableEnded || res.destroyed) return false; // v3.0.1 (P0#2): 断连后静默丢弃
+          try { res.write("data: " + JSON.stringify(obj) + "\n\n"); return true; } catch (e) { debug(`[channels/http] 已忽略异常: ${e && e.message ? e.message : e}`); return false; }
+        };
+        let full = "";
+        const reply = await this.agent.chatStream(String(text), {
+          sessionKey,
+          onDelta: (d) => { full += d; send({ type: "delta", content: d }); },
+          onTool: (ev) => { send({ type: "tool", tool: ev.tool, id: ev.id, status: ev.type, args: ev.args, ok: ev.ok, durationMs: ev.durationMs }); }, // 工具调用可视化
+          onStep: (ev) => { send({ type: "step", round: ev.round, maxRounds: ev.maxRounds }); }, // turn/step 推理轮次进度
+        });
+        const finalContent = full || reply;
+        const usage = this.agent?.usageStats
+          ? { calls: this.agent.usageStats.calls, tokens: this.agent.usageStats.tokens }
+          : null;
+        send({ type: "done", content: finalContent, sessionId: sessionKey, usage, tokens: usage });
+        if (!res.writableEnded && !res.destroyed) res.end();
+      } catch (e) {
+        // 不外泄内部实现细节 (如 ERR_HTTP_HEADERS_SENT 之类)
+        send({ type: "error", error: publicErrorMessage(e) });
+        try { if (!res.destroyed) res.end(); } catch (e2) { debug(`[channels/http] 已忽略异常: ${e2 && e2.message ? e2.message : e2}`); }
+      } finally { this._release(); }
+      return true;
+    }
+
+    return false;
+  }
+
+  // ---- 路由域 3: 会话管理 (列表/历史/重命名/删除/重置/中断) ----
+  async _routeSessions(req, res, get, post, reqPath) {
+    if (get && reqPath === "/sessions") {
+      if (!this._requireAuth(req, res)) return true;
+      const list = (this.agent.sessionStore && this.agent.sessionStore.list) ? this.agent.sessionStore.list() : [];
+      this._json(res, 200, { sessions: list });
+      return true;
+    }
+    if (get && /^\/sessions\/[^/]+\/history$/.test(reqPath)) {
+      if (!this._requireAuth(req, res)) return true;
+      const key = decodeURIComponent(reqPath.split("/")[2]);
+      const msgs = this.agent.sessionStore && typeof this.agent.sessionStore.deriveMessages === "function"
+        ? this.agent.sessionStore.deriveMessages(key)
+        : [];
+      this._json(res, 200, { sessionId: key, messages: msgs });
+      return true;
+    }
+    if (post && reqPath === "/sessions/rename") {
+      if (!this._requireAuth(req, res)) return true;
+      // 2026-09-18 修复 (缺陷 #1): 原实现把 _readBody 的【原始字符串】当对象用 —— body.from / body.to
+      //   恒为 undefined, rename 实际收到 (undefined, undefined) 后恒返回 false, 前端
+      //   post("/sessions/rename", {from,to}) 的契约从未生效 (重命名一直失败)。改为解析 JSON body。
+      const data = await this._readJson(req, res);
+      if (data === null) return true;
+      const ok = this.agent.sessionStore && typeof this.agent.sessionStore.rename === "function"
+        ? this.agent.sessionStore.rename(data.from, data.to) : false;
+      this._json(res, ok ? 200 : 404, { ok });
+      return true;
+    }
+    if (post && reqPath === "/sessions/delete") {
+      if (!this._requireAuth(req, res)) return true;
+      // 2026-09-18 修复 (缺陷 #2): 同上 —— 原实现 body.key 恒为 undefined → `|| "default"` 兜底,
+      //   于是"删除某个会话"实际删掉的是 default 主会话 (误删数据)。改为解析 JSON body。
+      const data = await this._readJson(req, res);
+      if (data === null) return true;
+      // 2026-10-03 修复 (P0-2): 前端 delSession 发的是 { sessionKey }, 后端只读 data.key →
+      // 恒 undefined → || "default" 兜底把主会话误删 (9-18 修复只改了后端解析方式,
+      // 前端字段名没对齐, 缺陷原样存活)。现在两侧字段名兼容读取。
+      if (this.agent.sessionStore) this.agent.sessionStore.delete(data.key || data.sessionKey || "default");
+      this._json(res, 200, { ok: true });
+      return true;
+    }
+    if (post && reqPath === "/reset") {
+      if (!this._requireAuth(req, res)) return true;
+      const data = await this._readJson(req, res);
+      if (data === null) return true;
+      this.agent.resetSession(data.sessionId || "default");
+      this._json(res, 200, { ok: true });
+      return true;
+    }
+    if (post && reqPath === "/interrupt") {
+      if (!this._requireAuth(req, res)) return true;
+      const body = await this._readBody(req, res);
+      if (body === null) return true;
+      try {
+        const data = JSON.parse(body || "{}");
+        const sessionId = data.sessionId || "default";
+        // v3.0.1 (P1#3): 按会话中断 —— 并发会话各断各的, 不再全进程一起停
+        if (typeof this.agent.interrupt === "function") this.agent.interrupt(sessionId);
+        this._json(res, 200, { ok: true, interrupted: true, sessionId });
+      } catch (e) {
+        this._fail(res, e);
+      }
+      return true;
+    }
+
+    return false;
+  }
+
+  // ---- 路由域 4: 静态界面 (三态返回: undefined 不匹配 / true / false) ----
+  _routeStatic(req, res, get, reqPath) {
+    if (!get) return undefined;
+
+    // 首页: 服务端注入 window.__PPX_BOOTSTRAP__ (本机回环请求附带 auth token) → 单进程免配置可用
+    if (reqPath === "/" || reqPath === "/index.html") {
+      const html = this.renderIndex(req);
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" });
+      res.end(html !== null ? html : "<!DOCTYPE html><meta charset=utf-8><p>皮皮虾服务已启动, 但 public/index.html 未找到。</p>");
+      return true;
+    }
+    // 通用静态文件服务 (public/ 下任意文件, 含 vendor/ 资源, 防路径穿越)
+    if (!reqPath.startsWith("/api/") && !LEGACY_REST_PATHS.some((p) => reqPath === p)) {
+      return this._serveStatic(res, reqPath);
+    }
+    return undefined;
+  }
+
+  // ---- API 门禁: REST 退役开关 + 鉴权。返回 true = 已写响应 (路由结束), false = 放行到具体 API 路由 ----
+  // channels.http.mcp.legacy_rest = true 时保留旧 /api/* REST 端点 (兼容旧脚本/客户端);
+  // 默认 false: /api/* 返回 410 Gone, 引导使用标准 MCP 端点 /mcp
+  _gateApi(req, res, reqPath) {
+    if (!reqPath.startsWith("/api/")) return false;
+    if (!this.mcpLegacyRest) {
+      this._json(res, 410, { error: "REST /api/* 已退役, 请使用标准 MCP 端点 POST /mcp (channels.http.mcp.legacy_rest=true 可恢复)" });
+      return true;
+    }
+    // /api/bootstrap 例外: 它本身就是"取 token"的入口, 可信本地请求免鉴权放行
+    // (必须用 _isTrustedLocal 而非 _isLoopback —— 否则浏览器里任意网站发来的跨源请求
+    //  源地址同样是 127.0.0.1, 会被误判为本机并拿到 token)
+    const bootstrapLocal = reqPath === "/api/bootstrap" && this._isTrustedLocal(req);
+    if (!bootstrapLocal && !this._requireAuth(req, res)) return true;
+    return false;
+  }
+
+  // API 路由表: 每个 handler 返回 true (已处理)
+  async _apiRoute(req, res, reqPath) {
+    const get = req.method === "GET";
+    // v3.0 (codex 对齐): 命令面板 / 审批流 / 目标看板 / 审查报告 / 权限热更新
+    if (await this._apiV3(req, res, reqPath, get)) return true;
+    switch (reqPath) {
+      // 引导信息 API (前端启动时刷新用): 版本/端口/token(仅回环)/能力开关
+      case "/api/bootstrap":
+        if (!get) return false;
+        this._json(res, 200, this.bootstrapPayload(req), { "Cache-Control": "no-store" });
+        return true;
+      case "/api/traces": {
+        if (!get) return false;
+        const limit = Number((req.url.split("limit=")[1] || "").split("&")[0] || 50);
+        this._json(res, 200, this.agent.traces.read(undefined, limit));
+        return true;
+      }
+      case "/api/stats":
+        if (!get) return false;
+        this._json(res, 200, this.agent.stats ? this.agent.stats() : this.agent.traces.stats());
+        return true;
+      case "/api/memory": {
+        if (!get) return false;
+        const facts = this.agent.facts ? this.agent.facts.list().slice(0, 20).map((f) => ({ content: f.content, score: f.score, type: f.type })) : [];
+        const scenes = this.agent.scenes ? this.agent.scenes.listWithDesc().slice(-10) : [];
+        this._json(res, 200, { facts, scenes });
+        return true;
+      }
+      // 主动任务生成 API (ANS 自主性): 扫描记忆待办/偏好, 返回主动提醒 + 结构化 items (含 id)
+      case "/api/proactive":
+        if (!get) return false;
+        try {
+          const out = await suggestProactive(this.agent);
+          this._json(res, 200, { message: out ? out.text : null, items: out ? out.items : [] });
+        } catch (e) {
+          this._json(res, 200, { message: null, items: [], error: e.message });
+        }
+        return true;
+      // 标记待办完成 (ANS): POST /api/proactive/done { id } → 之后不再主动提醒
+      case "/api/proactive/done": {
+        if (req.method !== "POST") return false;
+        if (!this._requireAuth(req, res)) return true;
+        const body = await this._readBody(req, res);
+        if (body === null) return true;
+        try {
+          const data = JSON.parse(body || "{}");
+          const ok = this.agent.proactiveMarkDone(data.id);
+          this._json(res, ok ? 200 : 404, { ok });
+        } catch (e) {
+          this._fail(res, e);
+        }
+        return true;
+      }
+      // 生命周期状态 API (ANS): 阶段/年龄/进化/繁衍
+      case "/api/lifecycle":
+        if (!get) return false;
+        this._json(res, 200, this.agent.lifecycleStatus ? this.agent.lifecycleStatus() : {});
+        return true;
+
+      // 提供方 API - 模型配置 Web UI 后端
+      // GET 列出 (key 抹掉, 只回 api_key_set) / POST 新增 / PUT 更新 / DELETE 删除
+      case "/api/providers":
+        return this._apiProviders(req, res);
+      // 健康探测 (body: { id }), 复用 LLMClient.health()
+      case "/api/providers/test":
+        if (req.method !== "POST") return false;
+        return this._apiProviderTest(req, res);
+      // 重排 (body: { order: [id1, id2, ...] })
+      case "/api/providers/reorder":
+        if (req.method !== "POST") return false;
+        return this._apiProviderReorder(req, res);
+
+      // 通用设置 API: 用户名 / HTTP 端口 / 安全 / agent 预设
+      case "/api/settings":
+        return this._apiSettings(req, res);
+
+      // 工作区文件树 + 读取 (Web UI 项目文件引用)
+      case "/api/workspace/tree":
+        if (!get) return false;
+        return this._apiWorkspaceTree(res, req);
+      case "/api/workspace/read":
+        if (!get) return false;
+        return this._apiWorkspaceRead(res, req);
+
+      default:
+        return false;
+    }
+  }
+
+  // ---- 静态文件 ----
+  _serveStatic(res, reqPath) {
+    const file = path.resolve(this.publicDir, reqPath.replace(/^\//, ""));
+    if (file.startsWith(this.publicDir + path.sep) && fs.existsSync(file) && fs.statSync(file).isFile()) {
+      const ext = path.extname(file).toLowerCase();
+      const mime = {
+        ".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".mjs": "text/javascript; charset=utf-8",
+        ".css": "text/css; charset=utf-8", ".json": "application/json; charset=utf-8", ".png": "image/png",
+        ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif",
+        ".svg": "image/svg+xml", ".ico": "image/x-icon", ".woff2": "font/woff2", ".map": "application/json",
+      }[ext] || "application/octet-stream";
+      const headers = { "Content-Type": mime };
+      if ([".html", ".js", ".mjs", ".css"].includes(ext)) headers["Cache-Control"] = "no-cache";
+      res.writeHead(200, headers);
+      res.end(fs.readFileSync(file));
+      return true;
+    }
+    res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+    res.end("not found");
+    return true;
+  }
+
+  // ---- v3.0 API (codex 对齐): 命令/审批/看板/审查/权限热更新 ----
+  // 全部端点失败时静默 404 (前端优雅降级隐藏对应能力)
+  async _apiV3(req, res, reqPath, get) {
+    const agent = this.agent;
+    // GET /api/commands — 斜杠命令清单 (claude-code 命令模型)
+    if (get && reqPath === "/api/commands") {
+      const cmds = agent.commands?.list ? agent.commands.list(true) : [];
+      this._json(res, 200, { commands: cmds.map((c) => ({ name: c.name, description: c.description || "", argumentHint: c.argumentHint || "" })) });
+      return true;
+    }
+    // GET /api/approvals/pending — 待审批清单 (codex approval flow)
+    if (get && reqPath === "/api/approvals/pending") {
+      this._json(res, 200, { approvals: agent.pendingApprovals ? agent.pendingApprovals() : [] });
+      return true;
+    }
+    // POST /api/approvals/:id — 审批裁决 { decision: "approve" | "deny" }
+    if (req.method === "POST" && reqPath.startsWith("/api/approvals/")) {
+      const id = reqPath.slice("/api/approvals/".length);
+      const body = await this._readBody(req, res);
+      if (body === null) return true;
+      let decision = "deny";
+      try { decision = JSON.parse(body || "{}").decision || "deny"; } catch (e) { debug(`[channels/http] 已忽略异常: ${e && e.message ? e.message : e}`); }
+      const ok = agent.resolveApproval ? agent.resolveApproval(id, decision) : false;
+      this._json(res, ok ? 200 : 404, { ok });
+      return true;
+    }
+    // GET /api/goalboard — 目标看板 (OMH goal board)
+    if (get && reqPath === "/api/goalboard") {
+      const board = agent.goalBoard;
+      if (!board) { this._json(res, 200, { goals: [] }); return true; }
+      const goals = board.list ? board.list() : [];
+      this._json(res, 200, { goals, text: board.render ? board.render() : "" });
+      return true;
+    }
+    // GET /api/review/latest — 最近一次审查报告 (OCR 分级流水线)
+    if (get && reqPath === "/api/review/latest") {
+      this._json(res, 200, agent._lastReview || { issues: [], report: null });
+      return true;
+    }
+    // POST /api/permissions — 权限热更新 { approvalMode?, sandbox?, networkAccess? }
+    if (req.method === "POST" && reqPath === "/api/permissions") {
+      const body = await this._readBody(req, res);
+      if (body === null) return true;
+      if (!agent.permissions) { this._json(res, 200, { ok: false, reason: "权限引擎未装配" }); return true; }
+      let cfg = {};
+      try { cfg = JSON.parse(body || "{}"); } catch (e) { debug(`[channels/http] 已忽略异常: ${e && e.message ? e.message : e}`); }
+      if (cfg.approvalMode) agent.permissions.approvalMode = cfg.approvalMode;
+      if (cfg.sandbox) agent.permissions.sandbox = cfg.sandbox;
+      if (cfg.networkAccess != null) agent.permissions.networkAccess = !!cfg.networkAccess;
+      this._json(res, 200, { ok: true, approvalMode: agent.permissions.approvalMode, sandbox: agent.permissions.sandbox });
+      return true;
+    }
+    return false;
+  }
+
+  // ---- 提供方 CRUD ----
+  async _apiProviders(req, res) {
+    if (!this._requireAuth(req, res)) return true;
+    const method = req.method;
+    if (method === "GET") {
+      const providers = listProviders(this.agent.root);
+      const defaultId = providers[0] ? providers[0].id : null;
+      this._json(res, 200, { providers, default_id: defaultId });
+      return true;
+    }
+    if (!["POST", "PUT", "DELETE"].includes(method)) return false;
+    const body = await this._readBody(req, res);
+    if (body === null) return true;
+    try {
+      const data = JSON.parse(body || "{}");
+      if (method === "POST") {
+        const created = addProvider(this.agent.root, data.provider || data);
+        this.agent.reloadProviders(); // 热重载 (新增默认时让 agent 立即可用)
+        this._json(res, 200, { ok: true, provider: created });
+        return true;
+      }
+      if (!data.id) throw new Error("缺少 id");
+      if (method === "PUT") {
+        const updated = updateProvider(this.agent.root, data.id, data.patch || {});
+        this.agent.reloadProviders();
+        this._json(res, 200, { ok: true, provider: updated });
+        return true;
+      }
+      const removed = removeProvider(this.agent.root, data.id);
+      this.agent.reloadProviders();
+      this._json(res, 200, { ok: true, provider: removed });
+      return true;
+    } catch (e) {
+      // 不存在/缺参 → 404, 其余校验失败 → 400 (保持原语义)
+      this._fail(res, e, /不存在|缺少/.test(e.message) ? 404 : 400);
+      return true;
+    }
+  }
+
+  // 提供方健康探测: 优先复用 agent 已有客户端 (含测试注入的 stub), 避免对磁盘配置的真实网络探测
+  async _apiProviderTest(req, res) {
+    if (!this._requireAuth(req, res)) return true;
+    const body = await this._readBody(req, res);
+    if (body === null) return true;
+    try {
+      const data = JSON.parse(body || "{}");
+      if (!data.id) throw new Error("缺少 id");
+      // 兜底顺序: allProviders → agent.llm → 磁盘配置临时构造
+      let client = (this.agent.allProviders || []).find((c) => c.providerId === data.id);
+      let fromCache = !!client;
+      if (!client && this.agent.llm && this.agent.llm.providerId === data.id) {
+        client = this.agent.llm;
+        fromCache = true;
+      }
+      if (!client) {
+        const { providers } = readConfig(this.agent.root);
+        const p = providers.find((x) => x.id === data.id);
+        if (!p) throw new Error("提供方不存在");
+        // LLM 客户端按需加载 (避免把网络栈带进未使用该端点的进程)
+        const { LLMClient } = await import("../llm/client.js");
+        client = new LLMClient(p);
+      }
+      const healthy = await client.health();
+      const detail = healthy
+        ? (fromCache ? "复用 agent 客户端, 探测通过" : "API 端点可达")
+        : "探测失败, 请检查 key/base_url";
+      this._json(res, 200, { ok: true, healthy, detail, source: fromCache ? "agent-cache" : "disk-config" });
+    } catch (e) {
+      this._fail(res, e);
+    }
+    return true;
+  }
+
+  async _apiProviderReorder(req, res) {
+    if (!this._requireAuth(req, res)) return true;
+    const body = await this._readBody(req, res);
+    if (body === null) return true;
+    try {
+      const data = JSON.parse(body || "{}");
+      const providers = reorderProviders(this.agent.root, data.order || []);
+      this.agent.reloadProviders();
+      this._json(res, 200, { ok: true, providers });
+    } catch (e) {
+      this._fail(res, e);
+    }
+    return true;
+  }
+
+  // ---- 通用设置 ----
+  async _apiSettings(req, res) {
+    if (!this._requireAuth(req, res)) return true;
+    if (req.method === "GET") {
+      this._json(res, 200, { settings: getSettings(this.agent.root) });
+      return true;
+    }
+    if (req.method !== "PUT") return false;
+    const body = await this._readBody(req, res);
+    if (body === null) return true;
+    try {
+      const data = JSON.parse(body || "{}");
+      const settings = updateSettings(this.agent.root, data.patch || {});
+      this.agent.reloadSettings(); // 热重载: 用户名/安全/agent 预设立即生效
+      this._json(res, 200, { ok: true, settings });
+    } catch (e) {
+      this._fail(res, e);
+    }
+    return true;
+  }
+
+  // ---- 工作区 ----
+  _apiWorkspaceTree(res, req) {
+    try {
+      const u = new URL(req.url, "http://127.0.0.1");
+      const wsRoot = path.resolve(this.agent.root);
+      const { tree, truncated, maxDepth, baseDir } = buildTree(wsRoot, {
+        root: u.searchParams.get("root") || "",
+        maxDepth: u.searchParams.get("maxDepth") || 3,
+      });
+      this._json(res, 200, {
+        ok: true, root: wsRoot, dir: baseDir, maxDepth, truncated,
+        tree: tree || { name: "", path: "", type: "dir", children: [] },
+      });
+    } catch (e) {
+      this._fail(res, e);
+    }
+    return true;
+  }
+
+  _apiWorkspaceRead(res, req) {
+    try {
+      const u = new URL(req.url, "http://127.0.0.1");
+      const out = readWorkspaceFile(path.resolve(this.agent.root), u.searchParams.get("path") || "");
+      this._json(res, 200, { ok: true, ...out });
+    } catch (e) {
+      this._fail(res, e);
+    }
+    return true;
+  }
+
+  // 结构化事件广播 (EQ 订阅回调): 尽力而为, 任何异常不得影响事件流
+  _broadcastEvent(ev) {
+    if (!this._sseClients.size) return;
+    let frame;
+    try { frame = `data: ${JSON.stringify({ type: "event", event: ev })}\n\n`; } catch { return; }
+    for (const r of [...this._sseClients]) {
+      try { if (!r.writableEnded) r.write(frame); else this._sseClients.delete(r); }
+      catch { this._sseClients.delete(r); }
+    }
+  }
+
+  // ---- 主动提醒 SSE (2026-10-03) ----
+  // GET /events: 建立 text/event-stream 长连接。鉴权兼容两种方式:
+  //   ① Authorization: Bearer 头 (fetch/测试场景)
+  //   ② ?token= 查询参数 (EventSource 无法自定义请求头; 本机服务 + safeEqual 常量时间比较)
+  _handleEvents(req, res) {
+    if (!this._authed(req, res)) {
+      let q = null;
+      try { q = new URL(req.url || "/", "http://x").searchParams.get("token"); } catch { q = null; }
+      if (!q || !safeEqual(q, this.authToken)) { this._json(res, 401, { error: "unauthorized" }); return; }
+    }
+    // 先准入判定完再 writeHead (与 SSE 对话端点同一纪律: 拒绝不能返 200)
+    res.writeHead(200, SSE_HEADERS);
+    res.write("retry: 5000\n\n");
+    this._sseClients.add(res);
+    debug(`[channels/http] SSE 提醒客户端接入 (在线=${this._sseClients.size})`);
+    req.on("close", () => {
+      this._sseClients.delete(res);
+      if (!this._sseClients.size && this._sseBeat) { clearInterval(this._sseBeat); this._sseBeat = null; }
+    });
+    if (!this._sseBeat) {
+      this._sseBeat = setInterval(() => {
+        for (const r of [...this._sseClients]) {
+          try { if (!r.writableEnded) r.write(": ping\n\n"); else this._sseClients.delete(r); }
+          catch { this._sseClients.delete(r); }
+        }
+        if (!this._sseClients.size && this._sseBeat) { clearInterval(this._sseBeat); this._sseBeat = null; }
+      }, 25000);
+      this._sseBeat.unref?.(); // 不阻止进程退出
+    }
+  }
+
+  async send(to, text) {
+    // 2026-10-03 修复: 原为 no-op (`return text`), server.js 主动提醒 ticker 调
+    // manager.broadcast(payload.text) 时 Web UI 永远收不到。升级为 SSE 广播:
+    // 所有 GET /events 在线客户端实时收到 {type:"reminder", text}。无订阅者时静默。
+    if (this._sseClients.size) {
+      const frame = `data: ${JSON.stringify({ type: "reminder", text })}\n\n`;
+      for (const r of [...this._sseClients]) {
+        try { if (!r.writableEnded) r.write(frame); else this._sseClients.delete(r); }
+        catch { this._sseClients.delete(r); }
+      }
+    }
+    return text; // 保持 Channel 契约: 返回投递文本
+  }
+
+  // 连通性测试: 用独立实例起临时 server 验证端口可绑定
+  async test() {
+    try {
+      await this.connect();
+      await this.disconnect();
+      return { ok: true, detail: `HTTP 通道可启动: http://${this.host}:${this.port}` };
+    } catch (e) {
+      return { ok: false, detail: e.message };
+    }
+  }
+
+  async disconnect() {
+    if (this._unsubBus) { try { this._unsubBus(); } catch { /* 重复退订无副作用 */ } this._unsubBus = null; }
+    if (this._sseBeat) { clearInterval(this._sseBeat); this._sseBeat = null; }
+    for (const r of [...this._sseClients]) { try { r.end(); } catch { /* 客户端已断 */ } }
+    this._sseClients.clear();
+    if (this.server) { await new Promise((r) => this.server.close(r)); this.server = null; }
+    this.connected = false;
+  }
+}