planning-with-files 阿拉伯语 task_plan.md 模板解析构建 AI Agent 的持久化任务路线图【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60 agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files导读本文围绕开源仓库 planning-with-files 中阿拉伯语AR国际化变体提供的 task_plan.md 模板系统讲解这张持久化任务路线图的结构设计、状态机约定与配套脚本机制。该模板是该技能面向阿拉伯语用户的正式交付物与英文原版模板完全同构用于为 AI 编码 Agent 的复杂任务建立磁盘上的工作记忆。读完本文你将掌握如何用这一模板组织多阶段任务、理解pending/in_progress/complete三种状态为何必须保留英文字面值这与完成门控脚本的匹配逻辑直接相关并能在自己的项目中正确初始化、更新与交付任务计划。模板在整体架构中的位置planning-with-files 的核心思想用一句话概括把 AI Agent 的上下文窗口当作易失的 RAM把文件系统当作持久的磁盘——任何重要信息都应落盘。整套技能围绕三个文件展开文件职责更新时机task_plan.md阶段、进度、决策每个阶段完成后findings.md研究、发现任何发现之后progress.md会话日志、测试结果整个会话期间其中task_plan.md是路线图本体也是钩子hook在每次工具调用时自动注入上下文的文件见 SKILL.md 的安全边界说明。阿拉伯语变体的模板存放在仓库的 i18n 目录下与英文模板 skills/planning-with-files/templates/task_plan.md 一一对应两者均通过测试 tests/test_skill_frontmatter_valid.py 等校验脚本保持一致性。阿拉伯语模板的完整结构模板文件本身是一份带使用说明的可执行文档它既是最终交付物的骨架又内嵌了每个字段的填写指引。以下按实际文件顺序逐段解析字段名保留原文说明以中文给出。1. 标题与引言# خطة المهمة: [وصف مختصر]文件以# 任务计划[简要描述]开头随后紧跟一段指引将此文件用作任务的持久路线图。在复杂工作开始之前创建它并在阶段变化时保持其更新。这段引言奠定了模板的双重身份先建计划、后动手执行是硬性要求不是可选建议。2. 目标الهدف## الهدف صف النتيجة النهائية المقصودة في جملة واحدة واضحة. [جملة واحدة تصف الحالة النهائية]目标区要求用一句话描述期望的最终状态。这一约束意义重大check-complete.sh以及各 v3 模式的完成门控都以task_plan.md的磁盘内容为判定依据而不是对话记录一个清晰、可验证的目标句是后续所有阶段自检的锚点。3. 下一步الخطوة التالية## الخطوة التالية سجّل الإجراء الوحيد الذي يجب تنفيذه تاليًا. حدّثه كلما تغيرت المرحلة النشطة أو الإجراء الفوري. [الإجراء التالي الوحيد. حدّثه كلما تغيرت حالة المرحلة.]下一步永远只记录唯一一个即将执行的动作且每当活动阶段或即时动作变化时都要更新。这与技能核心规则第 4 条每次阶段状态变化都要刷新 Next Step直接呼应见 阿拉伯语 SKILL.md——它保证 Agent 在任何时刻都知道当下该做什么。4. 当前阶段المرحلة الحالية## المرحلة الحالية اذكر المرحلة التي يجري العمل عليها الآن. المرحلة 1用于快速标识正在进行的阶段与下方 Phases 小节中的**Status:**状态机配合使用。5. 阶段划分المراحل## المراحل قسّم المهمة إلى ثلاث مراحل قابلة للتحقق أو أكثر. استخدم فقط pending أو in_progress أو complete للحالة، وحدّث القيمة كلما تقدم العمل.这是模板的核心区。模板给出了两条硬约束阶段数量为 3 个或更多、且每个阶段可验证状态值只允许pending、in_progress、complete三者之一并随工作推进持续更新。模板预置了 5 个阶段每个阶段由复选框清单与状态行构成阶段标题阿拉伯语任务清单要点初始状态阶段 1需求与发现理解用户意图确定约束与需求将发现记录到 findings.mdin_progress阶段 2规划与结构确定技术方案必要时创建项目结构记录决策及理由pending阶段 3实施逐步执行计划先写代码文件再执行增量测试pending阶段 4测试与验证验证全部需求将测试结果记录到 progress.md修复发现的问题pending阶段 5交付审查所有输出文件确认交付物完整交付给用户pending每个阶段的清单都遵循先写文件、再执行、边做边测的 Agent 工作纪律。值得注意的是任务项使用- [ ]复选框而阶段状态使用独立的- **الحالة:** in_progress行——两者分别服务于人类可读性和脚本可解析性。6. 关键问题الأسئلة الرئيسية## الأسئلة الرئيسية سجّل الأسئلة المهمة، واستبدلها بالإجابات عندما تُحسم. 1. [سؤال للإجابة عنه] 2. [سؤال للإجابة عنه]用于登记悬而未决的重要问题问题一旦有结论就用答案替换问题本身。这是把未决事项显式外化到磁盘防止它们在上下文压缩compaction后丢失。7. 已做决策القرارات المتخذة## القرارات المتخذة سجّل القرارات المهمة وسبب كل قرار. | القرار | المبررات | |--------|----------| | | |用两列表格决策 / 理由记录关键选择及其原因保证决策理由事后可追溯——这是多轮、长时任务中为什么当初这么选的唯一可靠来源。8. 遇到的错误الأخطاء التي تمت مواجهتها## الأخطاء التي تمت مواجهتها سجّل كل خطأ مميز ورقم المحاولة والحل. غيّر النهج قبل إعادة محاولة إجراء فاشل. | الخطأ | المحاولة | الحل | |-------|----------|------| | | 1 | |三列表格错误 / 尝试次数 / 解决方案并明确要求在重试失败操作前改变方法。这对应技能核心规则第 5、6 条记录所有错误、绝不重复失败。从源码看该要求与3-Strike 错误协议诊断修复 → 换方法 → 重新思考三次失败后升级给用户一致其本质是把失败经验固化为可检索的表格而非上下文中的瞬时记忆。9. 注意事项ملاحظات## ملاحظات - حدّث حالة المرحلة مع تقدم العمل: من pending إلى in_progress ثم complete. - أعد قراءة الهدف والخطوة التالية قبل القرارات المهمة. - سجّل الأخطاء فورًا كي لا تتكرر الأساليب الفاشلة.模板以三条运维纪律收尾状态按pending → in_progress → complete单向推进重大决策前重读目标与下一步错误即时登记以防重蹈覆辙。状态机契约为什么状态标记必须保留英文这是使用该模板以及所有 i18n 变体时最关键的技术约束。虽然模板正文全部阿拉伯语化但阶段状态行必须保持英文字面值**الحالة:** in_progress**Status:** complete英文原版写法原因在 commands/plan-ar.md 的命令文件中写得非常明确状态标记保持英文原样**Status:** in_progress和**Status:** complete因为check-complete.sh用grep -F搜索它们翻译会禁用完成门控。从 scripts/check-complete.sh 的源码可以印证这一机制TOTAL$(grep -c ### Phase $PLAN_FILE || true) COMPLETE_PRIMARY$(grep -cF **Status:** complete $PLAN_FILE || true) IN_PROGRESS_PRIMARY$(grep -cF **Status:** in_progress $PLAN_FILE || true) PENDING_PRIMARY$(grep -cF **Status:** pending $PLAN_FILE || true)脚本对阶段总数用正则### Phase计数阶段标题必须以英文Phase开头才能被识别对完成/进行中/待定状态用grep -cF做固定字符串匹配——-F意味着不做正则解释、逐字匹配任何翻译或改写都会导致计数归零。脚本还会对行内格式[complete]/[in_progress]/[pending]做兼容计数并按字段取较大值防止混用格式时漏计但它不会识别任何本地化后的状态词。这一设计的实际后果是阶段标题必须保留英文Phase N:前缀阿拉伯语标题可跟在后面否则TOTAL计为 0脚本将直接退出、不输出任何完成状态见源码对TOTAL0的专门处理其注释明确说明没有 Phase 标题就不是阶段化计划宁可不报也不能报虚假的 0/0状态值必须保留pending/in_progress/complete三个英文单词本地化只作用于说明性文字、任务清单与表格表头不能触及脚本的解析锚点。这也是测试 tests/test_plan_regression_guard.py 等所保障的兼容性边界——仓库通过版本化测试锁死了模板与脚本之间的解析契约。模板如何被脚本驱动从初始化到完成判定初始化init-session.sh模板的两种使用方式由 scripts/init-session.sh 支持# 传统模式在项目根目录创建 task_plan.md / findings.md / progress.md ./scripts/init-session.sh # slug 模式在 .planning/日期-slug/ 下创建隔离计划并打印 PLAN_ID ./scripts/init-session.sh Backend Refactorslug 模式专为仓库内并行多任务设计每个任务拥有独立计划目录脚本把PLAN_ID打印出来终端用export PLAN_IDid把会话钉到自己的计划上避免互相覆盖。脚本内部还内置了默认任务计划生成函数write_default_task_plan与模板同构并且只在文件不存在时才创建——只补缺失文件、绝不覆盖已有工作。v3 的自主/门控模式--autonomous/--gated则会在计划目录写入.mode标记、生成 16 位十六进制.nonce用于注入内容的定界符防混淆、重置.stop_blocks计数器并对计划做默认开启的 SHA-256 证明attestation。完成判定check-complete.sh阶段推进到complete后由 scripts/check-complete.sh 判定整个计划是否完成。它的解析完全依赖上述状态契约全部阶段complete且总数大于 0 时输出ALL PHASES COMPLETE (n/n)否则输出Task in progress (n/n phases complete)并分别报告in_progress与pending的阶段数--gate模式v3 门控下只有满足全部 5 个守卫条件.mode含gate、存在 in_progress 阶段、Stop 钩子未处于强制续跑、阻塞计数低于上限PWF_GATE_CAP默认 20、ledger 有推进才会输出{decision:block,...}阻止 Agent 停止。状态推进与 5 问重启测试模板的pending → in_progress → complete推进对应技能规则更新于行动之后每完成一个阶段就更新状态、登记错误、记录受影响文件。会话重启/clear、压缩或断线后Agent 靠5 问重启测试恢复状态问题答案来源我在哪task_plan.md 中的当前阶段我要去哪剩余阶段目标是什么计划中的目标陈述我学到了什么findings.md我做了什么progress.md模板中的目标、当前阶段、决策表与错误表正好为这 5 个问题提供了全部答案来源。配套文件与安全边界task_plan.md不是孤立的阿拉伯语变体还提供 findings.md 模板需求、研究结果、技术决策、问题、资源、视觉/浏览器结果与 progress.md 模板会话记录、测试结果表、错误日志、5 问重启测试表三者共同构成研究 → 计划 → 日志的闭环。安全边界上阿拉伯语 SKILL.md 明确警告task_plan.md会被钩子在每次工具调用时反复注入上下文因此它是间接提示注入的高价值目标。外部内容网页、API 返回等不可信材料只能写入findings.md绝不能写进task_plan.md——否则恶意指令会在每次工具调用时被放大。task_plan.md定稿后建议运行/plan-attest或scripts/attest-plan.sh做 SHA-256 证明钩子在每次触发时比对哈希发现计划被改动即以[PLAN TAMPERED]警告并拒绝注入该机制在 v3 模式默认开启。使用该模板的完整工作流综合模板结构、状态契约与配套脚本一次标准的阿拉伯语计划会话如下初始化运行scripts/init-session.sh 任务名slug 模式或手动复制模板到项目目录已存在计划则复用并只补缺失文件。填写骨架用一句话写清目标设置 Next Step 为第一个动作将阶段 1 状态置为in_progress。逐阶段推进每个阶段把任务清单勾选完成后将in_progress改为complete更新 Next Step、决策表与错误表并在progress.md记录会话日志。验证完成运行scripts/check-complete.sh确认输出ALL PHASES COMPLETE。继续扩展若用户追加需求直接在## المراحل下新增阶段如阶段 6、7在progress.md新开会话条目按原流程继续——这正是模板 Notes 中完成后继续条款的用途。小结阿拉伯语task_plan.md模板不是一个简单的表格占位文件而是一份结构即协议的工程交付物目标/下一步/当前阶段提供导航5 阶段清单提供可验证的执行粒度决策与错误表格提供可追溯的审计痕迹而保留英文的状态标记则确保它无缝接入check-complete.sh的完成门控与 v3 模式的终止判定。理解这份模板就等于理解了 planning-with-files 整个文件式规划体系在 i18n 变体下如何保持本地化文案、国际化协议的双轨设计。【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60 agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考