feat(prompt): decouple prompt-facing choice ids from canonical catego…

[xianyu9n]

Overview

Decouple the canonical category_id from the model-visible prompt/action identity.

Canonical category_id (e.g. finance:业务.账户信息.基本信息) is needed for registry / corpus lookup, canonical ground truth, evaluation/reward and data joins — but it should not appear in prompts or be generated by the LLM. This PR introduces a prompt-facing choice protocol while keeping the canonical contract completely unchanged.

Design

old:
  canonical category_id ——(渲染进 prompt / 模型直接输出 canonical id)——> LLM

new:
  canonical category_id
    → PromptChoiceRegistry
    → choice_id ("1".."N"，按 LeafRegistry.categories 稳定顺序)
    → Stage1 prompt: [["1","个人联系信息"], ...]；模型输出 {"candidates":["3","7","12","19","24"]}
    → Stage2 prompt: 5 候选局部编号 "1".."5"；模型输出 {"answer":"2"}
    → decode（Stage1 全局 choice_id / Stage2 位置编号）→ canonical category_id
    → 既有 evaluate_stage1/2 正确性逻辑（不变）

Boundary:

• LLM boundary: choice_id, internal boundary: category_id
• Choice ids never leak into corpus lookup / canonical target / reward semantics.

Changes

New: src/agent/task/prompt_choices.py

• PromptChoice (choice_id / category_id / display_name)
• PromptChoiceRegistry: bidirectional mapping, full registry coverage, unique choice ids, deterministic ("1".."N" by registry order), encode/decode_candidates
• display_name = shortest unique path suffix: leaf name when unique, otherwise parent-qualified until unique (e.g. 基本信息 → 账户信息 / 基本信息, 合约协议 / 基本信息, 营销服务 / 基本信息)
• encode/decode_stage2_answer: positional local ids 1..5
• PromptChoiceError for strict failures — no fuzzy/name fallback

Prompts: src/agent/task/prompts.py

• Stage 1 catalog → compact [choice_id, display_name] pairs; system contract requires 5 unique choice ids, forbids canonical ids
• Stage 2 bundle → local "id":"1".."5" + display_name + corpus description/examples
• stage1_answer / stage2_answer emit choice ids

Evaluation: src/agent/evaluation/classification.py

• evaluate_stage1_choices / evaluate_stage2_choices decode choice ids before delegating to the unchanged canonical evaluate_stage1/2 (which consume the unified parser check_stage1/2_output, shared with the RL reward adapter). No check logic duplicated; reward/evaluation stay canonical.

SFT: src/agent/training/sft/dataset.py

• ground_truth / candidates columns keep canonical category_id; only messages speak choice ids
• Validator decodes via the choice adapters

RL: src/agent/training/rl/dataset.py

• RL exporter reuses the same prompt builders, so RL prompts now speak choice ids too; reward_model.ground_truth / extra_info.candidates stay canonical
• RL validator's stage-1 catalog-coverage check adapted to [choice_id, display_name] format; canonical ids must not leak into prompts
• No RL reward integration (deferred)

Examples

Stage 1 (finance)

// before
{"category_id":"finance:业务.账户信息.基本信息","name":"基本信息"}   // {category_id,name} 233 项
{"candidates":["finance:业务.账户信息.基本信息", "…5 个完整 canonical id…"]}
// after
[["1","个人基本概况信息"],["49","账户信息 / 基本信息"], …]
{"candidates":["49","54","18","40","135"]}

Stage 2

// before: {"category_id":"finance:业务.账户信息.基本信息","name":"基本信息",…}，输出 {"answer":"finance:业务.账户信息.基本信息"}
// after
{"id":"1","name":"账户信息 / 基本信息","description":"…","examples":[…]},
{"id":"2","name":"合约协议 / 基本信息",…}
{"answer":"2"}  →(decode)→  finance:业务.合约协议.基本信息

Invariants

• canonical category_id unchanged
• registry universe unchanged (full coverage enforced)
• ground-truth semantics unchanged (target.category_id is the only label)
• reward/evaluation final comparison still uses canonical IDs
• training.common helpers reused (no duplication of canonical_target / build_candidates / corpus checks)
• shougang/infra code strategy intact; finance duplicate leaf names disambiguated by display_name

Tests

• python -m pytest -q → 181 passed, 2 skipped
• skipped tests: verl module not installed locally (environment, unrelated)

Deferred

• SFT/RL parquet re-export
• prompt token stats recompute + prompt_length_analysis.md
• artifacts/docs cleanup
• RL reward choice-id decoding
• formal SFT / VeRL RL smoke