@77-zhike/app-sdk 0.2.0-d7b1.15 → 0.2.0-d7b1.17

package/README.md

@@ -1,5 +1,11 @@
 # 智客 App SDK 与 CLI
 
+## 正文批注与待发同步
+
+`TextSelection` 可接收有界 `marks`（id、UTF-16区间、逐字text、1至20的ordinal）与 `onMarkActivate`；Host默认保留编号，通过当前view锚点打开Popover时才高亮对应原文，关闭后清除高亮，点击编号可重新编辑；不向App交付DOM或坐标。通过 `useConversation().state.references ?? []` 派生标记，与Composer待发引用保持同源。
+
+annotation的comment允许空字符串，支持“先加入对话、再编辑评论”。保存更新同id，取消保留已加入引用，删除通过removeReference同步移除。仅引用原文而无评论时需在主输入说明要求；至少一条有评论才支持缺省正文发送。`form.TextArea`新增可选labelHidden，隐藏视觉标题但保留可访问名称。使用这些增量前须同步升级SDK、Runtime与双端Host，不能单独向旧宿主发布App。
+
 ## 操作系统与 Windows 候选
 
 当前 npm 发布版的 Developer CLI 仅提供 macOS Keychain 适配。本开发分支新增 Windows Credential Manager 候选：复用现有浏览器 PKCE 和 Session，使用系统 Windows PowerShell 5.1 固定桥接，refresh credential 按当前用户和 API origin 存储。
@@ -269,3 +275,7 @@ Chart 仅接受纯数据 `labels` 与 `series`，不接受脚本、HTML 或任
 附件只读当前 App 会话中用户提交的文件，不扩展自定义 Tool 的权限。新 App 业务 Tool 仍在 agent 目录用 `.tools.ts` 合并定义并由 Integration Runtime 执行。元数据 Schema 必须为静态字面量，execute 可导入项目自己的业务校验函数。
 
 真实表单协作可参考 `built-in-apps/opportunity-quotes`：页面以 SDK 布局并列 Form 与 Conversation，callback 接收建议，用户确认后更新本地草稿；正式保存沿原入口。NativeDOM 内仍只允许原有控件，不直接放 Conversation；可以在 Conversation 内用独立 NativeDOM 展示本地建议确认区。
+
+### Slider（源码增量，需匹配 Host）
+
+`@77-zhike/app-sdk/ui` 提供单值/双端 `Slider`，支持整段拖动、step、minRange、键盘与最终commit。App只消费数值；Host合并在途变化并保留手势草稿。需先发布匹配的SDK和桌面/手机Host，再发布消费App。完整属性与行为见 Developer Docs `app-sdk/components/slider`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@77-zhike/app-sdk",
-  "version": "0.2.0-d7b1.15",
+  "version": "0.2.0-d7b1.17",
   "description": "智客 Integration App 一期 SDK 与本地 Toolchain",
   "repository": {
     "type": "git",
@@ -67,5 +67,5 @@
       "optional": true
     }
   },
-  "gitHead": "cd6cf8462837c082eca5c5ccf2fb1dab8441885c"
+  "gitHead": "df9d8e305f4b9d603b33d41840847ee3d28a654b"
 }

package/src/client/documents.d.ts

@@ -0,0 +1,21 @@
+import type { JsonValue } from '../ui/index.js';
+/** 受限JSON Schema；服务端校验完整白名单、数组/字符串上限与绑定。 */
+export type RestrictedInputSchema = Readonly<Record<string, JsonValue>>;
+export interface PreparePdfTemplateInput {
+  inputSchema: RestrictedInputSchema;
+  /** 本次制作的有界、已授权试填数据，不保存到App模板配置。 */
+  sampleData: Readonly<Record<string, JsonValue>>;
+}
+export interface OpenPdfDocumentInput {
+  /** opaque Job用途引用；不能传URL、附件ID或PDF字节。 */
+  documentRef: string;
+  action: 'open' | 'download';
+}
+export type PreparedPdfTemplate = Readonly<{templateFileRef: string}>;
+export type OpenPdfDocumentResult = Readonly<{status: 'opened' | 'started' | 'cancelled'}>;
+export function assertDocumentInput(operation: string, input: unknown): PreparePdfTemplateInput | OpenPdfDocumentInput;
+export function assertDocumentResult(operation: string, value: unknown): PreparedPdfTemplate | OpenPdfDocumentResult | null;
+export function createDocumentClient(invoke: (operation: string, input: unknown) => Promise<unknown>): {
+  preparePdfTemplate(input: PreparePdfTemplateInput): Promise<PreparedPdfTemplate | null>;
+  openPdfDocument(input: OpenPdfDocumentInput): Promise<OpenPdfDocumentResult>;
+};

package/src/client/documents.js

