codebee 0.1.103 → 0.1.104

package/app/core/skillpacks/market/weekly-report.md

@@ -1,71 +1,71 @@
----
-name: 周报晨报生成器守则
-note: 从任务与运行记录生成汇报：先取材再总结 / 晨报三段 / 周报四段 / 量化纪律与模板
-scopes:
-- "*"
-source: market
-market_id: weekly-report
----
-
-# 周报 / 晨报生成器守则（市场包）
-
-适用：为个人或团队生成晨报（昨日 / 今日 / 阻塞）与周报（本周 / 风险 / 下周）。
-第一原则：**先取材，再总结，不许凭印象编**。事实原料来自任务系统、运行记录、
-提交历史与日志；生成器的工作是把原料提炼成「能支撑决策」的信息，不是文学创作。
-
-## 一、取材清单（动笔前先收集）
-- 已完成：本周关闭的任务、成功结束的运行、合并的提交 / PR（git log --since 起止）。
-- 进行中：各任务当前状态、最近一次运行结论、卡在哪一步。
-- 信号类：评审打分、测试通过率、失败与重试次数、耗时的环比变化——量化的来源。
-- 未进系统的口头承诺 / 临时插活：单独列出并标注「口头事项」，不混进正式条目。
-
-## 二、晨报结构（10 行以内，站着读完）
-- **昨日完成**：2-4 条，每条写一个**结果**（不是动作）。
-- **今日计划**：2-4 条，每条可验证（「提测搜索分页」，而不是「继续做搜索」）。
-- **阻塞**：0-2 条，每条带「需要谁 / 需要什么」；没有就写「无」，不硬凑。
-
-## 三、周报结构
-1. **本周一句话**：本周最重要的结果或结论。上级只读这一行也能掌握大局。
-2. **关键进展**：按目标 / 项目分组，每组 1-3 条；每条 = 结果 + 量化 + 对照计划
-   （提前 / 按期 / 延期几天）。流水账禁止——「周一做了 A，周二做了 B」是日志，
-   不是汇报。
-3. **风险与阻塞**：每条 = 风险描述 + 影响面 + 需要的支持或缓解方案。
-   **只报风险不给方案 = 把问题原样上交；报喜不报忧 = 把雷埋到下周。**
-4. **下周计划**：2-5 条可验证的目标，与风险呼应，高风险项排前面。
-
-## 四、写作纪律
-- **量化**：能带数字必带数字（章数、字数、通过率、耗时、条数）；
-  「大量」「明显」「基本完成」这类模糊词出现即重写。
-- **结果导向**：写「完成了 X，达到 Y」；「在做 X」「推进中」放进计划或阻塞，不进步进展。
-- **动词开头、一条一意**：每条脱离上下文独立可懂。
-- **诚实纪律**：延期就写延期，附原因与新预计时间；数据缺失标注「缺」，不估算充数。
-- **篇幅纪律**：周报正文 ≤400 字（附录与链接不计）；超了说明没提炼。
-
-## 五、常见毛病对照（反例 → 正例）
-- 反例：「本周推进了 A 项目。」→ 正例：「A 项目完成搜索分页改造并提测，1 万条数据下翻页响应小于 200ms。」
-- 反例：「一切顺利。」→ 正例：「整体按期；联调依赖的 B 接口周三可用，已与对方确认。」
-- 反例：「风险：时间紧。」→ 正例：「风险：评审通过率低于阈值会触发返工，预计延期 2 天；已加排一轮预审。」
-- 反例：把 12 条流水账逐日列出 → 正例：归并成 3 条按目标分组的结果，逐日明细放附录链接。
-
-## 六、周报模板（可直接复制）
-```
-# 周报（MM.DD - MM.DD）
-
-一句话：完成xxx，指标y环比+z%；主要风险：xxx。
-
-## 关键进展
-- 【目标A】交付xxx（量化数据）；对照计划：按期 / 延期n天
-- 【目标B】……
-
-## 风险与阻塞
-- 风险：……；影响：……；需要：……（或已采取措施：……）
-
-## 下周计划
-- ……
-```
-
-## 七、自检
-- [ ] 每个数字都能在任务 / 运行记录 / git log 里找到出处
-- [ ] 无「继续推进」「持续优化」这类无信息量条目
-- [ ] 风险条目全部带缓解方案或明确的求助对象
-- [ ] 下周计划每条都有可验证的完成标志
+---
+name: 周报晨报生成器守则
+note: 从任务与运行记录生成汇报：先取材再总结 / 晨报三段 / 周报四段 / 量化纪律与模板
+scopes:
+- "*"
+source: market
+market_id: weekly-report
+---
+
+# 周报 / 晨报生成器守则（市场包）
+
+适用：为个人或团队生成晨报（昨日 / 今日 / 阻塞）与周报（本周 / 风险 / 下周）。
+第一原则：**先取材，再总结，不许凭印象编**。事实原料来自任务系统、运行记录、
+提交历史与日志；生成器的工作是把原料提炼成「能支撑决策」的信息，不是文学创作。
+
+## 一、取材清单（动笔前先收集）
+- 已完成：本周关闭的任务、成功结束的运行、合并的提交 / PR（git log --since 起止）。
+- 进行中：各任务当前状态、最近一次运行结论、卡在哪一步。
+- 信号类：评审打分、测试通过率、失败与重试次数、耗时的环比变化——量化的来源。
+- 未进系统的口头承诺 / 临时插活：单独列出并标注「口头事项」，不混进正式条目。
+
+## 二、晨报结构（10 行以内，站着读完）
+- **昨日完成**：2-4 条，每条写一个**结果**（不是动作）。
+- **今日计划**：2-4 条，每条可验证（「提测搜索分页」，而不是「继续做搜索」）。
+- **阻塞**：0-2 条，每条带「需要谁 / 需要什么」；没有就写「无」，不硬凑。
+
+## 三、周报结构
+1. **本周一句话**：本周最重要的结果或结论。上级只读这一行也能掌握大局。
+2. **关键进展**：按目标 / 项目分组，每组 1-3 条；每条 = 结果 + 量化 + 对照计划
+   （提前 / 按期 / 延期几天）。流水账禁止——「周一做了 A，周二做了 B」是日志，
+   不是汇报。
+3. **风险与阻塞**：每条 = 风险描述 + 影响面 + 需要的支持或缓解方案。
+   **只报风险不给方案 = 把问题原样上交；报喜不报忧 = 把雷埋到下周。**
+4. **下周计划**：2-5 条可验证的目标，与风险呼应，高风险项排前面。
+
+## 四、写作纪律
+- **量化**：能带数字必带数字（章数、字数、通过率、耗时、条数）；
+  「大量」「明显」「基本完成」这类模糊词出现即重写。
+- **结果导向**：写「完成了 X，达到 Y」；「在做 X」「推进中」放进计划或阻塞，不进步进展。
+- **动词开头、一条一意**：每条脱离上下文独立可懂。
+- **诚实纪律**：延期就写延期，附原因与新预计时间；数据缺失标注「缺」，不估算充数。
+- **篇幅纪律**：周报正文 ≤400 字（附录与链接不计）；超了说明没提炼。
+
+## 五、常见毛病对照（反例 → 正例）
+- 反例：「本周推进了 A 项目。」→ 正例：「A 项目完成搜索分页改造并提测，1 万条数据下翻页响应小于 200ms。」
+- 反例：「一切顺利。」→ 正例：「整体按期；联调依赖的 B 接口周三可用，已与对方确认。」
+- 反例：「风险：时间紧。」→ 正例：「风险：评审通过率低于阈值会触发返工，预计延期 2 天；已加排一轮预审。」
+- 反例：把 12 条流水账逐日列出 → 正例：归并成 3 条按目标分组的结果，逐日明细放附录链接。
+
+## 六、周报模板（可直接复制）
+```
+# 周报（MM.DD - MM.DD）
+
+一句话：完成xxx，指标y环比+z%；主要风险：xxx。
+
+## 关键进展
+- 【目标A】交付xxx（量化数据）；对照计划：按期 / 延期n天
+- 【目标B】……
+
+## 风险与阻塞
+- 风险：……；影响：……；需要：……（或已采取措施：……）
+
+## 下周计划
+- ……
+```
+
+## 七、自检
+- [ ] 每个数字都能在任务 / 运行记录 / git log 里找到出处
+- [ ] 无「继续推进」「持续优化」这类无信息量条目
+- [ ] 风险条目全部带缓解方案或明确的求助对象
+- [ ] 下周计划每条都有可验证的完成标志

