# time-format

> 时间格式规范，强制要求所有时间字段都必须通过工具动态获取，严禁使用任何假设时间

- Author: gengxiao
- Repository: atom-set/prompt-engin
- Version: 20260129205336
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/atom-set/prompt-engin
- Web: https://mule.run/skillshub/@@atom-set/prompt-engin~time-format:20260129205336

---

---
name: time-format
description: 时间格式规范，强制要求所有时间字段都必须通过工具动态获取，严禁使用任何假设时间
priority: 4
tags: ['document', 'time', 'format']
---

# 时间格式规范

## 使用场景

当用户需要：
- 创建包含时间字段的文档时
- 生成文件名包含日期时
- 记录时间戳时
- 任何需要时间信息的场景

## 触发条件

以下情况自动应用此规范：
- 检测到文档包含时间字段时
- 生成文件名需要日期时
- 用户要求添加时间信息时

## 与其他规则的配合

- **依赖关系**：
  - `time-check`：创建包含时间字段的文档时，必须先通过工具获取当前时间，这是强制检查机制
- 与核心规则配合使用

---

## ⚠️ 禁止假设时间清单（强制要求）

### 核心原则

**所有时间字段都必须通过工具动态获取，严禁使用任何假设时间！**

---

### 禁止的时间值（完整清单）

#### 1. 禁止任何具体日期（最常见错误）

| 禁止使用 | 原因 | 正确做法 |
|---------|------|---------|
| ❌ `2025-01-01` | 假设的元旦日期 | ✅ 运行 `date '+%Y-%m-%d'` |
| ❌ `2025-01-17` | 假设的具体日期 | ✅ 运行 `date '+%Y-%m-%d'` |
| ❌ `2025-01-21` | 假设的具体日期 | ✅ 运行 `date '+%Y-%m-%d'` |
| ❌ `2025-12-01` | 假设的12月日期 | ✅ 运行 `date '+%Y-%m-%d'` |
| ❌ `2024-11-27` | 历史日期 | ✅ 运行 `date '+%Y-%m-%d'` |
| ❌ 任何 `YYYY-MM-DD` 格式的具体日期 | 都是假设的 | ✅ 运行 `date '+%Y-%m-%d'` |

#### 2. 禁止格式占位符

| 禁止使用 | 原因 | 正确做法 |
|---------|------|---------|
| ❌ `YYYY-MM-DD` | 格式占位符，不是实际日期 | ✅ 运行 `date '+%Y-%m-%d'` |
| ❌ `YYYY-MM-DD HH:MM:SS` | 格式占位符 | ✅ 运行 `date '+%Y-%m-%d %H:%M:%S'` |
| ❌ `[日期]` | 占位符 | ✅ 运行 `date '+%Y-%m-%d'` |
| ❌ `[待填写]` | 占位符 | ✅ 运行 `date '+%Y-%m-%d'` |

#### 3. 禁止模糊表述

| 禁止使用 | 原因 | 正确做法 |
|---------|------|---------|
| ❌ `今天` | 模糊表述 | ✅ 运行 `date '+%Y-%m-%d'` |
| ❌ `当前日期` | 模糊表述 | ✅ 运行 `date '+%Y-%m-%d'` |
| ❌ `现在` | 模糊表述 | ✅ 运行 `date '+%Y-%m-%d %H:%M:%S'` |
| ❌ `本地时间`（单独使用） | 只说明时区，没有具体时间 | ✅ 运行 `date '+%Y-%m-%d'` |

#### 4. 禁止相对时间表述

| 禁止使用 | 原因 | 正确做法 |
|---------|------|---------|
| ❌ `昨天` | 相对时间 | ✅ 如需要，使用 `date -d "yesterday" '+%Y-%m-%d'` |
| ❌ `上周` | 相对时间 | ✅ 如需要，使用 `date -d "last week" '+%Y-%m-%d'` |
| ❌ `下个月` | 相对时间 | ✅ 如需要，使用 `date -d "next month" '+%Y-%m-%d'` |

---

### ⚠️ 特别强调（必读）

**以下是最常犯的错误，必须避免**：

1. **错误示例1：直接写入具体日期**
   ```markdown
   ❌ 错误：
   > **创建时间**: 2025-01-21（本地时间）
   
   ✅ 正确流程：
   # 第一步：获取当前日期
   run_terminal_cmd("date '+%Y-%m-%d'")
   # 返回：2025-12-01
   
   # 第二步：使用获取的日期
   write("file.md", "> **创建时间**: 2025-12-01（本地时间）")
   ```

2. **错误示例2：使用格式占位符**
   ```markdown
   ❌ 错误：
   > **创建时间**: YYYY-MM-DD（本地时间）
   
   ✅ 正确：先运行 date 命令获取实际日期
   ```

3. **错误示例3：在代码中硬编码日期**
   ```typescript
   ❌ 错误：
   const testDate = '2025-01-17';
   
   ✅ 正确：
   const testDate = new Date().toISOString().split('T')[0];
   ```

