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