codebee 0.1.103 → 0.1.105

package/app/core/branching.py

@@ -1,137 +1,137 @@
-# -*- coding: utf-8 -*-
-"""多线剧情推演（inkos 借鉴 2026-09-23）：写章前一次调用生成 2-3 条分支
-节拍计划，自带推荐择优，选中分支注入本章 BEATS；全部分支追加审计文件
-.codebee/branch-plans.md 供回看。计划级赛马——比 prose 级 Best-of-N 省
-一个数量级的 token。"""
-from __future__ import annotations
-
-import logging
-import os
-
-log = logging.getLogger(__name__)
-
-BRANCH_PLAN_PROMPT = """你是网文剧情策划。基于全书设定与上一章结尾，为下一章生成 __N__ 条**彼此方向不同**的剧情分支计划。
-
-要求：
-- 每条分支给出：本章节拍（50-120 字：事件/冲突/推进）+ 章末钩子（一句话）+ 一句取舍理由（为什么选/不选它）
-- 分支之间要有真实的方向差异（不同冲突来源/不同人物决定/不同信息揭示），不是同一件事换措辞
-- 你是策划也是评委：综合大纲意图、前情、人物动机，推荐其中最有力的一条
-
-只输出一个 ```json 代码块：
-{"branches": [{"beats": "…", "hook": "…", "why": "…"}, …], "pick": 0}
-pick = 推荐分支的下标（0 起）。
-
-## 全书目标
-__GOAL__
-
-## 大纲上下文（本章前后）
-__OUTLINE__
-
-## 上一章结尾
-__PREV__
-"""
-
-
-def plan_branches(run_id, task, i, goal, outline_txt, prev, n, *, log_path=None):
-    """生成并择优一条分支计划。返回 (beats, hook) 或 None（失败/未启用走原大纲）。
-
-    编排者一次调用产 N 条+自荐 pick；失败静默回落原大纲节拍（推演是增强
-    不是闸门）。全部分支连同 pick 追加 .codebee/branch-plans.md 审计。"""
-    if n < 2:
-        return None
-    # Token 压力守卫：压力 > 0.7 时跳过推演——每次推演是额外 4000
-    # max_tokens 编排者调用；长篇后期预算紧张时推演是第一个该省的增强
-    # （压缩守卫先跑、推演不跑，省下的预算留给正文章稿）。
-    try:
-        from . import token_meter
-        if token_meter.pressure_ratio(run_id) > 0.7:
-            return None
-    except Exception:
-        pass
-    from . import modelhub, runner
-    orch = modelhub.resolve_orchestrator()
-    if not orch:
-        return None
-    prov, model = orch
-    prompt = (BRANCH_PLAN_PROMPT
-              .replace("__N__", str(n))
-              .replace("__GOAL__", goal[:600])
-              .replace("__OUTLINE__", outline_txt[:3000])
-              .replace("__PREV__", (prev or "（开篇）")[-1200:]))
-    res = modelhub.chat(prov["id"], model, prompt, max_tokens=4000, timeout=300)
-    if not res.get("ok"):
-        return None
-    data = runner.extract_json(res.get("text") or "")
-    branches = (data or {}).get("branches") if isinstance(data, dict) else None
-    if not isinstance(branches, list):
-        return None
-    usable = [b for b in branches
-              if isinstance(b, dict) and str(b.get("beats") or "").strip()]
-    if len(usable) < 2:
-        return None
-    try:
-        pick = int(data.get("pick") or 0)
-    except (TypeError, ValueError):
-        pick = 0
-    pick = max(0, min(pick, len(usable) - 1))
-    chosen = usable[pick]
-    try:
-        from . import store as _store
-        wd = _store.run_workdir(run_id) or ""
-    except Exception:
-        wd = ""
-    _append_audit(wd, i, usable, pick)
-    return (str(chosen["beats"]).strip()[:300],
-            str(chosen.get("hook") or "").strip()[:80] or None)
-
-
-def _append_audit(workdir, chapter, branches, pick):
-    """全部分支追加 .codebee/branch-plans.md（失败静默——审计是增强）。"""
-    if not workdir:
-        return
-    try:
-        p = _audit_path(workdir)
-        os.makedirs(os.path.dirname(p), exist_ok=True)
-        with open(p, "a", encoding="utf-8") as f:
-            if f.tell() == 0:
-                f.write("# 多线剧情推演（每章分支计划与择优，供回看）\n\n")
-            f.write("## 第 %d 章\n" % chapter)
-            for k, b in enumerate(branches):
-                mark = "✅ " if k == pick else ""
-                f.write("- %s%s（钩子：%s）——%s\n" % (
-                    mark, str(b.get("beats") or "")[:160],
-                    str(b.get("hook") or "")[:60],
-                    str(b.get("why") or "")[:120]))
-            f.write("\n")
-    except Exception:
-        pass
-
-
-def _audit_path(workdir):
-    """审计文件路径（越界拒绝：workdir 必须存在的目录）。"""
-    from pathlib import Path
-    root = Path(workdir).resolve()
-    if not root.is_dir():
-        raise ValueError("workdir 必须是已存在的目录")
-    return root / ".codebee" / "branch-plans.md"
-
-
-def mark_stale(workdir, chapter):
-    """正史重写后旧推演标过期（inkos 借鉴：分支计划随正史失效）。
-
-    修订步骤改写章稿后，本章的分支计划节头追加「（已过期，正史已重写）」——
-    防止后续翻看审计时把旧推演当成当前正史的来源。失败静默。"""
-    if not workdir:
-        return
-    try:
-        p = _audit_path(workdir)
-        if not p.is_file():
-            return
-        txt = p.read_text(encoding="utf-8", errors="replace")
-        header = "## 第 %d 章\n" % chapter
-        stale_header = "## 第 %d 章（已过期，正史已重写）\n" % chapter
-        if header in txt and stale_header not in txt:
-            p.write_text(txt.replace(header, stale_header, 1),
-                         encoding="utf-8")
-    except Exception:
-        pass
+# -*- coding: utf-8 -*-
+"""多线剧情推演（inkos 借鉴 2026-09-23）：写章前一次调用生成 2-3 条分支
+节拍计划，自带推荐择优，选中分支注入本章 BEATS；全部分支追加审计文件
+.codebee/branch-plans.md 供回看。计划级赛马——比 prose 级 Best-of-N 省
+一个数量级的 token。"""
+from __future__ import annotations
+
+import logging
+import os
+
+log = logging.getLogger(__name__)
+
+BRANCH_PLAN_PROMPT = """你是网文剧情策划。基于全书设定与上一章结尾，为下一章生成 __N__ 条**彼此方向不同**的剧情分支计划。
+
+要求：
+- 每条分支给出：本章节拍（50-120 字：事件/冲突/推进）+ 章末钩子（一句话）+ 一句取舍理由（为什么选/不选它）
+- 分支之间要有真实的方向差异（不同冲突来源/不同人物决定/不同信息揭示），不是同一件事换措辞
+- 你是策划也是评委：综合大纲意图、前情、人物动机，推荐其中最有力的一条
+
+只输出一个 ```json 代码块：
+{"branches": [{"beats": "…", "hook": "…", "why": "…"}, …], "pick": 0}
+pick = 推荐分支的下标（0 起）。
+
+## 全书目标
+__GOAL__
+
+## 大纲上下文（本章前后）
+__OUTLINE__
+
+## 上一章结尾
+__PREV__
+"""
+
+
+def plan_branches(run_id, task, i, goal, outline_txt, prev, n, *, log_path=None):
+    """生成并择优一条分支计划。返回 (beats, hook) 或 None（失败/未启用走原大纲）。
+
+    编排者一次调用产 N 条+自荐 pick；失败静默回落原大纲节拍（推演是增强
+    不是闸门）。全部分支连同 pick 追加 .codebee/branch-plans.md 审计。"""
+    if n < 2:
+        return None
+    # Token 压力守卫：压力 > 0.7 时跳过推演——每次推演是额外 4000
+    # max_tokens 编排者调用；长篇后期预算紧张时推演是第一个该省的增强
+    # （压缩守卫先跑、推演不跑，省下的预算留给正文章稿）。
+    try:
+        from . import token_meter
+        if token_meter.pressure_ratio(run_id) > 0.7:
+            return None
+    except Exception:
+        pass
+    from . import modelhub, runner
+    orch = modelhub.resolve_orchestrator()
+    if not orch:
+        return None
+    prov, model = orch
+    prompt = (BRANCH_PLAN_PROMPT
+              .replace("__N__", str(n))
+              .replace("__GOAL__", goal[:600])
+              .replace("__OUTLINE__", outline_txt[:3000])
+              .replace("__PREV__", (prev or "（开篇）")[-1200:]))
+    res = modelhub.chat(prov["id"], model, prompt, max_tokens=4000, timeout=300)
+    if not res.get("ok"):
+        return None
+    data = runner.extract_json(res.get("text") or "")
+    branches = (data or {}).get("branches") if isinstance(data, dict) else None
+    if not isinstance(branches, list):
+        return None
+    usable = [b for b in branches
+              if isinstance(b, dict) and str(b.get("beats") or "").strip()]
+    if len(usable) < 2:
+        return None
+    try:
+        pick = int(data.get("pick") or 0)
+    except (TypeError, ValueError):
+        pick = 0
+    pick = max(0, min(pick, len(usable) - 1))
+    chosen = usable[pick]
+    try:
+        from . import store as _store
+        wd = _store.run_workdir(run_id) or ""
+    except Exception:
+        wd = ""
+    _append_audit(wd, i, usable, pick)
+    return (str(chosen["beats"]).strip()[:300],
+            str(chosen.get("hook") or "").strip()[:80] or None)
+
+
+def _append_audit(workdir, chapter, branches, pick):
+    """全部分支追加 .codebee/branch-plans.md（失败静默——审计是增强）。"""
+    if not workdir:
+        return
+    try:
+        p = _audit_path(workdir)
+        os.makedirs(os.path.dirname(p), exist_ok=True)
+        with open(p, "a", encoding="utf-8") as f:
+            if f.tell() == 0:
+                f.write("# 多线剧情推演（每章分支计划与择优，供回看）\n\n")
+            f.write("## 第 %d 章\n" % chapter)
+            for k, b in enumerate(branches):
+                mark = "✅ " if k == pick else ""
+                f.write("- %s%s（钩子：%s）——%s\n" % (
+                    mark, str(b.get("beats") or "")[:160],
+                    str(b.get("hook") or "")[:60],
+                    str(b.get("why") or "")[:120]))
+            f.write("\n")
+    except Exception:
+        pass
+
+
+def _audit_path(workdir):
+    """审计文件路径（越界拒绝：workdir 必须存在的目录）。"""
+    from pathlib import Path
+    root = Path(workdir).resolve()
+    if not root.is_dir():
+        raise ValueError("workdir 必须是已存在的目录")
+    return root / ".codebee" / "branch-plans.md"
+
+
+def mark_stale(workdir, chapter):
+    """正史重写后旧推演标过期（inkos 借鉴：分支计划随正史失效）。
+
+    修订步骤改写章稿后，本章的分支计划节头追加「（已过期，正史已重写）」——
+    防止后续翻看审计时把旧推演当成当前正史的来源。失败静默。"""
+    if not workdir:
+        return
+    try:
+        p = _audit_path(workdir)
+        if not p.is_file():
+            return
+        txt = p.read_text(encoding="utf-8", errors="replace")
+        header = "## 第 %d 章\n" % chapter
+        stale_header = "## 第 %d 章（已过期，正史已重写）\n" % chapter
+        if header in txt and stale_header not in txt:
+            p.write_text(txt.replace(header, stale_header, 1),
+                         encoding="utf-8")
+    except Exception:
+        pass

