1. 项目概述：为AI开发伙伴装上“鼠标”

如果你和我一样，深度使用Cursor IDE进行开发，那你一定体验过那种“一半是惊喜，一半是迷茫”的感觉。惊喜在于，AI助手能帮你生成代码、重构函数、甚至写文档，效率惊人；迷茫则在于，当任务稍微复杂一点，比如“给这个项目加个用户认证模块”，你和AI之间的协作就容易陷入混乱。它可能改了几个文件后，你突然忘了它具体做了什么、为什么这么做、下一步又该做什么。整个协作过程像是一场没有记分牌的球赛，你只知道球在动，但看不清比分和战术。

这就是我开发 Mouse 的初衷。你可以把它理解为一个专为 Cursor AI 设计的“任务管理鼠标”。Cursor本身是个强大的“光标”，能快速移动和执行，但它需要一个精准的“鼠标”来提供结构化的指令、清晰的路径和可视化的反馈。Mouse就是这套本地化、可视化、结构化的任务管理协议和工具集。它不依赖任何云端服务，核心就是一个简单的HTML可视化看板，以及一套让AI严格遵循的规则文件。其核心价值在于，它将一次性的、模糊的AI指令，转化为一个可追溯、可管理、可复现的工程项目流程。

简单来说，Mouse解决了几个关键痛点：

  1. 任务失忆症 ：AI没有长期记忆，复杂的多步骤任务容易“断片”。Mouse通过本地文件记录一切，让每次会话都能无缝接续。
  2. 过程黑盒 ：AI做了什么、改了哪些文件、为什么这么改？没有记录就只能靠猜。Mouse强制记录每一步操作和决策，形成完整的审计日志。
  3. 协作混乱 ：当任务需要分解时，缺乏统一的结构。Mouse定义了标准的任务与子任务格式，让复杂任务的拆解和执行井然有序。
  4. 进度盲区 ：你无法一眼看清所有任务的进行状态。Mouse的HTML看板提供了直观的可视化，让你对项目全局一目了然。

它特别适合那些正在使用Cursor进行中小型项目开发、需要AI深度参与复杂任务（如功能开发、代码重构、文档撰写）的开发者。无论你是独立开发者，还是小团队的核心成员，Mouse都能让你和AI的协作从“即兴发挥”升级为“工程化管理”。

2. 核心设计哲学与协议架构解析

Mouse的设计并非凭空而来，它融合了我过去在AI辅助开发领域的实践心得，特别是之前为Roo Code设计高效模式集（Rooroo）的经验。但针对Cursor，我的设计哲学发生了根本性的转变。

2.1 从“极致节俭”到“充分表达”的范式迁移

在Roo Code的生态里，由于计费模式与上下文长度强相关，我的核心目标是 “极致节俭” 。每一个token都要精打细算，规则必须高度简洁、无歧义，以确保即使是能力稍弱的模型也能在有限的上下文内理解并执行。这催生了像Rooroo那样高度压缩、符号化的指令集。

然而，Cursor的定价模型解放了上下文长度的束缚。更重要的是，通过慢速池可以使用Gemini 2.5 Pro这类顶级模型。这意味着我不再需要为token而焦虑，设计重心可以从“如何说得更少”转向 “如何说得更清楚” 。我可以设计更详尽、更具描述性的协议，充分利用大模型的强大理解能力。同时，Cursor内置的“应用差异模型”在编辑大文件时效率极高，这允许我在协议中设计更复杂的文件操作流程，而不用担心性能瓶颈。

因此，Mouse的协议是 “为强大模型和宽松上下文而生的充分表达型协议” 。它不吝啬于使用清晰的描述、结构化的字段和明确的枚举值，其首要目标是消除AI执行过程中的任何模糊地带。

2.2 协议的核心支柱：四大指导原则

