Rust Things

🦀 生锈的东西

一个高性能的Rust库和CLI for Things 3集成，为AI/LLM环境提供集成的MCP（模型上下文协议）服务器支持。

📦 版本1.0.0-生产就绪！

     ](RELEASE_NOTES.md)

✨ 特性

• 🚀 高性能：采用Rust构建，实现最高速度和可靠性
• 🔧 CLI工具：用于管理Things 3数据的命令行界面
• 🤖 MCP集成：用于AI/LLM集成的集成MCP服务器
• 📊 安全集成：通过异步SQLx读取，通过AppleScript进行突变（按 CulturedCode指南)
• 🏗️ 月球工作区：使用Moon构建系统组织monorepo
• 🧪 测试良好：全面的测试套件和基准测试
• 📈 性能监控：内置指标和系统监控
• 💾 缓存层：使用Moka进行高性能缓存
• 🔄 备份与恢复：具有元数据的完整备份系统
• 📤 数据导出：多种格式（JSON、CSV、OPML、Markdown）
• 🔧 高级MCP工具：17个用于AI/LLM集成的工具
• ⚡ 异步数据库：SQLx支持异步数据库操作，具有线程安全性
• 🌐 Web服务器：健康检查和监控仪表板服务器

🚀 安装

自制（macOS）

# Add the tap (when available)
brew tap GarthDB/rust-things3

# Install
brew install things3-cli

货物（生锈）

# Install from crates.io (when published)
cargo install things3-cli --features mcp-server

# Or install from source
cargo install --path apps/things3-cli --features mcp-server

升级后： cargo install 替换磁盘上的二进制文件，但任何 运行MCP服务器进程仍然使用旧的内存二进制文件。重新启动 升级后的进程（或您的编辑器/代理主机），因此新版本 加载。您可以通过以下方式验证运行版本 things3 --version.

源自

git clone https://github.com/GarthDB/rust-things3
cd rust-things3
cargo build --release

# Add to PATH
export PATH="$PWD/target/release:$PATH"

利用月球（开发）

# Install Moon if you haven't already
curl -fsSL https://moonrepo.dev/install | bash

# Clone and setup
git clone https://github.com/GarthDB/rust-things3
cd rust-things3
moon run :dev-pipeline

⚙️ 功能标志

1.0.0中的新功能：带功能标志的模块化编译！只选择你需要的东西。

图书馆(things3-core)

[dependencies]
# Minimal (core functionality only - 24% smaller binary)
things3-core = { version = "1.0", default-features = false }

# With specific features
things3-core = { version = "1.0", features = ["export-csv", "observability"] }

# Full features (recommended for most users)
things3-core = { version = "1.0", features = ["full"] }

可用功能：

• export-csv：CSV导出支持
• export-opml：OPML导出支持
• observability：指标、跟踪和健康检查
• full：启用所有功能
• test-utils：测试实用程序（仅限开发）

CLI(things3-cli)

[dependencies]
# CLI with all features
things3-cli = { version = "1.0", features = ["full"] }

# CLI with specific features
things3-cli = { version = "1.0", features = ["mcp-server", "export-csv"] }

其他CLI功能：

• mcp-server：MCP服务器功能（需要导出功能）

📚 看 功能.md 查看详细的功能文档和兼容性矩阵。

📖 快速开始

在5分钟内开始！看 快速入门指南 详细说明。

基本库使用

use things3_core::{ThingsDatabase, ThingsError};

#[tokio::main]
async fn main() -> Result {
    // Connect to database
    let db_path = things3_core::get_default_database_path();
    let db = ThingsDatabase::new(&db_path).await?;
    
    // Get inbox tasks
    let tasks = db.get_inbox(Some(10)).await?;
    for task in tasks {
        println!("- {}", task.title);
    }
    
    // Search for tasks
    let results = db.search_tasks("meeting").await?;
    println!("Found {} matching tasks", results.len());
    
    Ok(())
}

CLI命令

# Show help
things3 --help

# Health check
things3 health

# Show inbox tasks
things3 inbox
things3 inbox --limit 5

# Show today's tasks
things3 today
things3 today --limit 3

# Show all projects
things3 projects
things3 projects --area 

# Show all areas
things3 areas

# Search for tasks
things3 search "meeting"
things3 search "report" --limit 10

# Start MCP server (for AI/LLM integration)
things3 mcp

# Start health check server
things3 health-server --port 8080

# Start monitoring dashboard
things3 dashboard --port 8081

环境变量

# Set custom database path
export THINGS_DB_PATH="/path/to/things.db"

