lc_tools/

datetime.rs

// lc-tools/src/datetime.rs
//! Date and time tool for agents.
//!
//! Provides date/time query and calculation functionality.

use async_trait::async_trait;
use chrono::{DateTime, Datelike, Duration, Local, NaiveDate, NaiveDateTime, TimeZone, Weekday};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use lc_core::tools::{BaseTool, Tool, ToolError};

/// DateTime tool input parameters.
#[derive(Debug, Deserialize, JsonSchema)]
pub struct DateTimeInput {
    /// Operation type: "now", "format", "add", "subtract", "weekday", "diff".
    pub operation: String,

    /// Date/time string (optional, format: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS).
    pub datetime: Option<String>,

    /// Time unit: "days", "hours", "minutes", "weeks", "months", "years".
    pub unit: Option<String>,

    /// Value for add/subtract operations.
    pub value: Option<i64>,

    /// Target date/time for diff operation.
    pub target: Option<String>,
}

/// DateTime tool output result.
#[derive(Debug, Serialize)]
pub struct DateTimeOutput {
    /// Operation result.
    pub result: String,

    /// Operation type.
    pub operation: String,

    /// Additional details.
    pub details: Option<String>,
}

/// DateTime tool for querying and manipulating dates and times.
pub struct DateTimeTool;

impl DateTimeTool {
    /// Creates a new DateTimeTool instance.
    pub fn new() -> Self {
        Self
    }

    fn parse_datetime(&self, dt_str: &str) -> Result<DateTime<Local>, ToolError> {
        if let Ok(dt) = NaiveDateTime::parse_from_str(dt_str, "%Y-%m-%d %H:%M:%S") {
            return Local
                .from_local_datetime(&dt)
                .single()
                .ok_or_else(|| ToolError::ExecutionFailed("invalid datetime".to_string()));
        }

        if let Ok(date) = NaiveDate::parse_from_str(dt_str, "%Y-%m-%d") {
            let dt = date
                .and_hms_opt(0, 0, 0)
                .ok_or_else(|| ToolError::ExecutionFailed("invalid date".to_string()))?;
            return Local
                .from_local_datetime(&dt)
                .single()
                .ok_or_else(|| ToolError::ExecutionFailed("invalid datetime".to_string()));
        }

        Err(ToolError::ExecutionFailed(format!(
            "failed to parse datetime: {}, use format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS",
            dt_str
        )))
    }

    fn get_now(&self) -> DateTimeOutput {
        let now = Local::now();
        DateTimeOutput {
            result: now.format("%Y-%m-%d %H:%M:%S").to_string(),
            operation: "now".to_string(),
            details: Some(format!(
                "星期{}，第{}周",
                match now.weekday() {
                    Weekday::Mon => "一",
                    Weekday::Tue => "二",
                    Weekday::Wed => "三",
                    Weekday::Thu => "四",
                    Weekday::Fri => "五",
                    Weekday::Sat => "六",
                    Weekday::Sun => "日",
                },
                now.iso_week().week()
            )),
        }
    }

    fn format_datetime(&self, dt_str: &str) -> Result<DateTimeOutput, ToolError> {
        let dt = self.parse_datetime(dt_str)?;

        Ok(DateTimeOutput {
            result: dt.format("%Y年%m月%d日 %H时%M分%S秒").to_string(),
            operation: "format".to_string(),
            details: Some(format!(
                "星期{}，{}年{}周",
                match dt.weekday() {
                    Weekday::Mon => "一",
                    Weekday::Tue => "二",
                    Weekday::Wed => "三",
                    Weekday::Thu => "四",
                    Weekday::Fri => "五",
                    Weekday::Sat => "六",
                    Weekday::Sun => "日",
                },
                dt.year(),
                dt.iso_week().week()
            )),
        })
    }

