你是否有这些困扰？
场景 1: 多项目并行开发的混乱
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
问题：
• 同时维护 3-5 个项目
• 切换项目时忘记上次做到哪
• 不记得当前在哪个 Git 分支
• 需要花 2-3 分钟回忆上下文
• 每个项目都要 "热身" 才能进入状态
场景 2: 项目状态无法追踪
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
问题：
• 哪些项目已经 2 周没碰了？
• 这个想法是在哪个项目里产生的？
• 上次实验的结果怎么样了？
• 想回顾某个想法，但记不清细节
• 项目之间的知识无法沉淀
场景 3: 工作流碎片化
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
问题：
• 工作内容散落在多个地方
• 没有统一的上下文管理
• 无法快速切换项目
• 项目之间的知识复用困难
❌ 现状（使用 Context Manager 前）
切换项目时：
cd ~/workspace/project-1
git branch (想看分支) → develop
git log -1 (想看最近改动) → commit message...
cat README.md (想看项目目标) → 翻找...
ls -la | head (想看最近修改) → ...
💰 时间成本: 2-5 分钟
😞 摩擦成本: 高（每次都要"热身"）
❌ 现状
你在 tangshi 项目工作时产生了一个很好的想法，
但 3 周后切换到 podcast-app，想法消失了。
💡 想法成本: 0 (因为没记录)
💡 想法价值: ??? (永远丢失了)
❌ 现状
项目总数: 8 个
进行中: ??? (不记得了)
暂停中: ??? (可能有好几个)
已完成: ???
废弃: ??? (可能不知道)
无法整体把握所有项目状态。
Context Manager - 让你的大脑专注于创造，而不是记忆
✅ 使用 Context Manager 后
切换到项目：
ctx switch project-1
→ 立即看到：
• 当前分支: develop
• 上次焦点: "实现音频同步"
• 会话数: #5
• 最近修改: "2024-01-27"
💰 时间成本: 5 秒
✅ 摩擦成本: 零（无需"热身"）
1. 项目上下文存储结构
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
.claude/context.md
├── YAML Frontmatter (机器可读)
│ ├── project: context-manager-skill
│ ├── created: 2026-02-03
│ ├── last_session: 2026-02-04
│ ├── session_count: 12
│ ├── status: active
│ ├── category: 产品
│ └── branch: main
│
├── Markdown 内容 (人类可读)
│ ├── # 当前焦点
│ ├── # 下一步计划
│ ├── # 项目简介
│ ├── # 技术栈
│ ├── ## 待办事项
│ └── ## 会话记录
│
└── 💡 设计理念: 机器可读 + 人类可读双优
2. 自动追踪机制
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ctx update current_focus "实现新功能"
│
├── 📅 更新 last_session (当前时间)
├── 🔢 自动增加 session_count (11 → 12)
├── 📝 保留完整会话历史
└── ✨ 用户无需手动维护任何元数据
3. 快速切换机制
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ctx switch podcast-app
│
├── 🔍 查找 ~/workspace/podcast-app/.claude/context.md
├── 📊 解析 YAML + Markdown 内容
├── 🎨 渲染状态摘要 (ASCII art)
└── 🚀 cd ~/workspace/podcast-app
1. 双格式解析器 (scripts/context_manager.py:71-179)
def parse_context(content: str) -> dict:
"""
智能识别 v1/v2 格式并统一解析
时间复杂度: O(n) 其中 n = 文本行数
空间复杂度: O(m) 其中 m = 字段数量
"""
result = initialize_result_dict()
lines = content.split("\n")
# 格式版本检测 (启发式算法)
has_v2_markers = check_fields(content, ["created", "status", "category"])
has_v1_markers = check_fields(content, ["project_type", "session_count"])
if has_v2_markers:
result["format_version"] = "v2"
elif has_v1_markers:
result["format_version"] = "v1"
else:
result["format_version"] = "unknown"
# 三层解析管道
for line in lines:
parse_yaml_frontmatter(line, result) # Layer 1: 结构化数据
parse_todos(line, result) # Layer 2: 待办列表
parse_sessions(line, result) # Layer 3: 会话历史
return result2. 自动增量机制
def cmd_update(args):
"""
更新字段时自动维护元数据
关键设计:
- last_session: 每次更新时自动刷新
- session_count: 单调递增，反映项目活跃度
- history: 追加式记录，保留完整历史
"""
context = parse_context(read_file())
# 自动维护元数据
context["last_session"] = datetime.now().strftime("%Y-%m-%d")
context["session_count"] += 1 # 自动递增
# 追加会话记录
session = {
"date": context["last_session"],
"count": context["session_count"],
"focus": context["current_focus"]
}
context["sessions"].append(session)
write_file(serialize_context(context))关键设计决策：
- ✅ 向后兼容: v1/v2 混合格式自动识别
- ✅ 用户透明: 格式细节对用户完全隐藏
- ✅ 渐进式迁移: 不强制升级，自然过渡
- ✅ 数据完整性: YAML + Markdown 双重保障
"工具应该适应用户，而不是要求用户适应工具"
Context Manager 遵循以下设计哲学：
- 简洁性优先 - 10 分钟学会，终身受用
- 自动化至上 - 减少认知负荷，让工具替你记忆
- 渐进式增强 - 从基础功能开始，按需使用高级功能
- 原生集成 - 与现有工具 (Git, Claude Code) 无缝协同
| 设计维度 | 决策 | 替代方案 | 理由 |
|---|---|---|---|
| 数据格式 | Markdown + YAML frontmatter | JSON, SQLite, 纯文本 | 人类可读 + 机器可解析双优 |
| 文件位置 | .claude/context.md |
根目录 context.md |
不污染项目，与 Claude 生态一致 |
| 状态追踪 | 自动化 (session_count) | 完全手动 | 零认知负荷，自动累积价值 |
| 切换方式 | CLI (ctx switch) |
GUI 应用 | 极速启动 (5 秒 vs 30 秒+) |
| 依赖管理 | 零外部依赖 | 需要数据库/框架 | 降低使用门槛，离线可用 |
| 迁移策略 | 向后兼容 (v1/v2) | 强制升级 | 渐进式过渡，不中断工作流 |
问题: 数据应该多结构化？
选项 A: 完全结构化 (JSON/SQLite)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 优点:
• 解析简单，性能优秀
• 类型安全，减少错误
• 易于实现查询和过滤
❌ 缺点:
• 人类不可读 (需要工具查看)
• 难以用文本编辑器快速修改
• 学习成本高 (需要了解数据模型)
选项 B: 完全自由 (纯文本 Markdown)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 优点:
• 极致灵活，想怎么写就怎么写
• 人类可读性最佳
❌ 缺点:
• 解析困难，容易出错
• 无法自动化处理
• 难以实现状态查询
选项 C: 半结构化 (YAML frontmatter + Markdown) ⭐
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 优点:
• 结构化部分 (YAML) 可解析 → 自动化
• 自由文本部分 (MD) 灵活 → 扩展性
• 人类可读性优先 → 可维护性
❌ 缺点:
• 解析复杂度中等
• 需要遵守基本格式约定
决策: 选择 C
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
理由:
1. 工具定位是"上下文管理"，不是"数据库"
2. 用户需要能够直接编辑和理解数据
3. 灵活性 > 结构化 (笔记工具特性)
实现:
parse_context() 自动识别格式，容错性强
问题: 应该自动化多少？
选项 A: 完全手动
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ 问题:
• 用户需要记住更新 session_count
• 容易忘记更新 last_session
• 认知负荷高
选项 B: 完全自动 (后台持续监控) ⭐⭐
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ 问题:
• 需要常驻进程 (资源占用)
• 隐私担忧 (持续监控文件系统)
• 实现复杂度高
选项 C: 事件驱动自动 (ctx update 时触发) ⭐
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 优点:
• 零常驻进程
• 自动维护元数据 (session_count, last_session)
• 用户只需更新当前焦点
❌ 缺点:
• 需要手动触发更新
• 失去完全控制权
决策: 选择 C
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
理由:
1. 自动化 > 控制 (认知减负)
2. 事件驱动 > 持续监控 (资源效率)
3. 符合 UNIX 哲学 (做好一件事)
实现:
cmd_update() 自动增加 session_count，更新 last_session
问题: 配置文件应该放在哪里？
选项 A: 项目根目录 (context.md)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 优点:
• 显性可见，容易发现
❌ 缺点:
• 污染项目根目录
• 与其他文件混在一起
• 容易误操作
选项 B: 隐藏目录 (.claude/context.md) ⭐
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 优点:
• 不污染根目录 (ls 时清洁)
• 符合工具约定 (.git/, .vscode/)
• 降低误操作风险
• 与 Claude 生态一致
❌ 缺点:
• 新手可能不知道存在
• 需要工具辅助查看
决策: 选择 B
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
理由:
1. 工具性 > 可见性 (与 Claude 生态一致)
2. 专业性 > 易发现性 (面向开发者)
3. ctx ls 命令解决可见性问题
缓解措施:
• ctx init 自动创建目录
• ctx ls 显示所有项目
• README 清楚说明文件位置
问题: 应该做通用工具还是专用工具？
通用工具 (Obsidian, Notion, Jira)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ 问题:
• 功能臃肿，学习曲线陡峭
• 大部分功能用不上
• 配置复杂，启动慢
专用工具 (Context Manager) ⭐
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 优点:
• 专注解决"上下文切换"问题
• 零学习曲线 (10 分钟)
• 极致简洁 (600 行代码)
• 启动极快 (5 秒)
❌ 缺点:
• 功能范围有限
• 不适合复杂项目管理
决策: 专用工具
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
理由:
1. 专注 > 泛化 (奥卡姆剃刀原理)
2. 做好一件事 > 做百件事平庸
3. 可组合性 > 大而全
设计哲学:
"Do one thing and do it well" - UNIX 哲学
• 专注上下文管理
• 与其他工具组合 (Git, Claude Code)
• 不重复造轮子
Context Manager 的设计 DNA
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. 用户至上
✓ 工具适应用户，不是用户适应工具
✓ 零学习成本，渐进式增强
2. 自动化优先
✓ 减少认知负荷
✓ 让工具替你记忆
3. 简洁性至上
✓ 10 分钟学会
✓ 600 行代码实现
✓ 零外部依赖
4. 原生集成
✓ 与 Git 无缝协同
✓ 与 Claude Code 深度集成
✓ 符合 UNIX 哲学
5. 渐进式增强
✓ 从基础功能开始
✓ 按需使用高级功能
✓ 不强制升级
学习成本分析
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
一次性学习成本: 10 分钟
├── 阅读文档 (README.md) 3 分钟
├── 理解核心命令 5 分钟
│ ├── ctx init (1 分钟)
│ ├── ctx ls (1 分钟)
│ ├── ctx switch <project> (2 分钟)
│ └── ctx update <field> (1 分钟)
└── 首次实际使用 2 分钟
对比:
• Obsidian: 1-3 小时学习曲线
• Jira: 2-5 小时学习曲线
• beads: 1-2 小时学习曲线
• Context Manager: 10 分钟 ⭐
单次使用时间成本
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
命令 │ 时间 │ 对比 (传统方式)
──────────────────┼─────────┼─────────────────────────────
ctx ls │ 2 秒 │ 需要手动 ls + grep (30 秒)
ctx switch <proj> │ 3 秒 │ 需要cd + git查看 (2-5 分钟)
ctx update │ 5 秒 │ 需要编辑文件 (30-60 秒)
ctx status │ 1 秒 │ 需要查看多处 (1-2 分钟)
平均节省: 每次操作 1-4 分钟
场景 1: 轻度用户 (每周 5 次项目切换)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
投入:
• 学习成本: 10 分钟
• 首次配置: 5 分钟
• 总投入: 15 分钟
回报 (单次切换节省 2 分钟):
• 周节省: 5 次 × 2 分钟 = 10 分钟
• 月节省: 10 × 4 = 40 分钟
• 年节省: 10 × 52 = 520 分钟 ≈ 8.7 小时
回本点:
• 15 / 2 = 7.5 次 ≈ 1.5 周
• 投资回报率: (520 - 15) / 15 = 3367% 💰💰💰
场景 2: 中度用户 (每周 10 次项目切换)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
投入:
• 学习成本: 10 分钟
• 首次配置: 5 分钟
• 总投入: 15 分钟
回报 (单次切换节省 2 分钟):
• 周节省: 10 次 × 2 分钟 = 20 分钟
• 月节省: 20 × 4 = 80 分钟 ≈ 1.3 小时
• 年节省: 20 × 52 = 1040 分钟 ≈ 17.3 小时
回本点:
• 15 / 2 = 7.5 次 ≈ 3-4 天
• 投资回报率: (1040 - 15) / 15 = 6833% 💰💰💰💰
场景 3: 重度用户 (每周 20 次项目切换)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
投入:
• 学习成本: 10 分钟
• 首次配置: 5 分钟
• 总投入: 15 分钟
回报 (单次切换节省 2 分钟):
• 周节省: 20 次 × 2 分钟 = 40 分钟
• 月节省: 40 × 4 = 160 分钟 ≈ 2.7 小时
• 年节省: 40 × 52 = 2080 分钟 ≈ 34.7 小时
回本点:
• 15 / 2 = 7.5 次 ≈ 1-2 天
• 投资回报率: (2080 - 15) / 15 = 13767% 💰💰💰💰💰
使用频率对比表
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
使用频率 │ 单次节省 │ 周节省 │ 月节省 │ 年节省 │ 回本周次
───────────┼─────────┼───────┼───────┼───────┼──────────
每周 5 次 │ 2 分钟 │ 10分钟│ 40分钟│ 8.7h │ 1.5 周
每周 10 次 │ 2 分钟 │ 20分钟│ 1.3h │ 17.3h │ 3-4 天
每周 20 次 │ 2 分钟 │ 40分钟│ 2.7h │ 34.7h │ 1-2 天
结论: 即使轻度用户，1.5 周内即可回本
1. 时间节省
✓ 每周节省 10-40 分钟 (取决于使用频率)
✓ 每年节省 8-35 小时
✓ 减少上下文切换成本 90%+
2. 避免遗忘
✓ 想法不再丢失 (记录在 next_steps)
✓ 会话历史完整保留
✓ 项目状态持续追踪
3. 效率提升
✓ 项目切换从 2-5 分钟 → 5 秒
✓ 状态查询从 1-2 分钟 → 1 秒
✓ 整体工作效率提升 15-30%
1. 降低认知负荷
✓ 不需要记忆"我上次做到哪了"
✓ 不需要记忆"哪些项目正在进行"
✓ 大脑可以专注于创造，而非记忆
量化估算: 减少认知负荷约 40-60%
(基于减少的手动记忆和查找工作)
2. 提升工作连续性
✓ 快速恢复工作状态 (5 秒 vs 2-5 分钟)
✓ 减少"冷启动"时间
✓ 保持心流状态
量化估算: 工作连续性提升 70%+
(基于上下文恢复速度)
3. 知识沉淀
✓ 会话历史自动记录
✓ 项目演进过程可见
✓ 决策历史可追溯
长期价值:
• 6 个月后可以回顾项目历程
• 新人可以快速了解项目背景
• 形成个人知识库
4. 心理安全
✓ 知道所有项目的状态
✓ 不担心遗漏重要想法
✓ 减少焦虑感
量化估算:
• 减少项目切换焦虑 80%+
• 提升工作掌控感 60%+
长期收益 (往往被忽视)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. 与 AI 工具协同
✓ Claude Code 可以读取 .claude/context.md
✓ AI 理解项目上下文，提供更精准建议
• 减少 AI "幻觉" (基于真实项目状态)
• 减少 prompt 长度 (上下文已在文件中)
• 提升建议相关性 (+30-50%)
2. 项目健康度可视化
✓ session_count 反映项目投入
✓ status 反映项目生命周期
• 可以识别"僵尸项目" (长期未更新)
• 可以评估项目优先级 (基于活跃度)
• 可以做项目组合管理
3. 决策支持
✓ 历史会话记录
✓ 想法和决策的演进过程
• 可以追溯"为什么这么做"
• 可以避免重复错误
• 可以学习过往决策
4. 工作流优化
✓ 发现低效模式 (频繁切换)
• 识别"上下文切换过载"
• 优化项目并行数量
• 提升专注度
综合评估
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
投入:
• 时间: 15 分钟 (一次性)
• 金钱: $0 (MIT 许可)
• 资源: ~5MB 磁盘空间
• 学习: 10 分钟 (阅读 + 实践)
回报 (第一年):
• 时间节省: 8-35 小时
• 价值: $800-3500 (按 $100/小时计算)
• ROI: 5300%-23000% 💰💰💰💰💰
回报 (长期):
• 知识沉淀: 逐年累积
• AI 协同: 持续提升
• 心理安全: 持续受益
• 无法量化: 但巨大
结论:
"15 分钟的投入，换取每年 8-35 小时的节省，
以及无法估量的认知减负和知识沉淀。"
| 维度 | Context Manager | planning-with-files |
|---|---|---|
| 定位 | 项目上下文管理 | 文件级规划 |
| 学习曲线 | ⭐ 10 分钟 | ⭐⭐ 30 分钟 |
| 实现复杂度 | 600 行 Python | 复杂 (多工具集成) |
| 依赖 | ❌ 零依赖 | |
| 会话追踪 | ✅ 自动增量 | ❌ 无此概念 |
| Git 集成 | ✅ 原生支持分支追踪 | |
| 切换成本 | 5 秒 | 30 秒+ (需要打开文件) |
| 状态管理 | ✅ 3 种状态 (active/paused/completed) | |
| 适用场景 | 多项目并行快速切换 | 复杂任务分解和规划 |
| 匹配需求 | 95% (上下文切换) | 60% (需要手动维护) |
何时选择 Context Manager:
- ✅ 你需要频繁在多个项目间切换
- ✅ 你希望自动化追踪项目状态
- ✅ 你想要零学习成本的工具
何时选择 planning-with-files:
- ✅ 你需要复杂的任务分解和依赖管理
- ✅ 你团队使用文件级协作工作流
- ✅ 你需要图形化的进度追踪
| 维度 | Context Manager | beads |
|---|---|---|
| 定位 | 项目上下文管理 | Git 分支追踪 |
| 学习曲线 | ⭐ 10 分钟 | ⭐⭐⭐ 2 小时 |
| 实现复杂度 | 600 行 Python | 复杂 (git hooks + bd CLI) |
| 依赖 | ❌ 零依赖 | |
| 状态管理 | ✅ 3 种状态分类 | ❌ 只有 tracked/untracked |
| 上下文信息 | ✅ 详细 (待办、会话历史、分支) | |
| 切换成本 | 5 秒 | 30 秒 (需要 bd 命令) |
| 数据位置 | ✅ 项目本地 (.claude/) | |
| 适用场景 | 多项目并行开发 | 单项目多分支深度追踪 |
| AI 协同 | ✅ 原生支持 Claude Code | ❌ 无此设计 |
何时选择 Context Manager:
- ✅ 你管理多个独立项目 (而非单一项目的多个分支)
- ✅ 你需要记录上下文信息 (待办、会话历史)
- ✅ 你希望与 AI 工具协同工作
何时选择 beads:
- ✅ 你在一个项目中使用大量分支
- ✅ 你主要关心哪些分支已经被追踪
- ✅ 你不需要记录额外的上下文信息
| 维度 | Context Manager | Obsidian/Notion |
|---|---|---|
| 定位 | CLI 工具 (上下文管理) | 笔记应用/知识库 |
| 工作流 | 命令行为主 | 图形界面为主 |
| 自动化 | ✅ 自动追踪会话数和时间 | ❌ 手动更新所有字段 |
| 速度 | ⚡⚡⚡ 极快 (5 秒) | ⚡⚡ 快 (需要打开应用) |
| 资源占用 | ~5MB (Python 解释器) | 200MB+ (Electron) |
| 可编程性 | ✅ 原生脚本友好 | |
| 数据格式 | ✅ 标准 Markdown | |
| 搜索能力 | ✅ 强大 (全文搜索) | |
| 协作能力 | ❌ 无 | ✅ 强大 (实时协作) |
| 适用场景 | 项目切换、状态追踪 | 知识库、文档管理、研究 |
| 学习成本 | ⭐ 10 分钟 | ⭐⭐⭐ 1 小时+ |
何时选择 Context Manager:
- ✅ 你需要命令行极速体验
- ✅ 你只需要项目管理功能 (不需要完整知识库)
- ✅ 你想要自动化追踪 (零手动维护)
何时选择 Obsidian/Notion:
- ✅ 你需要构建知识库和第二大脑
- ✅ 你需要强大的搜索和链接功能
- ✅ 你需要团队协作能力
| 维度 | Context Manager | Jira/Linear |
|---|---|---|
| 定位 | 个人工作流助手 | 团队协作平台 |
| 学习曲线 | ⭐ 10 分钟 | ⭐⭐⭐⭐ 1-3 小时 |
| 复杂度 | ⭐⭐⭐ 极简 | ⭐⭐⭐⭐⭐ 复杂 |
| 使用场景 | 个人项目、独立开发者 | 团队项目、企业级管理 |
| 核心价值 | 上下文管理 | 任务管理 + 流程 + 协作 |
| 任务管理 | ✅ 强大 (分配、优先级、依赖) | |
| 团队协作 | ❌ 无 | ✅ 强大 (评论、@、通知) |
| 报表分析 | ❌ 无 | ✅ 强大 (燃尽图、速度图) |
| 集成能力 | ✅ Git + Claude Code | ✅ 几乎所有工具 |
| 价格 | ✅ 免费 (MIT) | 💰💰💰 昂贵 (SaaS) |
| 部署方式 | ✅ 本地 (离线可用) |
何时选择 Context Manager:
- ✅ 你是独立开发者或管理个人项目
- ✅ 你不需要团队协作功能
- ✅ 你想要简洁、极速的工具
- ✅ 你关注隐私和本地化
何时选择 Jira/Linear:
- ✅ 你管理团队项目
- ✅ 你需要任务分配和进度跟踪
- ✅ 你需要报表和数据分析
- ✅ 你需要与大量工具集成
Context Manager 的独特价值主张
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. 专注"上下文切换"这个细分领域
✓ 不是项目管理 (Jira/Linear)
✓ 不是笔记工具 (Obsidian/Notion)
✓ 不是分支追踪 (beads)
✓ 不是任务规划 (planning-with-files)
⇒ 而是"上下文管理" (Context Management)
2. 零学习成本的自动化
✓ 自动记住"我上次做到哪了"
✓ 自动记住"这个项目进行中吗？"
✓ 自动累积"我在这个项目投入了多少"
⇒ 用户只需要更新当前焦点，其他全自动
3. 与 AI 工具原生协同
✓ 为 Claude Code 提供项目上下文
✓ 让 AI 理解项目状态和历史
✓ 历史信息辅助 AI 决策
⇒ 这是传统工具没有的设计维度
4. 极致的简洁和速度
✓ 5 秒切换项目 (vs Obsidian 30 秒+)
✓ 零依赖 (vs beads 需要 git + bd)
✓ 10 分钟学习 (vs Jira 1-3 小时)
⇒ 符合 CLI 哲学：极速、高效、可组合
需要管理多个项目？
├─ 是 → 需要团队协作？
│ ├─ 是 → Jira/Linear
│ └─ 否 → 需要复杂任务分解？
│ ├─ 是 → planning-with-files
│ └─ 否 → Context Manager ⭐
└─ 否 → 单项目多分支？
├─ 是 → beads
└─ 否 → 需要知识库？
├─ 是 → Obsidian/Notion
└─ 否 → Context Manager
# 1. 查看所有项目
ctx ls
# 输出：
# 🟢 进行中 (2)
# context-manager-skill # 会话#12 • "优化 README 结构"
# podcast-app # 会话#8 • "修复音频同步问题"
#
# 🟡 已暂停 (3)
# tangshi # 会话#5 • "诗词生成效果优化"
# short-video-remotion # 会话#3 • "视频渲染性能优化"
# notebooklm-skill # 会话#2 • "API 集成测试"
# 2. 切换到项目
ctx switch context-manager-skill
# 输出：
# ╔════════════════════════════════════════════════════════╗
# ║ 项目: context-manager-skill ║
# ║ 上次: 2026-02-04 ║
# ║ 会话: #12 ║
# ║ 分支: main ║
# ╠════════════════════════════════════════════════════════╣
# ║ 当前焦点: 优化 README 结构 ║
# ╠════════════════════════════════════════════════════════╣
# ║ 📋 待办列表: ║
# ║ - [x] 修复编码问题 ║
# ║ - [ ] 更新测试覆盖率 ║
# ║ - [ ] 优化 trade-off 分析 ║
# ╚════════════════════════════════════════════════════════╝
# 3. 开始工作，完成后更新状态
ctx update current_focus "完成了 README 结构优化和 trade-off 分析"
ctx update status active让每次打开终端时自动显示项目关键信息，无需手动输入命令。
快速配置（3 步）：
# 1. 复制脚本到技能目录
cp show-context.sh ~/.claude/context-manager-skill/
# 2. 添加到 shell 配置
if [ -f ~/.claude/context-manager-skill/show-context.sh ]; then
~/.claude/context-manager-skill/show-context.sh
fi
# 3. 重新加载配置
source ~/.zshrc # 或 source ~/.bashrc现在每次打开终端，都会自动看到：
══════════════════════════════════════════════════════════════
📂 项目上下文 - my-project
══════════════════════════════════════════════════════════════
📊 状态: active | 分类: 产品
🎯 当前焦点: 完成核心功能
📅 会话 #5 | 最后工作: 2026-02-04
══════════════════════════════════════════════════════════════
📖 详细配置和自定义选项：参见 AUTO_DISPLAY.md
# 初始化新项目
cd ~/workspace/new-project
ctx init
# 查看完整上下文
ctx
# 更新状态分类
ctx update category 产品
ctx update brief "AI 驱动的播客生成平台"
# 查看紧凑状态（单行）
ctx status┌─────────────────────────────────────────────────────┐
│ CLI 入口 │
│ ctx / scripts/context_manager.py │
└──────────────────────┬──────────────────────────────┘
│
┌───────────────┴───────────────┐
↓ │
┌──────────────────────┐ ┌─────────────────────┐
│ 文件系统层 │ │ 解析器层 │
│ │ │ │
│ .claude/context.md │ │ parse_context() │
│ │ │ • v1 格式 │
│ │ │ • v2 格式 │
│ │ │ • 混合格式 │
└──────────────────────┘ └─────────────────────┘
│
┌───────────────────────────────────────────┐
↓ │
┌──────────────────────┐ ┌──────────────────────┐
│ 显示层 │ │ 配置层 │
│ │ │ │
│ ctx ls (分组显示) │ │ WORKSPACE_ROOT │
│ ctx status (紧凑) │ │ status 枚举值 │
│ ctx switch (切换) │ │ category 枚举值 │
└──────────────────────┘ └─────────────────────┘
# 项目上下文的数据模型
project:
name: str
metadata:
created: date
last_session: date
session_count: int
status: Status # active/paused/completed
category: Category # 探索性/产品/临时/学习
content:
current_focus: str
next_steps: str
branch: str
brief: str
stack: List[str]
history:
todos: List[Todo]
sessions: List[Session]1. 双格式解析器
def parse_context(content: str) -> dict:
"""
智能识别格式版本
v1 特征:
- project_type 字段
- session_count 字段
- 分支字段
v2 特征:
- created 字段
- status 字段（active/paused/completed）
- category 字段
混合格式:
- 同时包含 v1 和 v2 特征
"""
# 自动检测并统一解析2. 自动追踪机制
def cmd_update(args):
"""更新字段时自动维护元数据"""
# 1. 更新 last_session
# 2. 增加 session_count
# 3. 保留历史
# 用户无需手动维护- 完整文档 (SKILL.md) - 技术参考
- 迁移指南 (MIGRATION.md) - 从旧格式升级
- 贡献指南 (CONTRIBUTING.md) - 如何贡献
MIT License - 详见 LICENSE 文件
版本: v0.1.0 Python: 3.9+ 仓库: https://github.com/username/context-manager