这是我整理的《通用项目上下文规范》v1.4.0，包含项目入口、进度、完成记录的模板及维护流程。

版本日期：2026-10-17。

---

# 通用项目上下文规范（.agent 目录）

>  规范版本：v1.4.0
>  创建日期：2026-01-27
>  最后更新：2026-09-23
>  用途：创建、审查和迁移通用项目的 `.agent` 目录，为 AI 助手提供可持续维护的项目上下文，并管理项目学习文档
>  **运行边界**：创建完成后，各项目的 `memory.md` 应自包含实际执行的维护规则。日常工作读取项目规则，不依赖本规范。

---

##  设计理念

AI 助手每次新对话需要重新建立项目状态。`.agent` 目录作为项目的外部上下文，使新对话能够了解项目背景、当前进度和历史决策。

### 核心原则

| 原则 | 说明 |
|------|------|
| **时间切片** | 三个核心文件按时间维度分工：恒定信息 / 当前状态 / 历史记录 |
| **单一数据源** | 同一信息只保存一份权威内容，其他位置使用链接或受限摘要 |
| **链接优于复制** | 项目事实和外部资料用链接引用，避免复制后产生多份版本 |
| **自包含** | 项目 `memory.md` 内嵌完整维护规则；这是“链接优于复制”的有意例外 |
| **版本可追踪** | 规范和项目分别记录版本状态，迁移有据可查 |
| **职责分层** | 核心上下文、上下文扩展、学习文档、历史归档与跨环境交换材料按用途分离 |
| **按需扩展** | 3 个核心文件为最小启动集；其他目录只在出现对应内容时创建 |
| **生命周期管理** | 计划、交接和交换材料在职责结束后退出活跃区，保留价值决定归档或删除 |
| **索引不等于加载** | `memory.md` 登记文件及读取时机；扩展内容只在任务相关时读取 |

### 规范用途和运行边界

本规范有两种用途：

1. **创建**：建立新的 `.agent` 三件套，并生成自包含的项目维护规则。
2. **审查或迁移**：检查现有 `.agent` 的结构、规则版本和记录质量，按变更记录定向修订。

项目进入日常运行后，以项目 `memory.md` 内嵌规则为直接依据。仅在创建、审查或迁移 `.agent` 时比较上游规范版本；普通开发、学习和问答不为版本比较而重复读取本规范。

---

##  版本与迁移规则

### 版本编号

规范使用语义版本号，版本号和日期分别记录：

| 版本位 | 升级条件 | 示例 |
|--------|----------|------|
| **MAJOR** | 三件套结构、文件职责或核心迁移流程发生不兼容变化 | `v2.0.0` |
| **MINOR** | 增加向后兼容的规则、字段或扩展机制；旧项目不迁移仍可继续工作 | `v1.1.0` |
| **PATCH** | 错别字、格式、链接或不改变执行含义的澄清 | `v1.0.1` |

消除歧义若会改变实际执行方式，应按 `MINOR` 或 `MAJOR` 评估，不能机械归入 `PATCH`。

### 项目版本登记

每个项目的 `memory.md` 应登记：

- **上下文类型**：通用项目 / 课程学习 / 课程任务 / 其他已定义类型
- **采用规范版本**：例如 `v1.3.0`
- **最近迁移日期**：`YYYY-MM-DD`

版本字段用于审查和迁移，不改变“项目内嵌规则是日常运行依据”这一原则。

### 迁移规则

1. 先比较项目采用版本与本规范的版本变更记录。
2. 仅处理标记为需要迁移、且适用于该项目的条目。
3. 迁移前读取项目现有规则，保留项目定制内容。
4. 禁止整段自动覆盖项目 `memory.md`；采用审查后的定向修改。
5. 迁移完成后更新项目版本字段，并在项目完成日志中留下记录。

---

##  目录结构与文件分工

```text
项目根目录/
└── .agent/
    ├── memory.md                 # 核心：项目档案、维护规则和导航入口
    ├── progress.md               # 核心：当前进度快照
    ├── completed_tasks_log.md    # 核心：历史完成记录
    ├── plugins/                  # 可选：已安装插件的本地副本
    ├── context/                  # 可选：供 AI 接手的活跃上下文扩展
    ├── docs/                     # 可选：供用户学习和重复阅读的文档
    ├── archive/                  # 可选：已退出活跃区但仍需追溯的原文及索引
    └── exchange/                 # 可选：本地 AI 与网页 AI 的跨环境交换材料
```

