harmony-build 0.2.0

package/dist/packages/mcp-common/src/mcp-helpers.js

@@ -0,0 +1,94 @@
+/**
+ * MCP 服务器通用脚手架：
+ *   - registerTools(server, defs)：声明式地一次性注册 ListTools / CallTool 两个处理器
+ *   - zodToJsonSchema：把 zod 对象转成 MCP 需要的 JSON Schema（仅支持本项目用到的子集）
+ *   - ok(data) / fail(err)：MCP tool 响应的便捷构造器
+ *
+ * 该模块只依赖 zod 的类型；@modelcontextprotocol/sdk 由调用方注入，避免 common 强耦合。
+ */
+import { z } from "zod";
+import { toErrorPayload } from "./errors.js";
+export function registerTools(server, deps, tools) {
+    const byName = new Map(tools.map((t) => [t.name, t]));
+    server.setRequestHandler(deps.ListToolsRequestSchema, async () => ({
+        tools: tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: zodToJsonSchema(t.schema),
+        })),
+    }));
+    server.setRequestHandler(deps.CallToolRequestSchema, async (req) => {
+        const r = req;
+        const tool = byName.get(r.params.name);
+        if (!tool)
+            return fail({ code: "UNKNOWN_TOOL", message: `unknown tool: ${r.params.name}` });
+        try {
+            const parsed = tool.schema.parse(r.params.arguments ?? {});
+            const data = await tool.handler(parsed);
+            return ok(data);
+        }
+        catch (err) {
+            return fail(toErrorPayload(err));
+        }
+    });
+}
+export function ok(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+export function fail(payload) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    };
+}
+export function zodToJsonSchema(schema) {
+    const shape = schema.shape;
+    const properties = {};
+    const required = [];
+    for (const [key, value] of Object.entries(shape)) {
+        const meta = describeZod(value);
+        properties[key] = meta.schema;
+        if (meta.required)
+            required.push(key);
+    }
+    return { type: "object", properties, ...(required.length ? { required } : {}) };
+}
+function describeZod(t) {
+    const description = t._def.description;
+    let required = true;
+    let inner = t;
+    // 注意：unwrap 顺序无所谓，循环到稳定为止
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        if (inner instanceof z.ZodDefault) {
+            required = false;
+            inner = inner._def.innerType;
+            continue;
+        }
+        if (inner instanceof z.ZodOptional) {
+            required = false;
+            inner = inner._def.innerType;
+            continue;
+        }
+        break;
+    }
+    let schema;
+    if (inner instanceof z.ZodString)
+        schema = { type: "string" };
+    else if (inner instanceof z.ZodNumber)
+        schema = { type: "number" };
+    else if (inner instanceof z.ZodBoolean)
+        schema = { type: "boolean" };
+    else if (inner instanceof z.ZodEnum)
+        schema = { type: "string", enum: inner.options };
+    else if (inner instanceof z.ZodArray)
+        schema = { type: "array" };
+    else
+        schema = {};
+    if (description)
+        schema.description = description;
+    return { schema, required };
+}
+//# sourceMappingURL=mcp-helpers.js.map

