【Bug已解决】Older Codex Desktop threads may not expose codex_app thread management tools 解决方案

原始报错线索：Older Codex Desktop threads may not expose codex_app thread management tools（较老版本的桌面线程可能没有暴露出 codex_app 的线程管理工具，导致在新版本里对这些旧线程无法做管理操作）。

---

一、现象长什么样

系统升级后新增了「线程管理工具」。然后：

1. 用户对新线程能用管理工具（重命名、归档、合并）；
2. 但对升级前创建的旧线程，这些工具根本不出现 / 调用报错「不支持」；
3. 管理界面要么对旧线程显示残缺，要么点管理就抛异常；
4. 用户困惑：同样的线程，凭什么新的能用、旧的不能。 根因是能力是「按版本/创建时」固化的，消费方却假设「所有实体都有最新能力」，缺少协商与降级。

---

二、背景：能力为什么会随版本分化

一个实体的能力通常在创建时就由当时的服务端版本决定：

• 旧版服务端创建线程时，没有「线程管理」这一功能，所以旧线程的元数据结构里没有对应字段；
• 新版服务端创建线程时，才带上管理能力的元数据；
• 升级服务端不会自动「回填」旧实体（通常出于安全/一致性考虑也不该偷偷改旧数据）。 于是同一类实体，因创建版本不同，能力集不同——这是常态，必须有机制应对。

---

三、为什么旧线程不暴露工具：根因

3.1 消费方假设「能力总是最新」

UI / 调度器遍历线程时，默认每个线程都有 thread_management 能力，直接调用 → 旧线程没有 → 报错。

3.2 没有能力清单（capabilities）

实体不携带「我支持哪些能力」的结构化声明，消费方无从判断，只能盲试。

3.3 缺少协商 / 探测

消费方不先问「你支持管理吗」，就直接发管理指令。

3.4 无降级路径

旧线程不支持时，没有提供「替代操作 / 提示用户升级线程」的降级，直接失败。

四、最小可运行复现（假设所有线程都有能力）

下面演示「默认所有线程都有管理工具」如何对旧线程报错：

class Thread:
    def __init__(self, tid, capabilities):
        self.tid = tid
        self.capabilities = capabilities   # 集合，如 {"chat"}
def manage_thread_bad(t: Thread):
    # 错误：假设一定有 thread_manage 能力
    if "thread_manage" not in t.capabilities:
        raise NotImplementedError("该线程不支持管理")
    return f"管理 {t.tid}"
if __name__ == "__main__":
    old = Thread("old-1", {"chat"})              # 旧线程，无管理能力
    new = Thread("new-1", {"chat", "thread_manage"})
    print(manage_thread_bad(new))
    try:
        manage_thread_bad(old)
    except NotImplementedError as e:
        print("旧线程报错:", e)

旧线程因缺能力直接抛错——这就是「不暴露工具」在消费端的失败表现。

五、解决方案一：实体携带能力清单（capabilities）

每个实体明确声明「我支持什么」，消费方基于声明决策：

def get_caps(thread) -> set:
    """返回线程支持的能力集；缺失则视为空（向后兼容旧实体）。"""
    return set(getattr(thread, "capabilities", []) or [])
def supports(thread, cap) -> bool:
    return cap in get_caps(thread)
if __name__ == "__main__":
    old = Thread("old-1", ["chat"])
    new = Thread("new-1", ["chat", "thread_manage"])
    print("旧线程可管理?", supports(old, "thread_manage"))   # False
    print("新线程可管理?", supports(new, "thread_manage"))   # True

capabilities 从实体读取，旧实体没有就当空集——消费方立刻知道「不能用」。

六、解决方案二：能力协商（先问后做）

消费方在调用管理工具前，先协商「目标是否支持」，不支持就走降级：

