Project Manager v2.4 - 项目上下文管理系统

要解决的核心问题

Agent 会遗忘。 每天醒来是全新的，如果对话中没有及时记录，第二天就完全不记得做过什么。

本系统的目标：最小化信息遗漏，最大化可恢复性，不增加对话负担。

架构原则

与 Auto-Coding v3 集成

当使用 auto-coding-v3 进行代码开发时，该系统会在 workspace/projects/{project_name}/status/ 下生成详细的工程状态文件。
* STATUS.md 负责 宏观进度（Todo, Next Step, Decision）。
* status/ 目录负责 微观工程细节（Scratchpad, Logs）。

核心原则

1. 物理隔离：每个项目拥有独立的 STATUS.md，绝不混用。
2. 状态显式化：没有记录在文件里的事，就是没发生。
3. 对话中即时记录：重要决策/需求/完成节点即时写入，不堆积到最后。
4. session 内周期检查：skill 激活后自动注册周期性检查，持续扫描新对话。
5. 分级管理：轻重有别，杀鸡不用牛刀。
6. 意图优先：根据对话上下文自动判断项目操作意图。
7. 并发安全：写入前必须先 read 最新内容，合并后再 write。

目录结构规范

workspace/projects/
├── index.md              # 📇 项目索引（自动维护，必须含一句话概述）
├── {project-name}/
│   ├── STATUS.md         # 🧠 核心记忆：进度、待办、关键决策（每次对话必读/必写）
│   ├── docs/             # 方案、报告、调研数据
│   ├── src/              # 代码、产出物
│   └── status/           # auto-coding v3 微观工程文件（可选）
└── _archive/             # 📦 已归档项目
    └── {project-name}/
        └── STATUS.md     # 保留历史记录

📇 项目索引：projects/index.md

# 项目索引
> 自动维护，按最后活跃时间倒序

| 项目 | 目录 | 最后更新 | 状态 | 备注 |
|------|------|---------|------|------|
| english-reader | english-reader/ | 2026-04-20 | 活跃中 | 英语学习工具 |

维护规则：
- 首次使用：如不存在，自动创建并写入表头
- 新建项目时：添加到顶部
- 恢复项目时：更新"最后更新"时间，移到顶部
- 暂停项目时：更新"状态"为"已暂停"并记录暂停原因
- 归档项目时：移到 _archive/，index.md 标记为"已归档"
- 索引自愈：发现项目目录存在但 index 中没有时，自动补录
- 必须包含一句话概述，格式为「动词 + 对象 + 目的」

分级 STATUS.md 模板

A) 完整模板（>3天项目 / 多阶段任务 / 跨团队协作）

# 项目名称：[Name]
> 最后更新：[Date] | Git: [commit hash, 如果有]

## 🎯 核心目标
[一句话描述项目终极目标]

## 📍 当前状态
[当前处于什么阶段，刚完成了什么]

## 📋 待办事项 (Todo)
- [x] 已完成 1
- [ ] 待办 2 (优先级高)
- [ ] 待办 3

## 🔑 关键上下文/决策
- 决策 1 (为什么这么做)
- 约束 1 (用户明确要求的事项)
- 链接 (相关 URL/文件路径)

## 🛑 暂停原因/遗留问题
[如果项目暂停，记录卡点或下次需要确认的问题]

B) 轻量模板（<3天的单任务 / 调研/分析类临时任务）

# 项目名称：[Name]
> 最后更新：[Date]

## 📍 当前状态
[一句话描述当前进度]

## 🔑 决策（可选）
[如果做了重要选择，记录原因]

## 📋 下一步
- [ ] 接下来要做什么

模板选择规则

操作工作流 (Workflow)

1. 意图识别（自动激活）

穷举触发场景：

显式命令类（直接触发）

• 新建：新建项目、建个项目、帮我建一个、创建一个项目、开个新项目、搞个项目、我们来做XX、开始做XX
• 恢复：回到XX、继续XX、接着来、恢复到、回到项目、继续做
• 保存：保存状态、先停一下、暂停、我先走了、去做别的、歇会
• 查看：有哪些项目、项目列表、看看进度、看看XX进度、项目状态、目前在做啥
• 切换：切换到、不管这个了先搞YY、换个项目、先放一下

隐含指代类（根据上下文推断）

• 上次类：上次那个、上次说的、之前那个、之前聊的、上次说的方案、上次的方案、我们之前讨论的
• 继续类：接着来、继续吧、接着上次说、然后呢、下一步呢、继续做、那个做完了吗、那个项目怎么样了
• 关联类：跟之前说的一样、按我们之前讨论的、还是之前的方案、跟上次一样

