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

要解决的核心问题 / Problems Solved#

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

Agents forget. Every day they wake up fresh. If conversations aren't recorded in time, everything is lost by tomorrow.

本系统的目标：

• 最小化信息遗漏，最大化可恢复性，不增加对话负担
• 以项目经理角度管理对话，而非日记——每个项目独立记录，独立保存所有信息和细节
• 随时回到任意项目，不携带其他项目的污染信息和噪音
• 结构化锚点：任何信息按项目精确召回，无需翻遍历史
• 大幅降低 Memory 负载，节省 Token 消耗（STATUS.md 远小于完整对话历史）
• 推荐完整对话保存在 MemPalace 中

Goals:

• Minimize information loss, maximize recoverability, without adding conversation burden
• Manage conversations like a project manager — each project independently recorded with all details preserved
• Switch between projects freely without carrying noise or pollution from other projects
• Structured anchors: retrieve any information by project, no need to search through entire history
• Significantly reduce Memory footprint — STATUS.md is far smaller than full conversation history
• Full conversations recommended in MemPalace

架构原则#

层级文件职责即时记录projects/{name}/STATUS.md对话中即时写入重要决策/需求/完成节点按需状态同步memory/pm-checkpoint.jsonsession 内检查新对话，发现新话题智能恢复HEARTBEAT.md 第 5 项全局检查，作为最后一道防线全局记忆MEMORY.md / memory/*.md用户偏好、跨项目经验（不含项目进度）

与 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 状态同步（opt-in）：用户显式触发后才注册定期状态同步，不自动激活。
5. 分级管理：轻重有别，杀鸡不用牛刀。
6. 意图优先（显式触发）：根据对话上下文推断意图，但所有操作需用户确认后执行。
7. 写入安全：写入前必须先 read 最新内容，合并后再 write。⚠️ TOCTOU 限制：读-写之间内容可能被其他 session 修改，这不是真正的写入安全，只是降低冲突概率。

目录结构规范#

text

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

📇 项目索引： projects/index.md#

markdown

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

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

维护规则：

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

---

分级 STATUS.md 模板#

⚠️ 以下为简化示意，实际使用时应先从 skills/project-manager/templates/ 目录读取对应完整模板文件。

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

markdown

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

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

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

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

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

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

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

markdown

# 项目名称：[Name]
> 最后更新：[Date] | PM: v2.5

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

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

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

模板来源与选择规则#

模板文件位置： skills/project-manager/templates/ 目录下的 STATUS-A.md / STATUS-B.md（不是内联伪代码）。

选择规则：

场景模板3天以上的多阶段项目A 完整模板单任务（如"帮我把这个接口重构一下"）B 轻量模板调研/分析类临时任务B 轻量模板需要多人协作或长期维护A 完整模板不确定先用 B，后续发现需要再升级到 A

---

操作工作流 (Workflow)#

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

穷举触发场景：

显式命令类（直接触发）

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

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

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

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

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

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

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

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

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

识别优先级：

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

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

触发条件：

1. 显式触发：用户明确说"新建项目"/"帮我建一个"/"一个话题"/"记录一下"

2. 自动检测触发（P1 新增）：

   • 连续 3 轮对话收敛到同一主题
   • 内容涉及具体问题/需求/决策讨论（非闲聊）
   • 检查 index.md 无相关项目
   • 主动询问用户："这个话题我们聊了 3 轮了，要不要建个项目记录一下？"

门槛判断（避免过度工程）：

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

动作：

1. 先扫描 index.md — 检查是否有相关项目可以合并或关联
2. 有关联 → 合并到已有项目，告知用户"这个话题我已归入 XX 项目"
3. 无关联 → 继续以下步骤：
   1. 先向用户确认："这是个新话题，我建个项目记录一下？概述是「{一句话概述}」"
   2. 用户同意后再创建
   3. 目录名用 kebab-case： cmra-geo
   4. 创建目录 workspace/projects/{name}/
   5. 先从 skills/project-manager/templates/ 目录读取对应模板，根据复杂度选择 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 内状态同步（opt-in，需显式激活）#

这是什么？#

当用户显式请求（如"开启状态同步"、"自动检查新对话"）时，在当前 session 里注册状态同步任务。 不会自动激活。

为什么需要？#

用户不会每次都主动说"记一下"。状态同步解决了"你不说就不记"的问题——但必须由用户显式开启。

如何工作？#

注册流程

用户显式请求时，执行以下操作：

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

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"
}

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

检查内容分析规则

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

信号类型示例动作新需求"我们需要增加XX功能"更新 STATUS.md 待办新决策"用 Redis 不用 Memcached"更新 STATUS.md 决策完成节点"这个模块搞定了"更新 STATUS.md 进度新话题突然讨论完全不同的话题（如从技术跳到市场调研）扫描 index.md 判断是否建项目暂停信号"先停一下"、"明天继续"触发 Session 结束收尾（第 6 节）

门槛判断

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

过期与清理

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

Token 消耗控制

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

---

9. 📝 项目对话日志（v2.5 新增，opt-in）#

为什么需要#

项目相关的讨论分散在历史会话中，想回顾时找不到。对话日志把项目相关的关键讨论打包成独立文件，随时可以回顾。

触发时机（需用户显式开启）#

• 项目新建时：询问用户"是否开启对话日志？"，用户同意后初始化日志条目
• 每次更新 STATUS.md 时：如对话日志已开启，自动追加本次会话的关键内容
• 项目归档时：如对话日志已开启，打包整个项目的完整对话历史

存储结构#

两层存储：摘要索引存本地文件，完整对话推荐存 MemPalace。

本地摘要索引

写入 memory/project_log_{project_name}.md：

markdown

# 📝 项目对话日志：{project_name}
> 归档时间：{YYYY-MM-DD HH:MM}
> 关联项目：projects/{project_name}/STATUS.md

## 项目概况
[核心目标一句话摘要]

## 关键决策时间线
| 时间 | 决策 | 上下文 |
|------|------|--------|
| YYYY-MM-DD | 决定采用方案A而不是B | 性能优先级高于成本 |

## 踩过的坑
[记录所有尝试过但失败的方案、原因、教训]

## 历史会话快照
> session_key: abc123 | 时间: YYYY-MM-DD
[本次会话的关键讨论摘要，不超过200字]

---
> session_key: def456 | 时间: YYYY-MM-DD
[本次会话的关键讨论摘要]

完整对话归档（推荐）

推荐：将完整对话原文保存到 MemPalace（wing={project_name}, room=conversations），本地只保留摘要索引。MemPalace 支持语义搜索，可跨项目检索历史讨论。

归档策略#

• 只记结论，不记流水：超过200字的讨论压缩成摘要
• 决策必记：所有「就这么定了」「就用方案A」的时刻必须记录
• 踩坑必记：试过但失败的方案，防止重蹈覆辙
• 自动关联：session_key 链接到完整会话，方便回溯

检索方式#

• 按文件名： memory/project_log_{name}.md
• 按关键词搜索：记忆文件的内容可被全局搜索命中

---

10. 📅 甘特图自动生成（v2.5 新增）#

数据流关系#

唯一数据源 = STATUS.md 中的 ## 📅 Timeline YAML 块

输出文件 = projects/{name}/GANTT.md

更新里程碑时：先改 STATUS.md Timeline → 再重新渲染 GANTT.md。不要直接编辑 GANTT.md，否则下次渲染会被覆盖。

触发方式#

• 显式命令："生成甘特图"、"看看时间线"、"项目进度图"
• 建议触发：每次更新 STATUS.md 的 milestones 后，应该重新渲染 Gantt

渲染算法（自然语言描述，按此逻辑执行）#

第一步：读取项目时间配置 遍历所有项目目录，逐个读取 STATUS.md 中的 timeline 配置，提取每个项目的：

• 开始日期 start_date
• 预计完成日期 estimated_end
• 所有里程碑列表（含名称、日期、状态） 统计已完成里程碑数和总里程碑数，计算进度百分比 = 已完成 / 总数 × 100

第二步：渲染 ASCII 甘特图 输出格式如下：

text

📅 项目甘特图 | {当前年} 年 {当前月} 月
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

{项目名称}  [{进度条}] {进度百分比}%
  ├─ {YYYY-MM-DD} ✅ {已完成的里程碑名称}
  ├─ {YYYY-MM-DD} 🔄 {进行中的里程碑名称}
  └─ {YYYY-MM-DD} ⏳ {待完成的里程碑名称}

进度条渲染规则：

• 总长度固定 20 个字符
• █ 表示已完成部分，░ 表示未完成部分
• 0% 进度：20 个 ░，100% 进度：20 个 █
• 50% 进度：10 个 █ + 10 个 ░

第三步：资源冲突检测

• 扫描所有里程碑的日期，如果同一天有 ≥3 个项目有里程碑，显示 ⚠️ 资源冲突预警
• 统计方式：把所有里程碑的日期去重计数，超过阈值即触发
• ⚙️ 阈值说明：默认值 3，对个人 agent 可能敏感，后续支持通过配置调整

第四步：延期预警计算

• 🔴 已延期：当前日期 > estimated_end，且进度 < 100%
• 🟡 延期风险：当前日期距 estimated_end < 3 天，且进度 < 70%

第五步：输出到项目目录

• 自动创建或更新每个项目的 projects/{name}/GANTT.md
• 同时在 projects/index.md 顶部生成全局汇总甘特图

---

11. ⚠️ 项目风险自动识别（v2.5 新增，opt-in）#

触发方式#

• 显式命令："风险扫描"、"看看有什么风险"、"检查项目状态"
• 定时检查：用户显式请求后才启用（如"每天检查一次"）

风险规则引擎（严格按此逻辑执行）#

风险项触发条件等级所需字段静默风险最后更新日期距今 >14 天🔴 高last_updated无里程碑风险项目启动 >7 天，但无任何里程碑记录🔴 高start_date, milestones单点依赖风险有 >3 个项目声明依赖同一个 skill 或外部项目🟡 中dependencies估时不准风险连续 2 个已完成项目的估时偏差 >50%🟡 中estimated_hours, actual_hours范围蔓延风险里程碑总数比最初增加 >50% 后又新增🟡 中milestones依赖循环风险A 依赖 B 且 B 依赖 A（DAG 环路检测）🔴 高dependencies延期风险当前距 estimated_end <3 天，且进度 <70%🟡 中estimated_end, milestones已延期当前日期 > estimated_end 且进度 <100%🔴 高estimated_end, milestones

特殊规则说明#

• 估时不准风险：需要从 projects/ 目录下所有已完成项目（actual_end 非 null）中读取 estimated_hours 和 actual_hours 字段计算偏差。项目完成时 必须 回填 actual_hours，否则此规则无法触发。

扫描算法（自然语言描述，按此逻辑执行）#

第一步：全量扫描所有项目目录 遍历 projects/ 下每个项目，读取 STATUS.md，提取以下字段：timeline、dependencies、last_updated、estimated_hours、actual_hours。

第二步：逐个项目检查风险 按上述8项规则逐一检查，判断每个项目的风险项。

第三步：按风险等级分组输出 输出格式如下：

text

⚠️  项目风险扫描报告 | {YYYY-MM-DD}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔴 高风险 ({总数} 项)
──────────────────────────────────────────────────
• [{项目名}]  静默风险 - 最后更新 {天数} 天前
  建议: ping 一下确认项目状态，或归档

...

🟡 中风险 ({总数} 项)
──────────────────────────────────────────────────
• [{项目名}]  单点依赖 - 依赖 {skill} 的项目共 {n} 个
  建议: 评估是否需要技术储备方案

🟢 健康 ({总数} 项)
──────────────────────────────────────────────────
• 按时更新 + 有里程碑 + 无单点依赖 + 无延期

第四步：自动写入风险日志

• 所有识别出的风险自动写入对应项目 STATUS.md 的 ⚠️ Risk Log 章节
• 高风险项目同时在 index.md 标记 🔴 前缀

风险 Mitigation 建议#

• 静默风险：归档，或设一个唤醒日期
• 无里程碑风险：花 5 分钟拆 2-3 个阶段性节点
• 单点依赖风险：准备替代方案，或做技术储备
• 估时不准风险：下一个项目乘 1.5 倍安全系数

---

与日常记忆的关系#

信息类型存放位置示例 / 说明用户偏好MEMORY.md"不喜欢废话，只要结论"跨项目经验MEMORY.md"上次用 X 方案踩了 Y 坑"每日工作流水memory/YYYY-MM-DD.md"今天推进了 CMRA 认证模块，详情见 STATUS.md"项目进度projects/{name}/STATUS.md"CMRA：认证模块完成，开始做权限"甘特图数据projects/{name}/GANTT.mdSTATUS.md Timeline YAML 的渲染输出项目对话日志memory/project_log_{name}.md关键决策和踩坑记录工时追踪projects/{name}/STATUS.md风险引擎「估时不准」规则依赖此数据技术细节projects/{name}/status/测试日志、设计草稿检查点memory/pm-checkpoint.json状态同步的位置标记

原则：

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

---

Git 关联（可选）#

如果 git rev-parse --is-inside-work-tree 在项目目录下执行成功（返回 0）：

• 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。⚠️ TOCTOU 限制：读-写之间内容可能被其他 session 修改，这不是真正的写入安全，只是降低冲突概率。
7. index.md 按需创建：首次使用时如不存在，询问用户是否创建；发现项目目录存在但 index 中没有时，询问用户是否补录。
8. 对话中即时记录（需确认）：重要决策/需求/完成节点提议写入，但必须获得用户确认后才执行（第 4 节）。
9. Session 结束收尾：检测到对话结束时，提议做状态落盘，用户确认后执行（第 6 节）。
10. 新项目必须确认：创建新项目前必须向用户确认（第 2 节）。
11. 状态同步 opt-in：Session 状态同步需用户显式开启（第 8 节）。
12. 风险扫描 opt-in：风险引擎需用户显式请求（第 11 节）。
13. 对话日志 opt-in：对话日志需用户显式开启（第 9 节）。

---

触发词#

/project | 新建项目 | 项目列表 | 记录一下 | 回到项目 | 继续项目 | 上次那个 | 甘特图 | 时间线 | 进度图

---

📋 版本历史：详见 CHANGELOG.md

🔒 安全说明：详见 SECURITY.md