package/app/core/skillpacks/market/worldview-consistency.md

@@ -1,70 +1,70 @@
----
-name: 世界观设定一致性台账守则
-note: 设定台账五件套 / 设定变更三步流程 / 高频吃书场景 / 章前查章后记闭环
-scopes:
-- novel
-- serial_novel
-source: market
-market_id: worldview-consistency
----
-
-# 世界观设定一致性台账守则（市场包）
-
-适用：连载与长篇的设定管理。吃书（前后矛盾）是长篇差评第一来源，且几乎全部
-源于**「没有台账」而不是「记性差」**——几十万字跨度下，任何人都记不住自己写过的
-每个数字与专名。本包给出一套零工具依赖的台账纪律。
-
-## 一、台账五件套（开书第一天建立，一个文件即可）
-1. **规则体系**：力量 / 能力等级、代价与限制、禁忌（什么绝对做不到）。
-   **限制比能力更重要**——能赢只是爽，不能做什么才产生剧情。
-2. **地理与组织**：地名 / 势力名清单（含从属关系）。一地一名，写法逐字固定
-   （定了「云州」就不能又写「云洲」）。
-3. **时间线**：故事内历法 + 大事件年表（含「现在」的锚点日期）；每章推进了
-   多长时间记一笔，跨章对表。
-4. **专有名词表**：自造词、称谓、咒语、物品名，逐字锁定。
-5. **数字台账**：金额、距离、年龄、队伍人数、库存——正文出现过的每个数字。
-   数字是最容易吃书的类别，因为最枯燥、最没人记。
-
-## 二、铁律
-- **设定一经正文确认，不可静默更改。**要改，走三步：登记「改了什么 / 从哪章起
-  生效」→ 排查并修订前文旧描述（或用剧情解释）→ 更新台账。三步缺一不可。
-- 设定揭示分层：世界观全貌不必第一章交底，但**已揭示的部分永不反悔**。
-  未揭示的可以随时丰富——区分「未揭示」与「矛盾」：读者无从知晓的不算吃书。
-- 新设定入正文前先对台账查重：与既有规则冲突吗？冲突就要么改新、要么改旧，
-  不许「先写上再说」。
-- 跨书 / 跨卷沿用设定时，以台账为准重读一遍，不凭上一本的记忆。
-
-## 三、高频吃书场景（评审时重点排查）
-- 时间线对不上：上一段还是「昨天」，三天后又被称作「昨天」；旅程三天的两头
-  都只过了一夜。
-- 能力凭空升级 / 降级：前面明确做不到的事，后面无解释做到了（或反之）。
-- 称谓漂移：同一人物 / 势力的称呼前后不一；称呼随剧情需要临时变化。
-- 死人复活 / 物品复用：已确认死亡的角色、已消耗或损毁的物品再次登场。
-- 年龄与亲缘错位：年龄推算矛盾、辈分关系前后颠倒。
-
-## 四、闭环纪律：章前查、章后记
-- **章前查**：写 / 审每一章前，读一遍本章涉及的台账条目（出场地名、势力、规则、
-  上次时间锚点）。30 秒的事，防 30 万字后的大返工。
-- **章后记**：本章产生的任何新设定、新专名、新数字、时间推进，**当章写入台账，
-  不过夜**。攒三章再补 = 必漏。
-- 一致性评审给出的矛盾项，当轮修复并回填台账；同类矛盾出现第二次 = 台账结构
-  要补一类条目，而不是「下次更小心一点」。
-
-## 五、台账文件模板（可直接复制）
-> ## 规则体系
-> - 等级：……；代价：……；禁忌（绝对做不到的事）：……
-> ## 地理与组织
-> - 云州（州）＞ 落霞城（城）；青岚宗（宗门，驻落霞城）
-> ## 时间线
-> - 第 1 章：启程日（春三月初七）；第 2 章：+3 日 → 三月十一
-> ## 专有名词表
-> - 破妄瞳（术法名，逐字锁定）；称「宗主」不写「掌门」
-> ## 数字台账
-> - 主角 16 岁；启程盘缠 3 两银；落霞城至云州城 700 里
-
-## 六、交稿前自检
-- [ ] 本章新设定已查重并入台账，未与既有规则冲突
-- [ ] 时间推进已记账，与上一章锚点衔接无误
-- [ ] 数字（金额 / 距离 / 人数 / 年龄）与台账一致，新数字已登记
-- [ ] 专名写法与名词表逐字一致
-- [ ] 若改过既有设定：三步流程（登记 / 排查前文 / 更新台账）已走完
+---
+name: 世界观设定一致性台账守则
+note: 设定台账五件套 / 设定变更三步流程 / 高频吃书场景 / 章前查章后记闭环
+scopes:
+- novel
+- serial_novel
+source: market
+market_id: worldview-consistency
+---
+
+# 世界观设定一致性台账守则（市场包）
+
+适用：连载与长篇的设定管理。吃书（前后矛盾）是长篇差评第一来源，且几乎全部
+源于**「没有台账」而不是「记性差」**——几十万字跨度下，任何人都记不住自己写过的
+每个数字与专名。本包给出一套零工具依赖的台账纪律。
+
+## 一、台账五件套（开书第一天建立，一个文件即可）
+1. **规则体系**：力量 / 能力等级、代价与限制、禁忌（什么绝对做不到）。
+   **限制比能力更重要**——能赢只是爽，不能做什么才产生剧情。
+2. **地理与组织**：地名 / 势力名清单（含从属关系）。一地一名，写法逐字固定
+   （定了「云州」就不能又写「云洲」）。
+3. **时间线**：故事内历法 + 大事件年表（含「现在」的锚点日期）；每章推进了
+   多长时间记一笔，跨章对表。
+4. **专有名词表**：自造词、称谓、咒语、物品名，逐字锁定。
+5. **数字台账**：金额、距离、年龄、队伍人数、库存——正文出现过的每个数字。
+   数字是最容易吃书的类别，因为最枯燥、最没人记。
+
+## 二、铁律
+- **设定一经正文确认，不可静默更改。**要改，走三步：登记「改了什么 / 从哪章起
+  生效」→ 排查并修订前文旧描述（或用剧情解释）→ 更新台账。三步缺一不可。
+- 设定揭示分层：世界观全貌不必第一章交底，但**已揭示的部分永不反悔**。
+  未揭示的可以随时丰富——区分「未揭示」与「矛盾」：读者无从知晓的不算吃书。
+- 新设定入正文前先对台账查重：与既有规则冲突吗？冲突就要么改新、要么改旧，
+  不许「先写上再说」。
+- 跨书 / 跨卷沿用设定时，以台账为准重读一遍，不凭上一本的记忆。
+
+## 三、高频吃书场景（评审时重点排查）
+- 时间线对不上：上一段还是「昨天」，三天后又被称作「昨天」；旅程三天的两头
+  都只过了一夜。
+- 能力凭空升级 / 降级：前面明确做不到的事，后面无解释做到了（或反之）。
+- 称谓漂移：同一人物 / 势力的称呼前后不一；称呼随剧情需要临时变化。
+- 死人复活 / 物品复用：已确认死亡的角色、已消耗或损毁的物品再次登场。
+- 年龄与亲缘错位：年龄推算矛盾、辈分关系前后颠倒。
+
+## 四、闭环纪律：章前查、章后记
+- **章前查**：写 / 审每一章前，读一遍本章涉及的台账条目（出场地名、势力、规则、
+  上次时间锚点）。30 秒的事，防 30 万字后的大返工。
+- **章后记**：本章产生的任何新设定、新专名、新数字、时间推进，**当章写入台账，
+  不过夜**。攒三章再补 = 必漏。
+- 一致性评审给出的矛盾项，当轮修复并回填台账；同类矛盾出现第二次 = 台账结构
+  要补一类条目，而不是「下次更小心一点」。
+
+## 五、台账文件模板（可直接复制）
+> ## 规则体系
+> - 等级：……；代价：……；禁忌（绝对做不到的事）：……
+> ## 地理与组织
+> - 云州（州）＞ 落霞城（城）；青岚宗（宗门，驻落霞城）
+> ## 时间线
+> - 第 1 章：启程日（春三月初七）；第 2 章：+3 日 → 三月十一
+> ## 专有名词表
+> - 破妄瞳（术法名，逐字锁定）；称「宗主」不写「掌门」
+> ## 数字台账
+> - 主角 16 岁；启程盘缠 3 两银；落霞城至云州城 700 里
+
+## 六、交稿前自检
+- [ ] 本章新设定已查重并入台账，未与既有规则冲突
+- [ ] 时间推进已记账，与上一章锚点衔接无误
+- [ ] 数字（金额 / 距离 / 人数 / 年龄）与台账一致，新数字已登记
+- [ ] 专名写法与名词表逐字一致
+- [ ] 若改过既有设定：三步流程（登记 / 排查前文 / 更新台账）已走完

