1. 项目概述：用纯 Markdown 构建你的 AI 编程“第二大脑”

如果你和我一样，每天都在和 Claude、Cursor 这类 AI 编程助手打交道，那你一定遇到过这个令人头疼的问题：聊着聊着，AI 就把十分钟前讨论过的关键设计决策给忘了。或者，当你开启一个新会话，想继续昨天的工作时，又得从头到尾把项目背景、技术栈、当前进度再复述一遍。这种“金鱼记忆”不仅打断心流，更严重的是，它让 AI 无法积累经验，同一个错误可能会在不同的会话里反复出现。

市面上已经有了像 .cursorrules 或 AGENTS.md 这样的格式规范，它们能告诉 AI“应该怎么做”，但它们解决不了“记忆”和“管理”的问题。它们就像一本静态的操作手册，而我们需要的是一个能学习、能记忆、能根据上下文动态调整的“操作系统”。

这就是 MUSE 诞生的原因。它不是一个插件，也不是一个需要安装的软件，而是一套完全用纯 Markdown 文件构建的 AI 编程治理系统 。你可以把它理解为你和 AI 结对编程时的“第二大脑”和“项目管理中心”。它通过一套精巧的目录结构、文件约定和交互协议，实现了 角色隔离、持久化记忆、技能库、跨角色指令队列 等高级功能，而且 零代码依赖 ，复制粘贴就能用。

我花了几个月时间，在自己的多个项目中深度使用并迭代 MUSE。实测下来，它让我的 AI 助手从一个健忘的“临时工”，变成了一个拥有项目长期记忆、懂得分工协作的“资深搭档”。最直观的体验是，现在我用 /resume 命令开始工作，AI 能自动加载比裸奔状态下多 16.9 倍 的上下文信息，直接进入状态，再也不需要我手动喂背景了。

2. 核心架构解析：MUSE 如何用文件系统模拟“智能”

MUSE 的魔力不在于复杂的算法，而在于一套深思熟虑的、基于文件系统的约定。它把抽象的概念——“记忆”、“角色”、“技能”——都物化成了你可以看见、可以编辑的 Markdown 文件。理解这套架构，是高效使用和自定义 MUSE 的关键。

2.1 四层治理模型：从规范到系统

MUSE 将自己定位在“治理系统”层，这比单纯的格式规范高了一个维度。我们可以通过一个分层模型来理解它的定位和价值：

┌─────────────────────────────────────────────────────┐
│ L3  Memory Infrastructure   mem0 · MemOS · memsearch│  ← MUSE 不在这里竞争
├─────────────────────────────────────────────────────┤
│ L2  Governance System       🎭 MUSE                 │  ← MUSE 的核心战场
│     Roles · Memory · Skills · Directives · Dashboard│
├─────────────────────────────────────────────────────┤
│ L1  Workflow Kits           Spec Kit · sudocode     │  ← MUSE 覆盖并超越
├─────────────────────────────────────────────────────┤
│ L0  Format Specs            AGENTS.md · .cursorrules│  ← MUSE 兼容的基础
└─────────────────────────────────────────────────────┘

• L0 格式规范层 ：这是基础，定义了 AI 应该遵循的规则。MUSE 完全兼容它们，你的 AGENTS.md 可以无缝融入 MUSE 体系。
• L1 工作流工具包 ：提供一些预制的工作流。MUSE 内置的 /sprint （功能冲刺）和 /retro （回顾）就是这一层的典型代表，但它做得更系统。
• L2 治理系统层 ：这是 MUSE 的核心价值。它不止提供工作流，更提供一整套 管理机制 ：如何划分职责（角色）、如何保存和检索信息（记忆）、如何复用最佳实践（技能）、如何协调不同职责（指令队列）。这是从“工具”到“系统”的跃迁。
• L3 记忆基础设施层 ：更底层的、专门化的记忆存储与检索引擎。MUSE 明智地选择不在这里重复造轮子，而是专注于上层的治理逻辑。

我的理解 ：MUSE 的聪明之处在于，它用最简单的文本文件（Markdown）实现了 L2 层的复杂逻辑。它不试图取代专业的向量数据库，而是通过文件命名约定和搜索脚本，提供了一个“够用且极简”的记忆方案。这种务实的设计让它的上手和迁移成本几乎为零。

2.2 核心组件深度拆解

MUSE 的系统由几个核心组件环环相扣而成，每个都是一个独立的 Markdown 文件或目录。

