# 自定义提示词

Muse 的系统提示词可以自行修改。默认提示词随 App 内置、升级时自动更新；只需将需要修改或新增的片段放入自定义目录即可覆盖或扩展，无需修改 App 本体。

::: tip v1.12.0 起
本文的片段命名规则（`<两位数字>-<名称>.md`）、按数字新增片段、`.no-builtin` 完全禁用开关与 <span v-pre>`{{AICODE_*}}`</span> 变量自 **v1.12.0** 起支持。更早的版本只能放与默认片段**完全同名**的文件来覆盖，不支持按数字新增、`.no-builtin` 与变量。
:::

## 在 App 里管理

也可以不碰文件系统，直接在 **设置 → 提示词** 里管理：

- 页面按编号列出**实际生效**的每个片段，右侧徽章标明这份内容来自哪一层：
  - **项目**：当前工作区的 `.muse/prompts.custom/`
  - **全局**：`~/.muse/prompts.custom/`
  - **本地**：`~/.muse/prompts/`（启动时从内置释放的副本）
  - **内置**：App 自带的 `assets/prompts/`
- 同一编号只生效优先级最高的一份，优先级 **项目 > 全局 > 本地 > 内置**，其余被遮挡。
- 点一行编辑它的内容。保存默认写到该编号当前生效的层；「本地/内置」不可写，编辑后默认落到全局层，可在编辑页把作用域切到项目层（有工作区时）。
- 所有片段都可左滑；项目/全局片段可删除当前覆盖，删掉后自动回退到下一层；本地/内置片段的删除按钮为灰色，不可删除。
- 右上角「+」可用未占用的编号新增片段。编辑时摘要与正文分开填写；摘要显示在列表和预览页，不会注入 AI。手工编写文件时，开头的 `<!-- 摘要 -->` 同样会被识别为摘要，正文预览会隐藏这段注释。
- 首次进入会自动弹出使用说明公告，右上角 Info 可随时重看。

### 批量删除

列表右上角的「多选」按钮（方框带勾的图标）可以一次删掉多条自定义片段：

1. 点「多选」进入多选模式，每行左侧出现勾选框，整行点击即勾选。只有**项目 / 全局**来源的片段可以勾选，本地与内置来源的勾选框是灰的。
2. 顶部操作条提供「全选 / 取消全选」与删除按钮，最右「×」或系统返回键退出多选。
3. 删除会弹确认框；确认后这些编号的自定义覆盖一并移除，各编号自动回落到下一层来源，列表随即刷新。

编辑页会避让软键盘；摘要或正文较长时可以上下滚动，继续编辑末尾内容。

App 里的改动与手工放文件完全等价，两种方式可以混用。

## 目录结构

提示词放在 AI 配置目录 `~/.muse/` 下（本地模式容器内为 `/root/.muse/`；远程模式为服务器用户 home 下的 `.muse/`，读写以远端为准）：

```
~/.muse/
├── prompts/          默认提示词（App 启动时全量释放，升级自动覆盖）
│   ├── 00-identity.md
│   ├── 10-communication.md
│   ├── ...           顶层是「静态基线」片段，按两位数字前缀排序（内置最后一个为 99-runtime-context.md）
│   └── agent/        按需注入的片段（不进静态基线，用到时才读取）
│       ├── plan-mode.md           PLAN 模式提醒
│       ├── auto-mode.md           AUTO 模式提醒
│       ├── subagent-base.md       子代理基础运行规范
│       ├── subagent-context.md    子代理运行期上下文（身份/工作区/时间）
│       ├── compact-summary.md     长对话上下文压缩
│       ├── title-generator.md     会话标题生成
│       └── init.md                /init 命令的指令正文
├── prompts.custom/   你的自定义片段（覆盖或新增，升级不动这里）
│   ├── 50-我的安全规则.md
│   ├── 25-额外要求.md
│   └── agent/
│       └── plan-mode.md           覆盖按需片段
├── skills/
└── docs/
```

片段分两类，命名规则不同：

- **静态基线**（`prompts/` 顶层）：`<两位数字>-<名称>.md`，数字是它的身份，决定在系统提示词里的位置。
- **按需片段**（`prompts/agent/`）：没有数字，用到时才读取（如切换模式、压缩上下文、派发子代理、生成标题）。

## 命名规则

自定义片段放在 `prompts.custom/`：

