planning-with-files
活跃·★ 28.1k·MIT·更新于 2026-11-11
★ 最受欢迎
Planning with Files(PWF)是由 Othman Adi 开源的高口碑智能体规划框架,其核心哲学极为简明深刻:“智能体的上下文窗口终将耗尽,但磁盘上的规划永不磨灭。”该项目专门解决自主智能体在执行跨多轮复杂工程任务时容易出现的注意力发散、步骤遗忘与重复无用功等缺陷。
不同于脆弱的、极易随上下文压缩或 `/clear` 会话重置而灰飞烟灭的纯提示词指令,PWF 将任务状态硬性固化在项目本地的三大核心 Markdown 文件中:`task_plan.md`(结构化任务分解与当前执行项)、`findings.md`(项目架构洞察、API 特性与排错发现)以及 `progress.md`(已验证里程碑与单测证据)。系统通过生命周期钩子(Hooks)在每一轮对话前后自动比对读取,强力将模型拉回真实的执行路径上。
在针对长链路复杂任务的盲测 A/B 对比中,PWF 展现出压倒性的执行收敛率,目前已全面覆盖 60 余款遵循 Agent Skills 标准的智能体,并原生适配 Claude Code、Codex、Pi、OpenCode 与 DeepSeek Harness。需要注意的是,该模式会在项目根目录下直接产生规划辅助文档,需合理配置 Git 忽略或归档;每一轮的文件读写同步也会带来微小的磁盘 I/O 耗时。
#智能体技能#自主智能体#Claude#Claude Code#Claude Code 技能#Claude 技能#Codex#编程智能体
01
功能特性
01维护 task_plan.md、findings.md 与 progress.md。
02生命周期钩子注入选定项目计划上下文。
03提供 Agent Skills 及多个宿主专用插件路径。
02
为什么选择它
+不可磨灭的任务规划状态,无论遇到上下文压缩、会话重置还是终端意外崩溃,进度永不丢失。
+标准三文件体系(task_plan、findings、progress),清晰割裂任务清单、代码认知与实测证据。
+全自动生命周期会话钩子机制,轮次触发强约束,从机制上杜绝智能体自说自话与目标漂移。
+极佳的生态普适性,支持主流 Agent Skills 规范,无缝赋能 60 余款智能体编码工具。
03
权衡点
!直接在项目根目录下生成规划辅助文档,需要在团队协作中规范 Git 提交策略或加入 .gitignore。
!每轮迭代均涉及本地文件的读取比对与状态覆写,在超多轮次任务中存在微量磁盘 I/O 延迟。
!若开发者在终端外手动跳步完成了部分改动,智能体需要执行特定的同步模式来更新文件状态。
!对于极度简单、单文件小修小补的快速问答任务,维持整套文件规划机制会显得略显繁琐。
04
维护状况检查
活跃检查日期: 2026-11-12
- 最近提交
- 2026-11-11
- 近 90 天提交数
- 100+
- 近 90 天发布数
- 30
- 最新发布
- v3.28.1 (2026-11-07)
- 未关闭 issue
- 12
- 近期 issue 至少有一条评论的比例
- 18/24
近 12 周每周提交数
最早的一周在左边,最近 4 周为橙色。数据来源:GitHub 提交统计。
状态规则:GitHub 上已归档 = 已归档;最近提交在 90 天内 = 活跃;91 到 365 天 = 放缓;更久 = 停滞。所有数字来自所示日期的 GitHub API。
讨论最多的未关闭 issue
- #19 For multi-step / complex tasks, how should this skill be used properly?29 条评论 · 2026-01-12
- #230 Invitation: get planning-with-files verified on Sigistry (free, open source)5 条评论 · 2026-08-28
- #326 Consider opt-in checkbox-only re-attestation for routine progress updates4 条评论 · 2026-10-17
- #196 Add an optional hosted quick-try link for planning-with-files4 条评论 · 2026-07-08
- #380 SKILL.md is about 10k tokens: Claude Code keeps the first 5,000 after compaction, and three documented mechanisms no longer exist0 条评论 · 2026-11-10
issue 标题引自 GitHub。请打开链接确认该问题是否仍适用于你使用的版本。
05
兼容性
agent-skills
需要兼容 Agent Skills 的宿主
已通过文档验证
06
快速开始
1
$ npx skills add OthmanAdi/planning-with-files --skill planning-with-files
07
使用场景
↳在磁盘上跟踪长期编程任务。
↳在压缩或清空上下文后继续计划。
↳分别保存研究发现与进度更新。
08
同类工具
评论
登录后发表评论
暂无评论,来发表第一条吧