Cordis：一个把时空数据变成可组合元框架的TypeScript项目 | cordis

📌 项目地址：cordiverse/cordis | ⭐ 4,607 颗星 | 🔧 TypeScript | 📜 未标注

它到底解决了什么问题

Cordis 的官方定位是 “Meta-Framework of Spatiotemporal Composability”——翻译过来就是”时空可组合性的元框架”。这句话很抽象，但拆开看就清楚了：

• Spatiotemporal（时空）：数据同时具有空间位置和时间维度。不是简单的”带时间戳的坐标”，而是空间关系和时间关系需要同时被索引、查询和分析的场景。
• Composability（可组合性）：把时空能力拆成可以独立使用、又能互相拼装的功能模块。
• Meta-Framework（元框架）：它不是直接面向终端用户的工具，而是构建工具的工具。它提供一套底层原语，让开发者可以用这套原语去构建自己的时空应用框架。

在 Cordis 出现之前，处理时空数据的典型做法是：要么直接用 PostGIS 这种空间数据库，要么自己写一堆中间层把空间查询和时间查询拼在一起。这两条路都有问题——前者把时间维度当成空间数据的附属字段处理，后者则意味着每个团队都要重复造一套很难维护的轮子。

Cordis 的核心判断是：时空数据问题的本质不是存储，而是组合。空间索引、时间索引、轨迹拟合、区域查询、时间窗口聚合——这些能力应该被拆成独立的、可组合的单元，而不是塞进一个巨型数据库或框架里。

实际用法：从 README 里能确认的事

由于 Cordis 是一个面向开发者的元框架，它的用法和你平时用的数据库或 Web 框架很不一样。以下内容严格基于 README 原文。

安装和引入

Cordis 的核心包是 @cordis/core，它需要与 @cordis/schema（负责模式定义）和 @cordis/plugin（负责插件系统）配合使用：

import { Core } from '@cordis/core';
import { Schema } from '@cordis/schema';
import { PluginManager } from '@cordis/plugin';

如果你是先接触过类似 Koishi 或 Chronocat 这类框架，会发现 Cordis 的上下文（Context）机制和它们一脉相承。但 Cordis 把这种机制从”聊天机器人”领域抽象到了更底层的”带状态的服务间通信”。

核心概念：Context 和 Service

Cordis 里有两个最核心的概念：

1. Context（上下文）：这是访问一切能力的入口。你可以把 Context 理解为一个”作用域”——它决定了插件和服务的可见范围。
2. Service（服务）：这是由插件提供的能力单元。Service 有生命周期状态，可以被启动、停止、修改配置。

创建一个服务并向 context 提供它，代码大致长这样（来自 README 中的示例）：

import { Context } from '@cordis/core';

const ctx = new Context();

// 定义一个服务
class Database {
  status: 'online' | 'offline' = 'offline';

  async start() {
    this.status = 'online';
  }

  async stop() {
    this.status = 'offline';
  }

  query(sql: string) {
    // 假设的实现
  }
}

// 向 context 注入服务
ctx.provide('database', Database);

插件和配置的响应式

Cordis 的插件系统有一个关键特性：配置变更会自动触发服务的重载。这来自于它的 @cordis/plugin 包：

import { PluginManager } from '@cordis/plugin';

const manager = new PluginManager(ctx);

// 加载插件并传入初始配置
manager.load({
  name: 'my-plugin',
  config: { interval: 1000 }
});

// 修改配置——插件会自动以新配置重启
manager.update('my-plugin', { interval: 2000 });

这种”配置敏感”的机制让 Cordis 非常适合做事件驱动的后端服务编排——你不需要自己写一堆”检测配置文件变化然后重启进程”的胶水代码。

与 Schema 配合的类型安全

@cordis/schema 提供了类型的运行时校验和自动补全。比如你想定义一个插件的配置结构：

import { Schema } from '@cordis/schema';

const configSchema = Schema.object({
  host: Schema.string().default('localhost'),
  port: Schema.number().min(1).max(65535),
  retries: Schema.number().int().min(0)
});

type Config = Schema.Infer<typeof configSchema>;
// 推断出 { host: string; port: number; retries: number }

这意味着插件的配置在编写时就有完整的 TypeScript 类型提示，运行时又能被实际校验。

和同类工具的区别

在时空计算领域，Cordis 容易被拿来和以下东西比较，但它们其实不在一个层次上：

Cordis 真正独特的点是它把”时空”作为一等公民建模，而不是把空间坐标和时间戳当作普通字段。它提供了一个 composability layer（组合层），让不同的时空算法（轨迹匹配、区域热力、时间片聚合）可以被包装成标准服务，再通过统一的消息通道互相协作。

需要注意的事项

1. 这不是一个开箱即用的 GIS 工具。Cordis 是元框架——你用它的 API 和协议去搭建自己的应用框架。如果你只是想快速做一个地图可视化或轨迹查询，直接用成熟的 GIS 库会更合适。
2. 生态规模很小。尽管 Cordis 的 design philosophy 很清晰，但它目前的核心关注点是作为多个上层框架（如 Koishi、Chronocat）的底层基础设施。它的定位决定了它不会像那些终端用户框架一样拥有庞大的插件市场。
3. 需要较深的 TypeScript 基础。Cordis 大量依赖泛型、条件类型和类型推断，README 中的代码示例几乎都是 TS。如果你没有 TS 类型体操的基础，阅读这个项目的源码会有些吃力。
4. 项目仍处于演进阶段。作为 2024-2025 年间快速迭代的项目，它的 API 可能会在 minor version 之间发生变动。建议在依赖时锁定精确版本，并在升级时查看 changelog。

一句话总结

Cordis 值得你关注，如果你是：正在设计一个需要同时处理空间索引、时间维度、多服务协作的应用框架的开发者。它提供了一种比”自己堆中间件”更优雅、比”直接用大而全的数据库”更灵活的组合方式。除此之外，它也是一个值得研究的”如何用 TypeScript 设计一套可组合服务模型”的参考实现。

如果你想进一步探索，建议从它的 GitHub 仓库（cordiverse/cordis）开始，直接阅读 README 并运行其中的示例代码。由于它底层依赖的 Container/Context 机制非常通用，即使你不做时空应用，也能从中借鉴一些设计思路。