重要性标记类（应即时记录到 STATUS.md）

• 这个很重要、记住这个、别忘了、记一下、这个值得记录、这个方案要记下来、把刚才说的记到项目里、刚才聊的东西挺重要的

话题切换类（应保存当前状态）

• 换个话题、先聊点别的、先不说这个了、我们今天先这样、明天继续、下周再说、改天再聊

完成信号类（应更新状态）

• 搞定了、做完了、这个问题解决了、这个方案定了、就按这个来、确认了

识别优先级：
1. 明确提到项目名 → 直接匹配 index.md
2. 模糊指代 → 根据 index.md 中最近活跃的项目推断
3. 无法确定 → 展示最近 2-3 个活跃项目让用户选择，不要盲目猜测

2. 初始化新项目 (Start New)

触发条件：
- 用户明确说"新建项目"/"帮我建一个"
- Agent 主动发现：对话涉及新话题，扫描 index.md 后确认无关联 → 主动创建，并向用户确认

门槛判断（避免过度工程）：
- 建项目：超过几句实质讨论、有具体问题/需求/决策、可能后续会继续推进（如"调研某系统"、"帮我想个方案"、"评估某技术"）
- 不建项目：随口一问、一句话话题、单纯信息查询 → 写入当日记忆即可

动作：
1. 先扫描 index.md — 检查是否有相关项目可以合并或关联
2. 有关联 → 合并到已有项目，告知用户"这个话题我已归入 XX 项目"
3. 无关联 → 继续以下步骤：
1. 先向用户确认："这是个新话题，我建个项目记录一下？概述是「{一句话概述}」"
2. 用户同意后再创建
3. 目录名用 kebab-case：cmra-geo
4. 创建目录 workspace/projects/{name}/
5. 根据复杂度选择 A/B 模板，创建 STATUS.md
6. 确保 index.md 存在：如不存在自动创建并写入表头
7. 一句话概述生成规则：从对话核心意图提炼，格式为「动词 + 对象 + 目的」
8. 更新 projects/index.md（添加到顶部）
4. 注册 session 周期检查（见第 8 节）

3. 恢复旧项目 (Resume)

动作：
1. 模糊匹配：用户说的项目名可能不精确，先在 index.md 中查找
2. 强制读取：read(workspace/projects/{name}/STATUS.md)
3. 摘要同步："📖 已恢复 {name} 上下文。当前：[简述进度]。待办：[列出]。继续哪一步？"
4. 更新 index.md：将该项目移到最后活跃时间顶部
5. 如果 STATUS.md 不存在或为空 → 检查 memory/ 目录下是否有相关日期的记忆文件，尝试恢复上下文；无法恢复时如实告知用户
6. 注册 session 周期检查（见第 8 节）

4. 🔄 对话中即时记录

这是核心机制。 不是等到用户说"保存状态"才记录，而是在对话中即时写入。

触发时机（满足任一即写入）：
- 用户提出了新的需求或约束
- 做出了技术/方案决策
- 完成了一个子任务
- 用户明确要求记住某事
- 话题发生实质性切换（从项目 A 切换到项目 B）

写入策略（轻量，不拖慢对话）：
- 只更新 STATUS.md 的"当前状态"和"待办"模块
- 用 1-2 句话记录结论，不写过程流水账
- 如果当前对话没有关联的项目 → 触发"新项目创建"流程（第 2 节）

不写入的情况：
- 只是闲聊/寒暄
- 正在讨论中还没确定方案
- 同一个任务的中间尝试（最终用的是最初方案）

5. 暂停/切换 (Pause/Switch)

输入：先停一下 / 我去忙别的 / 切换到 XX

动作：
1. 总结当前对话的结论
2. 更新当前项目的 STATUS.md
3. 更新 index.md：状态改为"已暂停"，记录暂停原因
4. 如果是切换，恢复目标项目
5. 回复用户："✅ 状态已保存。下次说'回到 [Name]'即可无缝接续。"

6. Session 结束收尾

当检测到以下信号时（用户说"我先走了"、"明天继续"、长时间无新消息、或心跳检测到上次对话已超过 2 小时）：

1. 回顾最近一轮对话的内容
2. 提取未完成的任务和关键决策
3. 更新当前项目的 STATUS.md
4. 写入当日记忆 memory/YYYY-MM-DD.md（一句话摘要 + 引用 STATUS.md）
5. 如果涉及新话题但未建项目 → 记录到 HEARTBEAT 待处理队列

