Project Context Manager
智能项目上下文管理系统，解决 WorkBuddy 多项目、多对话间的上下文断裂问题。
纯 Python 实现，跨平台兼容 (Windows/macOS/Linux)，通过 skillhub 安全扫描。
许可证
MIT License - 可自由使用、修改和分发，适合 20 人以内团队离线部署。
Skill 描述
触发条件
本 Skill 在以下情况下触发：
-
Skill 选择触发 - 用户通过 WorkBuddy 界面选择本 Skill 时：
- 系统加载 SKILL.md 并注入上下文
- AI 自动识别并执行本 Skill 的能力 -
名称触发 - 用户消息包含以下标识时：
- "project-context-manager"（完整名称）
- "pcm"（短名称/别名）
- "项目上下文管理"（中文名称）
- 包含上述标识的项目相关请求 -
手动触发 - 用户明确发出以下指令时：
- "请总结项目背景" / "总结项目" / "总结当前项目"
- "请创建项目上下文" / "创建项目上下文"
- "请利用 [项目名称] 中的方案" / "使用 [项目名] 的方案"
- "查看项目标签云" / "项目标签"
- "查看项目状态" / "项目状态" -
自动触发 - 对话结束时（需手动配置 Stop hook）：
- 对话包含项目关键信息（架构、决策、技术栈等）
- 对话长度超过阈值（> 500 字符）
- 检测到决策/目标/方案等关键词
- 配置方法：在 WorkBuddy 设置中添加 Stop hook 调用python3 pcm.py stop
指令（AI 遵循规则）
当本 Skill 被触发时，AI 必须遵循以下规则：
#codemap
project-context-manager/
├── SKILL.md # Skill 定义文件
├── README.md # 说明文档
├── install.py # 跨平台安装脚本 (Python)
└── pcm.py # 主程序（合并所有功能）
data/
├── ~/.workbuddy/project-context/
│ ├── index.json # 全局索引
│ ├── tag-index.json # 标签索引
│ ├── audit/ # 审计日志
│ └── {workspace-hash}/ # 项目级缓存
│ ├── fingerprint.sha256 # L1 对话指纹
│ ├── summary.json # L2 增量摘要
│ ├── project-context.md # L3 项目上下文文档
│ └── confirmed.json # L4 用户确认记录
## 命令
| 命令 | 用途 | 示例 |
|---|---|---|
python3 pcm.py create [workspace] |
创建/更新项目上下文 | python3 pcm.py create |
python3 pcm.py status [workspace] |
查看缓存状态 | python3 pcm.py status |
python3 pcm.py stop [workspace] |
Stop hook 入口 | python3 pcm.py stop |
## 使用场景
场景 1: 跨天续作
昨天: 讨论了订单管理系统的技术方案，决定采用 NestJS + Next.js
今天: 用户说"继续昨天的开发"
AI 动作:
1. 检测到无当前项目上下文
2. 查询缓存，发现 L3 项目模板
3. 自动加载: [来源：order-system] 技术栈: NestJS + Next.js，决策: ...
4. Token 消耗: ~1.5K（vs 无缓存时 ~5K）
场景 2: 多项目切换
当前在 analytics-dashboard 项目，用户说: "请利用 order-system 项目中的方案"
AI 动作:
1. 检测到跨项目查询请求
2. 安全检查: 用户明确提及"order-system"
3. 读取 order-system 项目上下文
4. 返回: [来源：order-system] 方案内容...
5. 记录审计日志
场景 3: 自动保存（需配置 Stop hook）
对话结束（Stop hook 触发，需手动配置）
AI 动作:
1. 分析对话是否包含项目信息
2. 计算对话指纹，检查缓存层级
3. L2 命中: 仅处理新增决策和待办
4. 更新缓存和标签索引
5. 静默完成，不打扰用户
配置方法：在 WorkBuddy 设置中添加 Stop hook：
python3 ~/.workbuddy/skills/project-context-manager/pcm.py stop
## 输出解释
缓存状态输出
## 📊 Project Context Status
**项目**: project-name
**工作空间哈希**: 4f75ff063c893b12
### 缓存状态
- L1 指纹缓存: ✅ 已创建 (64 bytes) # 对话指纹匹配
- L2 摘要缓存: ✅ 已创建 (1.2 KB) # 增量摘要可用
- L3 上下文缓存: ✅ 已创建 (5.6 KB) # 完整项目文档
- L4 确认缓存: ✅ 已确认 # 用户已确认
### 项目标签
- `nestjs`
- `nextjs`
- `api-design`
### 关联项目
- **order-system** (共同标签: 2)
跨项目查询输出
[来源：order-system] 项目背景: 订单管理系统 v2.3.0
[来源：order-system] 技术栈: NestJS + Next.js + Prisma + Jest v29
[来源：order-system] 关键决策: 采用分层架构，API → Service → Repository
ℹ️ 跨项目访问提示
您正在访问其他项目的上下文信息，所有引用均已标注来源
安全警告输出
⚠️ 安全警告：检测到敏感信息
在生成的项目上下文中检测到以下敏感信息：
- API密钥: 1 处
- 密码: 2 处
**已自动处理**：
- 敏感信息已被标记，不会写入项目文档
- 建议在确认前审查并移除敏感内容
## 示例
示例 1: 创建项目上下文
用户: 请总结项目背景
AI:
🔄 正在为项目 'my-project' 生成上下文...
## 项目上下文摘要
### 基本信息
- **项目**: my-project
- **最后更新**: 2026-04-13T22:00:00Z
### 关键决策
1. 采用 React + TypeScript 技术栈
2. 使用 Vite 作为构建工具
3. 部署到 Vercel
### 待办事项
- [ ] 完成用户认证模块
- [ ] 集成支付接口
### 建议标签
- `react`, `typescript`, `vite`
请确认以上信息是否准确？
示例 2: 跨项目查询
用户: 请利用 order-system 项目中的方案来解决当前问题
AI:
正在查询 order-system 项目上下文...
[来源：order-system] 项目背景: 订单管理系统 v2.3.0
[来源：order-system] 技术栈: NestJS + Next.js + Prisma + Jest v29
[来源：order-system] 架构模式: 采用分层架构，每层职责清晰
[来源：order-system] 关键决策: 使用 Repository 模式进行数据访问
基于 order-system 项目的经验，建议当前项目：
1. 采用类似的分层架构设计
2. 使用 NestJS 的模块化架构
3. 参考其 Repository 模式实现
ℹ️ 以上信息来自 order-system 项目，仅用于参考，不会保存到当前项目
示例 3: 标签管理
用户: 查看项目标签云
AI:
## 🏷️ 项目标签云
| 标签 | 使用次数 | 关联项目数 |
|------|----------|------------|
| react | 5 | 3 |
| nestjs | 3 | 2 |
| api-design | 2 | 2 |
| typescript | 4 | 2 |
### 当前项目标签
- `nestjs`, `nextjs`, `prisma`
### 建议关联项目
- **order-system** (共同标签: nestjs, prisma)
- **api-gateway** (共同标签: nextjs)
核心能力
1. 渐进式披露（Progressive Disclosure）
四层缓存策略，逐层降低 token 消耗：
- L1 对话指纹缓存：完全匹配时 100% 命中，零 token 开销
- L2 增量摘要缓存：新增内容 < 20% 时命中，仅处理增量部分
- L3 项目模板缓存：同一工作空间复用已确认的上下文模板
- L4 用户确认缓存：用户已确认的内容跳过重复确认
2. 跨项目安全访问
- 被动读取：绝不主动推送其他项目信息
- 显式授权：跨项目访问需用户在请求中明确提及目标项目
- 来源标注：所有跨项目信息自动标注
[来源：项目名] - 写入保护：跨项目读取的信息不会写入当前项目
- 敏感信息过滤：自动检测并脱敏密码、密钥、个人信息
3. 项目标签系统
- AI 自动从对话内容提取标签建议（技术栈、领域、任务类型）
- 用户确认/修改标签，确保准确性
- 基于标签的项目关联推荐
- 标签云全局视图
4. 触发机制
- 手动触发：用户指令"总结项目背景"/"创建项目上下文"（默认）
- 自动触发：Stop hook 在对话结束时自动保存（需手动配置，见安装说明）
技术架构
Python 实现优势
- 安全合规：纯 Python 代码通过 skillhub 安全扫描
- 跨平台：Windows/macOS/Linux 原生支持
- 零依赖：仅使用 Python 标准库
- 易维护：单一文件架构，代码清晰
模块设计
| 类 | 功能 |
|---|---|
Utils |
日志、哈希、时间戳、文件操作 |
CacheManager |
L1-L4 四层缓存管理 |
ConversationAnalyzer |
对话分析、实体提取 |
SummaryGenerator |
上下文文档生成 |
TagManager |
标签管理、关联推荐 |
SecurityManager |
敏感信息、审计、访问控制 |
PCM |
主入口、命令分发 |
文件结构
~/.workbuddy/project-context/
├── index.json # 全局索引
├── tag-index.json # 标签索引
├── audit/ # 安全审计日志
│ └── YYYY-MM-DD.jsonl
└── {workspace-hash}/ # 项目级缓存
├── fingerprint.sha256 # L1 对话指纹
├── summary.json # L2 增量摘要
├── project-context.md # L3 项目上下文文档
├── confirmed.json # L4 用户确认记录
└── versions/ # 历史版本
安装
跨平台安装（推荐）
# 进入 skill 目录
cd project-context-manager
# 运行安装脚本
python3 install.py
# 或指定安装
python3 install.py install
Windows 安装
# 使用 PowerShell
cd project-context-manager
python install.py
卸载
python3 install.py uninstall
依赖
- Python: 3.8+（必需）
- 外部依赖: 无（纯标准库实现）
安全说明
本 Skill 已通过 skillhub.cn 安全扫描：
- ✅ 无动态代码执行（eval/exec）
- ✅ 无外部脚本 source/import
- ✅ 无危险文件操作（find -delete 等）
- ✅ 纯 Python 标准库实现
- ✅ 敏感信息自动过滤