整个Mouse协议建立在四个核心指令之上，它们贯穿于每一个任务的生命周期：

  1. 清晰第一，存疑必问 ：这是最高原则。协议要求AI在任何时候对用户指令、文件路径、代码标准或自身下一步行动存在哪怕一丝不确定时，都必须主动向用户提问澄清。它禁止AI进行“可能正确”的猜测。例如，如果用户说“优化 utils.js ”，AI必须确认具体是哪个 utils.js （项目里可能有多个），以及“优化”的具体标准是什么（是性能、可读性还是模块化？）。这从根本上避免了因误解而产生的错误修改。
  2. 记录一切可执行操作 ：所有对项目状态产生影响的行动都必须被记录。这不仅仅是“我创建了文件A”，而是包括“我为什么创建文件A（依据任务X的子任务Y）”、“创建时考虑了哪些备选方案”、“文件A的内容结构是基于什么标准”。日志是结构化的，包含时间戳（逻辑上的）、操作类型、目标对象和详细描述。
  3. 保护用户数据与项目完整性 ：在执行任何破坏性操作（如删除文件、覆盖重要代码）前，协议要求AI必须进行风险提示，并在可能的情况下建议备份或提供回滚方案。对于关键的用户数据文件（如 .env ， 数据库文件），协议内置了保护性规则，禁止AI直接修改其内容，除非得到用户的明确授权和具体指令。
  4. 遵循标准的任务生命周期 ：任务不是简单的“开始”和“结束”。Mouse定义了一个明确的状态流转模型： Pending （已创建待确认） -> Ready （已确认可执行） -> InProgress （执行中） -> Blocked （受阻，等待外部输入） -> Done （完成）/ Cancelled （取消）。这个生命周期被编码在任务文件的YAML头信息里，AI和看板都依据此状态来驱动流程。

2.3 文件系统即唯一信源： .mouse 目录的奥秘

Mouse坚决摒弃了依赖内存或临时存储的思路，它将项目的 本地文件系统 作为所有任务数据的唯一真实来源。所有状态都持久化在项目根目录下的 .mouse/ 文件夹中。这种设计带来了几个关键优势：

  • 持久化与可恢复性 ：关闭Cursor、重启电脑、甚至换一台机器，只要项目目录在，所有任务历史和上下文都在。AI在下一次会话中，可以通过读取 .mouse/ 目录立刻“恢复记忆”。
  • 版本控制友好 ： .mouse/ 目录下的所有Markdown文件都可以且应该被纳入Git版本控制。这意味着你的任务管理流程本身也具备了版本历史，你可以回溯到任何一个任务节点的状态。
  • 透明与可审计 ：任何开发者（或未来的你）都可以直接翻阅这些Markdown文件，了解项目的完整决策和执行历程，无需依赖任何专有工具或数据库。
  • 工具无关性 ：可视化看板（ mouse_dashboard.html ）只是一个简单的HTML文件，它通过读取 .mouse/ 目录来渲染视图。你可以用任何文本编辑器查看原始数据，也可以用任何能解析Markdown和YAML的工具来自行处理这些数据。

.mouse 目录的标准结构如下：

.your-project-root/
├── .mouse/
│   ├── tasks/          # 存放所有独立任务文件
│   │   └── MOUSE#TASK_0001.md
│   └── plans/          # 存放复杂任务的计划文件
│       └── MOUSE#TASK_0001_plan.md
├── .cursor/rules/      # Mouse协议规则文件
├── mouse_dashboard.html # 可视化看板
└── (你的项目源代码文件...)

3. 任务协议深度解析：从创建到归档

Mouse协议将任务管理分解为两个核心层级： 独立任务 和 计划任务 。理解它们的区别和协作方式是高效使用Mouse的关键。

3.1 独立任务：轻量级操作的标准化容器

独立任务适用于那些目标明确、步骤相对简单、可以在单次AI交互中完成的“S”（小）或“M”（中）型工作。例如：“在 src/utils/ 下创建一个名为 formatDate.js 的函数文件”、“修复 Login.vue 组件中的按钮点击事件绑定错误”。

当一个独立任务被创建时，AI会在 .mouse/tasks/ 目录下生成一个Markdown文件，例如 MOUSE#TASK_0001.md 。这个文件的结构是严格定义的：

