a2ui-project / a2ui-project/a2ui
fix(sdk): auto-heal and normalize protocol version in DirectJsonParser
- Ngôn ngữ chính
- TypeScript
- Star
- 16.4k
- Fork
- 1.3k
- Merge trung bình
- 3 ngày 15 giờ
- Pull request đã merge (30 ngày)
- 134
Mô tả
### Description
In the Direct JSON inference format (`DirectJsonFormat`), the LLM directly emits raw A2UI JSON message streams. The A2UI protocol schemas strictly require a top-level `"version"` property with a leading `'v'` (e.g., `"v0.9"`, `"v0.9.1"`, `"v1.0"`).
Because standard software version conventions use numeric strings (e.g. `"0.9"`, `"1.0"`), and system prompt workflow rules do not heavily emphasize envelope version string trivia, LLMs frequently omit the leading `'v'` (emitting `"version": "0.9"`) or omit the `"version"` property altogether. This causes non-deterministic schema validation failures (e.g., recent CI evals failure in #2594 where 5 samples failed solely due to `'0.9' is not one of ['v0.9', 'v0.9.1']`).
In contrast, other inference format compilers (`ExpressCompiler`, `ElementalCompiler`, `AtomCompiler`) deterministically inject the canonical target protocol version into compiled message payloads rather than burdening the LLM with envelope version formatting.
### Proposed Solution
1. **Auto-heal / Normalize Version in `DirectJsonParser`**:
- In `DirectJsonParser.compile()` (and `parse_and_fix`), check each compiled A2UI message dictionary.
- If `"version"` is missing the leading `'v'` (e.g. `"0.9"`, `"0.9.1"`, `"1.0"`), normalize it to `"v0.9"`, `"v0.9.1"`, or `"v1.0"`.
- If `"version"` is omitted entirely, deterministically inject the target protocol version associated with the catalog/format (e.g. `f"v{catalog.version}"`).
2. **Harmonize Evaluation & Specialist Parsing**:
- Ensure `subagent_tool` and evaluation scorers rely on `DirectJsonParser.compile()` so that syntax healing (smart quotes, trailing commas, and version normalization) is consistently applied.
### Related
- Relates to #2594
Hướng dẫn đóng góp
Hướng nghiên cứu
The issue is in the DirectJsonParser's compile and parse_and_fix methods. Look for the DirectJsonParser class in the codebase, likely in a file like `src/sdk/parser/direct_json_parser.ts`. Examine how it processes A2UI message dictionaries. The fix involves checking the 'version' property, adding a leading 'v' if missing, or injecting the catalog version. Run existing tests for the parser to ensure the normalization works.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Lĩnh vực
- backend-api-design
- Loại issue
- Lỗi
- Độ khó
- 2/5
- Thời gian dự kiến
- 1-3 giờ
- Mức độ hoạt động
- Sôi nổi
- Độ rõ ràng
- Đặc tả rõ ràng
- Mức phù hợp với người mới
- 75/100