4. **错误示例4：凭记忆或猜测日期**
   ```
   ❌ 错误思路："今天是1月21日，我就写2025-01-21"
   
   ✅ 正确思路："我必须先运行date命令获取当前日期"
   ```

---

### 🔍 自检清单（每次创建文档时必查）

在创建包含时间字段的文档时，必须完成以下检查：

- [ ] **我是否运行了 `date` 命令获取当前时间？**
  - 如果没有，立即运行：`date '+%Y-%m-%d'`
  
- [ ] **我使用的日期是从 `date` 命令返回的吗？**
  - 如果不是，停止！先运行 `date` 命令
  
- [ ] **我没有使用以下任何禁止的值吗？**
  - [ ] 没有使用 `2025-01-21`、`2025-01-17` 等具体日期
  - [ ] 没有使用 `YYYY-MM-DD` 格式占位符
  - [ ] 没有使用"今天"、"当前日期"等模糊表述
  - [ ] 没有凭记忆或猜测日期
  
- [ ] **如果是示例或格式说明，我有明确标注吗？**
  - 示例日期必须标注："⚠️ 此处仅为格式示例，实际使用时必须运行 date 命令获取真实日期"

---

### 🚨 违规处理

**如果发现使用了假设时间，应立即停止并纠正**：

1. **识别违规**：
   - 检查文档中的时间字段
   - 发现任何 `2025-XX-XX` 格式的日期
   - 发现 `YYYY-MM-DD` 占位符
   - 发现"今天"、"当前日期"等表述

2. **停止执行**：
   - 停止当前的文件写入操作
   - 不要提交包含假设时间的文档

3. **立即纠正**：
   - 运行 `date '+%Y-%m-%d'` 获取当前时间
   - 使用获取的时间替换假设时间
   - 重新执行文件写入

---

### 📌 记忆锚点（强化记忆）

**每次看到时间字段，立即想到这三个字：**

🔥 **先运行 date！**

**不管什么情况，只要涉及时间，第一反应就是：**

```bash
date '+%Y-%m-%d'
```

**任何具体日期都不能直接使用，只有 date 命令返回的日期才能使用！**

---

### ⚠️ 重要警告

**本规则中的所有日期格式示例（如 YYYY-MM-DD）仅用于说明格式结构，不代表具体日期。**

**实际使用时必须：**
- ✅ 使用系统当前时间（动态获取）
- ✅ 使用文档实际创建/更新时间
- ❌ 禁止使用固定的假设日期
- ❌ 禁止复制格式示例中的占位符

---

### 强制要求
- **核心原则**：所有涉及时间的地方都必须使用本地时间（系统时区），这是强制要求，不是建议
- **适用范围**：文档、代码、报告、日志、数据分析等所有时间相关的场景
- **统一原则**：**所有包含时间的地方**（文档、代码、测试代码、配置文件、脚本、报告等）都必须禁止硬编码假设日期，必须使用实际时间或动态生成时间

### 时区要求
- **统一时区**：所有时间相关输出必须使用本地时间（系统时区）
- **时区标识**：在需要明确时区的场景，应标注"本地时间"或实际时区

---

### 时间格式要求

#### 1. 文档中的时间显示

##### 1.1 格式规范

| 格式类型 | 格式定义 | 格式示例（占位符） | 说明 |
|---------|---------|-------------------|------|
| 日期 | YYYY-MM-DD | `{当前日期}` | 4位年-2位月-2位日 |
| 日期时间 | YYYY-MM-DD HH:MM:SS | `{当前时间}` | 包含时分秒 |
| 带毫秒 | YYYY-MM-DD HH:MM:SS.mmm | `{精确时间}` | 包含毫秒 |
| 带时区 | YYYY-MM-DD（本地时间） | `{当前日期}（本地时间）` | 标注时区 |

**说明**：
- 上表中的"格式示例"列使用占位符表示，实际使用时必须替换为真实日期
- 禁止直接使用 `{当前日期}` 这样的占位符文本

##### 1.2 获取时间的方法

**JavaScript 获取当前日期**：
```javascript
// 获取 YYYY-MM-DD 格式
const currentDate = new Date().toLocaleDateString('zh-CN', {
  year: 'numeric',
  month: '2-digit',
  day: '2-digit'
}).replace(/\//g, '-');

// 获取 YYYY-MM-DD HH:MM:SS 格式
const currentDateTime = new Date().toLocaleString('zh-CN', {
  year: 'numeric',
  month: '2-digit',
  day: '2-digit',
  hour: '2-digit',
  minute: '2-digit',
  second: '2-digit',
  hour12: false
}).replace(/\//g, '-');
```

**Shell 获取当前时间**：
```bash
# 获取 YYYY-MM-DD 格式
current_date=$(date '+%Y-%m-%d')

# 获取 YYYY-MM-DD HH:MM:SS 格式
current_time=$(date '+%Y-%m-%d %H:%M:%S')
```