---
TaskID: MOUSE#TASK_0001
Title: 创建日期格式化工具函数
Description: 项目需要统一的日期显示格式（YYYY-MM-DD HH:mm:ss）。创建一个可复用的工具函数，并确保处理了时区转换（默认转换为本地时间）。
Status: InProgress
Effort: S
Deliverables:
  - 文件：`src/utils/formatDate.js`
  - 导出：一个名为 `formatDate` 的函数
  - 文档：函数顶部的JSDoc注释
CreatedAt: 2023-10-27T10:00:00Z
UpdatedAt: 2023-10-27T10:05:00Z
Assignee: Cursor-AI
Tags: [utility, i18n]
---

## 历史日志

### 2023-10-27 10:00:00 | 任务创建
用户指令：“请创建一个用于格式化日期为‘YYYY-MM-DD HH:mm:ss’的工具函数。”
*   解析：需求明确，属于工具函数创建，评估为S级工作量。
*   行动：创建本任务文件，状态设为`Pending`。

### 2023-10-27 10:01:00 | 状态变更 -> Ready
*   确认：已向用户确认函数名称为`formatDate`，存放路径为`src/utils/`。用户无额外要求。
*   行动：将任务状态更新为`Ready`。

### 2023-10-27 10:02:00 | 状态变更 -> InProgress | 开始执行
*   行动：开始编写`src/utils/formatDate.js`文件。
*   依据：遵循项目编码标准（`@coding_standards.mouse.mdc`），使用ES模块导出，添加详细的JSDoc。

### 2023-10-27 10:04:00 | 文件创建与编写
*   行动：创建文件 `src/utils/formatDate.js`。
*   内容概要：
    ```javascript
    /**
     * 将Date对象或时间戳格式化为指定的字符串。
     * @param {Date|number} date - 要格式化的日期对象或时间戳（毫秒）。
     * @param {string} [format='YYYY-MM-DD HH:mm:ss'] - 输出格式。
     * @returns {string} 格式化后的日期字符串。
     */
    export function formatDate(date, format = 'YYYY-MM-DD HH:mm:ss') {
      // ... 实现逻辑
    }
    ```
*   日志：实现逻辑包含对输入类型的校验，以及使用`toLocaleString`进行本地化时间转换。

### 2023-10-27 10:05:00 | 状态变更 -> Done | 任务完成
*   验证：在浏览器控制台快速测试了函数，输出符合预期。
*   交付物确认：
    1.  文件 `src/utils/formatDate.js` 已创建。
    2.  函数 `formatDate` 已导出。
    3.  JSDoc注释已添加。
*   行动：将任务状态更新为`Done`。本次任务结束。

注意 ： HistoryLog 是独立任务的“执行流水账”。对于S/M级任务，AI的每一个实际操作步骤（思考、确认、创建文件、编写代码、测试）都按时间顺序记录在此。这提供了无与伦比的透明度和可追溯性。

3.2 计划任务：复杂工程的蓝图与导航图

当面对“重构用户认证模块”、“实现购物车完整流程”这类“L”（大）或“X”（特大）型任务时，直接开始编码是灾难性的。Mouse协议要求AI必须先制定 计划 。

计划文件存放在 .mouse/plans/ 目录下，例如 MOUSE#TASK_0002_plan.md 。它的核心是 工作分解结构 。AI需要将宏大的目标拆解成一系列顺序或并行的、原子性的子任务。

---
PlanID: MOUSE#TASK_0002_plan
ForTask: MOUSE#TASK_0002
Title: 用户认证模块重构计划
Status: InProgress
CreatedAt: 2023-10-27T11:00:00Z
---

## 总览
目标：将当前散落在多个文件中的认证逻辑（登录、注册、Token管理）重构为一个独立的、可维护的`auth`模块。

## 子任务分解

### 子任务 1: 分析现状与定义接口
*   **目标**：梳理现有认证相关代码，定义新`auth`模块的公共API接口。
*   **状态**: `Ready`
*   **执行日志**:
    *   `2023-10-27 11:05:00 | 开始`：正在分析`src/login.js`, `src/api.js`, `src/storage.js`中与认证相关的代码。
    *   `2023-10-27 11:10:00 | 进行中`：已识别出三个核心功能：`login(username, password)`, `register(userInfo)`, `validateToken(token)`。