**只需 3 个核心文件即可启动**。所有可选目录均在出现对应内容时创建，不预建空结构。

### 五类内容

| 类型 | 主要读者 | 定位 | 典型内容 | 默认加载 |
|------|----------|------|----------|----------|
| 核心上下文 | AI | 恢复项目背景、当前状态和历史决策 | `memory.md`、`progress.md`、`completed_tasks_log.md` | `memory.md`、`progress.md`：是；`completed_tasks_log.md`：按需 |
| 上下文扩展 | AI | 承载核心文件放不下、且当前仍需接手的较大主题 | 活跃规划、架构事实、接口约定、当前排错交接 | 否，任务相关时按需读取 |
| 学习文档 | 用户 | 保存可独立阅读、适合复习的系统化内容 | 长篇讲解、运行原理、教程、验收方法 | 否，学习、复习或维护文档时按需读取 |
| 历史归档 | AI 与用户 | 保存已完成、取消或被替代且仍有追溯价值的原文 | 旧方案、已执行计划、已结束交接及配套资源 | 否，仅追溯历史或现行资料明确引用时读取 |
| 跨环境交换材料 | 本地 AI、网页 AI 与用户 | 在不能共享同一对话上下文的 AI 环境之间传递任务、结果和反馈 | 执行说明、结果回填、反馈记录、专用测试文件 | 否，仅由相关任务按需引用 |

目录位置不决定加载级别。`context/`、`docs/`、`archive/` 与 `exchange/` 均不默认加载；出现在索引中也不表示每次对话必须读取。

### 核心文件分工

| 文件 | 时间维度 | 定位 | 只放 | 不放 |
|------|----------|------|------|------|
| memory.md | 恒定 | 项目**是什么** | 概述、技术栈、目录结构、分类索引、维护规则 | 频繁变动的状态；学习文档正文 |
| progress.md | 当下 | **现在**做什么 | 接手指南、里程碑摘要、活跃任务、待办、已知问题 | 已完成任务的详细记录；与当前任务无关的历史信息 |
| completed_tasks_log.md | 过去 | **做过**什么 | 已完成或已取消任务的详细记录（**完成内容**必填；其余小节按需） | 进行中的内容；学习文档正文 |

### 事件式写回规则

根据本轮实际发生的事件分别更新对应文件；同一轮发生多类变化时，可以更新多个文件：

1. **任务开始、推进、受阻或下一步变化** → 更新 `progress.md`。
2. **任务或阶段完成** → 执行完成归档流程。
3. **项目静态事实变化** → 更新 `memory.md`，例如新增模块、技术栈、目录结构、长期约束或文档索引发生变化。
4. **只读审查、概念解释或简单查询，且没有改变项目状态** → 不更新三件套。

“需要写回”指本轮工作导致项目状态、成果、决策、阻塞、下一步或静态事实发生变化，不使用“实质工作”等难以客观判断的表述。

### 完成归档流程

完成归档应作为一次连续更新执行：

1. 将完成任务的详细内容写入 `completed_tasks_log.md`，新记录插入文件顶部并使用 `YYYY-MM-DD HH:MM`。历史时间无法确定时允许只写日期或标明约数，禁止补造时间。
2. 从 `progress.md` 移除对应活跃任务区块，并删除已完成待办、失效现场状态和不再帮助理解当前阶段的旧里程碑。
3. 更新接手指南、剩余待办和已知问题；若成果构成里程碑，只保留“日期 + 一句话成果摘要”。
4. 检查该任务使用的计划、交接和交换材料：仍有长期效力的内容先迁入现行权威文档；有追溯价值的原文移入 `archive/`；可重建且无独立证据价值的临时材料删除。
5. 文档移入归档后，从 `memory.md` 活跃索引移除，并在 `archive/index.md` 登记；更新相关文件的最后更新时间。

`progress.md` 的里程碑摘要是单一数据源原则的受限例外。摘要只保留理解当前阶段所需的节点；完整历史和完成详情以 `completed_tasks_log.md` 为准。

