@co0ontty/wand 4.60.0 → 4.61.0-beta.g14d0be2

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "commit": "c0ff8ccee9e2b9591db65e5f14d45626e7a07fa9",
-  "builtAt": "2026-09-12T12:31:51.181Z",
-  "version": "4.60.0",
-  "channel": "stable"
+  "commit": "14d0be2916773382d9b9c692d21ec271479d1fe4",
+  "builtAt": "2026-09-14T06:27:55.916Z",
+  "version": "4.61.0-beta.g14d0be2",
+  "channel": "beta"
 }

package/dist/claude-pty-bridge.js

@@ -152,14 +152,17 @@ export class ClaudePtyBridge extends EventEmitter {
             return;
         }
         const cleanInput = input.replace(/[\r\n]+$/, "").trim();
+        const now = new Date().toISOString();
         // Add user message
         this.messages.push({
             role: "user",
+            createdAt: now,
             content: [{ type: "text", text: cleanInput }],
         });
         // Add assistant placeholder for streaming
         this.messages.push({
             role: "assistant",
+            createdAt: now,
             content: [],
         });
         // Initialize chat state
@@ -794,6 +797,7 @@ export class ClaudePtyBridge extends EventEmitter {
         // Emit turn completed
         const lastTurn = this.messages[this.messages.length - 1];
         if (lastTurn?.role === "assistant" && lastTurn.content.length > 0) {
+            lastTurn.completedAt = new Date().toISOString();
             this.emitEvent({
                 type: "chat.turn",
                 sessionId: this.sessionId,

package/dist/mission-types.d.ts

@@ -16,6 +16,8 @@ export interface Mission {
     status: MissionStatus;
     /** 可选关联的任务（workspace task）：派发的 attempt 会话绑定该任务。 */
     taskId?: string | null;
+    /** 可选里程碑：与任务共用同一份全局里程碑列表。 */
+    milestoneId?: string | null;
     worktree: MissionWorktreeOptions;
     createdAt: string;
     updatedAt: string;
@@ -82,6 +84,8 @@ export interface CreateMissionInput {
     providers: SessionProvider[];
     /** 关联到指定 workspace task；派发会话将绑定 workspaceTaskId。 */
     taskId?: string;
+    /** 里程碑 id；null / 缺省表示不归入里程碑。 */
+    milestoneId?: string | null;
     baseRef?: string;
     sharedDirectories?: string[];
     copyPaths?: string[];

package/dist/missions.js

@@ -147,6 +147,9 @@ export class Missions {
             throw new Error(`请选择 1-${MAX_ATTEMPTS} 个有效 provider。`);
         }
         const createdAt = nowIso();
+        const milestoneId = input.milestoneId?.trim() || null;
+        if (milestoneId && !this.storage.getWandMilestone(milestoneId))
+            throw new Error("未找到该里程碑。");
         const mission = {
             id: randomUUID(),
             title: input.title?.trim().slice(0, 120) || firstPromptLine(prompt),
@@ -154,6 +157,7 @@ export class Missions {
             cwd,
             status: "dispatching",
             taskId: input.taskId?.trim() || null,
+            milestoneId,
             worktree: {
                 baseRef: input.baseRef?.trim() || undefined,
                 sharedDirectories: normalizeStringList(input.sharedDirectories, "sharedDirectories"),

package/dist/server-app-connect.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 公开 origin 推导、App 连接码与结构化聊天人设。
+ *
+ * 这些逻辑原来内联在 `server.ts` 里，占了组合根很大一块，而且和路由注册混在
+ * 一起。它们只依赖请求头 / 配置 / 文件系统，跟 Express 组合根无关，因此单独
+ * 成模块；`server.ts` 只负责把结果接到 `/api/login`、`/api/config` 等路由上。
+ */
+import type { Request } from "express";
+import type { StructuredChatPersonaConfig, WandConfig } from "./types.js";
+export declare function generateAppToken(password: string, secret: string): string;
+export declare function verifyAppToken(token: string, password: string, secret: string): boolean;
+export declare function encodeConnectCode(url: string, token: string): string;
+export declare function isBrowserExtensionOrigin(value: string | undefined): boolean;
+/**
+ * App 连接码用于另一台设备。设置页若从 localhost 打开，直接编码浏览器 origin
+ * 会让客户端连接它自己；监听 0.0.0.0 时自动换成本机优先 LAN IPv4。
+ */
+export declare function resolveAppConnectOrigin(origin: string, config: WandConfig): string;
+/**
+ * 反代场景：配置了 publicOrigin 就优先用它。TLS 在 L4 反代终止时 node 只看到
+ * 明文 HTTP，既没有 X-Forwarded-Proto 也没有正确的 scheme，猜不出来。
+ */
+export declare function resolveRequestServerUrl(req: Request, config: WandConfig, useHttps: boolean): string;
+/** 设置页里的连接码：优先显式 origin，其次配置 publicOrigin，最后回落到请求头。 */
+export declare function resolveAppConnectCode(req: Request, config: WandConfig, useHttps: boolean, password: string): {
+    code: string;
+    url: string;
+};
+export declare function appTokenLoginPayload(req: Request, config: WandConfig, useHttps: boolean, password: string): {
+    appToken: string;
+    serverUrl: string;
+};
+export declare function resolveStructuredChatPersona(config: WandConfig): StructuredChatPersonaConfig | undefined;
+/** 本地头像文件的绝对路径；外链和未配置返回 null。 */
+export declare function resolveStructuredChatAvatarPath(configPath: string, config: WandConfig, role: "user" | "assistant"): string | null;
+/**
+ * `/api/config` 用的人设 payload。本地头像存在时替换成 `/api/structured-chat-avatar/:role`，
+ * 不把磁盘路径暴露给前端；文件不存在则整条 avatar 字段省略。
+ */
+export declare function buildStructuredChatPersonaPayload(configPath: string, config: WandConfig): Promise<StructuredChatPersonaConfig | undefined>;

package/dist/server-app-connect.js

@@ -0,0 +1,241 @@
+/**
+ * 公开 origin 推导、App 连接码与结构化聊天人设。
+ *
+ * 这些逻辑原来内联在 `server.ts` 里，占了组合根很大一块，而且和路由注册混在
+ * 一起。它们只依赖请求头 / 配置 / 文件系统，跟 Express 组合根无关，因此单独
+ * 成模块；`server.ts` 只负责把结果接到 `/api/login`、`/api/config` 等路由上。
+ */
+import crypto from "node:crypto";
+import { stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { resolveConfigDir } from "./config.js";
+import { normalizePublicOrigin } from "./ios-ota.js";
+import { firstQueryStringValue, firstHeaderValue, firstHeaderListValue } from "./server-request.js";
+// ── App 连接码 ──
+//
+// 连接码里的 token 是密码派生的（HMAC(password, appSecret)），兼容既有连接码；
+// 因此它等价于密码，绝不能写进日志或回显给非登录方。
+export function generateAppToken(password, secret) {
+    return crypto.createHmac("sha256", secret).update(password).digest("hex");
+}
+export function verifyAppToken(token, password, secret) {
+    const expected = generateAppToken(password, secret);
+    return crypto.timingSafeEqual(Buffer.from(token, "hex"), Buffer.from(expected, "hex"));
+}
+export function encodeConnectCode(url, token) {
+    return Buffer.from(`${url}#${token}`).toString("base64");
+}
+// ── 转发头解析 ──
+function unquoteHeaderValue(value) {
+    const trimmed = value.trim();
+    if (trimmed.length >= 2 && trimmed.startsWith("\"") && trimmed.endsWith("\"")) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+function getForwardedParam(req, key) {
+    const forwarded = firstHeaderListValue(req.headers.forwarded);
+    if (!forwarded)
+        return undefined;
+    const targetKey = key.toLowerCase();
+    for (const part of forwarded.split(";")) {
+        const eqIdx = part.indexOf("=");
+        if (eqIdx < 1)
+            continue;
+        const partKey = part.slice(0, eqIdx).trim().toLowerCase();
+        if (partKey !== targetKey)
+            continue;
+        return unquoteHeaderValue(part.slice(eqIdx + 1));
+    }
+    return undefined;
+}
+function normalizePublicProtocol(value) {
+    const proto = value?.trim().toLowerCase();
+    if (proto === "http" || proto === "https")
+        return proto;
+    return undefined;
+}
+function getPublicRequestProtocol(req, fallback) {
+    return (normalizePublicProtocol(firstHeaderListValue(req.headers["x-forwarded-proto"]))
+        ?? normalizePublicProtocol(getForwardedParam(req, "proto"))
+        ?? (firstHeaderListValue(req.headers["x-forwarded-ssl"])?.toLowerCase() === "on" ? "https" : undefined)
+        ?? (firstHeaderListValue(req.headers["x-forwarded-scheme"])?.toLowerCase() === "https" ? "https" : undefined)
+        ?? fallback);
+}
+function getPublicRequestHost(req, config) {
+    return (firstHeaderListValue(req.headers["x-forwarded-host"])
+        ?? getForwardedParam(req, "host")
+        ?? req.headers.host
+        ?? `${config.host}:${config.port}`);
+}
+// ── 浏览器扩展 origin ──
+export function isBrowserExtensionOrigin(value) {
+    if (!value)
+        return false;
+    return /^chrome-extension:\/\/[a-z]{32}$/i.test(value)
+        || /^moz-extension:\/\/[0-9a-f-]+$/i.test(value)
+        || /^safari-web-extension:\/\//i.test(value);
+}
+// ── LAN 地址选择 ──
+function isPrivateIpv4(address) {
+    if (address.startsWith("10.") || address.startsWith("192.168."))
+        return true;
+    const match = address.match(/^172\.(\d+)\./);
+    return match ? Number(match[1]) >= 16 && Number(match[1]) <= 31 : false;
+}
+function preferredLanIpv4() {
+    const candidates = [];
+    for (const [name, entries] of Object.entries(os.networkInterfaces())) {
+        for (const entry of entries ?? []) {
+            const family = entry.family;
+            if (entry.internal || (family !== "IPv4" && family !== 4))
+                continue;
+            let score = isPrivateIpv4(entry.address) ? 10 : 0;
+            if (/^(en|eth|wlan)\d+$/i.test(name))
+                score += 10;
+            candidates.push({ address: entry.address, score });
+        }
+    }
+    candidates.sort((a, b) => b.score - a.score || a.address.localeCompare(b.address));
+    return candidates[0]?.address;
+}
+/**
+ * App 连接码用于另一台设备。设置页若从 localhost 打开，直接编码浏览器 origin
+ * 会让客户端连接它自己；监听 0.0.0.0 时自动换成本机优先 LAN IPv4。
+ */
+export function resolveAppConnectOrigin(origin, config) {
+    if (config.host !== "0.0.0.0")
+        return origin;
+    try {
+        const parsed = new URL(origin);
+        const hostname = parsed.hostname.toLowerCase();
+        const isLocalOnly = hostname === "localhost"
+            || hostname === "127.0.0.1"
+            || hostname === "[::1]"
+            || hostname === "::1"
+            || hostname === "0.0.0.0"
+            || hostname === "[::]";
+        if (!isLocalOnly)
+            return parsed.origin;
+        const lanIp = preferredLanIpv4();
+        if (!lanIp)
+            return parsed.origin;
+        parsed.hostname = lanIp;
+        return parsed.origin;
+    }
+    catch {
+        return origin;
+    }
+}
+/**
+ * 反代场景：配置了 publicOrigin 就优先用它。TLS 在 L4 反代终止时 node 只看到
+ * 明文 HTTP，既没有 X-Forwarded-Proto 也没有正确的 scheme，猜不出来。
+ */
+export function resolveRequestServerUrl(req, config, useHttps) {
+    const configuredOrigin = normalizePublicOrigin(config.publicOrigin);
+    if (configuredOrigin)
+        return resolveAppConnectOrigin(configuredOrigin, config);
+    const requestProtocol = getPublicRequestProtocol(req, useHttps ? "https" : "http");
+    const requestHost = getPublicRequestHost(req, config);
+    const originHeader = firstHeaderValue(req.headers.origin);
+    const browserOrigin = isBrowserExtensionOrigin(originHeader)
+        ? undefined
+        : normalizePublicOrigin(originHeader) ?? undefined;
+    return resolveAppConnectOrigin(browserOrigin ?? `${requestProtocol}://${requestHost}`, config);
+}
+/** 设置页里的连接码：优先显式 origin，其次配置 publicOrigin，最后回落到请求头。 */
+export function resolveAppConnectCode(req, config, useHttps, password) {
+    const requestProtocol = getPublicRequestProtocol(req, useHttps ? "https" : "http");
+    const requestHost = getPublicRequestHost(req, config);
+    const browserOrigin = normalizePublicOrigin(firstQueryStringValue(req.query.origin));
+    const serverUrl = resolveAppConnectOrigin(normalizePublicOrigin(config.publicOrigin) ?? browserOrigin ?? `${requestProtocol}://${requestHost}`, config);
+    const token = generateAppToken(password, config.appSecret ?? "");
+    return { code: encodeConnectCode(serverUrl, token), url: serverUrl };
+}
+export function appTokenLoginPayload(req, config, useHttps, password) {
+    return {
+        appToken: generateAppToken(password, config.appSecret ?? ""),
+        serverUrl: resolveRequestServerUrl(req, config, useHttps),
+    };
+}
+// ── 结构化聊天人设 ──
+function isExternalAvatarSource(value) {
+    return /^(https?:|data:)/i.test(value);
+}
+function normalizePersonaName(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+function normalizePersonaAvatar(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+export function resolveStructuredChatPersona(config) {
+    const persona = config.structuredChatPersona;
+    if (!persona)
+        return undefined;
+    const userName = normalizePersonaName(persona.user?.name);
+    const userAvatar = normalizePersonaAvatar(persona.user?.avatar);
+    const assistantName = normalizePersonaName(persona.assistant?.name);
+    const assistantAvatar = normalizePersonaAvatar(persona.assistant?.avatar);
+    if (!userName && !userAvatar && !assistantName && !assistantAvatar) {
+        return undefined;
+    }
+    return {
+        user: userName || userAvatar ? { name: userName, avatar: userAvatar } : undefined,
+        assistant: assistantName || assistantAvatar ? { name: assistantName, avatar: assistantAvatar } : undefined,
+    };
+}
+/** 本地头像文件的绝对路径；外链和未配置返回 null。 */
+export function resolveStructuredChatAvatarPath(configPath, config, role) {
+    const avatar = role === "user"
+        ? config.structuredChatPersona?.user?.avatar
+        : config.structuredChatPersona?.assistant?.avatar;
+    if (!avatar || isExternalAvatarSource(avatar)) {
+        return null;
+    }
+    const configDir = resolveConfigDir(configPath);
+    return path.isAbsolute(avatar) ? avatar : path.resolve(configDir, avatar);
+}
+/**
+ * `/api/config` 用的人设 payload。本地头像存在时替换成 `/api/structured-chat-avatar/:role`，
+ * 不把磁盘路径暴露给前端；文件不存在则整条 avatar 字段省略。
+ */
+export async function buildStructuredChatPersonaPayload(configPath, config) {
+    const persona = resolveStructuredChatPersona(config);
+    if (!persona)
+        return undefined;
+    const buildRole = async (role) => {
+        const roleConfig = role === "user" ? persona.user : persona.assistant;
+        if (!roleConfig)
+            return undefined;
+        let avatar = roleConfig.avatar;
+        if (avatar && !isExternalAvatarSource(avatar)) {
+            const resolvedPath = resolveStructuredChatAvatarPath(configPath, config, role);
+            if (!resolvedPath) {
+                avatar = undefined;
+            }
+            else {
+                try {
+                    const fileStat = await stat(resolvedPath);
+                    avatar = fileStat.isFile() ? `/api/structured-chat-avatar/${role}` : undefined;
+                }
+                catch {
+                    avatar = undefined;
+                }
+            }
+        }
+        if (!roleConfig.name && !avatar)
+            return undefined;
+        return { name: roleConfig.name, avatar };
+    };
+    const [user, assistant] = await Promise.all([buildRole("user"), buildRole("assistant")]);
+    if (!user && !assistant)
+        return undefined;
+    return { user, assistant };
+}

package/dist/server-file-routes.js

@@ -7,6 +7,7 @@ import process from "node:process";
 import { promisify } from "node:util";
 import { getErrorMessage } from "./error-utils.js";
 import { asyncRoute } from "./express-async.js";
+import { sendRouteError } from "./server-request.js";
 import { isBlockedFolderPath, normalizeFolderPath } from "./middleware/path-safety.js";
 import { parseBoundedInteger } from "./request-limits.js";
 const execAsync = promisify(exec);
@@ -48,7 +49,7 @@ export function registerFileRoutes(app, deps) {
             res.json(await listPathSuggestions(query, defaultCwd));
         }
         catch (error) {
-            res.status(400).json({ error: getErrorMessage(error, "无法加载路径建议。") });
+            sendRouteError(res, error, "无法加载路径建议。");
         }
     }));
     app.get("/api/directory", asyncRoute(async (req, res) => {
@@ -96,7 +97,7 @@ export function registerFileRoutes(app, deps) {
             res.json(payload);
         }
         catch (error) {
-            res.status(400).json({ error: getErrorMessage(error, "无法读取目录。可能原因：路径不存在或权限不足。") });
+            sendRouteError(res, error, "无法读取目录。可能原因：路径不存在或权限不足。");
         }
     }));
     app.get("/api/file-preview", asyncRoute(async (req, res) => {
@@ -155,7 +156,7 @@ export function registerFileRoutes(app, deps) {
             res.json({ ...payload, mtime: fileStat.mtime.toISOString() });
         }
         catch (error) {
-            res.status(400).json({ error: getErrorMessage(error, "Failed to read file") });
+            sendRouteError(res, error, "Failed to read file");
         }
     }));
     app.post("/api/file-write", asyncRoute(async (req, res) => {
@@ -227,7 +228,7 @@ export function registerFileRoutes(app, deps) {
             });
         }
         catch (error) {
-            res.status(400).json({ error: getErrorMessage(error, "保存文件失败。") });
+            sendRouteError(res, error, "保存文件失败。");
         }
     }));
     app.post("/api/file-create", asyncRoute(async (req, res) => {
@@ -253,7 +254,7 @@ export function registerFileRoutes(app, deps) {
                 res.status(409).json({ error: "文件已存在。", path: resolvedPath });
                 return;
             }
-            res.status(400).json({ error: getErrorMessage(error, "创建文件失败。") });
+            sendRouteError(res, error, "创建文件失败。");
         }
     }));
     app.post("/api/dir-create", asyncRoute(async (req, res) => {
@@ -274,7 +275,7 @@ export function registerFileRoutes(app, deps) {
             res.json({ ok: true, path: resolvedPath, mtime: fileStat.mtime.toISOString() });
         }
         catch (error) {
-            res.status(400).json({ error: getErrorMessage(error, "创建文件夹失败。") });
+            sendRouteError(res, error, "创建文件夹失败。");
         }
     }));
     app.post("/api/file-rename", asyncRoute(async (req, res) => {
@@ -319,7 +320,7 @@ export function registerFileRoutes(app, deps) {
                 res.status(404).json({ error: "源路径不存在。" });
                 return;
             }
-            res.status(400).json({ error: getErrorMessage(error, "重命名/移动失败。") });
+            sendRouteError(res, error, "重命名/移动失败。");
         }
     }));
     app.post("/api/file-delete", asyncRoute(async (req, res) => {
@@ -345,7 +346,7 @@ export function registerFileRoutes(app, deps) {
                 res.status(404).json({ error: "路径不存在。" });
                 return;
             }
-            res.status(400).json({ error: getErrorMessage(error, "删除失败。") });
+            sendRouteError(res, error, "删除失败。");
         }
     }));
     app.get("/api/file-raw", asyncRoute(async (req, res) => {
@@ -396,7 +397,7 @@ export function registerFileRoutes(app, deps) {
             });
         }
         catch (error) {
-            res.status(400).json({ error: getErrorMessage(error, "Failed to read file") });
+            sendRouteError(res, error, "Failed to read file");
         }
     }));
     app.get("/api/folders", asyncRoute(async (req, res) => {
@@ -559,7 +560,7 @@ export function registerFileRoutes(app, deps) {
             res.json({ results: results.slice(0, maxResults), query, cwd: resolvedCwd });
         }
         catch (error) {
-            res.status(400).json({ error: getErrorMessage(error, "搜索失败。可能原因：路径不存在或权限不足。") });
+            sendRouteError(res, error, "搜索失败。可能原因：路径不存在或权限不足。");
         }
     }));
 }

package/dist/server-github-routes.js

@@ -1,13 +1,6 @@
 import { asyncRoute } from "./express-async.js";
 import { connectGithub, getGithubConnectorStatus, githubRequest, } from "./github-connector.js";
-import { getErrorMessage } from "./error-utils.js";
-function stringQuery(value, fallback = "") {
-    return typeof value === "string" ? value.trim() : fallback;
-}
-function integerQuery(value, fallback, min, max) {
-    const parsed = Number(stringQuery(value));
-    return Number.isInteger(parsed) && parsed >= min && parsed <= max ? parsed : fallback;
-}
+import { bodyObject, integerQuery, requiredString, sendRouteError, stringQuery } from "./server-request.js";
 function githubListQuery(reqQuery, defaults = {}) {
     const query = new URLSearchParams();
     if (defaults.state)
@@ -38,27 +31,16 @@ function issueNumber(req) {
         throw new Error("Issue 或 PR 编号无效。");
     return number;
 }
-function validateObjectBody(body) {
-    if (!body || typeof body !== "object" || Array.isArray(body))
-        throw new Error("请求体必须是对象。");
-    return body;
-}
-function requiredString(body, key) {
-    const value = typeof body[key] === "string" ? body[key].trim() : "";
-    if (!value)
-        throw new Error(`${key} 不能为空。`);
-    return value;
-}
-function publicError(error) {
+/** 把 connector 抛出的 HTTP 错误映射成对外的状态码；非法状态一律降为 500。 */
+function githubErrorStatus(error) {
     const status = error instanceof Error && "status" in error && typeof error.status === "number"
         ? error.status
         : 400;
-    return { status: status >= 400 && status < 600 ? status : 500, message: getErrorMessage(error, "GitHub 操作失败。") };
+    return status >= 400 && status < 600 ? status : 500;
 }
 function sendGithubError(res, error, remapAuth = false) {
-    const result = publicError(error);
-    const status = remapAuth && (result.status === 401 || result.status === 403) ? 400 : result.status;
-    res.status(status).json({ error: result.message });
+    const status = githubErrorStatus(error);
+    sendRouteError(res, error, "GitHub 操作失败。", remapAuth && (status === 401 || status === 403) ? 400 : status);
 }
 async function githubJson(storage, pathname, init = {}) {
     return (await githubRequest(storage, pathname, init)).data;
@@ -71,7 +53,7 @@ export function registerGithubRoutes(app, deps) {
     });
     app.post("/api/connectors/github", requireAdmin, asyncRoute(async (req, res) => {
         try {
-            const body = validateObjectBody(req.body);
+            const body = bodyObject(req.body);
             const token = requiredString(body, "token");
             const apiUrl = typeof body.apiUrl === "string" ? body.apiUrl : undefined;
             res.set("Cache-Control", "no-store");
@@ -98,7 +80,7 @@ export function registerGithubRoutes(app, deps) {
     app.post("/api/github/repos/:owner/:repo/issues/:number/bindings", requireAdmin, (req, res) => {
         try {
             const number = issueNumber(req);
-            const body = validateObjectBody(req.body);
+            const body = bodyObject(req.body);
             const sessionId = requiredString(body, "sessionId");
             if (sessions && !sessions.get(sessionId))
                 throw new Error("未找到该会话。");
@@ -168,7 +150,7 @@ export function registerGithubRoutes(app, deps) {
     }));
     app.post("/api/github/repos/:owner/:repo/issues", requireAdmin, asyncRoute(async (req, res) => {
         try {
-            const body = validateObjectBody(req.body);
+            const body = bodyObject(req.body);
             const payload = { title: requiredString(body, "title") };
             for (const key of ["body", "labels", "assignees", "milestone"]) {
                 if (body[key] !== undefined)
@@ -182,7 +164,7 @@ export function registerGithubRoutes(app, deps) {
     }));
     app.patch("/api/github/repos/:owner/:repo/issues/:number", requireAdmin, asyncRoute(async (req, res) => {
         try {
-            const body = validateObjectBody(req.body);
+            const body = bodyObject(req.body);
             const payload = {};
             for (const key of ["title", "body", "state", "state_reason", "labels", "assignees", "milestone"]) {
                 if (body[key] !== undefined)
@@ -198,7 +180,7 @@ export function registerGithubRoutes(app, deps) {
     }));
     app.post("/api/github/repos/:owner/:repo/issues/:number/comments", requireAdmin, asyncRoute(async (req, res) => {
         try {
-            const body = validateObjectBody(req.body);
+            const body = bodyObject(req.body);
             const payload = { body: requiredString(body, "body") };
             res.status(201).json(await githubJson(storage, `${repoPath(req)}/issues/${issueNumber(req)}/comments`, { method: "POST", body: JSON.stringify(payload) }));
         }
@@ -217,7 +199,7 @@ export function registerGithubRoutes(app, deps) {
     }));
     app.post("/api/github/repos/:owner/:repo/pulls", requireAdmin, asyncRoute(async (req, res) => {
         try {
-            const body = validateObjectBody(req.body);
+            const body = bodyObject(req.body);
             const payload = {
                 title: requiredString(body, "title"),
                 head: requiredString(body, "head"),

package/dist/server-mission-routes.js

@@ -1,9 +1,11 @@
 import { asyncRoute } from "./express-async.js";
 import { getErrorMessage } from "./error-utils.js";
+import { sendRouteError } from "./server-request.js";
+// Missions 的错误文案在 service 层就已确定，这里只把“不存在”类错误提升为 404。
+const MISSION_NOT_FOUND = /^(任务不存在|任务 attempt 不存在)|没有关联会话|当前不可用/;
 function sendMissionError(res, error) {
     const message = getErrorMessage(error, "任务操作失败。");
-    const missing = /^(任务不存在|任务 attempt 不存在)|没有关联会话|当前不可用/.test(message);
-    res.status(missing ? 404 : 400).json({ error: message });
+    sendRouteError(res, error, "任务操作失败。", MISSION_NOT_FOUND.test(message) ? 404 : 400);
 }
 function commentIdsFrom(body) {
     if (!body || typeof body !== "object" || !Array.isArray(body.commentIds))

package/dist/server-request.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 路由层共享的请求解析小工具。
+ *
+ * 这些函数原来在 `server-task-routes.ts`、`server-github-routes.ts`、
+ * `server.ts` 里各写了一份；集中到一处后，行为（尤其是“空字符串视为缺省”）
+ * 只有一个定义，路由文件只保留业务语义。
+ */
+/** 取字符串并 trim；非字符串一律当缺省处理。 */
+export declare function text(value: unknown, fallback?: string): string;
+/** Express query 值可能是数组，取第一个字符串。 */
+export declare function firstQueryStringValue(value: unknown): string | undefined;
+/** 请求头可能是数组（重复头），取第一个值。 */
+export declare function firstHeaderValue(value: string | string[] | undefined): string | undefined;
+/** 逗号分隔的请求头（如 Forwarded / X-Forwarded-*）取第一段。 */
+export declare function firstHeaderListValue(value: string | string[] | undefined): string | undefined;
+/** 查询参数版 `text()`：显式传 fallback 时返回 fallback 而不是空串。 */
+export declare function stringQuery(value: unknown, fallback?: string): string;
+/** 解析范围内整数，越界或非整数回落到 fallback。 */
+export declare function integerQuery(value: unknown, fallback: number, min: number, max: number): number;
+/** 要求请求体是普通对象；数组和 null 都拒绝。 */
+export declare function bodyObject(value: unknown): Record<string, unknown>;
+/** 从对象里取必填的非空字符串字段。 */
+export declare function requiredString(body: Record<string, unknown>, key: string): string;
+/**
+ * 路由 catch 块的标准回包：业务异常用 fallback 文案，默认 400。
+ *
+ * `getErrorMessage` 会把 Error.message 原样透出，因此抛出的错误必须是面向用户的；
+ * 内部错误请用 getErrorMessage(error, fallback) 已包好的 fallback。
+ */
+export declare function sendRouteError(res: {
+    status(code: number): {
+        json(body: unknown): unknown;
+    };
+}, error: unknown, fallback: string, status?: number): void;

package/dist/server-request.js

@@ -0,0 +1,61 @@
+/**
+ * 路由层共享的请求解析小工具。
+ *
+ * 这些函数原来在 `server-task-routes.ts`、`server-github-routes.ts`、
+ * `server.ts` 里各写了一份；集中到一处后，行为（尤其是“空字符串视为缺省”）
+ * 只有一个定义，路由文件只保留业务语义。
+ */
+import { getErrorMessage } from "./error-utils.js";
+/** 取字符串并 trim；非字符串一律当缺省处理。 */
+export function text(value, fallback = "") {
+    return typeof value === "string" ? value.trim() : fallback;
+}
+/** Express query 值可能是数组，取第一个字符串。 */
+export function firstQueryStringValue(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value))
+        return firstQueryStringValue(value[0]);
+    return undefined;
+}
+/** 请求头可能是数组（重复头），取第一个值。 */
+export function firstHeaderValue(value) {
+    if (Array.isArray(value))
+        return value[0];
+    return value;
+}
+/** 逗号分隔的请求头（如 Forwarded / X-Forwarded-*）取第一段。 */
+export function firstHeaderListValue(value) {
+    return firstHeaderValue(value)?.split(",")[0]?.trim();
+}
+/** 查询参数版 `text()`：显式传 fallback 时返回 fallback 而不是空串。 */
+export function stringQuery(value, fallback = "") {
+    return typeof value === "string" ? value.trim() : fallback;
+}
+/** 解析范围内整数，越界或非整数回落到 fallback。 */
+export function integerQuery(value, fallback, min, max) {
+    const parsed = Number(stringQuery(value));
+    return Number.isInteger(parsed) && parsed >= min && parsed <= max ? parsed : fallback;
+}
+/** 要求请求体是普通对象；数组和 null 都拒绝。 */
+export function bodyObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("请求体必须是对象。");
+    return value;
+}
+/** 从对象里取必填的非空字符串字段。 */
+export function requiredString(body, key) {
+    const value = text(body[key]);
+    if (!value)
+        throw new Error(`${key} 不能为空。`);
+    return value;
+}
+/**
+ * 路由 catch 块的标准回包：业务异常用 fallback 文案，默认 400。
+ *
+ * `getErrorMessage` 会把 Error.message 原样透出，因此抛出的错误必须是面向用户的；
+ * 内部错误请用 getErrorMessage(error, fallback) 已包好的 fallback。
+ */
+export function sendRouteError(res, error, fallback, status = 400) {
+    res.status(status).json({ error: getErrorMessage(error, fallback) });
+}