weacpx 0.3.1 → 0.3.2

package/README.md

@@ -11,21 +11,21 @@
 
 ## 这是什么
 
-`weacpx` 是一个微信控制台。它把微信消息接到 `acpx` 会话上，让你直接在手机里：
+`weacpx` 是一个可以通过微信直接控制 Codex / Claude Code / Gemini / OpenCode 的工具。它把微信消息通过 `acpx` 连接到 Agent CLI 会话上，让你直接在手机里：
 
-- 新建和切换 Codex / Claude Code 会话
+- 新建和切换会话
 - 让 Agent 继续在指定项目目录里工作
 - 查看流式回复、最终结果和工具调用摘要
 - 调整权限策略
-- 在需要时做最小可用的多 Agent 编排
+- 在需要时做多 Agent 编排
 
-如果你已经习惯在本地终端里用 `acpx`，`weacpx` 提供的是一个**远程入口**，而不是另一套全新的工作流。
+如果你需要临时远程编码或办公，`weacpx` 提供的是一个方便快捷的**远程入口**，让你在微信里就能随时随地干活。
 
 ## 适合谁
 
-`weacpx` 适合已经在用 Codex、Claude Code 或其他 `acpx` driver 的开发者。你可以用微信盯任务、发指令、看结果，并在同一个聊天里管理多个会话。
+`weacpx` 适合轻量临时使用多 Agent 办公的用户。你可以用微信盯任务、发指令、看结果，并在同一个聊天里管理多个会话。
 
-它不是云端 IDE，也不是可视化编排平台。
+> `weacpx` 的会话是跟本地隔离的，它目前还不能使用 CLI 已有的会话，你在 weacpx 也无法看到本地的 CLI 会话记录。
 
 ## 5 分钟快速开始
 
@@ -34,7 +34,7 @@
 开始前，你至少需要：
 
 - Node.js 22+ 或 Bun
-- 已可用的 Codex、Claude Code 或其他 `acpx` driver
+- 已可用的 Codex / Claude Code / Gemini / OpenCode
 - 一台装了微信的手机
 
 > `weacpx` 基于 `weixin-agent-sdk` 和 `acpx` 工作。正常情况下，你不需要额外全局安装 `acpx`。
@@ -42,7 +42,7 @@
 ### 安装
 
 ```bash
-npm install -g weacpx
+npm install -g weacpx --registry=https://registry.npmjs.org
 # 或
 bun add -g weacpx
 ```
@@ -53,7 +53,7 @@ bun add -g weacpx
 weacpx login
 ```
 
-终端会显示二维码。你用微信扫码登录。
+终端会显示二维码，请继续用微信扫码登录。
 
 ### 启动服务
 
@@ -85,7 +85,7 @@ hello
 1. **启动后台服务**：`weacpx start`
 2. **创建或切换会话**：`/ss ...`、`/use ...`
 3. **直接发普通文本**：让当前会话继续工作
-4. **必要时查看状态或取消**：`/status`、`/cancel`
+4. **必要时查看状态或取消当前任务**：`/status`、`/cancel`
 
 ### 1) 创建会话
 
@@ -95,7 +95,7 @@ hello
 /ss codex -d /absolute/path/to/your/repo
 ```
 
-它会使用 `codex`，绑定这个目录，并自动切换到新会话。
+它会使用 `codex`，绑定这个工作目录，并自动切换到新会话。
 
 ### 2) 发普通消息
 
@@ -109,9 +109,9 @@ hello
 
 `weacpx` 支持三种常用回复模式：
 
-- `stream`：默认，流式返回中间文本
+- `stream`：流式返回中间文本
 - `final`：只返回最终结果
-- `verbose`：在流式文本之外，额外显示工具调用摘要
+- `verbose`：默认，在流式文本之外，额外显示工具调用摘要
 
 例如 `verbose` 模式下，你会看到：
 
@@ -208,17 +208,19 @@ weacpx doctor --smoke --agent codex --workspace backend
 
 ## 常用微信命令
 
-下面这部分保留一份**中等长度**的日常手册。够你上手和日常使用，但不把 README 写成完整参考手册。
-
 完整微信命令参考见：[docs/commands.md](./docs/commands.md)。
 
 ### Agent 管理
 
