企业官网建设流程全解析

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是"路线图"本体，也是钩子（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` للحالة، وحدّث القيمة كلما تقدم العمل.

这是模板的核心区。模板给出了两条硬约束：

1. 阶段数量为 3 个或更多、且每个阶段可验证；
2. 状态值只允许pending、in_progress、complete三者之一，并随工作推进持续更新。

模板预置了 5 个阶段，每个阶段由复选框清单与状态行构成：

每个阶段的清单都遵循"先写文件、再执行、边做边测"的 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，脚本将直接退出、不输出任何完成状态（见源码对TOTAL=0的专门处理，其注释明确说明"没有 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 Refactor"

slug 模式专为仓库内并行多任务设计：每个任务拥有独立计划目录，脚本把PLAN_ID打印出来，终端用export PLAN_ID=<id>把会话钉到自己的计划上，避免互相覆盖。脚本内部还内置了默认任务计划生成函数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 问重启测试"恢复状态：

模板中的目标、当前阶段、决策表与错误表正好为这 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 模式默认开启）。

使用该模板的完整工作流

综合模板结构、状态契约与配套脚本，一次标准的阿拉伯语计划会话如下：

1. 初始化：运行scripts/init-session.sh "任务名"（slug 模式）或手动复制模板到项目目录；已存在计划则复用并只补缺失文件。
2. 填写骨架：用一句话写清目标，设置 Next Step 为第一个动作，将阶段 1 状态置为in_progress。
3. 逐阶段推进：每个阶段把任务清单勾选完成后，将in_progress改为complete，更新 Next Step、决策表与错误表，并在progress.md记录会话日志。
4. 验证完成：运行scripts/check-complete.sh，确认输出ALL PHASES COMPLETE。
5. 继续扩展：若用户追加需求，直接在## المراحل下新增阶段（如阶段 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