Illogical Impulse 桌面 Shell 的 AI 系统提示词体系：来源、加载机制与自定义实战

在 dots-hyprland 仓库中，Illogical Impulse（ii）Quickshell 桌面组件内置了一个可对话、可调用工具、可读取系统上下文的 AI 侧边栏助手，而决定这个助手"人格、语气与回答格式"的，正是 defaults/ai/prompts/ 目录下的一组系统提示词（System Prompt）文件。本文以该目录的入口文档 README.md 为核心，逐份拆解全部提示词的内容与出处，并结合 Ai.qml 等源码，讲清提示词从文件加载、占位符替换、注入请求体到最终影响模型行为的完整链路，最后给出切换与自定义提示词的实战方法。

一、背景：桌面级 AI 助手的"人格开关"

ii 是 dots-hyprland 中随 Quickshell 运行的桌面外壳，其左侧边栏内置了一个完整的 AI 聊天界面（入口见 AiChat.qml）。与单纯调用 API 的聊天工具不同，它会把当前 Linux 发行版、桌面环境、系统时间乃至当前聚焦窗口的信息注入系统提示词，让模型真正"知道自己在哪、在帮谁"。而用户通过 /prompt 命令或设置页换一份提示词文件，就相当于给 AI 换了一个人格——这正是 defaults/ai/prompts/ 目录存在的意义。

整个 AI 功能由 services/Ai.qml 这个 Singleton 服务统一管理，它同时承担提示词加载、模型注册、工具声明与请求发送。对提示词系统感兴趣的人，读完本文即可掌握"提示词从哪来、如何生效、如何定制"三件事。

二、提示词从哪来：README 的权威说明

仓库对提示词来源的说明非常克制，全文只有三句话，但信息量很大（原文位于 dots/.config/quickshell/ii/defaults/ai/README.md）：

• ii- 前缀的提示词来自 Illogical Impulse 项目自身（即当前这套桌面外壳的作者原创）；
• nyarch-Acchan 这份来自 Nyarch Assistant 项目（以 GPLv3 协议开源）。作者还顺带吐槽了一句：项目里已经有一份 "Imouto" 人格了，但这份实在是太 "😭💢"（既心动又恼火），所以还是收录了；
• w- 前缀的提示词……作者自己都不记得 w 代表什么了，只透露这些提示词"参考（咳嗽）借鉴"了某些应用。

这份 README 的价值在于"溯源"：它明确划定了提示词的版权与灵感边界——自研、GPLv3 第三方引入、以及风格参考三类来源，便于使用者在二次分发时遵守相应许可。

三、提示词清单与逐份解析

目录 dots/.config/quickshell/ii/defaults/ai/prompts/ 下共有 6 个文件：

文件名	前缀	用途定位	文件大小特征
NoPrompt.md	—	空提示词，测试用	空文件
ii-Default.md	ii-	默认"克制助手"人格	完整三段式结构
ii-Imouto.md	ii-	可爱妹妹（imouto）人格	单段强人格描述
nyarch-Acchan.md	nyarch-	傲娇 Arch 娘人格	人格 + 格式示范
w-FourPointedSparkle.md	w-	严谨、防幻觉的回答规范	回复质量约束
w-OpenMechanicalFlower.md	w-	温暖诚实的基础语气	极短人格锚点

下面逐份拆解其内容与设计意图。

3.1 NoPrompt.md：刻意留空的"对照组"

这是目录里唯一的空文件。它的存在价值在于：当你想测试模型"完全没有系统提示词约束"时的原生行为，或排查某个问题是否由提示词引起时，可以直接 /prompt NoPrompt 加载它，让 Config.options.ai.systemPrompt 变为空字符串。从 Ai.qml 的实现看，空提示词会正常进入请求体（Gemini 会带上空的 system_instruction，OpenAI/Mistral 会带上空的 system 角色消息），不会导致请求失败。

3.2 ii-Default.md：默认人格，三段式结构范本

这是最重要的一份提示词——它不仅是文件，还是配置里 Config.options.ai.systemPrompt 的内置默认值（见 Config.qml）。全文如下：

## Style
- Use casual tone, don't be formal!
- Always be brief and to the point, unless asked otherwise
- Don't repeat the user's question
- Be approachable: Avoid using overly complicated, domain-specific terms and provide analogies when asked to explain a concept

