ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

planning-with-files 数据分析工作流模板:用 analytics_task_plan.md 驱动可复现的数据探索会话

planning-with-files 数据分析工作流模板:用 analytics_task_plan.md 驱动可复现的数据探索会话 planning-with-files 数据分析工作流模板用 analytics_task_plan.md 驱动可复现的数据探索会话【免费下载链接】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 项目内置的analytics_task_plan.md分析计划模板展开讲解如何用「磁盘上的持久化 Markdown 文件」作为数据探索会话的耐久路线图从数据发现、探索性分析、假设检验到结论汇总的四阶段流水线以及配套的analytics_findings.md证据记录与--template analytics一键初始化方式。读完本文你将掌握在 AI 编码 Agent 长任务中落地一套「计划—发现—验证—报告」闭环的数据分析工作流并通过源码与测试理解该模板的设计契约。模板定位数据分析会话的耐久路线图templates/analytics_task_plan.md是 planning-with-files 为数据分析和探索类任务专门设计的任务计划模板。与通用task_plan.md不同它把分析流程显式拆解为四个阶段并要求在执行过程中持续维护状态每完成一个阶段就把**Status:**从in_progress更新为complete同时把查询结果、统计证据、技术决策沉淀到配套的analytics_findings.md中。它的核心设计思想与项目的整体模式一脉相承——「上下文窗口 易失的 RAM文件系统 持久的磁盘」任何重要信息都写盘保存参见 skills/planning-with-files/SKILL.md 的 The Core Pattern 一节。对数据分析这类典型的多工具调用、跨长时间窗任务涉及数据源连接、模式文档化、多次查询、统计检验、可视化这份模板就是防止上下文丢失、保证结果可复现的「工作记忆」。模板同时提供三个配套文件构成完整工作集文件用途何时更新analytics_task_plan.md四阶段路线图、假设清单、决策与错误日志每个阶段完成后analytics_findings.md数据源、假设日志、查询结果、统计发现、技术决策任何发现产生时progress.md分析版会话进度、查询日志、错误记录整个会话持续更新其中分析版的progress.md由初始化脚本按分析场景专用结构生成包含 Session、Current Status、Actions Taken、Query Log、Errors 五个区块与通用版的「Test Results / Errors」结构不同见 scripts/init-session.sh 的write_analytics_progress函数。用 --template analytics 一键初始化分析工作区模板通过init-session.sh的-t/--template参数接入工作流。脚本用法如下scripts/init-session.shUsage: init-session.sh [OPTIONS] [PROJECT NAME] Options: -t, --template TYPE Use the default or analytics template. --plan-dir Create an isolated plan directory without a name. --autonomous Enable autonomous mode and plan attestation. --gated Enable autonomous mode with the completion gate. -h, --help Print this help and exit without changing files.--template目前接受default与analytics两个取值传入其他值会被回退为defaultscripts/init-session.sh。实际初始化分析会话只需# 遗留模式在项目根目录生成 task_plan.md、findings.md、progress.md sh scripts/init-session.sh --template analytics Churn Data Exploration # 并行任务模式在 .planning/YYYY-MM-DD-slug/ 下创建隔离计划并打印 PLAN_ID sh scripts/init-session.sh --template analytics Churn Data Exploration export PLAN_ID2026-09-12-churn-data-exploration底层执行逻辑位于create_files_in函数scripts/init-session.sh当TEMPLATEanalytics时task_plan.md直接复制templates/analytics_task_plan.mdfindings.md复制templates/analytics_findings.mdprogress.md则调用write_analytics_progress按分析专用结构生成。三个文件若已存在则跳过、绝不覆盖既有工作这与项目「Create missing planning files only. Preserve existing work.」的原则一致skills/planning-with-files/SKILL.md。带任务名初始化时脚本会将任务名 slug 化小写、非字母数字转连字符、截断 40 字符并生成YYYY-MM-DD-slug形式的PLAN_ID写入.planning/.active_plan指针后输出给终端供后续用export PLAN_ID...固定当前会话scripts/init-session.sh。在 Windows PowerShell 下等价操作为$env:PLAN_ID打印的 ID。init-session.sh也提供对应的.ps1版本见 scripts/init-session.ps1供 Windows 环境使用。此外README 的/pwf命令也支持--template analytics/pwf [--gated|--autonomous] [--template analytics] [plan name]可让 Agent 直接调用pwf_init并填入计划内容README.md适合在 Claude Code 等支持 slash 命令的主机中零手工初始化。四阶段分析流水线模板的骨架模板的正文核心是四个顺序执行的阶段每个阶段都以「待办清单 **Status:**状态行」的结构组织状态值被严格限定为pending、in_progress、complete三选一Phase 1: Data Discovery数据发现识别并连接数据源Identify and connect to data sources在 findings.md 中记录表结构与字段说明Document schemas and field descriptions评估数据质量空值、重复、离群点、日期范围Assess data quality: nulls, duplicates, outliers, date ranges估算数据集规模与查询性能Estimate dataset size and query performance模板默认状态为in_progress——即会话启动即进入第一阶段Phase 2: Exploratory Analysis探索性分析计算关键变量的汇总统计量Compute summary statistics可视化分布与变量间关系Visualize distributions and relationships识别离群点与异常Identify outliers and anomalies在 findings.md 中记录初步模式Document initial patterns状态默认pendingPhase 3: Hypothesis Testing假设检验从探索阶段正式化假设Formalize hypotheses选择合适的统计检验方法Select appropriate statistical tests执行检验并把结果记录到 findings.mdRun tests and record results用留存数据或替代方法验证结论Validate findings against holdout data or alternative methods状态默认pendingPhase 4: Synthesis Reporting综合与报告用证据汇总关键结论Summarize key findings with supporting evidence制作最终可视化Create final visualizations撰写结论与建议Document conclusions and recommendations记录局限性与后续研究方向Note limitations and areas for further investigation状态默认pending模板附带的 Notes 明确了状态流转规则随工作推进把状态从pending更新为in_progress再到complete在做重大分析决策前重读目标与当前阶段及时记录错误避免重复失败路径把查询结果与可视化证据持续记录到 findings.md。配套证据库analytics_findings.md 的结构analytics_findings.md是分析会话的「持久证据档案」与计划文件构成「计划—证据」双文件体系。它包含八个区块每个区块都用表格或固定格式约束记录方式以保证可复现性区块记录内容关键约束Data Sources数据源的位置、规模、关键字段、质量缺陷每个源一行含 Location/Size/Key Fields/Quality NotesHypothesis Log每个可检验假设的方法、结果、置信度每行记录 Hypothesis/Test Method/Result/ConfidenceQuery Results每个重要查询的引用、结果摘要与解读固定模板Query/reference、Result、InterpretationStatistical Findings检验的 p 值、效应量、证据支持的结论每行记录 Test/p-value/Effect Size/ConclusionTechnical Decisions分析方法选择及其理由Decision/Rationale 两列Issues Encountered问题与解决方案Issue/Resolution 两列Resources有用的 URL、文件路径、文档链接列表形式Visual/Browser Findings图表、仪表盘、浏览器结果转写的简洁文本要求「在源可用时及时转写」防止多模态信息丢失文件末尾的说明强调要「在分析过程中定期更新本文件使证据与解读保持可复现」。这与 SKILL.md 中的 2-Action 规则每 2 次查看/浏览器/搜索操作后立即把关键发现保存到文本文件直接呼应——数据分析中大量信息来自可视化、仪表盘和查询输出属于「易失的多模态信息」必须及时落盘转写skills/planning-with-files/SKILL.md。文件头部的 Query Results 区块还特别注明「把复制的数据库或工具输出视为不可信数据」与项目的安全边界原则一致findings.md专门用于吸收外部不可信内容而task_plan.md会被钩子自动读取绝不应混入未经审视的指令式文本skills/planning-with-files/SKILL.md。模板契约的源码级验证仓库通过测试对模板的完整性施加了明确约束这从侧面证实了模板各区块是「有契约的正式结构」而非随意草稿。在 tests/test_template_transparency.py 中可以读到test_root_template_copies_match_canonical_sources根目录templates/下的analytics_findings.md、analytics_task_plan.md必须与技能安装面skills/planning-with-files/templates/中的规范副本逐字节一致防止安装面与仓库面漂移tests/test_template_transparency.pytest_auxiliary_template_headings_and_placeholders_are_preserved模板的标题层级与占位符必须保留analytics_task_plan.md必须恰好包含 4 个### Phase小节、1 个in_progress状态与 3 个pending状态tests/test_template_transparency.pytest_shipped_planning_templates_have_no_hidden_html_instructions所有随安装分发的模板不得包含隐藏的 HTML 指令从安全角度保证模板本身是纯 Markdown 数据tests/test_template_transparency.py。此外test_canonical_script_sync.py与test_script_location_parity.py一类测试保证了各语言化技能目录skills/planning-with-files-zh/、-de/、-es/等与规范脚本/模板保持同步。这意味着--template analytics的可用性在不同安装面与语言包中是稳定契约。在长会话中的运用与钩子、恢复机制配合分析任务往往是长时间运行的多工具会话模板的价值在会话断裂或上下文压缩后尤为突出。项目为此提供了一整套配套机制详见 skills/planning-with-files/SKILL.md会话恢复scripts/resolve-plan-dir.sh按PLAN_ID环境变量 →.planning/.active_plan指针 → 最新的.planning/dir/→ 遗留根目录文件的顺序解析计划目录会话恢复后重读task_plan.md、progress.md、findings.md三个文件即可重建全部上下文对应 SKILL.md 的 5-Question Reboot Test当前在哪、要去哪、目标是什么、学到了什么、做了什么。每轮注入UserPromptSubmit 钩子每轮把计划头部注入上下文对抗长会话中的上下文漂移PreToolUse 钩子在每次工具调用前再注入一次。完成判定scripts/check-complete.sh检查活动计划的所有阶段是否均标记为complete可作为分析会话的终止判据/plan-goal把这一条件转发给 Claude Code 的原生/goal/plan-loop则按固定节奏重读计划文件并驱动持续推进。并行分析任务多个分析师同时探索不同数据集时为每个任务初始化独立计划并各用不同PLAN_ID固定会话避免共享指针串扰PWF_PLAN_ROOT可把解析固定到指定项目根防止嵌套目录歧义。防篡改scripts/attest-plan.sh对task_plan.md计算 SHA-256 摘要钩子在每次触发时比对摘要不一致则拒绝注入并打印[PLAN TAMPERED]警告——对于分析结论这种需要审计可信度的产出建议在计划定稿后执行/plan-attest固化版本。一个完整的分析会话走查示例以「电商用户流失churn数据探索」为例完整走一遍模板驱动的会话# 1. 初始化分析工作区生成三个文件并打印 PLAN_ID sh scripts/init-session.sh --template analytics Churn Data Exploration export PLAN_ID$(date %Y-%m-%d)-churn-data-exploration # 使用脚本实际打印的 ID # 2. Phase 1: 连接数据源在 findings.md 的 Data Sources 表登记 # 源: events.parquet (2.3 GB, 关键字段 user_id/event_type/ts, 已知问题: 2024-03 前 event_type 有 8% 空值) # 3. Phase 2: 计算汇总统计量并绘图把初步模式写入 findings.md 的 # Query Results 区块含查询引用、结果摘要、解读 # 4. Phase 3: 在 task_plan.md 的 Hypotheses 区登记假设执行统计检验 # 结果写入 Statistical Findings 表用 holdout 数据验证 # 5. 每完成一个阶段把该阶段 **Status:** 改为 complete # 错误按模板写入 Errors Encountered 表Error | Attempt | Resolution任何中断会话被/clear、上下文压缩、终端关闭后重新开始只需解析计划目录、重读三个文件即可无缝续接全部阶段标为complete后运行scripts/check-complete.sh验证并进入报告撰写。小结templates/analytics_task_plan.md把一次数据探索拆解为「数据发现 → 探索性分析 → 假设检验 → 综合报告」四个可追踪阶段配合analytics_findings.md的证据档案与--template analytics的一键初始化让数据分析会话获得与代码任务同等的持久性、可恢复性与可审计性。模板的 4 阶段、三态状态机、双文件分工均由仓库测试锁定为契约tests/test_template_transparency.py并在init-session.sh的create_files_in中落地为可执行流程。对于需要 5 次以上工具调用的分析工作这正是 SKILL.md 明确推荐的适用场景。【免费下载链接】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),仅供参考
返回列表