package/dist/packages/mcp-common/src/mcp-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-helpers.js","sourceRoot":"","sources":["../../../../packages/mcp-common/src/mcp-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAkB7C,MAAM,UAAU,aAAa,CAC3B,MAAqB,EACrB,IAAuB,EACvB,KAA4C;IAE5C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAEtD,MAAM,CAAC,iBAAiB,CAAC,IAAI,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QACjE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACvB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,WAAW,EAAE,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC;SACvC,CAAC,CAAC;KACJ,CAAC,CAAC,CAAC;IAEJ,MAAM,CAAC,iBAAiB,CAAC,IAAI,CAAC,qBAAqB,EAAE,KAAK,EAAE,GAAY,EAAE,EAAE;QAC1E,MAAM,CAAC,GAAG,GAAwD,CAAC;QACnE,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC5F,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;YAC3D,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACxC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;QACnC,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,EAAE,CAAC,IAAa;IAC9B,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KAC1E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,OAA6D;IAChF,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KAC7E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAkC;IAChE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC3B,MAAM,UAAU,GAA4B,EAAE,CAAC;IAC/C,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,GAAG,WAAW,CAAC,KAAqB,CAAC,CAAC;QAChD,UAAU,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;QAC9B,IAAI,IAAI,CAAC,QAAQ;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAClF,CAAC;AAED,SAAS,WAAW,CAAC,CAAe;IAClC,MAAM,WAAW,GAAI,CAAmD,CAAC,IAAI,CAAC,WAAW,CAAC;IAC1F,IAAI,QAAQ,GAAG,IAAI,CAAC;IACpB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,0BAA0B;IAC1B,iDAAiD;IACjD,OAAO,IAAI,EAAE,CAAC;QACZ,IAAI,KAAK,YAAY,CAAC,CAAC,UAAU,EAAE,CAAC;YAClC,QAAQ,GAAG,KAAK,CAAC;YACjB,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC;YAC7B,SAAS;QACX,CAAC;QACD,IAAI,KAAK,YAAY,CAAC,CAAC,WAAW,EAAE,CAAC;YACnC,QAAQ,GAAG,KAAK,CAAC;YACjB,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC;YAC7B,SAAS;QACX,CAAC;QACD,MAAM;IACR,CAAC;IACD,IAAI,MAA+B,CAAC;IACpC,IAAI,KAAK,YAAY,CAAC,CAAC,SAAS;QAAE,MAAM,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;SACzD,IAAI,KAAK,YAAY,CAAC,CAAC,SAAS;QAAE,MAAM,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;SAC9D,IAAI,KAAK,YAAY,CAAC,CAAC,UAAU;QAAE,MAAM,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;SAChE,IAAI,KAAK,YAAY,CAAC,CAAC,OAAO;QAAE,MAAM,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;SACjF,IAAI,KAAK,YAAY,CAAC,CAAC,QAAQ;QAAE,MAAM,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;;QAC5D,MAAM,GAAG,EAAE,CAAC;IACjB,IAAI,WAAW;QAAE,MAAM,CAAC,WAAW,GAAG,WAAW,CAAC;IAClD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC9B,CAAC"}

package/dist/packages/mcp-common/src/safe-exec.d.ts

@@ -0,0 +1,23 @@
+export interface RunOptions {
+    /** 工作目录，默认 process.cwd() */
+    cwd?: string;
+    /** 超时，毫秒；默认 60_000；0 表示不超时 */
+    timeoutMs?: number;
+    /** 注入的环境变量（与 process.env 合并） */
+    env?: Record<string, string>;
+    /** stdout/stderr 单流最大字节数；超出截断；默认 1MB */
+    maxBytes?: number;
+    /** 标准输入文本，可选 */
+    stdin?: string;
+}
+export interface RunResult {
+    command: string;
+    args: string[];
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+    truncated: boolean;
+}
+export declare function runCommand(command: string, args?: string[], options?: RunOptions): Promise<RunResult>;

package/dist/packages/mcp-common/src/safe-exec.js

@@ -0,0 +1,74 @@
+/**
+ * 安全的进程执行封装：
+ * - 不经过 shell（避免命令注入）
+ * - 强制 timeout
+ * - 截断超长输出
+ * - 命令白名单（外层调用方控制）
+ */
+import { spawn } from "node:child_process";
+import { HarmonyMcpError } from "./errors.js";
+const DEFAULT_TIMEOUT = 60_000;
+const DEFAULT_MAX_BYTES = 1024 * 1024;
+export async function runCommand(command, args = [], options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT;
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const started = Date.now();
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: { ...process.env, ...(options.env ?? {}) },
+            shell: false,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let truncated = false;
+        let timer;
+        const onData = (which) => (chunk) => {
+            const cur = which === "stdout" ? stdout : stderr;
+            if (Buffer.byteLength(cur, "utf8") >= maxBytes) {
+                truncated = true;
+                return;
+            }
+            const text = chunk.toString("utf8");
+            if (which === "stdout")
+                stdout += text;
+            else
+                stderr += text;
+        };
+        child.stdout.on("data", onData("stdout"));
+        child.stderr.on("data", onData("stderr"));
+        child.on("error", (err) => {
+            if (timer)
+                clearTimeout(timer);
+            reject(new HarmonyMcpError("EXEC_SPAWN_FAILED", err.message, { command, args }));
+        });
+        child.on("close", (exitCode, signal) => {
+            if (timer)
+                clearTimeout(timer);
+            resolve({
+                command,
+                args,
+                exitCode,
+                signal,
+                stdout,
+                stderr,
+                durationMs: Date.now() - started,
+                truncated,
+            });
+        });
+        if (timeoutMs > 0) {
+            timer = setTimeout(() => {
+                child.kill("SIGKILL");
+            }, timeoutMs);
+        }
+        if (options.stdin !== undefined) {
+            child.stdin.write(options.stdin);
+            child.stdin.end();
+        }
+        else {
+            child.stdin.end();
+        }
+    });
+}
+//# sourceMappingURL=safe-exec.js.map

