# 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:` 字符串。 - 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 验证命令。 - 每个实施任务结束时都应创建一个聚焦的提交。