Make headless ZCode dispatch more robust: model ID consistency, env override, and rate-limit handling

[tizerluo]

Summary

When using ZCode as a headless reviewer/gate from an agent workflow, I hit a few rough edges around credential/model injection and long-running/concurrent prompt behavior.

This is not a report that ZCode itself is unavailable. Manual short zcode --prompt calls work. The issue is about making zcode-open-bridge's documented/wrapped headless path more deterministic for downstream automation.

Environment

• ZCode CLI: 0.15.0
• Platform: macOS arm64
• Node reported by zcode doctor: v25.9.0
• Repo: tizerluo/zcode-open-bridge
• Auth/config source: ~/.zcode/v2/config.json

Observed issues

1. Model ID handling is inconsistent

The authoritative credential helper returns the raw configured model id:

shared/credentials.py -> ZCODE_MODEL=GLM-5.2

Relevant local lines:

model_id = next(iter(models)) if models else "GLM-5.2"
return {
    "ZCODE_MODEL": model_id,
    ...
}

But skills/zcode-bridge-guide/SKILL.md documents an explicit env wrapper that adds a zai/ prefix for builtin Z.AI providers:

m = "GLM-5.2" if "GLM-5.2" in p.get("models", {}) else next(iter(p.get("models", {})), "")
if pid.startswith("builtin:zai"):
    m = f"zai/{m}"

Meanwhile zcode-agent-help capabilities --section native_cli says the env example is GLM-5.2.

This makes downstream wrappers easy to get wrong: some copy the raw shared/credentials.py behavior, others copy the guide's zai/GLM-5.2 behavior.

Request: please define one canonical model-id format for headless ZCODE_MODEL, then align:

• shared/credentials.py
• embedded copies in MCP/ACP wrappers
• skills/zcode-bridge-guide/SKILL.md
• packages/agent-help/zcode-agent-help

2. Explicit env override is hard to use for debugging

The documented pattern is generally:

env = {**os.environ, **load_zcode_credentials()}

This means an operator cannot temporarily run:

ZCODE_MODEL=GLM-5.2 ...

and expect it to override config-loaded values if the wrapper injects credentials after os.environ.

That makes model/config debugging harder in agent workflows.

Request: consider an escape hatch, for example:

• let explicit ZCODE_MODEL, ZCODE_BASE_URL, ANTHROPIC_API_KEY win when already set, or
• add a flag/env like ZCODE_CREDS_OVERRIDE_ENV=0/1, or
• document that config always wins and provide a supported debug command to print the exact injected env without secrets.

3. Long-running/concurrent headless gates need safer rate-limit behavior

For PR-review style usage, a single headless prompt can be much heavier than a manual short prompt. The guide already notes that open prompts can spawn multiple exploration calls and hit rate limits.

In practice, agent workflows may accidentally start multiple ZCode gates concurrently. When that happens, provider-side rate limit / quota errors can surface, while the caller only sees a generic failed subprocess.

Request: consider one or more of these in the bridge wrappers/docs:

• recommend or provide a simple process-level lock for headless review calls;
• parse common provider errors such as ProviderBusinessError, 1302, and retry-after;
• perform bounded retry/backoff where safe;
• document a recommended focused-review prompt pattern: attach evidence/diff, avoid broad exploration, and say not to spawn extra agents/tools unless necessary.

Why this matters

zcode-open-bridge is very useful as an external reviewer/tester in automated PR workflows. Those workflows need behavior that is:

• deterministic across shell/agent environments;
• easy to debug without editing config files;
• robust when several gates are scheduled close together;
• clear about whether GLM-5.2 or zai/GLM-5.2 is the correct headless model id.

Thanks for the project. Happy to provide more local diagnostics if useful, but I intentionally omitted secrets and provider credentials from this report.

[tizerluo]

三个子项都在 #5 实现了(CI 全绿、Codex deep review 通过)。

1. Model ID 一致性: canonical 统一为 config 里 models 的 key 原样(如 GLM-5.2),不加 provider 前缀。四处对齐(shared/ACP/MCP 本就一致,SKILL env wrapper 删除了 builtin:zai 的 zai/ 前缀逻辑——之前唯一的不一致来源)。实测两种格式都能跑,非 canonical 的 zai/ 已移除。

2. 显式 env override + 调试: 新增 merge_env_with_creds(),显式非空 env 优先于 config、空串视为未设置(避免 ZCODE_MODEL="" 误清空,Codex 指出的边界)。调试命令 zcode-agent-help --print-injected-env 脱敏打印注入凭证 + 来源(config vs env)。

3. 限流鲁棒性:

• shared/provider_error.py: 解析 429/1302/Too Many Requests/请求频繁/retry-after, 区分 rate_limit/quota/provider_error, 提取 retry_after(bounded [1,300])
• MCP ReviewFileLock(fcntl) 串行化并发 review, 目录不可写降级无锁, ZCODE_BRIDGE_REVIEW_LOCK=0 可关
• MCP 有限重试(仅限流, max_retries=3, ZCODE_BRIDGE_MAX_RETRIES 可调), 注意 zcode 内部已有重试, 外层保守
• README 文档化聚焦审查 prompt(attach 证据 + 不 spawn 子代理)
• 顺带修 ACP 轮询/停滞收尾不感知 turn 失败(实测 zcode 只在 turn.failed 事件给 resultType, projection 无标志): 无实质输出时返回 -32603 而非静默 end_turn

验证: 套件 82→133, ruff/CI 全绿, Codex(GPT-5.5) deep review 通过(修了其 P0 空串覆盖/P1 parser 副本漂移/P1 文件锁健壮性)。合并后关闭。

[tizerluo]

已通过 #5 合并解决 (commit 72f8c80)。三个子项 + 一个产品级发现全部实现:

1. model id 统一为原始格式 (GLM-5.2)
2. 显式非空 env 优先 + 空串保护 + --print-injected-env 调试命令
3. 限流鲁棒性 (provider 错误解析 + MCP 文件锁 + 有限重试 + ACP 轮询失败检测)

• baseURL 残留自动自愈 (App 切换 plan 后的残留检测)

143 测试、CI 全绿、Claude Opus + Codex 双引擎 deep review 通过、7 项真实业务实测通过 (含 SQL 注入审查 / 限流代码审查 / ACP 真流式 / 工具调用 turn)。兼容 ZCode 3.2.1。