docs(agents): update AGENTS.md and development skills for cordis architecture

.agents/skills/new-async-task/SKILL.md

@@ -1,121 +1,157 @@
 ---
 name: "new-async-task"
-description: "Wavelet 项目专用：新增或修改 Asynq 异步任务、后台任务、定时任务、任务元数据、TaskHandler、TaskParam、PayloadValidator、AppendLog、任务重试、任务执行记录或 Admin 任务 API 时必须使用。"
+description: "Wavelet 项目专用：新增或修改基于 Cordis 插件的 Asynq 异步任务、后台 Worker 消费处理器、Cron 定时调度任务与任务执行追踪时必须使用。"
 ---
 
-# 异步任务开发
+# 异步任务与定时调度开发规范 (Cordis 插件化架构)
 
-开始前阅读根目录 `AGENTS.md`。只修改任务相关链路，遵守项目路由、日志、数据库迁移和质量门禁要求。
+本技能是 Wavelet 在 Cordis 微内核与插件化架构下，进行 Asynq 异步后台任务与 Cron 定时调度开发的唯一指导规范。
 
-## 开始前
+---
 
-按任务范围检查当前实现：
+## 1. 核心架构：插件内自包含任务声明
 
-- `internal/infra/task/handler.go`：`TaskHandler`、`TaskResult`、`PayloadValidator`
-- `internal/infra/task/meta.go`：`TaskMeta`、`TaskParam`
-- `internal/infra/task/executor.go`：下发、执行、日志、重试、`OnTaskCompleted` 订阅
-- `internal/infra/task/handlers/register.go`：Handler 和元数据注册（由 bootstrap 调用）
-- `internal/platform/bootstrap/bootstrap.go`：任务注册与进程级装配入口
-- `internal/infra/task/worker/worker.go`：Worker 路由和队列
-- `internal/infra/task/scheduler/scheduler.go`：定时调度
-- `internal/apps/admin/task/routers.go`：Admin 任务 API
-- `internal/model/task_execution.go`：执行记录和日志持久化
+在 Cordis 架构中，后台 Worker 消费与定时调度**不再集中在中心化的注册表**，而是由各个业务插件在自身的 `Apply` 方法中通过微内核扩展点直接声明。
 
-需要模板时阅读 [references/CODE-EXAMPLES.md](references/CODE-EXAMPLES.md)。
+### 扩展点矩阵
 
-## 实现要求
+| 扩展点方法 | 说明 | 适用场景 |
+| :--- | :--- | :--- |
+| `ctx.Task().Register(pattern, handler, opts...)` | 注册 Asynq 任务类型与消费处理器 | 异步耗时计算、队列任务、通知外发 |
+| `ctx.Schedule().RegisterCron(spec, taskType, payload)` | 注册 Cron 表达式定时调度任务 | 周期统计、定时清理、健康检查 |
 
-### 任务定义
+---
 
-- 在 `internal/apps/<module>/tasks.go` 定义任务类型、Admin 任务类型和 `TaskMeta`。
-- Asynq 任务类型使用 `<module>:<action>` 格式。
-- 完整设置 `Type`、`AsynqTask`、`Name`、`Description`、`MaxRetry`、`Queue`、`Retryable`。
-- 有参数任务必须定义 payload struct。
-- `TaskParam.Name` 必须与 payload JSON tag 一致。
-- `TaskParam` 只描述前端表单，不代替服务端校验。
+## 2. 异步任务开发全流程
 
-### Handler
+### 步骤 1：定义任务 Payload 结构与类型常量
 
-- Handler 必须实现 `task.TaskHandler`。
-- 有参数任务必须实现 `task.PayloadValidator`，负责校验和标准化 Admin 下发参数。
-- `Execute` 必须再次解析 payload；不要假设入口一定经过 Admin 校验。
-- 成功返回 `&task.TaskResult{Message: ..., Detail: ...}`。
-- 失败返回 error，由任务框架处理状态和重试。
-- 不要吞掉关键错误。
-- 复杂 SQL 放到 `internal/model/` 或模块内的业务服务层（如 `internal/apps/<module>/service.go` 或 `logics.go`）。
+在插件内（如 `plugins/domain/order/tasks.go`）：
 
