imks/AGENTS.md

AGENTS.md — 开发规范 / Development Guidelines

本文件为所有 AI 编码助手（Claude Code、pi、Cursor 等）提供统一的开发指导。 This file provides unified development guidelines for all AI coding assistants.

最后更新 / Last Updated: 2026-06-11

---

目录 / Table of Contents

1. 语言 / Language
2. 代码风格 / Code Style
3. 禁止模式 / Forbidden Patterns
4. 错误处理 / Error Handling
5. 安全规范 / Security
6. 数据库规范 / Database
7. Socket.IO 事件规范 / Socket.IO Event Conventions
8. 日志与可观测性 / Logging & Observability
9. 性能规范 / Performance
10. 测试规范 / Testing
11. Git 规范 / Git Workflow
12. 工作流程 / Workflow
13. 架构决策记录 / ADR
14. 审查清单 / Review Checklist

---

1. 语言 / Language

Always respond in Chinese (中文). Use the user's language for all conversations and explanations. Code, commands, and technical terms can remain in English.

始终使用中文回复。代码、命令和技术术语可以保留英文。

---

2. 代码风格 / Code Style

2.1 基本原则 / Basic Principles

规则	说明
遵循现有风格	Follow existing project conventions
有意义命名	Use meaningful variable names; avoid single-letter names except loop counters
函数长度	Keep functions under 50 lines; split complex logic into smaller functions
嵌套深度	Maximum nesting depth: 3 levels; use early returns to flatten logic
注释	Add comments for complex logic only; prefer self-documenting code
文档注释	Public items must have /// doc comments; private items only when logic is non-obvious

2.2 Rust 最佳实践 / Rust Best Practices

// ✅ 正确 / Correct
fn get_message(id: Uuid) -> Result<Message, sqlx::Error> {
    let msg = db.find_message(id).await?;  // 使用 ? 传播错误
    Ok(msg)
}

// ❌ 错误 / Incorrect
fn get_message(id: Uuid) -> Message {
    db.find_message(id).await.unwrap()  // 禁止 unwrap()
}

规则	说明
错误传播	Use ? operator for error propagation; never use unwrap() or expect() in non-test code
unsafe	Avoid unsafe blocks; if necessary, add a // SAFETY: comment explaining why
clone()	Minimize clone() usage; prefer references or Arc for shared ownership
魔法数字	No magic numbers; define named constants with const
硬编码字符串	No hardcoded strings for config/status; use enums or constants
死代码	Remove dead code; don't leave commented-out code blocks
未完成代码	Don't commit unimplemented!(), todo!(), or FIXME without a tracking issue

2.3 导入规范 / Import Guidelines

// 标准库 → 第三方 crate → 本地模块
// stdlib → third-party crates → local modules
use std::sync::Arc;

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use uuid::Uuid;

use crate::models::message::Message;
use crate::socket::packet::Packet;

2.4 模型设计规范 / Model Design Guidelines

imks 的 models 层采用 一文件一实体 的拆分策略：

models/
├── mod.rs                   # 模块声明 + 公开 re-export
├── message.rs               # 核心 Message + MessageDetail + AuthorInfo + MessageType
├── message_attachment.rs    # 附件
├── message_bookmark.rs      # 书签/收藏
├── message_draft.rs         # 草稿
├── message_edit.rs          # 编辑历史
├── message_embed.rs         # 富媒体嵌入 + EmbedField
├── message_mention.rs       # @提及
├── message_pin.rs           # 置顶消息
├── message_poll.rs          # 投票 + Option + Vote
├── message_reaction.rs      # 表情反应
├── message_read_state.rs    # 已读状态
└── message_thread.rs        # 消息线程

每个模型文件包含：

• Row struct（sqlx::FromRow）
• Summary/detail struct（API 响应用，带 From 转换）
• 查询 SQL 常量（$1, $2... 占位符）
• CREATE_TABLE_SQL 迁移 DDL + 索引
• #[cfg(test)] 序列化/转换测试

---

3. 禁止模式 / Forbidden Patterns

以下代码模式在项目中严格禁止：