package/app/core/capability.py

@@ -1,144 +1,144 @@
-# -*- coding: utf-8 -*-
-"""能力维度（4D）：按任务类型（writing/coding/reasoning/vision）选模型。
-
-设计稿：docs/migration/05-model-seams.md §4D（按 CodeBee 实际架构落地：
-不改 modelhub.py——供应商声明可选 `strengths` 字段即可被识别；
-选择逻辑独立成模块，零侵入）。
-
-供应商声明示例（data/models.json 的 providers 条目）：
-  {"id": "p1", ..., "strengths": ["writing", "reasoning"]}
-未声明 strengths 的供应商视为无偏好（只做兜底）。
-"""
-from __future__ import annotations
-
-import re
-
-from .dispatch import TYPE_DIMENSIONS
-
-# 能力维度（先固化清单，schema 见设计稿）
-DIMS = ("writing", "coding", "reasoning", "vision")
-
-# 关键词分类表（覆盖 task type / 目标文本；可按需扩充）
-_KEYWORDS = {
-    "writing": ("写", "文案", "大纲", "连载", "章节", "小说", "营销", "总结", "润色",
-                "novel", "draft", "review"),
-    "coding": ("代码", "实现", "修复", "重构", "测试", "bug", "code", "fix",
-               "refactor", "test", "编译", "报错"),
-    "reasoning": ("推理", "分析", "调研", "对比", "规划", "拆解", "评审",
-                  "reason", "analyze", "plan", "orchestrate"),
-    "vision": ("图", "图片", "识别", "视觉", "ocr", "image", "vision", "截图"),
-}
-
-
-def classify_task_type(task) -> str:
-    """把任务分类到 DIMS 之一。task 显式带 task_type 时优先。"""
-    explicit = str((task or {}).get("task_type") or "").strip().lower()
-    if explicit in DIMS:
-        return explicit
-    preset = str((task or {}).get("type") or "").strip().lower()
-    if preset in TYPE_DIMENSIONS:
-        return TYPE_DIMENSIONS[preset]
-    text = "%s %s" % ((task or {}).get("type") or "",
-                      (task or {}).get("goal") or "")
-    scores = {}
-    for dim, kws in _KEYWORDS.items():
-        scores[dim] = sum(1 for kw in kws if kw in text)
-    best = max(scores, key=lambda d: scores[d])
-    if scores[best] > 0:
-        return best
-    return "coding"  # 默认兜底（CodeBee 主场景）
-
-
-def provider_strengths(prov):
-    """读供应商声明的能力维度（容错：非法值忽略）。"""
-    raw = (prov or {}).get("strengths")
-    if not isinstance(raw, list):
-        return []
-    return [s for s in raw if s in DIMS]
-
-
-def pick_by_strength(providers, task_type, *, enabled_only=True):
-    """按能力维度挑供应商。
-
-    规则：
-      1. 声明了该维度的可用供应商优先（保持原有顺序）；
-      2. 未声明的排后面（兜底）；
-      3. 都没有声明时返回原顺序（行为同现状）。
-    返回 (排序后的供应商列表, 分类依据说明)。
-    """
-    task_type = task_type if task_type in DIMS else classify_task_type({"goal": task_type})
-    pool = list(providers or [])
-    if enabled_only:
-        pool = [p for p in pool if p.get("enabled", True)]
-    strong = [p for p in pool if task_type in provider_strengths(p)]
-    rest = [p for p in pool if p not in strong]
-    ranked = strong + rest
-    reason = "%s：优先 %s" % (
-        task_type,
-        "、".join(p.get("id", "?") for p in strong) if strong else "（无声明，按原序兜底）")
-    return ranked, reason
-
-
-def resolve_binding_by_task(task, providers, bindings):
-    """任务 → 绑定解析（能力维度优先，回落 default）。
-
-    bindings 形如 modelhub 的 {"writing": {...}, "coding": {...}, "default": {...}}；
-    对应维度的绑定缺失/为空时回落 default。返回 (binding, task_type)。
-    """
-    tt = classify_task_type(task)
-    b = (bindings or {}).get(tt)
-    if not b:
-        b = (bindings or {}).get("default")
-    return b, tt
-
-
-# ---------------------------------------------------------------- §07 T3.1 级联
-
-TIER_ORDER = {"budget": 0, "standard": 1, "premium": 2}
-
-
-def cascade_reorder(agent, tier_of, *, providers=None, pricing=None,
-                    difficulty="easy", task_type="", role=""):
-    """FrugalGPT 式便宜优先：easy 任务把 call_chain 按 tier 升序稳定重排。
-
-    agent 来自 modelhub.bind_agent（可能带 call_chain）；tier_of(chain_entry)
-    返回该条目的档位串（"budget"/"standard"/"premium"或 None=standard）。
-    稳定排序保证同档内保持用户配置的原顺序。链长 <2 或非链式原样返回。
-    """
-    chain = (agent or {}).get("call_chain") or []
-    if len(chain) < 2:
-        return agent
-    if providers is not None and (task_type or role):
-        from .dispatch import rank_model_entries
-        ranked, _decisions = rank_model_entries(
-            chain, {p.get("id"): p for p in providers or []},
-            pricing or {}, difficulty, task_type, role)
-        out = dict(agent)
-        out["call_chain"] = ranked
-        return out
-
-    def key(entry):
-        return TIER_ORDER.get(tier_of(entry) or "standard", 1)
-
-    out = dict(agent)
-    out["call_chain"] = sorted(chain, key=key)
-    return out
-
-
-def make_tier_lookup(providers):
-    """由 providers 列表构造 chain_entry → tier 的查询函数。
-
-    tier 来源（按优先级）：链条目 model 在供应商 models[] 里的 tier 字段 →
-    供应商级 tier → None（按 standard 兜底）。缺什么都不抛。
-    """
-    by_id = {p.get("id"): p for p in (providers or []) if p.get("id")}
-
-    def tier_of(entry):
-        p = by_id.get((entry or {}).get("provider_id") or "")
-        if not p:
-            return None
-        for m in (p.get("models") or []):
-            if isinstance(m, dict) and m.get("name") == (entry or {}).get("model"):
-                return m.get("tier") or p.get("tier")
-        return p.get("tier")
-    return tier_of
+# -*- coding: utf-8 -*-
+"""能力维度（4D）：按任务类型（writing/coding/reasoning/vision）选模型。
+
+设计稿：docs/migration/05-model-seams.md §4D（按 CodeBee 实际架构落地：
+不改 modelhub.py——供应商声明可选 `strengths` 字段即可被识别；
+选择逻辑独立成模块，零侵入）。
+
+供应商声明示例（data/models.json 的 providers 条目）：
+  {"id": "p1", ..., "strengths": ["writing", "reasoning"]}
+未声明 strengths 的供应商视为无偏好（只做兜底）。
+"""
+from __future__ import annotations
+
+import re
+
+from .dispatch import TYPE_DIMENSIONS
+
+# 能力维度（先固化清单，schema 见设计稿）
+DIMS = ("writing", "coding", "reasoning", "vision")
+
+# 关键词分类表（覆盖 task type / 目标文本；可按需扩充）
+_KEYWORDS = {
+    "writing": ("写", "文案", "大纲", "连载", "章节", "小说", "营销", "总结", "润色",
+                "novel", "draft", "review"),
+    "coding": ("代码", "实现", "修复", "重构", "测试", "bug", "code", "fix",
+               "refactor", "test", "编译", "报错"),
+    "reasoning": ("推理", "分析", "调研", "对比", "规划", "拆解", "评审",
+                  "reason", "analyze", "plan", "orchestrate"),
+    "vision": ("图", "图片", "识别", "视觉", "ocr", "image", "vision", "截图"),
+}
+
+
+def classify_task_type(task) -> str:
+    """把任务分类到 DIMS 之一。task 显式带 task_type 时优先。"""
+    explicit = str((task or {}).get("task_type") or "").strip().lower()
+    if explicit in DIMS:
+        return explicit
+    preset = str((task or {}).get("type") or "").strip().lower()
+    if preset in TYPE_DIMENSIONS:
+        return TYPE_DIMENSIONS[preset]
+    text = "%s %s" % ((task or {}).get("type") or "",
+                      (task or {}).get("goal") or "")
+    scores = {}
+    for dim, kws in _KEYWORDS.items():
+        scores[dim] = sum(1 for kw in kws if kw in text)
+    best = max(scores, key=lambda d: scores[d])
+    if scores[best] > 0:
+        return best
+    return "coding"  # 默认兜底（CodeBee 主场景）
+
+
+def provider_strengths(prov):
+    """读供应商声明的能力维度（容错：非法值忽略）。"""
+    raw = (prov or {}).get("strengths")
+    if not isinstance(raw, list):
+        return []
+    return [s for s in raw if s in DIMS]
+
+
+def pick_by_strength(providers, task_type, *, enabled_only=True):
+    """按能力维度挑供应商。
+
+    规则：
+      1. 声明了该维度的可用供应商优先（保持原有顺序）；
+      2. 未声明的排后面（兜底）；
+      3. 都没有声明时返回原顺序（行为同现状）。
+    返回 (排序后的供应商列表, 分类依据说明)。
+    """
+    task_type = task_type if task_type in DIMS else classify_task_type({"goal": task_type})
+    pool = list(providers or [])
+    if enabled_only:
+        pool = [p for p in pool if p.get("enabled", True)]
+    strong = [p for p in pool if task_type in provider_strengths(p)]
+    rest = [p for p in pool if p not in strong]
+    ranked = strong + rest
+    reason = "%s：优先 %s" % (
+        task_type,
+        "、".join(p.get("id", "?") for p in strong) if strong else "（无声明，按原序兜底）")
+    return ranked, reason
+
+
+def resolve_binding_by_task(task, providers, bindings):
+    """任务 → 绑定解析（能力维度优先，回落 default）。
+
+    bindings 形如 modelhub 的 {"writing": {...}, "coding": {...}, "default": {...}}；
+    对应维度的绑定缺失/为空时回落 default。返回 (binding, task_type)。
+    """
+    tt = classify_task_type(task)
+    b = (bindings or {}).get(tt)
+    if not b:
+        b = (bindings or {}).get("default")
+    return b, tt
+
+
+# ---------------------------------------------------------------- §07 T3.1 级联
+
+TIER_ORDER = {"budget": 0, "standard": 1, "premium": 2}
+
+
+def cascade_reorder(agent, tier_of, *, providers=None, pricing=None,
+                    difficulty="easy", task_type="", role=""):
+    """FrugalGPT 式便宜优先：easy 任务把 call_chain 按 tier 升序稳定重排。
+
+    agent 来自 modelhub.bind_agent（可能带 call_chain）；tier_of(chain_entry)
+    返回该条目的档位串（"budget"/"standard"/"premium"或 None=standard）。
+    稳定排序保证同档内保持用户配置的原顺序。链长 <2 或非链式原样返回。
+    """
+    chain = (agent or {}).get("call_chain") or []
+    if len(chain) < 2:
+        return agent
+    if providers is not None and (task_type or role):
+        from .dispatch import rank_model_entries
+        ranked, _decisions = rank_model_entries(
+            chain, {p.get("id"): p for p in providers or []},
+            pricing or {}, difficulty, task_type, role)
+        out = dict(agent)
+        out["call_chain"] = ranked
+        return out
+
+    def key(entry):
+        return TIER_ORDER.get(tier_of(entry) or "standard", 1)
+
+    out = dict(agent)
+    out["call_chain"] = sorted(chain, key=key)
+    return out
+
+
+def make_tier_lookup(providers):
+    """由 providers 列表构造 chain_entry → tier 的查询函数。
+
+    tier 来源（按优先级）：链条目 model 在供应商 models[] 里的 tier 字段 →
+    供应商级 tier → None（按 standard 兜底）。缺什么都不抛。
+    """
+    by_id = {p.get("id"): p for p in (providers or []) if p.get("id")}
+
+    def tier_of(entry):
+        p = by_id.get((entry or {}).get("provider_id") or "")
+        if not p:
+            return None
+        for m in (p.get("models") or []):
+            if isinstance(m, dict) and m.get("name") == (entry or {}).get("model"):
+                return m.get("tier") or p.get("tier")
+        return p.get("tier")
+    return tier_of

