agent/AGENTS.md

AGENTS.md

项目

本仓库包含森林AI项目工作台 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 验证命令。
• 每个实施任务结束时都应创建一个聚焦的提交。