agent/AGENTS.md

# AGENTS.md

## 项目

本仓库包含 SenlinAI 项目工作台 MVP。

该产品是一个以项目为中心、面向私有化部署的工作台，服务于个人知识工作者、团队负责人和可信的内部用户。它用于组织项目任务、inbox 条目、Markdown 笔记、文件、AI 会话、项目内标签，以及轻量级任务分发。

## 仓库结构

- `backend`: Go Gin + Gorm + PostgreSQL API。
- `apps/web_v1`: 当前主 Web 客户端，使用 React + TypeScript + Arco Design。
- `apps/desktop`: Web 客户端的 Tauri 桌面壳。
- `infra`: 本地开发基础设施，例如 Docker Compose。
- `docs/superpowers/specs`: 产品和技术规格文档。
- `docs/superpowers/plans`: 实施计划。

## 后端规则

- 使用 Go、Gin、Gorm 和 PostgreSQL。
- 后端模块集中放在 `backend/internal` 下，并保持职责聚焦。
- 使用模块路径 `senlinai-agent/backend`。
- 业务逻辑包统一放在 `backend/internal/logic` 下，例如 `ai`、`auth`、`files`、`inbox`、`notes`、`projects`、`search`、`tasks`。
- Gorm 模型和数据库连接入口统一放在 `backend/internal/models`，不要恢复独立的 `domain` 或 `db` 包。
- 模型结构体使用 `SenlinAgent` 前缀，数据库表名使用 `senlin_agent_` 前缀。
- 所有服务端本地文件路径构造必须集中在文件服务中。
- 不允许 HTTP handler 直接构造存储路径。
- 项目标签必须限定在项目内；MVP 阶段不要引入全局标签体系。
- 任务分享保持保守：被指派人只能看到任务，以及被显式分享的关联对象。
- AI 未经用户确认，不得创建正式对象。
- AI 调用必须记录 provider、key 类型、action、status 和 error。
- 认证 session token 必须是已签名、会过期的 bearer token；不要接受可伪造的 `user:<id>` 字符串。
- HTTP handler 必须从认证 middleware 读取当前用户，不得硬编码用户 ID。
- 从 inbox 确认生成的任务、笔记和资料，应保留来源 inbox item ID。
- 任务分享必须校验被分享的 note/source 与任务属于同一个项目。
- 用户 AI key 必须加密存储；AI 调用在执行 provider 请求前应经过限流检查。

## 前端规则

- 当前主前端使用 React、TypeScript、Vite 和 Arco Design，位于 `apps/web_v1`。
- Web 应用优先面向桌面端构建，同时保持移动浏览器可用。
- 登录界面必须允许用户输入服务器 IP 地址或域名。
- 页面级工作台状态使用浏览器式标签页。
- 编辑器草稿和 AI 输入草稿要与标签页状态分开保存。
- MVP 阶段使用 Markdown 进行笔记编辑。

## Tauri 规则

- Tauri 用于包装当前主 Web 客户端。
- MVP 桌面端功能包括登录持久化、文件拖拽上传、通知，以及全局快捷键快速收集。
- MVP 阶段不要添加离线编辑、本地优先同步、后台剪贴板监控或文件系统索引。

## MVP 范围边界

除非后续批准的规格文档明确要求，否则不要添加以下功能：

- 真正的实时即时通讯。
- 项目级成员角色体系。
- 匿名公开任务分享。
- 自主 Agent 执行。
- 语义搜索或向量搜索。
- 原生移动 App。
- 浏览器扩展、邮件、IM 或第三方收集集成。

## 验证

- 后端变更应在 `backend` 目录运行 `go test ./...`。
- PostgreSQL 集成检查应从 `DATABASE_URL` 读取实时测试数据库 URL；不要提交真实凭据。
- Web 变更应在 `apps/web_v1` 目录运行 `node scripts/visual-check.mjs`、`npm run build` 和 `npm run lint`。
- Tauri 变更应先构建 Web 应用，然后在 `apps/desktop` 目录运行 Tauri 验证命令。
- 每个实施任务结束时都应创建一个聚焦的提交。