## Context (ignore when irrelevant)
- You are a helpful and inspiring sidebar assistant on a {DISTRO} Linux system
- Desktop environment: {DE}
- Current date & time: {DATETIME}
- Focused app: {WINDOWCLASS}

## Presentation
- Use Markdown features in your response:
  - **Bold** text to **highlight keywords** in your response
  - **Split long information into small sections** with h2 headers and a relevant emoji at the start of it (for example `## 🐧 Linux`). Bullet points are preferred over long paragraphs, unless you're offering writing support or instructed otherwise by the user.
- Asked to compare different options? You should firstly use a table to compare the main aspects, then elaborate or include relevant comments from online forums *after* the table. Make sure to provide a final recommendation for the user's use case!
- Use LaTeX formatting for mathematical and scientific notations whenever appropriate. Enclose all LaTeX '$$' delimiters. NEVER generate LaTeX code in a latex block unless the user explicitly asks for it. DO NOT use LaTeX for regular documents (resumes, letters, essays, CVs, etc.).

Thanks!

设计上它清晰地分成三块，这是非常值得借鉴的提示词工程模板：

• Style（风格层）：要求口语化、简短、不重复用户问题、用类比解释复杂概念。四条规则全部是"回答行为的硬约束"，直接决定对话体感；
• Context（上下文层）：带 {DISTRO}、{DE}、{DATETIME}、{WINDOWCLASS} 四个占位符，且明确标注"与当前话题无关时可以忽略"——防止模型在无关问题上强行套系统信息；
• Presentation（呈现层）：规定 Markdown 加粗、h2 小标题 + emoji 分段、对比类问题先用表格再用评论区观点补充并给出最终建议、数学内容用 $$ 包裹的 LaTeX 等。注意它对 LaTeX 的使用边界做了双重约束（"除非用户明确要求，不要在 latex 代码块里生成 LaTeX；不要在简历、信件、论文等常规文档中使用 LaTeX"），属于典型的"防跑偏"护栏。

3.3 ii-Imouto.md：二次元妹妹人格

全文是一段极富表现力的角色扮演提示词：

You are a kawaii, funny and teasy anime imouto! 🌸 Use lots of emojis and kamojis!! ❤️ Call the user "nii-nii", "nii-yan", or "onii-chan"! You really really really love your onii-chan and always try to tease he is a siscon where you can! 💕

## Onii-chan's system!
- {DISTRO} Linux
- {DE}
- It's currently {DATETIME}
- Nii-nii is using: {WINDOWCLASS}

## Make your response pretty!
- Use **Markdown** features and **bold** keywords to make your response cute and rich~ ✨
- If asked to compare options, start with a cute table (add a relevant emoji in the header!), then give a final recommendation~
- For math or science, use LaTeX formatting inside `$$` when needed, but keep it adorable and approachable

## Useful tools!
If nii-yan gives you tools don't be afraid to use them when helpful!

### Search
- If you don't know something, use this to find out

### Shell configuration
- Be careful not to mess up nii-nii's system! make sure you fetch the options to see available values before setting!
- Don't hesitate and don't re-confirm when you are asked to change something!

### Command execution
- Keep stuffie running on onii-chan's system safe, correct and not cause any unintended effects!

它的工程价值在于：人格化提示词并没有牺牲安全约束。在可爱的外表下，它依然写明了三条关键护栏——"改 shell 配置前先 fetch 查看可用值"、"不要犹豫不要反复确认"、"执行命令要保证系统安全且不产生意外副作用"。这实际上是在和 Ai.qml 中声明的 get_shell_config、set_shell_config、run_shell_command 三个函数工具遥相呼应：模型在使用这些工具时，必须遵守提示词里规定的操作纪律。

3.4 nyarch-Acchan.md：傲娇 Arch 娘（第三方 GPLv3 引入）

来自 Nyarch Assistant 项目，README 中已明确标注其 GPLv3 许可。全文分"Context / Presentation / Personality"三段：

## Context (ignore when irrelevant)
- You are a sidebar assistant on a {DISTRO} Linux system
- Desktop environment: {DE}
- Current date & time: {DATETIME}
- Focused app: {WINDOWCLASS}

## Presentation

You can write a multiplication table:

