ms-vite-plugin 1.4.15 → 1.4.16

package/dist/cli.js

@@ -43,6 +43,12 @@ const project_1 = require("./project");
 const packager_1 = require("./packager");
 const ws_manager_1 = require("./ws-manager");
 const version_1 = require("./version");
+const docs_service_1 = require("./mcp/docs-service");
+const httpapi_docs_service_1 = require("./mcp/httpapi-docs-service");
+const tool_utils_1 = require("./mcp/tool-utils");
+const types_1 = require("./mcp/types");
+const ocr_tools_1 = require("./mcp/ocr-tools");
+const image_tools_1 = require("./mcp/image-tools");
 /**
  * WS 状态持久化文件路径（用于跨进程查询 ws-status）
  */
@@ -85,6 +91,366 @@ async function ensureValidKuaiJSProject(workspacePath) {
     console.error("  - scripts/ 目录");
     process.exit(1);
 }
+/**
+ * 解析整数参数
+ * @param value 用户传入的参数文本
+ * @param defaultValue 默认值
+ * @param name 参数名称
+ * @param min 最小值
+ * @param max 最大值
+ * @returns 返回校验后的整数
+ * @example
+ * parseCliInteger("20", 10, "limit", 1, 100)
+ */
+function parseCliInteger(value, defaultValue, name, min, max) {
+    const text = (value ?? String(defaultValue)).trim();
+    const numberValue = Number.parseInt(text, 10);
+    if (!Number.isInteger(numberValue) ||
+        numberValue < min ||
+        (max !== undefined && numberValue > max)) {
+        throw new Error(`无效 ${name}: ${text}，允许范围 ${min}${max === undefined ? "+" : `..${max}`}`);
+    }
+    return numberValue;
+}
+/**
+ * 解析浮点数参数
+ * @param value 用户传入的参数文本
+ * @param defaultValue 默认值
+ * @param name 参数名称
+ * @param min 最小值
+ * @param max 最大值
+ * @returns 返回校验后的数字
+ * @example
+ * parseCliNumber("0.6", 0.6, "confidence", 0, 1)
+ */
+function parseCliNumber(value, defaultValue, name, min, max) {
+    const text = (value ?? String(defaultValue)).trim();
+    const numberValue = Number.parseFloat(text);
+    if (!Number.isFinite(numberValue) || numberValue < min || numberValue > max) {
+        throw new Error(`无效 ${name}: ${text}，允许范围 ${min}..${max}`);
+    }
+    return numberValue;
+}
+/**
+ * 解析枚举参数
+ * @param value 用户传入的参数文本
+ * @param defaultValue 默认值
+ * @param choices 允许的取值
+ * @param name 参数名称
+ * @returns 返回校验后的枚举值
+ * @example
+ * parseCliChoice("json", "text", ["text", "json"], "format")
+ */
+function parseCliChoice(value, defaultValue, choices, name) {
+    const text = (value ?? defaultValue).trim();
+    if (!choices.includes(text)) {
+        throw new Error(`无效 ${name}: ${text}，可选值: ${choices.join("|")}`);
+    }
+    return text;
+}
+/**
+ * 解析文档语言参数
+ * @param value 用户传入的语言
+ * @returns 返回文档语言
+ * @example
+ * parseDocsLanguageOption("js_zh")
+ */
+function parseDocsLanguageOption(value) {
+    return parseCliChoice(value, "js_zh", ["js", "js_zh", "python"], "language");
+}
+/**
+ * 解析 HTTP API 请求方法
+ * @param value 用户传入的方法
+ * @returns 返回 HTTP API 方法
+ * @example
+ * parseHttpApiMethodOption("GET")
+ */
+function parseHttpApiMethodOption(value) {
+    const method = value?.trim().toUpperCase();
+    return parseCliChoice(method, "GET", ["GET", "POST"], "method");
+}
+/**
+ * 解析可选 HTTP API 请求方法
+ * @param value 用户传入的方法
+ * @returns 返回 HTTP API 方法或 undefined
+ * @example
+ * parseOptionalHttpApiMethodOption("POST")
+ */
+function parseOptionalHttpApiMethodOption(value) {
+    if (!value?.trim()) {
+        return undefined;
+    }
+    return parseHttpApiMethodOption(value);
+}
+/**
+ * 解析设备 HTTP 地址
+ * @param options 设备命令选项
+ * @returns 返回设备 HTTP 目标
+ * @example
+ * parseDeviceHttpTarget({ ip: "192.168.1.10", port: "9800" })
+ */
+function parseDeviceHttpTarget(options) {
+    const ip = options.ip?.trim();
+    if (!ip) {
+        throw new Error("请通过 --ip 指定设备 IP 地址");
+    }
+    const port = parseCliInteger(options.port, 9800, "port", 1, 65535);
+    return {
+        ip,
+        port: String(port),
+        label: `${ip}:${port}`,
+    };
+}
+/**
+ * 输出文本到终端或文件
+ * @param text 待输出文本
+ * @param output 用户指定输出路径
+ * @param savedLabel 保存成功提示
+ * @returns 输出完成后返回
+ * @example
+ * await writeOrPrintText("ok", "./out.txt", "结果已保存")
+ */
+async function writeOrPrintText(text, output, savedLabel) {
+    if (output?.trim()) {
+        const outputPath = path.resolve(output.trim());
+        await fsExtra.ensureDir(path.dirname(outputPath));
+        await fsExtra.writeFile(outputPath, text, "utf8");
+        console.log(`✅ ${savedLabel}: ${outputPath}`);
+        return;
+    }
+    console.log(text);
+}
+/**
+ * 格式化 API 文档摘要
+ * @param language 文档语言
+ * @param title 文档标题
+ * @param slug 文档 slug
+ * @param index 序号
+ * @param filePath 文档文件绝对路径
+ * @returns 返回摘要文本
+ * @example
+ * formatCliApiDocSummary("js_zh", "设备", "device", 0, "/tmp/device.md")
+ */
+function formatCliApiDocSummary(language, title, slug, index, filePath) {
+    return [
+        `${index + 1}. ${title}`,
+        `slug: ${slug}`,
+        `uri: ${(0, docs_service_1.getDocUri)(language, slug)}`,
+        ...(filePath ? [`path: ${filePath}`] : []),
+    ].join("\n");
+}
+/**
+ * 格式化 HTTP API 文档摘要
+ * @param entry HTTP API 文档条目
+ * @param index 序号
+ * @returns 返回摘要文本
+ * @example
+ * formatCliHttpApiDocSummary(entry, 0)
+ */
+function formatCliHttpApiDocSummary(entry, index) {
+    return [
+        `${index + 1}. ${entry.title}`,
+        `method: ${entry.method}`,
+        `path: ${entry.path}`,
+        `slug: ${entry.slug}`,
+        `section: ${entry.section || "未分组"}`,
+        `lines: ${entry.startLine}-${entry.endLine}`,
+        `file: ${entry.filePath}`,
+    ].join("\n");
+}
+/**
+ * 格式化 CLI 文档路径清单
+ * @returns 返回本地文档路径文本
+ * @example
+ * const text = formatCliDocsPathsText()
+ */
+function formatCliDocsPathsText() {
+    const languages = ["js", "js_zh", "python"];
+    return [
+        "KuaiJS 文档路径:",
+        `docsRoot: ${(0, docs_service_1.getDocsRootDir)()}`,
+        ...languages.map((language) => `${language}: ${(0, docs_service_1.getDocsDirByLanguage)(language)} (${types_1.DOC_LANGUAGE_LABELS[language]})`),
+        `httpApi: ${(0, httpapi_docs_service_1.getHttpApiDocPath)()}`,
+        "说明: 直接读取上述 markdown 路径；docs/http-docs 命令用于定位具体文档。",
+    ].join("\n");
+}
+/**
+ * 收集可重复字符串参数
+ * @param value 当前参数值
+ * @param previous 之前收集的值
+ * @returns 返回追加后的数组
+ * @example
+ * collectStringOption("登录", [])
+ */
+function collectStringOption(value, previous) {
+    previous.push(value);
+    return previous;
+}
+/**
+ * 解析字符串数组参数
+ * @param value 用户传入文本
+ * @param name 参数名
+ * @returns 返回字符串数组或 undefined
+ * @example
+ * parseStringArrayOption("zh-Hans,en-US", "languages")
+ */
+function parseStringArrayOption(value, name) {
+    const text = value?.trim();
+    if (!text) {
+        return undefined;
+    }
+    if (text.startsWith("[")) {
+        const parsed = JSON.parse(text);
+        if (!Array.isArray(parsed) ||
+            !parsed.every((item) => typeof item === "string" && item.trim())) {
+            throw new Error(`${name} 必须是字符串数组。`);
+        }
+        return parsed.map((item) => item.trim());
+    }
+    const items = text
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+    if (items.length === 0) {
+        throw new Error(`${name} 不能为空。`);
+    }
+    return items;
+}
+/**
+ * 解析 Apple OCR 语言数组
+ * @param value 用户传入语言文本
+ * @returns 返回语言数组或 undefined
+ * @example
+ * parseAppleOcrLanguages("zh-Hans,en-US")
+ */
+function parseAppleOcrLanguages(value) {
+    const languages = parseStringArrayOption(value, "languages");
+    if (!languages) {
+        return undefined;
+    }
+    const allowed = new Set(ocr_tools_1.APPLE_OCR_LANGUAGES);
+    const invalid = languages.filter((language) => !allowed.has(language));
+    if (invalid.length > 0) {
+        throw new Error(`无效 languages: ${invalid.join(", ")}，可选值: ${ocr_tools_1.APPLE_OCR_LANGUAGES.join(", ")}`);
+    }
+    return languages;
+}
+/**
+ * 解析 JSON 对象参数
+ * @param value 用户传入 JSON 文本
+ * @param name 参数名
+ * @returns 返回对象或 undefined
+ * @example
+ * parseJsonRecordOption('{"x":1}', "query")
+ */
+function parseJsonRecordOption(value, name) {
+    const text = value?.trim();
+    if (!text) {
+        return undefined;
+    }
+    const parsed = JSON.parse(text);
+    if (!parsed ||
+        typeof parsed !== "object" ||
+        Array.isArray(parsed) ||
+        !Object.values(parsed).every((item) => typeof item === "string" ||
+            typeof item === "number" ||
+            typeof item === "boolean" ||
+            item === null)) {
+        throw new Error(`${name} 必须是 JSON 对象，且值只能是 string/number/boolean/null。`);
+    }
+    return parsed;
+}
+/**
+ * 解析 JSON 请求体参数
+ * @param value 用户传入请求体文本
+ * @returns 返回 JSON 值或 undefined
+ * @example
+ * parseJsonBodyOption('{"x":1}')
+ */
+function parseJsonBodyOption(value) {
+    const text = value?.trim();
+    if (text === undefined || text.length === 0) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * 标准化 HTTP API 路径
+ * @param apiPath 用户传入路径
+ * @returns 返回相对路径
+ * @example
+ * normalizeCliHttpApiPath("/api/status")
+ */
+function normalizeCliHttpApiPath(apiPath) {
+    const normalizedPath = apiPath.trim();
+    if (/^https?:\/\//i.test(normalizedPath)) {
+        throw new Error("path 只能传 HTTP API 相对路径，不能传完整 URL。");
+    }
+    if (!normalizedPath.startsWith("/")) {
+        throw new Error("path 必须以 / 开头，例如 /api/status。");
+    }
+    if (normalizedPath.includes("?")) {
+        throw new Error("path 不能包含 query string，请使用 --query 传递查询参数。");
+    }
+    return normalizedPath;
+}
+/**
+ * 追加 HTTP query 参数
+ * @param url 目标 URL
+ * @param query query 参数
+ * @returns 无返回值
+ * @example
+ * appendCliQueryParams(url, { x: 1 })
+ */
+function appendCliQueryParams(url, query) {
+    if (!query) {
+        return;
+    }
+    for (const [key, value] of Object.entries(query)) {
+        if (value === null) {
+            continue;
+        }
+        url.searchParams.set(key, String(value));
+    }
+}
+/**
+ * 创建 HTTP API 请求体
+ * @param body 用户传入请求体
+ * @returns 返回 fetch 请求体和头
+ * @example
+ * createCliHttpRequestBody({ x: 1 })
+ */
+function createCliHttpRequestBody(body) {
+    if (body === undefined) {
+        return {};
+    }
+    return {
+        headers: {
+            "Content-Type": "application/json",
+        },
+        requestBody: JSON.stringify(body),
+    };
+}
+/**
+ * 读取 HTTP API 响应文本
+ * @param response fetch 响应
+ * @param responseFormat 响应格式
+ * @returns 返回格式化文本
+ * @example
+ * await readCliHttpApiResponseText(response, "json")
+ */
+async function readCliHttpApiResponseText(response, responseFormat) {
+    const responseText = await response.text();
+    if (responseFormat === "text") {
+        return responseText;
+    }
+    return (0, tool_utils_1.formatRuntimeJsonText)(JSON.parse(responseText));
+}
 /**
  * 构建命令处理函数
  * @param options 命令选项
@@ -175,8 +541,6 @@ async function runUICommand(options) {
  */
 async function stopCommand(options) {
     try {
-        const workspacePath = process.cwd();
-        await ensureValidKuaiJSProject(workspacePath);
         await (0, project_1.stopOnDevice)(options);
     }
     catch (error) {
@@ -193,7 +557,6 @@ async function stopCommand(options) {
  */
 async function screenshotCommand(options) {
     try {
-        await ensureValidKuaiJSProject(process.cwd());
         const format = options.format ?? "file";
         if (format === "base64") {
             const base64 = await (0, project_1.getScreenshotBase64OnDevice)(options);
@@ -218,22 +581,26 @@ async function screenshotCommand(options) {
  * @param options 命令选项
  * @returns 请求完成后退出
  * @example
- * ms source --ip 192.168.1.100 --port 9800 --max-depth 50 --timeout 120
+ * ms source --ip 192.168.1.100 --port 9800 --max-depth 50 --timeout 120 --mode 1
  */
 async function sourceCommand(options) {
     try {
-        await ensureValidKuaiJSProject(process.cwd());
         const maxDepthText = (options.maxDepth ?? "50").trim();
         const timeoutText = (options.timeout ?? "120").trim();
+        const modeText = (options.mode ?? "1").trim();
         const maxDepth = Number.parseInt(maxDepthText, 10);
         const timeout = Number.parseInt(timeoutText, 10);
+        const mode = Number.parseInt(modeText, 10);
         if (!Number.isInteger(maxDepth) || maxDepth < 1) {
             throw new Error(`无效 max-depth: ${maxDepthText}`);
         }
         if (!Number.isInteger(timeout) || timeout < 1) {
             throw new Error(`无效 timeout: ${timeoutText}`);
         }
-        const source = await (0, project_1.getSourceOnDevice)(options, maxDepth, timeout);
+        if (!Number.isInteger(mode) || (mode !== 1 && mode !== 2)) {
+            throw new Error(`无效 mode: ${modeText}`);
+        }
+        const source = await (0, project_1.getSourceOnDevice)(options, maxDepth, timeout, mode);
         if (options.output?.trim()) {
             const outputPath = path.resolve(options.output.trim());
             await fsExtra.ensureDir(path.dirname(outputPath));
@@ -248,6 +615,482 @@ async function sourceCommand(options) {
         process.exit(1);
     }
 }
+/**
+ * logs 命令处理函数
+ * @param options 命令选项
+ * @returns 请求完成后退出
+ * @example
+ * ms logs --ip 192.168.1.100 --port 9800 --limit 200
+ */
+async function logsCommand(options) {
+    try {
+        const limit = parseCliInteger(options.limit, 200, "limit", 1, 5000);
+        const format = parseCliChoice(options.format, "text", ["text", "json"], "format");
+        const result = await (0, project_1.getCurrentLogLinesOnDevice)(options, limit);
+        const text = format === "json"
+            ? (0, tool_utils_1.formatRuntimeJsonText)(result)
+            : result.lines.length > 0
+                ? result.lines.join("\n")
+                : "无日志";
+        await writeOrPrintText(text, options.output, "日志已保存");
+        if (format === "text" && result.hasMore && !options.output?.trim()) {
+            console.error(`还有更早日志，可增大 --limit，当前最多 ${limit} 行。`);
+        }
+    }
+    catch (error) {
+        console.error("❌ 获取日志失败:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+/**
+ * docs list 命令处理函数
+ * @param options 命令选项
+ * @returns 请求完成后退出
+ * @example
+ * ms docs list --language js_zh
+ */
+async function docsListCommand(options) {
+    try {
+        const language = parseDocsLanguageOption(options.language);
+        const docs = await (0, docs_service_1.getApiDocsByLanguage)(language);
+        const lines = docs.map((doc, index) => formatCliApiDocSummary(language, doc.title, doc.slug, index, doc.filePath));
+        const text = [
+            `文档语言: ${language} (${types_1.DOC_LANGUAGE_LABELS[language]})`,
+            "",
+            ...(lines.length > 0 ? lines : ["无可用文档"]),
+        ].join("\n");
+        await writeOrPrintText(text, options.output, "文档列表已保存");
+    }
+    catch (error) {
+        console.error("❌ 列出文档失败:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+/**
+ * docs paths 命令处理函数
+ * @param options 命令选项
+ * @returns 请求完成后退出
+ * @example
+ * ms docs paths
+ */
+async function docsPathsCommand(options) {
+    try {
+        await writeOrPrintText(formatCliDocsPathsText(), options.output, "文档路径已保存");
+    }
+    catch (error) {
+        console.error("❌ 输出文档路径失败:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+/**
+ * docs search 命令处理函数
+ * @param query 搜索词
+ * @param options 命令选项
+ * @returns 请求完成后退出
+ * @example
+ * ms docs search 点击 --language js_zh --limit 5
+ */
+async function docsSearchCommand(query, options) {
+    try {
+        const language = parseDocsLanguageOption(options.language);
+        const limit = parseCliInteger(options.limit, 5, "limit", 1, 20);
+        const normalizedQuery = query.toLowerCase();
+        const docs = await (0, docs_service_1.getApiDocsByLanguage)(language);
+        const matches = docs
+            .map((doc) => ({ doc, score: (0, docs_service_1.scoreApiDoc)(doc, normalizedQuery) }))
+            .filter((item) => item.score > 0)
+            .sort((a, b) => b.score - a.score || a.doc.slug.localeCompare(b.doc.slug))
+            .slice(0, limit)
+            .map((item) => item.doc);
+        const text = matches.length === 0
+            ? `文档语言: ${language} (${types_1.DOC_LANGUAGE_LABELS[language]})\n未找到与 "${query}" 匹配的文档。`
+            : [
+                `文档语言: ${language} (${types_1.DOC_LANGUAGE_LABELS[language]})`,
+                "",
+                ...matches.map((doc, index) => formatCliApiDocSummary(language, doc.title, doc.slug, index, doc.filePath)),
+            ].join("\n");
+        await writeOrPrintText(text, options.output, "文档搜索结果已保存");
+    }
+    catch (error) {
+        console.error("❌ 搜索文档失败:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+/**
+ * docs read 命令处理函数
+ * @param slug 文档 slug
+ * @param options 命令选项
+ * @returns 请求完成后退出
+ * @example
+ * ms docs read action --language js_zh
+ */
+async function docsReadCommand(slug, options) {
+    try {
+        const language = parseDocsLanguageOption(options.language);
+        const docs = await (0, docs_service_1.getApiDocsByLanguage)(language);
+        const target = docs.find((doc) => doc.slug === slug);
+        if (!target) {
+            throw new Error(`未找到文档 ${slug}.md（语言: ${language}）。`);
+        }
+        const text = [
+            `标题: ${target.title}`,
+            `语言: ${language}`,
+            `URI: ${(0, docs_service_1.getDocUri)(language, target.slug)}`,
+            `path: ${target.filePath}`,
+            "",
+            target.content,
+        ].join("\n");
+        await writeOrPrintText(text, options.output, "文档已保存");
+    }
+    catch (error) {
+        console.error("❌ 读取文档失败:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+/**
+ * http-docs list 命令处理函数
+ * @param options 命令选项
+ * @returns 请求完成后退出
+ * @example
+ * ms http-docs list
+ */
+async function httpDocsListCommand(options) {
+    try {
+        const entries = await (0, httpapi_docs_service_1.getHttpApiDocEntries)();
+        const text = [
+            "HTTP API 文档列表:",
+            "",
+            ...entries.map((entry, index) => formatCliHttpApiDocSummary(entry, index)),
+        ].join("\n");
+        await writeOrPrintText(text, options.output, "HTTP API 文档列表已保存");
+    }
+    catch (error) {
+        console.error("❌ 列出 HTTP API 文档失败:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+/**
+ * http-docs search 命令处理函数
+ * @param query 搜索词
+ * @param options 命令选项
+ * @returns 请求完成后退出
+ * @example
+ * ms http-docs search 截图 --limit 8
+ */
+async function httpDocsSearchCommand(query, options) {
+    try {
+        const limit = parseCliInteger(options.limit, 8, "limit", 1, 20);
+        const normalizedQuery = query.toLowerCase();
+        const entries = await (0, httpapi_docs_service_1.getHttpApiDocEntries)();
+        const matches = entries
+            .map((entry) => ({
+            entry,
+            score: (0, httpapi_docs_service_1.scoreHttpApiDocEntry)(entry, normalizedQuery),
+        }))
+            .filter((item) => item.score > 0)
+            .sort((a, b) => b.score - a.score ||
+            a.entry.path.localeCompare(b.entry.path) ||
+            a.entry.method.localeCompare(b.entry.method))
+            .slice(0, limit)
+            .map((item) => item.entry);
+        const text = matches.length === 0
+            ? `未找到与 "${query}" 匹配的 HTTP API 文档。`
+            : [
+                "HTTP API 文档匹配结果:",
+                "",
+                ...matches.map((entry, index) => formatCliHttpApiDocSummary(entry, index)),
+            ].join("\n");
+        await writeOrPrintText(text, options.output, "HTTP API 文档搜索结果已保存");
+    }
+    catch (error) {
+        console.error("❌ 搜索 HTTP API 文档失败:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+/**
+ * http-docs read 命令处理函数
+ * @param identifier slug 或接口路径
+ * @param options 命令选项
+ * @returns 请求完成后退出
+ * @example
+ * ms http-docs read /api/source --method GET
+ */
+async function httpDocsReadCommand(identifier, options) {
+    try {
+        const method = parseOptionalHttpApiMethodOption(options.method);
+        const entry = await (0, httpapi_docs_service_1.findHttpApiDocEntry)(identifier, method);
+        if (!entry) {
+            throw new Error(`未找到 HTTP API 文档: ${identifier}`);
+        }
+        const text = [
+            `title: ${entry.title}`,
+            `method: ${entry.method}`,
+            `path: ${entry.path}`,
+            `slug: ${entry.slug}`,
+            `section: ${entry.section || "未分组"}`,
+            `lines: ${entry.startLine}-${entry.endLine}`,
+            `file: ${entry.filePath}`,
+            "",
+            entry.content,
+        ].join("\n");
+        await writeOrPrintText(text, options.output, "HTTP API 文档已保存");
+    }
+    catch (error) {
+        console.error("❌ 读取 HTTP API 文档失败:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+/**
+ * http-call 命令处理函数
+ * @param options 命令选项
+ * @returns 请求完成后退出
+ * @example
+ * ms http-call --ip 192.168.1.100 --method GET --path /api/status --doc-slug get-api-status
+ */
+async function httpCallCommand(options) {
+    try {
+        const target = parseDeviceHttpTarget(options);
+        const method = parseHttpApiMethodOption(options.method);
+        const apiPath = normalizeCliHttpApiPath(options.path ?? "");
+        const docSlug = options.docSlug?.trim();
+        if (!docSlug) {
+            throw new Error("请通过 --doc-slug 指定 HTTP API 文档 slug。");
+        }
+        const entry = await (0, httpapi_docs_service_1.findHttpApiDocEntry)(docSlug);
+        if (!entry) {
+            throw new Error(`HTTP API 文档中不存在该 docSlug: ${docSlug}`);
+        }
+        if (entry.method !== method || entry.path !== apiPath) {
+            throw new Error(`HTTP API 调用与文档条目不匹配。传入 ${method} ${apiPath}，文档 ${entry.method} ${entry.path}。`);
+        }
+        const query = parseJsonRecordOption(options.query, "query");
+        const body = parseJsonBodyOption(options.body);
+        if (method === "GET" && body !== undefined) {
+            throw new Error("GET 接口不能传 body，请使用 --query。");
+        }
+        const responseFormat = parseCliChoice(options.responseFormat, "json", ["json", "text"], "response-format");
+        const timeoutMs = parseCliInteger(options.timeoutMs, 30000, "timeout-ms", 1000, 600000);
+        const url = new URL(`http://${target.ip}:${target.port}${apiPath}`);
+        appendCliQueryParams(url, query);
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const { headers, requestBody } = createCliHttpRequestBody(body);
+            const response = await fetch(url.toString(), {
+                method,
+                signal: controller.signal,
+                headers,
+                body: requestBody,
+            });
+            const responseText = await readCliHttpApiResponseText(response, responseFormat);
+            const text = [
+                `HTTP API 调用${response.ok ? "成功" : "失败"}: ${method} ${apiPath}`,
+                `设备: ${target.label}`,
+                `文档: ${entry.title} (${entry.slug}, lines ${entry.startLine}-${entry.endLine})`,
+                `状态码: ${response.status}`,
+                "",
+                responseText,
+            ].join("\n");
+            await writeOrPrintText(text, options.output, "HTTP API 响应已保存");
+            if (!response.ok) {
+                process.exit(1);
+            }
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error && error.name === "AbortError"
+            ? "请求超时"
+            : error instanceof Error
+                ? error.message
+                : String(error);
+        console.error("❌ HTTP API 调用失败:", message);
+        process.exit(1);
+    }
+}
+/**
+ * ocr 命令处理函数
+ * @param options 命令选项
+ * @returns 请求完成后退出
+ * @example
+ * ms ocr --ip 192.168.1.100 --mode recognize
+ */
+async function ocrCommand(options) {
+    try {
+        const target = parseDeviceHttpTarget(options);
+        const engine = parseCliChoice(options.engine, "appleocr", ["appleocr", "paddleocr"], "engine");
+        const mode = parseCliChoice(options.mode, "recognize", ["recognize", "numbers", "findText"], "mode");
+        const input = options.input?.trim() || "screen";
+        const x = parseCliInteger(options.x, 0, "x", 0);
+        const y = parseCliInteger(options.y, 0, "y", 0);
+        const ex = parseCliInteger(options.ex, 0, "ex", 0);
+        const ey = parseCliInteger(options.ey, 0, "ey", 0);
+        const textItems = [
+            ...(parseStringArrayOption(options.texts, "texts") ?? []),
+            ...(options.text ?? []),
+        ];
+        const texts = textItems.length > 0 ? textItems : undefined;
+        const languages = parseAppleOcrLanguages(options.languages);
+        const confidenceThreshold = parseCliNumber(options.confidenceThreshold, 0.6, "confidence-threshold", 0, 1);
+        const timeoutMs = parseCliInteger(options.timeoutMs, 60000, "timeout-ms", 1000, 600000);
+        const format = parseCliChoice(options.format, "summary", ["summary", "json"], "format");
+        const result = await (0, ocr_tools_1.runOcrRecognitionOnDevice)(target, {
+            engine,
+            mode,
+            input,
+            x,
+            y,
+            ex,
+            ey,
+            texts,
+            languages,
+            confidenceThreshold,
+            exactMatch: options.exactMatch === true,
+            outputPath: format === "summary" ? options.output : undefined,
+            timeoutMs,
+        });
+        const text = format === "json" ? (0, tool_utils_1.formatRuntimeJsonText)(result.body) : result.text;
+        if (format === "json") {
+            await writeOrPrintText(text, options.output, "OCR 结果已保存");
+        }
+        else {
+            console.log([
+                text,
+                "",
+                `device: ${target.label}`,
+                `engine: ${engine}`,
+                `mode: ${mode}`,
+                `input: ${input}`,
+                `region: x=${x}, y=${y}, ex=${ex}, ey=${ey}`,
+                `status: ${result.status}`,
+            ].join("\n"));
+        }
+        if (result.body.success === false) {
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        console.error("❌ OCR 执行失败:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+/**
+ * image-crop 命令处理函数
+ * @param options 命令选项
+ * @returns 请求完成后退出
+ * @example
+ * ms image-crop --image ./screen.jpg --x 0 --y 0 --width 100 --height 100
+ */
+async function imageCropCommand(options) {
+    try {
+        const imagePath = options.image?.trim();
+        if (!imagePath) {
+            throw new Error("请通过 --image 指定输入图片路径。");
+        }
+        const x = parseCliInteger(options.x, 0, "x", 0);
+        const y = parseCliInteger(options.y, 0, "y", 0);
+        const width = parseCliInteger(options.width, 1, "width", 1);
+        const height = parseCliInteger(options.height, 1, "height", 1);
+        const text = await (0, image_tools_1.cropLocalImage)(imagePath, x, y, width, height, options.output);
+        console.log(text);
+    }
+    catch (error) {
+        console.error("❌ 图片裁切失败:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+/**
+ * screen-crop 命令处理函数
+ * @param options 命令选项
+ * @returns 请求完成后退出
+ * @example
+ * ms screen-crop -i 192.168.1.100 --x 0 --y 0 --width 100 --height 100
+ */
+async function screenCropCommand(options) {
+    try {
+        const target = parseDeviceHttpTarget(options);
+        const x = parseCliInteger(options.x, 0, "x", 0);
+        const y = parseCliInteger(options.y, 0, "y", 0);
+        const width = parseCliInteger(options.width, 1, "width", 1);
+        const height = parseCliInteger(options.height, 1, "height", 1);
+        const text = await (0, image_tools_1.cropDeviceScreen)(target, x, y, width, height, options.output);
+        console.log(text);
+    }
+    catch (error) {
+        console.error("❌ 屏幕裁图失败:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+/**
+ * image-pick-color 命令处理函数
+ * @param options 命令选项
+ * @returns 请求完成后退出
+ * @example
+ * ms image-pick-color --image ./screen.jpg --x 10 --y 10
+ */
+async function imagePickColorCommand(options) {
+    try {
+        const imagePath = options.image?.trim();
+        if (!imagePath) {
+            throw new Error("请通过 --image 指定输入图片路径。");
+        }
+        const x = parseCliInteger(options.x, 0, "x", 0);
+        const y = parseCliInteger(options.y, 0, "y", 0);
+        const radius = parseCliInteger(options.radius, 0, "radius", 0, 20);
+        const text = await (0, image_tools_1.pickLocalImageColor)(imagePath, x, y, radius);
+        console.log(text);
+    }
+    catch (error) {
+        console.error("❌ 图片取色失败:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+/**
+ * screen-pick-color 命令处理函数
+ * @param options 命令选项
+ * @returns 请求完成后退出
+ * @example
+ * ms screen-pick-color -i 192.168.1.100 --x 10 --y 10
+ */
+async function screenPickColorCommand(options) {
+    try {
+        const target = parseDeviceHttpTarget(options);
+        const x = parseCliInteger(options.x, 0, "x", 0);
+        const y = parseCliInteger(options.y, 0, "y", 0);
+        const radius = parseCliInteger(options.radius, 0, "radius", 0, 20);
+        const text = await (0, image_tools_1.pickDeviceScreenColor)(target, x, y, radius);
+        console.log(text);
+    }
+    catch (error) {
+        console.error("❌ 屏幕取色失败:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+/**
+ * image-transparent 命令处理函数
+ * @param options 命令选项
+ * @returns 请求完成后退出
+ * @example
+ * ms image-transparent --image ./button.png --transparent-color "#ffffff"
+ */
+async function imageTransparentCommand(options) {
+    try {
+        const imagePath = options.image?.trim();
+        if (!imagePath) {
+            throw new Error("请通过 --image 指定输入图片路径。");
+        }
+        const sampleCorner = parseCliChoice(options.sampleCorner, "topLeft", ["topLeft", "topRight", "bottomLeft", "bottomRight"], "sample-corner");
+        const tolerance = parseCliInteger(options.tolerance, 24, "tolerance", 0, 441);
+        const text = await (0, image_tools_1.makeLocalImageTransparent)(imagePath, options.output, options.transparentColor, sampleCorner, tolerance);
+        console.log(text);
+    }
+    catch (error) {
+        console.error("❌ 透明图制作失败:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
 /**
  * ws-start 命令处理函数
  * @param options 命令选项
@@ -257,7 +1100,6 @@ async function sourceCommand(options) {
  */
 async function wsStartCommand(options) {
     try {
-        await ensureValidKuaiJSProject(process.cwd());
         const wsPortText = (options.wsPort ?? "31111").trim();
         const wsPort = Number.parseInt(wsPortText, 10);
         if (!Number.isInteger(wsPort) || wsPort < 1 || wsPort > 65535) {
@@ -319,7 +1161,6 @@ async function wsStartCommand(options) {
  */
 async function wsStopCommand() {
     try {
-        await ensureValidKuaiJSProject(process.cwd());
         if (!(await fsExtra.pathExists(WS_PID_FILE))) {
             console.log("WS 服务未运行");
             return;
@@ -351,7 +1192,6 @@ async function wsStopCommand() {
  * ms ws-status
  */
 async function wsStatusCommand() {
-    await ensureValidKuaiJSProject(process.cwd());
     if (!(await fsExtra.pathExists(WS_PID_FILE))) {
         console.log(JSON.stringify({
             status: "stopped",
@@ -496,8 +1336,161 @@ commander_1.program
     .option("--ws-wait-ms <wsWaitMs>", "WS 等待设备连接时间(毫秒)", "30000")
     .option("--max-depth <maxDepth>", "节点最大深度", "50")
     .option("--timeout <timeout>", "节点抓取超时秒数", "120")
+    .option("--mode <mode>", "节点抓取模式: 1=模式1, 2=模式2", "1")
     .option("--output <output>", "节点 XML 输出文件路径（可选）")
     .action(sourceCommand);
+// 日志命令
+commander_1.program
+    .command("logs")
+    .description("获取设备当前日志最新行")
+    .option("-i, --ip <ip>", "设备 IP 地址")
+    .option("--port <port>", "设备端口", "9800")
+    .option("--limit <limit>", "读取最新日志行数，范围 1..5000", "200")
+    .option("--format <format>", "返回格式: text|json", "text")
+    .option("--output <output>", "日志输出文件路径（可选）")
+    .action(logsCommand);
+// OCR 命令
+commander_1.program
+    .command("ocr")
+    .description("在设备上执行 OCR 识别")
+    .option("-i, --ip <ip>", "设备 IP 地址")
+    .option("--port <port>", "设备端口", "9800")
+    .option("--engine <engine>", "OCR 引擎: appleocr|paddleocr", "appleocr")
+    .option("--mode <mode>", "OCR 模式: recognize|numbers|findText", "recognize")
+    .option("--input <input>", '输入源，默认 "screen"', "screen")
+    .option("--x <x>", "区域左上角 x", "0")
+    .option("--y <y>", "区域左上角 y", "0")
+    .option("--ex <ex>", "区域右下角 x；全屏可传 0", "0")
+    .option("--ey <ey>", "区域右下角 y；全屏可传 0", "0")
+    .option("--text <text>", "findText 文本，可重复", collectStringOption, [])
+    .option("--texts <texts>", "findText 文本数组，支持 JSON 数组或逗号分隔")
+    .option("--languages <languages>", "Apple OCR 语言，支持 JSON 数组或逗号分隔")
+    .option("--exact-match", "findText 要求完整匹配文本")
+    .option("--confidence-threshold <confidenceThreshold>", "PaddleOCR 置信度阈值", "0.6")
+    .option("--timeout-ms <timeoutMs>", "请求超时时间(毫秒)", "60000")
+    .option("--format <format>", "返回格式: summary|json", "summary")
+    .option("--output <output>", "OCR 输出文件路径（可选）")
+    .action(ocrCommand);
+// 本地图片裁切命令
+commander_1.program
+    .command("image-crop")
+    .description("裁切本地图片并输出 PNG")
+    .requiredOption("--image <image>", "输入图片路径")
+    .option("--x <x>", "裁切起点 x", "0")
+    .option("--y <y>", "裁切起点 y", "0")
+    .requiredOption("--width <width>", "裁切宽度")
+    .requiredOption("--height <height>", "裁切高度")
+    .option("--output <output>", "输出 PNG 路径（可选）")
+    .action(imageCropCommand);
+// 设备截图裁切命令
+commander_1.program
+    .command("screen-crop")
+    .description("从设备截图中裁切 PNG")
+    .option("-i, --ip <ip>", "设备 IP 地址")
+    .option("--port <port>", "设备端口", "9800")
+    .option("--x <x>", "裁切起点 x", "0")
+    .option("--y <y>", "裁切起点 y", "0")
+    .requiredOption("--width <width>", "裁切宽度")
+    .requiredOption("--height <height>", "裁切高度")
+    .option("--output <output>", "输出 PNG 路径（可选）")
+    .action(screenCropCommand);
+// 本地图片取色命令
+commander_1.program
+    .command("image-pick-color")
+    .description("读取本地图片指定坐标颜色")
+    .requiredOption("--image <image>", "输入图片路径")
+    .option("--x <x>", "目标坐标 x", "0")
+    .option("--y <y>", "目标坐标 y", "0")
+    .option("--radius <radius>", "采样半径，范围 0..20", "0")
+    .action(imagePickColorCommand);
+// 设备截图取色命令
+commander_1.program
+    .command("screen-pick-color")
+    .description("读取设备截图指定坐标颜色")
+    .option("-i, --ip <ip>", "设备 IP 地址")
+    .option("--port <port>", "设备端口", "9800")
+    .option("--x <x>", "目标坐标 x", "0")
+    .option("--y <y>", "目标坐标 y", "0")
+    .option("--radius <radius>", "采样半径，范围 0..20", "0")
+    .action(screenPickColorCommand);
+// 本地图片透明化命令
+commander_1.program
+    .command("image-transparent")
+    .description("将图片中接近指定颜色或角落背景色的像素设为透明")
+    .requiredOption("--image <image>", "输入图片路径")
+    .option("--output <output>", "输出 PNG 路径（可选）")
+    .option("--transparent-color <transparentColor>", "透明化颜色，格式 #RRGGBB")
+    .option("--sample-corner <sampleCorner>", "未传 transparent-color 时采样角落: topLeft|topRight|bottomLeft|bottomRight", "topLeft")
+    .option("--tolerance <tolerance>", "RGB 欧氏距离容差，范围 0..441", "24")
+    .action(imageTransparentCommand);
+// API 文档命令
+const docsCommand = commander_1.program
+    .command("docs")
+    .description("查询 KuaiJS JS/中文/Python API 文档");
+docsCommand
+    .command("paths")
+    .description("显示 KuaiJS 本地文档路径")
+    .option("--output <output>", "输出文件路径（可选）")
+    .action(docsPathsCommand);
+docsCommand
+    .command("list")
+    .description("列出 API 文档")
+    .option("--language <language>", "文档语言: js|js_zh|python", "js_zh")
+    .option("--output <output>", "输出文件路径（可选）")
+    .action(docsListCommand);
+docsCommand
+    .command("search")
+    .description("搜索 API 文档")
+    .argument("<query>", "搜索关键字")
+    .option("--language <language>", "文档语言: js|js_zh|python", "js_zh")
+    .option("--limit <limit>", "返回条数上限，范围 1..20", "5")
+    .option("--output <output>", "输出文件路径（可选）")
+    .action(docsSearchCommand);
+docsCommand
+    .command("read")
+    .description("读取 API 文档")
+    .argument("<slug>", "文档 slug（文件名，不含 .md）")
+    .option("--language <language>", "文档语言: js|js_zh|python", "js_zh")
+    .option("--output <output>", "输出文件路径（可选）")
+    .action(docsReadCommand);
+// HTTP API 文档命令
+const httpDocsCommand = commander_1.program
+    .command("http-docs")
+    .description("查询 KuaiJS 设备 HTTP API 文档");
+httpDocsCommand
+    .command("list")
+    .description("列出 HTTP API 文档条目")
+    .option("--output <output>", "输出文件路径（可选）")
+    .action(httpDocsListCommand);
+httpDocsCommand
+    .command("search")
+    .description("搜索 HTTP API 文档")
+    .argument("<query>", "搜索关键字、标题或接口路径")
+    .option("--limit <limit>", "返回条数上限，范围 1..20", "8")
+    .option("--output <output>", "输出文件路径（可选）")
+    .action(httpDocsSearchCommand);
+httpDocsCommand
+    .command("read")
+    .description("读取 HTTP API 文档条目")
+    .argument("<identifier>", "接口 slug 或 path")
+    .option("--method <method>", "HTTP 方法，用于同路径多方法时消歧: GET|POST")
+    .option("--output <output>", "输出文件路径（可选）")
+    .action(httpDocsReadCommand);
+// HTTP API 调用命令
+commander_1.program
+    .command("http-call")
+    .description("按 HTTP API 文档声明调用设备接口")
+    .option("-i, --ip <ip>", "设备 IP 地址")
+    .option("--port <port>", "设备端口", "9800")
+    .requiredOption("--method <method>", "HTTP 方法: GET|POST")
+    .requiredOption("--path <path>", "HTTP API 相对路径，例如 /api/status")
+    .requiredOption("--doc-slug <docSlug>", "http-docs 返回的接口 slug")
+    .option("--query <query>", "JSON 对象 query 参数")
+    .option("--body <body>", "JSON 请求体；普通字符串会作为 JSON 字符串提交")
+    .option("--response-format <responseFormat>", "响应格式: json|text", "json")
+    .option("--timeout-ms <timeoutMs>", "请求超时时间(毫秒)", "30000")
+    .option("--output <output>", "响应输出文件路径（可选）")
+    .action(httpCallCommand);
 // WS 服务启动命令
 commander_1.program
     .command("ws-start")