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

AGENTS.md

@@ -72,14 +72,14 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 
 | Skill | 何时使用 |
 | :--- | :--- |
-| `new-api` | 添加或修改自定义业务 API、Handler、服务层逻辑、自定义路由注册 |
-| `new-async-task` | 添加或修改 Asynq 任务、定时任务、TaskHandler、任务元数据 |
-| `new-setting` | 添加或修改系统/业务/公开设置、`/admin/system` 参数或 `/admin/settings` 图形化设置 |
-| `database-migration` | 数据库表结构变更、goose SQL 迁移（PG/SQLite/ClickHouse）、seed 数据 |
+| `new-api` | 基于 Cordis 插件开发业务 HTTP API、通过 `ctx.Router()` 声明路由与挂载中间件 |
+| `new-async-task` | 基于 Cordis 插件通过 `ctx.Task()` 与 `ctx.Schedule()` 注册 Asynq 异步任务与定时调度 |
+| `new-setting` | 基于 Cordis 插件通过 `ctx.Settings()` 声明配置 Schema、绑定 YAML 配置或管理台热加载设置 |
+| `database-migration` | 插件自包含 `embed.FS` 独立 Goose SQL 迁移（PG/SQLite 双方言、ClickHouse 分析库） |
+| `cache-framework` | 基于 `ctx.Cache()` 与 `contracts.CacheService` 访问三层缓存（RAM L1 + Redis L2 + Pub/Sub 同步） |
 | `logstore` | 日志/分析用途表、`internal/repository/logstore`、切换日志主库、PG/SQLite 回落 |
-| `clickhouse-batchwriter` | ClickHouse 批量写入、`internal/infra/persistence/batchwriter` 接入、分析表异步 flush、背压与写入路径改造 |
-| `file-upload` | 业务上传文件、Worker 程序化摄取、`upload.Ingest` 策略选型、文件访问与 `w_uploads` / 统计排查 |
-| `cache-framework` | 新增或修改业务缓存（RAM/Redis/DB 三层读路径）、缓存失效、多节点 pub/sub 同步、评估高频读是否应接入缓存 |
+| `clickhouse-batchwriter` | ClickHouse 批量写入、`internal/infra/persistence/batchwriter` 接入、分析表异步 flush 与背压策略 |
+| `file-upload` | 业务上传文件、Worker 程序化摄取、`upload.Ingest` / `contracts.StorageService`、文件访问与统计 |
 | `push-notification` | 系统通知推送事件、统一触发器投递、带消息推送的业务功能 |
 | `release-guide` | 根据自上一正式版本 Tag 以来的提交整理 Version Bump 提交信息以触发双语 Release |
 | `shadcn` | 添加、修改或组合 shadcn/ui 组件 |
@@ -87,24 +87,37 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 ## 严格遵循事项 (Guardrails)
 
 - 切勿删除 `frontend/node_modules`。
-- 保持 `internal/util/` 绝对纯净，禁止导入 Gin、GORM、sessions 等 Web/数据库框架包。
+- 保持 `pkg/util/` 绝对纯净，禁止导入 Gin、GORM、sessions 等 Web/数据库框架包。
 - 测试用例禁止硬编码相对路径创建临时目录，统一使用 Go 内置 `t.TempDir()`。
-- 所有 HTTP 路由仅在 `internal/router/router.go` 中作为高层分发注册。
 - 修改 API Handler 后运行 `make swagger`，完成代码开发后必须依次运行 `make code-check` 与 `make format`。
-- 业务模块必须复用平台缓存/文件服务：文件摄取统一用 `upload.Ingest`，删除用 `upload.Remove`/`upload.RemoveOwned`；禁止直接写 `w_uploads` 或绕过 upload 域直接操作 `infra/objectstore`。
-- 禁止在 `init()` 中注册跨模块集成（任务 Handler、推送事件、域事件监听器等），统一在 `internal/platform/bootstrap` 显式装配并在 `internal/cmd` 入口调用。
-- 核心业务模块（`oauth`、`user`）禁止直接 import `push` 或 `custom_events` 触发通知，须通过 `internal/listener` 发射域事件。
-- API 错误响应必须通过 `response.Abort*` 中断请求，由 `ErrorHandlerMiddleware` 统一写出 JSON 并记录 Trace；禁止在 Handler/中间件中直接 `c.JSON(status, response.Err(...))` 或 `200` 返回 `error_msg`。
-- **分层**：`apps → repository → model`，`repository → infra/persistence`；禁止 `model → repository`。
-  - `model`：实体、表名、配置 key、查询 DTO、无 IO 规则。禁止 `db.DB` / Redis / CH；禁止 `import repository`。GORM hook 仅可 mutate 自身字段，禁止在 hook 内再查 DB/缓存。
-  - `repository`：唯一持久化入口。apps/logics 禁止为业务 CRUD 直调 `db.DB`（管理端 SQL 控制台、infra 内部等例外保留）。禁止新增 `model.Get/List/Create/...` 类数据访问 API。
-- 日志/分析表（访问日志、审计流水、可观测时序）走 `internal/repository/logstore`，禁止 apps 直连 `repository/analytics` 或 `db.ChConn`/`db.ChDB`。判定与接入步骤见 `logstore` skill。
 
