@77-zhike/app-sdk 0.2.0-d7b1.2 → 0.2.0-d7b1.20

package/src/server/index.js

@@ -1,4 +1,14 @@
+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";
+export {
+  defineWorkflowBlock,
+  defineWorkflowBlockExecute,
+  defineWorkflowBlockActivate,
+  defineWorkflowBlockTrigger,
+  defineWorkflowBlockDeactivate,
+} from "./workflow-blocks/index.js";
 const LIFECYCLE_EVENT_MARKER = Symbol.for("zhike.lifecycle-event.v1");
 const WEBHOOK_HANDLER_MARKER = Symbol.for("zhike.webhook-handler.v1");
 const WORKSPACE_CONNECTION_EVENTS = new Set([
@@ -9,6 +19,7 @@ const WORKSPACE_CONNECTION_EVENTS = new Set([
 ]);
 
 export const ZHIKE_API_TOKEN = globalThis.ZHIKE_API_TOKEN;
+export const ZHIKE_CURRENT_USER_TOKEN = globalThis.ZHIKE_CURRENT_USER_TOKEN;
 const ZHIKE_OPEN_API_BASE_URL = "https://api-clm.77hub.com/v1";
 export const kv = globalThis.ZHIKE_APP_KV;
 
@@ -145,11 +156,43 @@ export function getWorkspaceConnection() {
     error.code = code;
     throw error;
   }
+  if (connection.protocol === "oidc" && (typeof connection.idToken !== "string" || !connection.idToken)) {
+    const error = new Error("connection_credential_unavailable");
+    error.code = "connection_credential_unavailable";
+    throw error;
+  }
+  const protocol = connection.type === "secret"
+    ? "secret"
+    : (connection.protocol === "oidc" && typeof connection.idToken === "string" && connection.idToken
+      ? "oidc" : "oauth2");
   return Object.freeze({
     id: connection.id,
     generation: connection.generation,
     type: connection.type,
+    protocol,
     value: connection.value,
+    ...(connection.type === "oauth2" ? { accessToken: connection.value } : {}),
+    ...(protocol === "oidc" ? { idToken: connection.idToken } : {}),
+  });
+}
+
+export function getCurrentUser() {
+  const current = globalThis.ZHIKE_CURRENT_USER;
+  if (
+    !current ||
+    typeof current !== "object" ||
+    typeof current.workspaceMemberId !== "string" ||
+    typeof current.displayName !== "string"
+  ) {
+    const error = new Error("current_user_unavailable");
+    error.code = "current_user_unavailable";
+    throw error;
+  }
+  return Object.freeze({
+    workspaceMemberId: current.workspaceMemberId,
+    displayName: current.displayName,
+    primaryEmailAddress: typeof current.primaryEmailAddress === "string" ? current.primaryEmailAddress : null,
+    avatarUrl: typeof current.avatarUrl === "string" ? current.avatarUrl : null,
   });
 }
 

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

@@ -0,0 +1,71 @@
+export type WorkflowScalarSchema =
+  | { readonly type: "string"; readonly minLength?: number; readonly enum?: readonly string[]; readonly title?: string; readonly description?: string; readonly examples?: readonly string[] }
+  | { readonly type: "number"; readonly title?: string; readonly description?: string; readonly examples?: readonly number[] }
+  | { readonly type: "boolean"; readonly title?: string; readonly description?: string; readonly examples?: readonly boolean[] };
+
+export interface WorkflowObjectSchema {
+  readonly type: "object";
+  readonly properties: Readonly<Record<string, WorkflowScalarSchema>>;
+  readonly required?: readonly string[];
+  readonly additionalProperties: false;
+  readonly title?: string;
+  readonly description?: string;
+  readonly examples?: readonly (string | number | boolean)[];
+}
+
+export interface WorkflowStepOutcome {
+  readonly id: string;
+  readonly label: string;
+  readonly dataSchema: WorkflowObjectSchema | null;
+}
+
+export interface WorkflowStepDefinition<
+  Config extends WorkflowObjectSchema = WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowStepOutcome[] = readonly WorkflowStepOutcome[],
+> {
+  readonly key: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly connection: "workspace" | "none";
+  readonly configSchema: Config;
+  readonly outcomes: Outcomes;
+}
+
+type ScalarValue<S> = S extends { readonly enum: readonly (infer E)[] } ? E
+  : S extends { readonly type: "string" } ? string
+  : S extends { readonly type: "number" } ? number
+  : S extends { readonly type: "boolean" } ? boolean
+  : never;
+
+type RequiredNames<S extends WorkflowObjectSchema> = S["required"] extends readonly string[]
+  ? S["required"][number] : never;
+
+export type WorkflowSchemaValue<S extends WorkflowObjectSchema> = {
+  [K in keyof S["properties"] as K extends RequiredNames<S> ? K : never]-?: ScalarValue<S["properties"][K]>;
+} & {
+  [K in keyof S["properties"] as K extends RequiredNames<S> ? never : K]?: ScalarValue<S["properties"][K]>;
+};
+
+type OutcomeResult<O extends WorkflowStepOutcome> = O extends WorkflowStepOutcome
+  ? O["dataSchema"] extends WorkflowObjectSchema
+    ? { readonly outcome: O["id"]; readonly data: WorkflowSchemaValue<O["dataSchema"]> }
+    : { readonly outcome: O["id"]; readonly data: null }
+  : never;
+
+export type WorkflowStepResult<Outcomes extends readonly WorkflowStepOutcome[]> =
+  OutcomeResult<Outcomes[number]>;
+
+export function defineWorkflowStep<
+  const Config extends WorkflowObjectSchema,
+  const Outcomes extends readonly [WorkflowStepOutcome, ...WorkflowStepOutcome[]],
+>(definition: WorkflowStepDefinition<Config, Outcomes>): WorkflowStepDefinition<Config, Outcomes>;
+
+export function defineWorkflowStepExecute<
+  Config extends WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowStepOutcome[],
+>(
+  step: WorkflowStepDefinition<Config, Outcomes>,
+  execute: (params: Readonly<{ config: WorkflowSchemaValue<Config> }>) =>
+    WorkflowStepResult<Outcomes> | Promise<WorkflowStepResult<Outcomes>>,
+): (params: Readonly<{ config: WorkflowSchemaValue<Config> }>) =>
+  WorkflowStepResult<Outcomes> | Promise<WorkflowStepResult<Outcomes>>;

package/src/server/steps/index.js

@@ -0,0 +1,15 @@
+const STEP_MARKER = Symbol.for("zhike.workflow-step.v1");
+
+export function defineWorkflowStep(definition) {
+  if (!definition || typeof definition !== "object") {
+    throw new TypeError("workflow_step_definition_invalid");
+  }
+  return Object.freeze({ ...definition, [STEP_MARKER]: true });
+}
+
+export function defineWorkflowStepExecute(step, execute) {
+  if (!step?.[STEP_MARKER] || typeof execute !== "function") {
+    throw new TypeError("workflow_step_execute_invalid");
+  }
+  return execute;
+}

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

@@ -0,0 +1,68 @@
+import type { WorkflowObjectSchema, WorkflowSchemaValue } from "../steps/index.js";
+
+export interface WorkflowTriggerOutcome {
+  readonly id: string;
+  readonly label: string;
+  readonly dataSchema: WorkflowObjectSchema;
+}
+
+export interface WorkflowTriggerDefinition<
+  Config extends WorkflowObjectSchema = WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowTriggerOutcome[] = readonly WorkflowTriggerOutcome[],
+> {
+  readonly key: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly connection: "workspace" | "none";
+  readonly requestHeaders?: readonly string[];
+  readonly configSchema: Config;
+  readonly outcomes: Outcomes;
+}
+
+type OutcomeResult<O extends WorkflowTriggerOutcome> = O extends WorkflowTriggerOutcome
+  ? {
+      readonly type: "outcome";
+      readonly id: O["id"];
+      readonly eventKey: string;
+      readonly data: WorkflowSchemaValue<O["dataSchema"]>;
+    }
+  : never;
+
+export type WorkflowTriggerEventResult<Outcomes extends readonly WorkflowTriggerOutcome[]> =
+  | { readonly type: "no-op" }
+  | { readonly type: "error"; readonly code: "invalid_signature"; readonly retryable: false }
+  | OutcomeResult<Outcomes[number]>;
+
+export function defineWorkflowTrigger<
+  const Config extends WorkflowObjectSchema,
+  const Outcomes extends readonly [WorkflowTriggerOutcome, ...WorkflowTriggerOutcome[]],
+>(definition: WorkflowTriggerDefinition<Config, Outcomes>): WorkflowTriggerDefinition<Config, Outcomes>;
+
+export function defineWorkflowTriggerActivate<Config extends WorkflowObjectSchema>(
+  trigger: WorkflowTriggerDefinition<Config>,
+  handler: (params: Readonly<{
+    config: WorkflowSchemaValue<Config>;
+    activationId: string;
+    triggerCallbackUrl: string;
+  }>) => Promise<Readonly<{ subscriptionRef: string | null }>>,
+): typeof handler;
+
+export function defineWorkflowTriggerOnEvent<
+  Config extends WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowTriggerOutcome[],
+>(
+  trigger: WorkflowTriggerDefinition<Config, Outcomes>,
+  handler: (params: Readonly<{
+    config: WorkflowSchemaValue<Config>;
+    body: string;
+    headers: Readonly<Record<string, string>>;
+  }>) => Promise<WorkflowTriggerEventResult<Outcomes>>,
+): typeof handler;
+
+export function defineWorkflowTriggerDeactivate(
+  trigger: WorkflowTriggerDefinition,
+  handler: (params: Readonly<{
+    activationId: string;
+    subscriptionRef: string | null;
+  }>) => Promise<void>,
+): typeof handler;

package/src/server/triggers/index.js

@@ -0,0 +1,27 @@
+const TRIGGER_MARKER = Symbol.for("zhike.workflow-trigger.v1");
+
+export function defineWorkflowTrigger(definition) {
+  if (!definition || typeof definition !== "object" || Array.isArray(definition)) {
+    throw new TypeError("workflow_trigger_definition_invalid");
+  }
+  return Object.freeze({ ...definition, [TRIGGER_MARKER]: true });
+}
+
+function bindTriggerHandler(trigger, handler, kind) {
+  if (!trigger?.[TRIGGER_MARKER] || typeof handler !== "function") {
+    throw new TypeError(`workflow_trigger_${kind}_invalid`);
+  }
+  return handler;
+}
+
+export function defineWorkflowTriggerActivate(trigger, handler) {
+  return bindTriggerHandler(trigger, handler, "activate");
+}
+
+export function defineWorkflowTriggerOnEvent(trigger, handler) {
+  return bindTriggerHandler(trigger, handler, "on_event");
+}
+
+export function defineWorkflowTriggerDeactivate(trigger, handler) {
+  return bindTriggerHandler(trigger, handler, "deactivate");
+}

package/src/server/workflow-blocks/index.d.ts

@@ -0,0 +1,72 @@
+import type {
+  WorkflowObjectSchema,
+  WorkflowSchemaValue,
+  WorkflowStepDefinition,
+  WorkflowStepOutcome,
+  WorkflowStepResult,
+} from "../steps/index.js";
+import type {
+  WorkflowTriggerDefinition,
+  WorkflowTriggerEventResult,
+  WorkflowTriggerOutcome,
+} from "../triggers/index.js";
+
+export type WorkflowStepBlockDefinition<
+  Config extends WorkflowObjectSchema = WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowStepOutcome[] = readonly WorkflowStepOutcome[],
+> = WorkflowStepDefinition<Config, Outcomes> & { readonly type: "step" };
+
+export type WorkflowTriggerBlockDefinition<
+  Config extends WorkflowObjectSchema = WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowTriggerOutcome[] = readonly WorkflowTriggerOutcome[],
+> = WorkflowTriggerDefinition<Config, Outcomes> & { readonly type: "trigger" };
+
+export type WorkflowBlockDefinition = WorkflowStepBlockDefinition | WorkflowTriggerBlockDefinition;
+
+export function defineWorkflowBlock<
+  const Config extends WorkflowObjectSchema,
+  const Outcomes extends readonly [WorkflowStepOutcome, ...WorkflowStepOutcome[]],
+>(definition: WorkflowStepBlockDefinition<Config, Outcomes>): WorkflowStepBlockDefinition<Config, Outcomes>;
+
+export function defineWorkflowBlock<
+  const Config extends WorkflowObjectSchema,
+  const Outcomes extends readonly [WorkflowTriggerOutcome, ...WorkflowTriggerOutcome[]],
+>(definition: WorkflowTriggerBlockDefinition<Config, Outcomes>): WorkflowTriggerBlockDefinition<Config, Outcomes>;
+
+export function defineWorkflowBlockExecute<
+  Config extends WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowStepOutcome[],
+>(
+  block: WorkflowStepBlockDefinition<Config, Outcomes>,
+  execute: (params: Readonly<{ config: WorkflowSchemaValue<Config> }>) =>
+    WorkflowStepResult<Outcomes> | Promise<WorkflowStepResult<Outcomes>>,
+): typeof execute;
+
+export function defineWorkflowBlockActivate<Config extends WorkflowObjectSchema>(
+  block: WorkflowTriggerBlockDefinition<Config>,
+  handler: (params: Readonly<{
+    config: WorkflowSchemaValue<Config>;
+    activationId: string;
+    triggerCallbackUrl: string;
+  }>) => Promise<Readonly<{ subscriptionRef: string | null }>>,
+): typeof handler;
+
+export function defineWorkflowBlockTrigger<
+  Config extends WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowTriggerOutcome[],
+>(
+  block: WorkflowTriggerBlockDefinition<Config, Outcomes>,
+  handler: (params: Readonly<{
+    config: WorkflowSchemaValue<Config>;
+    body: string;
+    headers: Readonly<Record<string, string>>;
+  }>) => Promise<WorkflowTriggerEventResult<Outcomes>>,
+): typeof handler;
+
+export function defineWorkflowBlockDeactivate(
+  block: WorkflowTriggerBlockDefinition,
+  handler: (params: Readonly<{
+    activationId: string;
+    subscriptionRef: string | null;
+  }>) => Promise<void>,
+): typeof handler;

package/src/server/workflow-blocks/index.js

@@ -0,0 +1,32 @@
+const WORKFLOW_BLOCK_MARKER = Symbol.for("zhike.workflow-block.v1");
+
+export function defineWorkflowBlock(definition) {
+  if (!definition || typeof definition !== "object" || Array.isArray(definition) ||
+    !["step", "trigger"].includes(definition.type)) {
+    throw new TypeError("workflow_block_definition_invalid");
+  }
+  return Object.freeze({ ...definition, [WORKFLOW_BLOCK_MARKER]: true });
+}
+
+function bindWorkflowBlockHandler(block, handler, type, kind) {
+  if (!block?.[WORKFLOW_BLOCK_MARKER] || block.type !== type || typeof handler !== "function") {
+    throw new TypeError(`workflow_block_${kind}_invalid`);
+  }
+  return handler;
+}
+
+export function defineWorkflowBlockExecute(block, handler) {
+  return bindWorkflowBlockHandler(block, handler, "step", "execute");
+}
+
+export function defineWorkflowBlockActivate(block, handler) {
+  return bindWorkflowBlockHandler(block, handler, "trigger", "activate");
+}
+
+export function defineWorkflowBlockTrigger(block, handler) {
+  return bindWorkflowBlockHandler(block, handler, "trigger", "trigger");
+}
+
+export function defineWorkflowBlockDeactivate(block, handler) {
+  return bindWorkflowBlockHandler(block, handler, "trigger", "deactivate");
+}

package/src/toolchain/agents/discovery.js

@@ -0,0 +1,126 @@
+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) {
+  if (depth > 24) invalid(path, '静态声明嵌套过深');
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+  if (ts.isNumericLiteral(node)) return Number(node.text);
+  if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(node.operand)) return -Number(node.operand.text);
+  if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
+  if (node.kind === ts.SyntaxKind.NullKeyword) return null;
+  if (ts.isArrayLiteralExpression(node)) return node.elements.map(item => literal(item, path, depth + 1));
+  if (ts.isObjectLiteralExpression(node)) {
+    const result = Object.create(null);
+    for (const property of node.properties) {
+      if (!ts.isPropertyAssignment(property) || !(ts.isIdentifier(property.name) || ts.isStringLiteral(property.name))) invalid(path, '元数据必须为静态 JSON 字面量');
+      const key = property.name.text;
+      if (Object.hasOwn(result, key) || ['__proto__', 'prototype', 'constructor'].includes(key)) invalid(path, '重复或保留字段');
+      result[key] = literal(property.initializer, path, depth + 1);
+    }
+    return result;
+  }
+  invalid(path, '元数据不能读取变量、函数或运行时代码');
+}
+
+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' &&
+    statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings) &&
+    statement.importClause.namedBindings.elements.some(item => !item.propertyName && item.name.text === api));
+  const exports = sourceFile.statements.filter(statement => ts.isExportAssignment(statement) && !statement.isExportEquals);
+  const call = exports[0]?.expression;
+  if (!imported || exports.length !== 1 || !call || !ts.isCallExpression(call) ||
+      !ts.isIdentifier(call.expression) || call.expression.text !== api || call.arguments.length !== 1 ||
+      !ts.isObjectLiteralExpression(call.arguments[0])) invalid(relativePath, `必须直接默认导出 ${api}({...})`);
+  const value = Object.create(null);
+  for (const property of call.arguments[0].properties) {
+    if (!property.name || !(ts.isIdentifier(property.name) || ts.isStringLiteral(property.name))) invalid(relativePath, '声明禁止 spread 或动态属性');
+    const key = property.name.text;
+    if (Object.hasOwn(value, key)) invalid(relativePath, '重复声明字段');
+    if (api === 'defineTool' && key === 'execute') {
+      const handler = ts.isMethodDeclaration(property) ? property : ts.isPropertyAssignment(property) ? property.initializer : null;
+      if (!handler || !(ts.isMethodDeclaration(handler) || ts.isArrowFunction(handler) || ts.isFunctionExpression(handler)) || handler.parameters.length > 1) invalid(relativePath, 'execute 必须是仅接收业务 input 的函数');
+      value[key] = true;
+    } else {
+      if (!ts.isPropertyAssignment(property)) invalid(relativePath, '元数据必须为静态字段');
+      value[key] = literal(property.initializer, relativePath);
+    }
+  }
+  return value;
+}
+
+export function discoverAgents(files) {
+  const agents = new Map();
+  for (const file of 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', '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 && !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');
+    }
+    if (!match) continue;
+    const owner = agents.get(match[1]);
+    if (!owner) invalid(file.relativePath, '工具缺少所属 agent.ts');
+    const value = definition(file, 'defineTool');
+    if (value.key !== match[2] || value.execute !== true) invalid(file.relativePath, 'Tool key 必须等于文件前缀且提供 execute');
+    delete value.execute;
+    owner.tools.push({ ...value, clientResult: value.clientResult ?? 'none', artifact: 'server',
+      entry: `agent-tool/${match[1]}/${match[2]}`, relativePath: file.relativePath });
+  }
+  return [...agents.values()].sort((a, b) => a.key.localeCompare(b.key)).map(agent => {
+    agent.tools.sort((a, b) => a.key.localeCompare(b.key));
+    try { assertAgentManifest(agentManifest(agent)); } catch { invalid(agent.relativePath, 'Agent/Tool 元数据、Schema 或归属无效'); }
+    return Object.freeze(agent);
+  });
+}
+
+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