**TypeScript 获取当前时间**：
```typescript
// 获取 YYYY-MM-DD 格式
const getCurrentDate = (): string => {
  const now = new Date();
  const year = now.getFullYear();
  const month = String(now.getMonth() + 1).padStart(2, '0');
  const day = String(now.getDate()).padStart(2, '0');
  return `${year}-${month}-${day}`;
};
```

##### 1.3 创建时间处理原则

**必须使用文档实际创建时间**（本地时间），禁止使用假设或固定的日期。

**获取文件创建时间的方法**：

```bash
# 使用 Git 历史获取文件首次提交时间
git log --follow --format=%ad --date=short --reverse -- <文件路径> | head -1

# macOS 获取文件创建时间
stat -f "%SB" -t "%Y-%m-%d" <文件路径>

# Linux 获取文件修改时间
stat -c "%y" <文件路径> | cut -d' ' -f1
```

**如果无法确定实际创建时间**：
- 可以不填写创建时间字段
- 只保留最后更新时间
- 或在文档中说明："创建时间未知"

---

#### 2. 代码中的时间处理

##### 2.1 基本要求

- **时间戳格式**：使用毫秒时间戳（number类型）
- **时区转换**：生成时间戳时，使用系统本地时区
- **时间格式化**：使用本地时间进行格式化输出

##### 2.2 禁止硬编码假设日期

**❌ 错误示例**：
```javascript
// 禁止：硬编码固定日期
const testDate = "固定日期字符串";
const createTime = "固定时间字符串";
```

**✅ 正确示例**：
```javascript
// 正确：使用动态时间
const testDate = new Date().toISOString().split('T')[0];
const createTime = new Date().toLocaleString('zh-CN');

// 正确：测试中使用相对时间
test('日期格式化测试', () => {
  const now = new Date();
  const result = formatDate(now);
  const expected = now.toISOString().split('T')[0];
  expect(result).toBe(expected);
});
```

##### 2.3 测试代码中的时间处理

**场景1：需要固定时间点的测试**

使用相对时间或Mock：
```javascript
// 方法1：使用相对时间
test('测试30天前的日期', () => {
  const now = new Date();
  const thirtyDaysAgo = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000);
  // 使用 thirtyDaysAgo 进行测试
});

// 方法2：Mock 时间
jest.useFakeTimers();
jest.setSystemTime(new Date('2024-01-01')); // 仅在测试中使用
test('测试特定时间', () => {
  const now = new Date(); // 返回 Mock 的时间
  // 测试逻辑
});
jest.useRealTimers();
```

---

#### 3. 报告中的时间显示

| 字段名称 | 格式 | 获取方式 | 示例代码 |
|---------|------|---------|---------|
| 分析时间 | YYYY-MM-DD HH:MM:SS | 报告生成时间 | `new Date().toLocaleString('zh-CN')` |
| 数据时间范围 | YYYY-MM-DD ~ YYYY-MM-DD | 数据实际范围 | 从数据源获取 |
| 创建时间 | YYYY-MM-DD | 报告创建时间 | `new Date().toLocaleDateString('zh-CN')` |

---

### 适用场景

**所有涉及时间的地方都必须使用本地时间，包括但不限于：**

| 场景类型 | 具体场景 | 获取方式 |
|---------|---------|---------|
| 文档 | 创建时间、更新时间 | Git历史或文件系统 |
| 报告 | 生成时间、分析时间 | 系统当前时间 |
| 代码 | 时间戳、格式化时间 | `Date.now()`, `new Date()` |
| 测试 | 测试数据时间 | 相对时间或Mock |
| 日志 | 日志记录时间 | 系统当前时间 |
| 配置 | 配置生效时间 | 系统当前时间 |

---

### 注意事项

1. ✅ **强制要求**：所有时间输出必须使用本地时间，避免时区混淆
2. ✅ **一致性要求**：时间戳生成和格式化应保持一致，都基于本地时区
3. ✅ **标注要求**：在文档中首次出现时间时，应标注"本地时间"信息
4. ✅ **代码要求**：代码中处理时间时，必须使用系统本地时区
5. ✅ **统一原则**：所有包含时间的地方都要禁止硬编码假设日期，必须使用实际时间或动态生成时间
6. ✅ **创建时间要求**：创建时间必须使用文档实际创建时间，禁止使用假设日期
7. ✅ **更新时间要求**：更新时间必须使用文档实际更新时间，禁止使用假设日期
8. ✅ **代码中的时间处理要求**：代码中禁止使用硬编码的假设日期，应使用动态时间生成
9. ⚠️ **格式示例说明**：本规则中的格式示例（如 `YYYY-MM-DD`、`{当前日期}` 等）仅用于说明格式结构，实际使用时必须替换为真实的动态获取的时间