@@ -0,0 +1,39 @@
+const invalid = () => { throw new Error('runtime_document_input_invalid'); };
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+const ref = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9_-]{0,79}$/.test(value);
+function bounded(value, depth = 0) {
+  if (depth > 12) invalid();
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
+  if (typeof value === 'number' && Number.isFinite(value)) return;
+  if (Array.isArray(value)) { if (value.length > 1000) invalid(); for (const item of value) bounded(item, depth + 1); return; }
+  if (!object(value)) invalid();
+  for (const [key, item] of Object.entries(value)) {
+    if (['__proto__', 'prototype', 'constructor'].includes(key)) invalid();
+    bounded(item, depth + 1);
+  }
+}
+export function assertDocumentInput(operation, input) {
+  if (!object(input)) invalid();
+  if (operation === 'openPdfDocument') {
+    if (Object.keys(input).some(key => !['documentRef', 'action'].includes(key)) || !ref(input.documentRef)
+      || !['open', 'download'].includes(input.action)) invalid();
+  } else if (operation === 'preparePdfTemplate') {
+    if (Object.keys(input).some(key => !['inputSchema', 'sampleData'].includes(key)) || !object(input.inputSchema)
+      || input.inputSchema.type !== 'object' || input.inputSchema.additionalProperties !== false || !object(input.sampleData)) invalid();
+    bounded(input);
+    if (new TextEncoder().encode(JSON.stringify(input)).length > 512 * 1024) invalid();
+  } else invalid();
+  // 快照避免App在异步交互期间原位改动请求。
+  return JSON.parse(JSON.stringify(input));
+}
+export function assertDocumentResult(operation, value) {
+  if (operation === 'preparePdfTemplate' && value === null) return null;
+  if (!object(value) || Object.keys(value).length !== 1) invalid();
+  if (operation === 'preparePdfTemplate' ? !ref(value.templateFileRef) : !['opened', 'started', 'cancelled'].includes(value.status)) invalid();
+  return Object.freeze({ ...value });
+}
+export function createDocumentClient(invoke) {
+  return Object.freeze(Object.fromEntries(['preparePdfTemplate', 'openPdfDocument'].map(operation => [operation,
+    input => invoke(operation, assertDocumentInput(operation, input)).then(value => assertDocumentResult(operation, value)),
+  ])));
+}

package/src/client/index.d.ts

@@ -169,6 +169,16 @@ export interface PageDefinition {
 }
 
 export type DefinedPage = Readonly<PageDefinition & { type: "page" }>;
+/** 结果来自同次已校验 Action；身份与导航 owner 由 Host 绑定。 */
+export interface ToolRendererProps<Result = unknown> {
+  readonly result: Result;
+  readonly actionKey: string;
+}
+export interface ToolRendererDefinition<Result = unknown> {
+  key: string;
+  Renderer: ComponentType<ToolRendererProps<Result>>;
+}
+export function defineToolRenderer<Result>(definition: ToolRendererDefinition<Result>): Readonly<ToolRendererDefinition<Result> & { type: 'tool-renderer' }>;
 export type FrontendExtensionDefinition =
   | SettingsExtensionDefinition
   | RecordActionDefinition
@@ -251,3 +261,9 @@ export function queryAnalysis(request: import('./analysis.js').AnalysisRequest):
 export type { OpenAssistantOptions } from './interactions.js';
 /** 打开侧边助手；首次发言才调用模型，context 仅作为新会话初始背景。 */
 export function openAssistant(options: import('./interactions.js').OpenAssistantOptions): Promise<void>;
+
+export type { RestrictedInputSchema, PreparePdfTemplateInput, OpenPdfDocumentInput, PreparedPdfTemplate, OpenPdfDocumentResult } from './documents.js';
+/** Desktop制作；取消返回null。缺能力或旧Host返回runtime_document_unsupported。 */
+export function preparePdfTemplate(input: import('./documents.js').PreparePdfTemplateInput): Promise<import('./documents.js').PreparedPdfTemplate | null>;
+/** Desktop/H5认证文件交付；started只表示已交浏览器，不证明磁盘保存。 */
+export function openPdfDocument(input: import('./documents.js').OpenPdfDocumentInput): Promise<import('./documents.js').OpenPdfDocumentResult>;

package/src/client/index.js

@@ -5,6 +5,14 @@ const FRONTEND_EXTENSION_MARKER = Symbol.for("zhike.frontend-extension.v1");
 const PAGE_VARIANTS = new Set(["full", "centered"]);
 const PAGE_ICONS = new Set(sdkIconNames);
 