package/app/core/step_runner.py

@@ -1,133 +1,133 @@
-# -*- coding: utf-8 -*-
-"""Step 执行器：压缩触发的重试守门（复用已渲染 prompt，不重复组装）。
-
-设计稿：docs/migration/02-context-compaction.md §1D。
-参考 dsh packages/core/agent-loop/src/agent.ts:307-378：
-  失败重试只在「前进 surface generation」时返回 {kind:'retry'}，
-  复用已渲染 PromptAssembly，不重跑 pre-step / 组装 / 用户消息准入。
-
-Tutti 语境：runner.run_agent 自带 prompt（已渲染）；重试的风险不是重复渲染
-（prompt 是同一个字符串），而是「不压缩直接重试」必然再次撑爆。
-本模块的守门：仅当 maybe_compact 真正前进了 surface generation 才重试一次。
-"""
-from __future__ import annotations
-
-import logging
-
-from .compaction import maybe_compact, DEFAULT_PRESSURE_THRESHOLD
-from .error_codes import ErrorCode
-
-log = logging.getLogger(__name__)
-
-# 触发「压缩后重试」的错误码
-_OVERFLOW_CODES = {ErrorCode.CONTEXT_OVERFLOW, ErrorCode.MAX_TOKENS}
-
-# 事前预检阈值：最近一次调用的上下文锚点已占本步模型容量九成 → 第一个请求
-# 大概率被供应商拒。只拦「大概率必死」，不提前压缩平时的高压（used() 是累计
-# 口径，比真实上下文偏大；0.8 的响应式阈值语义与此不同，勿混用）。
-_PRECHECK_RATIO = 0.9
-
-
-def _v2_compaction_tuning():
-    """settings_v2 orchestrator.compaction 微调 → (threshold|None, retain|None)。
-
-    None = 未配置（走 maybe_compact 的模块默认）；读取/注册失败静默回落。
-    retain 允许 0（尾部不保留），与 None（未配置）语义不同，勿合并。"""
-    try:
-        from .settings_schema import get as ss_get, register_default_namespaces
-        register_default_namespaces()
-        c = (ss_get("orchestrator") or {}).get("compaction") or {}
-        th = c.get("pressure_threshold")
-        rt = c.get("retain_tail_tokens")
-        return (float(th) if th else None,
-                int(rt) if rt is not None else None)
-    except Exception:
-        return None, None
-
-
-def execute_step(session, run_agent_fn, prompt, *, model: str = "",
-                 llm_caller=None, retain_tail_tokens=None, **kwargs):
-    """执行一次 step；撑爆时压缩并守门重试一次。
-
-    事前预检（借鉴 freebuff base-chat 每步容量重估）：换将切到小窗口模型后，
-    响应式路径要等供应商报 CONTEXT_OVERFLOW 才压缩——报得不干净就直接卡死。
-    先用「最近一次调用上下文 vs 本步模型容量」判一次，超阈先压缩再发。
-
-    Args:
-        session: session_log.Session（记录 replace_generation）
-        run_agent_fn: runner.run_agent（或测试替身），签名 (prompt, **kwargs) -> dict
-        prompt: 已渲染的提示词（重试时原样复用，不重新渲染）
-        model: 本步将要使用的模型名（容量与压力估算都按它算）
-        llm_caller: 压缩摘要 LLM（None = 不压缩，永不重试）
-        **kwargs: 透传 run_agent_fn
-
-    Returns:
-        (result, retried: bool)
-    """
-    v2_th, v2_rt = _v2_compaction_tuning()
-    compact_kwargs = {}
-    if retain_tail_tokens is not None:
-        compact_kwargs["retain_tail_tokens"] = retain_tail_tokens
-    elif v2_rt is not None:
-        compact_kwargs["retain_tail_tokens"] = v2_rt
-    if v2_th is not None:
-        compact_kwargs["threshold"] = v2_th
-    if llm_caller is not None and model:
-        try:
-            from .token_meter import token_meter
-            ctx = token_meter.last_context(session.run_id)
-            cap = token_meter.capacity(model)
-            if ctx > 0 and cap > 0 and ctx > cap * _PRECHECK_RATIO:
-                gen_p0 = session.replace_generation()
-                if maybe_compact(session, model=model, llm_caller=llm_caller,
-                                 run_id=session.run_id, **compact_kwargs) \
-                        and session.replace_generation() > gen_p0:
-                    log.info("precheck: last ctx~%d > %.0f%% of cap(%s)=%d, "
-                             "compacted before step", ctx, _PRECHECK_RATIO * 100,
-                             model, cap)
-        except Exception:
-            log.debug("precheck skipped", exc_info=True)
-    gen0 = session.replace_generation()
-    result = run_agent_fn(prompt, **kwargs)
-    code = result.get("error_code") or ""
-    if code not in _OVERFLOW_CODES or llm_caller is None:
-        return result, False
-    # 撑爆 → 尝试压缩
-    compacted = maybe_compact(session, model=model, llm_caller=llm_caller,
-                              run_id=session.run_id, **compact_kwargs)
-    gen1 = session.replace_generation()
-    if not compacted or gen1 <= gen0:
-        # 压缩未发生或未前进 generation：重试必然再次撑爆，不重试
-        log.info("overflow but no compaction progress (gen %s->%s), no retry",
-                 gen0, gen1)
-        return result, False
-    # 压缩生效：surface 已折叠。**真正替换 CLI 请求上下文**（2026-09-21
-    # 清最老待深挖项：此前重试仍发原 prompt + 续旧 resume 会话——摘要只进
-    # 审计日志，CLI 看到的上下文一点没小，重试必然再爆）：
-    # ①重试 prompt 改用 session 派生转录（折叠摘要 + 近尾消息，体量骤降）；
-    # ②弃 resume（旧会话本体仍是膨胀态，续上就前功尽弃）。
-    msgs = []
-    try:
-        msgs = session.derive_messages()
-    except Exception:
-        log.debug("derive_messages failed on retry", exc_info=True)
-    kwargs2 = dict(kwargs)
-    if msgs:
-        transcript = "\n\n".join("[%s] %s" % (m.get("role"), m.get("content"))
-                                 for m in msgs)
-        if len(transcript) > 24_000:
-            transcript = transcript[-24_000:]
-        retry_prompt = transcript
-        # 本步指令必须在场：被折叠/截断掉就显式补在尾部（缺失指令比重复严重）
-        tail = transcript[-2000:]
-        if prompt[:400] not in tail:
-            retry_prompt = transcript + "\n\n" + prompt
-        kwargs2.pop("resume", None)
-        log.info("compaction advanced gen %s->%s, retrying with derived "
-                 "context (%d msgs, resume dropped)", gen0, gen1, len(msgs))
-        result2 = run_agent_fn(retry_prompt, **kwargs2)
-    else:
-        log.info("compaction advanced gen %s->%s but no surface derived, "
-                 "retrying same prompt", gen0, gen1)
-        result2 = run_agent_fn(prompt, **kwargs)
+# -*- coding: utf-8 -*-
+"""Step 执行器：压缩触发的重试守门（复用已渲染 prompt，不重复组装）。
+
+设计稿：docs/migration/02-context-compaction.md §1D。
+参考 dsh packages/core/agent-loop/src/agent.ts:307-378：
+  失败重试只在「前进 surface generation」时返回 {kind:'retry'}，
+  复用已渲染 PromptAssembly，不重跑 pre-step / 组装 / 用户消息准入。
+
+Tutti 语境：runner.run_agent 自带 prompt（已渲染）；重试的风险不是重复渲染
+（prompt 是同一个字符串），而是「不压缩直接重试」必然再次撑爆。
+本模块的守门：仅当 maybe_compact 真正前进了 surface generation 才重试一次。
+"""
+from __future__ import annotations
+
+import logging
+
+from .compaction import maybe_compact, DEFAULT_PRESSURE_THRESHOLD
+from .error_codes import ErrorCode
+
+log = logging.getLogger(__name__)
+
+# 触发「压缩后重试」的错误码
+_OVERFLOW_CODES = {ErrorCode.CONTEXT_OVERFLOW, ErrorCode.MAX_TOKENS}
+
+# 事前预检阈值：最近一次调用的上下文锚点已占本步模型容量九成 → 第一个请求
+# 大概率被供应商拒。只拦「大概率必死」，不提前压缩平时的高压（used() 是累计
+# 口径，比真实上下文偏大；0.8 的响应式阈值语义与此不同，勿混用）。
+_PRECHECK_RATIO = 0.9
+
+
+def _v2_compaction_tuning():
+    """settings_v2 orchestrator.compaction 微调 → (threshold|None, retain|None)。
+
+    None = 未配置（走 maybe_compact 的模块默认）；读取/注册失败静默回落。
+    retain 允许 0（尾部不保留），与 None（未配置）语义不同，勿合并。"""
+    try:
+        from .settings_schema import get as ss_get, register_default_namespaces
+        register_default_namespaces()
+        c = (ss_get("orchestrator") or {}).get("compaction") or {}
+        th = c.get("pressure_threshold")
+        rt = c.get("retain_tail_tokens")
+        return (float(th) if th else None,
+                int(rt) if rt is not None else None)
+    except Exception:
+        return None, None
+
+
+def execute_step(session, run_agent_fn, prompt, *, model: str = "",
+                 llm_caller=None, retain_tail_tokens=None, **kwargs):
+    """执行一次 step；撑爆时压缩并守门重试一次。
+
+    事前预检（借鉴 freebuff base-chat 每步容量重估）：换将切到小窗口模型后，
+    响应式路径要等供应商报 CONTEXT_OVERFLOW 才压缩——报得不干净就直接卡死。
+    先用「最近一次调用上下文 vs 本步模型容量」判一次，超阈先压缩再发。
+
+    Args:
+        session: session_log.Session（记录 replace_generation）
+        run_agent_fn: runner.run_agent（或测试替身），签名 (prompt, **kwargs) -> dict
+        prompt: 已渲染的提示词（重试时原样复用，不重新渲染）
+        model: 本步将要使用的模型名（容量与压力估算都按它算）
+        llm_caller: 压缩摘要 LLM（None = 不压缩，永不重试）
+        **kwargs: 透传 run_agent_fn
+
+    Returns:
+        (result, retried: bool)
+    """
+    v2_th, v2_rt = _v2_compaction_tuning()
+    compact_kwargs = {}
+    if retain_tail_tokens is not None:
+        compact_kwargs["retain_tail_tokens"] = retain_tail_tokens
+    elif v2_rt is not None:
+        compact_kwargs["retain_tail_tokens"] = v2_rt
+    if v2_th is not None:
+        compact_kwargs["threshold"] = v2_th
+    if llm_caller is not None and model:
+        try:
+            from .token_meter import token_meter
+            ctx = token_meter.last_context(session.run_id)
+            cap = token_meter.capacity(model)
+            if ctx > 0 and cap > 0 and ctx > cap * _PRECHECK_RATIO:
+                gen_p0 = session.replace_generation()
+                if maybe_compact(session, model=model, llm_caller=llm_caller,
+                                 run_id=session.run_id, **compact_kwargs) \
+                        and session.replace_generation() > gen_p0:
+                    log.info("precheck: last ctx~%d > %.0f%% of cap(%s)=%d, "
+                             "compacted before step", ctx, _PRECHECK_RATIO * 100,
+                             model, cap)
+        except Exception:
+            log.debug("precheck skipped", exc_info=True)
+    gen0 = session.replace_generation()
+    result = run_agent_fn(prompt, **kwargs)
+    code = result.get("error_code") or ""
+    if code not in _OVERFLOW_CODES or llm_caller is None:
+        return result, False
+    # 撑爆 → 尝试压缩
+    compacted = maybe_compact(session, model=model, llm_caller=llm_caller,
+                              run_id=session.run_id, **compact_kwargs)
+    gen1 = session.replace_generation()
+    if not compacted or gen1 <= gen0:
+        # 压缩未发生或未前进 generation：重试必然再次撑爆，不重试
+        log.info("overflow but no compaction progress (gen %s->%s), no retry",
+                 gen0, gen1)
+        return result, False
+    # 压缩生效：surface 已折叠。**真正替换 CLI 请求上下文**（2026-09-21
+    # 清最老待深挖项：此前重试仍发原 prompt + 续旧 resume 会话——摘要只进
+    # 审计日志，CLI 看到的上下文一点没小，重试必然再爆）：
+    # ①重试 prompt 改用 session 派生转录（折叠摘要 + 近尾消息，体量骤降）；
+    # ②弃 resume（旧会话本体仍是膨胀态，续上就前功尽弃）。
+    msgs = []
+    try:
+        msgs = session.derive_messages()
+    except Exception:
+        log.debug("derive_messages failed on retry", exc_info=True)
+    kwargs2 = dict(kwargs)
+    if msgs:
+        transcript = "\n\n".join("[%s] %s" % (m.get("role"), m.get("content"))
+                                 for m in msgs)
+        if len(transcript) > 24_000:
+            transcript = transcript[-24_000:]
+        retry_prompt = transcript
+        # 本步指令必须在场：被折叠/截断掉就显式补在尾部（缺失指令比重复严重）
+        tail = transcript[-2000:]
+        if prompt[:400] not in tail:
+            retry_prompt = transcript + "\n\n" + prompt
+        kwargs2.pop("resume", None)
+        log.info("compaction advanced gen %s->%s, retrying with derived "
+                 "context (%d msgs, resume dropped)", gen0, gen1, len(msgs))
+        result2 = run_agent_fn(retry_prompt, **kwargs2)
+    else:
+        log.info("compaction advanced gen %s->%s but no surface derived, "
+                 "retrying same prompt", gen0, gen1)
+        result2 = run_agent_fn(prompt, **kwargs)
     return result2, True