mirror of
https://github.com/kuaifan/dootask.git
synced 2026-01-11 16:28:11 +00:00
feat: 添加 Claude Code 配置文件
- 创建 CLAUDE.md 项目指南 - 添加 .claude/rules/graphiti.md Graphiti 长期记忆集成规则
This commit is contained in:
kuaifan
parent
79c2ba140c
commit
67fc0781e5
55
.claude/rules/graphiti.md
Normal file
55
.claude/rules/graphiti.md
Normal file
@ -0,0 +1,55 @@
|
||||
# Graphiti 长期记忆集成
|
||||
|
||||
本项目使用 Graphiti 作为「长期记忆层」，用于持久化用户偏好、工作流程、重要约束和关键事实。
|
||||
|
||||
**统一 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、Manticore Search |
|
||||
|
||||
### 写入建议
|
||||
|
||||
- 默认使用 `source: "text"`，在 `episode_body` 中用简洁结构化自然语言描述背景、类型、范围、具体内容
|
||||
- 需要结构化数据时可用 `source: "json"`，保证 `episode_body` 是合法 JSON 字符串
|
||||
- 所有写入默认使用 `group_id: "dootask-main"`
|
||||
|
||||
## 更新与更正
|
||||
|
||||
- 偏好 / 流程发生变化时，新增一条 episode 说明新约定，并标明这是对旧习惯的更新
|
||||
- 用户要求「忘记」某些记忆时，可通过删除或更正相关 episode / 关系的方式处理
|
||||
- 尽量通过新增 episode 记录「更正 / 废弃说明」，而不是直接改写历史事实
|
||||
|
||||
## 使用原则
|
||||
|
||||
- **尊重已存偏好**：编码风格、回答结构、工具选择等应对齐已知偏好
|
||||
- **遵循已有流程**：若图谱中已有与当前任务匹配的 Procedure，应尽量按步骤执行
|
||||
- **利用事实**：理解系统行为、模块边界、历史决策时优先查已存 Facts
|
||||
- **代码优先**：如 Graphiti 与当前代码实际冲突，应以代码实际为准，并视情况新增 episode 更新事实
|
||||
|
||||
## 不要写入的内容
|
||||
|
||||
- 敏感信息（密钥、密码、隐私数据）
|
||||
- 只与当前一次任务相关、未来不会复用的临时信息
|
||||
- 体量巨大的原始数据（完整日志、长脚本全文），应只存摘要和关键结论
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **先查再做**：在提出方案或改动架构前，优先查阅 Graphiti 中已有的设计、偏好和约束
|
||||
2. **能复用就沉淀**：只要发现某个偏好 / 流程 / 约束未来会反复用到，就尽快写入 Graphiti
|
||||
3. **保持一致**：确保 Graphiti 中的记忆与实际代码长期保持一致，避免「记忆漂移」
|
||||
127
AGENTS.md
127
AGENTS.md
@ -1,127 +0,0 @@
|
||||
# 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/*`、`Manticore/*` 等；
|
||||
- 通用工具：`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、Manticore Search）集成方式等。
|
||||
- 写入建议：
|
||||
- 默认使用 `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，方便用户直接复制使用。
|
||||
123
CLAUDE.md
Normal file
123
CLAUDE.md
Normal file
@ -0,0 +1,123 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## 项目概述
|
||||
|
||||
DooTask 是一套开源的任务/项目管理系统，支持看板、任务、子任务、评论、对话、文件、报表等协作能力。
|
||||
|
||||
- **后端**：Laravel 8，运行在 LaravelS/Swoole 常驻进程上
|
||||
- **前端**：Vue 2 + Vite
|
||||
- **桌面端**：Electron 壳，核心逻辑复用 Web 前端
|
||||
|
||||
## 开发命令
|
||||
|
||||
所有命令通过 `./cmd` 脚本执行，确保与 Docker/容器环境一致：
|
||||
|
||||
```bash
|
||||
# 服务管理
|
||||
./cmd up # 启动容器
|
||||
./cmd down # 停止容器
|
||||
./cmd restart # 重启容器
|
||||
./cmd reup # 重新构建并启动
|
||||
|
||||
# 开发构建
|
||||
./cmd dev # 启动前端开发服务器（需要 Node.js 20+）
|
||||
./cmd serve # dev 别名
|
||||
./cmd prod # 构建前端生产版本
|
||||
./cmd build # prod 别名
|
||||
|
||||
# Laravel/PHP
|
||||
./cmd artisan ... # 运行 Laravel Artisan 命令
|
||||
./cmd composer ... # 运行 Composer 命令
|
||||
./cmd php ... # 运行 PHP 命令
|
||||
|
||||
# Electron
|
||||
./cmd electron # 构建桌面应用
|
||||
|
||||
# 配置管理
|
||||
./cmd port <端口> # 修改服务端口
|
||||
./cmd url <地址> # 修改访问地址
|
||||
./cmd env <键> <值> # 设置环境变量
|
||||
./cmd debug [true|false] # 切换调试模式
|
||||
|
||||
# 数据库
|
||||
./cmd mysql backup # 备份数据库
|
||||
./cmd mysql recovery # 恢复数据库
|
||||
|
||||
# 其他
|
||||
./cmd install # 一键安装
|
||||
./cmd update # 升级项目
|
||||
./cmd repassword # 重置管理员密码
|
||||
./cmd doc # 生成 API 文档
|
||||
./cmd https # 配置 HTTPS
|
||||
```
|
||||
|
||||
## 代码架构
|
||||
|
||||
### 后端 (`app/`)
|
||||
|
||||
**Controller (`app/Http/Controllers/Api/`)**：API 控制器，负责路由入口、参数校验、编排调用模型/模块、组装响应。保持控制器「薄」，业务异常通过 `App\Exceptions\ApiException` 抛出。
|
||||
|
||||
**Model (`app/Models/`)**：Eloquent 模型，负责表结构映射、关系、访问器/修改器、查询 Scope。避免在模型中堆积复杂业务逻辑。
|
||||
|
||||
**Module (`app/Module/`)**：跨控制器/跨模型的业务逻辑与独立功能子域：
|
||||
- 外部集成：`AgoraIO/`、`Manticore/`
|
||||
- 通用工具：`Lock.php`、`TextExtractor.php`、`Image.php`、`AI.php`
|
||||
- 复杂业务逻辑：`Base.php`（核心业务）、`Doo.php`、`Timer.php`
|
||||
|
||||
**Tasks (`app/Tasks/`)**：Swoole 异步任务，用于后台处理：
|
||||
- WebSocket 消息推送：`WebSocketDialogMsgTask.php`、`PushTask.php`
|
||||
- 定时任务：`LoopTask.php`、`AutoArchivedTask.php`
|
||||
- 搜索同步：`ManticoreSyncTask.php`
|
||||
|
||||
**Observers (`app/Observers/`)**：Eloquent 观察者，监听模型事件（created/updated/deleted）自动触发相关逻辑。
|
||||
|
||||
**Services (`app/Services/`)**：服务类，如 `WebSocketService.php`、`RequestContext.php`。
|
||||
|
||||
### 前端 (`resources/assets/js/`)
|
||||
|
||||
```
|
||||
├── app.js, App.vue # 应用入口与根组件
|
||||
├── components/ # 通用与业务组件（看板、文件预览、聊天）
|
||||
├── pages/ # 页面级组件（登录、项目、任务、消息、报表）
|
||||
├── store/ # Vuex 状态管理
|
||||
│ ├── state.js # 状态定义
|
||||
│ ├── mutations.js # 同步修改
|
||||
│ ├── actions.js # 异步操作（含 API 调用封装）
|
||||
│ └── getters.js # 计算属性
|
||||
├── routes.js # 前端路由
|
||||
├── functions/ # 业务函数
|
||||
├── utils/ # 工具函数
|
||||
├── directives/ # Vue 自定义指令
|
||||
├── mixins/ # Vue 混入
|
||||
└── language/ # 国际化翻译
|
||||
```
|
||||
|
||||
API 调用应使用 `store/actions.js` 中已有的封装，避免在组件中散落 axios/fetch。
|
||||
|
||||
### LaravelS/Swoole 注意事项
|
||||
|
||||
- **避免在静态属性、单例、全局变量中存储请求级状态**——防止请求间数据串联和内存泄漏
|
||||
- 构造函数、服务提供者、`boot()` 方法不会在每个请求重新执行
|
||||
- 配置/路由变更需要 `./cmd php restart` 或容器重启才能生效
|
||||
- 长生命周期逻辑（WebSocket、定时器）应复用现有模式，避免阻塞协程/事件循环
|
||||
|
||||
## 数据库
|
||||
|
||||
- 所有表结构变更必须通过 Laravel migration，禁止直接改库
|
||||
- 使用 Eloquent 模型访问数据库
|
||||
|
||||
## 前端弹窗文案
|
||||
|
||||
调用 `$A.modalXXX`、`$A.messageXXX`、`$A.noticeXXX` 时，内部会自动处理 `$L` 翻译，调用方不要额外包 `$L`。仅当显式传入 `language: false` 时，才由调用方自行处理翻译。
|
||||
|
||||
## 语言偏好
|
||||
|
||||
- 技术总结和关键结论优先使用简体中文
|
||||
- 遵循用户明确指定的语言偏好
|
||||
- 当改动形成自然的提交单元时，附带推荐的 Git commit message
|
||||
|
||||
## 扩展规则
|
||||
|
||||
详见 @.claude/rules/graphiti.md 了解 Graphiti 长期记忆集成。
|
||||
Loading…
x
Reference in New Issue
Block a user