- **顶层文件**必须是 `<两位数字>-<名称>.md`（如 `05-开头.md`、`50-我的安全规则.md`）。数字即身份：
  - 数字与某个内置静态基线片段相同（内置数字为 `00`、`10`、`15`、`20`、`30`、`40`、`50`、`60`、`70`、`99`）→ **覆盖**该片段，尾部名称可任意取；
  - 数字不在上述集合里 → 作为**新增片段**，按数字大小插入基线的对应位置（如 `05-开头.md` 排在 `00` 与 `10` 之间）。
- 不符合该格式的文件（如 `notes.md`、`2024-备忘.md`）会被忽略。
- 同一数字有多个文件时只取文件名排最前的那个，其余忽略——请保持数字唯一。
- **`agent/` 子目录**里的片段没有数字身份，按**精确同名**覆盖（如 `prompts.custom/agent/plan-mode.md`）。

## 加载优先级

顶层数字片段（`<两位数字>-<名称>.md`）按四级来源查找，同一编号只生效优先级最高的一份，找到即止：

1. **项目**：`<工作区>/.muse/prompts.custom/`（远程模式下是 App 私有目录里对应的项目目录）
2. **全局**：`~/.muse/prompts.custom/`
3. **本地**：`~/.muse/prompts/<同名文件>` — 启动时释放的副本
4. **内置**：App 自带的 `assets/prompts/`

`agent/` 下的按需片段（无编号）没有项目层，按「全局自定义（`prompts.custom/agent/xxx.md`）→ 本地 → 内置」三级查找。

所以你只需要放想修改或想新增的那几个片段，其余会自动使用默认版本。

## 修改方式

1. 在 `~/.muse/prompts.custom/` 下（没有就手动创建）放入片段：覆盖内置片段用相同数字命名，新增片段用尚未占用的数字命名，子目录片段（如 `agent/plan-mode.md`）对应放到 `prompts.custom/agent/` 下。
2. 编辑内容。
3. **保存后即时生效**（无需重启 App）。

::: tip 提示词片段即时生效
自定义提示词片段每次请求都会重新读取，改完直接生效，不用重启 App。注意：技能清单、记忆、子代理清单仍是**新开会话**才刷新。
:::

