feat: add canonical typed tool outputs

docs/user/develop/basic/tool.zh.md

@@ -20,9 +20,13 @@ export function apply(ctx: Context) {
     parameters: {
       name: { type: 'string', required: true, description: 'The name to greet' },
     },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
     async execute(args) {
       // args is inferred as { name: string }.
-      return [{ type: 'text', text: `Hello, ${args.name}!` }]
+      return `Hello, ${args.name}!`
     },
   }))
 }
@@ -107,33 +111,45 @@ export const tool = defineTool({
   name: 'example',
   description: 'Return an example result.',
   parameters: {},
+  output: {
+    schema: { type: 'string' },
+    render: (_args, value) => [{ type: 'text', text: value }],
+  },
   async execute(args, exec) {
     // args: inferred from parameters
     // exec: ToolExecution context
 
-    // Return a ContentBlock array.
+    // Return the value declared by output.schema.
     void args
     void exec
-    return [{ type: 'text', text: 'result here' }]
+    return 'result here'
   },
 })
 ```
 
 ### 返回值
 
-`execute` 必须返回一个 `ContentBlock[]`，告诉模型 tool 的执行结果：
+`execute` 返回由 `output.schema` 声明的无损 JSON 值。`output.render(args, value)` 会将经过校验的值另外转换为 Native／模型可见的内容：
 
 ```ts ignore-check
-// Text result
-return [{ type: 'text', text: 'file content here...' }]
-
-// Multiple blocks
-return [
-  { type: 'text', text: 'Found 3 matches:' },
-  { type: 'text', text: matchResults.join('\n') },
-]
+output: {
+  schema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      path: { type: 'string', required: true },
+      content: { type: 'string', required: true },
+    },
+  },
+  render: (_args, value) => [{ type: 'text', text: value.content }],
+},
+async execute(args) {
+  return { path: args.path, content: await readFile(args.path, 'utf8') }
+}
 ```
 
+执行期间的程序化调用方可以使用规范值，但 `tool/result` 不会持久化该值；渲染后的内容和可选的 `presentationMeta` 才是可回放的投影。工具主体返回的值若不满足 schema 或不是无损 JSON，就会变为 `INVALID_TOOL_OUTPUT` 失败。
+
 ### 参数校验
 
 `defineTool` 在调用 `execute` 之前会自动校验模型生成的参数。如果参数不合法，会抛出 `ToolArgsError`，框架将其转换为 `isError` 结果返回给模型，让模型自行修正。
@@ -148,6 +164,10 @@ Tool 可以定义 UI 渲染方法，用于在终端或 ACP 客户端中展示 to
 defineTool({
   name: 'bash',
   // ...
+  output: {
+    schema: { type: 'string' },
+    render: (_args, value) => [{ type: 'text', text: value }],
+  },
   presentCall(args) {
     return {
       card: 'terminal',
@@ -196,13 +216,24 @@ export function apply(ctx: Context) {
       path: { type: 'string', required: true, description: 'Directory path' },
       extension: { type: 'string', description: 'Filter by extension (e.g. ".ts")' },
     },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          count: { type: 'integer', required: true },
+          files: { type: 'array', required: true, items: { type: 'string' } },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `Found ${value.count} files.` }],
+    },
     async execute(args) {
       const entries = await readdir(args.path, { withFileTypes: true })
       let files = entries.filter(e => e.isFile())
       if (args.extension) {
         files = files.filter(f => f.name.endsWith(args.extension!))
       }
-      return [{ type: 'text', text: `Found ${files.length} files.` }]
+      return { count: files.length, files: files.map(file => file.name) }
     },
   }))
 }