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，方便用户直接复制使用。