1. 宪法层： CLAUDE.md 与 ETHOS.md 这是 AI 行为的“根本大法”。 CLAUDE.md 里写的是不容置疑的“铁律”，比如“所有交流使用中文”、“执行任何任务前先检查技能库”、“大文件每次只查看不超过300行”。这些规则优先级最高，确保了 AI 行为的基础可控性和安全性。 ETHOS.md 则定义了“建造者哲学”，更像是一种文化或价值观的灌输，比如“迭代优于完美”、“用户价值优先”。宪法层是静态的，为整个系统定下基调。

2. 角色层： .muse/ 目录 这是实现“角色隔离”的关键。在这个目录下，你可以为不同的职责创建独立的文件，例如：

• .muse/build.md : 负责功能开发的“建造者”角色状态。里面可能记录着当前正在实现的用户故事、下一步要写的函数、遇到的阻塞问题。
• .muse/qa.md : 负责质量保障的“测试者”角色状态。里面可能记录着待测的用例清单、已发现的 Bug、回归测试范围。
• .muse/growth.md : 负责增长和产品的“增长者”角色状态。可能记录着用户反馈、数据分析洞察、待优化的转化路径。

每个角色文件只关注自己职责范围内的上下文。当你以 /resume qa 启动会话时，AI 主要看到的是 qa.md 的内容和与之相关的记忆，而不会受到 build.md 中技术细节的干扰。这模拟了真实团队中的分工协作。

3. 记忆层： memory/ 与 MEMORIES.md 这是 MUSE 的“大脑”，采用了类似人类记忆的“短期-长期”双存储模型。

• 短期记忆 ( memory/YYYY-MM-DD.md ) : 每天自动生成一个文件，记录当天所有会话的原始对话、决策过程和代码片段。这是未经加工的“记忆碎片”。
• 长期记忆 ( MEMORIES.md ) : 通过 /distill 命令，从多日的短期记忆中提炼出高价值的经验、教训、设计决策和用户偏好。例如：“项目X中，使用Y库处理Z场景会导致性能问题，改用A方案更好。” 长期记忆是按主题分类的结构化知识。

4. 技能层： .agent/skills/ 目录 这里存放着65个可复用的“技能”文件。每个技能都是一个封装好的、解决特定问题的 Markdown 指令集。例如：

• git-commit.md : 指导 AI 如何编写规范的提交信息。
• systematic-debugging.md : 提供一个系统化的调试流程。
• tdd-workflow.md : 定义测试驱动开发的步骤。 技能分为“常驻技能”（每次会话都加载）、“触发技能”（遇到相关任务时加载）和“生命周期技能”（在特定事件如会话压缩时触发）。这极大地提升了 AI 处理复杂任务的一致性和专业性。

5. 工作流层：内置命令 这是用户与 MUSE 系统交互的接口。一系列以 / 开头的命令，如 /resume , /sprint , /bye , /distill ，封装了复杂的上下文管理操作，让用户可以用一个简单的指令触发一系列自动化流程。

2.3 数据流与生命周期：一次完整的协作是如何发生的

让我们跟踪一次典型的开发会话，看看数据如何在 MUSE 的各个组件间流动：

1. 启动 ( /resume build ) : 你输入命令。MUSE 引导 AI 执行以下操作：

   • 读取宪法 ：加载 CLAUDE.md 和 ETHOS.md ，确立行为准则。
   • 恢复角色状态 ：读取 .muse/build.md ，了解上次开发中断时的具体进度（例如：“正在实现用户登录模块，已完成API层，待完成前端表单验证”）。
   • 加载相关记忆 ：从 memory/ 目录中查找与“登录”、“认证”相关的近期日志，并从 MEMORIES.md 中提取关于“认证安全最佳实践”的长期教训。
   • 装配技能 ：根据当前任务（可能是“前端开发”），自动加载 frontend-design.md 、 ui-ux-pro-max.md 等技能。
   • 最终，AI 会生成一个包含以上所有信息的、超长的系统提示 ，并基于此开始与你对话。此时，AI 已经是一个深度了解项目历史、当前任务和最佳实践的“专家”了。

2. 协作与记忆 : 在接下来的对话中，所有有价值的交互（你的指令、AI的思考、生成的代码、达成的共识）都会被自动追加到当天的 memory/YYYY-MM-DD.md 文件中。同时， .muse/build.md 文件也会被更新，以反映最新的进度状态。