package/app/core/chaptersafe.py

@@ -1,32 +1,32 @@
-# -*- coding: utf-8 -*-
-"""章节安全落盘（tmp+原子改名，inkos 安全章节工作区借鉴）。
-
-写一半崩溃/磁盘满不会留下半章正文冒充成稿——断点续跑按「文件够长」
-判定，半文件会被误当合法稿复用；.tmp 写完 os.replace 原子落位，
-失败清理残渣后原样抛出。路径守卫用 pathlib resolve+parents 惯用法
-（同 _ms_io/_inside 口径）。pipeline._write_chapter 委托此函数。"""
-from __future__ import annotations
-
-from pathlib import Path
-
-
-def atomic_write_chapter(workdir, i, text):
-    """第 i 章安全落盘：tmp 写入 → 原子改名。返回最终路径。"""
-    root = Path(workdir).resolve()
-    p = (root / ("chapter-%02d.md" % int(i))).resolve()
-    # 守卫：目标必须在 workdir 之内且不得是 workdir 本身（".." 作 workdir
-    # 时 resolve 到父目录，p 仍是其中一章——但那不是调用方的工作目录，
-    # 一并拒绝：workdir 必须是已存在的目录）
-    if root not in p.parents or not root.is_dir():
-        raise ValueError("章节路径越界: chapter-%02d.md" % int(i))
-    tmp = Path(str(p) + ".tmp")
-    try:
-        tmp.write_text(str(text), encoding="utf-8", errors="replace")
-        tmp.replace(p)
-    except BaseException:
-        try:
-            tmp.unlink(missing_ok=True)
-        except OSError:
-            pass
-        raise
-    return p
+# -*- coding: utf-8 -*-
+"""章节安全落盘（tmp+原子改名，inkos 安全章节工作区借鉴）。
+
+写一半崩溃/磁盘满不会留下半章正文冒充成稿——断点续跑按「文件够长」
+判定，半文件会被误当合法稿复用；.tmp 写完 os.replace 原子落位，
+失败清理残渣后原样抛出。路径守卫用 pathlib resolve+parents 惯用法
+（同 _ms_io/_inside 口径）。pipeline._write_chapter 委托此函数。"""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def atomic_write_chapter(workdir, i, text):
+    """第 i 章安全落盘：tmp 写入 → 原子改名。返回最终路径。"""
+    root = Path(workdir).resolve()
+    p = (root / ("chapter-%02d.md" % int(i))).resolve()
+    # 守卫：目标必须在 workdir 之内且不得是 workdir 本身（".." 作 workdir
+    # 时 resolve 到父目录，p 仍是其中一章——但那不是调用方的工作目录，
+    # 一并拒绝：workdir 必须是已存在的目录）
+    if root not in p.parents or not root.is_dir():
+        raise ValueError("章节路径越界: chapter-%02d.md" % int(i))
+    tmp = Path(str(p) + ".tmp")
+    try:
+        tmp.write_text(str(text), encoding="utf-8", errors="replace")
+        tmp.replace(p)
+    except BaseException:
+        try:
+            tmp.unlink(missing_ok=True)
+        except OSError:
+            pass
+        raise
+    return p