Openclaw Project Context Manager

---
name: project-context-manager
description: 用统一规则管理长期项目的发现、进入、退出、恢复与阶段性固化。
metadata: { "openclaw": { "emoji": "🗂️", "requires": { "bins": ["python3"] } } }
---

# Project Context Manager

当用户在一个共享主会话中同时推进**多个长期项目**，并希望可靠地做到以下事情时，使用这个 skill：

- 防止项目上下文与普通对话混在一起
- 在会话丢失、归档或中断后恢复项目状态
- 为项目建立统一的文件结构
- 通过文件化记录而不是聊天记忆来保存项目进度

这个 skill 是**项目无关的通用机制**，不得假设或写死任何具体项目。

## 重要边界

这个 skill 管理的是**项目上下文**，不是 OpenClaw 原生 UI 层面的多会话切换。

它不应假装把共享主会话变成一个真正隔离的原生项目会话。它提供的是一套基于文件的项目发现、进入、恢复、退出边界与阶段性固化工作流。

## 核心理念

不要依赖聊天记忆来管理长期项目。

应依赖：

1. **workspace 级项目系统规则文件**
2. **统一项目根目录**（每个项目一个文件夹）
3. **项目级恢复入口与结构化进度文件**
4. 明确的 **进入 / 退出 / 恢复 / 固化** 协议

## 这个 skill 管什么

这个 skill 定义一套标准工作流，用于：

- 在统一项目根目录下发现项目
- 当用户说“进入项目 / 恢复项目”时，让用户先确认目标项目
- 只有在用户确认后才进入对应项目
- 通过恢复入口、索引、决策、checkpoint 与记忆恢复项目上下文
- 退出项目后，防止普通聊天被写入项目记录
- 在关键节点把当前项目状态固化为可恢复记录

## 标准架构

### workspace 级规则层

一个 workspace 级规则文件（推荐文件名：`PROJECT_SYSTEM.md`）定义：

- 项目放在哪
- 如何发现项目
- 如何进入、退出和恢复项目
- 如何进行阶段性固化
- 项目工作与普通事务的边界规则

### 项目级结构层

每个项目应位于独立文件夹中，并至少包含：

- `00_恢复入口.md`
- `00_文档总索引与当前进度.md`
- `01_项目会话与恢复机制说明.md`
- `99_关键决策记录.md`
- `checkpoints/`
- `session-backups/`

## 当用户说“进入项目 / 恢复项目”时的要求

除非用户已经非常明确指出目标项目，否则不要猜测他要进入哪个项目。

正确流程应为：

1. 优先读取 workspace 级项目系统规则文件
2. 优先读取项目注册表（若存在）
3. 优先扫描已登记项目路径；若采用统一项目根目录模式，再扫描该根目录
4. 列出可识别项目
5. 若存在歧义，让用户选择
6. 用户确认后，再读取该项目的恢复入口并恢复上下文

补充原则：
- 不应只依赖默认目录猜测项目
- 不应假设所有项目都位于同一个固定目录
- 单个项目里的 `00_恢复入口.md` 只能解决“已知项目后的恢复”，不能替代“发现有哪些项目”的能力

## 当用户说“退出项目”时的要求

当用户明确退出项目后：

- 后续消息不再默认属于该项目
- 不应把普通事务自动写入项目恢复文件
- 若后续消息看起来像项目相关，应提醒用户并确认是否重新进入项目

## 项目恢复工作流

选定具体项目后，应使用该项目自己的文件恢复：

1. `00_恢复入口.md`
2. `00_文档总索引与当前进度.md`
3. `99_关键决策记录.md`
4. 由索引或恢复入口指向的当前断点文件
5. 最新相关 checkpoint 文件
6. 必要时读取最近相关 workspace memory

恢复后应至少还原：

- 当前项目主线
- 已完成内容
- 当前断点
- 最近新增的重要文件
- 关键决策
- 推荐下一步

## 项目固化工作流

用户可通过以下表达显式触发固化：

- 固化当前项目
- 更新恢复文件并保存当前断点
- 保存当前阶段进展

当用户明确下达固化指令时，应立即执行。

在重要节点，应主动提醒用户是否需要固化，例如：

- 完成关键文档后
- 当前断点明显变化后
- 新决策形成后
- 新增强相关文件后
- 进入新阶段时
- 会话可能暂停或中断前

固化保存的是**可恢复的有效上下文**，而不是默认保存全部原始聊天原文。

通常需要更新：

- 项目索引 / 当前进度文件
- 关键决策文件（若决策发生变化）
- 当日 workspace memory（如有需要）
- checkpoint 快照文件（推荐在关键阶段生成）

## 项目创建与接管机制

### 1. 已有项目目录时的接管

当用户明确说明以下任一情况时，应视为“已有项目目录待接管”：

- 已经建好了项目文件夹
- 这个目录就是新项目
- 以这个目录作为项目继续推进
- 帮我给这个目录补齐项目恢复结构

此时应：

1. 确认用户提供的项目路径
2. 检查该目录是否已有项目结构文件
3. 若缺失结构，则提示是否初始化标准项目结构
4. 若已有部分结构，则提示是否补齐并接管
5. 接管完成后，再将该目录纳入项目恢复与固化机制
6. 将该项目路径登记到独立的项目注册表中，而不是写死在 skill 本体里

### 2. 未建项目目录时的新项目初始化

当用户明确表示要开展一个长期项目，但尚未建立项目目录时，应：