*   **最终输出摘要**: *(待子任务完成后填写)*
*   **交付物**:
    *   文档：`docs/auth-module-api.md` (接口定义)
    *   图表：(可选) 当前架构与新架构对比图。

### 子任务 2: 实现核心认证服务层
*   **目标**：创建`src/services/auth.service.js`，实现登录、注册、Token验证等核心业务逻辑。
*   **状态**: `Pending`
*   **执行日志**: *(尚未开始)*
*   **最终输出摘要**: *(待子任务完成后填写)*
*   **交付物**:
    *   文件：`src/services/auth.service.js`
    *   测试：`__tests__/services/auth.service.test.js` (骨架)

### 子任务 3: 创建Token管理工具
*   **目标**：将Token的生成、存储、刷新、验证逻辑抽象为独立工具。
*   **状态**: `Pending`
*   **执行日志**: *(尚未开始)*
*   **最终输出摘要**: *(待子任务完成后填写)*
*   **交付物**:
    *   文件：`src/utils/tokenManager.js`
    *   集成：更新`auth.service.js`以使用此工具。

### 子任务 4: 重构UI组件以使用新模块
*   **目标**：修改现有的登录页、注册页组件，调用新的`auth`模块接口。
*   **状态**: `Pending`
*   **执行日志**: *(尚未开始)*
*   **最终输出摘要**: *(待子任务完成后填写)*
*   **交付物**:
    *   修改文件：`src/components/LoginForm.vue`, `src/components/RegisterForm.vue`
    *   验证：确保功能与重构前一致。

计划文件的美妙之处在于，它本身就是一个动态的 项目管理看板 。AI（或你）可以逐个攻克子任务。每完成一个子任务，AI会更新其 状态 ，并在 最终输出摘要 中详细记录结果、遇到的问题和解决方案。这个摘要反过来会驱动主任务文件（ .mouse/tasks/MOUSE#TASK_0002.md ）中 HistoryLog 的更新。

3.3 任务状态机的驱动逻辑

状态不是随意改变的，它遵循一个严格的驱动逻辑：

  • Pending -> Ready ：需要用户或AI确认任务描述清晰、资源就绪。
  • Ready -> InProgress ：AI开始执行任务或子任务。
  • InProgress -> Blocked ：遇到无法自行解决的问题（如依赖缺失、需求模糊），必须等待用户输入。
  • InProgress -> Done ：所有交付物已验证完成，日志齐全。
  • 任何状态 -> Cancelled ：用户明确取消任务。

这个状态机确保了任务流程的严谨性，避免了任务在“半完成”的模糊地带徘徊。

4. 实操部署与深度集成指南

理解了协议，下一步就是让它在你自己的项目中运转起来。以下是从零开始，将Mouse深度集成到你的Cursor工作流中的详细步骤。

4.1 环境准备与规则安装

首先，你需要获取Mouse的规则文件。最推荐的方式是克隆仓库，这样便于后续更新。

# 在你的工作区目录（例如 ~/Projects）下执行
git clone https://github.com/marv1nnnnn/mouse.git

克隆后，你会得到完整的Mouse项目。但请注意， 你不需要在这个克隆的目录里工作 。关键是要将其中的规则文件复制到你自己的项目中去。

假设你的个人项目路径是 ~/Projects/my-awesome-app ，操作如下：

# 进入你的项目目录
cd ~/Projects/my-awesome-app

# 将Mouse的核心规则文件夹复制到你的项目根目录
# 这行命令假设你把mouse克隆到了上级目录。请根据你的实际情况调整路径。
cp -r ../mouse/.cursor/rules ./

# （可选但强烈推荐）复制可视化看板到项目根目录，方便随时查看
cp ../mouse/mouse_dashboard.html ./

现在，你的项目结构应该变成了：

my-awesome-app/
├── .cursor/
│   └── rules/          # 刚刚复制过来的Mouse协议规则
│       ├── core_protocol.mouse.mdc
│       ├── coding_standards.mouse.mdc
│       └── ... (其他标准文件)
├── mouse_dashboard.html # 可视化看板
├── package.json
├── src/
└── ... (你的其他项目文件)