package/dist/packages/mcp-common/src/safe-exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-exec.js","sourceRoot":"","sources":["../../../../packages/mcp-common/src/safe-exec.ts"],"names":[],"mappings":"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"}

package/dist/packages/mcp-common/src/sandbox.d.ts

@@ -0,0 +1,31 @@
+export interface SandboxOptions {
+    /** 允许的工作根目录列表（绝对路径） */
+    allowedRoots: string[];
+    /**
+     * v0.2: 允许 sandbox 在 resolve() 时自动把"看起来是鸿蒙工程根"的目录
+     * 加进白名单。默认 true。
+     */
+    autoDetectProjectRoot?: boolean;
+}
+/**
+ * 从任意 startPath（文件或目录）逐级向上找鸿蒙工程根。
+ * 找不到时返回 null。
+ */
+export declare function detectProjectRoot(startPath: string): string | null;
+export declare class PathSandbox {
+    private roots;
+    private readonly autoDetect;
+    constructor(opts: SandboxOptions);
+    /** 动态扩容：当 Agent 给出新工程目录时，可即时把它的工程根纳入白名单。 */
+    addRoot(rootPath: string): void;
+    /**
+     * v0.2: 给"只读静态扫描"类工具用——
+     * 把传入路径自身（若是目录）或其所在工程根作为合法根注册进沙箱，
+     * 但 NOT 用于会触发 shell 命令的 hvigor 类工具。
+     * 返回最终生效的根目录绝对路径。
+     */
+    ensureReadOnlyRoot(targetPath: string): string;
+    /** 把任意路径规范化为绝对路径，并校验其位于允许的根目录内。 */
+    resolve(targetPath: string): string;
+    private isInsideRoots;
+}

package/dist/packages/mcp-common/src/sandbox.js