7. 项目清理与归档 (Cleanup & Archive)

心跳期间定期检查：
- 超过 30 天未活跃 → 标记为"可能归档"，询问用户
- 已完成 → 状态改为"已完成"
- 已废弃 → 状态改为"已废弃"

归档操作：
1. 移动到 projects/_archive/{name}/
2. 保留 STATUS.md 作为历史记录
3. index.md 标记为"已归档"并移到底部

8. 🔄 Session 内周期检查（v2.4 核心新增）

这是什么？

当 project-manager skill 被激活（用户触发新建/恢复/保存等项目操作）时，在当前 session 里注册一个周期性检查任务。之后每隔一段时间自动扫描新对话，发现新话题就自动建项目或归档到已有项目。

为什么需要？

用户不会每次都主动说"记一下"。周期检查解决了"你不说就不记"的问题——一次激活，持续生效。

如何工作？

注册流程

skill 被激活时，执行以下操作：

1. 创建/更新 checkpoint 文件 memory/pm-checkpoint.json：

{
  "active": true,
  "sessionKey": "当前session的key或label",
  "lastCheckedMsgId": "当前最后一条消息的ID",
  "lastCheckTime": "2026-04-25T11:09:00+08:00",
  "intervalMinutes": 60,
  "activeProject": "当前关联的项目名（可选）",
  "expiresAt": "2026-04-26T00:00:00+08:00"
}

2. 创建一个 cron 任务，每 60 分钟执行一次：
   - 读取 pm-checkpoint.json 获取上次检查位置
   - 读取 checkpoint 之后新增的对话内容
   - 分析新内容：是否有新话题、新决策、新需求？
   - 对比 index.md：有关联 → 更新 STATUS.md；无关联 → 标记待确认
   - 更新 checkpoint 的 lastCheckedMsgId 和 lastCheckTime

检查内容分析规则

每次只读取 checkpoint 之后的新增对话，分析以下信号：

门槛判断

• 实质内容（有具体问题/需求/决策）→ 记录到 STATUS.md 或创建新项目
• 闲聊/寒暄 → 跳过
• 一句话话题 → 跳过

过期与清理

• checkpoint 文件设置过期时间（默认 24 小时）
• 过期后自动停止周期检查
• 用户说"不用检查了"时立即停止
• session 断开后下次激活时自动重新注册

Token 消耗控制

• 每次只读新增对话，不回顾全部历史
• checkpoint 用 message ID 定位，精确到单条消息
• 预计每次检查消耗 500-2000 token（60 分钟约 10-30 条新消息）

与日常记忆的关系

原则：
- 项目进度从 STATUS.md 读，经验教训沉淀到 MEMORY.md，两者不交叉。
- memory/YYYY-MM-DD.md 中的项目记录只写一句话摘要 + 引用 STATUS.md，不重复细节。

Git 关联（可选）

如果项目目录下有 .git 目录：
- STATUS.md 头部记录 Git: [最近 commit hash]
- 更新状态时自动执行 git log --oneline -1 获取最新 commit

严格约束

1. Memory 禁令：绝不要用 memory 工具或 MEMORY.md 记录项目进度。项目进度只存在于 STATUS.md。
2. 读取优先：回复项目相关问题前，必须先读取 STATUS.md。不要依赖上一轮对话的记忆。
3. 极简原则：STATUS.md 只记"结论"和"下一步"，不记过程流水账。
4. 模板降级：小任务用轻量模板，别搞过度工程化。
5. 模糊匹配：用户说"上次那个"、"接着来"时，主动推断对应项目；无法确定时展示最近项目让用户选。
6. 并发安全：写 STATUS.md 前先 read 最新内容，合并后再 write。
7. index.md 自愈：首次使用时如不存在自动创建；发现项目目录存在但 index 中没有时，自动补录。
8. 对话中即时记录：重要决策/需求/完成节点即时写入，不堆积到最后（第 4 节）。
9. Session 结束收尾：检测到对话结束时，必须做状态落盘（第 6 节）。
10. 新项目必须确认：创建新项目前必须向用户确认（第 2 节）。
11. 激活即注册：skill 被激活后必须注册 session 周期检查（第 8 节）。

V2.4 升级内容（2026-04-25）：新增 session 内周期自动检查机制（一次激活，持续扫描新对话）；checkpoint 增量读取（只读新增对话，控制 token 消耗）；穷举触发词场景（6 大类）；增强恢复旧项目时的兜底逻辑（STATUS.md 为空时从 memory/ 恢复）；索引必须含一句话概述