mp_navigate

Instructions

Implementation Reference

• src/tools/application.ts:136-202 (handler)

  The 'mp_navigate' tool handler function that executes navigation logic (navigateTo, redirectTo, reLaunch, switchTab, navigateBack) using WeappAutomatorManager. It dispatches the correct navigation method based on the 'transition' parameter, optionally waits, and returns the active page info.

  function createNavigateTool(manager: WeappAutomatorManager): AnyTool {
    return {
      name: "mp_navigate",
      description:
        "在小程序内导航，支持 navigateTo、redirectTo、reLaunch、switchTab 和 navigateBack。",
      parameters: navigateParameters,
      execute: async (rawArgs, context: ToolContext) =>
        withUserErrorResult(async () => {
        const args = navigateParameters.parse(rawArgs ?? {});
        const transition = args.transition ?? "navigateTo";
        const overrides = args.connection;
        const waitMs = args.waitMs;
        const providedPath = args.path;
  
        return manager.withMiniProgram<ContentResult>(
          context.log,
          { overrides },
          async (miniProgram) => {
            let url: string | undefined;
            let page;
  
            if (transition === "navigateBack") {
              page = await miniProgram.navigateBack();
            } else {
              if (!providedPath) {
                return toErrorResult(
                  "参数 path 是必需的，除非 transition 是 navigateBack。"
                );
              }
              url = buildUrl(providedPath, args.query);
              switch (transition) {
                case "navigateTo":
                  page = await miniProgram.navigateTo(url);
                  break;
                case "redirectTo":
                  page = await miniProgram.redirectTo(url);
                  break;
                case "reLaunch":
                  page = await miniProgram.reLaunch(url);
                  break;
                case "switchTab":
                  page = await miniProgram.switchTab(url);
                  break;
                default:
                  return toErrorResult(`不支持的 transition: ${transition}`);
              }
            }
  
            if (waitMs && page) {
              await page.waitFor(waitMs);
            }
  
            const activePage = page ?? (await miniProgram.currentPage());
  
            return toTextResult(
              formatJson({
                transition,
                url,
                activePage: activePage
                  ? { path: activePage.path, query: activePage.query }
                  : null,
              })
            );
          }
        );
        }),
    };

• src/tools/application.ts:22-36 (schema)

  Zod schema definition for 'mp_navigate' parameters: optional path, optional query record, transition enum (navigateTo/redirectTo/reLaunch/switchTab/navigateBack, default navigateTo), optional waitMs (non-negative int), and connection overrides.

  const navigateParameters = connectionContainerSchema
    .extend({
      path: z.string().trim().min(1).optional(),
      query: querySchema,
      transition: z
        .enum([
          "navigateTo",
          "redirectTo",
          "reLaunch",
          "switchTab",
          "navigateBack",
        ])
        .default("navigateTo"),
      waitMs: z.coerce.number().int().nonnegative().optional(),
    });

• src/tools/application.ts:61-73 (registration)

  The tool is registered by calling createNavigateTool(manager) inside createApplicationTools(), which returns an array of all application tools. This is the central registration point.

  export function createApplicationTools(
    manager: WeappAutomatorManager
  ): AnyTool[] {
    return [
      createEnsureConnectionTool(manager),
      createNavigateTool(manager),
      createScreenshotTool(manager),
      createCallWxMethodTool(manager),
      createGetConsoleLogsTool(manager),
      createCurrentPageTool(manager),
      createListProjectsTool(manager),
      createSetDefaultProjectTool(manager),
    ];

• src/tools/common.ts:41-54 (helper)

  The buildUrl helper function constructs a URL from a path and optional query parameters. Used by the navigate tool to build the navigation URL.

  export function buildUrl(
    path: string,
    query?: Record<string, string>
  ): string {
    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
  
    if (!query || Object.keys(query).length === 0) {
      return normalizedPath;
    }
    const searchParams = new URLSearchParams(query);
    const separator = normalizedPath.includes("?") ? "&" : "?";
    const search = searchParams.toString();
    return search ? `${normalizedPath}${separator}${search}` : normalizedPath;
  }

• src/tools.ts:7-13 (registration)

  Top-level registration: createTools() calls createApplicationTools(manager) which includes the mp_navigate tool.

  export function createTools(manager: WeappAutomatorManager): AnyTool[] {
    return [
      ...createApplicationTools(manager),
      ...createPageTools(manager),
      ...createElementTools(manager),
    ];
  }