3种钩子模式如何用文件系统构建AI智能体的持久化记忆【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running agentic tasks. Crash-proof markdown plans that survive context loss and /clear, plus a deterministic completion gate and multi-agent shared state on disk. Manus-style. Works with Claude Code, Codex CLI, Cursor, Kiro, OpenCode and 60 agents via the SKILL.md standard.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files在AI智能体开发领域最棘手的挑战不是编写代码而是让智能体记住自己正在做什么。当上下文窗口重置、会话中断或工具调用超过50次后原始目标往往消失在数字迷雾中。Planning-with-Files项目通过一种革命性的方法解决了这个根本问题将AI智能体的工作记忆持久化到文件系统中。这个开源项目基于Manus AI的工作模式为60多种AI代理提供了一个基于文件的规划框架。它不仅仅是一个工具而是一种全新的工作哲学——通过三个简单的Markdown文件task_plan.md、findings.md、progress.md构建起AI智能体的外部大脑。设计哲学文件作为持久化记忆层Planning-with-Files的核心设计理念源于一个简单的观察AI智能体擅长处理结构化文本而文件系统是地球上最可靠的持久化存储。项目的架构师Ahmad Othman Ammar Adi在官方文档中这样描述这不是一个技能而是一种工作模式——将你的计划、发现和进展写入文件让它们在任何上下文重置后都能存活下来。三文件架构AI智能体的外部记忆系统项目的核心是三个相互关联的Markdown文件每个文件承担特定的认知功能task_plan.md- 战略规划层 这个文件定义了任务的整体架构采用分阶段规划模式。每个阶段包含明确的状态标记pending、in_progress、complete支持自动进度跟踪。文件位于项目根目录或专用的.planning/子目录中为智能体提供持续的目标指引。findings.md- 研究记录层 所有研究发现、技术决策和关键见解都记录在这里。遵循两次操作规则在查看两个网页或搜索结果后智能体必须更新此文件。这种强制性的知识固化机制防止了信息丢失。progress.md- 执行日志层 详细记录每个操作步骤、文件修改和时间戳。这不仅是一个日志文件更是智能体的工作记忆扩展确保即使在会话中断后也能从上次停止的地方继续。项目核心架构展示AI智能体如何通过三个Markdown文件构建持久化记忆系统钩子机制智能上下文管理的实现模式项目的真正创新在于其钩子系统这是实现自动化上下文管理的技术核心。钩子机制通过预定义的事件触发器在关键操作点自动执行特定的脚本逻辑。PreToolUse钩子防止目标漂移的注意力管理器PreToolUse钩子是系统的注意力刷新器。在每次执行Write、Edit或Bash操作之前它会自动读取task_plan.md文件的前30行将当前目标重新注入智能体的注意力窗口。这个看似简单的机制解决了AI智能体开发中最常见的问题在长时间工作流中迷失方向。实现细节位于skills/planning-with-files/SKILL.md文件中的钩子配置部分。钩子使用精确的模式匹配来触发hooks: PreToolUse: - matcher: Write|Edit|Bash hooks: - type: command command: cat task_plan.md 2/dev/null | head -30 || true这种设计确保了每个重要决策都基于最新的目标状态同时避免了不必要的上下文污染。在v3版本中系统引入了低频率复述模式通过配置.mode文件可以在自主运行模式下减少复述频率优化性能。Stop钩子任务完成的智能守护者Stop钩子代表了质量保证的自动化实现。当用户尝试结束会话时这个钩子会触发scripts/check-complete.sh脚本验证所有计划阶段是否真正完成。脚本的核心逻辑既严谨又智能# 统计阶段总数和完成数 TOTAL$(grep -c ### Phase $PLAN_FILE || true) COMPLETE$(grep -cF **Status:** complete $PLAN_FILE || true) # 验证逻辑只有当所有阶段都完成时才允许停止 if [ $COMPLETE -eq $TOTAL ] [ $TOTAL -gt 0 ]; then echo ALL PHASES COMPLETE exit 0 else echo TASK NOT COMPLETE exit 1 fi更先进的是v3版本引入了门控模式这是一个可选的完成验证机制。当启用门控模式时系统会检查多个条件是否存在.mode文件并包含gate标记是否有正在进行中的阶段不仅仅是未完成的阶段Stop钩子的输入是否不包含stop_hook_activetrue标记阻塞计数器是否低于上限默认20次自上次阻塞以来运行日志是否有进展这种多层验证机制确保了智能体不会被无限期阻塞同时防止了未完成任务的提前终止。安全边界从漏洞到加固的演进历程项目的安全设计历程是一个值得学习的案例。在v2.21.0版本之前系统存在一个潜在的安全漏洞PreToolUse钩子会在每次工具调用时重新读取task_plan.md如果该文件包含来自不可信源的恶意内容这些内容会被反复注入上下文。安全审计发现了这个问题后团队实施了双重修复策略移除不必要的工具权限从allowed-tools中移除了WebFetch和WebSearch打破了潜在的恶意内容传播链添加显式安全边界在SKILL.md中添加了安全边界部分明确规定了网页/搜索结果只能写入findings.md的规则这个修复过程展示了开源项目如何通过透明的方式处理安全问题并将安全考虑融入架构设计。多场景应用从个人开发到企业级工作流Planning-with-Files的灵活性使其适用于从个人项目到企业级开发的多种场景。个人开发者场景复杂重构任务管理对于独立开发者系统提供了防止目标漂移的完美解决方案。在进行大型代码库重构时开发者可以创建详细的阶段规划Phase 1: 理解现有架构Phase 2: 设计新架构Phase 3: 逐步迁移等每个阶段开始时PreToolUse钩子自动刷新重构目标在findings.md中记录所有技术决策和发现在progress.md中跟踪每个文件修改完成所有阶段后Stop钩子验证完整性这种系统化的方法将原本容易混乱的复杂任务分解为可管理的步骤。团队协作场景多智能体协调工作流v3版本特别增强了多智能体协作支持。通过单一写入者规则系统确保了在并行执行时不会出现最后写入者胜出的数据损坏问题编排器智能体拥有task_plan.md和progress.md的独占写入权限工作器智能体只能向自己的运行日志文件ledger- .jsonl追加内容状态变更通过scripts/phase-status.sh在写入锁下进行这种架构支持复杂的分布式工作流其中多个专门化的AI智能体可以同时处理同一项目的不同方面而不会相互干扰。企业级部署自动化质量保证流水线对于企业环境项目提供了完整的自动化验证框架。通过集成到CI/CD流水线中团队可以使用自动化脚本初始化规划会话让AI智能体按照预定义阶段执行任务利用Stop钩子作为质量门禁通过运行日志进行审计和合规性检查tests/目录中包含了完整的测试套件确保了系统的可靠性和一致性。v3版本引入了古典石碑设计象征着项目从工具层到哲学层的演进集成策略跨平台兼容性与配置模式Planning-with-Files的设计考虑了广泛的兼容性支持60多种不同的AI代理平台。这种广泛的兼容性通过SKILL.md标准实现该标准定义了统一的技能接口规范。配置模式从简单到复杂的渐进式采用项目提供了三种主要的配置模式适应不同的使用场景传统模式默认PreToolUse钩子每次工具调用前读取计划Stop钩子仅提供建议性状态报告兼容所有v2.x版本的工作流自主模式autonomous降低复述频率优化长期运行性能添加运行合约和协调线支持多智能体协作门控模式gated启用完成验证机制可配置的阻塞上限默认20次停滞检测防止无限循环模式选择通过在规划目录中创建.mode文件来配置确保行为的明确性和可预测性。部署示例Claude Code集成对于Claude Code用户集成过程极其简单安装planning-with-files技能使用/plan命令开始新任务系统自动创建三个规划文件钩子自动配置并开始工作完整的示例可以在examples/目录中找到包括快速入门指南和实际应用场景。性能优化平衡功能与效率的实践在实际使用中性能考虑至关重要。Planning-with-Files通过多种策略优化资源使用选择性上下文加载PreToolUse钩子使用head -30命令只读取task_plan.md的关键部分避免了不必要的上下文污染。这种选择性加载策略在保持目标可见性的同时最小化了注意力窗口的占用。渐进式状态更新系统采用了智能的状态跟踪机制。只有在检测到正在进行中的阶段时Stop钩子才会执行完整的验证逻辑。这种惰性评估减少了不必要的计算开销。运行日志优化v3版本引入了运行日志系统ledger-*.jsonl文件提供了轻量级的进度跟踪机制。与完整的progress.md文件相比运行日志提供了更高效的增量更新能力。未来演进从文件系统到分布式记忆网络Planning-with-Files的当前实现已经展示了基于文件的持久化记忆的巨大潜力。未来的演进方向包括分布式记忆层计划中的功能扩展包括支持远程文件存储和同步使多个AI智能体能够在不同环境中共享相同的规划上下文。智能摘要生成基于运行日志的自动摘要功能可以为长时间运行的任务生成执行报告和关键决策点回顾。预测性规划通过分析历史规划数据系统可以提供阶段时间估算和资源需求预测进一步提高规划效率。效能评估实际应用中的价值体现根据项目文档中的基准测试数据使用Planning-with-files的系统在任务恢复速度上比传统方法快2.7倍。在A/B盲测中使用该方法的团队在3/3的对比测试中获胜。这些数据证明了基于文件的持久化规划不仅是一个理论概念而是实际提升AI智能体工作效率的有效工具。技术决策者的关键洞察对于技术决策者而言Planning-with-Files提供了几个重要的价值主张降低AI智能体开发风险通过防止目标漂移和确保任务完整性系统显著减少了因上下文丢失导致的返工和错误。提高团队协作效率标准化的文件格式和自动化钩子机制使多个开发者或AI智能体能够更有效地协作。增强可审计性所有决策、进展和错误都记录在结构化的Markdown文件中为项目审查和质量保证提供了完整的历史记录。未来兼容性基于SKILL.md标准的实现确保了与不断增长的AI代理生态系统的兼容性。Planning-with-Files代表了AI智能体开发范式的重要演进从依赖易失性上下文到构建持久化、可审计、可协作的工作记忆系统。通过将简单的文件系统转化为强大的认知扩展这个项目为下一代AI辅助开发工具奠定了基础。无论是个人开发者处理复杂重构还是企业团队构建自动化工作流Planning-with-Files都提供了经过实战验证的解决方案。它的成功不仅在于技术实现更在于对AI智能体工作模式的深刻理解——记忆不应该只在RAM中而应该持久化在文件系统中。【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running agentic tasks. Crash-proof markdown plans that survive context loss and /clear, plus a deterministic completion gate and multi-agent shared state on disk. Manus-style. Works with Claude Code, Codex CLI, Cursor, Kiro, OpenCode and 60 agents via the SKILL.md standard.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考