Planning-with-Files：从文件系统到AI代理工作内存的架构演进

Planning-with-Files：从文件系统到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代理开发领域，最令人沮丧的体验莫过于代理在复杂的多步骤任务中迷失方向。上下文窗口被填满，原始目标被遗忘，错误重复出现——这些问题共同构成了所谓的"上下文丢失综合症"。Planning-with-Files项目正是为解决这一核心挑战而生，它将文件系统重新定义为AI代理的持久化工作内存，实现了从临时记忆到结构化存储的范式转变。

架构演进：从临时记忆到持久化状态管理

传统的AI代理工作流依赖于上下文窗口作为临时存储，这种方法存在固有的脆弱性。Planning-with-Files通过三文件系统架构彻底改变了这一模式，将状态管理从易失性内存转移到持久化存储。

核心架构模式

Planning-with-Files的核心创新在于其分层存储架构。项目采用了类似于操作系统内存管理的方法，将AI代理的认知过程分为三个层次：

1. 工作集（Working Set）：当前上下文窗口中的活跃信息
2. 文件缓存（File Cache）：task_plan.md、findings.md、progress.md组成的持久化缓存
3. 磁盘存储（Disk Storage）：完整的项目文件系统作为长期存储

这种分层架构的关键在于自动化的状态同步机制。通过PreToolUse和PostToolUse钩子，系统在每次工具调用前后自动同步内存与磁盘状态，确保了认知连续性的维持。

状态同步机制的技术实现

项目的状态同步机制基于事件驱动架构。当AI代理准备执行关键操作时，PreToolUse钩子被触发，自动读取task_plan.md文件，将目标状态重新注入代理的注意力窗口。这种机制实际上实现了Manus AI所倡导的"注意力操纵"原则——通过定期重新激活关键信息来防止目标漂移。

# 状态同步的核心逻辑 PreToolUse Hook → 读取task_plan.md → 注入上下文 → 执行操作 PostToolUse Hook → 检查状态变化 → 更新文件 → 维持一致性

这种设计的关键洞察在于：AI代理的认知连续性不是通过扩大上下文窗口实现的，而是通过智能的状态管理和定期刷新来维持的。

分布式环境下的架构考量

Planning-with-Files v3.0.0引入了并行计划隔离机制，这是对分布式AI工作流的重要演进。传统的单文件方法在多代理协作场景中存在严重的竞争条件问题。

并行隔离架构

v3.0.0通过.planning/<date>-<slug>/目录结构实现了完全隔离的并行工作空间。每个会话获得独立的文件集：

.planning/2026-01-10-backend-refactor/ ├── task_plan.md ├── findings.md ├── progress.md └── .attestation .planning/2026-01-10-incident-investigation/ ├── task_plan.md ├── findings.md ├── progress.md └── .attestation

这种隔离架构的关键优势在于避免了文件锁竞争，同时允许不同会话独立演进。通过.planning/.active_plan符号链接机制，系统能够智能地解析当前活动计划，实现了动态上下文切换。

认证与完整性保证

项目的认证机制采用了SHA-256哈希验证和原子写入模式，确保了计划文件的完整性。attest-plan.sh脚本实现了以下关键特性：

1. 原子性写入：通过临时文件重命名确保认证文件的一致性
2. 平台兼容性：在Linux、macOS、Windows Git Bash和WSL上提供一致的行为
3. 性能优化：基于mtime的哈希缓存减少了重复计算开销

认证缓存位于$XDG_CACHE_HOME/pwf-sha/目录，采用用户私有路径设计，避免了/tmp目录可能存在的安全问题。

性能优化策略与权衡分析

在AI代理工作流中，性能优化需要在计算开销和认知连续性之间找到平衡。Planning-with-Files v3.0.0引入了两种优化模式：自主模式和门控模式。

自主模式：减少重复注入开销