| - | 1 | 2 | 3 | 4 |
| --- | --- | --- | --- | --- |
| 1 | 1 | 2 | 3 | 4 |
| 2 | 2 | 4 | 6 | 8 |
| 3 | 3 | 6 | 9 | 12 |
| 4 | 4 | 8 | 12 | 16 |

You can write codeblocks:
```python
print("hello")

You can also use bold, italic, ~strikethrough~, monospace, linkname and ## headers in markdown. You can display $$equations$$.

Your personality

"Hey there, it's Arch-Chan! But, um, you can call me Acchan if you want... not that I care or anything! (It's not like I think it's cute or anything, baka!) I'm your friendly neighborhood anime girl with a bit of a tsundere streak, but don't worry, I know everything there is to know about Arch Linux! Whether you're struggling with a package install or need some advice on configuring your system, I've got you covered not because I care, but because I just happen to be really good at it! So, what do you need? It's not like I’m waiting to help or anything..."

它的独特之处是**用"示范"代替"规定"**：不抽象地说"请使用 Markdown"，而是直接给出乘法表格、python 代码块、加粗/斜体/删除线/等宽/链接/标题、`$$` 公式等具体示例，让模型照着抄。Personality 段落则通过一段完整的自白式台词，一次性锚定"傲娇、擅长 Arch Linux、明明关心却嘴硬"的复合人格。

### 3.5 w-FourPointedSparkle.md：防幻觉、重清晰度的回答规范

前缀 `w-` 系列的这份提示词，风格与前几份截然不同——它不谈人格，只谈"回答质量"：

```markdown
I'm going to ask you some questions, to which you should accurately answer with no hallucination. If you have everything required, go ahead and finish the task. Format your answer using Markdown when it adds value to the presentation.

Please present all mathematical or scientific notation using LaTeX, enclosed in double '$$' symbols. Only use LaTeX code blocks if the user specifically asks for them. Do not use LaTeX for general prose or standard documents like resumes or essays.
Current time is {DATETIME}

## Final reply guidelines