+已内置常用的 Codex 与 Claude Code；
+
+可以使用 `/agent add opencode` 添加你所需要的 agents。
+
 | 命令 | 说明 |
 |------|------|
 | `/agents` | 查看 agent 列表 |
-| `/agent add codex` | 添加 `codex` |
-| `/agent add claude` | 添加 `claude` |
+| `/agent add gemini` | 添加 `Gemini` Agent |
+| `/agent add opencode` | 添加 `OpenCode` Agent |
 | `/agent rm <name>` | 删除 agent |
 
 ### Workspace 管理
@@ -226,7 +228,7 @@ weacpx doctor --smoke --agent codex --workspace backend
 | 命令 | 说明 |
 |------|------|
 | `/workspaces` / `/workspace` / `/ws` | 查看 workspace 列表 |
-| `/ws new <name> -d <path>` | 添加 workspace，`path` 是电脑上的绝对路径 |
+| `/ws new <name> -d <path>` | 添加 workspace，`path` 是电脑上的绝对路径，Windows 不用区分正反斜杠 |
 | `/workspace rm <name>` | 删除 workspace |
 
 ### Session 会话
@@ -246,7 +248,7 @@ weacpx doctor --smoke --agent codex --workspace backend
 | `/replymode reset` | 回退到全局默认 reply mode |
 | `/session reset` | 重置当前会话上下文 |
 | `/clear` | `/session reset` 的快捷别名 |
-| `/cancel` / `/stop` | 取消当前会话 |
+| `/cancel` / `/stop` | 停止当前任务 |
 
 建议你优先记住这三个：
 
@@ -316,6 +318,55 @@ README 里只保留用户视角的最常用命令。
 
 - [docs/weacpx-group-usage-guide.md](./docs/weacpx-group-usage-guide.md)
 
+
+### MCP 集成：外部 coordinator
+
+如果你想让 Codex、Claude Code 等外部 MCP host 直接使用 weacpx 的多 Agent 编排能力，可以把 `weacpx mcp-stdio` 配成一个 stdio MCP server。
+
+先启动 daemon：
+
+```bash
+weacpx start
+```
+
+MCP 配置推荐保持简单，不要在启动参数里绑定 workspace：
+
+```json
+{
+  "mcpServers": {
+    "weacpx": {
+      "command": "weacpx",
+      "args": ["mcp-stdio"]
+    }
+  }
+}
+```
+
+外部 host 调用 `delegate_request` 时传 `workingDirectory`，weacpx 会让被委派的 worker 在这个目录工作：
+
+```json
+{
+  "targetAgent": "claude",
+  "task": "审查这个改动的风险点",
+  "workingDirectory": "/absolute/path/to/your/repo"
+}
+```
+
+Windows 上如果 MCP host 不会帮你解析带参数的 `command`，把 `node.exe` 放在 `command`，把 weacpx 脚本和参数放在 `args`：
+
+```json
+{
+  "type": "stdio",
+  "command": "D:\\Users\\you\\.nvmd\\versions\\22.19.0\\node.exe",
+  "args": [
+    "E:\\projects\\weacpx\\dist\\cli.js",
+    "mcp-stdio"
+  ]
+}
+```
+
+更多身份规则、`workingDirectory` 语义、工具列表、流程图和故障排查见：[docs/external-mcp.md](./docs/external-mcp.md)。
+
 ## 常见场景
 
 ### 在手机上继续盯一个本地项目

package/dist/bridge/bridge-main.js

@@ -212,6 +212,115 @@ var init_spawn_command = __esm(() => {
   SCRIPT_FILE_PATTERN = /\.(c|m)?js$/i;
 });
 
