阶段4-tool契约: register支持CapabilityMeta(决策8 meta可选+新能力强制), 新增registerAll显式注册入口双入口过渡(决策9), RUNTIME_ERROR_CODES错误码固化+audit校验, 规范v1同步收紧

packages/rpa-core/src/engine/registry.ts

@@ -1,16 +1,54 @@
 import type { CapabilityHandler } from "./types";
 
-const handlers = new Map<string, CapabilityHandler>();
+/**
+ * 能力结构化元数据（任务 4.1，决策点 8：meta 可选 + 新能力强制）。
+ * 老能力逐步补齐；规范 v1 验收 checklist 对新能力要求必填。
+ */
+export interface CapabilityParamMeta {
+  key: string;
+  label?: string;
+  type: "string" | "number" | "boolean" | "object" | "array";
+  required?: boolean;
+  defaultValue?: string | number | boolean | null;
+  description?: string;
+}
 
-export function register(ids: string | string[], handler: CapabilityHandler): void {
+export interface CapabilityMeta {
+  /** 一句话能力摘要（中文） */
+  summary?: string;
+  /** 参数 schema（按字段名列出） */
+  params?: CapabilityParamMeta[];
+  /** 返回值说明 */
+  returns?: string;
+  /** 默认超时毫秒（无外部交互语义的能力省略） */
+  timeoutMs?: number;
+  /** 可能抛出的稳定错误码（见 engine/error-codes.ts） */
+  errorCodes?: string[];
+  /** 执行中是否需要回传截图（Agent 侧视觉判断用） */
+  needsScreenshot?: boolean;
+  /** 平台限制；省略表示跨平台 */
+  platforms?: Array<"win32">;
+}
+
+const handlers = new Map<string, CapabilityHandler>();
+const metas = new Map<string, CapabilityMeta>();
+
+export function register(ids: string | string[], handler: CapabilityHandler, meta?: CapabilityMeta): void {
   const list = Array.isArray(ids) ? ids : [ids];
-  for (const id of list) handlers.set(id, handler);
+  for (const id of list) {
+    handlers.set(id, handler);
+    if (meta) metas.set(id, meta);
+  }
 }
 
 export function getHandler(id: string): CapabilityHandler | undefined {
   return handlers.get(id);
 }
 
+export function getCapabilityMeta(id: string): CapabilityMeta | undefined {
+  return metas.get(id);
+}
+
 export function hasCapability(id: string): boolean {
   return handlers.has(id);
 }