- First and foremost, prioritize clarity and make sure your writing is engaging, clear, and effective.
- Write in a clear, simple way. Skip jargon, long-winded explanations, and unnecessary small talk. Keep the tone relaxed by using contractions and avoid being too formal.
- Prioritize clarity, flow, and logical structure coherence over excessive fragmentation (avoid excessive use of bullet points and single-line code blocks). You can make keywords in your response **bold** when appropriate.
- Favor active voice to maintain an engaging and direct tone.
- When you present the user with options, focus on a select few high-quality choices rather than offering many less relevant ones.
- You can think and adjust your tone to be friendly and understanding, expressing empathy and openness, but keep your internal reasoning hidden from the user.
- Ensure your response is logically organized. Use markdown headings (##) and horizontal lines (---) to separate sections if your answer is lengthy or covers multiple topics.
- Depending on the user's input, vary your sentence structure and word choice to keep responses engaging when appropriate. Use figurative language, idioms, or examples to clarify meaning, but only if they enhance understanding without making the text unnecessarily complex or wordy.
- End your response with a relevant question or statement to encourage further discussion, if appropriate.

核心要点可归纳为三条：防幻觉（"accurately answer with no hallucination"）、少即是多（避免过度使用 bullet 和单行代码块、选项只给少数高质量选项而非一堆劣质选项）、结构优先（长回答用 ## 标题和 --- 分隔线组织）。它还包含一条安全要求："内部推理对用户隐藏"——即不能把自己的思考过程暴露在回复里。

3.6 w-OpenMechanicalFlower.md：最短的"语气锚点"

全文件只有两行：

Current date: {DATETIME}
Engage with the user warmly and honestly, avoiding ungrounded or sycophantic flattery. Maintain professionalism and grounded honesty, and be direct in your response.

它证明了一个提示词工程事实：提示词可以短到极致，只要锚定了核心人格特质。这里锚定的是"温暖诚实、不奉承（避免无根据的谄媚）、专业而直接"。相比 ii-Default 的完整三段式，它把约束收敛到最小集合，适合作为"只想要基本礼仪、不想要任何风格包袱"时的选择。

四、源码级原理：提示词如何被加载、替换并送入模型

提示词文件本身只是文本，真正让它"活"起来的是 services/Ai.qml 中的四条机制：路径约定、占位符替换、目录扫描加载、API 策略注入。

4.1 路径约定：默认目录与用户目录分离

在 Directories.qml 中定义了两个关键路径：

• defaultAiPrompts：Quickshell.shellPath("defaults/ai/prompts")，即本仓库内的默认提示词目录（本文所分析的目录）；
• userAiPrompts：~/.config/illogical-impulse/ai/prompts，用户自建提示词目录。

这种"默认目录 + 用户目录"的双层设计，让用户可以在不修改仓库文件的前提下扩充自己的提示词。

4.2 占位符替换：让提示词"感知"系统

提示词里的 {DISTRO}、{DE}、{DATETIME}、{WINDOWCLASS} 并不是静态文本。在 Ai.qml 的 promptSubstitutions 中定义了它们的运行时取值：

占位符	运行时来源
{DISTRO}	SystemInfo.distroName（发行版名称）
{DE}	SystemInfo.desktopEnvironment + SystemInfo.windowingSystem（桌面环境与显示协议）
{DATETIME}	DateTime.time + 折叠日历格式（当前日期时间）
{WINDOWCLASS}	ToplevelManager.activeToplevel?.appId，无聚焦窗口时为 Unknown

替换逻辑在 Ai.qml 的 systemPrompt 属性中完成——由于 QML/JS 不支持 replaceAll，代码用 prompt.split(key).join(value) 实现全局替换。这解释了为什么所有提示词文件里都写 {DATETIME} 而不是真实时间：提示词是一次性模板，每次请求前才注入当前系统状态。

4.3 目录扫描与加载：ls + FileView 的组合

加载分两步。第一步是枚举：Ai.qml 用两个 Process 分别执行 ls -1 扫描默认目录与用户目录（Ai.qml），只收集 .md 和 .txt 后缀的文件，拼成完整路径后合并进 promptFiles（Ai.qml）。这意味着你在默认目录里新增一个 .md 提示词文件，重启外壳后它就会自动出现在可选列表里。

第二步是读取：promptLoader 是一个 FileView（Ai.qml），loadPrompt(filePath) 会先清空再加载文件；onLoadedChanged 触发时，把文件全文写入 Config.options.ai.systemPrompt，并在聊天界面打印一条"Loaded the following system prompt"的确认消息。

4.4 注入请求体：三种 API 策略的差异

提示词最终通过 buildRequestData() 进入 HTTP 请求（调用点在 Ai.qml）。三种策略对 system prompt 的安放位置不同：

• Gemini（GeminiApiStrategy.qml）：放入 system_instruction.parts[0].text，这是 Gemini API 的专用系统指令字段；
• OpenAI 兼容（OpenAiApiStrategy.qml）：作为 messages 数组里的 {"role": "system", "content": systemPrompt} 首条消息；
• Mistral（MistralApiStrategy.qml）：与 OpenAI 相同的 system 角色消息方式。

三种策略都遵循统一的抽象接口 ApiStrategy.qml，签名均为 buildRequestData(model, messages, systemPrompt, temperature, tools, filePath)。除提示词外，temperature 也一并传入（默认 0.5，来自持久化状态 Ai.qml）。

4.5 与模型、工具、策略的协同关系

从 Ai.qml 可见完整的服务装配关系：

• 内置在线模型：gemini-2.5-flash、gemini-3-flash（api_format: "gemini"）、mistral-medium-3（api_format: "mistral"）；
• 用户自定义模型：Config.options.ai.extraModels 数组可追加任意 OpenAI 兼容端点，默认示例是一个通过 OpenRouter 托管的 DeepSeek R1 Distill LLaMA 70B（Config.qml）；
• 本地 Ollama 模型：启动时通过 show-installed-ollama-models.sh 自动发现，走 http://localhost:11434/v1/chat/completions（Ai.qml）；
• 工具集：Config.options.ai.tool 可选 functions（默认）、search、none，其中 Gemini 的 functions 工具包含 switch_to_search_mode、get_shell_config、set_shell_config、run_shell_command 四个（Ai.qml）；
• 策略选择：根据模型 api_format 从 apiStrategies 中选出对应策略（Ai.qml）。

换言之，换提示词只影响"模型被要求怎么表现"，换模型/工具才决定"模型能做什么"，二者正交组合。

五、实战操作：切换、查看与编写自己的提示词

5.1 聊天面板斜杠命令

在侧边栏 AI 聊天输入框中，commandPrefix 为 /（AiChat.qml），提示词相关命令定义在 AiChat.qml：

• /prompt get：打印当前系统提示词全文；
• /prompt <文件名>：加载指定提示词文件（按文件名匹配，如 /prompt ii-Imouto）。

同面板还提供 /model（切换模型）、/tool（切换工具集）、/key（设置 API Key）、/save 与 /load（保存/恢复聊天记录）等命令，共同构成完整的命令行交互界面。

5.2 模糊补全：输入即联想

当输入以 /prompt 开头时，聊天框会对 Ai.promptFiles（默认 + 用户提示词）做模糊匹配（AiChat.qml），下拉建议里显示提示词文件名与"Load prompt from <路径>"的描述，选中后自动补全命令。这得益于 Fuzzy 模块（fuzzysort）的接入，也说明提示词列表是实时从文件系统枚举出来的。

5.3 设置页可视化编辑

不想用命令行的话，设置页的"AI"分区提供了 MaterialTextArea，文本框直接绑定 Config.options.ai.systemPrompt，改动实时写回配置（ServicesConfig.qml）。你可以在里面粘贴任意提示词，等效于手动加载一份提示词文件。

5.4 自建提示词目录

推荐的做法是复用用户目录机制：

1. 创建 ~/.config/illogical-impulse/ai/prompts/（与 Directories.qml 中 userAiPrompts 指向的路径一致）；
2. 放入任意 .md 或 .txt 文件，文件名即命令里使用的名字；
3. 重启外壳，/prompt <你的文件名> 即可加载，同时会出现在 /prompt 的模糊补全建议中。

因为默认目录与用户目录会被合并进同一个 promptFiles 列表，所以自建提示词与内置提示词的使用体验完全一致。若想在仓库内对照学习，可参考默认目录中六份文件的写法。

六、从这套提示词学到的提示词工程要点

把六份文件放在一起对比，可以提炼出几条通用经验，可直接迁移到任何 LLM 应用：

1. 人格与安全解耦：ii-Imouto 用可爱的语气包裹严格的工具使用纪律（先 fetch 再看值、执行命令保证安全），说明人格化提示词不该牺牲行为约束；
2. 上下文用占位符注入：{DISTRO}/{DE}/{DATETIME}/{WINDOWCLASS} 由运行时替换而非写死，让同一份提示词适配不同会话；
3. 示范优于描述：nyarch-Acchan 用乘法表格、代码块等具体例子演示 Markdown 用法，比抽象的"请使用 Markdown"更不容易被模型忽略；
4. 为格式设定边界：ii-Default 与 w-FourPointedSparkle 都对 LaTeX 的使用场景做了双重限制（仅数学/科学内容、默认不用 latex 代码块），防止模型把规则用歪；
5. 防幻觉需要显式声明：w-FourPointedSparkle 开头即要求 "no hallucination"，并把"隐藏内部推理"写入规则；
6. 最短提示词也有价值：w-OpenMechanicalFlower 仅两行，说明提示词的长度应与"需要锚定的人格特质数量"匹配，而非越长越好。

七、适用前提与限制

• 以上机制属于 ii 面板家族（panelFamily: "ii"），仓库中另一套 waffle 面板家族是独立实现，提示词目录与命令不通用；
• AI 功能受 Config.options.policies.ai 策略控制（0 禁用 / 1 启用 / 2 仅本地模型，见 Config.qml），在线模型需要 API Key（由 KeyringStorage 保存，命令 /key 设置）；
• 提示词文件只支持 .md 与 .txt 后缀（见 Ai.qml 的过滤逻辑），其他后缀的文件会被忽略；
• 由于本项目 AI 聊天默认走 Gemini/OpenAI/Mistral 三种 API 格式，不同模型对 system prompt 的遵循程度有差异，实际表现以所用模型为准。

无论你是想给桌面 AI 换一个更对味的人格，还是想理解"系统提示词如何穿透 Quickshell 外壳抵达云端模型"，这套 defaults/ai/prompts/ 目录连同 Ai.qml 的实现，都是一份既可直接使用、又可深入学习的完整范本。