fix(plugin): normalize tool param metadata in tool detail

Author: FinleyGe

packages/infrastructure/src/plugin/tool.impl.test.ts

@@ -113,6 +113,102 @@ describe('ToolManager.detail', () => {
       version: '1.10.0'
     });
   });
+
+  it('normalizes input schema tool parameter metadata in tool detail', async () => {
+    const toolManager = createToolManager();
+    listVersions.mockResolvedValue(successResult([{ version: '1.0.0' }]));
+    getPluginByUserPluginId.mockResolvedValue(
+      successResult({
+        ...makeTool('1.0.0'),
+        inputSchema: {
+          type: 'object',
+          properties: {
+            withToolDescription: {
+              type: 'string',
+              toolDescription: 'Existing model-facing description'
+            },
+            manualByDefault: {
+              type: 'string',
+              description: {
+                en: 'Fallback manual description',
+                'zh-CN': '手动参数说明'
+              }
+            },
+            explicitFalse: {
+              type: 'string',
+              description: {
+                en: 'Explicit false fallback'
+              },
+              isToolParams: false
+            },
+            explicitTrue: {
+              type: 'string',
+              description: {
+                en: 'Explicit true fallback'
+              },
+              isToolParams: true
+            }
+          }
+        },
+        children: [
+          {
+            id: 'child',
+            name: { en: 'Child' },
+            description: { en: 'Child tool' },
+            icon: 'https://example.com/child.svg',
+            toolDescription: 'Child tool',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                childParam: {
+                  type: 'string',
+                  description: {
+                    en: 'Child fallback'
+                  }
+                }
+              }
+            },
+            outputSchema: {
+              type: 'object'
+            }
+          }
+        ]
+      } satisfies ToolType)
+    );
+
+    const [result, err] = await toolManager.detail({
+      pluginId: 'getTime',
+      source: 'system',
+      version: '1.0.0'
+    });
+
+    const properties = (result?.inputSchema as { properties: Record<string, unknown> }).properties;
+    const childProperties = (result?.children?.[0]?.inputSchema as {
+      properties: Record<string, unknown>;
+    }).properties;
+
+    expect(err).toBeNull();
+    expect(properties.withToolDescription).toMatchObject({
+      toolDescription: 'Existing model-facing description',
+      isToolParams: true
+    });
+    expect(properties.manualByDefault).toMatchObject({
+      toolDescription: 'Fallback manual description',
+      isToolParams: false
+    });
+    expect(properties.explicitFalse).toMatchObject({
+      toolDescription: 'Explicit false fallback',
+      isToolParams: false
+    });
+    expect(properties.explicitTrue).toMatchObject({
+      toolDescription: 'Explicit true fallback',
+      isToolParams: true
+    });
+    expect(childProperties.childParam).toMatchObject({
+      toolDescription: 'Child fallback',
+      isToolParams: false
+    });
+  });
 });
 
 describe('ToolManager.run', () => {

packages/infrastructure/src/plugin/tool.impl.ts

@@ -28,6 +28,8 @@ import { ErrorCode } from '@infrastructure/errors/error.registry';
 import { InvokeManager } from './invoke/invoke.impl';
 import { Semver } from './utils/semver';
 
+type JsonObject = Record<string, unknown>;
+
 export type ToolManagerDeps = {
   pluginRepo: PluginRepoPort;
   pluginRuntimeManager: PluginRuntimeManagerPort;
@@ -41,6 +43,72 @@ export type PluginToolRunPayloadType = {
   childId?: string;
 };
 
+function isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function getDescriptionFallback(description: unknown): string | undefined {
+  if (typeof description === 'string' && description.length > 0) {
+    return description;
+  }
+
+  if (!isJsonObject(description)) {
+    return undefined;
+  }
+
+  const en = description.en;
+  return typeof en === 'string' && en.length > 0 ? en : undefined;
+}
+
+function normalizeInputSchemaToolParams(inputSchema: unknown): unknown {
+  if (!isJsonObject(inputSchema) || !isJsonObject(inputSchema.properties)) {
+    return inputSchema;
+  }
+
+  const properties = Object.fromEntries(
+    Object.entries(inputSchema.properties).map(([key, property]) => {
+      if (!isJsonObject(property)) {
+        return [key, property];
+      }
+
+      const normalizedProperty = { ...property };
+      const hasToolDescription =
+        typeof normalizedProperty.toolDescription === 'string' &&
+        normalizedProperty.toolDescription.length > 0;
+      const hasIsToolParams = normalizedProperty.isToolParams !== undefined;
+
+      if (hasIsToolParams) {
+        if (!hasToolDescription) {
+          const fallback = getDescriptionFallback(normalizedProperty.description);
+          if (fallback !== undefined) {
+            normalizedProperty.toolDescription = fallback;
+          }
+        }
+
+        return [key, normalizedProperty];
+      }
+
+      if (hasToolDescription) {
+        normalizedProperty.isToolParams = true;
+        return [key, normalizedProperty];
+      }
+
+      const fallback = getDescriptionFallback(normalizedProperty.description);
+      if (fallback !== undefined) {
+        normalizedProperty.toolDescription = fallback;
+      }
+      normalizedProperty.isToolParams = false;
+
+      return [key, normalizedProperty];
+    })
+  );
+
+  return {
+    ...inputSchema,
+    properties
+  };
+}
+
 export class ToolManager implements ToolManagerPort {
   private static instance: ToolManager;
   private constructor(private deps: ToolManagerDeps) {}
@@ -61,6 +129,11 @@ export class ToolManager implements ToolManagerPort {
   }): ToolDetailType {
     return {
       ...tool,
+      inputSchema: normalizeInputSchemaToolParams(tool.inputSchema),
+      children: tool.children?.map((child) => ({
+        ...child,
+        inputSchema: normalizeInputSchemaToolParams(child.inputSchema)
+      })),
       source,
       isToolset: Boolean(tool.children?.length),
       isLatestVersion