关键点 ： .cursor/rules/ 目录是Cursor IDE读取并应用规则的固定位置。只要规则文件放在这里，Cursor AI（在聊天或编辑模式中）就会尝试遵循这些规则。你不需要进行任何额外的IDE配置或插件安装。

4.2 首次使用：启动任务与协议引导

规则安装好后，如何开始第一个任务？关键在于 如何与AI对话 。

  1. 打开你的项目 ：在Cursor中打开 my-awesome-app 项目。

  2. 发起一个明确的任务指令 ：不要只说“帮我写个函数”。使用更结构化的描述。例如：

    “@core_protocol.mouse.mdc 请遵循Mouse协议。我需要创建一个用户个人资料页面，包含头像上传、基本信息编辑和密码修改功能。请将此作为一个任务进行规划。”

    这里的 @core_protocol.mouse.mdc 是魔法咒语 。它直接引用了规则文件，强烈提示AI激活并遵循Mouse协议。在任务初期或你感觉AI没有按协议行事时，使用它效果显著。

  3. 观察AI的响应 ：一个正确遵循协议的AI会这样回应：

    • “我将遵循Mouse协议处理此任务。首先，我将创建一个任务文件来正式记录它...”
    • 随后，你会在项目资源管理器中看到新增的 .mouse/tasks/ 目录和里面的 MOUSE#TASK_0001.md 文件。
    • 对于这个复杂任务，AI很可能判断其为L级，并会告诉你：“这是一个大型任务，我将先创建一个计划文件来分解它。” 接着创建 .mouse/plans/MOUSE#TASK_0001_plan.md 。

  4. 介入与引导 ：此时，你可以打开AI创建的任务或计划文件进行审阅。如果觉得拆解不合理，可以直接在Chat中提出：“我认为子任务2和3可以合并，因为它们都涉及API调用层。” AI会根据你的反馈更新计划文件。 这就是人与AI协同规划的过程 。

4.3 可视化看板的配置与使用

mouse_dashboard.html 是一个静态HTML文件，它通过JavaScript读取你项目中的 .mouse/ 目录来动态生成视图。使用它有两种主流方式：

方式一：直接文件协议打开（最简单）

  1. 在你的文件管理器中，找到项目根目录下的 mouse_dashboard.html 。
  2. 双击它，它会在你的默认浏览器中打开，地址栏类似 file:///Users/yourname/Projects/my-awesome-app/mouse_dashboard.html 。
  3. 页面加载后，通常会有一个“选择文件夹”或“上传.mouse目录”的按钮。点击并选择你项目中的 .mouse 文件夹。
  4. 看板就会加载并显示所有任务和计划的状态。

方式二：使用本地HTTP服务器（更稳定，功能更全） 某些浏览器由于安全限制，直接通过 file:// 协议访问本地文件时，读取其他目录可能会受限。使用一个简单的HTTP服务器可以绕过此限制，也更接近真实Web环境。

# 在项目根目录下打开终端
cd ~/Projects/my-awesome-app

# 方法A: 使用Python（最常见）
python3 -m http.server 8080
# 访问 http://localhost:8080/mouse_dashboard.html

# 方法B: 使用Node.js的http-server（需提前安装: npm install -g http-server）
http-server -p 8080
# 访问 http://localhost:8080/mouse_dashboard.html

# 方法C: 使用PHP
php -S localhost:8080
# 访问 http://localhost:8080/mouse_dashboard.html

启动服务器后，用浏览器访问 http://localhost:8080/mouse_dashboard.html 。此时页面通常能自动检测到同域名下的 .mouse 目录并加载，无需手动选择。

看板界面通常会以卡片或列表形式展示所有任务，用颜色区分状态（如绿色进行中、蓝色已完成、灰色待处理），并展示任务间的依赖关系。你可以一目了然地掌握项目整体进度，并点击任何任务卡查看其详细日志和子任务。

4.4 与项目现有标准的融合

Mouse协议是通用的任务管理框架，而具体的编码、文档、提交规范因项目而异。这就是 coding_standards.mouse.mdc 、 documentation_standards.mouse.mdc 等文件的作用。

你 必须 根据自己项目的技术栈和团队规范，定制这些文件。例如，你的 coding_standards.mouse.mdc 可能包含：