-## 技术栈与项目目录结构
-
-### 技术栈
-- **后端**：Go 1.25+、Gin、GORM、PostgreSQL、可选 ClickHouse、Redis、Asynq、Cobra、Viper、Swaggo、OpenTelemetry、Zap、AWS SDK v2。
-- **前端**：Next.js (App Router)、TypeScript、Tailwind CSS、pnpm、shadcn/ui。
+### Cordis 架构核心防线与分层规范
+- **微内核 (`core/`)**：
+  - 上下文总线（`Context`）、泛型依赖注入（`Container`）、生命周期编排（`Lifecycle`）、扩展点定义（`extpoints/`）与领域事件总线（`EventBus`）。
+  - **严禁**包含任何具体业务逻辑，**严禁** import `gin`、`gorm`、`asynq` 等具体运行时依赖。
+- **服务契约 (`core/contracts/`)**：
+  - 跨插件通信的统一公开 Go Interface（如 `AuthService`、`UserService`、`CacheService`、`DBService`、`StorageService`）与公共 DTO。
+  - **严禁**包含任何具体业务实现或 SQL 操作。
+- **自包含插件 (`plugins/`)**：
+  - 所有业务功能与驱动实现均以扁平自包含插件形式存在（`plugins/drivers/`、`plugins/infra/`、`plugins/domain/` 或下游 `custom_plugins/`）。
+  - 每个插件实现 `core.Plugin`（`Name() string` 与 `Apply(ctx *core.Context) error`）。
+  - 插件内部就近组织 Handler、Service、Model 与 Migration。
+- **插件通信与依赖隔离**：
+  - **严禁跨包 import internal/私有实现**：插件之间严禁直接 import 对方具体实现包代码。
+  - **单向服务契约调用**：调用方仅面向 `core/contracts` 编程，在 `Apply` 中通过 `core.Provide[contracts.XxxService](ctx, svc)` 注册服务，通过 `core.Inject[contracts.XxxService](ctx)` 或 `ctx.Using(func(svc contracts.XxxService) { ... })` 声明式解析。
+  - **事件总线广播**：状态联动与解耦通信统一通过强类型事件 `ctx.Events().Emit()` 广播，由感兴趣的插件通过 `ctx.Events().On()` 订阅，消除双向依赖与循环引用。
+- **扩展点自包含注册**：
+  - **HTTP 路由**：插件自包含在 `Apply` 中通过 `ctx.Router().Group(...)` 挂载路由与中间件，禁止跨插件散落注册。
+  - **异步与定时任务**：插件自包含在 `Apply` 中通过 `ctx.Task().Register(...)` 与 `ctx.Schedule().RegisterCron(...)` 声明。
+  - **动态配置**：插件自包含在 `Apply` 中通过 `ctx.Settings().Register(core.SettingSchema{...})` 声明配置模式，通过 `ctx.Config().Bind(...)` 绑定 YAML 配置。
+  - **数据迁移**：插件自包含在内部维护 `migrations/*.sql`，通过 `//go:embed` 打包并在 `Apply` 中通过 `ctx.Migrations().Register(pluginID, embedFS)` 注入。
+- **表单一所有者原则 (Single Owner Principle)**：
+  - 每张数据表有且仅由一个所有者插件声明与维护（表名使用插件前缀如 `w_order_*`）。
+  - 严禁插件 B 跨过所有者插件 A 直接 DDL/DML 旁路读写表 A，必须调用插件 A 暴露的 `contracts` 接口或订阅事件。
+- **平台服务复用**：
+  - 文件摄取统一使用 `upload.Ingest` / `contracts.StorageService`，禁止绕过存储域直接操作底层 Bucket 或直写文件表。
+  - 业务缓存统一使用 `ctx.Cache()`（`contracts.CacheService`）或标准缓存框架，禁止自研不带失效广播的本地 map。
+  - 数据库操作通过 `ctx.DB()`（`contracts.DBService`）获取受事务与 Trace 保护的连接。
 
 ## 后端开发规范
 
@@ -113,20 +126,18 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 - **成功**：HTTP 200，写出 `c.JSON(http.StatusOK, response.OK(data))` 或 `response.OKNil()`。
 - **失败**：使用 `internal/shared/response` 的 `Abort*` 系列函数（如 `AbortBadRequest`、`AbortUnauthorized`、`AbortNotFound`、`AbortInternal`）中断请求。
 - **错误文案**：使用模块内 `errs.go` 中的 camelCase 字符串常量（如 `errBindParamsFailed`），禁止暴露底层数据库/系统错误细节给客户端。
