[feat] agent: 支持模型网关 Token/KV 缓存观测、紧凑工程视图与零副作用生成预检 #337

目标与范围

面向 #261 与 #188，解决内置 Agent 多轮创作时缺乏推理侧 Token 与 KV-Cache 命中率观测、大工程读取全量 ProjectSnapshot 导致上下文膨胀，以及提交高成本生成前无法零副作用获取真实后端校验与预算预检的问题。本次交付 ModelGateway 用量汇总轨迹、project.get 紧凑摘要与按节点局部读取，以及 generation.precheck 只读查询；不引入计费账本，也不改变既有生成提交与会话锁语义。

用户流程与关键规则

• ModelGateway 在转发上游 SSE 流与有限长度 2xx JSON 响应时，旁路解析并归一化不同兼容协议下的 promptTokens、completionTokens、totalTokens、cachedPromptTokens、cacheMissPromptTokens、reasoningTokens 与 cacheHitRate；在连接与回合结束时幂等写入单条 turn.usage 轨迹记录，不修改流式分块或响应字节。
• project.get（含 Agent read_project 与 CLI opendirector project show）保持 view="full" 默认兼容，新增 view="summary"（返回对象计数、画布节点轻量绑定摘要、生成任务状态与模型列表）与 itemIds 过滤（仅返回指定画布节点及其直接关联的 GenerationSpec、Reference、Asset、EditorDocument、Job 与 ResultVersion）。
• 新增只读查询 generation.precheck（通过 HTTP /queries、Agent query 与 CLI opendirector generation precheck 共用），复用正式生成的输入解析、模型能力规则、参考字节预算、编辑锁与队列容量校验，返回 ready、结构化 issues、参考媒体汇总、预估时长与人工确认提示，全程不创建 Job、不请求编辑会话。

实现影响

• 调整 packages/core/src/opendirector/agent/model_gateway.py、packages/core/src/opendirector/agent/native.py、packages/core/src/opendirector/agent/tools.py 与 packages/core/src/opendirector/cli.py。
• 扩展 packages/core/src/opendirector/domain/creation/commands.py、packages/core/src/opendirector/application/creation_canvas.py 与 apps/api/src/opendirector_api/creation.py，支持 Accept-Language 本地化问题说明。
• 重新生成 src/contracts/creation.schema.json 与 src/contracts/generated.ts，并同步更新中英文 CLI 文档 docs/guides/cli.md。

验收标准

• SSE 流式与 2xx JSON 模型响应均能准确统计归一化 Token 与 KV 缓存命中率，且 ModelGateway.close() 重复调用仅输出一条 turn.usage。
• project.get、read_project 与 opendirector project show 在 view="summary" 和 itemIds 过滤下保留权威对象 ID 与 revision，默认全量读取兼容既有调用。
• generation.precheck 与正式生成提交共享模型、参考、锁与队列校验规则，不产生任务或持久化写入，并在中英文请求头下返回对应语言的错误说明。