# Enable fallback to default path
export THINGS_FALLBACK_TO_DEFAULT=true

# Enable verbose logging
export RUST_LOG=debug

🌐 Web服务器

CLI包括用于监视和健康检查的内置web服务器：

健康检查服务器

# Start health check server
things3 health-server --port 8080

# Test health endpoint
curl http://localhost:8080/health
curl http://localhost:8080/ping

监控仪表板

# Start monitoring dashboard
things3 dashboard --port 8081

# Access dashboard
open http://localhost:8081

仪表板提供：

• 实时指标和统计
• 数据库健康监控
• 性能指标
• 系统资源使用情况
• 任务和项目分析

🤖 MCP集成

MCP（模型上下文协议）服务器为AI/LLM集成提供了46个工具。常用工具：

可用的MCP工具

看 skills/things3/references/TOOLS.md 查看完整的46种工具目录。

配置

光标

// .cursor/mcp.json
{
  "mcpServers": {
    "things3": {
      "command": "things3",
      "args": ["mcp"],
      "env": {
        "THINGS_DB_PATH": "/path/to/things.db"
      }
    }
  }
}

VS Code

// .vscode/mcp.json
{
  "servers": {
    "things3": {
      "type": "stdio",
      "command": "things3",
      "args": ["mcp"],
      "cwd": "${workspaceFolder}",
      "env": {
        "THINGS_DB_PATH": "/path/to/things.db"
      }
    }
  }
}

泽德

// .zed/settings.json
{
  "mcp": {
    "things3": {
      "command": "things3",
      "args": ["mcp"],
      "env": {
        "THINGS_DB_PATH": "/path/to/things.db"
      }
    }
  }
}

与Claude Code/您的AI代理一起使用

rust-things3附带了代理技能，可以让你直接从Claude Code、Claude Desktop、Cursor、Zed和其他任何地方驱动Things 3 agentskills.io 网站-兼容主机。

看 技能/README.md 有关安装说明和完整目录。

文档

入门指南

• 快速入门指南 -在5分钟内开始
• 用户指南 -全面使用指南
• 错误处理指南 -错误处理模式和恢复策略

发布文档（1.0.0）

• 发布说明 -1.0.0的新增功能
• 迁移指南 -从0.x升级到1.0.0
• 功能标志指南 -带有功能标志的模块化编译
• 安全审计 -安全审计结果
• 1.0后路线图 -未来发展规划
• 更新日志 -完整的版本历史记录

核心文件

• 建筑 -系统设计和组件概述
• MCP集成 -完整的MCP服务器指南
• 可靠性指南 -连接池、错误恢复和弹性模式
• 性能指南 -基准和优化策略
• 数据库模式 -Things 3数据库结构
• 开发指南 -设置和开发工作流程
• 覆盖率分析 -测试覆盖率报告

示例

基本示例

看 libs/things3-core/examples/ 实用示例目录：

• basic_usage.rs -基本数据库操作（连接、查询、创建、更新）
• bulk_operations.rs -批量操作示例（移动、完成、删除）
• search_tasks.rs -高级搜索功能
• export_data.rs -以多种格式（JSON、CSV、Markdown）导出数据

cargo run --package things3-core --example basic_usage
cargo run --package things3-core --example bulk_operations
cargo run --package things3-core --example search_tasks
cargo run --package things3-core --example export_data

集成示例（1.0.0中新增）

现实世界的整合模式 examples/integration/:

• mcp_client.rs -自定义MCP客户端实现
• cli_extension.rs -使用自定义命令扩展CLI
• web_api.rs -使用Axum web框架的REST API
• background_service.rs -长时间运行服务，优雅关机
• custom_middleware.rs -针对跨领域问题的定制中间件

cd examples/integration
cargo run --example mcp_client
cargo run --example cli_extension -- today
cargo run --example web_api
cargo run --example background_service
cargo run --example custom_middleware

看 examples/integration/README.md 详细文档。

API文档

生成和查看API文档：

cargo doc --workspace --no-deps --open

测试

测试覆盖率

• 总测试：438次测试
• 覆盖：~85%+（目标：85%+）
• 测试类别:

- 数据库操作（第一阶段） - MCP I/O层（第2阶段） - 中间件链（第3阶段） - 可观测性系统（第4阶段）

运行测试

# All tests
cargo test --workspace

# Specific package
cargo test --package things3-core

# With coverage
cargo llvm-cov --workspace --all-features --html
open target/llvm-cov/html/index.html

运行实时AppleScript测试（仅限macOS）

