Version: 0.6.6.dev.260317

✨ feat(task,agent): 新增任务完成接口，并打通聊天全链路 Token 记账

- ✅ 新增“标记任务为完成”接口，并补充幂等保护，避免重复完成导致状态污染
- 📊 为聊天链路补充 Token 统计能力：
  - 流式主对话链路直接读取模型 `usage`
  - Agent 链路通过 `Eino callback + ctx` 聚合 `Generate usage`
  - 在流式场景下补齐缺失的 `usage` 数据
- 🧾 按口径 B 完成 Token 落库：
  - 用户消息 `token` 记为 `0`
  - 助手消息记录本轮总 `token`
  - 持久化时同步更新 `chat_histories.tokens_consumed`、`agent_chats.tokens_total`、`users.token_usage`
- 🔄 异步标题生成产生的 Token 通过 Outbox 事件完成账本增量调整，保证统计口径一致
- 📝 同步更新 `AGENTS.md` 与 `.gitignore`
- 📚 小幅更新 README 说明文档

backend/model/agent.go

@@ -20,6 +20,21 @@ type ChatHistoryPersistPayload struct {
 	ConversationID string `json:"conversation_id"`
 	Role           string `json:"role"`
 	Message        string `json:"message"`
+	TokensConsumed int    `json:"tokens_consumed"`
+}
+
+// ChatTokenUsageAdjustPayload 是“会话 token 账本增量调整”事件载荷。
+//
+// 职责边界：
+// 1. 只表达“对哪个用户/会话增加多少 token”；
+// 2. 不承载 chat_histories 落库语义（消息正文由聊天持久化事件负责）；
+// 3. 不包含 outbox/kafka 协议字段（由基础设施层统一封装）。
+type ChatTokenUsageAdjustPayload struct {
+	UserID         int       `json:"user_id"`
+	ConversationID string    `json:"conversation_id"`
+	TokensDelta    int       `json:"tokens_delta"`
+	Reason         string    `json:"reason"`
+	TriggeredAt    time.Time `json:"triggered_at"`
 }
 
 // GetConversationMetaResponse 是会话元信息查询接口的返回结构。

backend/model/task.go

@@ -56,6 +56,31 @@ type UserAddTaskRequest struct {
 	DeadlineAt    *time.Time `json:"deadline_at"`
 }
 
+// UserCompleteTaskRequest 是“标记任务完成”接口的请求体。
+//
+// 职责边界：
+// 1. 只承载目标任务 ID；
+// 2. 不承载 user_id（user_id 一律由鉴权中间件注入，避免越权）。
+type UserCompleteTaskRequest struct {
+	TaskID int `json:"task_id"`
+}
+
+// UserCompleteTaskResponse 是“标记任务完成”接口的响应体。
+//
+// 字段语义：
+//  1. TaskID：本次操作的目标任务；
+//  2. IsCompleted：操作后的完成状态（成功时恒为 true）；
+//  3. AlreadyCompleted：
+//     3.1 true：任务原本就已完成，本次请求命中幂等语义；
+//     3.2 false：任务由未完成切换为完成；
+//  4. Status：给前端的简短状态文案。
+type UserCompleteTaskResponse struct {
+	TaskID           int    `json:"task_id"`
+	IsCompleted      bool   `json:"is_completed"`
+	AlreadyCompleted bool   `json:"already_completed"`
+	Status           string `json:"status"`
+}
+
 type GetUserTaskResp struct {
 	ID            int    `json:"id"`
 	UserID        int    `json:"user_id"`