refine

用途

refine（CocoRefine）用于维护位于 cocoplus/strategies/ 的 CocoStrategyBook——一个受版本控制、带证据归因的已验证提示词策略仓库。其核心目的是防止“自引证”失效模式：策略库的增长不能仅因代理自认为推理合理而发生。每条策略的归因必须引用已记录的评估结果，例如 CocoContract 证据记录、CocoSentinel 判定或已解决的 SecondEye 发现，而绝不能是记录代理的自我评估。

使用前需确认 .cocoplus/ 目录存在；若不存在，则输出“CocoPlus is not initialized. Run $pod init first.”并停止。

主要命令

• $refine search [query]：按任务类型、数据特征或关键词搜索 cocoplus/strategies/*.yaml，返回匹配策略及其上下文字段和弃用状态。默认排除已弃用策略，除非传入 --include-deprecated。
• $refine add：交互式收集必填字段，并向 cocoplus/strategies/<strategy-id>.yaml 写入新策略 YAML，包括身份（策略 ID、名称、从 1 开始的版本号、弃用状态 false）、上下文（任务类型、数据特征、质量约束：correctness / performance / security / maintainability）、策略内容（以明确的条件式无关形式书写，不得使用“might help”“could improve”“in some cases”等模糊措辞）、归因（会话 ID、确认有效性的 CocoContract 证据记录或质量门判定、归因时的函数版本哈希）、退化条件（观察到该策略产生更差结果的条件）。若策略内容包含模糊措辞，或未提供证据归因记录（自撰理由不充分），则拒绝添加。通过 cocorefine/refine-update --op add --file <path> 原子提交变更。
• $refine update <strategy-id>：为已有策略创建新版本，递增版本号，将上一版本内容块追加到历史区（不得删除），应用新内容。更新同样需要新的归因记录，并适用相同的自引证拒绝规则。优化轮次需包含结构化变异词汇：add_example、add_constraint、restructure、add_edge_case；每轮必须只变更一个字段，并使用二元评估标准，cocorefine/refine-update 会拒绝多字段变异和评分式评分表，以便将因果归因到单一变更。
• $refine deprecate <strategy-id> [reason]：将策略标记为 deprecated: true，记录原因与时间戳，保留版本历史（弃用不是删除）。已弃用策略不会注入未来会话的 SkillbookView。
• $refine history <strategy-id>：按从旧到新显示该策略的完整版本历史与归因记录。
• $refine status：报告 CocoStrategyBook 健康状况，包括活跃策略总数、归因通过的策略、归因过期的策略（归因中引用的函数版本哈希与当前源码不匹配）、待归因策略。

学习循环

CocoRefine 的四步循环在已完成的函数获得评估结果后运行：

1. 执行：CocoBrew 在构建开始前从 CocoStrategyBook 加载匹配策略到代理的提示词上下文（SkillbookView，只读），注入的策略 ID 记录在会话元数据中。
2. 评估：声明的 CocoContract 结果契约或启用的质量门针对函数输出运行，产生特定层级的证据记录。
3. 反思（cocorefine/refine-reflect，Tier 3 异步，可调用 Haiku）：检查实际轨迹数据，包括注入的策略 ID、函数版本哈希、可用的模型输出/评估元数据以及具体评估证据记录。此步骤禁止基于反思代理自身对策略质量的评估来归因有效性。若评估记录缺失或不完整，则不产生归因——这是有效且预期的结果，不是需要规避的错误。
4. 更新（cocorefine/refine-update）：原子应用变异。仅允许 add、update、deprecate 三种操作，不存在其他写入路径。

访问控制

优化与分析代理仅获得只读的 SkillbookView：仅当前策略内容与适用的上下文字段，不含归因元数据与版本历史。cocorefine/refine-update 是唯一写入路径，仅在学循环的更新步骤调用，任何代理不得在该上下文之外调用，以防止优化代理在会话中途修改策略库从而影响其对所评估策略的判断。

退出标准

• $refine add 拒绝任何包含模糊措辞的策略内容。
• $refine add 与 $refine update 均要求真实的、通过的 CocoContract、CocoSentinel 或已解决的 SecondEye 证据归因记录；自撰理由与不存在的引用会被拒绝。
• $refine update 创建新版本记录，不覆盖或删除先前版本。
• 优化轮次须声明一种变异策略、一个变更字段和二元评估标准。
• $refine deprecate 将策略从 SkillbookView 注入中排除，同时保留其版本历史。
• 优化代理获得只读 SkillbookView，不能直接调用 cocorefine/refine-update。
• 当评估记录缺失或不完整时，cocorefine/refine-reflect 不产生归因。

限制

refine 依赖 CocoPlus 初始化环境（.cocoplus/）；策略必须严格使用明确指令式表述；归因必须引用已记录的评估证据，不能由代理自行判断；优化轮次一次只能变更一个字段，并使用二元评估标准；写入权限严格限于学习循环的更新步骤。资料未说明该工具是否收费、是否有独立图形界面或非 CocoPlus 环境下的使用方式。