From 28fa06eaa56a19906732681cc02474a87ac9d408 Mon Sep 17 00:00:00 2001 From: weichen Date: Tue, 29 Sep 2026 15:18:32 +0000 Subject: [PATCH] Add the intent seed domain for the agent-intent module. --- README.md | 3 ++- docs/agent-intent-mapping.md | 12 ++++++++++++ domains/catalog_test.go | 2 +- domains/catalog_write_test.go | 4 ++-- domains/embed.go | 2 +- domains/intent.go | 12 ++++++++++++ domains/intent.json | 29 +++++++++++++++++++++++++++++ domains/register.go | 3 ++- errcode/codes.go | 7 +++++++ 9 files changed, 68 insertions(+), 6 deletions(-) create mode 100644 docs/agent-intent-mapping.md create mode 100644 domains/intent.go create mode 100644 domains/intent.json diff --git a/README.md b/README.md index 32c4f2d..687e8a0 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ | 包 | 职责 | 依赖边界 | |---|---|---| | errcode | 码格式、定义、注册表、`E` 错误类型 | 只依赖标准库 | -| domains | sys / agent / squad 种子码；Go 为权威，JSON 为导出快照 | 只依赖 errcode | +| domains | sys / agent / squad / intent 种子码；Go 为权威，JSON 为导出快照 | 只依赖 errcode | | httpx | 统一错误信封与 `X-Trace-Id` | 只依赖 errcode | | server | HTTP API，默认 `:8091` | 组合根之一 | | cli | `errcode` 命令 | 组合根之一 | @@ -27,6 +27,7 @@ - [注册治理](docs/governance.md) - [agent-native](docs/agent-native-mapping.md) - [agent-squad](docs/agent-squad-mapping.md) +- [agent-intent](docs/agent-intent-mapping.md) - [和日志系统对齐](docs/integration.md) ## 进程内用法 diff --git a/docs/agent-intent-mapping.md b/docs/agent-intent-mapping.md new file mode 100644 index 0000000..9971413 --- /dev/null +++ b/docs/agent-intent-mapping.md @@ -0,0 +1,12 @@ +# agent-intent 错误码映射 + +agent-intent v1 无 HTTP 面，核心包按 Pattern B 接入：错误常量的字符串值即下列规范码，错误类型实现 `ErrorCode()` / `ErrorFields()` 鸭子方法供日志系统展开；其仓内 `catalogcheck` 对齐测试保证两边常量相等，本表是人类可读对照。 + +| agent-intent 常量 | 规范码 | HTTP | 触发场景 | +|---|---|---|---| +| `intent.InvalidSpec` | intent.invalid_spec | 400 | spec 定义/校验失败：id 冲突、正则不合法、未知字段、matcher 无正向条件、槽位 group 越界、覆盖版本未递增 | +| `intent.SpecProtected` | intent.spec_protected | 400 | overlay 试图覆盖或禁用保护域内的 spec | +| `intent.LoadFailed` | intent.load_failed | 500 | 配置读取/解析失败；此时保留上一生效快照 | +| `intent.InvalidArgument`（复用框架域） | sys.invalid_argument | 400 | 调用方错误：nil 快照、输入超长 | + +「无匹配」（fallback 分支）是正常识别结果，不产生错误码；识别路径的失败语义与重试由宿主决定。 diff --git a/domains/catalog_test.go b/domains/catalog_test.go index b955dc8..c97ac9f 100644 --- a/domains/catalog_test.go +++ b/domains/catalog_test.go @@ -10,7 +10,7 @@ import ( func TestEmbeddedCatalogMatchesRegistry(t *testing.T) { r := errcode.NewRegistry() RegisterAll(r) - for _, domain := range []string{"sys", "agent", "squad"} { + for _, domain := range []string{"sys", "agent", "squad", "intent"} { got, err := ExportDomain(r, domain) if err != nil { t.Fatal(err) diff --git a/domains/catalog_write_test.go b/domains/catalog_write_test.go index 6675440..1feb02b 100644 --- a/domains/catalog_write_test.go +++ b/domains/catalog_write_test.go @@ -9,11 +9,11 @@ import ( func TestWriteCatalog(t *testing.T) { if os.Getenv("WRITE_CATALOG") != "1" { - t.Skip("set WRITE_CATALOG=1 to regenerate sys.json agent.json squad.json") + t.Skip("set WRITE_CATALOG=1 to regenerate sys.json agent.json squad.json intent.json") } r := errcode.NewRegistry() RegisterAll(r) - for _, domain := range []string{"sys", "agent", "squad"} { + for _, domain := range []string{"sys", "agent", "squad", "intent"} { data, err := ExportDomain(r, domain) if err != nil { t.Fatal(err) diff --git a/domains/embed.go b/domains/embed.go index 0265178..61f9eb3 100644 --- a/domains/embed.go +++ b/domains/embed.go @@ -4,7 +4,7 @@ import "embed" // 导出的目录快照。改 Go 定义后用 WRITE_CATALOG=1 重写这些文件。 // -//go:embed sys.json agent.json squad.json +//go:embed sys.json agent.json squad.json intent.json var catalogFS embed.FS // CatalogJSON 返回已嵌入的域目录原文。 diff --git a/domains/intent.go b/domains/intent.go new file mode 100644 index 0000000..82587eb --- /dev/null +++ b/domains/intent.go @@ -0,0 +1,12 @@ +package domains + +import "error-code-system/errcode" + +func registerIntent(r *errcode.Registry) { + must(r, def(errcode.IntentInvalidSpec, 400, errcode.SeverityError, errcode.RetryNever, errcode.SideEffectNone, + "意图定义校验失败", "检查 spec 的 id/domain/matcher/slots 与来源文件；整批配置已原子拒绝")) + must(r, def(errcode.IntentSpecProtected, 400, errcode.SeverityError, errcode.RetryNever, errcode.SideEffectNone, + "试图覆盖或禁用保护域意图", "保护域由宿主构建时声明；修改须走宿主内置定义，不接受 overlay")) + must(r, def(errcode.IntentLoadFailed, 500, errcode.SeverityError, errcode.RetryNever, errcode.SideEffectNone, + "意图配置加载失败", "查看来源路径与解析原因；失败时保留上一生效快照")) +} diff --git a/domains/intent.json b/domains/intent.json new file mode 100644 index 0000000..3fff997 --- /dev/null +++ b/domains/intent.json @@ -0,0 +1,29 @@ +[ + { + "code": "intent.invalid_spec", + "http": 400, + "severity": "error", + "retry": "never", + "side_effects": "none", + "summary": "意图定义校验失败", + "hint": "检查 spec 的 id/domain/matcher/slots 与来源文件；整批配置已原子拒绝" + }, + { + "code": "intent.load_failed", + "http": 500, + "severity": "error", + "retry": "never", + "side_effects": "none", + "summary": "意图配置加载失败", + "hint": "查看来源路径与解析原因；失败时保留上一生效快照" + }, + { + "code": "intent.spec_protected", + "http": 400, + "severity": "error", + "retry": "never", + "side_effects": "none", + "summary": "试图覆盖或禁用保护域意图", + "hint": "保护域由宿主构建时声明；修改须走宿主内置定义，不接受 overlay" + } +] diff --git a/domains/register.go b/domains/register.go index e208a6a..df6977a 100644 --- a/domains/register.go +++ b/domains/register.go @@ -8,11 +8,12 @@ import "error-code-system/errcode" func init() { RegisterAll(errcode.Default) } -// RegisterAll 向 r 登记 sys / agent / squad 三域。重复调用会因码冲突失败。 +// RegisterAll 向 r 登记 sys / agent / squad / intent 四域。重复调用会因码冲突失败。 func RegisterAll(r *errcode.Registry) { registerSys(r) registerAgent(r) registerSquad(r) + registerIntent(r) } func must(r *errcode.Registry, def errcode.Definition) { diff --git a/errcode/codes.go b/errcode/codes.go index 9275479..48498c3 100644 --- a/errcode/codes.go +++ b/errcode/codes.go @@ -48,3 +48,10 @@ const ( SquadQualityFailed Code = "squad.quality_failed" SquadCancelled Code = "squad.cancelled" ) + +// 意图识别域。对齐 agent-intent 核心包错误常量；消费方以 catalogcheck 对齐测试防止双权威。 +const ( + IntentInvalidSpec Code = "intent.invalid_spec" + IntentSpecProtected Code = "intent.spec_protected" + IntentLoadFailed Code = "intent.load_failed" +)