这 AppleScriptBackend 集成测试驱动真实的Things 3安装 通过 osascript。默认情况下，它们被门控并忽略-- cargo test 在没有Things 3的CI/CD/Linux/Mac上无法运行它们。

先决条件：

• macOS与 事情3 安装。
• 第一次调用会触发macOS自动化权限提示

（“生锈的3想要控制东西3”）。通过系统设置授予它→ 隐私和安全→ 自动化，否则测试将失败 权限被拒绝错误。

运行方式：

THINGS3_LIVE_TESTS=1 cargo test -p things3-core --test applescript_live \
    -- --ignored --test-threads=1

--test-threads=1 是必需的：每个测试都会改变单个共享 Things 3实例，并发运行将竞争。每个测试创建 具有唯一性的实体 rust-things3 e2e {ts}-{uuid}-风格标题和 完成后删除它们（Drop guard确保即使在恐慌时也能进行清理）。 了解为什么该项目使用AppleScript而不是编写 直接使用SQLite数据库，请参阅 Culture Code的安全 文章.

看 开发指南 了解更多测试细节。

发展

先决条件

• 锈蚀1.70+
• Moon（用于工作空间管理）
• 事情3（用于测试）
• 货物llvm-cov（覆盖范围）

设置

# Clone the repository
git clone https://github.com/GarthDB/rust-things3
cd rust-things3

# Install dependencies
moon run :local-dev-setup

# Run tests
moon run :test-all

# Run development pipeline
moon run :dev-pipeline

快速命令

# Format code
cargo fmt --all

# Lint code
cargo clippy --workspace -- -D warnings

# Run coverage
cargo llvm-cov --workspace --all-features --html

# Generate docs
cargo doc --workspace --no-deps

看 开发指南 获取全面的发展信息。

项目结构

rust-things3/
├── apps/
│   └── things3-cli/       # CLI application with MCP server
├── libs/
│   ├── things3-core/      # Core library
│   └── things3-common/    # Shared utilities
├── tools/
│   └── xtask/             # Development tools
└── tests/                 # Integration tests

API 参考

核心库

基本用法

use things3_core::{ThingsDatabase, Task, Project, Area, ThingsConfig};
use anyhow::Result;

#[tokio::main]
async fn main() -> Result {
    // Create database connection with SQLx
    let db = ThingsDatabase::new("/path/to/things.db").await?;
    
    // Get inbox tasks
    let tasks = db.get_inbox(Some(10)).await?;
    
    // Get today's tasks
    let today_tasks = db.get_today(None).await?;
    
    // Get all projects
    let projects = db.get_projects(None).await?;
    
    // Search tasks
    let search_results = db.search_tasks("meeting").await?;
    
    Ok(())
}

高级配置

use things3_core::{ThingsDatabase, ThingsConfig};
use std::path::Path;

// Custom database path with SQLx
let db = ThingsDatabase::new(Path::new("/custom/path/to/things.db")).await?;

// From environment variables
let config = ThingsConfig::from_env();
let db = ThingsDatabase::new(&config.database_path).await?;

错误处理

use things3_core::{ThingsDatabase, ThingsError};
use anyhow::Result;

async fn handle_errors() -> Result {
    let db = ThingsDatabase::new("/path/to/things.db").await?;
    
    match db.get_inbox(Some(5)).await {
        Ok(tasks) => println!("Found {} tasks", tasks.len()),
        Err(ThingsError::Database(msg)) => {
            eprintln!("Database error: {}", msg);
        }
        Err(e) => {
            eprintln!("Other error: {}", e);
        }
    }
    
    Ok(())
}

缓存和性能

use things3_core::{ThingsDatabase, CacheConfig};
use std::time::Duration;

// Configure caching
let cache_config = CacheConfig {
    max_capacity: 1000,
    time_to_live: Duration::from_secs(300),
    time_to_idle: Duration::from_secs(60),
};
let db = ThingsDatabase::with_cache_config(cache_config)?;

// Get cache statistics
let stats = db.get_cache_stats().await?;
println!("Cache hits: {}, misses: {}", stats.hits, stats.misses);

数据导出

use things3_core::{DataExporter, ExportFormat, ExportConfig};

// Export to JSON
let exporter = DataExporter::new_default();
let json_data = exporter.export_json(&tasks, &projects, &areas).await?;

// Export to CSV
let csv_data = exporter.export_csv(&tasks, &projects, &areas).await?;

// Custom export configuration
let config = ExportConfig {
    include_completed: false,
    date_format: "%Y-%m-%d".to_string(),
    time_format: "%H:%M:%S".to_string(),
};
let exporter = DataExporter::new(config);