1. 识别这是“长期项目启动”，而不是普通一次性任务
2. 提示用户是否需要建立标准项目目录与恢复结构
3. 若用户同意：
   - 让用户提供路径
   - 或使用统一项目根目录创建新项目文件夹
4. 初始化标准项目结构
5. 再进入该项目的恢复与管理流程

### 3. 仅想逻辑分开、不想立刻建目录时

当用户只想把对话逻辑上与其他事务分开，但尚未准备建立正式项目目录时：

1. 可以先按“项目方式”继续讨论
2. 但应提醒用户：当前只是逻辑分开；若希望后续稳定恢复，仍建议尽早建立项目目录与恢复结构
3. 在未正式建立项目目录前，不应假装该项目已经具备完整恢复能力

### 4. 项目目录确认与恢复前发现机制

为了避免会话中断后只能恢复“已知路径的单个项目”，当前版本增加如下要求：

1. **首次纳入项目管理时，应确认项目路径**
   - 若用户已给出路径，直接登记
   - 若用户未给出路径，可在合适时机提示补充

2. **项目路径不应写死在 `SKILL.md` 本体中**
   - skill 负责规则
   - 具体项目路径应登记在独立的项目注册表中
   - 当前版本可采用轻量注册表：`~/.openclaw/workspace/projects-registry.json`

3. **当用户说“恢复项目 / 进入项目 / 回到项目”时**
   - 若当前没有明确激活的项目上下文，应先读取项目注册表
   - 当前版本可优先读取：`~/.openclaw/workspace/projects-registry.json`
   - 再扫描所有已登记项目路径
   - 检查路径是否存在、恢复文件是否完整
   - 列出当前可识别项目
   - 让用户选择进入哪个项目
   - 用户确认后，再读取对应项目的 `00_恢复入口.md`

4. **目录确认应采用条件触发，不高频打扰**
   - 首次纳入项目时可确认目录
   - 恢复失败、路径失效、无法形成候选项目列表时可提示补目录
   - 路径已确认有效时，不应反复提醒

5. **注册表只记录已确认项目**
   - 项目注册表用于记录“已被用户确认纳入 skill 管理的项目”
   - 不应把 assistant 仅凭猜测发现的目录写入注册表
   - 不应把普通聊天中偶然提到的话题自动写入注册表

6. **单次提醒原则**
   - 对同一项目的目录确认问题，默认只提醒一次
   - 只有在用户再次要求恢复、路径再次失效、或目录状态发生变化时，才适合再次提醒

## 提示触发规则

### 强触发：应主动进入项目创建 / 接管流程

当用户明确表达以下意图时，应主动触发项目创建或接管提示：

- 开始一个新项目
- 这是一个长期项目
- 以后要持续推进这个事情
- 给这个任务建立项目管理
- 这个项目需要后续继续跟进
- 我已经建好了项目目录 / 文件夹

### 中触发：可提示一次

当用户没有明确说“新项目”，但已经表现出明显的长期项目特征时，可以提示一次是否需要进入项目机制。

长期项目特征可包括：
- 需要分阶段推进
- 需要持续写文档
- 需要记录断点
- 需要 checkpoint / 恢复
- 需要后续多轮协作
- 需要在普通事务之外单独管理

### 弱触发：不提示

以下情况不应主动提示建立项目：

- 一次性问答
- 临时报错排查
- 短任务脚本
- 单次资料查询
- 普通闲聊
- 用户没有表现出长期推进或恢复需求

即：新话题 ≠ 新项目。

## 反打扰规则

- 不应因每个新话题都建议建项目
- 同一主题内，默认只提醒一次
- 如果用户已经拒绝，则不应在短时间内重复催促
- 只有再次出现明确的长期项目信号时，才适合重新提醒
- assistant 不应擅自创建项目目录，除非用户明确同意

## 初始化一个新项目结构

本 skill 提供一个初始化脚本，用于生成标准项目结构。

使用方式：

```bash
python3 {baseDir}/scripts/init_project.py '<JSON>'
```

示例：

```bash
python3 {baseDir}/scripts/init_project.py '{
  "projects_root": "/Users/example/Desktop/项目库",
  "project_name": "示例项目",
  "create_workspace_rule": true
}'
```

## 脚本输入参数

```json
{
  "projects_root": "string, required",
  "project_name": "string, required",
  "create_workspace_rule": true,
  "workspace_root": "string, optional, defaults to ~/.openclaw/workspace",
  "project_rule_filename": "string, optional, defaults to PROJECT_SYSTEM.md"
}
```

## 初始化会创建什么

- workspace 级 `PROJECT_SYSTEM.md`（如果请求创建且当前不存在）
- 项目根目录下的项目文件夹
- 该项目的标准恢复与管理文件
- `checkpoints/` 与 `session-backups/` 目录

## 边界规则

- 这个 skill 管理的是**项目上下文**，不是原生 UI 会话切换
- 不应假装 WebChat 或 main 会话已经变成真正的多会话隔离环境
- 不应假设某个具体项目
- 用户退出项目后，不应把普通聊天写入项目记录
- 恢复时不能只依赖固定历史文件名，必须先扫描项目目录

## 第一版范围

第一版重点支持：

- 标准化的项目发现
- 项目进入 / 退出 / 恢复 / 固化规则
- 新项目标准模板生成

第一版不提供：

- OpenClaw 原生多会话 UI 支持
- 隐式后台项目自动切换
- 通道级 thread binding