    fn add_time(&self, dt_str: &str, value: i64, unit: &str) -> Result<DateTimeOutput, ToolError> {
        let dt = self.parse_datetime(dt_str)?;

        let new_dt = match unit {
            "seconds" => dt + Duration::seconds(value),
            "minutes" => dt + Duration::minutes(value),
            "hours" => dt + Duration::hours(value),
            "days" => dt + Duration::days(value),
            "weeks" => dt + Duration::weeks(value),
            "months" => {
                let months = value as i32;
                // M-27: `value` may be negative (subtract). Rust `/` and `%` truncate toward
                // zero, so `(new_month - 1) / 12` and `% 12` produced a wrong year offset and a
                // negative month that wrapped on `as u32` → "month calculation failed" whenever
                // the delta crossed a year boundary backwards (e.g. 2024-03-15 minus 13 months).
                // `div_euclid`/`rem_euclid` floor to the mathematical quotient, correct for both
                // positive and negative deltas while leaving positive behavior unchanged.
                let total_zero_based = dt.month() as i32 - 1 + months;
                let year = dt.year() + total_zero_based.div_euclid(12);
                let month = (total_zero_based.rem_euclid(12) + 1) as u32;

                dt.with_year(year)
                    .and_then(|d| d.with_month(month))
                    .ok_or_else(|| ToolError::ExecutionFailed("month calculation failed".to_string()))?
            }
            "years" => dt
                .with_year(dt.year() + value as i32)
                .ok_or_else(|| ToolError::ExecutionFailed("year calculation failed".to_string()))?,
            _ => {
                return Err(ToolError::ExecutionFailed(format!(
                "unsupported time unit: {}, use: seconds, minutes, hours, days, weeks, months, years",
                unit
            )))
            }
        };

        Ok(DateTimeOutput {
            result: new_dt.format("%Y-%m-%d %H:%M:%S").to_string(),
            operation: "add".to_string(),
            details: Some(format!("{} {} 后", value, self.unit_to_chinese(unit))),
        })
    }

    fn subtract_time(
        &self,
        dt_str: &str,
        value: i64,
        unit: &str,
    ) -> Result<DateTimeOutput, ToolError> {
        self.add_time(dt_str, -value, unit)
    }

    fn get_weekday(&self, dt_str: &str) -> Result<DateTimeOutput, ToolError> {
        let dt = self.parse_datetime(dt_str)?;

        let weekday = match dt.weekday() {
            Weekday::Mon => "星期一",
            Weekday::Tue => "星期二",
            Weekday::Wed => "星期三",
            Weekday::Thu => "星期四",
            Weekday::Fri => "星期五",
            Weekday::Sat => "星期六",
            Weekday::Sun => "星期日",
        };

        Ok(DateTimeOutput {
            result: weekday.to_string(),
            operation: "weekday".to_string(),
            details: Some(format!("{} 是 {}", dt.format("%Y-%m-%d"), weekday)),
        })
    }

    fn diff_time(&self, dt1_str: &str, dt2_str: &str) -> Result<DateTimeOutput, ToolError> {
        let dt1 = self.parse_datetime(dt1_str)?;
        let dt2 = self.parse_datetime(dt2_str)?;

        let diff = dt2.signed_duration_since(dt1);

        // M-27: decompose the total duration once over its absolute seconds instead of mixing
        // `num_days()` (floored whole days) with `num_hours() % 24` / `num_minutes() % 60`
        // (truncation toward zero). For a negative diff the floored days already consumed the
        // remainder the mod parts tried to contribute, double-counting hours/minutes. Working on
        // `abs_seconds` keeps one authoritative, sign-correct decomposition for every magnitude.
        let total_seconds = diff.num_seconds();
        let direction = total_seconds.signum();
        let abs_seconds = total_seconds.unsigned_abs();
        let days = abs_seconds / 86_400;
        let hours = (abs_seconds % 86_400) / 3_600;
        let minutes = (abs_seconds % 3_600) / 60;

        Ok(DateTimeOutput {
            result: format!("{}天 {}小时 {}分钟", days, hours, minutes),
            operation: "diff".to_string(),
            details: Some(if direction >= 0 {
                format!(
                    "从 {} 到 {} 相隔 {}天 {}小时 {}分钟",
                    dt1.format("%Y-%m-%d"),
                    dt2.format("%Y-%m-%d"),
                    days,
                    hours,
                    minutes
                )
            } else {
                format!(
                    "从 {} 到 {} 相隔 {}天 {}小时 {}分钟",
                    dt2.format("%Y-%m-%d"),
                    dt1.format("%Y-%m-%d"),
                    days,
                    hours,
                    minutes
                )
            }),
        })
    }

