pull 是 CocoPlus 体系中的上下文压缩技能，用于将文件或目录中的文件精炼为 pull 产物（.pull.md），在保留所有决策相关信息的前提下降低 token 消耗。CocoHarvest 在阶段输入超过配置的 token 阈值时会自动使用 pull 文件。
用途 主要面向大型上下文文件的压缩，包括评估产物（evaluation artifacts）、schema 导出（schema dumps）、查询结果集（query result sets）和分析输出（analysis outputs）。支持输入格式为 .md、.json、.sql、.txt。
使用前提
- .cocoplus/ 必须已初始化（先运行 $pod init）。
- 目标文件或目录必须存在。
参数
- <target>（必填）：要精炼的文件路径或目录。
- --validate（可选）：精炼后运行往返重构测试。
- --human（可选）：生成人类可读的叙事摘要，而非面向 LLM 的密集 pull 文件。
两种输出模式
- 默认模式（无标志）：生成 <target>.pull.md，机器密集、面向 LLM 优化、决策值逐字保留，供 CocoHarvest 自动使用。
- --human 模式：生成 <target>.pull-human.md，面向利益相关者的散文叙事。不会被 CocoHarvest 使用，且不会覆盖 .pull.md 机器输出。
默认模式的处理流程
- 验证初始化：检查 .cocoplus/ 是否存在，否则提示先运行 $pod init 并退出。
- 验证目标：检查目标是否存在，否则提示路径错误并退出。
- 目录处理：若目标是目录，枚举符合条件的文件并逐个独立处理，最后在 <target>/pull-manifest.md 生成目录清单，列出每个文件、压缩比和可靠性（如使用 --validate）。
- 结构分析：由 Haiku 子代理读取目标文件，生成 JSON 结构映射，识别各分区及其内容类型（schema_definition、query_result、narrative_analysis、tabular_data、decision_conclusion、code_block、metadata），并逐分区分类为 decision_bearing（阈值、字段名、标准、约束值等必须逐字保留）或 background（支撑决策的上下文与推理）。若结构分析失败，则直接进入精炼，并在头部标注 structure_guided: false。
- 精炼：由 Sonnet 子代理读取结构映射（如可用）和目标文件，按顺序应用以下规则：
- 规则 1 逐字保留（不可协商）：decision_bearing 内容原样复制，不转述、不取整、不同义替换。
- 规则 2 叙事压缩：将解释性段落压缩为结论，结论须从叙述中提取而非推断。
- 规则 3 去重：跨分区重复内容合并为单一权威引用并注明出现次数。
- 规则 4 表格压缩：超过 20 行的表格替换为前 5 行原文加统计摘要（行数、数值列 min/max/mean、分类列唯一值数），并注明源文件行数。
- 写入输出：在源文件旁写入 <source-name>.pull.md，头部包含 pull_source、pull_timestamp、original_tokens_estimate、pull_tokens_estimate、compression_ratio、structure_guided、reliability 等字段。若 pull 文件比源文件更大（未实现压缩），在头部记录 distillation_outcome: no_reduction，并以源文件作为 CocoHarvest 输入，不强行生成膨胀产物。
- 更新清单：在 .cocoplus/pull/manifest.json（不存在则创建）追加条目，包含 source、pull、timestamp、compression_ratio、reliability、distillation_outcome。
--validate 往返重构测试 在精炼完成后依次运行三个子代理：
- V1 探针问题生成器（Haiku）：读取源文件（非 pull 文件），生成恰好 10 个探针问题，覆盖主要决策相关事实（至少 4 个）、源中关键约束（至少 2 个），且每个主要分区至少一个问题。写入临时文件 <target>.pull-probes.json。
- V2 验证代理（Sonnet）：仅读取 <target>.pull.md，回答全部 10 个问题，答案写入临时内存。
- V3 真值提取器（Sonnet）：读取源文件，回答相同问题，写入临时内存。 比较 V2 与 V3 答案：匹配定义为相同数值（百分比 1% 容差内）、相同字段/函数名、相同是/否结论。匹配分 = 匹配数 / 10 × 100。分数 ≥85% 记为 reliability: high，否则为 low；并将 validation_score 与 divergent_probes 追加到 pull 文件头部，同步更新清单中的可靠性。最后删除临时探针文件。若分数低于 85%，输出警告说明 CocoHarvest 将不会自动使用该文件而是加载原始文件。
--human 模式流程 验证初始化与目标后，启动 Sonnet 叙事子代理，读取目标文件并生成面向非技术利益相关者的散文摘要。规则包括：结论先行（倒金字塔）、使用平实语言（避免 SQL 与 JSON 字段名）、数值结合上下文表达（如“88% 准确率——高于 discuss.md 中设定的 85% 阈值”）、除源内容确实需要外不超过 500 字、不包含原始表格而转译为句子或简短要点。输出写入 <target>.pull-human.md，头部包含 pull_source、pull_timestamp、pull_mode: human、audience: stakeholder。human 模式不更新 .cocoplus/pull/manifest.json，也不覆盖已有 .pull.md。
CocoHarvest 的自动使用 CocoHarvest 准备阶段输入时检查每个输入文件的估算 token 数。若超过 .cortex-plugin/plugin.json 中 cocoHarvest.pullThreshold（默认 8,000 tokens）：存在对应 .pull.md 且可靠性高则使用 pull 文件并记录日志；存在但可靠性低则使用源文件并警告；不存在则自动调用 $pull <file> 并使用结果。阶段日志始终记录使用的是源文件还是 pull 文件。
存储
- pull 产物与源文件同目录存放（<source-name>.pull.md）。
- 清单位于 .cocoplus/pull/manifest.json。
- pull 文件默认被 gitignore（属于派生产物）；如需提交运行 $pod config set pull.commit=true。
错误情况
- 目标不存在：输出“Target not found: <target>. Check the path and try again.”并退出。
- 结构分析子代理失败：继续直接精炼，头部标注 structure_guided: false。
- 精炼产物大于源文件：记录 distillation_outcome: no_reduction，不写入膨胀的 pull 文件。
- 验证 V1/V2/V3 子代理失败：输出验证未能完成的提示，pull 文件仍写入但可靠性标记为 pending。
- 无法写入清单：记录警告，不阻断精炼输出。
完成标准
- <target>.pull.md 已与源文件一同写入（或记录了 no_reduction）。
- .cocoplus/pull/manifest.json 已更新新条目。
- 如使用 --validate，验证摘要已追加到 pull 文件头部，可靠性设为 high 或 low。
- 输出展示原始 token 估算、pull token 估算、压缩百分比与可靠性（如已验证）。
限制与禁止事项 默认模式不得转述数值、阈值、字段名或约束值；V2 验证代理必须在 V1 生成问题之后运行且只能读取 pull 文件（防止循环测试）；不得由同一代理既生成问题又回答问题；分数低于 85% 不得标记为 high；CocoHarvest 不得自动使用低可靠性 pull 文件；不得删除源文件；不得在 CocoHarvest 中使用 --human 输出；--human 模式不得覆盖已有 .pull.md。