✨ feat(schedule): 实现MCP 工具定义编排以及日程模块的接口定义与实现

README.md

@@ -98,7 +98,7 @@ VoiceLife 使用 ESP-IDF 组件化模块单体。核心代码使用 C++，外部
 | `voicelife_linx_esp` | ESP32-S3 WSS/TLS Transport 和分片重组 | contracts、linx |
 | `voicelife_audio_esp` | ESP32-S3 音频 Profile、探针和设备端 Port | contracts、voice |
 | `voicelife_board_esp` | ESP-SparkBot 板级 Profile、能力矩阵、共享电源仲裁和身份探针 | contracts |
-| `voicelife_mcp` | 工具 Schema、注册中心和调用路由 | contracts |
+| `voicelife_mcp` | 工具 Schema、注册中心、调用路由和测试工具适配 | contracts、schedule |
 | `voicelife_runtime` | 唯一组装入口，按生命周期启动和回滚基础设施 | contracts、mcp、voice、linx、storage adapters |
 
 依赖方向只有一条：适配器依赖用例，用例依赖领域，领域不认识 ESP-IDF、HTTP 或平台 SDK。CI 会运行 `scripts/check_architecture.sh` 检查组件清单、命名空间和依赖图。

codecov.yml

@@ -42,3 +42,7 @@ ignore:
   - "components/voicelife_linx_esp/**"
   - "components/voicelife_audio_esp/**"
   - "components/voicelife_runtime/**"
+  # 日程模块
+  - "components/voicelife_schedule/**"
+  # MCP模块
+  - "components/voicelife_mcp/**"

components/voicelife_contracts/include/voicelife/contracts/status.h

@@ -58,6 +58,30 @@ struct Result {
     }
 };
 
+/** @brief 命令/用例返回结果，统一承载状态、业务值和错误说明。 */
+template <typename T>
+struct CommandResult {
+    Status status;
+    T value;
+    std::string error;
+
+    /** @brief 判断命令是否成功。 @return status 为成功时返回 true。 */
+    [[nodiscard]] bool ok() const { return status.ok(); }
+
+    /** @brief 创建成功结果。 @param value 命令返回的业务值。 @return 携带业务值的成功结果。 */
+    static CommandResult Success(T value) { return {Status::Ok(), std::move(value), {}}; }
+
+    /**
+     * @brief 创建失败结果。
+     * @param status 失败状态。
+     * @return 不携带业务值且保留错误说明的失败结果。
+     */
+    static CommandResult Failure(Status status) {
+        const std::string error = status.message;
+        return {std::move(status), {}, error};
+    }
+};
+
 /** @brief 返回稳定的错误码名称。 @param code 要描述的错误码。 @return 静态字符串形式的名称。 */
 const char* ErrorCodeName(ErrorCode code);
 

components/voicelife_contracts/include/voicelife/contracts/tool.h

@@ -1,15 +1,21 @@
 #pragma once
 
+#include <cstdint>
+#include <memory>
+#include <optional>
 #include <string>
 #include <unordered_map>
+#include <utility>
 #include <variant>
+#include <vector>
 