    fn unit_to_chinese(&self, unit: &str) -> String {
        match unit {
            "seconds" => "秒",
            "minutes" => "分钟",
            "hours" => "小时",
            "days" => "天",
            "weeks" => "周",
            "months" => "月",
            "years" => "年",
            _ => unit,
        }
        .to_string()
    }
}

impl Default for DateTimeTool {
    fn default() -> Self {
        Self::new()
    }
}

#[async_trait]
impl Tool for DateTimeTool {
    type Input = DateTimeInput;
    type Output = DateTimeOutput;

    async fn invoke(&self, input: Self::Input) -> Result<Self::Output, ToolError> {
        match input.operation.as_str() {
            "now" => Ok(self.get_now()),
            "format" => {
                let dt = input.datetime.ok_or_else(|| {
                    ToolError::InvalidInput(
                        "format operation requires a datetime parameter".to_string(),
                    )
                })?;
                self.format_datetime(&dt)
            }
            "add" => {
                let dt = input.datetime.ok_or_else(|| {
                    ToolError::InvalidInput(
                        "add operation requires a datetime parameter".to_string(),
                    )
                })?;
                let value = input.value.ok_or_else(|| {
                    ToolError::InvalidInput("add operation requires a value parameter".to_string())
                })?;
                let unit = input.unit.ok_or_else(|| {
                    ToolError::InvalidInput("add operation requires a unit parameter".to_string())
                })?;
                self.add_time(&dt, value, &unit)
            }
            "subtract" => {
                let dt = input.datetime.ok_or_else(|| {
                    ToolError::InvalidInput(
                        "subtract operation requires a datetime parameter".to_string(),
                    )
                })?;
                let value = input.value.ok_or_else(|| {
                    ToolError::InvalidInput(
                        "subtract operation requires a value parameter".to_string(),
                    )
                })?;
                let unit = input.unit.ok_or_else(|| {
                    ToolError::InvalidInput(
                        "subtract operation requires a unit parameter".to_string(),
                    )
                })?;
                self.subtract_time(&dt, value, &unit)
            }
            "weekday" => {
                let dt = input.datetime.ok_or_else(|| {
                    ToolError::InvalidInput(
                        "weekday operation requires a datetime parameter".to_string(),
                    )
                })?;
                self.get_weekday(&dt)
            }
            "diff" => {
                let dt1 = input.datetime.ok_or_else(|| {
                    ToolError::InvalidInput(
                        "diff operation requires a datetime parameter".to_string(),
                    )
                })?;
                let dt2 = input.target.ok_or_else(|| {
                    ToolError::InvalidInput(
                        "diff operation requires a target parameter".to_string(),
                    )
                })?;
                self.diff_time(&dt1, &dt2)
            }
            _ => Err(ToolError::InvalidInput(format!(
                "unsupported operation: {}, use: now, format, add, subtract, weekday, diff",
                input.operation
            ))),
        }
    }
}

#[async_trait]
impl BaseTool for DateTimeTool {
    fn name(&self) -> &str {
        "datetime"
    }