@@ -0,0 +1,96 @@
+/**
+ * 路径沙箱：确保被操作的路径都在用户声明的工作区内，防止 Agent 误操作。
+ *
+ * v0.2 起：支持运行时自动从工具入参里的 project_dir / file_path
+ * 推断出鸿蒙工程根目录，并动态加入白名单 —— 这样用户切换工程时不必再改环境变量。
+ */
+import path from "node:path";
+import fs from "node:fs";
+import { HarmonyMcpError } from "./errors.js";
+/** 用于判定一个目录是不是鸿蒙工程根的标志文件 */
+const HARMONY_ROOT_MARKERS = [
+    "hvigorw",
+    "hvigorfile.ts",
+    "hvigorfile.js",
+    "build-profile.json5",
+    "oh-package.json5",
+];
+/**
+ * 从任意 startPath（文件或目录）逐级向上找鸿蒙工程根。
+ * 找不到时返回 null。
+ */
+export function detectProjectRoot(startPath) {
+    let cur = path.resolve(startPath);
+    // 如果起点是文件，转成它所在目录
+    try {
+        const st = fs.statSync(cur);
+        if (st.isFile())
+            cur = path.dirname(cur);
+    }
+    catch {
+        // 路径不存在也没关系，按目录处理
+    }
+    const root = path.parse(cur).root;
+    while (cur && cur !== root) {
+        for (const marker of HARMONY_ROOT_MARKERS) {
+            if (fs.existsSync(path.join(cur, marker))) {
+                return cur;
+            }
+        }
+        cur = path.dirname(cur);
+    }
+    return null;
+}
+export class PathSandbox {
+    roots;
+    autoDetect;
+    constructor(opts) {
+        this.autoDetect = opts.autoDetectProjectRoot !== false;
+        if (!opts.allowedRoots.length && !this.autoDetect) {
+            throw new HarmonyMcpError("SANDBOX_NO_ROOT", "PathSandbox requires at least one allowedRoot (or enable autoDetectProjectRoot)");
+        }
+        this.roots = opts.allowedRoots.map((p) => path.resolve(p));
+    }
+    /** 动态扩容：当 Agent 给出新工程目录时，可即时把它的工程根纳入白名单。 */
+    addRoot(rootPath) {
+        const abs = path.resolve(rootPath);
+        if (!this.roots.includes(abs)) {
+            this.roots.push(abs);
+        }
+    }
+    /**
+     * v0.2: 给"只读静态扫描"类工具用——
+     * 把传入路径自身（若是目录）或其所在工程根作为合法根注册进沙箱，
+     * 但 NOT 用于会触发 shell 命令的 hvigor 类工具。
+     * 返回最终生效的根目录绝对路径。
+     */
+    ensureReadOnlyRoot(targetPath) {
+        const abs = path.resolve(targetPath);
+        if (this.isInsideRoots(abs))
+            return abs;
+        const detected = this.autoDetect ? detectProjectRoot(abs) : null;
+        const root = detected ?? abs;
+        this.addRoot(root);
+        return abs;
+    }
+    /** 把任意路径规范化为绝对路径，并校验其位于允许的根目录内。 */
+    resolve(targetPath) {
+        const abs = path.resolve(targetPath);
+        if (this.isInsideRoots(abs))
+            return abs;
+        // v0.2: 自动探测——如果 abs 落在某个鸿蒙工程目录下，则把该工程根加入白名单。
+        if (this.autoDetect) {
+            const detected = detectProjectRoot(abs);
+            if (detected) {
+                this.addRoot(detected);
+                if (this.isInsideRoots(abs))
+                    return abs;
+            }
+        }
+        throw new HarmonyMcpError("SANDBOX_VIOLATION", `path ${abs} is outside allowed roots`, { roots: this.roots });
+    }
+    isInsideRoots(abs) {
+        return this.roots.some((root) => abs === root || abs.startsWith(root + path.sep));
+    }
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/packages/mcp-common/src/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../../../../packages/mcp-common/src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAY9C,4BAA4B;AAC5B,MAAM,oBAAoB,GAAG;IAC3B,SAAS;IACT,eAAe;IACf,eAAe;IACf,qBAAqB;IACrB,kBAAkB;CACnB,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,IAAI,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAClC,kBAAkB;IAClB,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,EAAE,CAAC,MAAM,EAAE;YAAE,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,kBAAkB;IACpB,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;IAClC,OAAO,GAAG,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC3B,KAAK,MAAM,MAAM,IAAI,oBAAoB,EAAE,CAAC;YAC1C,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;gBAC1C,OAAO,GAAG,CAAC;YACb,CAAC;QACH,CAAC;QACD,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,OAAO,WAAW;IACd,KAAK,CAAW;IACP,UAAU,CAAU;IAErC,YAAY,IAAoB;QAC9B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,qBAAqB,KAAK,KAAK,CAAC;QACvD,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YAClD,MAAM,IAAI,eAAe,CACvB,iBAAiB,EACjB,iFAAiF,CAClF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED,4CAA4C;IAC5C,OAAO,CAAC,QAAgB;QACtB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,kBAAkB,CAAC,UAAkB;QACnC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACrC,IAAI,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC;YAAE,OAAO,GAAG,CAAC;QACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACjE,MAAM,IAAI,GAAG,QAAQ,IAAI,GAAG,CAAC;QAC7B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACnB,OAAO,GAAG,CAAC;IACb,CAAC;IAED,mCAAmC;IACnC,OAAO,CAAC,UAAkB;QACxB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACrC,IAAI,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC;YAAE,OAAO,GAAG,CAAC;QAExC,8CAA8C;QAC9C,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,MAAM,QAAQ,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;YACxC,IAAI,QAAQ,EAAE,CAAC;gBACb,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;gBACvB,IAAI,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC;oBAAE,OAAO,GAAG,CAAC;YAC1C,CAAC;QACH,CAAC;QAED,MAAM,IAAI,eAAe,CACvB,mBAAmB,EACnB,QAAQ,GAAG,2BAA2B,EACtC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CACtB,CAAC;IACJ,CAAC;IAEO,aAAa,CAAC,GAAW;QAC/B,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACpF,CAAC;CACF"}

package/dist/packages/profiler-mcp/src/index.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { z } from "zod";
+import { ToolDef } from "@harmony-mcp/common";
+export declare const NAMESPACE = "profiler";
+export declare const tools: ToolDef<z.ZodObject<z.ZodRawShape>>[];

package/dist/packages/profiler-mcp/src/index.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * profiler-mcp: 鸿蒙性能工具的 MCP Server 化。
+ *
+ * 工具：
+ *   - capture_trace        通过 hdc shell hitrace 抓 trace（指定时长与 tag）
+ *   - analyze_trace        把 ftrace 文本解析为 Top 慢函数 / 掉帧 / 主线程长段
+ *   - capture_and_analyze  上面两个的组合，一步出根因
+ *   - cold_start_breakdown 冷启动场景的便捷封装（启动 ability + 抓 5s trace）
+ *
+ * 依赖：本机已安装 hdc 并能连接设备/模拟器。
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createLogger, HarmonyMcpError, isMainModule, registerTools, runCommand, } from "@harmony-mcp/common";
+import { analyzeTrace } from "./trace-analyzer.js";
+const logger = createLogger("profiler-mcp");
+const HDC_BIN = process.env.HDC_BIN ?? "hdc";
+const DEFAULT_TARGET = process.env.HDC_TARGET;
+// 默认抓的 tag 集合（覆盖 ArkUI 渲染 / Ability / IPC / 网络）
+const DEFAULT_TAGS = ["app", "ability", "graphic", "ohos", "ace", "render"];
+const TargetField = z.string().min(1).optional().describe("设备序列号；不填使用默认设备");
+const CaptureTraceSchema = z.object({
+    duration_seconds: z.number().int().positive().max(60).default(5)
+        .describe("抓取时长（秒）"),
+    tags: z.array(z.string()).optional()
+        .describe(`hitrace tag 列表；默认 ${DEFAULT_TAGS.join(",")}`),
+    buffer_kb: z.number().int().positive().default(8192)
+        .describe("环形缓冲大小 KB"),
+    output_path: z.string().optional()
+        .describe("本地保存路径；省略则保存到临时目录并返回路径"),
+    target: TargetField,
+});
+const AnalyzeTraceSchema = z.object({
+    trace_path: z.string().describe("本地 .ftrace 文件路径"),
+    top_n: z.number().int().positive().max(50).default(10),
+});
+const CaptureAndAnalyzeSchema = CaptureTraceSchema.extend({
+    top_n: z.number().int().positive().max(50).default(10),
+});
+const ColdStartSchema = z.object({
+    bundle_name: z.string(),
+    ability_name: z.string(),
+    duration_seconds: z.number().int().positive().max(20).default(5),
+    target: TargetField,
+});
+async function hdc(args, target, timeoutMs = 60_000) {
+    const finalTarget = target ?? DEFAULT_TARGET;
+    const finalArgs = finalTarget ? ["-t", finalTarget, ...args] : args;
+    return runCommand(HDC_BIN, finalArgs, { timeoutMs });
+}
+async function captureTrace(opts) {
+    const duration = opts.duration_seconds ?? 5;
+    const tags = opts.tags?.length ? opts.tags : DEFAULT_TAGS;
+    const remoteFile = `/data/local/tmp/mcp-trace-${Date.now()}.ftrace`;
+    const localFile = opts.output_path ?? path.join(os.tmpdir(), `mcp-trace-${Date.now()}.ftrace`);
+    // 1) 抓 trace（hitrace 阻塞 N 秒后自动结束）
+    const captureArgs = [
+        "shell",
+        "hitrace",
+        "-t",
+        String(duration),
+        "-b",
+        String(opts.buffer_kb ?? 8192),
+        "-o",
+        remoteFile,
+        ...tags,
+    ];
+    const cap = await hdc(captureArgs, opts.target, (duration + 15) * 1000);
+    if (cap.exitCode !== 0) {
+        throw new HarmonyMcpError("HITRACE_FAILED", cap.stderr || "hitrace failed", {
+            stdout: cap.stdout,
+        });
+    }
+    // 2) 拉回本地
+    const recv = await hdc(["file", "recv", remoteFile, localFile], opts.target, 60_000);
+    if (recv.exitCode !== 0) {
+        throw new HarmonyMcpError("TRACE_RECV_FAILED", recv.stderr || "file recv failed");
+    }
+    const stat = await fs.stat(localFile);
+    return { local_path: localFile, bytes: stat.size, tags, duration_seconds: duration };
+}
+export const NAMESPACE = "profiler";
+export const tools = [
+    {
+        name: "capture_trace",
+        description: "通过 hitrace 抓取指定时长的 trace，并把文件拉回本地",
+        schema: CaptureTraceSchema,
+        handler: captureTrace,
+    },
+    {
+        name: "analyze_trace",
+        description: "解析本地 ftrace 文件，输出 Top 慢函数 / 主线程长段 / 疑似掉帧",
+        schema: AnalyzeTraceSchema,
+        handler: async (a) => {
+            const text = await fs.readFile(a.trace_path, "utf8");
+            return analyzeTrace(text, a.top_n);
+        },
+    },
+    {
+        name: "capture_and_analyze",
+        description: "抓 trace 并立刻分析，一步出根因（推荐 Agent 默认调用）",
+        schema: CaptureAndAnalyzeSchema,
+        handler: async (a) => {
+            const cap = await captureTrace(a);
+            const text = await fs.readFile(cap.local_path, "utf8");
+            const analysis = analyzeTrace(text, a.top_n);
+            return { capture: cap, analysis };
+        },
+    },
+    {
+        name: "cold_start_breakdown",
+        description: "冷启动场景便捷封装：force-stop → start_ability → 抓 N 秒 trace → 分析",
+        schema: ColdStartSchema,
+        handler: async (a) => {
+            await hdc(["shell", "aa", "force-stop", a.bundle_name], a.target);
+            // 启动 + 抓 trace 并发，确保抓到启动期
+            const startPromise = hdc(["shell", "aa", "start", "-b", a.bundle_name, "-a", a.ability_name], a.target);
+            const cap = await captureTrace({
+                duration_seconds: a.duration_seconds,
+                buffer_kb: 8192,
+                target: a.target,
+            });
+            await startPromise;
+            const text = await fs.readFile(cap.local_path, "utf8");
+            const analysis = analyzeTrace(text, 10);
+            return { capture: cap, analysis };
+        },
+    },
+];
+async function main() {
+    const server = new Server({ name: "harmony-profiler-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+    registerTools(server, { ListToolsRequestSchema, CallToolRequestSchema }, tools);
+    await server.connect(new StdioServerTransport());
+    logger.info("profiler-mcp server started");
+}
+if (isMainModule(import.meta.url)) {
+    main().catch((err) => {
+        logger.error("fatal", { err: String(err) });
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/packages/profiler-mcp/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/profiler-mcp/src/index.ts"],"names":[],"mappings":"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"}

package/dist/packages/profiler-mcp/src/trace-analyzer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 极简 hitrace/ftrace 文本分析器（first pass）。
+ *
+ * 输入：hitrace --trace_dump 的文本输出（ftrace 文本格式）
+ * 解析维度：
+ *   - 用户态打点段（tracing_mark_write: B|...   E|... ） —— 提取 (name, duration_us)
+ *   - frame 段（H:RSRenderThread / H:UIRender / H:Frame:）—— 提取掉帧
+ *
+ * 这是工程化解析的最小子集；完整版需要对接华为 SmartPerf 解析库。
+ */
+export interface TraceSegment {
+    name: string;
+    tid: number;
+    pid: number;
+    startUs: number;
+    durationUs: number;
+}
+export interface TraceAnalysis {
+    total_segments: number;
+    duration_us: number;
+    top_slow: Array<{
+        name: string;
+        duration_us: number;
+        tid: number;
+        pid: number;
+    }>;
+    long_main_thread: Array<{
+        name: string;
+        duration_us: number;
+    }>;
+    suspected_jank_frames: Array<{
+        name: string;
+        duration_us: number;
+    }>;
+    summary: string;
+}
+export declare function parseTrace(text: string): TraceSegment[];
+export declare function analyzeTrace(text: string, topN?: number): TraceAnalysis;

package/dist/packages/profiler-mcp/src/trace-analyzer.js

@@ -0,0 +1,95 @@
+/**
+ * 极简 hitrace/ftrace 文本分析器（first pass）。
+ *
+ * 输入：hitrace --trace_dump 的文本输出（ftrace 文本格式）
+ * 解析维度：
+ *   - 用户态打点段（tracing_mark_write: B|...   E|... ） —— 提取 (name, duration_us)
+ *   - frame 段（H:RSRenderThread / H:UIRender / H:Frame:）—— 提取掉帧
+ *
+ * 这是工程化解析的最小子集；完整版需要对接华为 SmartPerf 解析库。
+ */
+const ENTRY_LINE = /^\s*\S+-(\d+)\s+\(\s*(\d+)\)\s+\[\d+\]\s+\S+\s+(\d+\.\d+):\s+tracing_mark_write:\s+([BE])\|\d+\|(.+)$/;
+export function parseTrace(text) {
+    const stack = new Map(); // per-tid 栈
+    const segs = [];
+    for (const line of text.split(/\r?\n/)) {
+        const m = ENTRY_LINE.exec(line);
+        if (!m)
+            continue;
+        const tid = Number(m[1]);
+        const pid = Number(m[2]);
+        const tsUs = Math.round(parseFloat(m[3]) * 1_000_000);
+        const phase = m[4];
+        const name = m[5].trim();
+        const s = stack.get(tid) ?? [];
+        if (phase === "B") {
+            s.push({ name, pid, tid, startUs: tsUs });
+            stack.set(tid, s);
+        }
+        else {
+            // E
+            const open = s.pop();
+            if (open) {
+                segs.push({
+                    name: open.name,
+                    pid: open.pid,
+                    tid: open.tid,
+                    startUs: open.startUs,
+                    durationUs: tsUs - open.startUs,
+                });
+            }
+        }
+    }
+    return segs;
+}
+export function analyzeTrace(text, topN = 10) {
+    const segs = parseTrace(text);
+    if (!segs.length) {
+        return {
+            total_segments: 0,
+            duration_us: 0,
+            top_slow: [],
+            long_main_thread: [],
+            suspected_jank_frames: [],
+            summary: "no segments parsed; check that the trace text contains tracing_mark_write lines",
+        };
+    }
+    const minTs = Math.min(...segs.map((s) => s.startUs));
+    const maxTs = Math.max(...segs.map((s) => s.startUs + s.durationUs));
+    const sortedByDur = [...segs].sort((a, b) => b.durationUs - a.durationUs);
+    const topSlow = sortedByDur.slice(0, topN).map((s) => ({
+        name: s.name,
+        duration_us: s.durationUs,
+        tid: s.tid,
+        pid: s.pid,
+    }));
+    // 主线程经验：tid == pid（首线程多为主线程）
+    const mainSegs = segs.filter((s) => s.tid === s.pid);
+    const longMain = mainSegs
+        .filter((s) => s.durationUs >= 16_000) // 单段 > 一帧 16ms
+        .sort((a, b) => b.durationUs - a.durationUs)
+        .slice(0, topN)
+        .map((s) => ({ name: s.name, duration_us: s.durationUs }));
+    // 帧段：常见命名前缀有 "H:RSRenderThread::DrawFrame" / "H:UIRender" / "Frame:"
+    const frameSegs = segs.filter((s) => /^(H:RSRenderThread|H:UIRender|Frame:|H:Render|H:ArkUI_DoFrame)/i.test(s.name));
+    const jank = frameSegs
+        .filter((s) => s.durationUs >= 16_667) // 60fps 阈值
+        .sort((a, b) => b.durationUs - a.durationUs)
+        .slice(0, topN)
+        .map((s) => ({ name: s.name, duration_us: s.durationUs }));
+    const summary = [
+        `parsed ${segs.length} segments over ${(maxTs - minTs) / 1000}ms`,
+        `top slow: ${topSlow[0]?.name ?? "n/a"} (${topSlow[0]?.duration_us ?? 0}us)`,
+        `long main-thread segs: ${longMain.length}`,
+        `suspected jank frames: ${jank.length}`,
+    ].join("; ");
+    return {
+        total_segments: segs.length,
+        duration_us: maxTs - minTs,
+        top_slow: topSlow,
+        long_main_thread: longMain,
+        suspected_jank_frames: jank,
+        summary,
+    };
+}
+//# sourceMappingURL=trace-analyzer.js.map

package/dist/packages/profiler-mcp/src/trace-analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-analyzer.js","sourceRoot":"","sources":["../../../../packages/profiler-mcp/src/trace-analyzer.ts"],"names":[],"mappings":"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"}