# Pi Time Awareness

[English](README.md) | 简体中文

长会话里，时间往往是最先从上下文里变模糊的东西。

模型会读上下文，但未必读得懂时间。

在以时间为第四维度的世界里，我们需要给它恰到好处的时间感。

## 安装

### npm package

```bash
pi install npm:pi-time-awareness
```

### Git repository

```bash
pi install git:github.com/EnderLiquid/pi-time-awareness
```

## 功能

`pi-time-awareness` 让你的 Agent 能够感知当前时间，以及会话经历的时间跨度。

它为 Agent 提供了两种互补的时间能力：

- 低频时间锚点：插件会适时在新的用户消息后，额外注入一条在 TUI 中隐藏的时间提示消息。这条消息会写入会话历史，使 Agent 能根据最近锚点粗略了解当前时间，并通过上下文中的多个锚点感知会话的时间跨度。时间锚点的注入间隔至少为一小时，以避免产生过多上下文噪音。

- `time` 工具：模型可以按需获取当前精确时间，返回格式化显示字符串 `display` 和 Unix 毫秒时间戳 `unixMs`。

同时，它会移除 Pi 系统提示词中内建的 `Current date:` 行，避免长期会话里出现低精度、可能过时的日期噪音。

## 特点

- 时间信息低频注入，不污染上下文，缓存友好

- 用对齐用户消息的持久时间锚点，替代 Pi 粗糙的当前日期提示，时间感知更精确、更立体

- 节流判断基于当前会话分支的最近时间锚点，回退树或切换分支后仍能保持正确行为

## 时间格式

示例：

- 锚点消息：`Time anchor: Wed 2026-06-17 10:32:45 UTC+08:00`

- 工具返回：
  
  ```json
  {
    "display": "Wed 2026-06-17 10:32:45 UTC+08:00",
    "unixMs": 1781663565000
  }
  ```

插件会跟随运行时所在的本地时区，统一以 `UTC±HH:mm` 形式展示偏移。

## 许可证

MIT License