CMDCSkillEngine.Analyzer.LLM (cmdc_skill_engine v0.3.0)

Copy Markdown View Source

LLM 驱动的执行分析器 —— v0.2 新增。

v0.1 的 CMDCSkillEngine.Analyzer 使用基于规则的启发式(统计工具调用成败) 判定任务是否完成。v0.2 引入本模块,用 ReqLLM.generate_object/4 在会话结束 时让指定模型做结构化 JSON 输出,产生更准确的判断与进化建议。

调用方式

{:ok, analysis} =
  CMDCSkillEngine.Analyzer.LLM.analyze(
    %{
      session_id: "sess-1",
      skills: [%CMDC.Skill{skill_id: "sk_a", name: "a", description: "..."}],
      tool_results: [%{tool: :read_file, success: true}],
      messages: [%{role: :user, content: "summarize foo.md"}]
    },
    model: "openai:gpt-4o-mini",
    analysis_timeout: 15_000
  )

返回 {:ok, %ExecutionAnalysis{}}{:error, reason}。任何失败都应被调用方 捕获并降级到规则 Analyzer,不要向用户报错。

设计约束

  • 纯函数入口:不依赖 Plugin state;便于测试、离线回放、手动触发。
  • 超时控制:Task.await/2 + analysis_timeout(默认 10s)。
  • 幂等:多次调 analyze/2 返回语义相同的 ExecutionAnalysis
  • 失败降级:捕获 exit/throw/error/rescue 返回 {:error, reason}

Schema(强制)

  • task_completed :: boolean()
  • execution_note :: String.t()
  • tool_issues :: [String.t()]
  • skill_judgments :: [%{skill_id, skill_applied, note}]
  • evolution_suggestions :: [%{evolution_type, target_skill_ids, category, direction}]

测试注入

  • :generate_fnfn model, messages, schema, opts -> ... end。 返回值可以是 {:ok, %ReqLLM.Response{}}{:ok, map()}{:error, reason}。 未提供时默认调 ReqLLM.generate_object/4

Summary

Functions

手动触发一次 LLM 分析。

返回强制的 LLM 输出 schema。供调用方调试/审计使用。

Functions

analyze(context, opts)

@spec analyze(
  map(),
  keyword()
) :: {:ok, CMDCSkillEngine.Types.ExecutionAnalysis.t()} | {:error, term()}

手动触发一次 LLM 分析。

必传 :model;可选 :analysis_timeout:req_llm_opts:system_prompt:generate_fn。详见模块 moduledoc。

object_schema()

@spec object_schema() :: keyword()

返回强制的 LLM 输出 schema。供调用方调试/审计使用。