### 活跃任务边界与状态

- 每个活跃任务使用独立三级标题：`### 任务：[名称]`。
- 从该标题到下一个同级标题之前的内容是迁移单元。
- 完整完成：按完成归档流程迁移整个任务区块。
- 部分完成：保留任务区块并更新当前状态和下一步，不提前归档为完成。
- 取消：移入 `completed_tasks_log.md`，明确记录取消原因和已产生的成果。
- 拆分：保留父任务中的关键决策，建立可独立接手的子任务区块。

### 写回时机与失败处理

- 当本轮需要写回时，必须在发送本轮最终回复前完成。
- 写入失败时不得声称已经完成；应保留原状态，说明失败文件和未完成步骤。
- 重试编辑前应重新读取目标文件，避免覆盖用户或其他进程的新修改。

### 记录标准

> **`progress.md` 必须单独提供继续当前工作的必要信息；`completed_tasks_log.md` 的每条记录必须能够独立追溯对应历史，无需依赖完整聊天记录。**

- **活跃任务必填**：目标、当前状态、下一步；阻塞、关键决策和验证结果按需记录。
- **当前快照**：只保留当前与未来；完成归档后删除已完成待办，不长期保留 `[x]`；PID、临时 Build ID、一次性测试计数等仅在仍影响接手时保留。
- **里程碑**：只记录已经完成且仍帮助理解当前阶段的节点；完整历史以完成日志为准。
- **完成记录**：每条必须有“完成内容”；“关键决策”“遇到的问题”“相关文件”有则写、无则整节省略，禁止为凑结构写“无”。
- **上下文完整**：凡新对话接手所需的决策、踩坑、阻塞和验证结果，写入对应位置。

---

##  文件模板

>  **模板使用要求**：
> 1. 新建项目上下文时，必须完整采用对应模板的全部章节与小节，禁止自行省略、裁剪或修改模板结构；
> 2. `memory.md` 内嵌的维护规则正文须完整复制，未使用的索引小节保留标题与表格骨架（暂无内容时注明“暂无”）；
> 3. 如确有特殊情况需要调整、裁剪或省略模板内容，必须先向用户询问并获得明确确认。

### memory.md（项目档案 + 导航入口）

