通用问题

排查顺序

优先检查版本、配置路径、环境变量、网络代理、模型名和 API 返回内容。

为什么同一个模型在不同工具里表现不一样？

模型只是其中一部分。工具权限、上下文注入、压缩策略、MCP、系统提示词和文件读取方式都会影响结果。比较模型时要尽量固定这些变量。

为什么 Agent 改错目录？

最常见原因是启动位置不是真实项目根目录。开始前执行：

pwd
git status --short
rg --files -g package.json -g pyproject.toml -g Cargo.toml

如果当前目录只是会话容器，先切到真实仓库。

什么时候需要浏览器视觉检查？

只要改了前端布局、文档首页、组件样式、移动端导航或可视化输出，就应该截图检查。代码通过构建不代表文字不溢出、按钮不遮挡、颜色对比足够。

什么时候应该写成 Skill？

当一个流程会重复三次以上，且包含固定输入、固定检查、固定输出格式，就值得沉淀为 Skill。比如论文分析、PPT 生成、浏览器视觉 QA、服务器端口排查。

为什么路由检查偶尔出现 Content 数据库错误？

开发服务、typecheck 和 build 都可能触发 Nuxt Content 处理。不要在同一个工作区里并行跑 pnpm typecheck、pnpm build 和 pnpm check:routes。如果开发服务已经报 no such table: _content_docs，先停止 dev server，删除 .data/content/contents.sqlite，再重新启动 pnpm dev --host 127.0.0.1 --port 3000。

怎么确认复刻页没有被改坏？

检查两件事：/codex/model 页面能正常渲染，/raw/codex/model.md 和 content/3.codex/5.model.md 完全一致。当前项目的 pnpm check:routes 已经包含这个一致性检查。