dootask/AGENTS.md

# DooTask 项目说明

## 一、项目总览

- **项目定位**：DooTask 是一套开源的任务 / 项目管理系统，支持看板、任务、子任务、评论、对话、文件、报表等协作能力。
- **后端技术栈**
  - 基于 Laravel（运行在 LaravelS / Swoole 常驻进程上），代码集中在 `app/`、`routes/`、`config/` 等目录。
  - 数据库通过 Laravel Eloquent 模型访问，所有表结构变更必须通过 migration 完成，禁止直接手工改库。
- **前端技术栈**
  - 主 Web 前端基于 Vue2 + Vite，代码集中在 `resources/assets/js`。
  - 打包与开发通过根目录的 `./cmd` 脚本间接调用 Vite。
- **桌面端**
  - 使用 Electron 作为桌面壳，核心业务逻辑仍在 Web 前端与 Laravel 后端中。

更多安装、升级、迁移说明见根目录 `README.md`。

## 二、开发与运行（命令约定）

- 开发 / 构建命令统一通过根目录的 `./cmd` 脚本执行，以保证与 Docker / 容器环境一致：
  - 启动服务：`./cmd up`
  - 停止服务：`./cmd down`
  - 重启服务：`./cmd reup` 或 `./cmd restart`
  - Laravel 工具：`./cmd artisan ...`
  - 前端开发：`./cmd dev`
  - 前端构建：`./cmd prod` 或 `./cmd build`
  - 其他工具：`./cmd composer ...`、`./cmd php ...`、`./cmd doc` 等
- 在示例、脚本与回答中，优先使用 `./cmd ...` 形式，而不是直接调用 `php`、`composer`、`npm` 等命令。

## 三、代码结构（后端 + 前端）

- **Controller（`app/Http/Controllers`）**
  - 负责路由入口、参数接收与基础校验，编排调用模型 / 模块，并组装 API 响应。
  - 原则：控制器尽量保持「薄」，复杂业务逻辑不要堆积在控制器中。
  - 业务异常优先使用 `App\Exceptions\ApiException` 抛出，由全局 Handler 统一转换为标准 JSON 响应。

- **Model（`app/Models`）**
  - 负责数据表结构映射、关系（relations）、访问器 / 修改器、自定义查询 Scope 等「数据层」逻辑。
  - 避免在模型方法中塞入大量跨业务的流程控制逻辑，复杂业务应下沉到模块中。

- **Module（`app/Module`）**
  - 承载跨控制器 / 跨模型的业务逻辑与独立功能子域，例如：
    - 外部服务集成：`AgoraIO/*`、`ZincSearch/*` 等；
    - 通用工具：`Lock.php`、`TextExtractor.php`、`Image.php` 等；
    - 项目 / 任务 / 对话等领域里的复杂协作逻辑。
  - 原则：
    - 新增较复杂的业务功能时，优先考虑创建 / 扩展 Module，而不是在 Controller 或 Model 中堆砌流程。
    - Module 尽量保持单一职责与可复用，命名能直接反映其业务或能力作用。

- **运行环境注意事项（LaravelS / Swoole）**
  - 避免在静态属性、单例、全局变量中存储请求级状态或可变数据，防止请求间数据串联和内存泄漏。
  - 不要假设构造函数、服务提供者或 `boot()` 方法会在每个请求重新执行；涉及配置、路由等改动时，通常需要通过 `./cmd php restart` 或容器重启后才能生效。
  - 编写长连接、定时任务、WebSocket 等长生命周期逻辑时，优先复用现有模式，并避免长时间阻塞协程 / 事件循环的操作。

- **前端（`resources/assets/js`，Vue2 + Vite）**
  - 结构大致包括：
    - `app.js`、`App.vue`：应用入口与根组件；
    - `components/`：通用与业务组件（任务看板、文件预览、聊天等）；
    - `pages/`：页面级组件（登录、项目、任务视图、消息、报表等）；
    - `store/`：Vuex 全局状态管理；
    - `routes.js`：前端路由配置。
  - 构建与开发：
    - 开发模式：使用 `./cmd dev` 或类似子命令，内部通过 Vite 启动开发服务器。
    - 生产构建：使用 `./cmd prod` 或 `./cmd build`，内部通过 Vite 产出前端静态资源。
  - 与后端接口协作：
    - 接口调用默认通过已有的 Vuex 封装发起请求，新增接口时优先扩展集中封装，而不是在组件中直接散落 `axios/fetch`。

- **Electron**
  - Electron 主要作为桌面入口壳，核心业务逻辑仍在 Web/Vue2 前端与 PHP/Laravel 后端。
  - 日常开发与调试优先使用 `./cmd electron ...`；需要构建 App 端资源时使用 `./cmd appbuild`。
  - 原则：优先保证 Web 端行为正确，再通过 Electron 壳复用 Web 逻辑；桌面专有能力（本地文件、托盘等）需在代码中明确边界。