禁止项	说明
// ── xxxx ──────────	禁止使用此类分隔线注释
unwrap() / expect() (非测试)	在非测试代码中禁止使用；使用 ? 或 unwrap_or 等安全替代
panic!() / unreachable!()	除极少数不可能到达的分支外禁止使用
未处理的 todo!()	不得提交包含 todo!() 的代码，除非有对应的 issue 追踪
注释掉的代码	不得提交被注释的代码块；使用 Git 历史追溯
过深嵌套 (≥4层)	使用 early return、match、map/and_then 扁平化逻辑
过长函数 (>50行)	拆分为更小的、职责单一的函数
魔法数字	使用 const 定义命名常量
硬编码字符串	使用枚举或常量定义配置值/状态值
死代码	删除未使用的代码、导入和变量
Box<dyn Error> 在公共 API	使用具体错误类型替代 trait object

---

4. 错误处理 / Error Handling

4.1 错误类型体系 / Error Type System

imks 使用统一的 ImksError 枚举和 ImksResult<T> 类型别名，与 appks 的 AppError/AppResult 保持一致风格。

// error.rs — 统一错误类型
use thiserror::Error;

#[derive(Debug, Error)]
pub enum ImksError {
    // Protocol layer (engine)
    #[error("invalid engine packet type: {0}")]
    InvalidEnginePacketType(u8),
    #[error("invalid engine packet type char: {0}")]
    InvalidEnginePacketTypeChar(char),
    #[error("empty engine packet")]
    EmptyEnginePacket,
    #[error("invalid base64: {0}")]
    InvalidBase64(#[from] base64::DecodeError),
    #[error("invalid utf8 in packet: {0}")]
    InvalidPacketUtf8(#[from] FromUtf8Error),
    #[error("engine serialization error: {0}")]
    EngineSerialization(String),

    // Transport upgrade
    #[error("session not found for upgrade")]
    UpgradeSessionNotFound,
    #[error("session already closed, cannot upgrade")]
    UpgradeSessionClosed,
    #[error("invalid session state for upgrade")]
    UpgradeInvalidState,

    // Socket.IO layer
    #[error("invalid socket packet type: {0}")]
    InvalidSocketPacketType(u8),
    #[error("invalid socket packet type char: {0}")]
    InvalidSocketPacketTypeChar(char),
    #[error("empty socket packet")]
    EmptySocketPacket,
    #[error("invalid socket packet format: {0}")]
    InvalidSocketPacketFormat(String),
    #[error("missing namespace in socket packet")]
    MissingNamespace,
    #[error("invalid attachment count in binary event")]
    InvalidAttachmentCount,

    // Socket namespace
    #[error("namespace error: {0}")]
    Namespace(String),
    #[error("socket not found: {0}")]
    SocketNotFound(String),
    #[error("failed to send packet to socket: channel full")]
    SocketSendFull,

    // Adapter layer
    #[error("adapter redis error: {0}")]
    AdapterRedis(String),
    #[error("adapter nats error: {0}")]
    AdapterNats(String),
    #[error("adapter message bus error: {0}")]
    AdapterMessageBus(String),
    #[error("adapter serialization error: {0}")]
    AdapterSerialization(String),
    #[error("adapter room error: {0}")]
    AdapterRoom(String),

    // Database
    #[error("database error: {0}")]
    Database(#[from] sqlx::Error),

    // gRPC
    #[error("gRPC error: {0}")]
    GrpcStatus(#[from] tonic::Status),
    #[error("gRPC transport error: {0}")]
    GrpcTransport(#[from] tonic::transport::Error),

    // Serialization
    #[error("JSON error: {0}")]
    Json(#[from] serde_json::Error),

    // Auth
    #[error("auth error: {0}")]
    Auth(String),
    #[error("token expired")]
    TokenExpired,

    // General
    #[error("not found: {0}")]
    NotFound(String),
    #[error("invalid input: {0}")]
    InvalidInput(String),
    #[error("internal error: {0}")]
    Internal(String),
}

pub type ImksResult<T> = Result<T, ImksError>;

4.2 错误处理原则 / Error Handling Principles

原则	说明
统一类型	所有公共 API 返回 ImksResult<T>，不暴露子模块错误
显式处理	Handle all errors explicitly; no silent failures
From 转换	外部库错误通过 #[from] 自动转换，减少 map_err 样板
异步传播	Use ? operator; don't suppress errors in spawned tasks
通道满	Handle mpsc::TrySendError gracefully（buffer or log），don't panic
gRPC 错误	Map tonic::Status → ImksError::Grpc

4.3 错误日志格式 / Error Logging Format

// 记录错误时包含完整上下文
tracing::error!(
    error = %err,
    socket_sid = %sid,
    event = %event_name,
    "Failed to handle socket event"
);

4.4 现有子模块迁移 / Migration from Submodule Errors

当前部分子模块使用独立的 thiserror enum（PacketError、AdapterError），需要逐步迁移到 ImksError：

// 旧 / Old
pub enum PacketError { ... }
pub fn decode(data: &str) -> Result<Packet, PacketError> { ... }

// 新 / New
pub fn decode(data: &str) -> ImksResult<Packet> {
    // 内部仍可用 thiserror，对外转为 ImksError
    inner_decode(data).map_err(|e| ImksError::Packet(e.to_string()))
}

---

5. 安全规范 / Security

用户认证、授权、密码管理、2FA 等企业级安全由 appks 统一处理。 imks 作为内部消息服务，仅负责消息层面的安全。

5.1 基础安全 / Basic Security

规则	说明
密钥管理	Never hardcode secrets or API keys; use environment variables
输入验证	Always validate and sanitize user input（消息体、事件名、namespace path）
SQL 注入	Use parameterized queries（sqlx handles this automatically）
gRPC 安全	appks ↔ imks 的 gRPC 连接应使用 mTLS，防止密钥在传输中被截获

5.2 JWT 验证双模式 / Dual-Mode JWT Verification

imks 支持两种 JWT 验证模式（详见 rpc.md）：

模式	方式	延迟	适用场景
RPC 验证	调用 appks TokenService.VerifyToken()	实时	敏感操作
本地验证	启动时拉取 GetSigningKeys() 缓存到本地	零延迟	高频操作（消息收发）

推荐策略：普通操作（发消息、读频道）→ 本地验证，敏感操作 → RPC 验证。

5.3 连接安全 / Connection Security

要求	说明
命名空间验证	验证 namespace path（/ 开头，≤256 字符，无控制字符），防止 DoS
消息体大小	限制单条消息大小（EngineConfig.max_payload）
速率限制	按 socket 限制消息发送频率

---

6. 数据库规范 / Database

6.1 基础规范 / Basic Rules

规则	说明
参数化查询	Always use parameterized queries (sqlx does this by default)
迁移规范	All schema changes must go through migration files in migrate/
UUID v7	所有主键使用 UUID v7（时间有序），便于索引和游标分页
软删除	使用 deleted_at 字段进行软删除，不用硬删除
去规范化	对于高频读取的聚合字段（如 total_votes、unread_count），可在表中冗余存储

6.2 imks 管理的数据库表 / imks-Managed Tables

imks 仅管理消息相关表，用户/频道/成员/权限等由 appks 核心服务管理。

表	对应模型文件	说明
message	models/message.rs	核心消息表（由 appks 创建）
message_attachment	models/message_attachment.rs	文件附件
message_embed	models/message_embed.rs	富媒体嵌入
message_embed_field	models/message_embed.rs	嵌入字段
message_poll	models/message_poll.rs	投票
message_poll_option	models/message_poll.rs	投票选项
message_poll_vote	models/message_poll.rs	投票记录
message_pin	models/message_pin.rs	置顶消息
message_read_state	models/message_read_state.rs	已读状态
message_draft	models/message_draft.rs	草稿
message_edit	models/message_edit.rs	编辑历史

6.3 性能优化 / Performance Optimization

规则	说明
N+1 防护	Use JOIN or batch queries instead of N+1 patterns
游标分页	Use UUID v7 cursor-based pagination（WHERE id < $3 ORDER BY id DESC），不用 OFFSET
索引规范	Add indexes for frequently queried columns; document index rationale
ON CONFLICT	Use INSERT ... ON CONFLICT for upsert patterns（draft、read_state）

---

7. Socket.IO 事件规范 / Socket.IO Event Conventions

7.1 事件命名 / Event Naming

imks 使用 Socket.IO 协议进行实时通信，事件名遵循以下约定：

// 客户端 → 服务端（发送操作）
"message:send"          // 发送消息
"message:edit"          // 编辑消息
"message:delete"        // 删除消息
"typing:start"          // 开始输入
"typing:stop"           // 停止输入
"reaction:add"          // 添加反应
"reaction:remove"       // 移除反应

// 服务端 → 客户端（推送事件）
"message:new"           // 新消息
"message:updated"       // 消息已更新
"message:deleted"       // 消息已删除
"typing"                // 用户输入状态
"reaction:updated"      // 反应已更新
"presence:update"       // 在线状态变更

7.2 事件数据结构 / Event Data Structure

// 客户端发送消息事件
// Client sends: "message:send"
{
  "channel_id": "01909a...",
  "body": "hello world",
  "thread_id": null,
  "reply_to_message_id": null
}

// 服务端广播新消息
// Server broadcasts: "message:new"
{
  "id": "01909b...",
  "channel_id": "01909a...",
  "author": { "id": "...", "username": "alice" },
  "body": "hello world",
  "created_at": "2026-06-11T10:00:00Z",
  "reactions": {},
  "attachment_count": 0
}

7.3 房间（Room）机制 / Room Mechanism

// channel_id 作为房间名，频道内消息只广播给加入该房间的 sockets
// Use channel_id as room name; messages broadcast only to sockets in that room
namespace.emit_to_room(&channel_id, "message:new", message_data).await;

7.4 适配器（Adapter）模式 / Adapter Pattern

imks 通过 Adapter trait 支持水平扩展，将 Socket.IO 事件广播到多节点：

┌─────────┐     ┌─────────┐     ┌─────────┐
│ Node 1  │────→│  NATS / │←────│ Node 2  │
│ (imks)  │     │  Redis  │     │ (imks)  │
└─────────┘     └─────────┘     └─────────┘

Adapter	适用场景
LocalAdapter	单节点开发/测试
RedisAdapter	生产环境 Redis Pub/Sub
NatsAdapter	生产环境 NATS（更低延迟）

---

8. 日志与可观测性 / Logging & Observability

8.1 日志规范 / Logging Standards

// 使用 tracing crate 进行结构化日志
use tracing::{info, warn, error, debug};

info!(
    socket_sid = %socket.sid,
    engine_sid = %socket.engine_sid,
    namespace = %namespace.path,
    "Socket connected"
);

warn!(
    socket_sid = %sid,
    "Adapter register error: {}",
    e
);

error!(
    error = %err,
    engine_sid = %sid,
    "Failed to handle engine message"
);

级别	用途
error	错误需要立即关注（连接失败、数据库错误）
warn	异常但可恢复的情况（adapter 注册失败、socket 发送失败）
info	关键业务操作记录（连接/断开、命名空间创建）
debug	开发调试信息（数据包收发详情）
trace	详细执行路径

8.2 关键指标 / Key Metrics

指标	说明
活跃连接数	Active WebSocket + Polling + WebTransport sessions
消息吞吐量	Messages sent/received per second
广播延迟	P50/P95/P99 broadcast latency across nodes
事件处理延迟	Event handling time (receive → broadcast → deliver)
Adapter 延迟	NATS/Redis broadcast delay between nodes
连接错误率	Connection failure rate
数据库查询延迟	Message insert/select latency

8.3 健康检查 / Health Check

// GET /health
{
    "status": "healthy",
    "version": "0.1.0",
    "uptime": 3600,
    "checks": {
        "postgres": { "status": "up", "latency_ms": 5 },
        "redis": { "status": "up", "latency_ms": 2 },
        "nats": { "status": "up", "latency_ms": 1 },
        "appks_grpc": { "status": "up", "latency_ms": 3 }
    }
}

---

9. 性能规范 / Performance

9.1 实时消息 SLA / Real-time Messaging SLA

指标	目标
消息端到端延迟（P50）	<50ms
消息端到端延迟（P95）	<200ms
消息端到端延迟（P99）	<500ms
连接建立时间	<100ms
消息吞吐量（单节点）	>10,000 msg/s
错误率	<0.1%

9.2 性能原则 / Performance Principles

原则	说明
零拷贝	Minimize data copying; use references where possible
批量操作	Batch adapter broadcasts; use pipelining for Redis
无锁优先	Use DashMap (lock-free) for hot-path data; RwLock for cold-path
背压控制	Use bounded mpsc::channel (256) to prevent memory blowout
连接复用	Reuse gRPC channels to appks

9.3 优化策略 / Optimization Strategies

场景	策略
跨节点广播	NATS（<1ms P50）优于 Redis（~2ms P50）
消息持久化	异步写入 + 批量 COMMIT
会话查找	DashMap 直接查找，无锁竞争
gRPC 调用	连接池 + 本地密钥缓存减少 RPC 往返

---

10. 测试规范 / Testing

10.1 基础要求 / Basic Requirements

规则	说明
新功能	All new features must have unit tests
Bug 修复	Bug fixes must include regression tests
模型测试	All model files must have serialization/conversion tests
测试隔离	Tests must be independent and not depend on execution order

10.2 测试命令 / Test Commands

cargo test                       # 运行所有测试
cargo test --lib                 # 仅运行 lib 测试
cargo test models::              # 运行 models 模块测试
cargo test socket::parser::      # 运行 socket parser 测试
cargo test -- --nocapture        # 显示输出

10.3 测试文件组织 / Test File Organization

tests/
├── engine_io_tests.rs     # Engine.IO 协议测试
├── socket_io_tests.rs     # Socket.IO 协议测试
├── adapter_tests.rs       # Adapter 测试
└── session_tests.rs       # 会话管理测试

# 单元测试 (inline)
models/message.rs          → #[cfg(test)] mod tests { ... }
models/message_poll.rs     → #[cfg(test)] mod tests { ... }
socket/parser.rs           → #[cfg(test)] mod tests { ... }
engine/codec.rs            → #[cfg(test)] mod tests { ... }

---

11. Git 规范 / Git Workflow

11.1 提交信息格式 / Commit Message Format

使用 Angular 风格，全部英文：

<type>(<scope>): <subject>

[optional body]

[optional footer]

Type	说明
feat	新功能
fix	Bug 修复
refactor	重构
docs	文档
test	测试
chore	构建/工具
perf	性能优化
style	代码格式

示例 / Examples:

feat(models): add MessagePin, MessageReadState, MessageDraft, MessageEdit models
fix(socket): handle namespace validation on connect
refactor(engine): extract session store to dedicated module
docs(readme): add architecture overview
test(parser): add edge cases for binary event decoding
chore(deps): update tonic to 0.14

11.2 提交原则 / Commit Principles

原则	说明
原子提交	Each commit should address one concern
完整性	Each commit should leave the codebase in a working state
禁止强制推送	Never force push to main branch
提交前检查	Run cargo check and cargo test before committing

11.3 分支策略 / Branch Strategy

分支	用途
main	生产就绪代码
feat/*	功能开发
fix/*	Bug 修复
release/*	发布准备

---

12. 工作流程 / Workflow

12.1 开发流程 / Development Process

1. 理解先于编写 — Read before write; understand context first
2. 最小变更 — Minimal changes; don't refactor unrelated code
3. 验证变更 — Verify after changes; run tests or check output
4. 文档同步 — Update documentation when changing public APIs

12.2 AI 助手工作规范 / AI Assistant Guidelines

规则	说明
先读后写	Always read existing code before making changes
最小侵入	Make minimal changes; don't refactor unrelated code
验证结果	Run cargo check or cargo test after changes
解释变更	Explain what you changed and why
询问不确定	Ask when unsure about requirements
遵守禁止模式	Never use // ── xxxx ────────── style comments

12.3 常用命令 / Common Commands

cargo build                      # 构建
cargo check                      # 快速检查（推荐开发时使用）
cargo test                       # 运行测试
cargo test --lib                 # 仅运行 lib 测试
cargo clippy                     # Lint 检查
cargo fmt                        # 格式化
cargo doc --no-deps              # 生成文档

---

13. 架构决策记录 / ADR

架构决策记录存放在 docs/adr/ 目录下，使用 Markdown 格式。

当前决策 / Current Decisions

ADR	标题	状态
—	Socket.IO 作为实时通信协议	Accepted
—	UUID v7 作为主键实现游标分页	Accepted
—	双模式 JWT 验证（本地 + RPC）	Accepted
—	Adapter 模式支持多节点水平扩展	Accepted
—	消息表由 appks 管理，imks 仅扩展富内容表	Accepted

ADR 模板 / ADR Template

# ADR-NNN: 标题

## 状态
Accepted | Superseded | Deprecated

## 背景
描述问题背景

## 决策
描述做出的决策

## 后果
描述正面和负面影响

---

14. 审查清单 / Review Checklist

代码审查 / Code Review

• 代码风格符合项目规范（无 // ── 分隔线）
• 没有使用禁止模式（unwrap、panic、todo 等）
• 错误处理完整（?传播、具体类型）
• 安全考虑已处理（JWT 验证模式选择正确）
• 性能影响已评估（无 N+1、无阻塞调用）
• 测试已添加（model 文件必须有测试）
• 文档已更新（新 struct 有 doc comment）

PR 审查 / PR Review

• 提交信息符合 Angular 风格
• 每个提交只关注一个问题
• 变更范围合理
• 没有遗留的 TODO/FIXME
• cargo check 和 cargo test 通过

发布前审查 / Pre-release Review

• 所有测试通过
• 无 clippy warning
• 迁移 SQL 已包含在 migrate/ 中
• 依赖安全审计通过（cargo audit）

---

附录 / Appendix

项目架构速查 / Quick Architecture Reference

imks — IM 实时消息服务 / Real-time Messaging Service

┌──────────────────────────────────────────────┐
│                  imks                         │
│                                               │
│  ┌─────────────┐  ┌─────────────────────────┐ │
│  │   engine/    │  │       socket/           │ │
│  │             │  │                          │ │
│  │ • websocket  │  │  • server (Socket.IO)    │ │
│  │ • webtransport│  │  • namespace (rooms)    │ │
│  │ • polling   │  │  • parser (protocol)     │ │
│  │ • session   │  │  • adapter (scale-out)   │ │
│  │ • packet    │  │    ├─ local              │ │
│  │ • codec     │  │    ├─ redis              │ │
│  │ • heartbeat │  │    └─ nats               │ │
│  │ • server    │  │  • message_bus           │ │
│  └─────────────┘  │  • session_store         │ │
│                    └─────────────────────────┘ │
│  ┌─────────────┐  ┌─────────────────────────┐ │
│  │   models/    │  │       pb/               │ │
│  │             │  │                          │ │
│  │ 12 个消息    │  │  gRPC client stubs      │ │
│  │ 领域模型     │  │  → appks TokenService    │ │
│  │             │  │  → appks ChannelService   │ │
│  │ message     │  │  → appks MemberService    │ │
│  │ attachment  │  │  → appks PermissionService│ │
│  │ embed/poll  │  │                          │ │
│  │ reaction    │  │                          │ │
│  │ thread/pin  │  │                          │ │
│  │ draft/edit  │  │                          │ │
│  │ mention     │  │                          │ │
│  │ bookmark    │  │                          │ │
│  │ read_state  │  │                          │ │
│  └─────────────┘  └─────────────────────────┘ │
│                                               │
│  ┌─────────────┐                              │
│  │  migrate/    │                              │
│  │             │                              │
│  │ SQL 迁移     │                              │
│  └─────────────┘                              │
└─────────────────────┬────────────────────────┘
                      │ gRPC
                      ▼
┌──────────────────────────────────────────────┐
│                  appks (core)                 │
│                                               │
│  TokenService  │ ChannelService │ MemberSvc   │
│  PermissionSvc │ WebhookSvc     │ EmojiSvc    │
│                                               │
│  Postgres (users, channels, members, ...)     │
│  Redis (JWT keys, sessions, rate limiting)    │
└──────────────────────────────────────────────┘

基础设施速查 / Infrastructure Quick Reference

服务	用途	协议/库
Postgres	消息数据持久化	sqlx
Redis	Adapter 广播 / 会话存储	fred
NATS	Adapter 广播（低延迟替代）	async-nats
appks gRPC	JWT 验证 / 频道/成员/权限查询	tonic

传输层对比 / Transport Comparison

传输	适用场景	特点
Polling	浏览器不支持 WS 时的降级	兼容性最好，延迟高
WebSocket	主流浏览器/移动端	全双工，低延迟
WebTransport	现代浏览器（Chrome 97+）	基于 QUIC，多路复用，不队头阻塞

---

This document is maintained by the development team. For questions or suggestions, please open an issue.