chore: rename .agent to .agents and update skill path references

.agents/skills/new-api/references/handler_example.go

@@ -0,0 +1,55 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package references
+
+import (
+	"net/http"
+
+	"github.com/Rain-kl/Wavelet/internal/shared/response"
+	"github.com/gin-gonic/gin"
+)
+
+// createChannelRequest 客户端请求体 DTO
+type createChannelRequest struct {
+	Name string `json:"name" binding:"required,min=1,max=100"`
+}
+
+// createChannelResponse API 响应体 DTO
+type createChannelResponse struct {
+	ID   int64  `json:"id"`
+	Name string `json:"name"`
+}
+
+// CreateChannel 示例：产品域 Handler（应放在 internal/apps/channel/routers.go）
+// @Summary 创建频道
+// @Description 示例：语义路径下的业务接口，而非 /api/v1/custom/...
+// @Tags channel
+// @Accept json
+// @Produce json
+// @Param request body createChannelRequest true "业务请求参数"
+// @Success 200 {object} response.Any{data=createChannelResponse} "操作成功"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Router /api/v1/channels [post]
+func CreateChannel(c *gin.Context) {
+	var req createChannelRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, "参数校验失败")
+		return
+	}
+
+	// 通常结合 oauth.LoginRequired()；此处仅演示从上下文取用户
+	userID := int64(9527)
+
+	result, err := CreateChannelLogic(c.Request.Context(), userID, req.Name)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(createChannelResponse{
+		ID:   result.ID,
+		Name: result.Name,
+	}))
+}

.agents/skills/new-api/references/logics_example.go

@@ -0,0 +1,38 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package references
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	"go.uber.org/zap"
+)
+
+// channelCreated 示例 logics 返回值（真实代码可用 model 或专用 DTO）
+type channelCreated struct {
+	ID   int64
+	Name string
+}
+
+// CreateChannelLogic 示例：模块内闭环业务（放在 apps/channel/logics.go）
+// 接收 context.Context，不依赖 gin.Context，便于单测与 Worker 复用。
+func CreateChannelLogic(ctx context.Context, userID int64, name string) (*channelCreated, error) {
+	if name == "" {
+		return nil, errors.New("name cannot be empty")
+	}
+
+	logger.Info(ctx, "creating channel",
+		zap.Int64("user_id", userID),
+		zap.String("name", name),
+	)
+
+	// 轻量级本地逻辑；复杂持久化可进 model/repository
+	return &channelCreated{
+		ID:   1,
+		Name: fmt.Sprintf("%s (by %d)", name, userID),
+	}, nil
+}

.agents/skills/new-api/references/service_example.go

@@ -0,0 +1,40 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package references
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	"go.uber.org/zap"
+)
+
+// ChannelService 示例有状态 Service（放在 internal/apps/channel/service.go）
+// 需要注入 DB/客户端时使用；简单逻辑优先 logics.go 纯函数。
+type ChannelService struct {
+	// 例如：repo ChannelRepository
+}
+
+// NewChannelService 构造函数
+func NewChannelService() *ChannelService {
+	return &ChannelService{}
+}
+
+// Create 核心业务：首位参数必须是 context.Context；禁止依赖 Gin。
+func (s *ChannelService) Create(ctx context.Context, userID int64, name string) (int64, error) {
+	if name == "" {
+		return 0, errors.New("name cannot be empty")
+	}
+
+	logger.Info(ctx, "channel service create",
+		zap.Int64("user_id", userID),
+		zap.String("name", name),
+	)
+
+	// DB 事务、远程调用等
+	_ = fmt.Sprintf("user=%d name=%s", userID, name)
+	return 1, nil
+}