hostpad 0.2.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # hostpad
 
-HostPad 的 Mac 端伴侣：**MCP 服务器 + iPhone 加密同步桥**，让 AI agent（ZCode / Claude 等）直接在你的 iPhone 上开发、调试、迭代 iOS 工具（HTML/JS 小工具，跑在 [HostPad App] 里）。
+HostPad 的 Mac 端伴侣：**MCP 服务器 + iPhone 加密同步桥**，让 AI agent（ZCode / Claude 等）直接在你的 iPhone 上开发、调试、迭代 HostPad 工具（**跑在 JavaScriptCore 的 JS 程序 + 宿主 API**，UI 经 `host.ui.render()` 渲染 HTML 片段——**不是网页，entry 必须是 main.js 这类 JS 入口**。能力面详见 `get_dev_guide` 工具）。
 
 单进程双面：
 
@@ -27,13 +27,14 @@ npx hostpad
 }
 ```
 
-## MCP 工具（9 个）
+## MCP 工具（10 个）
 
 | 工具 | 作用 |
 |------|------|
 | `list_devices` | 列出连接的 iPhone（配对状态 / 设备名 / 地址） |
 | `pair` | 用手机屏显的 6 位配对码确认配对 |
-| `create_tool` / `update_tool` / `list_tools` / `delete_tool` | 管理工具（update 为覆盖合并：只传改动文件，推送即热重载） |
+| `get_dev_guide` | **写工具前先读**：运行时能力面（能/不能用清单、host API、UI/交互模型、最小模板） |
+| `create_tool` / `update_tool` / `list_tools` / `delete_tool` | 管理工具（update 为覆盖合并：只传改动文件，推送即热重载）；list_tools 返回 toolsDir，直接落盘到 `<toolsDir>/<toolId>/` 也会自动推送 |
 | `reload` | 重推工具（激活） |
 | `get_logs` | 读手机回流的日志环形缓冲（工具 console.* 与系统事件，游标分页） |
 | `rpc_call` | 调用手机上运行中工具的 `onMessage` 处理器，返回值回传 |
@@ -61,4 +62,10 @@ npx hostpad [--port 8787] [--tools ./tools] [--insecure] [--pair-code 123456] [-
 - Node ≥ 18（零第三方依赖之外仅 `ws`）
 - iPhone 端需 HostPad App
 
+## 联调提示
+
+- MCP stdio 走标准管道，单行长度无限制（130KB+ 的 `create_tool` 实测通过）。
+  **不要用 FIFO 手工模拟 stdin**：macOS kqueue 在 FIFO 上对长写入不再唤醒读端，
+  大 payload 会假性"卡死"，这不是本服务的限制。
+
 License: 目前未授权发布（UNLICENSED），供 HostPad 项目配套使用。

package/bin/hostpad.js

@@ -6,6 +6,8 @@ const os = require('node:os');
 const readline = require('node:readline');
 const { createBridge } = require('../lib/bridge.js');
 const { createMcpServer } = require('../lib/mcp.js');
+const { startDiscovery } = require('../lib/discovery.js');
+const { GUIDE } = require('../lib/guide.js');
 
 // ---------- 参数 ----------
 function arg(name, def) {
@@ -14,8 +16,12 @@ function arg(name, def) {
     ? process.argv[i + 1] : def;
 }
 const PORT = parseInt(arg('port', '8787'), 10);
-const TOOLS = arg('tools', './tools');
-const STATE = arg('state', null);
+// 默认落 ~/.hostpad/（用户级固定目录）：相对 CWD 的 ./tools 换目录启动就「工具全没」，
+// npx 缓存包内的 state 清缓存即丢配对 token
+const HOSTPAD_HOME = require('node:path').join(os.homedir(), '.hostpad');
+const TOOLS = arg('tools', require('node:path').join(HOSTPAD_HOME, 'tools'));
+const LEGACY_STATE = require('node:path').join(__dirname, '..', '.hostpad-state.json');
+const STATE = arg('state', require('node:path').join(HOSTPAD_HOME, 'state.json'));
 const INSECURE = process.argv.includes('--insecure');
 const PAIR_CODE = arg('pair-code', null);
 const AUTO_CONFIRM = parseInt(arg('auto-confirm', '0'), 10);
@@ -23,10 +29,10 @@ const AUTO_CONFIRM = parseInt(arg('auto-confirm', '0'), 10);
 if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log(`hostpad — HostPad 的 MCP 服务器 + 手机同步桥
 