def ensure_capability(thread, cap):
    """协商：返回 (supported, reason)。"""
    if supports(thread, cap):
        return True, "ok"
    # 旧线程：提示可升级该线程以获得能力
    return False, f"线程 {thread.tid} 创建于旧版本，不携带 {cap}；请升级/迁移该线程"
def manage_thread_safe(thread):
    ok, reason = ensure_capability(thread, "thread_manage")
    if not ok:
        return {"action": "degraded", "reason": reason}
    return {"action": "managed", "tid": thread.tid}
if __name__ == "__main__":
    print(manage_thread_safe(Thread("old-1", ["chat"])))
    # {'action': 'degraded', 'reason': '线程 old-1 ... 请升级/迁移该线程'}
    print(manage_thread_safe(Thread("new-1", ["chat", "thread_manage"])))
    # {'action': 'managed', 'tid': 'new-1'}

先协商再动作，旧线程得到清晰降级而非崩溃。

七、解决方案三：版本门控 + 一次性迁移

对旧实体提供「迁移」路径，把它们补齐到新版能力集（只补元数据，不偷偷改业务数据）：

MIN_CAP_VERSION = "2.0"
def needs_migration(thread, created_version):
    """旧版本创建的线程需要迁移以补齐能力声明。"""
    return created_version < MIN_CAP_VERSION
def migrate_thread(thread, created_version):
    """给旧线程补上能力声明（不改动业务内容）。"""
    if needs_migration(thread, created_version):
        caps = set(getattr(thread, "capabilities", []) or [])
        caps.add("thread_manage")        # 补齐新版能力
        thread.capabilities = list(caps)
        thread.migrated_from = created_version
    return thread
if __name__ == "__main__":
    old = Thread("old-1", ["chat"])
    migrate_thread(old, created_version="1.0")
    print("迁移后能力:", old.capabilities)   # ['chat', 'thread_manage']
    print("可否管理:", supports(old, "thread_manage"))   # True

迁移只补齐能力声明（元数据），让旧线程「获得」新工具的可见性，而不动业务数据——这是最干净的修复。

八、跨实体一致性

• feature flag：新能力用 flag 控制，旧实体 flag 默认关，新建实体开；
• 协商而非假设：任何「新能力调用」前先查 capabilities；
• 可观测：界面应标注「该线程为旧版，部分功能不可用」；
• 迁移幂等：迁移可重复执行且结果一致。

---

九、排查清单

「旧线程不暴露新工具」，按下面排查：

1. 实体是否带 capabilities 声明？旧实体是否当空集处理（第五节）；
2. 消费方是否先协商再调用？还是假设都有能力（第六节）；
3. 是否有迁移路径？旧实体能否补齐能力声明（第七节）；
4. 迁移是否幂等？重复执行是否安全；
5. feature flag 是否一致？旧实体 flag 状态对吗；
6. UI 是否标注旧版限制；
7. 新建实体是否默认带新能力？别把新实体也漏了；
8. 日志是否记录实体创建版本与能力集。

---

十、小结

「旧版线程不暴露新工具」的根因是能力随创建版本固化，而消费方假设所有实体都有最新能力，缺少协商与降级。通用修复：

1. 能力清单：每个实体声明 capabilities，旧实体缺失即空集（第五节）；
2. 先协商后做：调用新能力前查声明，不支持则走降级并提示迁移（第六节）；
3. 一次性迁移：只补齐旧实体的能力声明（元数据），不动业务数据；
4. flag + 可观测：新能力用 flag 控制，UI 标注旧版限制（第八节，呼应第 106/107 篇）。 一句话：能力是「创建时固化」的，消费方必须「按实体实际能力决策」，而非「按最新版本假设」。用 capabilities 声明 + 协商 + 幂等迁移，旧实体既能优雅降级，又能被平滑补齐——这与第 131 篇 MCP 工具暴露、第 106 篇功能开关、第 87 篇幂等修复，共同体现「版本演进中的实体必须有能力协商与向后兼容」。