+// src/transport/prompt-media.ts
+import { mkdtemp, open, rm, writeFile } from "node:fs/promises";
+import { tmpdir as defaultTmpdir } from "node:os";
+import path from "node:path";
+async function createStructuredPromptFile(text, media, deps = defaultStructuredPromptFileDeps) {
+  if (!media) {
+    return null;
+  }
+  if (media.type !== "image") {
+    throw new Error("prompt media type is not supported; only image media is supported");
+  }
+  const imageData = await deps.readImageFile(media.filePath, MAX_STRUCTURED_IMAGE_BYTES);
+  if (imageData.byteLength === 0) {
+    throw new Error("image prompt must not be empty");
+  }
+  if (imageData.byteLength > MAX_STRUCTURED_IMAGE_BYTES) {
+    throw new Error(`image prompt exceeds ${MAX_STRUCTURED_IMAGE_BYTES} bytes`);
+  }
+  const blocks = [];
+  if (text.trim().length > 0) {
+    blocks.push({ type: "text", text });
+  }
+  blocks.push({
+    type: "image",
+    mimeType: resolveImageMimeType(imageData, media.mimeType),
+    data: imageData.toString("base64")
+  });
+  let dir = "";
+  try {
+    dir = await deps.mkdtemp(path.join(deps.tmpdir(), "weacpx-acp-prompt-"));
+    const filePath = path.join(dir, "prompt.json");
+    await deps.writeFile(filePath, JSON.stringify(blocks), "utf8");
+    return {
+      filePath,
+      cleanup: async () => {
+        await deps.rm(dir, { recursive: true, force: true });
+      }
+    };
+  } catch (error) {
+    if (dir) {
+      try {
+        await deps.rm(dir, { recursive: true, force: true });
+      } catch {}
+    }
+    throw error;
+  }
+}
+async function readImageFileBounded(filePath, maxBytes) {
+  const handle = await open(filePath, "r");
+  try {
+    const imageStats = await handle.stat();
+    if (!imageStats.isFile()) {
+      throw new Error("image prompt path must be a regular file");
+    }
+    if (imageStats.size > maxBytes) {
+      throw new Error(`image prompt exceeds ${maxBytes} bytes`);
+    }
+    const chunks = [];
+    let total = 0;
+    let position = 0;
+    const chunkSize = 1024 * 1024;
+    while (total <= maxBytes) {
+      const buffer = Buffer.allocUnsafe(Math.min(chunkSize, maxBytes + 1 - total));
+      const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+      if (bytesRead === 0)
+        break;
+      chunks.push(buffer.subarray(0, bytesRead));
+      total += bytesRead;
+      position += bytesRead;
+    }
+    return Buffer.concat(chunks, total);
+  } finally {
+    await handle.close();
+  }
+}
+function resolveImageMimeType(buffer, declaredMimeType) {
+  if (/^image\/[A-Za-z0-9.+-]+$/.test(declaredMimeType) && declaredMimeType !== "image/*") {
+    return declaredMimeType;
+  }
+  if (buffer.subarray(0, 8).equals(Buffer.from("89504e470d0a1a0a", "hex"))) {
+    return "image/png";
+  }
+  if (buffer.length >= 3 && buffer[0] === 255 && buffer[1] === 216 && buffer[2] === 255) {
+    return "image/jpeg";
+  }
+  const header6 = buffer.subarray(0, 6).toString("ascii");
+  if (header6 === "GIF87a" || header6 === "GIF89a") {
+    return "image/gif";
+  }
+  if (buffer.length >= 12 && buffer.subarray(0, 4).toString("ascii") === "RIFF" && buffer.subarray(8, 12).toString("ascii") === "WEBP") {
+    return "image/webp";
+  }
+  if (buffer.length >= 2 && buffer.subarray(0, 2).toString("ascii") === "BM") {
+    return "image/bmp";
+  }
+  return "image/png";
+}
+var MAX_STRUCTURED_IMAGE_BYTES, defaultStructuredPromptFileDeps;
+var init_prompt_media = __esm(() => {
+  MAX_STRUCTURED_IMAGE_BYTES = 100 * 1024 * 1024;
+  defaultStructuredPromptFileDeps = {
+    readImageFile: readImageFileBounded,
+    mkdtemp,
+    writeFile,
+    rm,
+    tmpdir: defaultTmpdir
+  };
+});
+
 // src/transport/streaming-prompt.ts
 function createStreamingPromptState(formatToolCalls = false) {
   return {
@@ -417,9 +526,9 @@ function isUnder(child, parent) {
   const p = parent.replace(/[\\/]+$/, "");
   return c === p || c.startsWith(p + "/") || c.startsWith(p + "\\");
 }
-async function defaultFsExists(path) {
+async function defaultFsExists(path2) {
   try {
-    await access(path);
+    await access(path2);
     return true;
   } catch {
     return false;
@@ -787,6 +896,7 @@ class BridgeRequestScheduler {
 // src/bridge/bridge-runtime.ts
 init_spawn_command();
 init_prompt_output();
+init_prompt_media();
 init_streaming_prompt();
 import { copyFile, readdir } from "node:fs/promises";
 import { homedir as homedir3 } from "node:os";
@@ -933,15 +1043,22 @@ class BridgeRuntime {
   }
   async prompt(input, onEvent) {
     await this.launchMcpQueueOwnerIfNeeded(input);
+    const structuredPrompt = await createStructuredPromptFile(input.text, input.media);
     const spawnSpec = resolveSpawnCommand(this.command, this.buildPromptArgs(input, [
       "prompt",
       "-s",
       input.name,
-      input.text
+      ...structuredPrompt ? ["--file", structuredPrompt.filePath] : [input.text]
     ]));
     const formatToolCalls = input.replyMode === "verbose";
-    const result = onEvent ? await this.runPromptCommand(spawnSpec.command, spawnSpec.args, onEvent, { formatToolCalls }) : await this.run(spawnSpec.command, spawnSpec.args);
-    return { text: getPromptText(result) };
+    try {
+      const result = onEvent ? await this.runPromptCommand(spawnSpec.command, spawnSpec.args, onEvent, { formatToolCalls }) : await this.run(spawnSpec.command, spawnSpec.args);
+      return { text: getPromptText(result) };
+    } finally {
+      try {
+        await structuredPrompt?.cleanup();
+      } catch {}
+    }
   }
   async launchMcpQueueOwnerIfNeeded(input) {
     if (!input.mcpCoordinatorSession) {
@@ -1335,6 +1452,7 @@ class BridgeServer {
           }
         });
       case "prompt":
+        const media = asOptionalPromptMedia(params.media);
         return await this.runtime.prompt({
           agent: requireString(params, "agent"),
           agentCommand: asOptionalString(params.agentCommand),
@@ -1342,8 +1460,9 @@ class BridgeServer {
           name: requireString(params, "name"),
           mcpCoordinatorSession: asOptionalString(params.mcpCoordinatorSession),
           mcpSourceHandle: asOptionalString(params.mcpSourceHandle),
-          text: requireString(params, "text"),
-          replyMode: asOptionalReplyMode(params.replyMode)
+          text: requirePromptText(params, media),
+          replyMode: asOptionalReplyMode(params.replyMode),
+          media
         }, (event) => {
           if (event.type === "prompt.segment") {
             writeLine?.(encodeBridgePromptSegmentEvent({
@@ -1449,6 +1568,16 @@ function requireString(params, key) {
   }
   return value;
 }
+function requirePromptText(params, media) {
+  const value = params.text;
+  if (typeof value !== "string") {
+    throw new BridgeInvalidRequestError("text must be a non-empty string");
+  }
+  if (value.length === 0 && media?.type !== "image") {
+    throw new BridgeInvalidRequestError("text must be a non-empty string unless image media is provided");
+  }
+  return value;
+}
 function requirePermissionMode(params, key) {
   const value = params[key];
   if (value === "approve-all" || value === "approve-reads" || value === "deny-all") {
@@ -1469,6 +1598,33 @@ function asOptionalString(value) {
   }
   return value;
 }
+function asOptionalPromptMedia(value) {
+  if (value === undefined) {
+    return;
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new BridgeInvalidRequestError("media must be an object when provided");
+  }
+  const record = value;
+  const type = record.type;
+  const filePath = record.filePath;
+  const mimeType = record.mimeType;
+  if (type !== "image") {
+    throw new BridgeInvalidRequestError("media.type must be image");
+  }
+  if (typeof filePath !== "string" || filePath.length === 0) {
+    throw new BridgeInvalidRequestError("media.filePath must be a non-empty string");
+  }
+  if (typeof mimeType !== "string" || mimeType.length === 0) {
+    throw new BridgeInvalidRequestError("media.mimeType must be a non-empty string");
+  }
+  return {
+    type,
+    filePath,
+    mimeType,
+    ...typeof record.fileName === "string" && record.fileName.length > 0 ? { fileName: record.fileName } : {}
+  };
+}
 var VALID_REPLY_MODES = new Set(["stream", "final", "verbose"]);
 function asOptionalReplyMode(value) {
   if (typeof value !== "string" || !VALID_REPLY_MODES.has(value)) {