    fn description(&self) -> &str {
        "日期时间工具。支持多种操作：

操作类型:
- now: 获取当前时间
- format: 格式化日期时间
- add: 添加时间
- subtract: 减去时间
- weekday: 获取星期几
- diff: 计算时间差

示例:
- 获取当前时间: {\"operation\": \"now\"}
- 格式化日期: {\"operation\": \"format\", \"datetime\": \"2024-01-15\"}
- 添加3天: {\"operation\": \"add\", \"datetime\": \"2024-01-15\", \"value\": 3, \"unit\": \"days\"}
- 计算差值: {\"operation\": \"diff\", \"datetime\": \"2024-01-01\", \"target\": \"2024-01-15\"}"
    }

    async fn run(&self, input: String) -> Result<String, ToolError> {
        let parsed: DateTimeInput = serde_json::from_str(&input)
            .map_err(|e| ToolError::InvalidInput(format!("JSON parse failed: {}", e)))?;

        let output = self.invoke(parsed).await?;

        Ok(format!(
            "{}\n详细信息: {}",
            output.result,
            output.details.unwrap_or_default()
        ))
    }

    fn args_schema(&self) -> Option<serde_json::Value> {
        use schemars::schema_for;
        serde_json::to_value(schema_for!(DateTimeInput)).ok()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn test_datetime_now() {
        let tool = DateTimeTool::new();

        let input = DateTimeInput {
            operation: "now".to_string(),
            datetime: None,
            unit: None,
            value: None,
            target: None,
        };

        let result = tool.invoke(input).await.unwrap();
        assert!(!result.result.is_empty());
        assert!(result.details.is_some());
    }

    #[tokio::test]
    async fn test_datetime_format() {
        let tool = DateTimeTool::new();

        let input = DateTimeInput {
            operation: "format".to_string(),
            datetime: Some("2024-01-15".to_string()),
            unit: None,
            value: None,
            target: None,
        };

        let result = tool.invoke(input).await.unwrap();
        assert!(result.result.contains("2024年"));
        assert!(result.result.contains("01月"));
        assert!(result.result.contains("15日"));
    }

    #[tokio::test]
    async fn test_datetime_add_days() {
        let tool = DateTimeTool::new();

        let input = DateTimeInput {
            operation: "add".to_string(),
            datetime: Some("2024-01-15".to_string()),
            unit: Some("days".to_string()),
            value: Some(3),
            target: None,
        };

        let result = tool.invoke(input).await.unwrap();
        assert!(result.result.contains("2024-01-18"));
    }

    #[tokio::test]
    async fn test_datetime_weekday() {
        let tool = DateTimeTool::new();

        // 2024-01-15 is a Monday
        let input = DateTimeInput {
            operation: "weekday".to_string(),
            datetime: Some("2024-01-15".to_string()),
            unit: None,
            value: None,
            target: None,
        };

        let result = tool.invoke(input).await.unwrap();
        assert_eq!(result.result, "星期一");
    }

    #[tokio::test]
    async fn test_datetime_diff() {
        let tool = DateTimeTool::new();

        let input = DateTimeInput {
            operation: "diff".to_string(),
            datetime: Some("2024-01-01".to_string()),
            unit: None,
            value: None,
            target: Some("2024-01-15".to_string()),
        };

        let result = tool.invoke(input).await.unwrap();
        assert!(result.result.contains("14天"));
    }

    #[tokio::test]
    async fn test_datetime_subtract_months_cross_year() {
        let tool = DateTimeTool::new();
        // M-27: subtracting 13 months from 2024-03-15 crosses a year backward.
        // The old `/` `%` (truncate toward zero) arithmetic failed here with "month calculation failed".
        let input = DateTimeInput {
            operation: "subtract".to_string(),
            datetime: Some("2024-03-15".to_string()),
            unit: Some("months".to_string()),
            value: Some(13),
            target: None,
        };
        let result = tool.invoke(input).await.unwrap();
        assert!(
            result.result.contains("2023-02-15"),
            "expected 2023-02-15, got: {}",
            result.result
        );
    }

    #[tokio::test]
    async fn test_datetime_diff_negative_decomposition() {
        let tool = DateTimeTool::new();
        // M-27: -25h ≡ 1 day 1 hour ago. Mixing `num_days()` (floored) with `num_hours() % 24`
        // (truncated) double-counted negative diffs; absolute-seconds decomposition must not.
        let input = DateTimeInput {
            operation: "diff".to_string(),
            datetime: Some("2024-01-02 01:00:00".to_string()),
            unit: None,
            value: None,
            target: Some("2024-01-01 00:00:00".to_string()),
        };
        let result = tool.invoke(input).await.unwrap();
        assert!(
            result.result.contains("1天 1小时 0分钟"),
            "expected 1天 1小时 0分钟, got: {}",
            result.result
        );
    }
}