## 四、在本项目中使用 Graphiti 作为长期记忆

- **角色与 group_id**
  - Graphiti 作为本项目的「长期记忆层」，用于持久化：
    - 用户偏好（Preferences）、工作流程 / 习惯（Procedures）、重要约束（Requirements）、关键事实 / 关系（Facts）。
  - 目标是：跨对话、跨任务保持一致的行为和决策，而不是简单堆积信息。
  - 本项目统一使用的 `group_id`：`dootask-main`。

- **任务开始前（读）**
  - 在进行实质性工作（写代码、设计方案、做大改动）前，应先通过 Graphiti 查询已有记忆：
    - 使用节点搜索（如 `search_nodes`）在 `group_id = "dootask-main"` 下查找与当前任务相关的 Preference / Procedure / Requirement；
    - 使用事实搜索（如 `search_facts`）查找相关事实与实体关系；
    - 查询语句中可包含：任务类型（Bug 修复 / 重构 / 新功能等）、涉及模块（任务、项目、对话、WebSocket、报表等）以及关键字 `dootask`。
  - 发现与当前任务高度相关的偏好 / 流程 / 约束时，应优先遵守；如存在冲突，应在回答中说明并做合理选择。

- **什么时候写入 Graphiti（写）**
  - **偏好（Preferences）**：用户表达持续性偏好时（语言、输出格式、技术选型等），应尽快写入；
  - **流程 / 习惯（Procedures）**：形成「以后都按这个流程来」的稳定开发 / 发布 / 调试流程时，应记录为可复用步骤；
  - **约束 / 决策（Requirements）**：项目长期有效的决策，如不再支持某版本、某模块的架构约定等；
  - **事实 / 关系（Facts）**：模块边界约定、服务之间的调用关系、与外部系统（如 AgoraIO、ZincSearch）集成方式等。
  - 写入建议：
    - 默认使用 `source: "text"`，在 `episode_body` 中用简洁结构化自然语言描述背景、类型、范围、具体内容；
    - 需要结构化数据时可用 `source: "json"`，保证 `episode_body` 是合法 JSON 字符串；
    - 所有写入默认使用 `group_id: "dootask-main"`。

- **更新与更正**
  - 偏好 / 流程发生变化时，新增一条 episode 说明新约定，并标明这是对旧习惯的更新，后续以最新、最明确的为准；
  - 用户要求「忘记」某些记忆时，可通过删除或更正相关 episode / 关系的方式处理；
  - 尽量通过新增 episode 记录「更正 / 废弃说明」，而不是直接改写历史事实。

- **在工作中的使用方式**
  - 尊重已存偏好：编码风格、回答结构、工具选择等应对齐已知偏好；
  - 遵循已有流程：若图谱中已有与当前任务匹配的 Procedure，应尽量按步骤执行；
  - 利用事实：理解系统行为、模块边界、历史决策时优先查已存 Facts，减少重新摸索；
  - 如 Graphiti 与当前代码实际冲突，应以代码实际为准，并视情况新增 episode 更新事实。

- **不要写入 Graphiti 的内容**
  - 含敏感信息（密钥、密码、隐私数据等）；
  - 只与当前一次任务相关、未来不会复用的临时信息（调试日志、一次性命令输出等）；
  - 体量巨大的原始数据（完整日志、长脚本全文等），应只存摘要和关键结论。

- **最佳实践小结**
  - 先查再做：在提出方案或改动架构前，优先查阅 Graphiti 中已有的设计、偏好和约束；
  - 能复用就沉淀：只要发现某个偏好 / 流程 / 约束未来会反复用到，就尽快写入 Graphiti，而不是只放在当前对话里；
  - 保持项目内外一致：确保 Graphiti 中的记忆与实际代码长期保持一致，避免「记忆漂移」。

## 五、前端弹窗文案

- 在前端 Vue 代码中调用 `$A.modalXXX`、`$A.messageXXX`、`$A.noticeXXX` 时，这些方法内部会统一处理 `$L` 翻译，调用方默认不要再额外包一层 `$L`。
- 仅当 `modalXXX` 特殊场景显式传入 `language: false`（关闭内部自动翻译）时，才由调用方在传入前自行决定是否使用 `$L` 处理文案。

## 六、AI 回复风格与语言偏好

- 总体说明与重要总结（尤其是最终回答的 recap 部分），在不影响技术表达准确性的前提下，应优先使用简体中文进行回复。
- 如用户在对话中明确要求使用其他语言（例如英文），则以用户的显式指令为最高优先级。
- 当本次协作的改动已经较为完整且自然形成一个提交单元时，应在最终回答中附带一条或数条推荐的 Git 提交 message，方便用户直接复制使用。