写技术博客这事儿，最怕什么？最怕把教程写成“打开App→点击设置→搞定”这种流水账，读者照着做却满屏报错，卡在某个莫名其妙的环节里。写石墨AI相关的内容尤其如此，稍微一个参数没写清楚，或者路径差了一个斜杠，整个操作就崩了。

要解决这个问题，关键是把那些被忽略的真实细节都塞进文章里。比如，别说什么“可能遇到报错”，直接把终端里那行红字贴出来——包括行号和堆栈最顶端的提示。在提示词里直接嵌入错误原文，格式就写成：“当执行【xxx命令】时，终端返回：【Error: Cannot find module 'fs-extra'】，请检查依赖安装路径。” 所有“常见问题”“一般情况”这类模糊表述统统删掉，每句指令都必须绑定一个可验证的结果。比如，写清楚“执行后应看到package.json中间出现fs-extra条目”，而不是只显示“added 1 package”。

用具体错误替代抽象描述

第一步：复现你截图里那个报错——不是写“可能遇到报错”，而是把终端里实际弹出的红色文字完整贴进来，包括行号和堆栈最顶那行。

第二步：在提示词里直接嵌入这个错误原文，格式为：“当执行【xxx命令】时，终端返回：【Error: Cannot find module "fs-extra'】，请检查依赖安装路径。”

第三步：删掉所有“常见问题”“一般情况”“建议尝试”这类模糊表述，每句指令必须绑定一个可验证结果，比如“执行后应看到package.json中间出现fs-extra条目，而非仅显示‘added 1 package’”。

绑定真实操作对象

方法一：用真实文件名代替占位符

把“将配置文件放入指定目录”改成“把_config.yaml复制到~/shimo-ai-plugins/v0.3.1/contexts/下，注意v0.3.1是当前插件版本号，不是你的本地路径名”。

方法二：截图标注不可跳过的界面元素

在描述按钮位置时，不写“点击右上角图标”，而写“点击编辑区右上角第三个图标（图标为⚡+圆圈，非⚙️或?）”。

【误点⚙️会进入全局设置，导致后续AI指令无法加载上下文】

暴露失败路径

写清楚哪一步做错会导致什么后果，而不是只说“正确操作是……”。

例如：如果跳过npm install --no-sa ve @shimo/ai-core这步，后续调用shimo-ai init时会卡在Loading model…状态超过90秒，且无任何错误提示——此时需强制终止进程并删除node_modules/.cache/shimo-ai目录才能重试。

再如：在石墨文档内粘贴提示词时，若开头多了一个空行，AI会将第一行识别为标题而非指令，直接忽略全部后续内容。

参数值带量纲和边界

不要写“调整temperature值”，要写：“temperature设为0.3（0.1～0.5区间内效果稳定；超过0.7时生成内容开始出现事实性错误，如将‘石墨AI 2.4.0’误标为‘2.5.0’）”。

max_tokens不能只说“合理设置”，而要给出实测数据：“处理1200字技术文档时，max_tokens=512可完整输出摘要；若设为256，末尾3段必被截断，且不会提示截断警告”。