```markdown
# [项目名称] - 项目上下文

>  最后更新：YYYY-MM-DD
>  上下文类型：通用项目
>  采用规范版本：v1.4.0
>  最近迁移日期：YYYY-MM-DD

## 上下文索引

| 文档 | 用途 | 读取时机 |
|------|------|----------|
| [progress.md](progress.md) | 当前进度快照 | 每次对话 |
| [completed_tasks_log.md](completed_tasks_log.md) | 历史完成记录 | 按需读取；需要追溯历史决策、成果或排错过程时读取相关记录 |
| [context/示例.md](context/示例.md) | 较大的 AI 接手上下文 | 当前任务直接相关时 |
| [archive/index.md](archive/index.md) | 已退出活跃区的历史文档索引 | 用户要求追溯历史，或现行资料明确引用旧方案时 |

## 已安装插件

| 插件 | 本地文件 | 版本 | 读取时机 | 项目配置 |
|------|----------|------|----------|----------|
| [插件名称] | [plugins/插件名称.md](plugins/插件名称.md) | vX.Y.Z | [与当前任务相关时的具体触发条件] | [项目专用配置；无则填写“默认”] |

> 只登记已复制到 `.agent/plugins/` 的插件；未安装插件时标注“暂无”。插件只在符合读取时机时按需读取。

## 学习文档索引

| 文档 | 用途 | 读取时机 |
|------|------|----------|
| [docs/示例.md](docs/示例.md) | 面向用户的系统化学习材料 | 用户要求学习、复习、更新或当前任务直接依赖时 |

> 示例行仅说明格式；创建项目时仅删除示例文件行，必须保留“上下文索引”“已安装插件”与“学习文档索引”的章节标题和表格骨架；暂无内容时标注“暂无”。

---

## 项目概述

- **名称**：[项目名称]
- **目标**：[一两句话描述项目要做什么]
- **约束**：[截止日期、人员、特殊要求等]

## 技术栈

- [语言/框架/工具]

## 目录结构

[项目文件组织]

---

##  上下文维护规则

### 文件分工

| 文件 | 定位 | 只放 | 不放 |
|------|------|------|------|
| memory.md | 项目档案 + 导航入口 | 概述、技术栈、结构、分类索引、本规则 | 频繁变动的状态；学习文档正文 |
| progress.md | 当前快照 | 接手指南、里程碑摘要、活跃任务、待办、已知问题 | 已完成任务详情；与当前任务无关的历史信息 |
| completed_tasks_log.md | 历史归档 | 已完成或已取消任务的详细记录 | 进行中的内容；学习文档正文 |

### 事件式写回

1. 任务开始、推进、受阻或下一步变化 → 更新 `progress.md`。
2. 任务或阶段完成 → 先写完成日志，再移除活跃任务，更新接手指南、待办和已知问题；构成里程碑时追加一句摘要。
3. 项目静态事实变化 → 更新 `memory.md`。
4. 只读审查、概念解释或简单查询，且未改变项目状态 → 不更新三件套。

需要写回指本轮导致项目状态、成果、决策、阻塞、下一步或静态事实发生变化。同一轮发生多类变化时，分别更新对应文件。

### 活跃任务与归档

- 每个活跃任务使用 `### 任务：[名称]` 三级标题；该标题到下一个同级标题前为迁移单元。
- 活跃任务必填目标、当前状态、下一步；阻塞、关键决策、验证结果按需记录。
- 完整完成才迁移；部分完成继续保留并更新；取消任务归档时写明取消原因；拆分任务时建立可独立接手的子任务。
- 新完成记录插入 `completed_tasks_log.md` 顶部，使用 `YYYY-MM-DD HH:MM`；无法确定的历史时间禁止补造。
- `progress.md` 只保留当前与未来：完成后删除已完成待办和失效现场状态；里程碑只保留理解当前阶段所需的一句话摘要。
- 计划、交接文档仅在仍需跨会话继续工作时留在 `context/`；完成、取消或被替代后，先迁移仍有效内容，再按追溯价值归档或删除。

### 历史文档与临时材料

- `.agent/archive/` 保存已退出活跃区但仍有决策、设计或证据价值的原文；采用“一份 `index.md` + 多份独立原文”，配套资源随原文迁移。
- `archive/index.md` 登记文档、归档日期、原用途、归档原因和现行资料；`memory.md` 只索引该入口，不逐项登记归档文件。
- `.agent/exchange/` 用于本地 AI 与网页 AI 之间传递任务说明、执行结果、反馈和专用测试文件；不作为权威上下文，也不进入 `memory.md` 索引。
- 相关事项结束时逐项清理交换材料：长期结论写入权威文档或完成日志；有独立证据价值的原文归档；可重建、重复或无追溯价值的材料删除。
- 归档前同步更新活跃索引和引用；归档内容仅在用户要求追溯历史或现行资料明确引用时读取。

### 写回时机与失败处理

- 需要写回时，在发送本轮最终回复前完成。
- 写入失败不得声称完成；说明失败文件和未完成步骤。
- 重试编辑前重新读取目标文件。

### 记录标准

`progress.md` 须单独提供继续当前工作的必要信息；`completed_tasks_log.md` 的每条记录须能独立追溯对应历史，无需依赖完整聊天记录。

- 已完成待办不长期保留 `[x]`；PID、临时 Build ID、一次性测试计数等仅在仍影响接手时保留。
- 里程碑只记录已经完成且仍帮助理解当前阶段的节点；计划中的事项写在“待办”，完整历史以完成日志为准。
- 完成记录必填“完成内容”；“关键决策”“遇到的问题”“相关文件”有则写、无则省略整节。

### 插件查找与维护