编辑方式有三种：在终端里用 `vi` / `nano` 直接修改；交由 AI 代写（其文件工具能直接读写这个目录）；或[用文件管理器访问 App 私有目录](https://aicode.murk.top/md/guide/files.md#工作区文件在手机上的位置)。

## 完全禁用内置提示词

在 `prompts.custom/` 下新建一个名为 `.no-builtin` 的文件（内容随意，存在即生效），即可让**主代理**的系统提示词只由你在 `prompts.custom/` 顶层写好的数字片段组成：

- 不再注入任何内置片段，也不再自动附加技能清单、子代理清单、记忆、项目规则、工作区与当前时间；
- 需要哪些动态内容，就在你自己的片段里用下面的变量按需取回；
- 只作用于主代理，子代理仍按各自定义注入内置片段；
- `prompts.custom/` 里没有可识别的数字片段时系统提示词会为空，请确保至少有 `NN-xxx.md`。

::: danger 这是"完全接管"
启用后 AI 的行事规则完全由你写的片段决定，务必自备身份、工具说明与安全边界等内容，否则 AI 会缺少必要上下文。
:::

## 可用变量

在片段正文里写这些占位符，运行时会替换成真实内容；清单为空时替换为空字符串：

::: v-pre
| 变量 | 替换为 |
| --- | --- |
| `{{AICODE_SKILLS}}` | 可用技能列表（每行一项） |
| `{{AICODE_SUBAGENTS}}` | 可用子代理列表（每行一项） |
| `{{AICODE_MEMORY_GLOBAL}}` | 全局记忆列表（每行一项） |
| `{{AICODE_MEMORY_PROJECT}}` | 项目记忆列表（每行一项） |
| `{{AICODE_PROJECT_RULES_GLOBAL}}` | 全局项目规则正文（`~/.muse` 下的 `AGENTS.md` / `CLAUDE.md`） |
| `{{AICODE_PROJECT_RULES_PROJECT}}` | 工作区项目规则正文（项目根目录下的 `AGENTS.md` / `CLAUDE.md`） |
| `{{AICODE_PROJECT_RULES}}` | 等价于 `{{AICODE_PROJECT_RULES_PROJECT}}`，为兼容旧片段保留 |
| `{{AICODE_WORKSPACE}}` | 项目根目录（`~/workspace`，未选工作区时为提示文本） |
| `{{AICODE_ENVIRONMENT}}` | 当前运行环境（本地容器（PRoot） / 远程 SSH 服务器） |
| `{{AICODE_DATE}}` | 当前日期（`yyyy-MM-dd`） |
| `{{AICODE_SUBAGENT_NAME}}` | 当前子代理名称（仅子代理提示词渲染时有值） |
:::

::: tip 变量在任意片段处就地展开
系统提示词里的技能、子代理、记忆、项目规则、工作区与当前时间，默认由内置片段 `99-runtime-context.md` 用这些变量承载；你也可以在自己的片段里写变量，同样会在该处替换成真实内容。想改变这些内容的位置或顺序，编辑或覆盖 `99-runtime-context.md` 即可。
变量只替换为**纯数据**（列表行、文件正文、路径、日期），像「可用技能：」这样的标题与引导语都写在片段文件里，随片段一起编辑。
:::

`prompts.custom/` 里没有 `99-runtime-context.md` 的覆盖时，运行期上下文照常由内置版本注入；若你覆盖了它却没写变量，对应内容就不会出现。

其它占位符（如压缩提示词用的 <span v-pre>`{{INSTRUCTION}}`</span>）不受影响。

## 升级时的行为

- `prompts/` 目录每次启动都会被内置版本全量覆盖，所以默认提示词会随 App 升级自动更新。
- `prompts.custom/` 目录 App 永远不会自动写入或删除，你的自定义在升级后完整保留。

::: danger 请勿直接修改 prompts/ 目录
`prompts/` 目录中的内容在每次启动时都会被全量重置，手动修改的内容在 App 升级或重启后会被覆盖。如需持久自定义，请务必保存在 `prompts.custom/` 目录中。
:::

## 片段说明

| 文件名 | 内容 |
| --- | --- |
| `00-identity.md` | AI 身份与角色定义 |
| `10-communication.md` | 沟通与回复风格 |
| `15-project-rules.md` | 项目规则加载约定（AGENTS.md / CLAUDE.md），详见 [记忆与项目规则](https://aicode.murk.top/md/guide/memory.md) |
| `20-coding-discipline.md` | 编码纪律 |
| `30-comments.md` | 代码注释规范 |
| `40-approach.md` | 工作方式与流程 |
| `50-safety.md` | 安全与可信边界 |
| `60-tools-and-paths.md` | 工具说明与路径约定 |
| `70-skills-and-mcp.md` | 技能与 MCP 说明 |
| `99-runtime-context.md` | 运行期上下文：技能、子代理、记忆、项目规则、工作区与当前时间（用变量承载） |
| `agent/plan-mode.md` | PLAN 模式提醒（按需注入） |
| `agent/auto-mode.md` | AUTO 模式提醒（按需注入） |
| `agent/subagent-base.md` | 子代理基础运行规范（按需注入） |
| `agent/subagent-context.md` | 子代理运行期上下文：身份、工作区与时间（按需注入） |
| `agent/compact-summary.md` | 长对话上下文压缩的提示词 |
| `agent/title-generator.md` | 会话标题生成的提示词 |
| `agent/commit-generator.md` | 根据 Git 差异生成 Conventional Commits 提交信息的提示词 |
| `agent/goal.md` | 目标自主循环：持续推进、完成审计与受阻判断的提示词 |
| `agent/init.md` | `/init` 命令的指令正文（分析代码库并生成/改进 `AGENTS.md`），可在对话输入框用 `/init` 触发 |

## 恢复默认

删掉 `~/.muse/prompts.custom/` 下对应的文件，那个片段就恢复默认版本；删掉整个 `prompts.custom/` 目录则全部恢复（`.no-builtin` 一并删除后内置提示词重新启用）。

## 注意

- 旧版把 `80-plan-mode.md`、`81-auto-mode.md`、`90-subagent-base.md` 放在 `prompts/` 顶层，**v1.12.0 起**已移到 `prompts/agent/` 且去掉编号；对应的自定义覆盖请改用 `prompts.custom/agent/plan-mode.md` 等路径。
- `60-tools-and-paths.md` 这类片段会随工具变更而更新。如果你覆盖了它，App 升级后不会自动获得新版工具说明，AI 看到的工具定义可能和实际不一致。需要更新时手动同步，或删掉你的自定义版本让默认版本重新生效。