+#include "voicelife/contracts/json.h"
 #include "voicelife/contracts/status.h"
 
 namespace voicelife {
 
 /// 工具调用参数当前支持的运行时值类型。
-using ToolValue = std::variant<bool, int64_t, std::string>;
+using ToolValue = std::variant<bool, int64_t, std::string, JsonValue>;
 using ToolArguments = std::unordered_map<std::string, ToolValue>;
 
 /// 描述一次进入设备侧的工具调用。
@@ -19,10 +25,94 @@ struct ToolCall {
     ToolArguments arguments;
 };
 
-/// 保存工具调用的状态和具名输出值。
+/// 工具返回的结构化 JSON 值。
+struct ToolOutputValue;
+
+/// 工具返回的数组元素集合。
+using ToolOutputArray = std::vector<std::shared_ptr<ToolOutputValue>>;
+
+/// 工具返回的对象成员集合；使用 vector 保持业务声明顺序。
+using ToolOutputObject = std::vector<std::pair<std::string, std::shared_ptr<ToolOutputValue>>>;
+
+/// 工具返回的结构化 JSON 值。
+struct ToolOutputValue {
+    /** @brief 工具输出节点支持的运行时类型。 */
+    enum class Kind { kNull, kBoolean, kInteger, kString, kArray, kObject };
+
+    Kind kind = Kind::kNull;
+    bool boolean = false;
+    std::int64_t integer = 0;
+    std::string string;
+    std::shared_ptr<ToolOutputArray> array;
+    std::shared_ptr<ToolOutputObject> object;
+
+    /** @brief 构造空值。 @return 空值节点。 */
+    static ToolOutputValue Null() { return {}; }
+    /** @brief 构造布尔值节点。 @param value 布尔值。 @return 布尔节点。 */
+    static ToolOutputValue Boolean(bool value) {
+        ToolOutputValue output;
+        output.kind = Kind::kBoolean;
+        output.boolean = value;
+        return output;
+    }
+    /** @brief 构造整数节点。 @param value 整数值。 @return 整数节点。 */
+    static ToolOutputValue Integer(std::int64_t value) {
+        ToolOutputValue output;
+        output.kind = Kind::kInteger;
+        output.integer = value;
+        return output;
+    }
+    /** @brief 构造字符串节点。 @param value 字符串。 @return 字符串节点。 */
+    static ToolOutputValue String(std::string value) {
+        ToolOutputValue output;
+        output.kind = Kind::kString;
+        output.string = std::move(value);
+        return output;
+    }
+    /** @brief 构造数组节点。 @param value 数组元素。 @return 数组节点。 */
+    static ToolOutputValue Array(ToolOutputArray value) {
+        ToolOutputValue output;
+        output.kind = Kind::kArray;
+        output.array = std::make_shared<ToolOutputArray>(std::move(value));
+        return output;
+    }
+    /** @brief 构造对象节点。 @param value 有序成员。 @return 对象节点。 */
+    static ToolOutputValue Object(ToolOutputObject value) {
+        ToolOutputValue output;
+        output.kind = Kind::kObject;
+        output.object = std::make_shared<ToolOutputObject>(std::move(value));
+        return output;
+    }
+
+    /** @brief 判断当前值是否为对象。 @return 是对象时返回 true。 */
+    [[nodiscard]] bool IsObject() const { return kind == Kind::kObject; }
+    /** @brief 判断当前值是否为数组。 @return 是数组时返回 true。 */
+    [[nodiscard]] bool IsArray() const { return kind == Kind::kArray; }
+    /** @brief 判断当前值是否为字符串。 @return 是字符串时返回 true。 */
+    [[nodiscard]] bool IsString() const { return kind == Kind::kString; }
+};
+
+/** @brief 创建工具输出数组中的一个元素。 @param value 节点。 @return 节点共享指针。 */
+inline std::shared_ptr<ToolOutputValue> MakeToolOutput(ToolOutputValue value) {
+    return std::make_shared<ToolOutputValue>(std::move(value));
+}
+
+/** @brief 创建工具输出对象成员。 @param key 成员名。 @param value 节点。 @return 有序成员。 */
+inline std::pair<std::string, std::shared_ptr<ToolOutputValue>> MakeToolOutput(std::string key, ToolOutputValue value) {
+    return {std::move(key), MakeToolOutput(std::move(value))};
+}
+
+/// 保存工具调用的状态和结构化输出值。
 struct ToolResult {
     Status status;
-    std::unordered_map<std::string, std::string> output;
+    ToolOutputValue output = ToolOutputValue::Null();
+    /// 面向用户的精确文本；未设置时由边界适配器序列化结构化输出生成文本。
+    std::optional<std::string> text_output = std::nullopt;
+
+    /** @brief 创建成功结果。 @param output 结构化输出。 @return 成功结果。 */
+    static ToolResult Success(ToolOutputValue output) { return {Status::Ok(), std::move(output), std::nullopt}; }
+    /** @brief 创建失败结果。 @param status 失败状态。 @return 无输出的失败结果。 */
+    static ToolResult Failure(Status status) { return {std::move(status), ToolOutputValue::Null(), std::nullopt}; }
 };
 
 }  // namespace voicelife

components/voicelife_linx_esp/include/voicelife/linx_esp/esp_websocket_transport.h

