@co0ontty/wand 1.10.0 → 1.14.2

package/README.md

@@ -1,6 +1,15 @@
 # wand
 
-通过浏览器远程访问和管理本地 CLI 工具的 Web 控制台。专为 Claude Code 设计，支持终端和结构化对话双视图、会话持久化与恢复、权限管控、文件浏览等功能。
+[![npm version](https://img.shields.io/npm/v/@co0ontty/wand.svg)](https://www.npmjs.com/package/@co0ontty/wand)
+[![license](https://img.shields.io/npm/l/@co0ontty/wand.svg)](https://github.com/co0ontty/wand/blob/master/LICENSE)
+[![node](https://img.shields.io/node/v/@co0ontty/wand.svg)](https://nodejs.org)
+[![GitHub last commit](https://img.shields.io/github/last-commit/co0ontty/wand)](https://github.com/co0ontty/wand/commits/master)
+
+通过浏览器远程访问和管理本地 CLI 工具的 Web 控制台。专为 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 和 [Codex](https://github.com/openai/codex) 设计，支持终端和结构化对话双视图、会话持久化与恢复、权限管控、文件浏览、Android 客户端等功能。
+
+<p align="center">
+  <img src="docs/screenshots/chat-view.png" width="800" alt="结构化对话视图" />
+</p>
 
 ## 安装
 
@@ -22,6 +31,43 @@ wand web
 
 安装完成后打开浏览器访问终端中提示的地址即可。
 
+## 功能
+
+<p align="center">
+  <img src="docs/screenshots/home.png" width="800" alt="欢迎页" />
+</p>
+
+### 核心
+
+- **双视图模式** — 终端原始输出和结构化对话视图可随时切换，同一会话两种呈现
+- **多 Provider 支持** — 同时支持 Claude Code 和 Codex，可按需创建不同类型的会话
+- **会话管理** — 创建、归档、恢复会话；支持从 Claude 原生历史记录恢复；会话列表显示摘要，懒加载
+- **权限控制** — 可视化权限提示，支持逐次确认、单次批准、本轮记忆等策略；工具调用自动分组与审批统计
+
+### 交互体验
+
+- **结构化对话** — 代码块语法高亮、工具调用折叠/展开、多问题分组渲染、Token 用量按轮累计
+- **个性化角色** — 像素风猫咪头像（赛博虎妞 / 勤劳初二），支持自定义对话角色名称
+- **消息排队** — 在 AI 思考时可继续输入，消息自动排队发送
+- **文件浏览器** — 内置路径浏览和搜索功能
+
+### 部署与访问
+
+- **PWA 支持** — 可添加到主屏幕作为独立应用使用
+- **Android 客户端** — WebView 壳应用，支持加密连接码分发、APK 自动更新检查、原生通知推送、启动器图标切换
+- **HTTPS** — 可选自签证书，适合远程或移动端访问
+- **版本管理** — 内置更新检查与升级提示
+
+## 截图
+
+| 登录 | 对话视图 |
+|:---:|:---:|
+| <img src="docs/screenshots/login.png" width="400" alt="登录页" /> | <img src="docs/screenshots/chat-view.png" width="400" alt="对话视图" /> |
+
+| 终端 PTY 视图 |
+|:---:|
+| <img src="docs/screenshots/terminal-pty.png" width="800" alt="终端 PTY 视图" /> |
+
 ## 配置
 
 配置文件位于 `~/.wand/config.json`，首次 `wand init` 时自动生成。
@@ -43,17 +89,6 @@ wand config:set port 9443
 | `password` | (随机生成) | 登录密码 |
 | `language` | `""` | Claude 回复语言偏好 |
 
-## 功能
-
-- **双视图模式** — 终端原始输出和结构化对话视图可随时切换
-- **会话管理** — 创建、归档、恢复会话；支持从 Claude 原生历史记录恢复；会话列表显示摘要
-- **权限控制** — 可视化权限提示，支持逐次确认、单次批准、本轮记忆等策略；工具调用自动分组
-- **文件浏览器** — 内置路径浏览和搜索功能
-- **多种运行模式** — full-access / default / auto-edit 等 Claude 运行模式
-- **个性化** — 像素风猫咪头像、回复语言偏好设置
-- **PWA 支持** — 可添加到主屏幕作为独立应用使用
-- **HTTPS** — 可选自签证书，适合远程或移动端访问
-
 ## 开发
 
 ```bash
@@ -84,6 +119,7 @@ src/
   session-logger.ts         # 文件日志 ~/.wand/sessions/
   resume-policy.ts          # Claude 历史绑定与恢复策略
   web-ui/                   # 服务端渲染的前端 HTML/CSS/JS
+android/                    # Android WebView 壳应用
 ```
 
 数据存储在 `~/.wand/` 下：`config.json`（配置）、`wand.db`（SQLite）、`sessions/`（日志）。

package/dist/config.d.ts

@@ -1,8 +1,9 @@
-import { ExecutionMode, WandConfig } from "./types.js";
+import { CardExpandDefaults, ExecutionMode, WandConfig } from "./types.js";
 export declare const defaultConfig: () => WandConfig;
 export declare function resolveConfigPath(inputPath?: string): string;
 export declare function resolveConfigDir(configPath: string): string;
 export declare function hasConfigFile(configPath: string): boolean;
 export declare function ensureConfig(configPath: string): Promise<WandConfig>;
 export declare function saveConfig(configPath: string, config: WandConfig): Promise<void>;
+export declare function normalizeCardDefaults(input: unknown): CardExpandDefaults;
 export declare function isExecutionMode(value: unknown): value is ExecutionMode;

package/dist/config.js

@@ -1,3 +1,4 @@
+import crypto from "node:crypto";
 import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
@@ -16,6 +17,8 @@ export const defaultConfig = () => ({
     allowedCommandPrefixes: [],
     shortcutLogMaxBytes: 10 * 1024 * 1024,
     language: "",
+    android: defaultAndroidApkConfig(),
+    cardDefaults: defaultCardExpandDefaults(),
     commandPresets: [
         {
             label: "Claude",
@@ -79,6 +82,49 @@ export async function saveConfig(configPath, config) {
     await mkdir(path.dirname(configPath), { recursive: true });
     await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
 }
+function defaultCardExpandDefaults() {
+    return {
+        editCards: false,
+        inlineTools: false,
+        terminal: false,
+        thinking: false,
+        toolGroup: false,
+    };
+}
+export function normalizeCardDefaults(input) {
+    if (!input || typeof input !== "object")
+        return defaultCardExpandDefaults();
+    const raw = input;
+    return {
+        editCards: typeof raw.editCards === "boolean" ? raw.editCards : false,
+        inlineTools: typeof raw.inlineTools === "boolean" ? raw.inlineTools : false,
+        terminal: typeof raw.terminal === "boolean" ? raw.terminal : false,
+        thinking: typeof raw.thinking === "boolean" ? raw.thinking : false,
+        toolGroup: typeof raw.toolGroup === "boolean" ? raw.toolGroup : false,
+    };
+}
+function defaultAndroidApkConfig() {
+    return {
+        enabled: false,
+        apkDir: "android",
+        currentApkFile: "",
+    };
+}
+function normalizeAndroidApkConfig(input) {
+    if (!input || typeof input !== "object")
+        return undefined;
+    const defaults = defaultAndroidApkConfig();
+    const androidInput = input;
+    return {
+        enabled: typeof androidInput.enabled === "boolean" ? androidInput.enabled : defaults.enabled,
+        apkDir: typeof androidInput.apkDir === "string" && androidInput.apkDir.trim()
+            ? androidInput.apkDir.trim()
+            : defaults.apkDir,
+        currentApkFile: typeof androidInput.currentApkFile === "string"
+            ? androidInput.currentApkFile.trim()
+            : defaults.currentApkFile,
+    };
+}
 function normalizeStructuredChatPersona(input) {
     if (!input || typeof input !== "object")
         return undefined;
@@ -132,6 +178,11 @@ function mergeWithDefaults(input) {
             : defaults.commandPresets,
         structuredChatPersona: normalizeStructuredChatPersona(input.structuredChatPersona),
         language: typeof input.language === "string" ? input.language.trim() : defaults.language,
+        appSecret: typeof input.appSecret === "string" && input.appSecret.length >= 32
+            ? input.appSecret
+            : crypto.randomBytes(32).toString("hex"),
+        android: normalizeAndroidApkConfig(input.android) ?? defaults.android,
+        cardDefaults: normalizeCardDefaults(input.cardDefaults),
     };
 }
 export function isExecutionMode(value) {

package/dist/message-truncator.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Truncates tool_result content in messages for WebSocket transport.
+ * Cards that are collapsed by default have their large results replaced
+ * with a summary, and clients fetch full content on-demand via API.
+ */
+import type { CardExpandDefaults, ConversationTurn } from "./types.js";
+/**
+ * Truncate messages for WebSocket transport. Tool results for collapsed card
+ * types are replaced with a short summary when they exceed the threshold.
+ *
+ * @param messages - Original messages array (not mutated)
+ * @param cardDefaults - Current card expand defaults from config
+ * @param streamingTurnIndex - Index of the currently streaming turn (-1 if none).
+ *   Tool results in the streaming turn are never truncated.
+ */
+export declare function truncateMessagesForTransport(messages: ConversationTurn[], cardDefaults: CardExpandDefaults, streamingTurnIndex?: number): ConversationTurn[];

package/dist/message-truncator.js

@@ -0,0 +1,76 @@
+/**
+ * Truncates tool_result content in messages for WebSocket transport.
+ * Cards that are collapsed by default have their large results replaced
+ * with a summary, and clients fetch full content on-demand via API.
+ */
+const TRUNCATION_THRESHOLD = 200;
+const SUMMARY_LENGTH = 100;
+/** Tool name → cardDefaults field mapping */
+function isToolDefaultCollapsed(toolName, defaults) {
+    switch (toolName) {
+        case "Read":
+        case "Glob":
+        case "Grep":
+        case "WebFetch":
+        case "WebSearch":
+        case "TodoRead":
+            return defaults.inlineTools !== true;
+        case "Bash":
+            return defaults.terminal !== true;
+        case "Edit":
+        case "Write":
+        case "MultiEdit":
+            return defaults.editCards !== true;
+        default:
+            return false;
+    }
+}
+function getContentString(content) {
+    return typeof content === "string" ? content : JSON.stringify(content);
+}
+/**
+ * Truncate messages for WebSocket transport. Tool results for collapsed card
+ * types are replaced with a short summary when they exceed the threshold.
+ *
+ * @param messages - Original messages array (not mutated)
+ * @param cardDefaults - Current card expand defaults from config
+ * @param streamingTurnIndex - Index of the currently streaming turn (-1 if none).
+ *   Tool results in the streaming turn are never truncated.
+ */
+export function truncateMessagesForTransport(messages, cardDefaults, streamingTurnIndex = -1) {
+    return messages.map((turn, turnIndex) => {
+        // Never truncate the currently streaming turn
+        if (turnIndex === streamingTurnIndex)
+            return turn;
+        // Build tool_use_id → tool_name map from this turn's blocks
+        const toolNameMap = new Map();
+        for (const block of turn.content) {
+            if (block.type === "tool_use") {
+                toolNameMap.set(block.id, block.name);
+            }
+        }
+        let changed = false;
+        const truncatedContent = turn.content.map((block) => {
+            if (block.type !== "tool_result")
+                return block;
+            const result = block;
+            // Never truncate errors
+            if (result.is_error)
+                return block;
+            const toolName = toolNameMap.get(result.tool_use_id) || "";
+            if (!isToolDefaultCollapsed(toolName, cardDefaults))
+                return block;
+            const contentStr = getContentString(result.content);
+            if (contentStr.length <= TRUNCATION_THRESHOLD)
+                return block;
+            changed = true;
+            return {
+                ...result,
+                content: contentStr.slice(0, SUMMARY_LENGTH) + "…",
+                _truncated: true,
+                _originalSize: contentStr.length,
+            };
+        });
+        return changed ? { ...turn, content: truncatedContent } : turn;
+    });
+}

package/dist/process-manager.d.ts

@@ -45,6 +45,8 @@ export declare class ProcessManager extends EventEmitter {
         provider?: SessionProvider;
     }): SessionSnapshot;
     list(): SessionSnapshot[];
+    /** Return lightweight snapshots for the session list (no output/messages). */
+    listSlim(): SessionSnapshot[];
     hasClaudeSessionFile(cwd: string, claudeSessionId: string): boolean;
     private claudeHistoryCache;
     private static readonly HISTORY_CACHE_TTL_MS;
@@ -64,6 +66,8 @@ export declare class ProcessManager extends EventEmitter {
     private deleteClaudeCache;
     runStartupCommands(): SessionSnapshot[];
     private snapshot;
+    /** Lightweight snapshot for list views — omits output and messages. */
+    private snapshotSlim;
     private isPermissionBlocked;
     private defaultAutonomyPolicy;
     resolveEscalation(id: string, requestId: string, resolution?: "approve_once" | "approve_turn" | "deny"): SessionSnapshot;

package/dist/process-manager.js

@@ -8,6 +8,7 @@ import pty from "node-pty";
 import { SessionLogger } from "./session-logger.js";
 import { SessionLifecycleManager } from "./session-lifecycle.js";
 import { ClaudePtyBridge } from "./claude-pty-bridge.js";
+import { truncateMessagesForTransport } from "./message-truncator.js";
 import { appendWindow, hasExplicitConfirmSyntax, hasPermissionActionContext, normalizePromptText } from "./pty-text-utils.js";
 import { prepareSessionWorktree } from "./git-worktree.js";
 import { getResumeCommandSessionId, hasRealConversationMessages, } from "./resume-policy.js";
@@ -863,6 +864,13 @@ export class ProcessManager extends EventEmitter {
             .sort((a, b) => b.startedAt.localeCompare(a.startedAt))
             .map((session) => this.snapshot(session));
     }
+    /** Return lightweight snapshots for the session list (no output/messages). */
+    listSlim() {
+        this.archiveExpiredSessions();
+        return Array.from(this.sessions.values())
+            .sort((a, b) => b.startedAt.localeCompare(a.startedAt))
+            .map((session) => this.snapshotSlim(session));
+    }
     hasClaudeSessionFile(cwd, claudeSessionId) {
         return isClaudeSessionFileAvailable(cwd, claudeSessionId);
     }
@@ -1171,6 +1179,43 @@ export class ProcessManager extends EventEmitter {
             autoApprovePermissions: record.autoApprovePermissions || undefined,
             approvalStats: record.approvalStats.total > 0 ? record.approvalStats : undefined,
             summary: deriveSessionSummary(messages, record.currentTask?.title ?? null),
+            currentTaskTitle: record.status === "running" ? record.currentTask?.title ?? undefined : undefined,
+        };
+    }
+    /** Lightweight snapshot for list views — omits output and messages. */
+    snapshotSlim(record) {
+        const messages = record.ptyBridge?.getMessages() ?? record.messages;
+        return {
+            id: record.id,
+            sessionKind: "pty",
+            provider: record.provider,
+            runner: "pty",
+            command: record.command,
+            cwd: record.cwd,
+            mode: record.mode,
+            worktreeEnabled: record.worktreeEnabled ?? false,
+            worktree: record.worktree ?? null,
+            autonomyPolicy: record.autonomyPolicy,
+            approvalPolicy: record.approvalPolicy,
+            allowedScopes: record.allowedScopes,
+            status: record.status,
+            exitCode: record.exitCode,
+            startedAt: record.startedAt,
+            endedAt: record.endedAt,
+            output: "",
+            archived: record.archived,
+            archivedAt: record.archivedAt,
+            permissionBlocked: this.isPermissionBlocked(record),
+            pendingEscalation: record.pendingEscalation || undefined,
+            lastEscalationResult: record.lastEscalationResult || undefined,
+            claudeSessionId: record.claudeSessionId || null,
+            resumedFromSessionId: record.resumedFromSessionId ?? undefined,
+            resumedToSessionId: record.resumedToSessionId ?? undefined,
+            autoRecovered: record.autoRecovered ?? false,
+            autoApprovePermissions: record.autoApprovePermissions || undefined,
+            approvalStats: record.approvalStats.total > 0 ? record.approvalStats : undefined,
+            summary: deriveSessionSummary(messages, record.currentTask?.title ?? null),
+            currentTaskTitle: record.status === "running" ? record.currentTask?.title ?? undefined : undefined,
         };
     }
     isPermissionBlocked(record) {
@@ -1438,31 +1483,39 @@ export class ProcessManager extends EventEmitter {
             case "output.raw":
                 // Sync record.output from bridge before emitting so the event carries fresh data
                 record.output = record.ptyBridge?.getRawOutput() ?? record.output;
-                // Emit output event for terminal view
-                this.emitEvent({
-                    type: "output",
-                    sessionId: event.sessionId,
-                    data: {
-                        chunk: event.data.chunk,
-                        output: record.output,
-                        messages: record.ptyBridge?.getMessages(),
-                        permissionBlocked: this.isPermissionBlocked(record),
-                    },
-                });
+                {
+                    const rawMessages = record.ptyBridge?.getMessages() ?? [];
+                    const messages = truncateMessagesForTransport(rawMessages, this.config.cardDefaults ?? {}, rawMessages.length - 1);
+                    // Emit output event for terminal view
+                    this.emitEvent({
+                        type: "output",
+                        sessionId: event.sessionId,
+                        data: {
+                            chunk: event.data.chunk,
+                            output: record.output,
+                            messages,
+                            permissionBlocked: this.isPermissionBlocked(record),
+                        },
+                    });
+                }
                 break;
             case "output.chat":
                 // Sync record.output from bridge before emitting so the event carries fresh data
                 record.output = record.ptyBridge?.getRawOutput() ?? record.output;
-                // Emit output event with updated messages for chat view
-                this.emitEvent({
-                    type: "output",
-                    sessionId: event.sessionId,
-                    data: {
-                        output: record.output,
-                        messages: record.ptyBridge?.getMessages(),
-                        permissionBlocked: this.isPermissionBlocked(record),
-                    },
-                });
+                {
+                    const rawMessages = record.ptyBridge?.getMessages() ?? [];
+                    const messages = truncateMessagesForTransport(rawMessages, this.config.cardDefaults ?? {}, rawMessages.length - 1);
+                    // Emit output event with updated messages for chat view
+                    this.emitEvent({
+                        type: "output",
+                        sessionId: event.sessionId,
+                        data: {
+                            output: record.output,
+                            messages,
+                            permissionBlocked: this.isPermissionBlocked(record),
+                        },
+                    });
+                }
                 break;
             case "permission.prompt": {
                 const data = event.data;

package/dist/server-session-routes.js

@@ -71,6 +71,11 @@ function listAllSessions(processes, structured) {
     return [...structured.list(), ...processes.list()]
         .sort((a, b) => b.startedAt.localeCompare(a.startedAt));
 }
+/** Lightweight session list — omits output and messages to reduce payload. */
+function listAllSessionsSlim(processes, structured) {
+    return [...structured.listSlim(), ...processes.listSlim()]
+        .sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+}
 function requireWorktreeSession(snapshot) {
     if (!snapshot) {
         throw new Error("未找到该会话。");
@@ -133,7 +138,7 @@ function isMergeActionAllowed(snapshot) {
 }
 export function registerSessionRoutes(app, processes, structured, storage, defaultMode) {
     app.get("/api/sessions", (_req, res) => {
-        const all = listAllSessions(processes, structured);
+        const all = listAllSessionsSlim(processes, structured);
         console.log("[WAND] GET /api/sessions count:", all.length, "sessions:", all.map(s => ({ id: s.id.substring(0, 8), kind: s.sessionKind, runner: s.runner, status: s.status })));
         res.json(all);
     });
@@ -178,6 +183,29 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
             res.status(400).json({ error: getErrorMessage(error, "无法发送结构化消息。") });
         }
     });
+    // ── Tool content lazy-load endpoint ──
+    app.get("/api/sessions/:id/tool-content/:toolUseId", (req, res) => {
+        const snapshot = getSessionById(processes, structured, req.params.id);
+        if (!snapshot) {
+            res.status(404).json({ error: "未找到该会话。" });
+            return;
+        }
+        const toolUseId = req.params.toolUseId;
+        const messages = snapshot.messages ?? [];
+        for (const turn of messages) {
+            for (const block of turn.content) {
+                if (block.type === "tool_result" && block.tool_use_id === toolUseId) {
+                    res.json({
+                        tool_use_id: block.tool_use_id,
+                        content: block.content,
+                        is_error: block.is_error || false,
+                    });
+                    return;
+                }
+            }
+        }
+        res.status(404).json({ error: "未找到该工具结果。" });
+    });
     app.post("/api/sessions/:id/worktree/merge/check", (req, res) => {
         try {
             const current = requireWorktreeSession(getLatestSessionSnapshot(processes, structured, storage, req.params.id));