@@ -0,0 +1,84 @@
+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',
+  'app_id', 'appId', 'version_id', 'versionId', 'run_id', 'executionId', 'tool_call_id', 'constructor', 'prototype']);
+const SCHEMA_KEYS = ['type', 'properties', 'required', 'additionalProperties', 'items', 'enum', 'const',
+  'minLength', 'maxLength', 'pattern', 'minimum', 'maximum', 'minItems', 'maxItems', 'title', 'description'];
+function invalid() { throw new TypeError('app_manifest_agent_invalid'); }
+function record(value) { if (!value || typeof value !== 'object' || Array.isArray(value)) invalid(); }
+function keys(value, allowed) { if (Object.keys(value).some(key => !allowed.includes(key))) invalid(); }
+function text(value, max) { if (typeof value !== 'string' || !value.trim() || value.length > max) invalid(); }
+
+export function assertAgentSchema(value) {
+  function visit(schema, depth = 0) {
+    record(schema); keys(schema, SCHEMA_KEYS);
+    if (depth > 6 || !['object', 'array', 'string', 'integer', 'number', 'boolean', 'null'].includes(schema.type)) invalid();
+    if (schema.type === 'object') {
+      record(schema.properties);
+      if (schema.additionalProperties !== false || Object.keys(schema.properties).length > 32) invalid();
+      const required = schema.required ?? [];
+      if (!Array.isArray(required) || new Set(required).size !== required.length ||
+          required.some(key => typeof key !== 'string' || !Object.hasOwn(schema.properties, key))) invalid();
+      for (const [key, child] of Object.entries(schema.properties)) {
+        if (key.trim() !== key || !FIELD.test(key) || RESERVED.has(key)) invalid();
+        visit(child, depth + 1);
+      }
+    } else if (schema.type === 'array') visit(schema.items, depth + 1);
+    else if (schema.properties !== undefined || schema.items !== undefined || schema.required !== undefined ||
+      schema.additionalProperties !== undefined) invalid();
+    for (const key of ['minLength', 'maxLength', 'minItems', 'maxItems']) {
+      if (schema[key] !== undefined && (!Number.isSafeInteger(schema[key]) || schema[key] < 0 || schema[key] > 8192)) invalid();
+    }
+    for (const [min, max] of [['minLength', 'maxLength'], ['minItems', 'maxItems'], ['minimum', 'maximum']]) {
+      if (schema[min] !== undefined && schema[max] !== undefined && schema[min] > schema[max]) invalid();
+    }
+    for (const key of ['minimum', 'maximum']) if (schema[key] !== undefined &&
+      (typeof schema[key] !== 'number' || !Number.isFinite(schema[key]))) invalid();
+    if (schema.enum !== undefined && (!Array.isArray(schema.enum) || !schema.enum.length || schema.enum.length > 64 ||
+      schema.enum.some(item => item !== null && (!['string', 'boolean', 'number'].includes(typeof item) || typeof item === 'number' && !Number.isFinite(item))))) invalid();
+    if (schema.const !== undefined && schema.const !== null && (!['string', 'boolean', 'number'].includes(typeof schema.const) || typeof schema.const === 'number' && !Number.isFinite(schema.const))) invalid();
+    for (const key of ['title', 'description']) if (schema[key] !== undefined) text(schema[key], 1200);
+    if (schema.pattern !== undefined) { text(schema.pattern, 256); try { new RegExp(schema.pattern); } catch { invalid(); } }
+  }
+  visit(value);
+  if (value.type !== 'object' || new TextEncoder().encode(JSON.stringify(value)).length > 16384) invalid();
+  return value;
+}
+
+export function assertAgentManifest(value) {
+  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) {
+    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', 'dedupeBy']);
+  if (typeof value.key !== 'string' || !KEY.test(value.key) || typeof value.showByDefault !== 'boolean') invalid();
+  if (value.dedupeBy !== undefined && (typeof value.dedupeBy !== 'string' || value.dedupeBy.length > 100
+    || !/^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*){0,3}$/.test(value.dedupeBy)
+    || value.dedupeBy.split('.').some(key => ['__proto__', 'prototype', 'constructor'].includes(key)))) invalid();
+  return value;
+}