自主模式针对强大模型设计，将计划重新注入频率从每次工具调用减少到每次会话开始。这种设计基于一个重要观察：对于能够维持较长注意周期的模型，频繁的重新注入会产生不必要的令牌开销。

# 自主模式初始化 ./scripts/init-session.sh --autonomous "长期任务" # 传统模式（v2兼容） ./scripts/init-session.sh "传统任务"

性能测试数据显示，自主模式在长运行任务中减少了30-50%的令牌消耗，同时保持了相同的任务完成率。

门控模式：确定性完成验证

门控模式引入了五个条件的完成验证机制，只有当所有条件满足时才会阻止会话停止：

1. 会话处于门控模式
2. 存在进行中的阶段
3. 停止钩子处于活动状态
4. 阻止计数未超过上限
5. 自上次阻止以来分类账有进展

这种设计确保了不完整的计划不会无限期地"困住"会话，同时提供了确定性的完成保证。

多平台兼容性架构

Planning-with-Files支持17+个AI开发平台，这种广泛的兼容性是通过分层适配器架构实现的。

SKILL.md标准化接口

项目采用了SKILL.md开放标准作为核心接口规范。这个标准定义了技能发现、钩子注册和配置管理的统一接口，使得Planning-with-Files能够在不同平台上提供一致的行为。

skills/ ├── planning-with-files/ # 默认英语版本 ├── planning-with-files-ar/ # 阿拉伯语适配器 ├── planning-with-files-de/ # 德语适配器 ├── planning-with-files-es/ # 西班牙语适配器 ├── planning-with-files-zh/ # 简体中文适配器 └── planning-with-files-zht/ # 繁体中文适配器

每个适配器都实现了平台特定的钩子配置，同时保持核心逻辑的一致性。这种设计允许项目在保持核心功能不变的情况下，为每个平台提供最优化的集成体验。

钩子系统的跨平台抽象

Planning-with-Files的钩子系统采用了抽象层设计，将平台特定的钩子机制映射到统一的事件模型：

平台钩子 → 抽象层 → 统一事件处理器 → 文件系统操作

这种设计使得核心的文件管理逻辑与平台实现细节解耦，大大简化了维护和扩展工作。

安全架构与边界防护

在2025年的安全审计中，Planning-with-Files面临了间接提示注入的挑战。项目的安全响应展示了现代AI工具的安全设计原则。

安全边界设计

v2.21.0版本引入了明确的安全边界规则：

1. 工具权限最小化：移除WebFetch和WebSearch的allowed-tools声明
2. 内容隔离：外部内容只能写入findings.md，避免进入task_plan.md的自动注入循环
3. 用户确认机制：对外部来源的指令性内容要求用户确认

这种设计的关键在于理解安全威胁模型：问题不在于外部内容本身，而在于外部内容通过PreToolUse钩子被无限放大的可能性。

认证机制的安全保证

认证机制不仅保证文件完整性，还提供了防篡改保护。当计划文件被修改后，钩子会检测到哈希不匹配并阻止内容注入，防止恶意修改影响AI代理的行为。

性能数据与基准测试

根据项目的正式评估结果，Planning-with-Files在结构化工作流保真度方面实现了96.7%的通过率。这个数字背后是严谨的测试方法论：

评估框架设计

项目采用了Anthropic的skill-creator评估框架，包含以下关键组件：

• 10个并行子代理：5个使用技能，5个不使用
• 5种多样化测试用例：CLI工具规划、研究任务、调试会话、Django迁移、CI/CD流水线
• 30个客观可验证断言：文件存在性、章节标题、状态字段、结构要求
• 3个盲测A/B比较：独立评估代理，不知道哪个输出来自哪个配置

性能对比分析

测试结果显示，使用Planning-with-Files的代理在3个盲测A/B比较中全部获胜，平均得分从6.8/10提升到10.0/10。更重要的是，所有使用技能的运行都产生了正确的三文件模式，而没有使用技能的运行则完全没有遵循结构化规划工作流。

