Repository navigation
feat(errors): structured error guidance for AI agents - #84
Merged
Merged
Conversation
Enrich XError details with hint, retryable, category, and native DB codes for MySQL/PostgreSQL. Document the contract, add RFC 0015, and cover mapping with unit and integration tests. Co-authored-by: x_zhuo <zx06@users.noreply.github.com>
Co-authored-by: x_zhuo <zx06@users.noreply.github.com>
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #84 +/- ##
==========================================
+ Coverage 84.32% 84.43% +0.10%
==========================================
Files 67 69 +2
Lines 6367 6744 +377
==========================================
+ Hits 5369 5694 +325
- Misses 723 767 +44
- Partials 275 283 +8
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Co-authored-by: x_zhuo <zx06@users.noreply.github.com>
Co-authored-by: x_zhuo <zx06@users.noreply.github.com>
- Split MySQL 1045 and PG 28P01/28000 into auth_failed with keyring hint - Map no_keyword and similar static RO reasons to unrecognized_statement - Centralize hint strings; expand dbclassify unit tests and table-driven integration Co-authored-by: x_zhuo <zx06@users.noreply.github.com>
Co-authored-by: x_zhuo <zx06@users.noreply.github.com>
|
zx06
marked this pull request as ready for review
October 10, 2026 06:52
cursor Bot
pushed a commit
that referenced
this pull request
Oct 10, 2026
Resolve merge conflicts (RFC 0015–0017, query executeQuery+dbType). Reuse HintQueryResultTruncated from internal/errors after PR #84. Co-authored-by: x_zhuo <zx06@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds backward-compatible agent guidance to JSON/YAML error envelopes via
error.details:hint,retryable,category, optionaldialect,native_code, andnative_code_kind. MySQL errno and PostgreSQL SQLSTATE map to stable categories (e.g.unknown_table,syntax_error,read_only_blocked,connection). Enrichment runs centrally inerrors.New/errors.Wrap, so CLI, MCP, and Web share the same behavior without changing top-levelcode, exit codes, orschema_version(still1).Changes
docs/rfcs/0016-error-guidance-for-agents.mdand updates todocs/error-contract.md,docs/ai.md, and.agents/skills/xsql/SKILL.mdinternal/errors: classification + enrichment (dbclassify.go,guidance.go)internal/db/query.go: passdialecton query failures; drivers tag connect errors with dialect中文摘要
为 xsql 的错误 JSON 在
details中自动补充 hint（下一步建议）、retryable（是否值得重试）、category（稳定语义分类）以及 MySQL/PostgreSQL 的 native_code，帮助 AI 在未知表、语法错误、连接失败、只读拦截等场景下少做无效重试。现有error.code、退出码与schema_version=1不变，仅追加字段。Testing
go build ./.../go vet ./...go test ./...go test -tags=e2e ./tests/e2e/...go test -tags=integration ./tests/integration/...(MySQL 8.0 + PostgreSQL 16)golangci-lint run ./...