# 项目 XYZ 编码标准

## 通用规则
- 使用 ESLint + Prettier 配置，规则文件为 `.eslintrc.js` 和 `.prettierrc`。
- 所有函数、类、组件必须包含JSDoc/TSDoc注释。
- 使用 `const` 和 `let`，避免 `var`。

## React 特定规则
- 组件使用函数式组件和React Hooks。
- 状态管理使用Zustand，store文件放在 `src/stores/`。
- PropTypes 或 TypeScript 接口定义是必须的。

## Vue 特定规则
- 使用 Composition API 和 `<script setup>` 语法。
- 组件文件命名使用 PascalCase，如 `UserProfile.vue`。
- Pinia 作为状态管理库。

## 提交消息
- 遵循 Conventional Commits 规范。
- 关联任务ID，例如：`feat(auth): implement login API [MOUSE#TASK_0001]`。

当AI执行任务时，它会同时参考 core_protocol.mouse.mdc （告诉它“怎么做”任务管理）和你自定义的标准文件（告诉它“做成什么样”）。你可以在聊天中通过 @coding_standards.mouse.mdc 来提醒AI关注代码规范。

5. 高级技巧与实战心得

经过大量项目的实践，我总结出一些能让Mouse发挥最大效能的技巧和心得，这些在官方文档里可找不到。

5.1 任务拆分的艺术：如何定义“好的”子任务

让AI拆解任务，结果可能过于琐碎或依然笼统。你需要引导它。一个 “好的”子任务 应符合 “SMART”原则 的变体：

  • Specific（具体） ：目标明确单一。❌“优化前端性能”。✅“使用React.memo包装 ProductList 组件以减少不必要的重渲染”。
  • Measurable（可衡量） ：有明确的完成标准。❌“让页面加载更快”。✅“通过代码分割和懒加载，将首屏JavaScript包体积减少30%”。
  • Actionable（可执行） ：AI能独立操作，无需频繁中断问你。❌“设计数据库 schema”。✅“基于已确认的ER图，在 prisma/schema.prisma 中创建User, Post, Comment模型及其关系”。
  • Relevant（相关） ：直接贡献于主任务目标。
  • Time-bound（有时限） ：在Mouse的语境下，这更多意味着“能在一次连续的AI交互中完成”，避免子任务本身又需要多轮复杂对话。

实操技巧 ：当你给AI一个大型任务时，可以先自己做一个高阶拆分，然后在指令中给出提示：“请将此任务拆分为子任务。我建议从以下方面考虑：1. 数据库模型设计，2. 后端API接口，3. 前端页面组件，4. 集成测试。请基于此创建详细计划。”

5.2 利用日志进行高效上下文切换与问题排查

Mouse最强大的功能之一就是详尽的日志。但日志不是用来堆灰的，你要主动用它。

  • 快速接续 ：当你隔了一天再打开项目，不用在Chat里翻历史记录。直接打开 .mouse/tasks/ 下状态为 InProgress 或 Blocked 的任务文件，阅读最新的几条 HistoryLog 或 ExecutionLog ，你就能在几秒钟内恢复到最新的上下文。然后对AI说：“继续任务MOUSE#TASK_0003，我们上次在子任务2.3中遇到了一个关于API响应格式的问题。”
  • 根因分析 ：当出现一个Bug时，不要盲目地让AI“修复它”。先去查日志。搜索最近修改了相关文件的TaskID。打开那个任务文件，查看AI当时修改的意图和具体变更。很多时候，Bug的引入原因和修复方法就在日志里写着。这比让AI重新理解整个问题要高效得多。
  • 知识沉淀 ： FinalOutputSummary 字段是黄金。特别是对于解决了一个棘手问题（如某个诡异的兼容性Bug）的子任务，AI在总结里写下的解决方案和观察，是你项目的宝贵知识库。定期回顾这些总结，能避免重复踩坑。

5.3 协议引导的时机与话术