MCP服务器集成

use things3_cli::mcp::{ThingsMcpServer, CallToolRequest};
use serde_json::json;

// Create MCP server
let server = ThingsMcpServer::new(config)?;

// List available tools
let tools = server.list_tools().await?;
println!("Available tools: {:?}", tools.tools);

// Call a tool
let request = CallToolRequest {
    name: "get_inbox".to_string(),
    arguments: Some(json!({
        "limit": 10
    })),
};
let result = server.call_tool(request).await?;

CLI库

use things3_cli::{Cli, Commands, print_tasks, print_projects};
use std::io::stdout;

// Parse CLI arguments
let cli = Cli::parse();

// Use CLI functions programmatically
match cli.command {
    Commands::Inbox { limit } => {
        let tasks = db.get_inbox(limit).await?;
        print_tasks(&mut stdout(), &tasks)?;
    }
    Commands::Projects { area_uuid, limit } => {
        let projects = db.get_projects(area_uuid, limit).await?;
        print_projects(&mut stdout(), &projects)?;
    }
    // ... other commands
}

基础功能类库

use things3_common::utils::{
    get_default_database_path,
    format_date,
    format_datetime,
    parse_date,
    is_valid_uuid,
    truncate_string
};

// Get default database path
let db_path = get_default_database_path();
println!("Default path: {}", db_path.display());

// Format dates
let formatted = format_date(chrono::Utc::now().date_naive());
println!("Today: {}", formatted);

// Parse dates
let date = parse_date("2024-01-15")?;
println!("Parsed date: {}", date);

// Validate UUIDs
let is_valid = is_valid_uuid("550e8400-e29b-41d4-a716-446655440000");
println!("Valid UUID: {}", is_valid);

// Truncate strings
let truncated = truncate_string("Very long string", 10);
println!("Truncated: {}", truncated);

建筑

该项目被组织为Moon管理的Rust工作区：

rust-things3/
├── apps/things3-cli/      # CLI application with MCP server
├── libs/things3-core/     # Core database and business logic
├── libs/things3-common/   # Shared utilities
├── examples/              # Usage examples
├── docs/                  # Documentation
└── tests/                 # Integration tests

主要特点：

• 异步优先：基于Tokio构建，用于并发操作
• 类型安全：SQLx用于编译时SQL验证
• MCP协议：行业标准AI代理通信
• 中间件：可扩展的请求/响应处理
• 可观测性：内置指标、日志记录和跟踪

看 架构文档 详细的系统设计。

故障排除

未找到数据库

# Find your Things 3 database
find ~/Library/Group\ Containers -name "main.sqlite" 2>/dev/null

# Set custom path
export THINGS_DB_PATH="/path/to/main.sqlite"

权限问题

事情3必须运行 使用变异操作（创建、更新、完成、删除）时。默认值 AppleScriptBackend 通过驱动Things 3 osascript --它要求应用程序打开。

首次运行时，macOS将提示： *“生锈的3想要控制Things 3。”* 通过系统设置授予访问权限→ 隐私和安全→ 自动化。

对于只读操作（收件箱、今天、搜索等），Things 3不需要运行。

升级后失效的二进制文件

如果您通过以下方式升级 cargo install 但MCP服务器的行为仍然像 在旧版本上，您可能正在运行 过时的内存二进制文件 --the 即使磁盘上的文件发生了变化，操作系统也会将旧的可执行文件缓存在内存中。

症状： 工具调用返回在新版本中修复的错误； things3 --version 从新shell运行时打印旧版本号 但运行过程报告了一些不同的情况。

修复： 重新启动承载MCP服务器的进程或应用程序（例如 编辑器、Claude Desktop或正在运行的shell things3 mcp)，然后验证：

things3 --version   # should print the new version

测试失败

如果遇到数据库锁定问题，请运行单线程测试：

cargo test -- --test-threads=1

看 开发指南 了解更多故障排除提示。

贡献

我们欢迎捐款！请查看我们的 贡献指南 有关以下内容的详细信息：

• 开发设置
• 代码风格指南
• 测试要求
• 拉取请求流程
• 问题报告

快速开始

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加测试（保持85%以上的覆盖率）
5. 运行开发管道： moon run :dev-pipeline
6. 提交拉取请求

有关更多详细信息，请参阅 贡献.md 和 开发指南.

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

致谢

• 灵感来自 事物3
• 建于 月亮 工作空间管理
• 跟随 开发应用程序/事物api 模式