3. 健康检查 ( /ctx ) : 在会话中，你可以随时使用 /ctx 命令。AI 会评估当前对话消耗的上下文窗口比例，并给出“绿灯”（充足）、“黄灯”（警告）或“红灯”（即将耗尽）的指示。这让你能主动管理上下文，避免在关键时刻因“失忆”而前功尽弃。

4. 优雅结束 ( /bye ) : 工作完成后，输入 /bye 。这会触发一个“会话收尾协议”：

   • 保存最终状态 ：将最终的进度更新到 .muse/build.md 。
   • 执行防御性压缩 ：如果会话很长，可能会触发 strategic-compact 技能，对当前对话进行智能摘要，并保存到记忆文件中。
   • 检查记忆蒸馏 ：提醒你是否需要运行 /distill 来将短期记忆转化为长期知识。
   • 更新数字孪生 ：如果配置了 USER.md ，可能会更新你的个人偏好档案。

5. 知识提炼 ( /distill ) : 每隔几天或积累了一定量的短期记忆后，你运行 /distill 。AI 会扫描 memory/ 目录下的多个日志文件，识别出重复出现的模式、重要的决策、解决的难题和学到的教训，然后将这些结构化、分类别地写入 MEMORIES.md 。这个过程就是“把经验变成知识”。

实操心得 ：不要等到记忆文件堆积如山才做 /distill 。我习惯在完成一个功能模块或解决一个复杂问题后立即进行。这时细节还热乎着，提炼出的知识最准确、最有价值。长期记忆库 MEMORIES.md 会成为项目最宝贵的资产，新加入的 AI（或团队成员）能通过它快速掌握项目精髓。

3. 从零开始：手把手部署与配置你的 MUSE 系统

理解了架构，我们来实战。我将带你完成一次从克隆到深度定制的完整部署，并分享每一步的配置要点和避坑指南。

3.1 基础部署：三种方式任你选

方式A：交互式安装（推荐给所有用户） 这是最省心的方法，尤其适合不熟悉命令行或想快速体验的用户。

# 1. 克隆仓库
git clone https://github.com/myths-labs/muse.git
cd muse

# 2. 运行交互式设置脚本
./setup.sh

运行后，脚本会像一个向导一样问你几个问题：

• Preferred language : 选择系统的主要工作语言（如 zh 中文）。
• Default AI model : 选择你主要使用的 AI 工具（如 claude 对应 Claude Code）。
• Docs preference : 询问你是否需要中文文档。 根据你的回答，它会自动配置好对应的模板文件。完成后，你的当前目录就已经是一个配置好的 MUSE 项目根目录了。

方式B：针对特定工具的快速安装 如果你已经明确要用哪个 AI 工具，并且想把它应用到现有的项目中，这个方法最直接。

# 假设你的项目在 /Users/you/Projects/my-awesome-app
cd /Users/you/Projects/my-awesome-app

# 从 MUSE 仓库运行安装脚本，指定工具和目标路径
/path/to/muse/scripts/install.sh --tool cursor --target .

# 或者，如果你已经在 muse 目录内
cd /path/to/muse
./scripts/install.sh --tool cursor --target /Users/you/Projects/my-awesome-app

这个脚本会做几件事：

1. 将 MUSE 的核心模板文件（ CLAUDE.md , USER.md , MEMORIES.md ）复制到你的项目根目录。
2. 在项目根目录创建必要的文件夹（ .muse/ , memory/ , .agent/ ）。
3. 将技能库和工作流文件复制到 .agent/ 下。
4. 最关键的一步 ：根据你指定的工具（如 cursor ），它会将 CLAUDE.md 中的宪法内容，转换成该工具能识别的格式（对于 Cursor，是 .cursor/rules/ 目录下的 .mdc 文件），并放置到正确的位置。

方式C：手动部署（适合追求完全控制或学习） 如果你想深入每一个细节，或者项目有特殊的结构要求，手动部署是最好的方式。

# 1. 在你的项目根目录创建 MUSE 所需的核心文件和目录
cd /your/project/root

# 2. 创建宪法和记忆文件（可以从 MUSE 仓库复制模板，或从头编写）
touch CLAUDE.md ETHOS.md USER.md MEMORIES.md

# 3. 创建核心目录
mkdir -p .muse memory .agent/skills .agent/workflows