- “已安装插件”是本项目支持插件的唯一索引。当前任务符合某项读取时机时，读取表中登记的本地插件文件；未触发时不加载。
- 插件未在项目入口登记时，视为本项目未安装，不扫描目录或规范库猜测可用插件。
- 当前任务需要的能力不在项目入口，或用户要求新增能力、安装插件、升级插件、审查上下文时，读取 `规范库/.agent/memory.md` 的中央插件索引查找适用插件。
- 安装插件前取得用户确认；确认后将源文件复制到 `.agent/plugins/`，再在“已安装插件”中登记名称、本地文件、版本、读取时机和项目配置；项目配置优先于插件默认值。
- 升级插件时比较源版本与本地版本，保留项目定制并定向修改，禁止直接覆盖；卸载时同步移除索引项，相关产物是否删除另行确认。
- 日常运行只依赖项目 `.agent/` 中的入口和本地插件；规范库源文件仅用于安装、升级和审查。

### 上下文扩展与学习文档

#### `.agent/context/`：上下文扩展

当某项 AI 接手信息较大、需要独立维护，且不适合继续放入核心三件套时，创建上下文扩展：

- 内容服务于 AI 继续工作，强调事实、约束、决策和验证结果。
- 一个主题一个文件，文件名应自解释。
- 在“上下文索引”中登记用途和读取时机。
- 核心文件只保留必要概述和链接，不复制正文。
- 新文件优先放入 `context/`；已有项目中散放在 `.agent/` 根目录的扩展文件可继续使用，无需强制迁移。

#### `.agent/docs/`：学习文档

当内容主要服务用户学习和重复阅读时，可创建或更新学习文档：

- 适用于系统化长篇讲解、架构原理、运行教程、可复现排错过程、验收方法和阶段研究成果；输出较长本身不构成创建理由，内容还应具有学习或复用价值。
- 文档应脱离原对话独立可读，并补足必要前置知识和逻辑链。
- 用户明确要求保存时可直接创建或更新；AI 主动判断值得保存时，应先说明建议文件名、用途和内容范围，取得同意后写入。
- 已有职责相同的文档时优先增量更新，一个主题只保留一份权威正文。
- 同一主题确需同时服务 AI 接手和用户学习时，`context/` 只保留执行所需的简明事实、约束和文档链接，详细解释只保存在 `docs/`。
- 在“学习文档索引”中登记用途和读取时机；核心三件套只记录摘要、状态和路径。
- `.agent/docs/` 是长期项目资料，不作为临时缓存；图片使用与 Markdown 文件同名的 `.assets/` 目录，便于 Typora 维护。

普通项目的个人学习文档优先放入 `.agent/docs/`。课程章节笔记仍遵循课程学习规范放入课程 `笔记/`；README、用户手册、正式报告和需对外协作或提交的材料仍放项目公开位置。内容用途变化时移动权威文件并更新索引，禁止保留两份独立正文。

#### 文档成果写回

创建、移动或实质更新上下文扩展或学习文档后：

1. 更新 `memory.md` 对应索引；仅修改正文、不改变用途或路径时无需机械更新索引。
2. 若构成任务或阶段成果，在 `completed_tasks_log.md` 记录结果和路径，不复制正文。
3. 若影响当前状态、下一步或阻塞，同时更新 `progress.md`。

### 对话初始化

AI 每次新对话，必须依次读取：
1. `memory.md` — 了解项目背景、维护规则和可用资料。
2. `progress.md` — 了解当前状态和待办。

`completed_tasks_log.md` 不默认读取。仅在 `progress.md` 信息不足或引用历史记录、当前任务需要追溯历史决策、成果或排错过程，或用户要求回顾历史时，读取相关记录；文件较大时只读取所需范围或近期部分。

`context/` 与 `docs/` 均不默认全量读取。只有当前任务直接相关、索引明确指定，或用户要求阅读、复习或更新时，才按需读取相应文件；索引到文件不等于自动加载文件。

`archive/` 与 `exchange/` 不默认读取。归档仅在用户要求追溯历史或现行资料明确引用时读取；交换材料仅由当前活跃任务按需读取。

仅在创建、审查或迁移 `.agent` 时比较上游规范版本；普通项目工作不为版本检查而读取父规范。
```

---

### progress.md（当前进度快照）

```markdown
# [项目名称] - 进度快照

>  最后更新：YYYY-MM-DD HH:MM
>  本文件只聚焦当前和未来，已完成的详细记录在 completed_tasks_log.md

---

##  接手指南

> 上次对话结束时的工作状态摘要，让新对话能立即接手。