-### 注册
+```go
+package order
 
-- 在 `internal/infra/task/handlers/register.go` 同时注册 Handler 和 `TaskMeta`。
-- 不要在其他位置单独注册任务。
-- **禁止**在业务包 `routers.go` 或 `init()` 中调用 `task.RegisterHandler`；统一由 `bootstrap.RegisterTasks()` → `taskhandlers.Register()` 在进程启动时装配。
-- 任务完成钩子（如 push 通知）通过 `task.OnTaskCompleted` 注册，在 `bootstrap.RegisterTaskListeners()` 中装配（Worker/`all` 进程）。
+import (
+	"context"
+	"encoding/json"
+	"time"
 
-### 进程装配分工
+	"github.com/hibiken/asynq"
+)
 
-| 进程 | 注册入口 |
-| :--- | :--- |
-| `api` | `cmd/api.go` → `bootstrap.RegisterAPI()`（含 `RegisterTasks`） |
-| `worker` | `worker.StartWorker()` → `bootstrap.RegisterWorker()`（含 `RegisterTasks` + `RegisterTaskListeners`） |
-| `scheduler` | `scheduler.StartScheduler()` → `bootstrap.RegisterScheduler()` |
-| `all` | `cmd/all.go` → `bootstrap.RegisterAll()` |
+const (
+	TaskTypeOrderTimeoutCancel = "order:timeout_cancel"
+)
 
-所有 `Register*` 使用 `sync.Once`，重复调用安全。
+// OrderTimeoutPayload 定义任务入参
+type OrderTimeoutPayload struct {
+	OrderID   string `json:"order_id"`
+	Reason    string `json:"reason"`
+	CreatedAt int64  `json:"created_at"`
+}
+```
 
-### 测试
+### 步骤 2：实现任务执行处理器 (Handler)
 
-- 依赖已注册任务类型或 Handler 的测试（如 `internal/apps/admin/task/routers_test.go`），必须在 setup 中显式调用 `bootstrap.RegisterTasks()`。
-- 不得依赖 `init()` 副作用或 import 链触发注册。
+Handler 必须接受 `ctx context.Context, t *asynq.Task`，返回 `error`：
 
-## 日志要求
+```go
+func (p *Plugin) handleOrderTimeoutCancel(ctx context.Context, t *asynq.Task) error {
+	var payload OrderTimeoutPayload
+	if err := json.Unmarshal(t.Payload(), &payload); err != nil {
+		return err // 反序列化失败，直接中断
+	}
 
-- 在 `TaskHandler.Execute` 中使用 `task.AppendLog(ctx, format, args...)`。
-- 记录任务开始、参数摘要、批次进度、关键状态、可继续错误和完成摘要。
-- 批量处理按批次记录；禁止为大循环中的每条数据写日志。
-- 不要直接修改任务日志的 Redis key 或 `w_task_executions.log`。
+	// 记录任务日志
+	// task.AppendLog(ctx, "开始处理订单超时关单: order_id=%s", payload.OrderID)
 
-日志框架约束：
+	// 执行业务逻辑
+	if err := p.svc.CancelTimeoutOrder(ctx, payload.OrderID, payload.Reason); err != nil {
+		// 返回 error 触发 Asynq 框架自动重试
+		return err
+	}
 
-- 执行状态实时写入数据库：`pending`、`running`、`succeeded`、`failed`。
-- 实时日志写入 Redis，每个任务最多保留最近 1000 行。
-- Redis 日志 TTL 为 24 小时，每次追加时刷新。
-- 查询时优先返回 Redis 日志，Redis 不存在时读取数据库。
-- 任务成功或自动重试耗尽后，将日志写入数据库并删除 Redis 缓冲。
-- 自动重试期间保留同一 taskID 的 Redis 日志。
+	return nil
+}
+```
 
-## 重试要求
+### 步骤 3：在插件 `Apply` 中注册任务与定时调度
 
