# Performance Optimization Recommendations

In this mode, each atomic API call corresponds to a complete round trip of "model decision → on-device execution → result feedback → re-inference," which typically introduces an additional 1–2 seconds of latency. Without adjusting the model or prompts, properly designing atomic APIs can significantly reduce response latency.

This document presents four optimization approaches, ordered from lowest to highest modification cost:

Optimization Approach Optimization Target Prerequisites
Output Streamlining Input size per round trip None; recommended for all SKILLs
apiCalls Chained Invocation Number of round trips The trigger and input parameters of the downstream API can be determined by the upstream return result
Sinking Common Logic into Middleware Number of round trips The logic is a common pre- or post-step for multiple APIs and is idempotent
Merging Bound APIs Number of round trips Two APIs inevitably appear in pairs and in a fixed order

Among these, Output Streamlining reduces the input volume per round trip, while the latter three reduce the number of round trips. It is recommended to evaluate them one by one in the order above.

# 1. Output Streamlining

# 1.1 Applicable Scenarios

structuredContent serves two types of consumers simultaneously: the Mini-Program AI (for understanding and reasoning) and the on-device side (for atomic component rendering and handoff). Fields that are only used by the on-device side and not needed for model decision-making—such as page navigation paths, style and tracking parameters, large enumeration code tables, etc.—should be removed from structuredContent.

The return result of an atomic API enters all subsequent inferences as a historical message. Therefore, the benefit of this optimization is not limited to a single call: it reduces the input size of every subsequent call in the current session; at the same time, context growth slows down, which can reduce the frequency of context compression triggers, allowing the model to retain original conversation details for a longer time.

# 1.2 Field Responsibilities

Field Enters Model Context Purpose
content / structuredContent / isError Yes For model understanding and reasoning
handoff No Handoff data, retrieved by Mini-Program pages via ft.onAgentHandoff

For field semantics, see Integration - Atomic API Implementation.

# 1.3 Notes

  • Mixed-content link fields marked as format: "page-link" must be retained in structuredContent, as the platform needs to extract page paths from them;
  • It is not recommended to write data returned by backend APIs directly into structuredContent without filtering.

# 2. apiCalls Chained Invocation

# 2.1 Applicable Scenarios

When atomic API A is executed and is highly likely to be immediately followed by a call to atomic API B (e.g., more than half of A calls are followed by B), and whether B is triggered and its input parameter values can both be determined by A's return result, A's return value should carry apiCalls, allowing the framework to directly initiate B's call, skipping a segment of model inference in between.

# 2.2 Declaration Method

// Return value of API A
{
  isError: false,
  content: [{ type: 'text', text: 'Query complete' }],
  apiCalls: [{ name: 'B', arguments: { id: result.id } }]
}

# 2.3 Example

The typhoon API only needs to be called when the weather query result contains typhoon information; the trigger condition is entirely determined by the return result:

// Return handling of getDailyWeatherForecast
const result = await fetchDailyForecast(location, days);
const resp = {
  isError: false,
  content: [{ type: 'text', text: summarize(result) }],
  structuredContent: result
};
// Only dispatch apiCalls when the return contains typhoon information
if (result.typhoonWarning != null) {
  resp.apiCalls = [{
    name: 'getTyphoonWarning',
    arguments: { location, typhoonName: result.typhoonWarning.name }
  }];
}
return resp;

# 2.4 Notes

  • Dispatch conditionally: Only carry apiCalls when the return result meets the condition; do not dispatch unconditionally;
  • Not applicable when the downstream API depends on the user's free choice: B's trigger must be deterministically derivable from A's return result;
  • apiCalls is not equivalent to API merging: A and B remain two independent APIs, and B can still be called separately in other chains.

# 3. Sinking Common Logic into Middleware

# 3.1 Applicable Scenarios

APIs that simultaneously satisfy all of the following conditions should be removed from the atomic API list in mcp.json and instead registered as middleware via skill.use():

  • They do not constitute an independent business goal, and users will not initiate requests specifically for them;
  • Their return values serve only as a gate or context for subsequent calls, such as login state, location, privacy authorization, or unified display cards;
  • They are common pre- or post-logic for most APIs within the SKILL.

If retained as atomic APIs, the model would need to make a decision and call them once every round, introducing an additional complete round trip.

# 3.2 Example

const skill = ft.modelContext.createSkill(skillPath);
skill.use(async (ctx, next) => {
  // Pre-logic: automatically executed before each atomic API call
  const token = ft.getStorageSync('token');
  if (!token) {
    const { code } = await ft.login();
    const res = await ft.request({ url: '.../login', data: { code } });
    ft.setStorageSync('token', res.data.token);
  }
  try {
    await next(); // Execute the actual atomic API
  } finally {
    // Post-logic: log reporting, unified display, etc.
  }
});

For the complete semantics of middleware, see Integration - Middleware Mechanism.

# 3.3 Notes

  • Middleware must remain idempotent and side-effect-free, as it executes before and after every atomic API call;
  • The entire middleware chain and atomic API execution time share the same timeout limit; long-running logic should not be introduced within middleware;

# 4. Merging Bound APIs

# 4.1 Applicable Scenarios

When two atomic APIs inevitably appear in pairs and their call order is fixed, they should be merged into a single API.

# 4.2 Example

Taking a segment of input pre-processing as an example: the original design includes two atomic APIs, checkContent (content safety check and login check) and intentRecognition (intent recognition). Both take the user's raw input as input parameters and logically always appear in pairs, never called separately. Such binding relationships should be merged into a single API:

// Before merging: for each round of user input, the model needs to call twice consecutively
// checkContent({ content, business }) -> intentRecognition({ query })

// After merging: a single call returns both the check result and the recognized intent
skill.registerAPI('preprocess', async ({ content, business }) => {
  const check = await checkContentSafety(content); // Original checkContent logic
  if (!check.passed) {
    return {
      isError: false,
      content: [{ type: 'text', text: check.reason }],
      structuredContent: { passed: false }
    };
  }
  if (check.needLogin) {
    // The not-logged-in branch retains the original handling: apiCalls directly connects to the login card, bypassing model inference
    return {
      isError: false,
      content: [{ type: 'text', text: 'Please log in first' }],
      structuredContent: { passed: false, needLogin: true },
      apiCalls: [{ name: 'authLogin', arguments: { originQuery: content } }]
    };
  }
  const intent = await recognizeIntent(content); // Original intentRecognition logic
  return {
    isError: false,
    content: [{ type: 'text', text: 'Pre-check passed' }],
    structuredContent: { passed: true, needLogin: false, intent }
  };
});

After merging, each round of user input is reduced from 2 API calls (2 segments of model inference) to 1.

# 4.3 Inapplicable Cases

  • There is a user decision point in the middle of the chain, such as selecting a store, selecting a product, or confirming an order—merging would deprive the user of their choice;
  • It is merely high-frequency co-occurrence rather than a binding relationship—in such cases, apiCalls should be used instead of forced merging.
© FinClip with ❤ , Since 2017