不是每次对话都需要 @ 规则文件。过度使用会让对话显得生硬。我的经验是：

  • 任务启动时必用 ：在发起一个明确的新功能开发、重构或复杂修复时，开头就带上 @core_protocol.mouse.mdc ，为本次协作定下基调。
  • AI偏离时纠正 ：如果你发现AI开始跳过创建任务文件直接写代码，或者修改文件却不记录，立即打断它：“请暂停。请先遵循Mouse协议，为此修改创建一个任务或子任务并记录在案。@core_protocol.mouse.mdc”
  • 涉及标准时引用 ：当任务进入具体实现阶段，可以引用具体标准文件。“在实现这个组件时，请确保遵循我们的Vue组件规范。@vue_standards.mouse.mdc”
  • 日常小修小补可不用 ：对于“把这个变量名改一下”、“在这个函数里加一行日志”这种几秒钟就能完成的微调，可以不强制启动完整的Mouse流程，以保持灵活性。

5.4 处理AI的“不完美”遵循

即使有协议，AI（尤其是不同模型）的遵循程度仍有差异。我的应对策略是：

  1. 明确指令胜于模糊期望 ：不要说“按规矩来”。要说：“请严格按照Mouse协议第3.2节的要求，为这个功能创建一个计划文件，并至少分解出3个原子性的子任务，每个子任务必须包含Objective、Deliverables和Acceptance Criteria。”
  2. 检查与修正 ：把AI生成的任务/计划文件当作初稿。主动去阅读和修正。如果子任务分解不合理，直接在Chat中给出修改后的Markdown代码块，让AI更新文件。 你是项目经理，AI是执行者，你有最终的审核权。
  3. 利用“Clarity First”原则 ：如果AI对某个指令犹豫或执行结果奇怪，这往往是你的指令不够清晰导致的。此时，应该欢迎AI根据协议向你提问。回答这些问题，本身就是对任务需求的再次澄清和精炼，能极大提升后续执行的质量。

6. 常见问题与故障排除实录

在实际使用中，你肯定会遇到一些状况。以下是我和社区用户遇到的最典型问题及其解决方案。

6.1 AI不创建.mouse目录或任务文件

现象 ：你发出了带 @core_protocol.mouse.mdc 的指令，但AI只是口头回应，没有在文件系统中创建任何东西。

可能原因与解决 ：

  1. 规则未正确加载 ：首先确认 .cursor/rules/ 目录是否在 项目根目录 下，并且 core_protocol.mouse.mdc 文件在其中。Cursor有时需要重启或重新打开项目才能加载新规则。
  2. 指令不够明确 ：AI可能认为当前对话还不构成一个“任务”。尝试更正式的启动语句：“ 现在，请初始化一个Mouse任务。 任务标题：‘修复用户登录失败的错误’。描述：‘部分用户在输入正确密码后仍提示登录失败，需要排查...’”
  3. 模型差异 ：不同AI模型对规则的敏感性不同。Claude和Gemini通常遵循得更好。在Cursor中，你可以尝试切换不同的模型（如从Claude切换到Gemini）来执行任务初始化步骤。
  4. 手动创建 ：如果上述方法无效，你可以自己创建 .mouse/tasks/ 目录和一个简单的任务文件模板，然后对AI说：“我已经创建了任务框架，请根据MOUSE#TASK_0001.md中的内容继续执行。”

6.2 任务ID冲突或重复

现象 ：出现了两个 MOUSE#TASK_0005.md 文件，或者ID不连续。

原因 ：正如项目已知问题所述，AI没有真正的全局内存。如果同时进行多个对话，或者在不同会话中快速创建任务，AI可能无法准确记住已使用的最后一个ID。

解决方案 ：

  • 预防 ：对于重要的、长期的项目，我建议 手动管理起始ID或使用更复杂的ID 。你可以修改协议规则（有一定难度），或者简单地告诉AI：“在创建新任务时，请先检查 .mouse/tasks/ 目录下已存在的最大ID号，然后使用下一个可用的数字。例如，现有最大ID是MOUSE#TASK_0012，则新任务应为MOUSE#TASK_0013。”
  • 事后修复 ：如果已经冲突，手动重命名或删除重复的文件即可。任务ID主要是为了识别和排序，不影响看板功能（看板通过文件内容解析状态）。

6.3 可视化看板无法加载数据

