Agent Core
头文件：claw_core.h
claw_core 实现设备侧的 Agent 核心：收到包含「用户说了什么、来自哪个会话与通道」的消息后，在独立任务里完成上下文拼装、调用大语言模型、解析 Tool Call、再通过统一入口执行能力，并按配置迭代多轮，直到模型给出最终文本或出错。
claw_core_request_t 包含单次交互所需的全部元数据，例如：
session_id：会话标识（Console 里session命令会切换当前会话；IM 路由也会按策略生成会话 id）。user_text：用户输入正文。source_*/target_*：来源通道、聊天 id、消息 id、来源 cap 等。这些字段会原样传入claw_cap_call_from_core，以便在 Capability 层定向回复或关联上下文。
应用通过 claw_core_submit 投递请求，用 claw_core_receive / claw_core_receive_for 取回 claw_core_response_t。
claw_core_response_t 包含助手回复正文（text 字段）与错误信息（error_message）。
claw_core_request_t.flags 支持以下标志位的组合：
| 标志 | 说明 |
|---|---|
CLAW_CORE_REQUEST_FLAG_PUBLISH_OUT_MESSAGE | Agent 完成推理后，将响应以 out_message 事件发布到 Event Router |
CLAW_CORE_REQUEST_FLAG_SKIP_RESPONSE_QUEUE | 跳过响应队列，不通过 claw_core_receive 返回结果 |
Event Router 的 run_agent 动作会同时设置这两个标志，实现异步提交 + 事件发布的响应路径。
在拼装发往大语言模型的当前轮用户提示时，claw_core 会附带一段 Behavior Notes，说明最终助手结果通常会由框架自动投递给用户，因此一般不必再主动调用各 IM 的 cap_im_* 发送接口返回正文（减少重复回复）。
claw_core 支持挂接多个 context provider（claw_core_context_provider_t）。每个 provider 在收集阶段往 claw_core_context_t 里填一块内容，类型由 claw_core_context_kind_t 区分，包括：
CLAW_CORE_CONTEXT_KIND_SYSTEM_PROMPTCLAW_CORE_CONTEXT_KIND_MESSAGESCLAW_CORE_CONTEXT_KIND_TOOLS
basic_demo 在 app_claw_start 里按固定顺序挂了多个 provider：
- 可编辑人设与画像：
claw_memory_profile_provider - 长期记忆：
claw_memory_long_term_provider（完整模式）或claw_memory_long_term_lightweight_provider（轻量模式） - 会话历史：
claw_memory_session_history_provider - Skills 目录：
claw_skill_skills_list_provider - 已激活 Skill 文档：
claw_skill_active_skill_docs_provider - 当前可见工具列表：
claw_cap_tools_provider - Lua 异步任务状态：
cap_lua_async_jobs_provider
因此：大语言模型最终接收的工具列表，不仅取决于注册了哪些 Capability，还取决于 claw_cap_set_llm_visible_groups。
claw_core 通过回调处理大语言模型发出的工具调用请求。
basic_demo 的 call_cap 回调指向 claw_cap_call_from_core，该函数由 claw_cap 提供。
claw_core 只基于「能力名 + JSON 参数 + 当前请求上下文」接受调用工具的指令，但不负责查找对应的 Capability 实现与执行。
Capability 的解析与执行工作由 claw_cap 负责。
一轮里允许的工具轮数由 max_tool_iterations 限制。
会话历史写入
Section titled “会话历史写入”claw_core 通过回调机制支持多种会话历史写入方式。
basic_demo 中，append_session_turn 设为 claw_memory_append_session_turn_callback，该函数由 claw_memory 提供。
claw_core 会在合适时机触发回调函数，将会话历史交由 claw_memory 处理。
claw_core_cancel_request(request_id) 用于取消当前正在执行的请求：
request_id == 0：取消任意当前 in-flight 请求。request_id != 0：仅当当前 in-flight 请求 ID 匹配时才生效。- 若没有可取消的请求，返回
ESP_ERR_NOT_FOUND。
该取消是协作式中断，主要用于中止进行中的 LLM HTTP 请求；请求结束后，错误信息会被统一标记为 request cancelled，便于上层识别。
claw_core_add_completion_observer 允许注册完成观察器，在每次请求结束后接收 claw_core_completion_summary_t：
request_id/session_id：请求与会话标识。final_text：本轮最终回复文本（可能为空）。context_providers_csv：本轮注入了非空上下文的 provider 列表（CSV）。tool_calls_csv：本轮触发过的工具调用列表（CSV）。
该机制适合做审计、统计或“结果一致性”检查（例如检测某些声明是否伴随了对应工具调用）。
basic_demo 注册了 cap_lua_honesty_observe_completion 作为 completion observer，用于检测模型回复中声称执行了 Lua 操作但实际未产生工具调用的情况，并在发现不一致时记录日志。
初始化错误处理
Section titled “初始化错误处理”app_claw_start 会在 API Key、profile、model 不全时跳过 claw_core_init / claw_core_start，并打印日志。
此时依赖大语言模型的 ask、Event Router 发往 Agent 的路由（含 fallback 路由）、图片 inspect 等能力不可用。
但 Event Router、自动化、本地 Capability、Console REPL 仍可工作。
claw_core_config_t 中常见字段含义：
profile/provider/backend_type/model/base_url/auth_type/timeout_ms：对接不同大语言模型供应商时的路由与鉴权（具体支持的后端在claw_core_llm与llm/backends下实现）。profile与provider二选一即可。system_prompt：系统提示词，必填（claw_core_init会校验此字段非空）。image_max_bytes：传入 LLM 层的图像/媒体大小上限。task_stack_size、task_priority、task_core：后台 Agent 任务在 FreeRTOS 上的资源。request_queue_len、response_queue_len：请求/响应队列深度。max_context_providers：最多可注册的 provider 数量。