-- **Logics 分工**：`logics.go` 只接受 `context.Context`，返回 `(result, error)`，严禁依赖 `*gin.Context` 或调用 `c.JSON`/`Abort*`。
+- **Service/Logics 分工**：业务逻辑层只接受 `context.Context`，返回 `(result, error)`，严禁依赖 `*gin.Context` 或调用 `c.JSON`/`Abort*`。
 - **错误日志**：底层错误在 Handler/Logic 边界用 `pkg/logger` 打印日志，禁止使用 `_ = ...` 静默吞掉关键错误。
 
 ### 数据库操作
-- 平台域（user、auth_source、access_token、schedule、task_execution）的持久化必须走 `internal/repository`，禁止在 `internal/model` 中调用 `db.DB` / Redis。
-- 管理员代码推荐使用 `db.DB(ctx)`（`internal/infra/persistence`，包名 `db`）保证 Trace 链路透传。
-- 禁止在 Handler 写复杂 SQL；迁移文件位于 `internal/infra/persistence/migrator/goose/`（禁止 GORM AutoMigrate）。
+- 插件数据库表结构严禁使用 GORM AutoMigrate，统一编写 Goose SQL 迁移并嵌入二进制。
 - 不创建物理外键（显式建索引）；Go 模型零值需与数据库默认值匹配。
 - **SQL LIKE 查询防注入与转义**：所有含用户输入的模糊查询必须调用 `pkg/util.EscapeLike` 转义通配符，并显式指定 `ESCAPE '\\'` 语法（如 `Where("username LIKE ? ESCAPE '\\'", util.EscapeLike(keyword)+"%")`），同时兼容 PostgreSQL 与 SQLite 方言并杜绝通配符注入攻击。
 
 ### 并发与安全防护规范
 - **Goroutine 安全**：禁止直接使用裸 `go func()`；统一使用 `pkg/util.Go`，确保具备未捕获 panic 恢复和调用栈日志记录能力。
-- **Pub/Sub 监听并发安全**：启动 Redis Pub/Sub 订阅监听前，必须捕获局部客户端实例（如 `redisClient := db.Redis`），禁止在 goroutine 闭包中直读可变全局 `db.Redis`；提供 `Stop*Listener` 时必须维护 `done` 通道等待 goroutine 完整退出后再重置状态，消除测试或重连时的数据竞争。
-- **Session 固定攻击防御**：用户登录/授权成功后，必须调用 `oauth.SetLoginSession`（内部执行 Session ID 轮换），防止 Session 固定攻击。
+- **Pub/Sub 监听并发安全**：启动 Redis Pub/Sub 订阅监听前，必须捕获局部客户端实例，禁止在 goroutine 闭包中直读可变全局变量；提供停止监听接口时必须维护 `done` 通道等待 goroutine 完整退出后再重置状态，消除数据竞争。
+- **Session 固定攻击防御**：用户登录/授权成功后，必须调用 Session 轮换逻辑，防止 Session 固定攻击。
 - **防账户枚举与时序攻击**：
   - 登录失败统一返回模糊报错；当查询用户不存在时，必须调用 `pkg/util.DummyCheckPassword` 执行同等开销的 bcrypt 哈希计算，彻底消除时序侧信道攻击。
   - 验证码、签名 Token 等敏感字符串比对必须使用 `crypto/subtle.ConstantTimeCompare` 常量时间比对。
@@ -146,7 +157,7 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
     - **色彩对比度**：正文、提示、徽章等小字颜色在亮色/暗色模式下必须满足 WCAG AA（对比度 ≥ 4.5:1）。
 - **组件拆分与维护**：
     - 物理路由页面 `page.tsx` 仅维护高级骨架与布局。
-    - 单文件超过 600 行或含多 Tab/大复杂区块时，必须按就近原则拆分为子组件存放在路由同级的 `components/` 局部目录中（参考 `/admin/database` 的模块化拆分结构）。
+    - 单文件超过 600 行或含多 Tab/大复杂区块时，必须按就近原则拆分为子组件存放在路由同级的 `components/` 局部目录中。
 - **样式与服务**：
     - 优先使用 shadcn/ui 的 `variant` 和全局 CSS 变量，不要在业务代码中硬编码颜色/背景。
     - 前端请求统一在 `frontend/lib/services/<name>/` 中继承 `BaseService` 编写并在 `index.ts` 注册。
@@ -159,5 +170,4 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
     - key 使用 camelCase 分层（如 `auth.login.submit`）；完整短语作为 value，禁止在组件内拼接句子。
     - 新增或修改文案时必须**同步**更新 `zh-CN.json` 与 `en.json`，保持 key 树一致。
     - 语言选项展示用自称：`中文` / `English`（不随当前 UI 语言翻译）。
-    - 日期/数字格式化使用 locale 感知 helper（如 `formatDateTime`），禁止写死 `'zh-CN'` / `date-fns` 的 `zhCN`（除非该路径尚未迁移且不在本次改动范围）。
-    - 设计说明见 `docs/superpowers/specs/2026-07-24-frontend-i18n-design.md`。
+    - 日期/数字格式化使用 locale 感知 helper（如 `formatDateTime`），禁止写死 `'zh-CN'` / `date-fns` 的 `zhCN`。