-- Handler 返回 error 以触发 Asynq 自动重试。
-- 不要在 Handler 内自行实现重复重试循环。
-- Admin 手动重试只允许：
-  - 原任务状态为 `failed`
-  - `Retryable=true`
-  - `RetryCount < MaxRetry`
-- 修改重试行为时同时检查：
-  - `internal/infra/task/executor.go`
-  - `internal/model/task_execution.go`
-  - `internal/apps/admin/task/routers.go`
-  - 前端任务执行列表
+```go
+func (p *Plugin) Apply(ctx *core.Context) error {
+	// 1. 注册异步任务处理器
+	ctx.Task().Register(
+		TaskTypeOrderTimeoutCancel,
+		p.handleOrderTimeoutCancel,
+		extpoints.WithTaskRetry(3),
+		extpoints.WithTaskTimeout(5*time.Minute),
+	)
 
-## 定时任务
+	// 2. 注册定时调度任务 (例如每天凌晨 2 点执行汇总)
+	ctx.Schedule().RegisterCron(
+		"0 2 * * *",
+		"order:daily_settlement",
+		map[string]any{"scope": "all"},
+	)
 
-- 默认定时任务必须通过 Goose SQL 迁移写入 `schedules`。
-- PostgreSQL 和 SQLite 迁移必须同时提供。
-- 初始化 SQL 必须幂等。
-- 涉及迁移时使用 `database-migration` skill。
+	return nil
+}
+```
 
-## Admin API
+### 步骤 4：在业务逻辑中投递异步任务
 
-- Handler 放在现有 Admin task 模块或 `internal/apps/admin/<module>/`。
-- 路由只在 `internal/router/router.go` 注册。
-- 响应保持 `{ "error_msg": "", "data": ... }`。
-- 分页数据保持 `{ "total": 0, "results": [] }`。
-- Swagger 注释必须完整；API 变化后运行 `make swagger`。
+当业务需要下发延迟或异步任务时：
 
-## 前端
+```go
+func (s *OrderService) EnqueueTimeoutCheck(ctx context.Context, orderID string) error {
+	payloadBytes, _ := json.Marshal(OrderTimeoutPayload{
+		OrderID:   orderID,
+		Reason:    "15分钟未支付自动关单",
+		CreatedAt: time.Now().Unix(),
+	})
 
-- 仅任务元数据变化时，优先复用现有动态任务表单，不新增页面。
-- API 调用必须通过 `frontend/lib/services/`。
-- 修改 shadcn/ui 时使用 `shadcn` skill。
-- 不使用 `any`。
-- 页面根容器使用 `w-full`，不添加页面级 `max-w-*`。
+	task := asynq.NewTask(
+		TaskTypeOrderTimeoutCancel,
+		payloadBytes,
+		asynq.ProcessIn(15*time.Minute), // 延迟 15 分钟执行
+		asynq.MaxRetry(3),
+	)
+
+	// 投递到任务客户端
+	_, err := s.taskClient.EnqueueContext(ctx, task)
+	return err
+}
+```
+
+---
+
+## 3. 运行切面透明性 (Profile Transparency)
+
+Cordis 微内核支持多种启动切面（`api`、`worker`、`schedule`、`all`）：
+- 插件开发者**无需在插件代码中编写 `if mode == "worker"` 分支**。
+- 插件只需在 `Apply` 中把任务与调度注册进 `Context`。
+- 当进程以 `worker` 切面启动时，微内核的 `driver_asynq_worker` 驱动会自动拾取并监听已注册的任务。
+- 当进程以 `schedule` 切面启动时，`driver_asynq_cron` 驱动会自动启动调度器引擎。
+
+---
+
+## 4. 任务日志与重试规范
+
+1. **日志记录**：
+   - 记录任务启动参数摘要、分批处理进度及最终完成统计。
+   - 大循环处理中应按批次记录日志，禁止每条数据单独打日志刷屏。
+2. **重试机制**：
+   - Handler 返回 error 即自动触发 Asynq 重试策略。
+   - 禁止在 Handler 内部编写裸 `for` 死循环重试。
+3. **幂等性保障**：
+   - 任务由于网络波动或超时可能被重复消费，业务操作必须实现幂等保护（如基于订单状态机检查或分布式锁 `ctx.DistLock()`）。
+
+---
+
+## 5. 质量验证
+
+```bash
+make format
+make code-check
+go test ./plugins/...
+```