Skip to content

Commit ef807f2

Browse files
ambiguous-pointerambiguous-pointer
committed
Feat: Add coding agent domain skills ([#1457](#1457))
* feat(skills): add backend domain skills for runtime, discovery, engine, events, store, and Console API Document component lifecycle, ListAndWatch discovery, resource engine behavior, EventBus dispatching, storage indexes, and Web MVC flow for coding agents. * feat(skills): add frontend domain skill for routing, components, and traffic rule forms Document Vue frontend structure, API clients, Pinia state, route metadata, layout tabs, and traffic rule form design. * feat(skills): add OpenAI skill metadata Add agents/openai.yaml metadata for each dubbo-admin domain skill.
1 parent cea721e commit ef807f2

37 files changed

Lines changed: 2676 additions & 0 deletions

File tree

‎.agents/skills/dubbo-admin-console-api/SKILL.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
name: dubbo-admin-console-api
3+
description: Implements and reviews dubbo-admin Console API changes. Use when the user asks about HTTP endpoints, Gin routes, handlers, request or response models, console services, error handling, API pagination, or the handler to service to manager to store flow under pkg/console/. Do not use for frontend-only, discovery-only, or store-internals tasks unless they affect Console API behavior.
4+
---
5+
6+
# dubbo-admin Console API
7+
8+
## Purpose
9+
10+
Use this skill to change or explain dubbo-admin Web MVC behavior consistently across router, handler, model, service, manager, and store layers.
11+
12+
## When to use
13+
14+
Use for Console API endpoint additions, request binding, response models, service logic, route registration, API error handling, and backend API review.
15+
16+
Do not use for Vue-only changes, registry discovery internals, or memory store implementation details unless an API contract depends on them.
17+
18+
## Inputs
19+
20+
Required:
21+
- Target endpoint, handler, model, or package path.
22+
- Intended API behavior or observed bug.
23+
24+
Optional:
25+
- Example request or response payload.
26+
- Related frontend API caller.
27+
- Existing route or service function to mirror.
28+
29+
If missing, inspect `pkg/console/router/router.go` first and ask only for behavior that cannot be inferred from code.
30+
31+
## Workflow
32+
33+
1. Locate the route in `pkg/console/router/router.go`.
34+
2. Read the matching handler in `pkg/console/handler/` for binding and response style.
35+
3. Read or update request and response types in `pkg/console/model/`.
36+
4. Put business logic in `pkg/console/service/`; keep handlers focused on HTTP concerns.
37+
5. Use `ctx.ResourceManager()` and helpers in `pkg/core/manager/` for resource access.
38+
6. Return responses with `model.NewSuccessResp`, `util.HandleArgumentError`, or `util.HandleServiceError`.
39+
7. If endpoint behavior is unclear, read `references/web-mvc-flow.md`.
40+
41+
## Output format
42+
43+
Return changed files, endpoint behavior, request and response contract, validation performed, and any frontend impact.
44+
45+
## Validation
46+
47+
- Confirm the route is registered under `/api/v1`.
48+
- Confirm handler binding matches method semantics: query for reads, JSON body for mutations.
49+
- Confirm service code returns typed models and propagates business errors.
50+
- Run focused Go tests for changed packages; use `make test` for shared API behavior.
51+
52+
## Edge cases
53+
54+
- Some handlers include lightweight auth, cookie, or parameter logic; do not force all logic into services.
55+
- If changing response fields, check frontend callers under `ui-vue3/src/api/`.
56+
- If a resource query becomes slow, switch to `dubbo-admin-store`.
57+
58+
## References
59+
60+
- Read `references/web-mvc-flow.md` for the current route, handler, service, and response pattern.

‎.agents/skills/dubbo-admin-console-api/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "Dubbo Admin Console API"
3+
short_description: "Guide for dubbo-admin Console API work"
4+
default_prompt: "Use $dubbo-admin-console-api to add or change a dubbo-admin Console API endpoint."

‎.agents/skills/dubbo-admin-console-api/evals/evals.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
"skill_name": "dubbo-admin-console-api",
3+
"evals": [
4+
{
5+
"id": "obvious-trigger",
6+
"prompt": "Add a new GET endpoint under /api/v1/service that returns a typed response from pkg/console/service.",
7+
"expected_behavior": "Use the Console API router, handler, model, service, and manager workflow."
8+
},
9+
{
10+
"id": "paraphrased-trigger",
11+
"prompt": "The admin backend route binds query parameters incorrectly and returns the wrong CommonResp data.",
12+
"expected_behavior": "Inspect pkg/console handlers, models, services, and response helpers."
13+
},
14+
{
15+
"id": "file-based-trigger",
16+
"prompt": "Review changes in pkg/console/router/router.go and pkg/console/handler/application.go.",
17+
"expected_behavior": "Use this skill because Console API files are touched."
18+
},
19+
{
20+
"id": "no-trigger",
21+
"prompt": "Change the Vue sidebar icon for the service page.",
22+
"expected_behavior": "Do not use this skill; use the frontend skill."
23+
},
24+
{
25+
"id": "conflict-trigger",
26+
"prompt": "A frontend API call fails because the backend response field changed.",
27+
"expected_behavior": "Use this skill for backend contract review and coordinate with frontend skill for caller updates."
28+
}
29+
]
30+
}

‎.agents/skills/dubbo-admin-console-api/references/web-mvc-flow.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# Console API Web MVC Implementation
2+
3+
This reference explains how dubbo-admin exposes backend HTTP APIs through Gin handlers, typed models, console services, resource managers, and stores.
4+
5+
## End-to-end call chain
6+
7+
```text
8+
runtime.RegisterComponent(&consoleWebServer{})
9+
-> Bootstrap initializes consoleWebServer.Init
10+
-> Init creates gin.Engine, middleware, static UI, health route
11+
-> Runtime starts consoleWebServer.Start
12+
-> Start creates consolectx.NewConsoleContext(coreRt)
13+
-> router.InitRouter(c.Engine, c.cs)
14+
-> HTTP request under /api/v1
15+
-> handler binds query/path/body
16+
-> handler calls service function
17+
-> service uses consolectx.Context and ctx.ResourceManager()
18+
-> manager/store reads or writes resources
19+
-> service returns typed model response
20+
-> handler wraps with model.NewSuccessResp or util.Handle*Error
21+
```
22+
23+
## Console component
24+
25+
Key file: `pkg/console/component.go`
26+
27+
Console is registered as a runtime component and depends on `runtime.ResourceManager`:
28+
29+
```go
30+
func init() {
31+
runtime.RegisterComponent(&consoleWebServer{})
32+
}
33+
34+
func (c *consoleWebServer) RequiredDependencies() []runtime.ComponentType {
35+
return []runtime.ComponentType{runtime.ResourceManager}
36+
}
37+
```
38+
39+
`Init` sets up Gin:
40+
41+
- embedded admin UI mounted at `/admin`
42+
- SPA fallback for `/admin/**`
43+
- `/health` endpoint
44+
- cookie session store
45+
- auth middleware
46+
- zap logging and recovery middleware
47+
- Gin mode from config
48+
49+
`Start` creates console context and registers `/api/v1` routes:
50+
51+
```go
52+
c.cs = consolectx.NewConsoleContext(coreRt)
53+
router.InitRouter(c.Engine, c.cs)
54+
httpServer := c.startHttpServer(errChan)
55+
```
56+
57+
On stop, the HTTP server shuts down with `Shutdown(context.Background())`.
58+
59+
## Auth behavior
60+
61+
`authMiddleware` skips paths ending in `/login`. Other requests require a session value named `user`. Missing user returns HTTP 401 with `model.NewBizErrorResp`.
62+
63+
This means many API handlers assume authentication already passed.
64+
65+
## Console context
66+
67+
Key file: `pkg/console/context/context.go`
68+
69+
`consolectx.Context` wraps runtime access:
70+
71+
```go
72+
type Context interface {
73+
ResourceManager() manager.ResourceManager
74+
CounterManager() counter.CounterManager
75+
Config() app.AdminConfig
76+
AppContext() context.Context
77+
LockManager() lock.Lock
78+
}
79+
```
80+
81+
`ResourceManager()` retrieves the runtime ResourceManager component and returns its manager:
82+
83+
```go
84+
rmc, _ := c.coreRt.GetComponent(runtime.ResourceManager)
85+
return rmc.(manager.ResourceManagerComponent).ResourceManager()
86+
```
87+
88+
CounterManager and LockManager are optional and may return nil.
89+
90+
## Route registration
91+
92+
Key file: `pkg/console/router/router.go`
93+
94+
All Console API routes are grouped under `/api/v1`:
95+
96+
```go
97+
router := r.Group("/api/v1")
98+
```
99+
100+
Common groups include:
101+
102+
- `/auth`
103+
- `/instance`
104+
- `/application`
105+
- `/service`
106+
- `/configurator`
107+
- `/condition-rule`
108+
- `/tag-rule`
109+
- global `/search`, `/overview`, `/metadata`, `/meshes`
110+
111+
When adding an endpoint, register the route in the existing group that matches frontend URL structure.
112+
113+
## Handler pattern
114+
115+
Handlers usually close over `consolectx.Context` and return `gin.HandlerFunc`:
116+
117+
```go
118+
func GetApplicationDetail(ctx consolectx.Context) gin.HandlerFunc {
119+
return func(c *gin.Context) {
120+
req := &model.ApplicationDetailReq{}
121+
if err := c.ShouldBindQuery(req); err != nil {
122+
util.HandleArgumentError(c, err)
123+
return
124+
}
125+
resp, err := service.GetApplicationDetail(ctx, req)
126+
if err != nil {
127+
util.HandleServiceError(c, err)
128+
return
129+
}
130+
c.JSON(http.StatusOK, model.NewSuccessResp(resp))
131+
}
132+
}
133+
```
134+
135+
Read endpoints commonly use `ShouldBindQuery`. Mutation endpoints commonly use `ShouldBindJSON` or path parameters depending on existing handler style.
136+
137+
## Error and response model
138+
139+
Key files:
140+
141+
- `pkg/console/model/common.go`
142+
- `pkg/console/util/error.go`
143+
144+
Success response:
145+
146+
```go
147+
model.NewSuccessResp(data)
148+
```
149+
150+
Service errors are normalized to `bizerror.Error` and returned with HTTP 200:
151+
152+
```go
153+
func HandleServiceError(ctx *gin.Context, err error) {
154+
var e bizerror.Error
155+
if !errors.As(err, &e) {
156+
e = bizerror.New(bizerror.UnknownError, err.Error())
157+
}
158+
ctx.JSON(http.StatusOK, model.NewBizErrorResp(e))
159+
}
160+
```
161+
162+
Argument errors use `bizerror.InvalidArgument`. Auth middleware is an exception and returns HTTP 401.
163+
164+
## Service layer
165+
166+
Key directory: `pkg/console/service/`
167+
168+
Services receive `consolectx.Context` and typed request models. They usually access resources through generic manager helpers or `ctx.ResourceManager()` directly.
169+
170+
Typical resource query:
171+
172+
```go
173+
resources, err := manager.ListByIndexes[*meshresource.ServiceProviderMetadataResource](
174+
ctx.ResourceManager(),
175+
meshresource.ServiceProviderMetadataKind,
176+
[]index.IndexCondition{...},
177+
)
178+
```
179+
180+
Do not put store/index details into handlers. Keep HTTP binding in handlers and resource logic in services.
181+
182+
## Frontend contract
183+
184+
Frontend API callers live under `ui-vue3/src/api/`. If a response field, request parameter, or endpoint path changes, check both Console model structs and frontend caller usage.
185+
186+
## Common failure modes
187+
188+
- Route registered under wrong group or duplicate service group block.
189+
- Handler binds query when frontend sends JSON, or vice versa.
190+
- Model tags do not match frontend parameter names.
191+
- Service returns raw resource shape not expected by frontend view.
192+
- Error returned directly instead of through `util.HandleServiceError`.
193+
- Optional managers such as CounterManager or LockManager are nil.
194+
195+
## Review checklist
196+
197+
- Route path and HTTP method match frontend usage.
198+
- Handler binding matches request source.
199+
- Request/response models have correct tags and JSON field names.
200+
- Service owns business logic and uses ResourceManager/store helpers.
201+
- Response uses `CommonResp` consistently.
202+
- Frontend API client is updated when contract changes.

‎.agents/skills/dubbo-admin-discovery/SKILL.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
name: dubbo-admin-discovery
3+
description: Implements and reviews dubbo-admin registry discovery changes. Use when the user asks about Zookeeper or Nacos discovery, ListAndWatch, informers, discovery factories, discovery subscribers, ServiceProviderMetadata or ServiceConsumerMetadata processing, or Application, Service, RPCInstance, and Instance derivation under pkg/core/discovery/ and pkg/core/controller/. Do not use for engine-sourced RuntimeInstance behavior.
4+
---
5+
6+
# dubbo-admin Discovery
7+
8+
## Purpose
9+
10+
Use this skill to trace registry-sourced resources from ListWatcher input through informer events, EventBus dispatch, subscribers, store writes, and derived mesh resources.
11+
12+
## When to use
13+
14+
Use for Zookeeper or Nacos registry flow, discovery ListWatchers, discovery subscribers, metadata-derived services, application instance counts, and registry event bugs.
15+
16+
Do not use for Kubernetes runtime infrastructure engine flow; use `dubbo-admin-engine` for RuntimeInstance behavior.
17+
18+
## Inputs
19+
20+
Required:
21+
- Registry type, resource kind, subscriber, or discovery package path.
22+
- The event or resource transition being changed or debugged.
23+
24+
Optional:
25+
- Example registry metadata.
26+
- Store query or index involved.
27+
- Console API result affected by discovery data.
28+
29+
If missing, start at `pkg/core/discovery/component.go` and identify the subscriber for the resource kind.
30+
31+
## Workflow
32+
33+
1. Read `pkg/core/discovery/component.go` for dependencies, informer creation, subscriber registration, and start behavior.
34+
2. Inspect `pkg/core/controller/listwatcher.go` and `pkg/core/controller/informer.go`.
35+
3. Follow registry-specific ListWatcher creation through `pkg/core/discovery/factory.go`.
36+
4. Read the relevant subscriber under `pkg/core/discovery/subscriber/`.
37+
5. Verify resource writes against store and index behavior.
38+
6. Read `references/discovery-flow.md` for subscriber registration and event flow details.
39+
40+
## Output format
41+
42+
Return the resource flow, affected subscriber, store/index interactions, changed files, and validation commands or residual test gaps.
43+
44+
## Validation
45+
46+
- Confirm informer events emit the expected `cache.DeltaType`.
47+
- Confirm subscriber `ResourceKind()` matches the event resource kind.
48+
- Confirm derived resources use stable resource keys.
49+
- Run targeted subscriber or controller tests; use `make test` for broad discovery changes.
50+
51+
## Edge cases
52+
53+
- Nacos and Zookeeper register extra subscribers conditionally.
54+
- Delete events may need old objects and must not assume `NewObj()` exists.
55+
- If dispatch semantics are the problem, switch to `dubbo-admin-events`.
56+
57+
## References
58+
59+
- Read `references/discovery-flow.md` for ListWatcher, informer, and subscriber details.

‎.agents/skills/dubbo-admin-discovery/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "Dubbo Admin Discovery"
3+
short_description: "Guide for dubbo-admin discovery flow"
4+
default_prompt: "Use $dubbo-admin-discovery to trace or modify dubbo-admin discovery event flow."

‎.agents/skills/dubbo-admin-discovery/evals/evals.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
"skill_name": "dubbo-admin-discovery",
3+
"evals": [
4+
{
5+
"id": "obvious-trigger",
6+
"prompt": "Fix ServiceProviderMetadataEventSubscriber so Service resources update after provider metadata deletion.",
7+
"expected_behavior": "Use discovery subscriber and informer event flow."
8+
},
9+
{
10+
"id": "paraphrased-trigger",
11+
"prompt": "Nacos registry changes are not reflected in applications shown by dubbo-admin.",
12+
"expected_behavior": "Trace registry ListWatcher, informer events, subscribers, and store writes."
13+
},
14+
{
15+
"id": "file-based-trigger",
16+
"prompt": "Review pkg/core/discovery/component.go and pkg/core/discovery/subscriber/service_consumer_metadata.go.",
17+
"expected_behavior": "Use this skill because discovery orchestration and subscribers are touched."
18+
},
19+
{
20+
"id": "no-trigger",
21+
"prompt": "Change how EventBus handles subscriber errors for all domains.",
22+
"expected_behavior": "Do not use this skill as primary; use dubbo-admin-events."
23+
},
24+
{
25+
"id": "conflict-trigger",
26+
"prompt": "A RuntimeInstance from Kubernetes is not merged into an Instance resource.",
27+
"expected_behavior": "Use dubbo-admin-engine, not discovery, because RuntimeInstance is engine-sourced."
28+
}
29+
]
30+
}

0 commit comments

Comments
 (0)