-用法：npx hostpad [--port 8787] [--tools ./tools] [--insecure] [--pair-code 123456] [--auto-confirm 800]
+用法：npx hostpad [--port 8787] [--tools <dir>] [--insecure] [--pair-code 123456] [--auto-confirm 800]
 
   --port        WebSocket 桥端口（默认 8787）
-  --tools       工具目录（默认 ./tools）
+  --tools       工具目录（默认 ~/.hostpad/tools；直接落盘到此目录会自动推送）
   --insecure    明文模式（本地快迭代/soak 用；默认加密 + 配对）
   --pair-code   固定配对码（自动化用）
   --auto-confirm <ms>  出现待配对设备后 ms 毫秒自动确认（需 --pair-code；自动化用）
@@ -39,10 +45,17 @@ MCP 客户端（ZCode/Claude 等）配置：
 }
 
 // ---------- 桥 ----------
+require('node:fs').mkdirSync(HOSTPAD_HOME, { recursive: true });
+// 一次性迁移：旧版本 state 落在 npm 包内，清 npx 缓存会丢全部配对 token
+if (STATE !== LEGACY_STATE && !require('node:fs').existsSync(STATE)
+    && require('node:fs').existsSync(LEGACY_STATE)) {
+  require('node:fs').copyFileSync(LEGACY_STATE, STATE);
+  console.error('[hostpad] 已迁移配对 state →', STATE);
+}
 const bridge = createBridge({
   port: PORT,
   toolsDir: TOOLS,
-  statePath: STATE ?? require('node:path').join(__dirname, '..', '.hostpad-state.json'),
+  statePath: STATE,
   secure: !INSECURE,
   pairCode: PAIR_CODE,
   log: (...a) => console.error('[bridge]', ...a), // stdout 留给 MCP 协议
@@ -83,18 +96,26 @@ const tools = [
     },
     handler: async ({ code }) => bridge.pairConfirm(String(code)),
   },
+  {
+    name: 'get_dev_guide',
+    description: '【写工具前先读】HostPad 工具运行时能力面：能/不能用清单、host API、UI/交互模型、权限与资源限制、最小模板。工具跑在 JavaScriptCore（非网页）',
+    inputSchema: { type: 'object', properties: {} },
+    handler: async () => ({ guide: GUIDE }),
+  },
   {
     name: 'create_tool',
-    description: '创建工具并推送到手机（推送即激活）。manifest: {id,name,version,entry,permissions?}',
+    description: '创建工具并推送到手机（推送即激活）。工具跑在 JavaScriptCore：entry 必须是 JS 入口文件（如 main.js，顶层执行，可选 main()），不能是 HTML；无 DOM/window/定时器/fetch；UI 用 host.ui.render({title, body:HTML片段})，交互用 data-hostpad 属性 + host.ui.onMessage；网络 host.http.request 需 permissions:["http"]。完整指南调 get_dev_guide',
     inputSchema: {
       type: 'object',
       properties: {
         manifest: {
           type: 'object',
+          description: '工具清单；entry 见 get_dev_guide',
           properties: {
             id: { type: 'string' }, name: { type: 'string' },
-            version: { type: 'string' }, entry: { type: 'string' },
-            permissions: { type: 'array', items: { type: 'string' } },
+            version: { type: 'string' },
+            entry: { type: 'string', description: 'JS 入口文件（如 main.js），不能是 HTML/CSS' },
+            permissions: { type: 'array', items: { type: 'string' }, description: '可选：http / clipboard / notifications' },
           },
           required: ['id', 'name', 'version', 'entry'],
         },
@@ -109,7 +130,7 @@ const tools = [
   },
   {
     name: 'update_tool',
-    description: '更新工具并推送（覆盖合并：只传要改的文件）。可只改 manifest 或只改 files',
+    description: '更新工具并推送（覆盖合并：只传要改的文件）。可只改 manifest 或只改 files。entry 仍须为 JS 入口文件（契约见 get_dev_guide）',
     inputSchema: {
       type: 'object',
       properties: {
@@ -126,9 +147,12 @@ const tools = [
   },
   {
     name: 'list_tools',
-    description: '列出 Mac 侧工具目录中的全部工具',
+    description: '列出 Mac 侧工具目录中的全部工具（返回含 toolsDir：直接把文件落盘到 <toolsDir>/<toolId>/ 也会触发自动推送）',
     inputSchema: { type: 'object', properties: {} },
-    handler: async () => ({ tools: bridge.listTools() }),
+    handler: async () => ({
+      toolsDir: bridge.store.dir,
+      tools: bridge.listTools(),
+    }),
   },
   {
     name: 'delete_tool',
@@ -205,4 +229,6 @@ bridge.start().then(() => {
   for (const ip of nets) console.error(`[hostpad] 手机连接：ws://${ip}:${bridge.port}`);
   console.error(`[hostpad] 工具目录：${require('node:path').resolve(TOOLS)}`);
   console.error('[hostpad] MCP stdio 就绪（agent 请经 stdin/stdout 对话）');
+  // P1：局域网自动发现——UDP 广播 ws 地址（8792，每 2s），手机端「发现服务器」即收即连
+  startDiscovery({ port: bridge.port, insecure: INSECURE });
 });

package/lib/bridge.js

@@ -20,13 +20,14 @@ function createBridge({
   pairCode = null,
   maxPairFails = 5,
   lockMs = 60_000,
+  codeTtlMs = 60_000,
   logsCap = 1000,
   watch = true,
   log = console.log,
 } = {}) {
   const store = createToolStore(toolsDir);
   const ratelimiter = createRateLimiter({ maxFails: maxPairFails, lockMs });
-  const codeStore = createCodeStore({ ttl: 60_000 });
+  const codeStore = createCodeStore({ ttl: codeTtlMs });
 
   // ---------- 设备 token 状态（兼容 M1 字符串数组） ----------
   function loadState() {
@@ -100,13 +101,24 @@ function createBridge({
 
   // ---------- 配对 ----------
 
+  /** 发配对挑战；TTL 前 5s 自动换新码重发——输错/超时后手机屏上永远是有效码 */
   function startPairing(conn) {
+    if (conn.pairTimer) { clearTimeout(conn.pairTimer); conn.pairTimer = null; }
     conn.pair = null;
     const pairId = crypto.randomUUID();
     const code = codeStore.issue(pairId, pairCode);
     conn.pair = { pairId };
     sendTo(conn, { type: 'pair-challenge', pairId, code });
-    log(`[pair] 设备 ${conn.device?.name ?? conn.ip} 显示配对码（60s 有效）`);
+    conn.pairTimer = setTimeout(() => {
+      conn.pairTimer = null;
+      if (conn.pair?.pairId === pairId) startPairing(conn);
+    }, Math.max(codeTtlMs - 5_000, Math.floor(codeTtlMs / 2)));
+    log(`[pair] 设备 ${conn.device?.name ?? conn.ip} 显示配对码（${codeTtlMs / 1000}s 内有效，过期自动换新）`);
+  }
+
+  function stopPairing(conn) {
+    if (conn.pairTimer) { clearTimeout(conn.pairTimer); conn.pairTimer = null; }
+    conn.pair = null;
   }
 
   /** MCP pair(code)：对任一待配对连接校验配对码；错误计失败，达到阈值锁定 IP */
@@ -115,6 +127,7 @@ function createBridge({
       for (const conn of conns) {
         if (!conn.pair || conn.authed) continue;
         if (codeStore.verify(conn.pair.pairId, code)) {
+          const pairId = conn.pair.pairId;
           ratelimiter.reset(conn.ip);
           const token = crypto.randomUUID();
           tokens.push({
@@ -125,22 +138,23 @@ function createBridge({
           });
           saveState();
           conn.authed = true;
-          const pairId = conn.pair.pairId;
-          conn.pair = null;
+          stopPairing(conn);
           sendTo(conn, { type: 'pair-granted', pairId, token });
           log(`[pair] ✓ 配对成功 ${conn.device?.name ?? conn.ip}`);
           pushAll(conn, 'initial');
           resolve({ ok: true, device: conn.device });
           return;
         }
-        // 该连接的码被消费但不匹配：清掉待配对态，手机重新 auth 可再触发
-        conn.pair = null;
+        // 该连接的码被消费但不匹配：立即换新码重发（手机 UI 自动刷新），
+        // 失败计限速；达到阈值锁定 IP 并断开
         ratelimiter.fail(conn.ip);
         if (ratelimiter.isLocked(conn.ip)) {
+          stopPairing(conn);
           conn.ws.close(4003, 'locked');
           reject(new Error('IP 已锁定（配对失败次数过多），60s 后自动解除'));
           return;
         }
+        startPairing(conn);
       }
       reject(new Error('配对码不符或已过期'));
     });
@@ -292,6 +306,7 @@ function createBridge({
     });
     ws.on('close', () => {
       conns.delete(conn);
+      stopPairing(conn);
       for (const [rpcId, p] of pendingRpc) {
         if (p.conn === conn) { clearTimeout(p.timer); p.reject(new Error('设备断开')); pendingRpc.delete(rpcId); }
       }

package/lib/discovery.js

@@ -0,0 +1,107 @@
+// P1：服务器自动发现（发送侧）——UDP 广播，零依赖（仅 node:dgram / node:os）
+//
+// agent 进程启动后每 2s 向 255.255.255.255:8792 广播一行 UTF-8 JSON：
+//   {"v":1,"type":"hostpad-discovery","proto":"1.3","port":<ws端口>,"name":"<电脑名>",
+//    "insecure":<bool>,"ip":"<本机非internal IPv4>"}
+// 协议要点：iOS Network 框架收 UDP 广播时 remoteEndpoint 常退化为广播地址本身（拿不到
+// 发送方单播 IP），故报文显式携带 ip 字段为准——App 端 ws 地址 = ws://<ip>:<port>。
+// 多网卡：每个非 internal IPv4 地址各广播一条（同名多 IP 在 App 端各自成候选，去重键 ip:port）。
+// 生命周期：socket 与定时器均 unref，不阻止进程退出；stop() 显式收尾（幂等，测试用）。
+'use strict';
+const dgram = require('node:dgram');
+const os = require('node:os');
+
+const DISCOVERY_PORT = 8792;
+const BROADCAST_ADDR = '255.255.255.255';
+const INTERVAL_MS = 2000;
+
+/** 枚举本机可广播 IPv4（os.networkInterfaces() 里 family=IPv4 且非 internal；去重） */
+function localIPv4s(interfaces = os.networkInterfaces()) {
+  const out = [];
+  for (const addrs of Object.values(interfaces ?? {})) {
+    for (const n of addrs ?? []) {
+      if (n && (n.family === 'IPv4' || n.family === 4) && !n.internal) out.push(n.address);
+    }
+  }
+  return [...new Set(out)];
+}
+
+/** 纯函数：要广播的 JSON 文本数组（一网卡一包；无可用网卡 → []，不抛错） */
+function buildPackets(port, insecure, name, interfaces = os.networkInterfaces()) {
+  return localIPv4s(interfaces).map((ip) => JSON.stringify({
+    v: 1,
+    type: 'hostpad-discovery',
+    proto: '1.3',
+    port,
+    name,
+    insecure: Boolean(insecure),
+    ip,
+  }));
+}
+
+function createDiscovery({
+  port,
+  insecure = false,
+  name = os.hostname(),
+  broadcast = true, // 测试旗标：false 时单播到 target（回环收不到广播）
+  target = BROADCAST_ADDR,
+  discoveryPort = DISCOVERY_PORT,
+  intervalMs = INTERVAL_MS,
+  log = console.error, // 与 bin 口径一致：诊断走 stderr，stdout 留给 MCP 协议
+} = {}) {
+  let socket = null;
+  let timer = null;
+  let stopped = false;
+  let logged = false;
+
+  function failOnce(stage, err) {
+    if (logged) return; // 协议口径：错误静默，只记一次
+    logged = true;
+    log(`[discovery] ${stage}失败：${err?.message ?? err}（发现广播已停）`);
+  }
+
+  function announce() {
+    if (!socket || stopped) return;
+    for (const packet of buildPackets(port, insecure, name)) {
+      socket.send(packet, discoveryPort, target, (err) => { if (err) failOnce('send', err); });
+    }
+  }
+
+  function start() {
+    socket = dgram.createSocket('udp4');
+    socket.on('error', (err) => { failOnce('socket', err); stop(); });
+    socket.bind(() => { // 随机本地口发送；bind 后再设 SO_BROADCAST 最稳妥
+      if (stopped) return;
+      if (broadcast) {
+        try { socket.setBroadcast(true); } catch (err) { failOnce('setBroadcast', err); }
+      }
+      announce(); // 启动即发一包，不等第一个 interval
+    });
+    socket.unref();
+    timer = setInterval(announce, intervalMs);
+    timer.unref();
+    return api;
+  }
+
+  function stop() {
+    stopped = true;
+    if (timer) { clearInterval(timer); timer = null; }
+    if (socket) { try { socket.close(); } catch { /* 已关 */ } socket = null; }
+  }
+
+  const api = { start, stop };
+  return api;
+}
+
+// ---- 模块面：单例接线（bin/server.js 启动处调用；测试里 stop() 收尾） ----
+let active = null;
+function startDiscovery(opts = {}) {
+  stop();
+  active = createDiscovery(opts).start();
+  return active;
+}
+function stop() {
+  if (active) { active.stop(); active = null; }
+}
+
+module.exports = { startDiscovery, stop, buildPackets, localIPv4s, DISCOVERY_PORT, INTERVAL_MS };

package/lib/guide.js

@@ -0,0 +1,100 @@
+// 运行时能力面指南（MCP get_dev_guide 返回体）。
+// 写给 AI agent：第一句话先纠正「网页 App」心智——工具是 JavaScriptCore 程序，
+// 不是 index.html。此文件与 docs/manifest.md 同源，改一处记得同步另一处。
+'use strict';
+
+const FENCE = '```';
+const GUIDE = `# HostPad 工具开发指南
+
+## 一句话心智
+
+工具是**跑在 JavaScriptCore 的 JS 程序**，不是网页：没有 window/DOM/定时器/fetch。
+manifest.entry 必须是 JS 入口文件（如 main.js，顶层执行，可选定义 main()）。
+UI 通过 host.ui.render() 输出 HTML 片段（白名单净化后进 WebView 壳）。
+
+## 不能用（会 ReferenceError 或静默失败）
+
+- window / document / navigator 及一切 DOM API（querySelector、addEventListener…）
+- getUserMedia / Canvas / Audio（无媒体面，相机类工具目前做不了）
+- setTimeout / setInterval / requestAnimationFrame（一个都没有；异步只能靠
+  host.http/notify 的回调、host.ui.onMessage 事件、挂件 refreshAfterMinutes）
+- fetch / XMLHttpRequest / WebSocket（用 host.http.request，回调式）
+- localStorage / sessionStorage（用 host.kv）
+- atob / btoa / TextEncoder / TextDecoder（JSCore 不带；base64 需自带实现）
+- import / require / <script src>（无模块系统；多文件用 host.fs.read() 读进来自己 eval）
+- HTML/CSS 文件作为 entry 或被自动加载（style.css 没人加载；
+  样式写进 render 片段的 <style> 或元素 style 属性）
+
+## host API（v0.4）
+
+${FENCE}js
+host.env                                  // { pushId, toolId, version, permissions }
+host.console.log/warn/error(...)          // 回流 Mac 端 get_logs
+host.ui.render({ title, body })           // body = HTML 片段（见下方净化规则）
+host.ui.onMessage(fn)                     // fn({ name, values })；返回值经 rpc_call 回传
+host.ui.openURL(url, { inApp = true })    // 免权限；仅 http/https
+host.ui.snapshot(spec)                    // 桌面挂件快照（entries/timer/refreshAfterMinutes）
+host.kv.get/set/remove/keys/clear         // 键值存储（跨启动持久）
+host.fs.read/write/list/delete/exists     // 工具专属文件沙盒（UTF-8 文本）
+host.db.exec/query(sql, params)           // SQLite（与 kv 同库）
+host.http.request(url, options, cb)       // 需 permissions: ["http"]
+                                          // options: { method, headers, body, timeoutMs(≤120000) }
+                                          // cb(err, res)，res = { status, headers, body }
+host.clipboard.setText(text)              // 需 permissions: ["clipboard"]（只写）
+host.notify({ title, body }, cb?)         // 需 permissions: ["notifications"]
+host.share(text)                          // 系统分享面板；免权限
+${FENCE}
+
+## UI 片段与交互（关键差异）
+
+render 的 body 经白名单净化：h1-h6/p/div/span/表格/a/button/img/input/select/
+textarea/form/style 等 40 个标签放行；script/iframe/object/embed 连内容删除；
+一切 on* 事件属性剥除。**交互唯一通道是 data-hostpad 属性**：
+
+${FENCE}html
+<form>
+  <input name="repo" value="apple/swift">
+  <button data-hostpad='{"name":"load"}'>加载</button>
+</form>
+${FENCE}
+点击时壳自动收集作用域内（最近 form，否则整个 body）带 name 的输入值，
+host.ui.onMessage 收到 { name: "load", values: { repo: "apple/swift" } }。
+注意 img 的 data: src 会被剥（base64 内联图不可用，只能 http(s) 远程图）。
+
+## 权限模型
+
+manifest.permissions 声明 "逃出沙盒" 的能力：http / clipboard / notifications。
+存储（kv/fs/db）不设权限（沙盒即边界）；share/openURL 用户可见、免声明。
+
+## 资源限制
+
+- 入口执行与每次消息处理各有 5 秒看门狗（超时隔离）
+- 内存预算约 50MB（相对工具启动时的进程增量）
+- 大数据建议边算边丢；base64 大块文本尤其吃亏
+
+## 最小可运行模板（main.js）
+
+${FENCE}js
+host.ui.render({
+  title: 'Hello',
+  body: '<p id="out">已运行 ' + host.env.version + '</p>' +
+        '<button data-hostpad="ping">点我</button>',
+});
+host.ui.onMessage(function (msg) {
+  if (msg.name === 'ping') {
+    host.ui.render({ title: 'Hello', body: '<p>pong</p>' });
+    return { ok: true };
+  }
+});
+${FENCE}
+
+## 两种部署路径
+
+1. MCP：create_tool / update_tool（推送即热加载激活）
+2. 落盘：直接把 {manifest.json, main.js, …} 写进工具目录（list_tools 返回 toolsDir），
+   fs.watch 检测到变化后约 200ms 自动推送。
+   不要经 FIFO 手工写 stdin 测 MCP——stdio 是标准管道，行长无限制；
+   FIFO 上大 payload 的「卡死」是 macOS kqueue 平台行为，不是本服务限制。
+`;
+
+module.exports = { GUIDE };

package/lib/ratelimit.js

@@ -38,8 +38,11 @@ function createCodeStore({ ttl = 60_000, now = Date.now } = {}) {
   const codes = new Map(); // pairId -> { code, expiresAt }
   return {
     issue(pairId, fixedCode) {
+      // 配对挑战会周期性重发新码，顺带清掉过期条目防缓慢堆积
+      const nowT = now();
+      for (const [k, v] of codes) if (nowT > v.expiresAt) codes.delete(k);
       const code = fixedCode || String(Math.floor(100000 + Math.random() * 900000));
-      codes.set(pairId, { code, expiresAt: now() + ttl });
+      codes.set(pairId, { code, expiresAt: nowT + ttl });
       return code;
     },
     verify(pairId, code) {

package/lib/tools.js

@@ -7,12 +7,24 @@ const crypto = require('node:crypto');
 
 const ID_RE = /^[A-Za-z0-9._-]+$/;
 
+// entry 是 JavaScriptCore 的 JS 入口（不是网页文件）——HTML 当 entry 是最高频接入错误，
+// 在落盘前拒收并把正确心智写进错误消息
+const ENTRY_JS_RE = /\.m?js$/i;
+
 function assertManifest(m) {
   if (!m || typeof m !== 'object') throw new Error('manifest 必须是对象');
   for (const key of ['id', 'name', 'version', 'entry']) {
     if (typeof m[key] !== 'string' || !m[key]) throw new Error(`manifest 缺字段: ${key}`);
   }
   if (!ID_RE.test(m.id)) throw new Error(`manifest.id 非法: ${m.id}`);
+  if (/\.(html?|css)$/i.test(m.entry) || /^index\.html$/i.test(m.entry)) {
+    throw new Error(
+      `manifest.entry 不能是 ${m.entry}：工具跑在 JavaScriptCore（无浏览器/DOM），entry 必须是 JS 入口文件（如 main.js，顶层执行，可选定义 main()）。` +
+      'UI 用 host.ui.render({ title, body: "HTML 片段" }) 输出，交互用 data-hostpad 属性 + host.ui.onMessage。完整指南：get_dev_guide');
+  }
+  if (!ENTRY_JS_RE.test(m.entry)) {
+    throw new Error(`manifest.entry 应为 JS 入口文件（如 main.js），当前: ${m.entry}`);
+  }
 }
 
 function assertFilePath(p) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hostpad",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "HostPad 的 MCP 服务器 + iPhone 同步桥：AI agent 经 MCP 管理与调试 iOS 工具（写→推→读日志闭环）",
   "license": "UNLICENSED",
   "bin": {

package/server.js

@@ -13,6 +13,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const readline = require('node:readline');
 const { createBridge } = require('./lib/bridge.js');
+const { startDiscovery } = require('./lib/discovery.js');
 
 const argv = process.argv.slice(2);
 function arg(name, def) {
@@ -63,6 +64,8 @@ if (PAIRING && AUTO_CONFIRM_MS > 0 && FIXED_CODE) {
 }
 
 bridge.start().then(() => {
+  // P1：局域网自动发现广播（开发态默认明文，--pairing 即加密口径——insecure 按实际模式标注）
+  startDiscovery({ port: PORT, insecure: !PAIRING });
   console.log(`[agent] listening ws://0.0.0.0:${bridge.port}`);
   console.log('[agent] watching for changes…（改 tools/ 下任意文件即热推送）');
   if (SOAK_N > 0) runSoak().catch((e) => { console.log('[soak] error', e); process.exit(2); });