现象 ：打开 mouse_dashboard.html 后，页面空白或提示无法加载数据。

排查步骤 ：

  1. 检查路径 ：确保你通过HTTP服务器（ http://localhost:... ）访问，而不是直接双击文件（ file://... ）。后者可能因浏览器同源策略而阻止读取 .mouse 目录。
  2. 检查控制台 ：按F12打开浏览器开发者工具，查看“Console”（控制台）标签页是否有红色错误信息。常见的错误是“Failed to load resource”或跨域错误，这通常确认了是文件协议访问的问题。
  3. 检查数据源 ：确认你的项目根目录下确实存在 .mouse 文件夹，并且里面有 .md 文件。看板只会读取 tasks/ 和 plans/ 子目录下的Markdown文件。
  4. 检查文件格式 ：确保你的 .md 任务/计划文件格式正确，特别是YAML头信息（ --- 包裹的部分）没有语法错误。一个格式错误的文件可能导致整个解析失败。可以尝试暂时移走疑似有问题的文件，看看板是否能加载其他任务。

6.4 AI记录了日志但未实际修改文件

现象 ： HistoryLog 里写满了“正在创建XXX文件”、“正在修改YYY函数”，但实际项目文件毫无变化。

原因 ：这是最需要警惕的情况之一。通常是因为AI处于“聊天模式”，它只是在 模拟 或 描述 操作，而没有获得执行实际文件操作的权限或指令。

解决 ：

  • 使用“Edit”模式或“Chat”中的代码块 ：对于重要的文件创建和修改，最可靠的方式是让AI在Chat中生成具体的代码块，然后由你 亲自 复制粘贴到对应文件中并保存。或者，使用Cursor的“Edit”指令，让AI直接编辑指定文件。
  • 明确指令 ：告诉AI：“请将上述方案，实际创建/修改到项目文件中。对于新文件，请在Chat中提供完整代码；对于现有文件，请使用Cursor的编辑功能或给出具体的diff更改建议。”
  • 理解边界 ：记住，Mouse协议本身是一个“记录”和“规划”框架，它不赋予AI自动执行文件操作的超能力。实际的文件操作，仍然需要你通过Cursor的编辑功能或手动操作来完成。协议确保了这些操作被“记录在案”。

6.5 如何管理越来越多的任务文件

现象 ：项目进行数月后， .mouse/ 目录里积累了上百个任务文件，显得杂乱。

最佳实践 ：

  • 定期归档 ：对于状态已是 Done 或 Cancelled 且与当前迭代无关的旧任务，可以定期将它们移到一个归档目录，例如 .mouse/archive/2023-Q3/ 。这能保持活动任务的目录清爽。看板程序通常只读取 tasks/ 和 plans/ 根目录，所以归档不影响当前视图。
  • 利用Git ： .mouse/ 目录本身就在版本控制下。你可以利用Git分支来管理不同功能集的任务历史。例如，在 feature/auth-overhaul 分支上， .mouse/ 目录里就是该功能相关的所有任务。合并分支时，这些任务记录也会被合并，提供了完整的功能开发历史。
  • 标签化 ：在任务文件的YAML头信息中善用 Tags 字段。例如，标记为 [bugfix, high-priority] 或 [refactor, database] 。未来的看板版本或许能支持按标签过滤，目前你也可以通过搜索文件内容来快速定位相关任务。

Mouse不是一个完美的、全自动的魔法工具，它是一个需要你稍加引导和管理的、极其强大的协作框架。它把原本混沌的AI编程过程，变成了一个可规划、可追踪、可复盘的工程项目。开始可能会觉得多了一些步骤，但一旦习惯，你会发现它带来的清晰度和掌控感，远超过那一点额外的管理开销。尤其是在团队协作或处理长期项目时，这份“数字工单”的价值会愈发凸显。

Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

DeepSeek-V4 上线验收标准：从压测到观测的工程实践

avatar DeepSeek技术社区
cover

多租户推理服务中密钥管理与配额熔断的工程实践

avatar DeepSeek技术社区
cover

知识库权限下放至段落级：DeepSeek RAG 增量索引与 ACL 同步的工程实践

avatar DeepSeek技术社区