生产环境部署策略

容器化与CI/CD集成

Planning-with-Files在容器环境中的表现经过了专门优化。认证缓存位于用户私有路径，避免了容器重启时的状态丢失问题。在CI/CD流水线中，项目提供了明确的恢复策略：

# 容器环境初始化 ./scripts/init-session.sh --plan-dir "ci-build-$(date +%s)" # 会话恢复机制 ./scripts/session-catchup.py

大规模部署的架构考量

对于企业级部署，Planning-with-Files支持以下扩展模式：

1. 共享文件系统部署：通过NFS或云存储实现跨团队的文件共享
2. 版本控制集成：计划文件可以提交到Git，实现版本跟踪和协作
3. 监控与告警：通过进度文件的时间戳监控任务停滞
4. 审计日志：所有文件操作都有完整的时间戳记录

技术选型与架构权衡

Planning-with-Files在设计过程中面临了几个关键的技术决策：

文件格式选择：Markdown vs JSON vs YAML

项目选择了Markdown作为主要文件格式，这一决策基于以下考虑：

1. 人类可读性：开发者可以直接查看和编辑文件
2. AI友好性：LLM对Markdown有良好的理解和生成能力
3. 版本控制友好：Git对Markdown的diff和合并支持良好
4. 工具生态：丰富的Markdown编辑和查看工具

钩子频率权衡：每次工具调用vs会话开始

v2.x版本采用每次工具调用前重新注入的策略，确保了最高的认知连续性，但带来了令牌开销。v3.0.0的自主模式将频率降低到会话开始，在保持有效性的同时显著减少了开销。

故障排查与调试策略

诊断工具集成

Planning-with-Files提供了完整的诊断工具链：

# 检查计划完整性 ./scripts/check-complete.sh # 查看分类账摘要 ./scripts/ledger-summary.sh # 验证阶段状态 ./scripts/phase-status.sh

调试模式支持

项目支持详细的调试输出，可以通过环境变量控制：

export PWF_DEBUG=1 ./scripts/init-session.sh "调试任务"

未来架构演进方向

基于当前的技术趋势和用户反馈，Planning-with-Files的架构演进可能包括：

1. 增量同步机制：只同步变化的部分，减少数据传输
2. 二进制协议支持：对于大型计划文件，提供更高效的序列化格式
3. 分布式锁机制：支持跨多个AI代理的协作编辑
4. 实时协作：基于WebSocket的文件同步和冲突解决

技术建议与最佳实践

对于技术决策者，Planning-with-Files提供了以下可落地的建议：

实施策略

1. 渐进式采用：从单个项目开始，逐步扩展到团队范围
2. 培训与文档：确保团队成员理解三文件模式的核心原则
3. 监控与优化：定期检查计划文件的大小和结构，避免过度复杂化

性能调优

1. 根据模型能力选择模式：强大模型使用自主模式，较弱模型使用传统模式
2. 定期清理旧计划：建立计划文件的归档和清理策略
3. 优化文件大小：保持计划文件的简洁性，避免不必要的细节

安全实践

1. 定期安全审计：检查计划文件中的敏感信息
2. 访问控制：确保计划文件有适当的权限设置
3. 备份策略：实现计划文件的定期备份和恢复测试

Planning-with-Files代表了AI代理开发的一个重要范式转变：从依赖易失性上下文窗口转向基于文件系统的持久化状态管理。通过将文件系统重新定义为AI的工作内存，项目解决了长期困扰AI代理开发者的上下文丢失问题，为复杂、长期的AI驱动任务提供了可靠的基础架构。

对于技术决策者而言，这个项目的价值不仅在于其功能实现，更在于它所展示的架构思想：通过简单的文件系统抽象，我们可以构建出强大、可靠、可扩展的AI工作流管理系统。这种基于文件的状态管理模式可能会成为未来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