【免费下载链接】plannotatorAnnotate and review coding agent plans and code diffs visually, share with your team, send feedback to agents with one click.项目地址https://gitcode.com/gh_mirrors/pl/plannotator点击查看免费下载本文详解 Plannotator 复合规划技能plannotator-compound的 Claude Code 回退路径当用户没有 Plannotator 计划归档时如何利用仓库内置的 Python 解析器从~/.claude/projects/的 JSONL 会话日志中抽取ExitPlanMode否决原因完成清单统计、并行抽取、模式归约、HTML 报告生成与改进钩子注入的完整流程。读完本文你能独立运行回退模式的数据管道理解解析器的三类结果分类与人因human-reason提取机制并掌握报告各阶段在回退模式下的具体差异与约束。回退路径的定位与触发条件plannotator-compound技能的主数据源是 Plannotator 计划目录$PLANNOTATOR_DATA_DIR/plans/或~/.plannotator/plans/中的*-denied.md归档文件。当用户没有可用的 Plannotator 归档——即普通 Claude Code 用户其否决历史只存在于~/.claude/projects/的会话日志中——技能会切换到回退模式。主技能定义见 SKILL.md其 Source Selection 一节明确规定了三级数据源优先级Plannotator 归档一等路径→ Claude Code 日志二等路径→ 两者皆无时向用户询问目录、不做猜测。回退模式的目标与主技能完全一致来自 claude-code-fallback.md 的开头提取用户真实的否决理由denial reasons将其归约reduce为分类法taxonomy与纠正性提示词prompt corrections产出与主技能相同设计的 HTML 报告、相同的章节流也就是说回退模式不是另一个功能而是同一套 map-reduce 分析流水线在另一种数据源上的投影上游数据从「Plannotator markdown 归档」换成「解析器输出的 JSON part 文件」中间的抽取、归约、报告、改进钩子阶段全部保留仅在各阶段的「输入解读」和「可报告字段」上做出适配。数据源与内置解析器为什么不能直接读原始 JSONL回退模式指定唯一的可信数据源Source of Truth是仓库捆绑的解析器extract_exit_plan_mode_outcomes.py运行前必须先将该脚本路径解析为相对于技能目录的绝对路径[RESOLVED SKILL PATH]而不是使用仓库内的相对副本。解析器只依赖 Python 标准库、逐行流式读取 JSONL。从源码结构看它刻意维护同一份数据的三个视图见脚本文件头 docstring第 2–27 行严格的 Claude Code 原生分类——识别两条固定字符串批准User has approved your plan.APPROVE_PREFIX否决The user doesnt want to proceed with this tool use. The tool use was rejectedREJECT_PREFIX通用否决捕获——任何匹配的ExitPlanModetool_result 只要is_errortrue且文本非空就作为否决/错误载荷捕获即使是自定义 hook 输出或其他非原生集成产生的内容人因human-reason提取——原生内联理由原样保留非原生的自由文本载荷整体视为人类理由结构化的非原生载荷则尽量压缩为其中的引用blockquote反馈关键字符串常量定义在 第 40–48 行。原生否决理由的提取依赖两个标记classify_result第 262–312 行定位标记REASON_MARKER To tell you how to proceed, the user said:\n——用户手写理由从该标记之后开始截断标记NOTE_MARKER \n\nNote: The users next message may contain a correction or preference.——该标记之前的内容才是纯理由之后的系统提示语被剥掉每条ExitPlanMode尝试最终会落入以下结果枚举之一outcome_rank第 315–325 行outcome含义pending有ExitPlanMode调用但尚无结果如空文本的非错误结果approved_native文本以APPROVE_PREFIX开头denied_native_no_reason以REJECT_PREFIX开头但未找到REASON_MARKER或标记后为空denied_native_with_reason原生否决且提取到了用户手写理由denied_non_native_with_payloadis_errortrue的非原生拒绝携带载荷denied_non_native_no_payloadis_errortrue但文本为空non_native_other非错误、非原生的其他输出human_reason的来源字段有且仅有三种取值extract_human_reason第 228–259 行native_inline_reason原生否决文本中REASON_MARKER之后的内容non_native_freeform_payload非原生载荷被classify_reason_style判定为自由文本不以#/YOUR PLAN WAS NOT APPROVED.开头且不含\n##、\n---等结构化标记structured_quote_extraction结构化非原生载荷中提取出的 blockquote 反馈extract_blockquote_feedback第 199–225 行多个引文用空行拼接解析器存在的意义就在于剥离会话日志中的噪声通用的原生拒绝字符串、hook 包装器的样板文字等都不会进入默认的人因输出。因此文档明确要求不要直接读取~/.claude/projects/**/*.jsonl原始日志除非满足以下三种例外之一解析器运行失败用户要求进行审计级audit-level校验需要手工检查一两条可疑记录运行解析器完整命令与参数标准运行命令先创建工作目录再运行解析器。优先使用python3不可用时退回pythonmkdir -p /tmp/compound-planningpython3 [RESOLVED SKILL PATH]/scripts/extract_exit_plan_mode_outcomes.py \ --projects-dir ~/.claude/projects \ --json-out /tmp/compound-planning/claude-code-human-reasons.json \ --show-samples 0预期产出由write_json_report第 701–764 行 实现清单文件manifest/tmp/compound-planning/claude-code-human-reasons/claude-code-human-reasons.manifest.json分片文件part files/tmp/compound-planning/claude-code-human-reasons/claude-code-human-reasons.part-XXXX-of-XXXX.json注意--json-out的命名约定传入路径去掉.json后缀后作为目录名manifest 与该目录下按四位序号命名的 part 文件都放在其中。脚本执行后会在标准输出打印检测到的记录数与写出的 part 文件数Wrote JSON output: detected N records ... emitted M part file(s) plus a manifest.。完整参数表从parse_args第 77–127 行可确认全部 CLI 参数及其默认值参数默认值说明--projects-dir~/.claude/projectsClaude projects 根目录--include-subagents关闭是否包含/subagents/子目录的 JSONL默认跳过--records-filterhuman-reasons写入 JSON 输出的记录集可选all/native/native-denials/denials/human-reasons--include-non-native-denials关闭样例输出中是否包含非原生否决载荷默认样例只显示原生否决--show-samples5文本摘要中打印的否决样例条数回退流程要求传0关闭--json-out无可选JSON 报告输出路径--max-output-tokens-per-file50000写 part 文件时每文件的近似 token 预算上限回退流程使用默认的--records-filter human-reasons即默认只输出「含有可提取人类理由」的记录——这正是后续 map-reduce 阶段要处理的干净数据集。关于分片机制build_json_chunks第 541–568 行按每条记录的近似 token 数estimate_tokens用(len 3) // 4保守估算第 151–153 行累积到--max-output-tokens-per-file预算后切出一个 part。这意味着 part 文件数是数据集规模的自然函数直接决定了后文抽取阶段的批次数。扫描行为同样值得了解iter_jsonl_files使用os.walk遍历并按目录/文件名排序默认剔除subagents目录第 130–138 行scan_projects先按sessionId::tool_use_id建立每条ExitPlanMode尝试捕获input.plan的字符长度作为plan_length_chars、planFilePath、cwd、时间戳再匹配后续roleuser消息中对应tool_use_id的tool_result块来更新结果第 368–461 行。先读 Manifest再读 Part 文件文档要求读取任何 part 文件之前必须先读 manifest。manifest 提供整体数据集形状过滤后的记录总数ExitPlanMode尝试总次数原生批准 / 原生否决计数非原生否决计数part 文件列表只有在理解了整体分布之后才使用 part 文件。manifest 中的summary字段即summarize()第 464–509 行产出的完整计数器涵盖total_exit_plan_attempts、approved_native、denied_native_with_reason、denied_native_no_reason、denied_non_native_with_payload、human_reasons_total、human_reasons_native/human_reasons_non_native等全部口径后续清单与报告的「可恢复理由占比」都从这里取值。回退模式下的数据集清单Inventory在 Claude Code 回退模式下上报的数据集字段是解析器组装的否决原因数据集而不是Plannotator 的文件计数找到的人类否决理由数human denial reasons found扫描的ExitPlanMode尝试总数原生批准数native approvals可提取内联理由的原生否决数无可恢复理由的原生否决数携带可恢复载荷的非原生否决数写出的 JSON part 文件数记录中的日期范围跨越总天数去重后的会话数distinct sessions去重后的项目根 /cwd值数此外还需计算存在plan_length_chars时的平均值全部否决中含可恢复人类理由的百分比即human_reasons_total / total denials对应脚本摘要输出中的 Human reasons across all denial types 一行严禁在回退模式下虚构 Plannotator 专属清单字段不统计*-approved.md文件数不统计*.annotations.md文件数不统计*.diff.md文件数不做批准计划的行数分析如果用户特别索要这些字段应明确告知 Claude Code 日志回退模式不包含这些产物。回退模式下的历史报告检测历史报告检测Previous Report Detection同样适用。检查用户主目录或 Plannotator 计划目录${PLANNOTATOR_DATA_DIR:-~/.plannotator}/plans/中是否存在compound-planning-report*.html文件。找到后向用户提供与 Plannotator 模式相同的「增量 vs 全量」选择。关键差异在于过滤方式增量模式按时间戳过滤解析器输出而不是按文件名日期——使用每条 JSON 记录中的timestamp字段Plannotator 模式的日期嵌在YYYY-MM-DD文件名里回退模式的日期来自会话日志记录本身。若不存在历史报告使用首份报告的命名约定compound-planning-report.html否则使用下一个版本号compound-planning-report-v2.html、-v3.html……。抽取阶段批处理策略与抽取提示词回退模式下把解析器写出的 JSON part 文件视为干净的源数据集。批处理阈值小数据集 200 条记录直接读取 part 文件不启动额外 agent中数据集200–800 条记录按 part 文件或时间范围拆分为 2–4 个 agent大数据集800 条记录按 part 文件组或均衡的时间范围拆分所有抽取 agent 都应使用model: haiku——它们做的是直接的文件读取与结构化抽取不需要推理能力。每个抽取 agent 读取所分配 part 文件中的每一条记录把干净的 markdown 结果写入/tmp/compound-planning/extraction-{batch-name}.md要求写入独立输出文件而不是依赖 agent 任务输出是因为后者混入了 JSONL 框架日志、难以解析主技能对 Plannotator 模式有此说明回退模式沿用同一约定。抽取提示词模板每个回退抽取批次使用以下提示词替换 part 文件列表与输出路径You are extracting structured data from Claude Code ExitPlanMode denial records. Files to read: [JSON PART FILES] Output: Write your complete results to [OUTPUT FILE PATH] Read EVERY record in the assigned files. Each record already contains a cleaned human_reason field. Use that as the primary source text. For EACH record, extract: - Date - Session ID - Project / cwd - Topic (only if inferable from the reason or plan path; otherwise say Unknown from logs) - Human denial reason - What was specifically asked to change - Feedback type (let the content determine the category) - Notable phrases - Reason source (native_inline_reason, non_native_freeform_payload, or structured_quote_extraction) - Plan path if present - Plan length in chars if present Do NOT skip any records. One entry per record. Format each entry as: **[session_id :: tool_use_id]** - Date: ... - Project: ... - Topic: ... - Human denial reason: ... - Feedback type: ... - Specific asks: ... - Notable phrases: ... - Reason source: ... - Plan path: ... - Plan length chars: ... --- After processing all records, write the complete results to [OUTPUT FILE PATH]. State the total record count at the end of the file.注意提示词中要求记录的Reason source三值枚举与解析器写入每条记录的human_reason_source字段完全一致session_id :: tool_use_id的条目主键格式也对应解析器的make_attempt_keysessionId :: toolUseId。抽取阶段不做主题臆测Topic 只有当能从理由或计划路径推断时才填写否则写 Unknown from logs。归约阶段分类法与纠正性指令归约步骤在概念上与主模式相同产出八个维度分类法taxonomy头部模式top patterns反复出现的短语recurring phrases评审者的隐性价值观reviewer values反复出现的 agent 失误结构性要求structural requests随时间的演化纠正性提示词指令corrective prompt instructions归约 agent 使用model: sonnet与 Plannotator 模式一致当抽取文件数达到 21 个以上时同样适用两段式归约partial reduces 分组 → 最终 reduce 合并去重回退模式下对应的判断依据是 part 文件数量较多。但必须正确解读数据集的性质这是来自 Claude Code 日志的否决原因证据并非每条否决都有可恢复的人类理由批注annotations可能完全不存在「哪些做法有效」的特质往往是从反复否决反馈的反面推断出来的如果「什么有效」的证据强度弱于「什么无效」的证据必须明确说出来而不是用对称的措辞掩盖证据差异。HTML 报告的适配规则报告模板与章节顺序与主技能完全相同同一模板设计语言参见 report-template.html、同样以叙事优先narrative-first的编辑风格、同样的 7 个主要章节。回退模式的差异集中在以下几点来源标注与数据口径在报告头部 / 元信息中明确声明数据来源是 Claude Code 的ExitPlanMode否决原因只使用真实的否决原因计数、日期、短语与百分比KPI 侧栏替换Plannotator 版本使用「修订率」denied / (approved denied)KPI回退数据源中该指标可能不存在。回退模式下优先使用这组 KPI 三件套头部否决类别占比top denial category percentage恢复的人类否决理由总数total human denial reasons recovered去重后的否决类别数number of distinct denial categories如果数据中自然涌现出更好的第三指标就使用它但不得杜撰指标。页脚 / 出处说明页脚标语应说明本报告派生自 Claude Code 否决原因而非 Plannotator markdown 归档。必须声明的关键限制当human_reasons_total total denials时即 manifest 中「人类理由总数」小于否决总数必须在叙事或页脚注释中说明会话日志中有一部分否决不包含可恢复的人类手写反馈因此无法参与模式分析。这一点与解析器的三级捕获设计直接对应——denied_native_no_reason和denied_non_native_no_payload两类记录正是不可恢复的部分。版本化命名与保存位置版本化命名v2、v3……在回退模式下同样适用。报告保存到 Plannotator 计划目录${PLANNOTATOR_DATA_DIR:-~/.plannotator}/plans/目录不存在则创建这样无论数据源是什么所有复合规划报告都集中在同一位置。回退模式的总结与改进钩子结束总结应包含的信息分析结束时向用户汇报分析了多少条人类否决原因扫描了多少次ExitPlanMode尝试发现的前 3 个否决模式纠正性指令预计覆盖的否决原因百分比单条影响最大的提示词改进报告保存位置含版本号若为增量模式注明更早的发现位于上一份报告中改进钩子在回退模式下同样生效主技能 Phase 6 的改进钩子Improvement Hook在回退模式下同样适用从 Claude Code 否决原因导出的纠正性提示词指令对注入未来的规划会话同样有用流程与主技能一致。钩子的落地机制在仓库中有对应实现。Plannotator 的 hook 配置hooks.json在PreToolUse阶段匹配EnterPlanMode工具调用并执行plannotator improve-context注入内容本身由 composeImproveContext 组装——当存在改进钩子内容时会以[Plannotator Improvement Hook]头注入纠正指令The following corrective instructions were generated from analysis of previous plan denial patterns. Apply these guidelines when writing your plan:与可选的 PFM 提醒以水平线分隔。也就是说回退模式产出的报告第 7 节指令与主模式一样最终能通过同一条注入链路在每次进入 plan mode 时生效。钩子文件位于${PLANNOTATOR_DATA_DIR:-~/.plannotator}/hooks/compound/enterplanmode-improve-hook.txt写入时保持纯文本、每条指令一行、带序号无 HTML、无 markdown 围栏、无前言——钩子系统会原样注入规划上下文。若文件已存在向用户提供替换Replace/ 合并Merge/ 保留现状Keep existing三个选项合并时需按意图去重、保留更具体可执行的版本并重排序号。审计模式仅在用户明确要求时使用只有当用户明确要求查看原始否决记录或会话日志噪声时才运行审计模式命令——注意--records-filter denials会包含所有denied_native*与denied_non_native*记录filter_records的末位分支第 512–538 行即不再以「是否含人类理由」为过滤条件python3 [RESOLVED SKILL PATH]/scripts/extract_exit_plan_mode_outcomes.py \ --projects-dir ~/.claude/projects \ --records-filter denials \ --json-out /tmp/compound-planning/claude-code-all-denials.json \ --show-samples 0文档特别强调除非用户要求不要将审计模式的输出用于常规报告——常规报告必须建立在默认的 human-reasons 干净数据集之上以保持「每条记录都含可引用人类反馈」的分析前提。小结Claude Code 回退模式让plannotator-compound的分析能力从「Plannotator 归档用户」扩展到「任何使用 plan mode 的 Claude Code 用户」内置解析器把~/.claude/projects/里的ExitPlanMode结果规范化为带human_reason与human_reason_source的干净 JSON 记录manifest part 文件的双层输出支撑了按 token 预算分片的并行抽取而清单、KPI、页脚与限制声明的适配规则保证了报告在证据较弱的数据源上依然诚实可用。整条路径的工程约束可以归纳为三条默认信任解析器输出而非原始 JSONL只用真实数据、不虚构 Plannotator 专属字段当human_reasons_total小于否决总数时显式声明覆盖缺口。赞分享【免费下载链接】plannotatorAnnotate and review coding agent plans and code diffs visually, share with your team, send feedback to agents with one click.项目地址https://gitcode.com/gh_mirrors/pl/plannotator点击查看免费下载相关推荐Plannotator × Claude Code 集成实战ExitPlanMode Hook、权限模式与计划评审闭环Plannotator × Claude Code 集成实战ExitPlanMode Hook、权限模式与计划评审闭环 Plannotator 是一个面向编码Kimi Code CLI 计划模式Plan Mode全解析从 EnterPlanMode 到 ExitPlanMode 的规划与审批工作流Kimi Code CLI 计划模式Plan Mode全解析从 EnterPlanMode 到 ExitPlanMode 的规划与审批工作流 导读 Kim人工智能AI Agent代码智能体交互助手CLI工具调用Plannotator Compound 深度解析从被否决的计划档案中提炼反馈分类法与可注入的改进 HookPlannotator Compound 深度解析从被否决的计划档案中提炼反馈分类法与可注入的改进 Hook plannotator compound 是 P上一篇gridstack.js核心原理揭秘GridStackEngine布局算法深度解析下一篇Vaex在媒体领域的应用用户观看行为数据分析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考