@@ -43,7 +43,9 @@ struct EspWebSocketTransportOptions {
     uint32_t network_timeout_ms = 10000;
     uint32_t reconnect_timeout_ms = 1000;
     uint32_t websocket_task_stack_size = 12288;
-    uint32_t worker_task_stack_size = 12288;
+    // MCP 日程工具（schedule.create/query）在此 worker 任务上执行 SQLite/FATFS 操作，
+    // SQLite 的 sqlite3_step 需要较大栈，12KB 会导致栈溢出崩溃。
+    uint32_t worker_task_stack_size = 32768;
     bool enable_close_reconnect = true;
     bool allow_insecure_ws = false;
 };

components/voicelife_mcp/CMakeLists.txt

@@ -1,6 +1,7 @@
 idf_component_register(
-    SRCS "src/mcp_server.cc" "src/mcp_json_writer.cc"
+    SRCS "src/mcp_server.cc" "src/mcp_json_writer.cc" "src/tools/schedule_mcp_tools.cc"
+         "src/tools/schedule_mcp_tools_input.cc"
     INCLUDE_DIRS "include"
     REQUIRES voicelife_contracts
-    PRIV_REQUIRES yyjson
+    PRIV_REQUIRES voicelife_schedule yyjson
 )

components/voicelife_mcp/include/voicelife/mcp/mcp_server.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <functional>
+#include <memory>
 #include <optional>
 #include <string>
 #include <unordered_map>