- **正在进行**：[具体在做什么]
- **当前状态**：[做到哪了]
- **下一步**：[立即要做什么]

---

##  里程碑

> 只记录已经完成的节点，按时间追加。计划中的事项写在下方「待办」。

| 日期 | 里程碑 |
|------|--------|
| YYYY-MM-DD | [里程碑描述] |

---

##  活跃任务

> 每个任务使用独立三级标题。完整完成后按维护规则迁移整个任务区块。

### 任务：[任务名称]

- **目标**：[可验收的目标]
- **当前状态**：[做到哪里，已有结果]
- **下一步**：[立即可执行的动作]
- **阻塞**：[按需填写；没有则省略]
- **关键决策**：[按需填写；没有则省略]
- **验证结果**：[按需填写；没有则省略]

---

##  待办

- [ ] [待办事项]

---

##  已知问题

| 问题 | 状态 | 备注 |
|------|------|------|
| [问题描述] |  | [备注] |
```

---

### completed_tasks_log.md（历史完成记录）

```markdown
# [项目名称] - 完成记录

> 此文件记录已完成任务的详细信息，从 progress.md 迁移而来。
> 按时间倒序排列，方便回溯。
> **完成内容**为必填；**关键决策 / 遇到的问题 / 相关文件**为可选，有则写、无则省略整节。

---

## YYYY-MM-DD HH:MM: [任务/阶段名称]

### 完成内容
- [做了什么]（必填）

### 关键决策
- [为什么这样做]（可选；无则删除本小节）

### 遇到的问题
- [踩了什么坑，怎么解决的]（可选；无则删除本小节）

### 相关文件
- `path/to/file`（可选；无则删除本小节）

---

