@spzhongwin/skill-logger-plugin 1.0.11 → 1.0.13

package/src/types.ts

@@ -1,198 +1,198 @@
-/**
- * 全插件共享的数据类型。
- *
- * 设计要点：
- * - `MatchRule` 是「判别联合」(discriminated union)：用 `type` 字段区分四种匹配策略，
- *   TypeScript 能据此收窄到具体形状，matcher 里按 `rule.type` 分派。
- * - 这些类型同时是「标准配置」的契约：用户平台返回的 JSON 必须符合 `SkillStandardConfig`。
- */
-
-/** 脚本参数规则：用于在同一脚本下按参数细分功能点，如 `--mode current`。 */
-export type ArgRule = {
-  /** 参数名，含前缀，如 `--mode`。 */
-  flag: string;
-  /** 期望值；省略表示「只要出现该 flag 即命中」。 */
-  value?: string;
-};
-
-/**
- * 脚本调用：模型通过 `exec` 跑某个 skill 自带脚本（.py/.sh/.js 等）。
- * 识别时忽略解释器前缀（python/node/bash/uv run/./），用脚本路径后缀匹配。
- */
-export type ScriptMatchRule = {
-  type: "script";
-  /** 相对 skill 根目录的脚本路径，如 `scripts/model_usage.py`。 */
-  script: string;
-  /** 可选：按参数细分功能点；全部命中才算命中。 */
-  argRules?: ArgRule[];
-};
-
-/**
- * CLI 包装调用：模型通过 `exec` 调一个包装 CLI，如 `mcporter call linear.list_issues`。
- * `command` 是命令头，`targetPattern` 是其后用于定位功能点的子串。
- */
-export type CommandMatchRule = {
-  type: "command";
-  /** 命令名，如 `mcporter`。 */
-  command: string;
-  /** 命令后用于识别功能点的子串，如 `call linear.list_issues`。 */
-  targetPattern: string;
-};
-
-/** 参数谓词：判断某个工具参数是否等于期望值（支持点路径取嵌套字段）。 */
-export type WherePredicate = {
-  /** 参数键，支持 `a.b.c` 点路径。 */
-  param: string;
-  /** 期望值（严格相等比较，做 String 归一）。 */
-  equals: string;
-};
-
-/**
- * 工具直调：模型直接调用一个「非 exec」工具（典型为注册进 openclaw 的 MCP/SSE 工具）。
- * 按 `toolName` 匹配（精确 / 前缀 / 正则三选一），可加参数谓词进一步限定。
- */
-export type ToolMatchRule = {
-  type: "tool";
-  /** 精确工具名。 */
-  toolName?: string;
-  /** 工具名前缀（如某 MCP server 的统一前缀）。 */
-  toolNamePrefix?: string;
-  /** 工具名正则（字符串形式，matcher 内编译）。 */
-  toolNameRegex?: string;
-  /** 可选参数谓词，全部满足才命中。 */
-  where?: WherePredicate[];
-};
-
-/**
- * HTTP/SSE 端点调用：模型 `exec` 里 curl 某端点，或 fetch 类工具带 url 参数。
- */
-export type HttpMatchRule = {
-  type: "http";
-  /** URL 子串匹配，如 `/v1/audio/transcriptions`。 */
-  urlContains?: string;
-  /** host 子串匹配，如 `api.openai.com`。 */
-  hostContains?: string;
-};
-
-export type MatchRule =
-  | ScriptMatchRule
-  | CommandMatchRule
-  | ToolMatchRule
-  | HttpMatchRule;
-
-/** 一个 skill 内的功能点定义。 */
-export type SkillFunction = {
-  /** 功能点唯一标识（skill 内唯一）。 */
-  id: string;
-  /** 人类可读名称。 */
-  name: string;
-  /** 功能点说明（可选）。 */
-  description?: string;
-  /** 匹配规则。 */
-  match: MatchRule;
-};
-
-/** skill 的标准配置：由用户平台定义、插件拉取并缓存。 */
-export type SkillStandardConfig = {
-  skillName: string;
-  /** 本次返回的配置对应的版本（按请求里的本地版本精确匹配）。 */
-  version: string;
-  /** 平台上该 skill 的最新版本（服务端附加，用于过期检测）；缺省时回退用 version。 */
-  latestVersion?: string;
-  description?: string;
-  functions: SkillFunction[];
-};
-
-/** matcher 命中后返回的结构。 */
-export type MatchResult = {
-  skillName: string;
-  skillVersion: string;
-  functionId: string;
-  functionName: string;
-  matchType: MatchRule["type"];
-  /** 从调用里解析出的参数（脚本 flag / mcporter k=v / http query 等）。 */
-  args: Record<string, unknown>;
-};
-
-/** 观测到的一次工具调用的最小描述（matcher 输入）。 */
-export type ToolCall = {
-  toolName: string;
-  params: Record<string, unknown>;
-};
-
-/** 上报身份；做成独立类型，便于将来替换来源（user_id 等）。 */
-export type Identity = {
-  user_id: string;
-  git_name: string;
-  git_email: string;
-  machine_id: string;
-};
-
-export type UserInfoSnapshot = {
-  user_id?: string;
-  user_name?: string;
-  emp_id?: string;
-  person_id?: string;
-  corp_id?: string;
-  avatar?: string;
-  deptList?: unknown[];
-  title?: string;
-  error_message?: string;
-};
-
-/** 落盘 / 上报的事件。两类：skill 触发、功能点调用。 */
-export type SkillEvent = {
-  event_id: string;
-  event_type: "skill_trigger" | "function_call";
-  skill_name: string;
-  skill_version?: string;
-  function_id?: string;
-  function_name?: string;
-  /** 命中的匹配策略类型（function_call 时有）。 */
-  match_type?: MatchRule["type"];
-  /** 触发方式：skill_trigger 为 inline/tool；function_call 为观测到的工具名（exec/mcp 工具…）。 */
-  invoke_mode?: string;
-  /** 观测到的工具名。 */
-  invoke_tool?: string;
-  /** exec 时的原始命令行。 */
-  command?: string;
-  args?: Record<string, unknown>;
-  /** success/error 来自 after_tool_call；unknown 表示 after 未到达（被中断/阻断）而由兜底补记。 */
-  status?: "success" | "error" | "unknown";
-  error_message?: string;
-  duration_ms?: number;
-  app_key?: string;
-  user_info?: UserInfoSnapshot;
-  session_id?: string;
-  agent_id?: string;
-  run_id?: string;
-  plugin_id?: string;
-  plugin_name?: string;
-  plugin_version?: string;
-  /** ISO 8601。 */
-  called_at: string;
-};
-
-/** 插件运行期配置（来自 manifest configSchema / pluginConfig）。 */
-export type PluginConfig = {
-  /** 插件唯一ID，用于区分不同网关或业务线的插件实例。 */
-  pluginId?: string;
-  /** 插件中文描述名称。 */
-  pluginName?: string;
-  /** 插件版本号（从 package.json 中读取）。 */
-  pluginVersion?: string;
-  /** 拉取标准配置的服务地址。缺失则用本地静态桩。 */
-  platformBaseUrl?: string;
-  /** 网关长连接中心服务地址（如 wss://api.aishuo.co/gateway/ws）。若缺失，尝试从 platformBaseUrl 推导。 */
-  wsServerUrl?: string;
-  /** 批量上报的服务地址。缺失则只落本地、不上报。 */
-  reportBaseUrl?: string;
-  /** 上报鉴权头的值（如 Bearer xxx）。 */
-  authToken?: string;
-  /** 是否记录「无法自信归属到功能点」的调用（默认 true）。 */
-  recordUnattributed?: boolean;
-  /** 是否开启插件内部的调试日志输出（默认 true，方便实战联调观察过程）。 */
-  debugLogging?: boolean;
-  /** 是否开启插件专属文件日志（落盘为 skill-logger.err），用于排查 WS 连接和指令运行情况 */
-  enableFileLog?: boolean;
-};
+/**
+ * 全插件共享的数据类型。
+ *
+ * 设计要点：
+ * - `MatchRule` 是「判别联合」(discriminated union)：用 `type` 字段区分四种匹配策略，
+ *   TypeScript 能据此收窄到具体形状，matcher 里按 `rule.type` 分派。
+ * - 这些类型同时是「标准配置」的契约：用户平台返回的 JSON 必须符合 `SkillStandardConfig`。
+ */
+
+/** 脚本参数规则：用于在同一脚本下按参数细分功能点，如 `--mode current`。 */
+export type ArgRule = {
+  /** 参数名，含前缀，如 `--mode`。 */
+  flag: string;
+  /** 期望值；省略表示「只要出现该 flag 即命中」。 */
+  value?: string;
+};
+
+/**
+ * 脚本调用：模型通过 `exec` 跑某个 skill 自带脚本（.py/.sh/.js 等）。
+ * 识别时忽略解释器前缀（python/node/bash/uv run/./），用脚本路径后缀匹配。
+ */
+export type ScriptMatchRule = {
+  type: "script";
+  /** 相对 skill 根目录的脚本路径，如 `scripts/model_usage.py`。 */
+  script: string;
+  /** 可选：按参数细分功能点；全部命中才算命中。 */
+  argRules?: ArgRule[];
+};
+
+/**
+ * CLI 包装调用：模型通过 `exec` 调一个包装 CLI，如 `mcporter call linear.list_issues`。
+ * `command` 是命令头，`targetPattern` 是其后用于定位功能点的子串。
+ */
+export type CommandMatchRule = {
+  type: "command";
+  /** 命令名，如 `mcporter`。 */
+  command: string;
+  /** 命令后用于识别功能点的子串，如 `call linear.list_issues`。 */
+  targetPattern: string;
+};
+
+/** 参数谓词：判断某个工具参数是否等于期望值（支持点路径取嵌套字段）。 */
+export type WherePredicate = {
+  /** 参数键，支持 `a.b.c` 点路径。 */
+  param: string;
+  /** 期望值（严格相等比较，做 String 归一）。 */
+  equals: string;
+};
+
+/**
+ * 工具直调：模型直接调用一个「非 exec」工具（典型为注册进 openclaw 的 MCP/SSE 工具）。
+ * 按 `toolName` 匹配（精确 / 前缀 / 正则三选一），可加参数谓词进一步限定。
+ */
+export type ToolMatchRule = {
+  type: "tool";
+  /** 精确工具名。 */
+  toolName?: string;
+  /** 工具名前缀（如某 MCP server 的统一前缀）。 */
+  toolNamePrefix?: string;
+  /** 工具名正则（字符串形式，matcher 内编译）。 */
+  toolNameRegex?: string;
+  /** 可选参数谓词，全部满足才命中。 */
+  where?: WherePredicate[];
+};
+
+/**
+ * HTTP/SSE 端点调用：模型 `exec` 里 curl 某端点，或 fetch 类工具带 url 参数。
+ */
+export type HttpMatchRule = {
+  type: "http";
+  /** URL 子串匹配，如 `/v1/audio/transcriptions`。 */
+  urlContains?: string;
+  /** host 子串匹配，如 `api.openai.com`。 */
+  hostContains?: string;
+};
+
+export type MatchRule =
+  | ScriptMatchRule
+  | CommandMatchRule
+  | ToolMatchRule
+  | HttpMatchRule;
+
+/** 一个 skill 内的功能点定义。 */
+export type SkillFunction = {
+  /** 功能点唯一标识（skill 内唯一）。 */
+  id: string;
+  /** 人类可读名称。 */
+  name: string;
+  /** 功能点说明（可选）。 */
+  description?: string;
+  /** 匹配规则。 */
+  match: MatchRule;
+};
+
+/** skill 的标准配置：由用户平台定义、插件拉取并缓存。 */
+export type SkillStandardConfig = {
+  skillName: string;
+  /** 本次返回的配置对应的版本（按请求里的本地版本精确匹配）。 */
+  version: string;
+  /** 平台上该 skill 的最新版本（服务端附加，用于过期检测）；缺省时回退用 version。 */
+  latestVersion?: string;
+  description?: string;
+  functions: SkillFunction[];
+};
+
+/** matcher 命中后返回的结构。 */
+export type MatchResult = {
+  skillName: string;
+  skillVersion: string;
+  functionId: string;
+  functionName: string;
+  matchType: MatchRule["type"];
+  /** 从调用里解析出的参数（脚本 flag / mcporter k=v / http query 等）。 */
+  args: Record<string, unknown>;
+};
+
+/** 观测到的一次工具调用的最小描述（matcher 输入）。 */
+export type ToolCall = {
+  toolName: string;
+  params: Record<string, unknown>;
+};
+
+/** 上报身份；做成独立类型，便于将来替换来源（user_id 等）。 */
+export type Identity = {
+  user_id: string;
+  git_name: string;
+  git_email: string;
+  machine_id: string;
+};
+
+export type UserInfoSnapshot = {
+  user_id?: string;
+  user_name?: string;
+  emp_id?: string;
+  person_id?: string;
+  corp_id?: string;
+  avatar?: string;
+  deptList?: unknown[];
+  title?: string;
+  error_message?: string;
+};
+
+/** 落盘 / 上报的事件。两类：skill 触发、功能点调用。 */
+export type SkillEvent = {
+  event_id: string;
+  event_type: "skill_trigger" | "function_call";
+  skill_name: string;
+  skill_version?: string;
+  function_id?: string;
+  function_name?: string;
+  /** 命中的匹配策略类型（function_call 时有）。 */
+  match_type?: MatchRule["type"];
+  /** 触发方式：skill_trigger 为 inline/tool；function_call 为观测到的工具名（exec/mcp 工具…）。 */
+  invoke_mode?: string;
+  /** 观测到的工具名。 */
+  invoke_tool?: string;
+  /** exec 时的原始命令行。 */
+  command?: string;
+  args?: Record<string, unknown>;
+  /** success/error 来自 after_tool_call；unknown 表示 after 未到达（被中断/阻断）而由兜底补记。 */
+  status?: "success" | "error" | "unknown";
+  error_message?: string;
+  duration_ms?: number;
+  app_key?: string;
+  user_info?: UserInfoSnapshot;
+  session_id?: string;
+  agent_id?: string;
+  run_id?: string;
+  plugin_id?: string;
+  plugin_name?: string;
+  plugin_version?: string;
+  /** ISO 8601。 */
+  called_at: string;
+};
+
+/** 插件运行期配置（来自 manifest configSchema / pluginConfig）。 */
+export type PluginConfig = {
+  /** 插件唯一ID，用于区分不同网关或业务线的插件实例。 */
+  pluginId?: string;
+  /** 插件中文描述名称。 */
+  pluginName?: string;
+  /** 插件版本号（从 package.json 中读取）。 */
+  pluginVersion?: string;
+  /** 拉取标准配置的服务地址。缺失则用本地静态桩。 */
+  platformBaseUrl?: string;
+  /** 网关长连接中心服务地址（如 wss://api.aishuo.co/gateway/ws）。若缺失，尝试从 platformBaseUrl 推导。 */
+  wsServerUrl?: string;
+  /** 批量上报的服务地址。缺失则只落本地、不上报。 */
+  reportBaseUrl?: string;
+  /** 上报鉴权头的值（如 Bearer xxx）。 */
+  authToken?: string;
+  /** 是否记录「无法自信归属到功能点」的调用（默认 true）。 */
+  recordUnattributed?: boolean;
+  /** 是否开启插件内部的调试日志输出（默认 true，方便实战联调观察过程）。 */
+  debugLogging?: boolean;
+  /** 是否开启插件专属文件日志（落盘为 skill-logger.err），用于排查 WS 连接和指令运行情况 */
+  enableFileLog?: boolean;
+};