+export function defineToolRenderer(definition) {
+  if (!definition || typeof definition !== 'object' || Array.isArray(definition)
+    || Object.keys(definition).some(key => !['key', 'Renderer'].includes(key))
+    || typeof definition.key !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(definition.key)
+    || typeof definition.Renderer !== 'function') throw new TypeError('tool_renderer_definition_invalid');
+  return Object.freeze({ ...definition, type: 'tool-renderer' });
+}
+
 export function defineFrontendExtension(definition) {
   if (!definition || typeof definition !== "object" || Array.isArray(definition)) {
     throw new TypeError("Frontend Extension definition 必须是对象");
@@ -76,3 +84,5 @@ export function getCurrentUser() { throw new Error('current_user_unavailable');
 
 export function queryAnalysis() { return Promise.reject(new Error('runtime_analysis_unavailable')); }
 export function openAssistant() { return Promise.reject(new Error('runtime_host_interaction_unavailable')); }
+export function preparePdfTemplate() { return Promise.reject(new Error('runtime_document_unsupported')); }
+export function openPdfDocument() { return Promise.reject(new Error('runtime_document_unsupported')); }

package/src/client/interactions.d.ts

@@ -11,7 +11,7 @@ export interface ToastOptions { message: string; tone?: 'info' | 'success' | 'er
 export interface ConfirmOptions { title: string; description?: string; confirmLabel?: string; cancelLabel?: string }
 export interface OpenExternalUrlOptions { url: string }
 export interface NavigateOptions { destination: import('./destinations.js').AppDestination }
-export type HostInteraction = {operation:'openAssistant';input:OpenAssistantOptions} | {operation:'showToast';input:ToastOptions} | {operation:'confirm';input:ConfirmOptions} | {operation:'navigate';input:NavigateOptions} | {operation:'openExternal';input:OpenExternalOptions} | {operation:'openExternalUrl';input:OpenExternalUrlOptions};
+export type HostInteraction = {operation:'preparePdfTemplate';input:import('./documents.js').PreparePdfTemplateInput} | {operation:'openPdfDocument';input:import('./documents.js').OpenPdfDocumentInput} | {operation:'openAssistant';input:OpenAssistantOptions} | {operation:'showToast';input:ToastOptions} | {operation:'confirm';input:ConfirmOptions} | {operation:'navigate';input:NavigateOptions} | {operation:'openExternal';input:OpenExternalOptions} | {operation:'openExternalUrl';input:OpenExternalUrlOptions};
 export function assertHostInteraction(operation: unknown, input: unknown): Readonly<ToastOptions | ConfirmOptions | NavigateOptions | OpenExternalOptions | OpenExternalUrlOptions | OpenAssistantOptions>;
 export function createClientInteractions(invoke: (operation: string, input: ToastOptions | ConfirmOptions | NavigateOptions | OpenExternalOptions | OpenExternalUrlOptions | OpenAssistantOptions) => Promise<unknown>): {
   openAssistant(input: OpenAssistantOptions): Promise<void>;

package/src/client/interactions.js

@@ -1,3 +1,4 @@
+import { assertDocumentInput } from './documents.js';
 import { assertExternalUrl } from './external-url.js';
 import { assertAppDestination } from './destinations.js';
 
@@ -11,6 +12,7 @@ const externalUrl = value => {
   } catch { return false; }
 };
 export function assertHostInteraction(operation, input) {
+  if (['preparePdfTemplate', 'openPdfDocument'].includes(operation)) return assertDocumentInput(operation, input);
   if (!input || typeof input !== 'object' || Array.isArray(input)) fail();
   const allowed = operation === 'openAssistant' ? ['scenario','context','title'] : operation === 'showToast' ? ['message','tone'] : operation === 'confirm' ? ['title','description','confirmLabel','cancelLabel'] : operation === 'navigate' ? ['destination'] : operation === 'openExternal' ? ['href'] : operation === 'openExternalUrl' ? ['url'] : [];
   if (!allowed.length || Object.keys(input).some(key=>!allowed.includes(key))) fail();

package/src/client/points.generated.js

@@ -62,6 +62,14 @@ export const frontendPoints = Object.freeze([
     "definitionName": "PageDefinition",
     "componentName": "Page",
     "maxPerApp": 100
+  },
+  {
+    "key": "app.tool-renderers",
+    "kind": "view",
+    "legacyType": "tool-renderer",
+    "definitionName": "ToolRendererDefinition",
+    "componentName": "Renderer",
+    "maxPerApp": 64
   }
 ].map(Object.freeze));
 export const frontendPoint = type => frontendPoints.find(point => point.legacyType === type);

package/src/forms/index.d.ts

@@ -71,6 +71,8 @@ export interface FormHandle<S extends FormSchema> {
   placeholder?: string;
   disabled?: boolean;
   resizable?: boolean;
+  labelHidden?: boolean;
+  appearance?: "default" | "revision";
   }>;
   NumberInput: ComponentType<{
   name: FieldName<S, "number">;

package/src/server/agents/index.d.ts

@@ -4,6 +4,9 @@ export interface AppAgentDefinition {
   name: string;
   /** App 提供的系统提示词，最多 16KiB UTF-8，不交付 Client Worker。 */
   systemPrompt: string;
+  /** 引用同 App 独立 Action 的 key，Schema/execute 只维护一份。 */
+  actionRefs?: readonly string[];
+  aiExposure?: AppExpertExposure;
 }
 export type ToolSchema = Readonly<Record<string, unknown>>;
 export interface AppToolDefinition<Input, Output> {
@@ -15,8 +18,42 @@ export interface AppToolDefinition<Input, Output> {
   outputSchema: ToolSchema;
   /** 默认 none；output 只允许成功且通过校验的结果进入实时 callback。 */
   clientResult?: 'none' | 'output';
+  /** 缺省私有；公开查询声明不代替执行授权。 */
+  aiExposure?: AppActionExposure;
+  /** 同 App 静态 Tool Renderer；展示不授予服务端执行或业务写入权限。 */
+  toolRenderer?: { key: string; showByDefault: boolean };
   /** 仅在所属安装的服务端执行环境运行，凭据沿用现有 Server SDK。 */
   execute(input: Input): Output | Promise<Output>;
 }
 export function defineAgent(definition: AppAgentDefinition): Readonly<AppAgentDefinition>;
 export function defineTool<Input = Record<string, unknown>, Output = unknown>(definition: AppToolDefinition<Input, Output>): Readonly<AppToolDefinition<Input, Output>>;
+
+export interface AppActionExposure {
+  effect: 'query';
+  /** 公开 object 标识；只用于说明适用对象，不授予权限。 */
+  subjectTypes: readonly string[];
+  usage: string;
+  limitations: string;
+  /** 已有 inputSchema 中接收 {object, recordId} 的字段；由 Host 绑定。 */
+  subjectInput?: string;
+}
+export interface AppExpertExposure {
+  subjectTypes: readonly string[];
+  usage: string;
+  limitations: string;
+  outputSchema: ToolSchema;
+  /** 只允许显式开放的原私有工具子集；独立能力沿 actionRefs。 */
+  toolKeys?: readonly string[];
+}
+interface AppDataCapabilityBase {
+  key: string;
+  name: string;
+  description: string;
+  subjectTypes: readonly string[];
+  usage: string;
+}
+export type AppDataCapabilityDefinition = AppDataCapabilityBase & (
+  { kind: 'live'; actionRef: string; sourceBinding?: never } |
+  { kind: 'published'; sourceBinding: string; actionRef?: never }
+);
+export function defineDataCapability<T extends AppDataCapabilityDefinition>(definition: T): Readonly<T>;

package/src/server/agents/index.js

@@ -1,3 +1,6 @@
+import { assertDataCapability } from '../../toolchain/ai-capabilities.js';
+import { assertAiExposure } from '../../toolchain/agents/exposure.js';
+import { assertToolRendererReference } from '../../toolchain/agents/manifest.js';
 const KEY = /^[a-z][a-z0-9-]{0,63}$/;
 
 function fields(value, required, optional = []) {
@@ -11,7 +14,7 @@ function fields(value, required, optional = []) {
 }
 
 export function defineAgent(definition) {
-  fields(definition, ["key", "name", "systemPrompt"]);
+  fields(definition, ["key", "name", "systemPrompt"], ["actionRefs", "aiExposure"]);
   if (typeof definition.systemPrompt !== "string" || !definition.systemPrompt.trim() ||
       new TextEncoder().encode(definition.systemPrompt).length > 16384) {
     throw new TypeError("agent_definition_invalid");
@@ -20,11 +23,18 @@ export function defineAgent(definition) {
 }
 
 export function defineTool(definition) {
-  fields(definition, ["key", "name", "description", "inputSchema", "outputSchema", "execute"], ["clientResult"]);
+  fields(definition, ["key", "name", "description", "inputSchema", "outputSchema", "execute"], ["clientResult", "aiExposure", "toolRenderer"]);
   if (typeof definition.execute !== "function" || typeof definition.description !== "string" ||
       !definition.description.trim() || definition.description.length > 1200 ||
       ![undefined, "none", "output"].includes(definition.clientResult)) {
     throw new TypeError("agent_tool_definition_invalid");
   }
+  if (definition.aiExposure !== undefined) assertAiExposure(definition.aiExposure, definition.inputSchema);
+  if (definition.toolRenderer !== undefined) assertToolRendererReference(definition.toolRenderer);
   return Object.freeze({ ...definition, clientResult: definition.clientResult ?? "none" });
 }
+
+export function defineDataCapability(definition) {
+  assertDataCapability(definition);
+  return Object.freeze({ ...definition });
+}

package/src/server/index.d.ts

@@ -1,4 +1,4 @@
-export { defineAgent, defineTool, type AppAgentDefinition, type AppToolDefinition, type ToolSchema } from "./agents/index.js";
+export { defineAgent, defineTool, defineDataCapability, type AppAgentDefinition, type AppToolDefinition, type ToolSchema } from "./agents/index.js";
 import type { JsonValue } from "../index.js";
 export { defineWorkflowStep, defineWorkflowStepExecute } from "./steps/index.js";
 export type { WorkflowObjectSchema, WorkflowScalarSchema, WorkflowStepDefinition, WorkflowStepOutcome, WorkflowStepResult, WorkflowSchemaValue } from "./steps/index.js";
@@ -319,3 +319,5 @@ export interface WebhookContext {
   /** 从 1 开始的业务尝试序号。 */
   readonly attemptNumber: number;
 }
+
+export type { AppActionExposure, AppExpertExposure, AppDataCapabilityDefinition } from "./agents/index.js";

package/src/server/index.js

@@ -1,4 +1,4 @@
-export { defineAgent, defineTool } from "./agents/index.js";
+export { defineAgent, defineTool, defineDataCapability } from "./agents/index.js";
 const SERVER_FUNCTION_MARKER = Symbol.for("zhike.server-function.v1");
 export { defineWorkflowStep, defineWorkflowStepExecute } from "./steps/index.js";
 export { defineWorkflowTrigger, defineWorkflowTriggerActivate, defineWorkflowTriggerOnEvent, defineWorkflowTriggerDeactivate } from "./triggers/index.js";

package/src/toolchain/agents/discovery.js

@@ -1,9 +1,12 @@
 import ts from 'typescript';
 import { posix } from 'node:path';
 import { ZhikeCliError } from '../../errors.js';
+import { assertAiCapabilities } from '../ai-capabilities.js';
 import { assertAgentManifest } from './manifest.js';
 
 const AGENT_PATH = /^app\/agents\/([a-z][a-z0-9-]{0,63})\/agent\.ts$/;
+const ACTION_PATH = /^app\/actions\/([a-z][a-z0-9-]{0,63})\.tools\.ts$/;
+const DATA_PATH = /^app\/data-capabilities\/([a-z][a-z0-9-]{0,63})\.ts$/;
 const TOOL_PATH = /^app\/agents\/([a-z][a-z0-9-]{0,63})\/([a-z][a-z0-9-]{0,63})\.tools\.ts$/;
 function invalid(path, message) { throw new ZhikeCliError('zhike_agent_invalid', `${path}: ${message}`); }
 function literal(node, path, depth = 0) {
@@ -28,7 +31,7 @@ function literal(node, path, depth = 0) {
   invalid(path, '元数据不能读取变量、函数或运行时代码');
 }
 
-function definition(file, api) {
+export function definition(file, api) {
   const { sourceFile, relativePath } = file;
   const imported = sourceFile.statements.some(statement => ts.isImportDeclaration(statement) &&
     statement.moduleSpecifier.text === '@77-zhike/app-sdk/server' &&
@@ -62,19 +65,20 @@ export function discoverAgents(files) {
     const match = file.relativePath.match(AGENT_PATH);
     if (!match) continue;
     const value = definition(file, 'defineAgent');
-    if (value.key !== match[1] || Object.keys(value).some(key => !['key', 'name', 'systemPrompt'].includes(key))) invalid(file.relativePath, 'Agent key 必须等于目录且只接受 key/name/systemPrompt');
+    if (value.key !== match[1] || Object.keys(value).some(key => !['key', 'name', 'systemPrompt', 'actionRefs', 'aiExposure'].includes(key))) invalid(file.relativePath, 'Agent key 必须等于目录且只接受 key/name/systemPrompt');
     agents.set(value.key, { ...value, relativePath: file.relativePath, tools: [] });
   }
   if (agents.size > 16) invalid("app/agents", "一个 App 最多 16 个 Agent");
   for (const file of files) {
     const match = file.relativePath.match(TOOL_PATH);
-    if (file.relativePath.endsWith('.tools.ts') && !match) invalid(file.relativePath, '工具必须位于 Agent 的直接子目录');
+    if (file.relativePath.endsWith('.tools.ts') && !match && !ACTION_PATH.test(file.relativePath)) invalid(file.relativePath, '工具必须位于 Agent 的直接子目录');
     if (/^app\/agents\/.+\/agent\.(?:ts|tsx)$/.test(file.relativePath) && !AGENT_PATH.test(file.relativePath)) invalid(file.relativePath, 'Agent 入口必须是直接子目录 agent.ts');
     for (const statement of file.sourceFile.statements) {
       if (!(ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) || !statement.moduleSpecifier || !ts.isStringLiteral(statement.moduleSpecifier)) continue;
       const specifier = statement.moduleSpecifier.text;
       if (!specifier.startsWith('.')) continue;
       const target = posix.normalize(posix.join(posix.dirname(file.relativePath), specifier)).replace(/\.js$/, '.ts');
+      if (ACTION_PATH.test(target.endsWith('.ts') ? target : `${target}.ts`)) invalid(file.relativePath, '独立 Action 只能通过 actionRefs 引用，不能导入执行声明；请抽取普通 helper');
       const tool = (target.endsWith(".ts") ? target : `${target}.ts`).match(TOOL_PATH);
       if (tool && (!match || match[1] !== tool[1])) invalid(file.relativePath, '不能跨 Agent 导入工具声明，请抽取普通 helper');
     }
@@ -97,3 +101,26 @@ export function discoverAgents(files) {
 export function agentManifest({ relativePath, tools, ...agent }) {
   return { ...agent, tools: tools.map(({ relativePath: path, ...tool }) => tool) };
 }
+
+export function discoverAiCapabilities(files, agents) {
+  const actions = [], dataCapabilities = [];
+  for (const file of files) {
+    const action = file.relativePath.match(ACTION_PATH);
+    const data = file.relativePath.match(DATA_PATH);
+    if (file.relativePath.startsWith('app/actions/') && file.relativePath.endsWith('.tools.ts') && !action) invalid(file.relativePath, 'Action 必须位于 actions 直接目录');
+    if (!action && !data) continue;
+    const value = definition(file, action ? 'defineTool' : 'defineDataCapability');
+    if (value.key !== (action ?? data)[1]) invalid(file.relativePath, 'key 必须与文件名一致');
+    if (action) {
+      if (value.execute !== true) invalid(file.relativePath, 'Action 缺少 execute');
+      delete value.execute;
+      actions.push({...value, clientResult:value.clientResult ?? 'none', artifact:'server', entry:`action/${value.key}`, relativePath:file.relativePath});
+    } else dataCapabilities.push({...value, relativePath:file.relativePath});
+  }
+  actions.sort((a,b)=>a.key.localeCompare(b.key));
+  dataCapabilities.sort((a,b)=>a.key.localeCompare(b.key));
+  try { assertAiCapabilities({sdkAbiVersion:'2',aiCapabilitiesVersion:'1',actions:actions.map(stripPath),dataCapabilities:dataCapabilities.map(stripPath),agents:agents.map(agentManifest)}); }
+  catch { invalid('app/actions', '独立能力声明或跨引用无效'); }
+  return {actions, dataCapabilities};
+}
+export function stripPath({relativePath, ...value}) { return value; }

package/src/toolchain/agents/exposure.js

@@ -0,0 +1,31 @@
+const OBJECT = /^[a-z][a-z0-9_]{0,63}$/;
+export function assertAiExposure(value, inputSchema, expert = false) {
+  const invalid = () => { throw new TypeError('app_manifest_ai_exposure_invalid'); };
+  const allowed = expert
+    ? ['subjectTypes', 'usage', 'limitations', 'outputSchema', 'toolKeys']
+    : ['subjectTypes', 'usage', 'limitations', 'effect', 'subjectInput'];
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+      Object.keys(value).some(key => !allowed.includes(key)) ||
+      !Array.isArray(value.subjectTypes) || value.subjectTypes.length > 16 ||
+      new Set(value.subjectTypes).size !== value.subjectTypes.length ||
+      value.subjectTypes.some(item => typeof item !== 'string' || !OBJECT.test(item))) invalid();
+  for (const key of ['usage', 'limitations']) {
+    if (typeof value[key] !== 'string' || !value[key].trim() || value[key].length > 1200) invalid();
+  }
+  if (expert) {
+    if (!value.outputSchema || (value.toolKeys !== undefined && (!Array.isArray(value.toolKeys) ||
+        new Set(value.toolKeys).size !== value.toolKeys.length ||
+        value.toolKeys.some(key => typeof key !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(key))))) invalid();
+  } else {
+    if (value.effect !== 'query') invalid();
+    if (value.subjectInput !== undefined) {
+      const subject = inputSchema?.properties?.[value.subjectInput];
+      if (typeof value.subjectInput !== 'string' || !Object.hasOwn(inputSchema.properties, value.subjectInput) ||
+          subject?.type !== 'object' || subject.additionalProperties !== false ||
+          Object.keys(subject.properties ?? {}).sort().join(',') !== 'object,recordId' ||
+          subject.properties.object?.type !== 'string' || subject.properties.recordId?.type !== 'string' ||
+          !subject.required?.includes('object') || !subject.required?.includes('recordId')) invalid();
+    }
+  }
+  return value;
+}

package/src/toolchain/agents/manifest.js

@@ -1,3 +1,4 @@
+import { assertAiExposure } from './exposure.js';
 const KEY = /^[a-z][a-z0-9-]{0,63}$/;
 const FIELD = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
 const RESERVED = new Set(['tenant_id', 'tenantId', 'member_id', 'memberId', 'installation_id', 'installationId',
@@ -46,17 +47,35 @@ export function assertAgentSchema(value) {
 }
 
 export function assertAgentManifest(value) {
-  record(value); keys(value, ['key', 'name', 'systemPrompt', 'tools']);
+  record(value); keys(value, ['key', 'name', 'systemPrompt', 'tools', 'actionRefs', 'aiExposure']);
   if (typeof value.key !== "string" || value.key.trim() !== value.key || !KEY.test(value.key)) invalid();
   text(value.name, 80); text(value.systemPrompt, 16384);
   if (new TextEncoder().encode(value.systemPrompt).length > 16384 || !Array.isArray(value.tools) || value.tools.length > 32) invalid();
   const seen = new Set();
   for (const tool of value.tools) {
-    record(tool); keys(tool, ['artifact', 'key', 'entry', 'name', 'description', 'inputSchema', 'outputSchema', 'clientResult']);
-    if (typeof tool.key !== "string" || tool.key.trim() !== tool.key || !KEY.test(tool.key) || seen.has(tool.key) || tool.artifact !== 'server' ||
-        tool.entry !== `agent-tool/${value.key}/${tool.key}` || !['none', 'output'].includes(tool.clientResult)) invalid();
-    seen.add(tool.key); text(tool.name, 80); text(tool.description, 1200);
-    assertAgentSchema(tool.inputSchema); assertAgentSchema(tool.outputSchema);
+    if (seen.has(tool.key)) invalid();
+    seen.add(tool.key);
+    assertToolManifest(tool, `agent-tool/${value.key}/${tool.key}`);
   }
   return value;
 }
+
+export function assertToolManifest(tool, entry) {
+  record(tool); keys(tool, ['artifact', 'key', 'entry', 'name', 'description', 'inputSchema', 'outputSchema', 'clientResult', 'aiExposure', 'toolRenderer']);
+  if (typeof tool.key !== 'string' || tool.key.trim() !== tool.key || !KEY.test(tool.key) ||
+      tool.artifact !== 'server' || tool.entry !== entry || !['none', 'output'].includes(tool.clientResult)) invalid();
+  text(tool.name, 80); text(tool.description, 1200);
+  assertAgentSchema(tool.inputSchema); assertAgentSchema(tool.outputSchema);
+  if (tool.toolRenderer !== undefined) assertToolRendererReference(tool.toolRenderer);
+  if (tool.aiExposure !== undefined) {
+    if (Object.hasOwn(tool.inputSchema.properties, 'explanation')) invalid();
+    assertAiExposure(tool.aiExposure, tool.inputSchema);
+  }
+  return tool;
+}
+
+export function assertToolRendererReference(value) {
+  record(value); keys(value, ['key', 'showByDefault']);
+  if (typeof value.key !== 'string' || !KEY.test(value.key) || typeof value.showByDefault !== 'boolean') invalid();
+  return value;
+}

package/src/toolchain/ai-capabilities.js

@@ -0,0 +1,69 @@
+import { assertToolManifest, assertAgentSchema } from './agents/manifest.js';
+import { assertAiExposure } from './agents/exposure.js';
+
+export function assertAiCapabilities(manifest) {
+  const invalid = () => { throw new TypeError('app_manifest_ai_capabilities_invalid'); };
+  const actions = manifest.actions === undefined ? [] : manifest.actions;
+  const data = manifest.dataCapabilities === undefined ? [] : manifest.dataCapabilities;
+  const agents = manifest.agents ?? [];
+  const hasAiFields = manifest.actions !== undefined || manifest.dataCapabilities !== undefined ||
+    agents.some(agent => agent.aiExposure !== undefined || agent.actionRefs !== undefined ||
+      agent.tools.some(tool => tool.aiExposure !== undefined));
+  if (manifest.aiCapabilitiesVersion !== undefined && manifest.aiCapabilitiesVersion !== '1') invalid();
+  if (hasAiFields && manifest.aiCapabilitiesVersion !== '1') invalid();
+  if (manifest.aiCapabilitiesVersion !== undefined && manifest.sdkAbiVersion !== '2') invalid();
+  if (!Array.isArray(actions) || actions.length > 64 || !Array.isArray(data) || data.length > 64) invalid();
+  if (manifest.frontendExtensions !== undefined) {
+    const renderers = new Set(manifest.frontendExtensions.filter(item => item.type === 'tool-renderer').map(item => item.key));
+    for (const tool of [...actions, ...agents.flatMap(agent => agent.tools)]) {
+      if (tool.toolRenderer && !renderers.has(tool.toolRenderer.key)) invalid();
+    }
+  }
+  const byKey = new Map();
+  for (const action of actions) {
+    assertToolManifest(action, `action/${action.key}`);
+    if (byKey.has(action.key) || action.clientResult !== 'none') invalid();
+    byKey.set(action.key, action);
+  }
+  const dataKeys = new Set();
+  for (const item of data) {
+    assertDataCapability(item);
+    if (dataKeys.has(item.key)) invalid();
+    dataKeys.add(item.key);
+    if (item.kind === 'live') {
+      const action = byKey.get(item.actionRef);
+      if (!action?.aiExposure || item.sourceBinding !== undefined ||
+          item.subjectTypes.some(type => !action.aiExposure.subjectTypes.includes(type))) invalid();
+    } else if (item.kind === 'published') {
+      if (typeof item.sourceBinding !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(item.sourceBinding) || item.actionRef !== undefined) invalid();
+    } else invalid();
+  }
+  for (const agent of agents) {
+    const refs = agent.actionRefs === undefined ? [] : agent.actionRefs;
+    if (!Array.isArray(refs) || refs.length > 32 || new Set(refs).size !== refs.length || refs.some(ref => !byKey.has(ref))) invalid();
+    if (agent.aiExposure !== undefined) {
+      assertAiExposure(agent.aiExposure, null, true);
+      assertAgentSchema(agent.aiExposure.outputSchema);
+      if (refs.some(ref => !byKey.get(ref).aiExposure) ||
+          (agent.aiExposure.toolKeys ?? []).some(key => !agent.tools.find(tool => tool.key === key)?.aiExposure)) invalid();
+    }
+  }
+  return manifest;
+}
+
+export function assertDataCapability(item) {
+  const invalid = () => { throw new TypeError('app_manifest_ai_capabilities_invalid'); };
+    if (!item || typeof item !== 'object' || Array.isArray(item) ||
+        Object.keys(item).some(key => !['key', 'name', 'description', 'subjectTypes', 'kind', 'sourceBinding', 'actionRef', 'usage'].includes(key)) ||
+        typeof item.key !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(item.key)) invalid();
+    for (const [key, max] of [['name', 80], ['description', 1200], ['usage', 1200]]) {
+      if (typeof item[key] !== 'string' || !item[key].trim() || item[key].length > max) invalid();
+    }
+    assertAiExposure({subjectTypes:item.subjectTypes, usage:item.usage, limitations:item.description, effect:'query'});
+  if (item.kind === 'published') {
+    if (typeof item.sourceBinding !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(item.sourceBinding) || item.actionRef !== undefined) invalid();
+  } else if (item.kind === 'live') {
+    if (typeof item.actionRef !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(item.actionRef) || item.sourceBinding !== undefined) invalid();
+  } else invalid();
+  return item;
+}

package/src/toolchain/real-build.js

@@ -6,7 +6,7 @@ import { dirname, relative, resolve, sep } from "node:path";
 import { build } from "esbuild";
 import ts from "typescript";
 
-import { agentManifest } from "./agents/discovery.js";
+import { agentManifest, stripPath } from "./agents/discovery.js";
 import { serializeWebhookResponse } from "./webhook-response.js";
 
 import { TOOLING_VERSION } from "../config.js";
@@ -43,7 +43,7 @@ export async function buildAppBundle({
       sources.serverFunctions.length > 0 ||
       sources.webhookHandlers.length > 0 ||
       sources.workflowSteps.length > 0 ||
-      sources.workflowTriggers.length > 0 || sources.agents.length > 0
+      sources.workflowTriggers.length > 0 || sources.agents.length > 0 || sources.actions.length > 0
       ? await buildServerArtifact(projectDirectory, sources) : null;
   } catch (error) {
     const policyError = error.errors?.find(item => item.detail instanceof ZhikeCliError)?.detail;
@@ -96,7 +96,7 @@ export async function buildAppBundle({
   });
 }
 
-async function assertTypeScriptProgram(projectDirectory, { sourceFiles, serverFunctions, agents }) {
+async function assertTypeScriptProgram(projectDirectory, { sourceFiles, serverFunctions, agents, actions }) {
   const paths = {
     "@77-zhike/app-sdk": [resolve(SDK_SOURCE_ROOT, "index.d.ts")],
     "@77-zhike/app-sdk/client": [resolve(SDK_SOURCE_ROOT, "client", "index.d.ts")],
@@ -129,6 +129,7 @@ async function assertTypeScriptProgram(projectDirectory, { sourceFiles, serverFu
   const handlers = [
     ...serverFunctions.map(item => ({ ...item, member: '' })),
     ...agents.flatMap(agent => agent.tools.map(item => ({ ...item, member: '.execute' }))),
+    ...actions.map(item => ({...item, member: '.execute'})),
   ];
   const contractSource = [
     'import type { ServerFunction } from "@77-zhike/app-sdk/server";',
@@ -194,10 +195,10 @@ async function buildServerArtifact(projectDirectory, sources) {
   const hasConnectionLifecycle = sources.lifecycleEvents.some(
     ({ event }) => event === "connection-added" || event === "connection-removed",
   );
-  const tools = sources.agents.flatMap(agent => agent.tools);
+  const tools = [...sources.agents.flatMap(agent => agent.tools), ...sources.actions];
   const toolImports = tools.map((tool, index) => `import agentTool${index} from "./src/${tool.relativePath}";`);
   const agentToolDeclarations = `const agentTools = new Map([${tools.map((tool, index) => `[${JSON.stringify(tool.entry)}, agentTool${index}]`).join(",")}]);`;
-  const agentToolDispatch = `  if (request.kind === "agent_tool") { const tool = agentTools.get(request.entryKey); if (!tool) throw new Error("runtime_agent_tool_not_found"); return tool.execute(Object.freeze({ ...request.input })); }\n`;
+  const agentToolDispatch = `  if (request.kind === "agent_tool" || request.kind === "app_action") { const prefix = request.kind === "app_action" ? "action/" : "agent-tool/"; const tool = typeof request.entryKey === "string" && request.entryKey.startsWith(prefix) ? agentTools.get(request.entryKey) : null; if (!tool) throw new Error("runtime_agent_tool_not_found"); return tool.execute(Object.freeze({ ...request.input })); }\n`;
   const imports = [
     ...toolImports,
     ...(hasConnectionLifecycle
@@ -327,7 +328,7 @@ function createSdkBuildPlugin(projectDirectory, sources, target) {
       buildApi.onLoad({ filter: /.*/, namespace: "zhike-sdk-runtime" }, (args) => {
         if (args.path.endsWith("/client")) {
           return {
-            contents: "export const defineFrontendExtension = (definition) => definition; export const definePage = (definition) => ({ ...definition, type: 'page' });",
+            contents: "export const defineFrontendExtension = (definition) => definition; export const definePage = (definition) => ({ ...definition, type: 'page' }); export const defineToolRenderer = (definition) => ({ ...definition, type: 'tool-renderer' });",
             loader: "js",
           };
         }
@@ -411,6 +412,9 @@ function createManifest({ clientBytes, serverBytes, sources }) {
       key,
     })),
     ...(sources.agents.length ? { agents: sources.agents.map(agentManifest) } : {}),
+    ...((sources.actions.length || sources.dataCapabilities.length || sources.agents.some(agent => agent.aiExposure || agent.actionRefs || agent.tools.some(tool => tool.aiExposure))) ? {aiCapabilitiesVersion:'1'} : {}),
+    ...(sources.actions.length ? {actions:sources.actions.map(stripPath)} : {}),
+    ...(sources.dataCapabilities.length ? {dataCapabilities:sources.dataCapabilities.map(stripPath)} : {}),
     serverFunctions: sources.serverFunctions.map(({ key }) => ({
       artifact: "server",
       key,
@@ -444,6 +448,7 @@ function createServerDefinitionsDigest(sources) {
       ...(sources.agents.length ? { agents: sources.agents.map(({ key, tools }) => ({
         key, tools: tools.map(({ key: toolKey, entry }) => ({ key: toolKey, entry })),
       })) } : {}),
+      ...(sources.actions.length ? {actions:sources.actions.map(({key,entry})=>({key,entry}))} : {}),
       serverFunctions: sources.serverFunctions.map(({ key }) => ({ key })),
       webhookHandlers: sources.webhookHandlers.map(({ key, methods }) => ({ key, methods })),
       ...(sources.workflowSteps.length > 0 ? { workflowSteps: sources.workflowSteps.map(({ key, entry }) => ({ key, entry })) } : {}),