# 4. （可选）将 MUSE 仓库的技能库复制过来，这是一个巨大的效率提升
cp -r /path/to/muse/skills/* .agent/skills/
cp -r /path/to/muse/workflows/* .agent/workflows/

# 5. 更新 .gitignore，避免将私人记忆和状态文件提交到仓库
echo "# MUSE System" >> .gitignore
echo ".muse/" >> .gitignore
echo "memory/" >> .gitignore
echo "MEMORIES.md" >> .gitignore
echo "USER.md" >> .gitignore
echo ".agent/" >> .gitignore

手动部署让你对每个文件的作用有最清晰的认识。部署完成后，你的项目结构应该如下所示：

your-project/
├── CLAUDE.md              # 📜 宪法（AI 的铁律）
├── ETHOS.md               # 💡 建造者哲学
├── USER.md                # 👤 你的个人偏好（私密）
├── MEMORIES.md            # 🧠 长期记忆库（私密）
├── .muse/                 # 🎭 角色状态目录（私密）
│   └── build.md           # ⚙️ 开发者角色状态文件
├── memory/                # 📝 短期记忆目录（私密）
│   └── 2024-05-27.md     # 当天的对话日志
├── .agent/                # 🤖 技能与工作流（可共享）
│   ├── skills/            # 技能库（65+个技能文件）
│   └── workflows/         # 工作流定义
└── [你的源代码目录]       # 项目本身的代码

注意事项 ：无论用哪种方式，请务必检查 .gitignore 文件。 memory/ 、 .muse/ 、 MEMORIES.md 、 USER.md 这些文件包含你的会话历史和个人偏好， 强烈建议不要提交到公开的版本库 。而 .agent/skills/ 和 CLAUDE.md 、 ETHOS.md 的核心部分通常是可以共享的。

3.2 核心文件定制：让你的 MUSE 独一无二

部署只是搭好了舞台，定制才是让 MUSE 真正为你所用的关键。

1. 打磨你的宪法： CLAUDE.md 这是最重要的文件。不要直接使用默认模板，一定要根据你的项目和技术栈进行深度定制。一个有效的宪法应该包含：

# 铁律 (Iron Rules)
1.  **语言与沟通**：所有对话、代码注释、提交信息均使用简体中文。除非是专有名词或库名，否则避免中英文混杂。
2.  **技能优先**：在执行任何任务（编码、调试、设计）前，必须首先检查 `.agent/skills/` 目录中是否有相关技能文件，并遵循其中定义的最佳实践。
3.  **大文件处理**：对于超过 300 行的文件，必须分段查看。先看文件头部（结构定义）和尾部（主要函数），再根据需求查看特定函数。严禁一次性要求查看整个大型文件。
4.  **上下文警戒线**：当感知到上下文窗口使用率超过 80% 时，必须立即主动提醒用户，并建议执行 `/ctx` 命令检查或 `/bye` 命令结束会话。
5.  **验证闭环**：在声称完成任何任务（如修复 Bug、实现功能）前，必须提供可验证的步骤或证据。例如，修复 Bug 后应说明如何复现和验证修复；实现功能后应说明测试方法。
6.  **会话礼仪**：每次会话结束时，必须等待用户输入 `/bye` 命令，以触发完整的会话收尾、状态保存和记忆归档流程。

# 项目特定规则 (Project-Specific Rules)
- **技术栈**：本项目使用 Next.js 14 (App Router)、TypeScript、Tailwind CSS 和 Prisma ORM。所有代码必须符合此技术栈规范。
- **代码风格**：使用 ESLint 和 Prettier 配置。所有生成的代码必须通过 `npm run lint` 检查。
- **API 设计**：遵循 RESTful 规范，响应格式统一为 `{ success: boolean, data: any, message?: string }`。
- **安全要求**：所有用户输入必须经过验证和清理。数据库查询必须使用参数化查询或 Prisma 的 safe API，绝对禁止字符串拼接。

为什么这么写？ 第一条规则避免了中英文混杂的混乱。第二条确保了最佳实践的复用。第三条和第四条是应对 AI 上下文限制的“生存法则”。第五条强制形成了“完成定义”，提高了交付质量。第六条保证了 MUSE 系统的完整性。下面的项目特定规则，让 AI 从一开始就站在项目的上下文里思考。

2. 定义建造者哲学： ETHOS.md 这个文件塑造 AI 的“性格”和“价值观”。它不像宪法那样强制，但会潜移默化地影响 AI 的决策倾向。

# 我们的建造者哲学
1.  **迭代优于完美**：我们追求快速发布和持续改进，而不是等待一个“完美”的版本。首个可运行版本比完美的蓝图更有价值。
2.  **用户价值驱动**：每一个功能、每一行代码，都要问“这为用户解决了什么问题？”。优先处理高用户价值、高影响度的事务。
3.  **简单性是高级的复杂**：在满足需求的前提下，选择最简单、最直白的解决方案。过度设计是万恶之源。
4.  **所有权精神**：你不仅是代码的执行者，更是这个功能的“主人”。你需要思考边界情况、错误处理、监控指标，而不仅仅是完成票上的任务。
5.  **透明沟通**：遇到阻塞、风险或预估偏差，第一时间透明沟通。隐藏问题不会让它消失，只会让它爆炸时威力更大。

3. 创建你的角色文件： .muse/build.md 角色文件是动态的，记录着该角色的“工作现场”。初始内容可以很简单：

# 建造者角色状态
**当前聚焦**：用户认证模块
**当前任务**：实现基于 JWT 的登录 API 接口 `/api/auth/login`
**下一步行动**：
- 在 `lib/auth.ts` 中完成 `signToken` 工具函数。
- 在 `app/api/auth/login/route.ts` 中实现 POST 处理逻辑，连接数据库验证用户。
- 编写对应的单元测试。
**阻塞项**：无
**今日进展**：
- [x] 设计了用户表 Prisma Schema。
- [x] 创建了密码哈希工具函数。

随着会话进行，AI 和你会共同更新这个文件。它成为了上下文恢复的“锚点”。

3.3 技能库的妙用：从“会用”到“精通”

MUSE 自带的65个技能是一个宝库。但很多人只是复制过去，却没有真正“激活”它们。关键在于 CLAUDE.md 中的那条铁律：“ 执行任何任务前，必须首先检查技能库 ”。你需要训练 AI（其实也是训练自己）养成这个习惯。

例如，当你让 AI 进行代码审查时，它应该自动触发 security-review.md 和 code-review-checklist.md 技能。这些技能文件里可能包含了：

• 安全检查清单（SQL注入、XSS、敏感信息泄露）。
• 代码质量清单（单一职责、错误处理、日志记录）。
• 性能审查要点（N+1查询、循环内复杂操作）。

如何自定义技能？ 非常简单。在 .agent/skills/ 目录下创建一个新的 .md 文件即可。例如，为你的项目创建一个 deploy-to-vercel.md ：

# 技能：部署到 Vercel
**触发条件**：当用户提及“部署”、“上线”、“发布到生产环境”时。
**执行步骤**：
1.  **检查**：确保 `vercel.json` 或 `next.config.js` 中的配置正确，特别是环境变量和重写规则。
2.  **构建**：运行 `npm run build` 确保本地构建成功，无类型错误或编译错误。
3.  **环境变量**：核对 `.env.production` 文件中的变量是否与 Vercel 项目设置中配置的完全一致。
4.  **数据库迁移**：如果涉及数据库变更，提示用户需先在生产数据库上运行 `npx prisma migrate deploy`。
5.  **部署命令**：提供部署命令 `vercel --prod`，并提示用户确认。
6.  **部署后检查**：部署完成后，提供检查清单：访问首页、测试核心 API、检查日志是否有报错。

现在，当你说“准备部署一下”，AI 就会加载这个技能，并引导你完成一个标准、安全的部署流程，避免遗漏关键步骤。

4. 高阶工作流与实战技巧

当基础配置完成后，MUSE 真正强大的地方在于其预设的高阶工作流。这些不是简单的命令，而是封装了最佳实践的完整协作剧本。

4.1 /sprint ：像产品团队一样进行功能冲刺

/sprint 命令将一个功能从想法到上线的过程，结构化为七个阶段。它不仅仅是给 AI 一个指令，更是为你和 AI 提供了一个清晰的协作框架。

阶段拆解与实操要点：

1. Think (思考) ：AI 会引导你澄清需求。 关键问题 ：“这个功能为用户解决的核心问题是什么？”“成功的标准是什么？” 这一步一定要写下来，放在角色文件或记忆里，作为后续所有决策的北极星。
2. Plan (规划) ：AI 会帮你进行技术方案设计。 我的经验 ：在这里要强迫 AI 输出一个简单的系统设计图（用文字或 Mermaid 语法描述），并识别出潜在的技术风险（如第三方 API 的稳定性、数据一致性要求）。规划的输出应该是一个可执行的任务列表。
3. Build (构建) ：进入编码阶段。此时，MUSE 的角色隔离优势就体现出来了。 .muse/build.md 文件会持续更新当前任务、下一步行动和阻塞项。 技巧 ：要求 AI 将大任务拆解成小于2小时的“原子提交”，并遵循 git-commit 技能规范。这能让进度更可视，回滚也更安全。
4. Review (审查) ：构建完成后，切换到“QA角色”进行审查。你可以通过 /resume qa 启动一个专注于审查的会话。AI 会加载 code-review-checklist.md 等技能，从代码质量、安全、性能、测试覆盖度等角度进行系统性审查。 注意 ：审查意见要记录在 .muse/qa.md 中，并与 build.md 中的待办项关联。
5. Test (测试) ：AI 会引导或帮助你编写测试用例。对于关键路径，一定要有集成测试或 E2E 测试。MUSE 的 tdd-workflow.md 技能在这里非常有用。
6. Ship (发布) ：对应我们自定义的 deploy-to-vercel.md 技能。AI 会按步骤引导你完成部署前检查、执行部署和部署后验证。
7. Reflect (反思) ：这是最容易被忽略但价值最高的一步。AI 会引导你回顾整个冲刺过程：哪些地方做得好？遇到了什么意外问题？有什么经验教训？ 务必 将反思的结果通过 /distill 命令提炼后存入 MEMORIES.md 。例如：“在实现支付回调时发现，网络超时处理不足，导致订单状态不一致。解决方案：增加异步重试队列和最终状态对账任务。”

避坑指南 ：不要试图在一个超长的会话中完成整个 /sprint 。最好每个阶段（尤其是 Build 和 Review）用独立的会话完成，并用 /bye 妥善保存状态。这样能有效管理上下文，也让 AI 能在每个阶段保持最佳状态。

4.2 /retro ：数据驱动的每周回顾

/retro 是一个强大的元工作流。它不只是让你“感觉一下”这周做了什么，而是通过分析 git log 和 memory/ 目录，给你生成一份数据驱动的报告。

它会分析什么？

• 提交数据 ：从 git log --since="1 week ago" 中提取提交次数、提交信息模式、文件变更分布。
• 记忆分析 ：扫描过去一周的 memory/*.md 文件，统计讨论的主题、解决的问题、遇到的错误。
• 生成报告 ：综合以上信息，生成一份包含“本周产出”、“遇到的问题”、“学到的教训”、“下周重点”的回顾报告。

如何最大化其价值？

1. 保持提交信息的规范性 ：使用 git-commit 技能，确保提交信息清晰（如 feat: 实现用户登录API 、 fix: 修复支付回调超时处理 ）。这样 /retro 的分析会更准确。
2. 在记忆日志中记录决策 ：在 memory/ 文件中，不仅记录代码，也记录“为什么这么做”的讨论。例如：“决定选用A方案而非B，因为A在并发场景下更稳定，见链接[设计讨论]。”
3. 将回顾输出存入 MEMORIES.md ：运行 /retro 后，将其输出的核心教训和下周计划，手动或通过提示让 AI 提炼后存入 MEMORIES.md 。这形成了持续改进的闭环。

4.3 记忆管理：从数据沼泽到知识图谱

memory/ 目录很容易变成一堆杂乱无章的日志文件。有效的记忆管理是 MUSE 能否发挥长期价值的关键。

1. 定期蒸馏 ( /distill ) 这是我的个人节奏，供参考：

• 每日小蒸馏 ：每天工作结束时，花5分钟快速浏览当天的 memory/YYYY-MM-DD.md ，用一句话总结最重要的1-2个收获，手动添加到 MEMORIES.md 的“本日亮点”部分。
• 每周大蒸馏 ：周末运行一次 /distill ，让 AI 系统性地扫描过去一周的所有记忆文件。AI 会识别出：
  • 重复出现的模式 （例如，三次不同的会话都提到了“数据库连接池配置”）。
  • 解决了的难题 （例如，如何优化某个复杂查询）。
  • 做出的重要决策及其原因 。
  • 用户或测试反馈的汇总 。 将这些信息分类（技术决策、业务逻辑、踩坑记录、优化点）后，结构化地写入 MEMORIES.md 。

2. 智能搜索 ( /search ) 当 MEMORIES.md 和 memory/ 文件越来越多时，如何快速找到所需信息？MUSE 提供了一个基于 TF-IDF 的简单搜索脚本 ( ./scripts/search.sh )。虽然不如专业的语义搜索引擎强大，但对于文本量不大的个人项目完全够用。

# 在项目根目录下搜索所有记忆和角色文件中关于“登录”的内容
./scripts/search.sh 登录

技巧 ：为你搜索到的关键知识在 MEMORIES.md 中添加易于搜索的关键词标签，例如 #优化 #数据库 #索引 。

3. 归档与清理 MUSE 有自动检测机制，会在你运行 /bye 时提醒你“记忆文件已累积多日，建议进行蒸馏”。对于已经蒸馏过的、旧的 memory/ 文件，我建议：

• 创建一个 memory/archive/ 目录。
• 将超过30天且已蒸馏过的日志文件移入归档目录。
• 在 MEMORIES.md 开头维护一个“归档索引”，记录哪些日期的原始日志已被归档，以及其中包含的主要知识点。

5. 常见问题与故障排查实录

即使设计得再完善，在实际使用中还是会遇到各种问题。以下是我在深度使用 MUSE 过程中遇到的一些典型情况及解决方案。

5.1 上下文依然耗尽过快

问题描述 ：即使使用了 MUSE，在非常复杂的任务中，AI 仍然会提示上下文窗口将满。

根本原因 ：MUSE 的 /resume 虽然装配了大量上下文，但后续的长篇对话本身也会消耗上下文。宪法、技能、记忆、角色状态这些“系统负载”是固定的，而对话内容则是增长的变量。

解决方案 ：

1. 启用防御性自动保存 ：MUSE 有一个 L0 防御机制，每10轮对话会静默保存一次当前关键上下文到 memory/CRASH_CONTEXT.md 。确保你的 CLAUDE.md 中相关规则是启用的。这样即使会话崩溃，最多只丢失10轮对话。
2. 主动使用 /ctx 命令 ：在感觉对话有点长时，主动运行 /ctx 检查健康度。如果显示黄灯（>60%），可以考虑：
   • 运行 /bye 然后 /resume ：主动结束当前会话并重新开始。新的会话会加载最新的角色状态和记忆，但抛弃了中间的对话过程。这相当于“重启”了 AI，保留了结果但清理了过程。
   • 使用 strategic-compact 技能 ：在会话中，你可以直接要求 AI：“请使用战略压缩技能，总结我们过去20轮对话关于X模块设计的核心结论。” AI 会生成一个高度凝练的摘要，你可以将这个摘要复制到角色文件或记忆文件中，然后开始新会话。
3. 优化你的记忆文件 ：检查 MEMORIES.md 和 memory/ 中的日志。是否记录了太多冗余的、未提炼的对话？定期蒸馏和归档，保持长期记忆库的精炼。

5.2 多角色协作时状态不同步

问题描述 ：你在 build 角色下开发了一个功能，切换到 qa 角色进行测试时，QA 角色似乎不知道这个新功能的存在。

原因分析 ：角色隔离是 MUSE 的核心特性， .muse/build.md 和 .muse/qa.md 是两个独立的状态文件。默认情况下，它们不会自动同步。

解决方案 ：使用 📡 指令队列 和 /sync 命令。

1. 发送指令 ：在 build 角色会话结束时，你可以让 AI 向 qa 角色发送一条指令。例如，在 .muse/build.md 中追加：

   [指令至 qa]
   新功能“用户画像分析”已开发完成，代码位于 `src/features/analytics/`。主要入口组件是 `UserProfileChart.tsx`。请依据测试技能进行功能和性能测试。
   

   或者，更正式的做法是，在 memory/ 目录下创建一个 directive_to_qa.md 文件，MUSE 的同步机制能识别它。
2. 同步状态 ：在启动 qa 角色会话时，使用 /sync receive 命令。AI 会主动去检查其他角色目录或指令文件，获取最新的更新。
3. 设计同步节奏 ：对于紧密协作的角色（如 build 和 qa），可以约定在每日站会（虚拟的）后手动运行一次 /sync all ，双向同步状态。对于独立性强的角色（如 growth 和 research），可以按需同步。

5.3 技能不触发或冲突

问题描述 ：你明明在 .agent/skills/ 目录下放置了对应的技能文件，但 AI 在执行相关任务时似乎没有应用它。或者，多个技能对同一任务有冲突的指导。

排查步骤 ：

1. 检查宪法 ：首先确认 CLAUDE.md 中“执行任何任务前先检查技能库”这条铁律是否存在且生效。
2. 检查技能加载逻辑 ：MUSE 的技能加载是有优先级的。 CLAUDE.md 中的“常驻技能”每次都会加载。对于“触发技能”，AI 是根据你的任务描述中的关键词来匹配技能文件名的。确保你的技能文件名包含清晰的关键词（如 database-migration.md ），并且你在对话中使用了这些关键词（如“我们需要进行一次数据库迁移”）。
3. 查看会话上下文 ：使用 /ctx 命令后，AI 有时会列出当前已加载的技能列表。检查你的目标技能是否在列。
4. 解决技能冲突 ：如果两个技能（例如 quick-prototype.md 和 production-ready-code.md ）对代码质量有不同要求，你需要在任务指令中明确指定优先级。例如：“我们现在进行原型设计，请主要应用 quick-prototype 技能，暂时忽略 production-ready-code 中关于完整错误处理的要求。”

5.4 与现有项目集成困难

问题描述 ：我的项目已经有复杂的目录结构，或者已经在使用其他 AI 助手配置（如自己的 .cursorrules ），如何平滑集成 MUSE？

解决方案 ：MUSE 的设计是非侵入式的。

1. 目录结构 ：MUSE 的所有文件都在项目根目录或 .muse 、 .agent 这样的隐藏目录下，与你的 src/ 、 app/ 等源码目录互不干扰。你可以放心部署。
2. 兼容现有配置 ：MUSE 的 CLAUDE.md 是你的“总宪法”。你可以将现有 .cursorrules 或 AGENTS.md 中的精华部分 合并 到 CLAUDE.md 中。然后，使用安装脚本（ ./scripts/install.sh --tool cursor ）时，MUSE 会自动将合并后的宪法内容转换成 Cursor 能识别的 .mdc 格式并放置到正确位置。 你无需删除旧的配置，MUSE 会覆盖或增强它 。
3. 渐进式采用 ：不必一开始就启用所有功能。可以从 最小配置 开始：只使用 CLAUDE.md 、 memory/ 和 /resume 、 /bye 命令。等你和 AI 都适应了这种有记忆的协作方式后，再逐步引入角色隔离、技能库和高级工作流。

5.5 可视化仪表板无法加载或数据不准

问题描述 ：使用在线仪表板或本地生成的 dashboard.html 时，看不到数据或数据看起来不对。

排查与解决 ：

1. 数据源问题 ：仪表板读取的是你项目目录下的 memory/ 、 .muse/ 、 MEMORIES.md 等文件。请确认：
   • 你打开仪表板时，选择的目录确实是你的 项目根目录 （包含上述文件的目录）。
   • 这些目录和文件有读取权限。
   • 你已经有了一些会话记录（即 memory/ 目录下有 .md 文件），否则仪表板自然是空的。
2. 本地仪表板生成 ：运行 ./scripts/dashboard.sh 后，它会在 .muse/dashboard.html 生成一个静态 HTML 文件。用浏览器打开这个文件。 注意 ：由于浏览器安全限制，直接双击打开（ file:// 协议）可能无法读取本地文件。最佳实践是使用一个简单的本地 HTTP 服务器：

   # 在项目根目录运行
   python3 -m http.server 8000
   

   然后访问 http://localhost:8000/.muse/dashboard.html 。
3. 数据准确性 ：仪表板的数据分析基于简单的文件统计和模式匹配。如果觉得“会话时长”、“活跃角色”等数据不准，可以检查 memory/ 下的日志文件格式是否符合 YYYY-MM-DD.md 的命名规范，以及文件内容是否清晰。

经过几个月的深度使用，MUSE 已经从我的一个实验性项目，变成了我所有编码工作的标准配置。它带来的最大改变，不是某个具体功能的提升，而是将我和 AI 的协作从“一次性的问答”变成了“持续性的共建”。项目知识得以沉淀，最佳实践得以固化，犯错成本显著降低。最让我惊喜的是 /retro 功能，它让我能清晰地看到每周的产出流和认知迭代，这种反馈感对于独立开发者来说是无价的。如果你也在寻求与 AI 更深度、更持久的协作，我强烈建议你花上一个下午，按照本文的指南部署和配置属于你的 MUSE 系统。