OthmanAdi/planning-with-files

⭐ 20,799  ·  Python  ·  GitHub 仓库

实现Manus风格持久化Markdown规划的Claude Code技能——价值20亿美元收购案背后的工作流模式

adal agent-skills antigravity claude claude-code claude-skills copilot copilot-skills

一句话总结

为AI智能体设计的持久化Markdown规划方案，完整复现了Meta斥资20亿美元收购Manus背后的工作流架构。

🔥 核心能力与独特卖点

• 持久化Markdown规划：维护结构化的task_plan.md文件，即使清空上下文或重启IDE也能保留。彻底解决了AI智能体在清除对话或重启IDE时丢失所有任务状态的痛点。
• 自动会话恢复：执行/clear命令后，系统自动检测丢失的上下文，检查会话存储，提取近期对话历史来恢复规划。消除了困扰所有基于智能体工作流的"空白页"问题。
• 多平台支持：覆盖17+款IDE和工具，包括Claude Code、Cursor、GitHub Copilot、Gemini CLI、Codex等——每款都有专属的钩子配置。一套工作流，适配所有环境。
• 并行规划隔离：支持在.planning/YYYY-MM-DD-slug/目录下同时运行多个独立规划，各有独立的会话追踪。运行复杂的并发智能体任务，规划互不干扰。
• 安全加固：包含哈希认证（/plan-attest）、提示注入分隔符和经过审计的安全修复。为生产环境智能体工作流提供企业级安全保障。

独特卖点：这是唯一开源实现的Manus持久化规划模式——正是驱动20亿美元收购案的确切工作流架构。它不仅仅是又一个任务管理器；它是经过验证、被收购认可、专为智能体编程设计的成熟模式。

技术架构

组件	技术栈	用途
核心逻辑	Python + Shell脚本	规划创建、会话追踪、恢复逻辑
配置	SKILL.md + hooks.json	智能体集成的生命周期钩子
存储	Markdown文件（task_plan.md）	人类可读、可版本控制的规划持久化
会话管理	.planning/目录结构	带日期戳的并行规划隔离
IDE集成	各IDE的hooks.json、plugin.json	支持Windows、Linux、macOS的OS感知钩子
安全	哈希认证、提示分隔符	防篡改和注入防护
生命周期钩子	SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop	覆盖智能体事件全生命周期

该架构采用插件化、事件驱动设计：每个IDE的智能体触发生命周期钩子，由规划系统拦截，确保规划在正确的时机被创建、更新和恢复。

快速入门指南

# 克隆仓库
git clone https://github.com/OthmanAdi/planning-with-files.git
cd planning-with-files

# 安装到Claude Code（主要目标平台）
# 将SKILL.md和钩子文件复制到你的Claude Code项目根目录
cp -r planning-with-files/* /path/to/your/project/

# 对于Cursor、Copilot或其他IDE，使用对应的分支
git checkout cursor  # 或 copilot、gemini-cli、codex等

# 初始化新规划
# 智能体将在首次交互时自动创建task_plan.md

安装逻辑：该项目是一个技能/插件，直接放入项目根目录即可。每个IDE都有专用的配置分支，包含正确的hooks.json和生命周期设置。复制文件后，你的智能体将在下一次会话启动时自动开始使用持久化Markdown规划。

优点、缺点与使用场景

优点

• 96.7%的基准测试通过率——在真实智能体工作流中经过验证的可靠性
• 活跃的社区——拥有分支、扩展和快速迭代
• 上下文清除后自动恢复——不再丢失工作成果
• 经过安全审计——具备哈希认证和注入防御
• 17+平台支持——每个IDE都有专属配置

缺点

• 每个IDE需要手动安装——暂无包管理器安装方式
• 版本迭代频繁（v2.37.0+，更新频繁）可能需要持续维护
• 部分功能因IDE而异——并非所有能力在每个平台上都可用
• NixOS等非标准环境存在Shell兼容性问题（需要修复shebang）

谁不应该使用？

• 普通用户——仅运行单次会话的智能体提示，从不清除上下文
• 受限制的企业环境团队——禁止向IDE添加自定义钩子
• 不支持的IDE用户（例如不在17+支持列表中的小众或专有工具）
• NixOS开发者——不愿意应用文档中提到的shebang变通方案

理想使用场景

• 多会话编码项目——清除智能体上下文后仍需恢复工作
• 复杂的多步骤重构——需要跨天进行结构化任务追踪
• CI/CD流水线智能体——需要在自动化运行中保持状态
• 标准化智能体工作流的团队——希望采用经过验证、被收购认可的模式
• 高级用户——同时处理多个并行智能体任务（如后端+前端+文档）

社区与活跃度

这个项目火爆异常。拥有20,799颗星，最后更新于2026年5月10日，它不仅受欢迎，而且正在积极维护和快速演进。社区已经在多个平台上产生了分支和扩展，v2.37.0的发布节奏表明团队正在快速交付并修复问题。96.7%的基准测试通过率不仅仅是一个数字——它表明社区正在生产环境中对其进行压力测试，而它经受住了考验。如果你在2026年构建智能体工作流，这就是值得关注和采用的模式。