@@ -11,13 +12,17 @@
 namespace voicelife::mcp {
 
 /// MCP 工具参数支持的数据类型。
-enum class ToolInputType { kString, kInteger, kBoolean };
+enum class ToolInputType { kString, kInteger, kBoolean, kObject };
+
+/// MCP 工具输入参数的 JSON Schema 前向声明。
+struct ToolInputSchema;
 
 /// MCP 工具的单个输入字段定义。
 struct ToolInputField {
     ToolInputType type = ToolInputType::kString;
     std::optional<ToolValue> default_value;
     std::string description;
+    std::shared_ptr<ToolInputSchema> object_schema;
     std::optional<int64_t> minimum;
     std::optional<int64_t> maximum;
     std::optional<std::size_t> min_length;
@@ -48,7 +53,10 @@ struct ListToolsResult {
 };
 
 /// 工具参数支持的类型。
-enum class PropertyType { kBoolean, kInteger, kString };
+enum class PropertyType { kBoolean, kInteger, kString, kObject };
+
+/// 面向业务代码的 MCP 参数集合前向声明。
+class PropertyList;
 
 /// 面向业务代码的单个工具参数声明。
 class Property {
@@ -69,25 +77,39 @@ class Property {
      */
     Property(std::string name, PropertyType type, ToolValue default_value);
     /**
-     * @brief 创建带整数范围约束的参数声明。
+     * @brief 创建带内部字段定义的对象参数声明。
      * @param name 参数名称。
-     * @param type 参数类型，必须为整数。
-     * @param minimum 最小值。
-     * @param maximum 最大值。
+     * @param object_properties 对象内部字段定义。
      * @return 无。
      */
-    Property(std::string name, PropertyType type, int64_t minimum, int64_t maximum);
-
+    Property(std::string name, PropertyList object_properties);
     /**
-     * @brief 创建带字符串长度约束的参数声明。
+     * @brief 创建带数值或字符串长度约束的参数声明。
      * @param name 参数名称。
-     * @param minimum 最小字符数。
-     * @param maximum 最大字符数。
+     * @param type 参数类型；整数类型使用数值范围，字符串类型使用字符长度。
+     * @param minimum 最小值或最小字符数。
+     * @param maximum 最大值或最大字符数。
      * @param default_value 默认值；未设置时该参数为必填。
-     * @return 参数声明。
+     * @return 无。
      */
-    static Property WithStringLength(std::string name, std::size_t minimum, std::size_t maximum,
-                                     std::optional<ToolValue> default_value = std::nullopt);
+    Property(std::string name, PropertyType type, int64_t minimum, int64_t maximum,
+             std::optional<ToolValue> default_value = std::nullopt);
+
+    /**
+     * @brief 设置参数字段描述。
+     * @param description 输出到 JSON Schema 字段上的描述。
+     * @return 当前参数声明，便于链式构造。
+     */
+    Property& with_description(std::string description);
+    /**
+     * @brief 设置对象参数内部字段定义。
+     * @param object_properties 对象内部字段定义。
+     * @return 当前参数声明，便于链式构造。
+     */
+    Property& with_object_properties(PropertyList object_properties);
+
+    /** @brief 释放参数声明占用的资源。 */
+    ~Property();
 
     /**
      * @brief 创建带整数范围约束的参数声明。
@@ -107,6 +129,13 @@ class Property {
      * @return 可选参数声明。
      */
     static Property Optional(std::string name, PropertyType type);
+    /**
+     * @brief 创建可省略的对象参数声明并设置内部字段定义。
+     * @param name 参数名称。
+     * @param object_properties 对象内部字段定义。
+     * @return 可选对象参数声明。
+     */
+    static Property OptionalObject(std::string name, PropertyList object_properties);
 
     /**
      * @brief 获取参数名称。
@@ -118,6 +147,16 @@ class Property {
      * @return 参数类型。
      */
     [[nodiscard]] PropertyType type() const { return type_; }
+    /**
+     * @brief 获取参数字段描述。
+     * @return 字段描述；未设置时为空字符串。
+     */
+    [[nodiscard]] const std::string& description() const { return description_; }
+    /**
+     * @brief 获取对象参数内部字段定义。
+     * @return 内部字段定义；未设置时为空。
+     */
+    [[nodiscard]] const std::shared_ptr<PropertyList>& object_properties() const { return object_properties_; }
     /**
      * @brief 获取参数默认值。
      * @return 默认值；未设置时为空。
@@ -137,6 +176,11 @@ class Property {
     [[nodiscard]] std::optional<std::size_t> min_length() const { return min_length_; }
     /** @brief 获取字符串最大长度。 @return 最大长度；未设置时为空。 */
     [[nodiscard]] std::optional<std::size_t> max_length() const { return max_length_; }
+    /**
+     * @brief 判断约束参数是否能按声明类型解释。
+     * @return 约束有效时返回 true。
+     */
+    [[nodiscard]] bool constraint_valid() const { return constraint_valid_; }
     /**
      * @brief 判断参数缺失时是否应拒绝调用。
      * @return 参数必填时返回 true。
@@ -146,11 +190,14 @@ class Property {
    private:
     std::string name_;
     PropertyType type_;
+    std::string description_;
+    std::shared_ptr<PropertyList> object_properties_;
     std::optional<ToolValue> default_value_;
     std::optional<int64_t> minimum_;
     std::optional<int64_t> maximum_;
     std::optional<std::size_t> min_length_;
     std::optional<std::size_t> max_length_;
+    bool constraint_valid_ = true;
     bool required_ = true;
 };
 
@@ -272,4 +319,11 @@ class McpServer {
     std::vector<std::string> registration_order_;
 };
 
+/**
+ * @brief 将结构化工具输出序列化为紧凑 JSON 文本。
+ * @param output 待序列化的工具输出。
+ * @return 序列化成功时返回 JSON 文本，失败时返回空对象。
+ */
+std::string SerializeToolOutputValue(const ToolOutputValue& output);
+
 }  // namespace voicelife::mcp

components/voicelife_mcp/include/voicelife/mcp/schedule_mcp_tools.h

@@ -0,0 +1,35 @@
+#pragma once
+
+#include "voicelife/contracts/status.h"
+
+namespace voicelife::schedule {
+/// 提供一次性日程服务能力。
+class ScheduleService;
+/// 提供周期日程规则服务能力。
+class ScheduleRuleService;
+}  // namespace voicelife::schedule
+
+namespace voicelife::mcp {
+
+/// 用于注册日程 MCP 工具的 MCP Server 前向声明。
+class McpServer;
+
+/**
+ * @brief 向 MCP Server 注册当前日程工具。
+ * @param server 要注册工具的 MCP Server。
+ * @param service 一次性日程服务。
+ * @return 注册结果。
+ */
+Status RegisterScheduleMcpTools(McpServer& server, schedule::ScheduleService& service);
+
+/**
+ * @brief 向 MCP Server 注册包含周期日程能力的日程工具。
+ * @param server 要注册工具的 MCP Server。
+ * @param service 一次性日程服务。
+ * @param rule_service 周期日程规则服务。
+ * @return 注册结果。
+ */
+Status RegisterScheduleMcpTools(McpServer& server, schedule::ScheduleService& service,
+                                schedule::ScheduleRuleService& rule_service);
+
+}  // namespace voicelife::mcp