[更多历史记录...按时间倒序排列]
```

---

##  可选目录

### 通用创建原则

1. 一个主题一个文件，不按单条信息拆分。
2. 文件名应能直接说明主题。
3. 文件创建、移动或职责变化后，在 `memory.md` 对应索引中登记。
4. 已有职责相同的文件时优先更新，避免重复正文。
5. 只创建实际需要的目录和文件，不预建空结构。

### 常见上下文扩展（`.agent/context/`）

| 文件 | 适用场景 |
|------|----------|
| `plan.md` | 已确认并需长期接手的项目规划、架构设计、任务拆解 |
| `architecture.md` | 详细技术事实、模块关系、接口约定和数据流 |
| `troubleshooting.md` | 反复出现且影响后续工作的故障与解决方案 |
| `api.md` | AI 后续开发所需的接口定义和请求响应格式 |
| `decisions.md` | 重要技术取舍及其约束、原因和放弃方案 |

### 常见学习文档（`.agent/docs/`）

| 文件 | 适用场景 |
|------|----------|
| `系统架构与运行原理.md` | 面向用户解释系统组成、启动过程和调用链 |
| `环境配置与启动指南.md` | 保存可重复执行的环境搭建和运行方法 |
| `完整功能与验收标准.md` | 解释功能边界、验收层级和测试步骤 |
| `常见问题与原理.md` | 整理适合学习和复看的排错过程及底层原因 |

### 历史归档（`.agent/archive/`）

第一次出现需保留的历史原文时创建目录和 `index.md`。索引采用下表，不合并各文档正文：

| 文档 | 归档日期 | 原用途 | 归档原因 | 现行资料 |
|------|----------|--------|----------|----------|
| `[文件链接]` | `YYYY-MM-DD` | [原职责] | [已完成、取消或被替代] | [当前权威文档或完成记录；没有则省略] |

归档对象包括已执行并验收的计划、已结束的交接、被新方案替代的设计及其配套资源。文件较多时可按年份或主题建立子目录；`memory.md` 仍只登记 `archive/index.md`。

### 跨环境交换材料（`.agent/exchange/`）

- 用于本地 AI 与网页 AI 无法共享同一对话上下文时，传递任务说明、执行结果、反馈和专用测试文件。
- 文件应标明接收方、当前用途和结果回填位置；用途也可由相关活跃任务或引用文档明确给出。
- 相关事项结束时逐项决定迁入权威文档、移入归档或删除；不把 `exchange/` 当作长期权威资料库。
- 删除遵守当前环境的安全删除规则；无法确认追溯价值时先归档。

> 以上文件名仅为示例。归类以主要读者、用途和生命周期为准。

---

##  注意事项

### 避免过度设计

- 初期只用 3 个核心文件。
- 所有可选目录只在出现对应内容时创建，不预建空目录。
- 不因单次短回答、临时日志、进程号或未验证猜测创建长期文档；本地 AI 与网页 AI 确需跨环境协作时使用 `exchange/`，事项结束后清理。
- 各目录按职责和生命周期划分，不以文件数量决定是否使用；同一目录内部文件较少时保持扁平。

### 保持更新

- 本轮导致项目状态、成果、决策、阻塞、下一步或静态事实变化时，在最终回复前写回对应文件。
- 没有状态变化的只读审查、概念解释和简单查询不机械更新时间。
- 完成任务按归档流程同步更新完成日志、活跃任务、接手指南、待办、已知问题及相关计划、交接和交换材料。
- `progress.md` 只保留当前阶段需要的里程碑，完成待办及时移除。
- `memory.md` 的活跃索引与实际文件保持同步；历史原文统一经 `archive/index.md` 下钻。

### 敏感信息

- 密码、密钥等敏感信息应评估是否进入版本控制。
- 如需保存，使用 `.gitignore` 排除或采用加密存储。

---

##  版本变更记录

| 版本 | 日期 | 主要变更 | 兼容性 | 现有项目迁移 |
|------|------|----------|--------|--------------|
| `v1.4.0` | 2026-09-23 | 增加 `archive/` 历史归档与 `exchange/` 跨环境 AI 交流材料的职责、索引和退出机制；计划与交接文档在任务结束后归档或删除；收紧 `progress.md` 的历史保留范围 | 向后兼容；不使用新目录的项目可继续运行 | 按需迁移：存在过期计划、交接或临时材料时补充内嵌规则和归档入口，并定向清理活跃上下文 |
| `v1.3.1` | 2026-09-15 | 删除重复的上下文类型选择表，统一由规范库中央入口负责选型 | 仅调整规范职责，核心模板与运行规则不变 | 无需迁移 |
| `v1.3.0` | 2026-09-15 | 增加课程任务类型边界，区分整门任务型课程与单项大型交付项目 | 向后兼容；通用项目核心结构不变 | 按需审查课程目录：整门课程以多项轻量考核任务为主要状态时可迁移到课程任务类型 |
| `v1.2.0` | 2026-09-14 | 增加项目本地插件目录、已安装插件索引和内嵌插件查找维护规则；创建或迁移时从中央插件索引安装 | 向后兼容；无插件项目可继续运行 | 按需迁移：需要使用插件时补充索引与内嵌规则，不自动创建空目录 |
| `v1.1.1` | 2026-09-09 | 增加模板使用硬性要求，明确新建项目时必须完整采用对应模板的结构与全部小节、禁止自行裁剪或省略，澄清示例文件行删除说明 | 向后兼容 | 无需迁移已有项目 |
| `v1.1.0` | 2026-08-10 | 将可选内容分为 `.agent/context/` 上下文扩展与 `.agent/docs/` 学习文档；定义分类索引、创建授权、按需加载、文档成果写回及与课程笔记和公开文档的边界；将 `completed_tasks_log.md` 调整为按需读取 | 向后兼容；旧的根目录扩展文件可继续使用 | 按需迁移：定向更新项目内嵌规则和索引；不自动创建空目录或移动现有文件 |
| `v1.0.0` | 2026-07-14 | 建立正式版本基线；引入版本登记和模板适用边界；修复待办与文件职责歧义；改为事件式写回；定义任务边界、完成归档、里程碑摘要和失败处理 | 首个正式基线 | 建议迁移：同步版本字段和内嵌维护规则；保留项目定制内容 |

---

##  相关规范

- 笔记整理规范（原文中的关联规范，本公开附录未收录）
- 课程学习上下文规范（原文中的关联规范，本公开附录未收录） — 适用于以章节学习和答疑为主要状态的课程
- 课程任务上下文规范（原文中的关联规范，本公开附录未收录） — 适用于以多项任务、活动或技能考核为主要状态的课程