CodePapr 教程

设计要点

• 本地优先：文件和命令在工作区执行
• 单一 Runtime：Agent、Session、ToolRegistry、Provider 共用一套语义
• 缓存优先：稳定内容前置，易变内容后置
• 结构化改文件：Search/Replace Diff，先校验再写入

支持的 LLM Provider

环境要求

标准安装

# 克隆仓库
npm install
npm run build

桌面端构建（cargo check / npm run debug / release / publish）从 crates.io 拉取 tree-sitter 及各语言 grammar 的最新兼容版本，不再依赖 .cargo-vendor/* 子模块。npm run build 已经包含 codepapr-server 宿主进程的编译，跑完这两步本机就有一个可用的宿主二进制；桌面端启动时会把它当 Tauri externalBin sidecar 拉起。

安装验收

npm run verify

通过这一步，说明当前机器至少满足：Node 依赖安装正确、workspace 构建正常（含 codepapr-server 编译）、workspace 测试正常、Tauri cargo check 正常。

支持平台

两个平台共用同一套 Rust 后端与前端代码，发布流程会同时输出 dmg / msi 安装包。

外部依赖

根据你要执行的操作，可能还需要：

• 可用的模型 API key（DeepSeek / OpenAI / Claude 或本地兼容端点）
• Chrome 或 Chromium 兼容浏览器（用于浏览器交互和截图）
• VS Code（可选，用于工作区任务和调试配置）

三种启动方式

配置存放位置

Provider 模式

DeepSeek 接口参考地址

# OpenAI 格式（DeepSeek provider 默认使用）
https://api.deepseek.com/v1

CodePapr 的 DeepSeek provider 固定使用 OpenAI 兼容的 https://api.deepseek.com/v1。如果你想用 Anthropic 协议接 DeepSeek，可在 provider 中选择 Claude，并把 baseURL 设为 DeepSeek 提供的 Anthropic 兼容端点。

环境变量回退顺序

桌面端 provider 兼容层会按以下顺序读取 API key：

1. DEEPSEEK_API_KEY
2. OPENAI_API_KEY
3. ANTHROPIC_API_KEY

应用级设置项

快速模型路由

三步启动

1. 设置里填 API key、provider、模型
2. 选项目文件夹
3. Ask / Plan / Agent / App

最短路径

npm install
npm run build
npm run debug

首次使用流程

1. 打开设置，填写 provider、model 和 API key
2. 选择项目文件夹
3. 在 Ask、Plan、Agent、App 中选择当前任务模式
4. 输入任务描述，让代理执行或分析
5. 在文件树、编辑器、Git、预览面板中复核结果

使用入口

注意：Explore、Scout、Mentor 三个内置子代理均可在桌面端设置面板（Mentor Tab）启用并配置；内部代理 Verifier / Compactor 的模型档位在高级 Tab 配置（verifierModelTier / compactionModel），不经 task 工具暴露。

Ask、Plan、Agent、App 不是不同产品，而是同一套 Runtime 的四种工作方式。

Ask 分析模式

适合：解释架构、梳理模块职责、分析报错原因、先问清楚再决定是否执行。

特点：

• 只读：变更类工具（write/edit/bash/git 等）在工具注册层被直接屏蔽，从机制上杜绝误改文件
• 遇到时效性问题时，优先走只读时间/网页工具核实
• 只有你明确要求基于项目核实，它才会进入只读工具链

Plan 规划模式

适合：大改动前先出执行方案、确认影响文件和验证方式、把复杂任务拆成清晰步骤。

特点：

• 优先给出任务清单与实施方案
• 分析影响文件、执行顺序、验证方式和潜在风险
• 遇到需求歧义时，调用 question 工具向用户提问确认决策

Agent 执行模式

适合：修复 bug、实现功能、跑测试与验证、需要真正读写文件和调用工具的任务。

特点：

• 会主动搜索项目、读写文件、跑命令、做验证
• 会使用工作区工具、bash 命令执行、预览和浏览器能力
• Agent 主执行循环在 Web Worker 中运行，长任务不会阻塞界面
• bash 等长命令会在工具调用卡片中显示运行状态和日志
• 主执行默认最多连续运行 500 个内部工具轮次
• 文件改动后会异步派发后台诊断；同一失败指纹不会重复触发修复

App 应用生成模式

适合：数据探索与可视化、生成交互式图表和仪表盘、一句话将分析结果变成可交互的应用。

核心理念：

• 你的直接产出不是 Markdown 回答——而是一个完整的应用（拆分源码的 .papr 应用）
• 就像即时开发一个针对当前问题的专用工具
• 与编码 Agent 完全不同——它是"应用工厂"，不是"写代码的人"

工作流程：

1. 探索数据源：用 list / read / grep 理解数据结构
2. 写入应用：用 write 把 manifest.json、骨架 index.html、css/theme.css 和按职责拆开的 js/*.js 写到 .CodePapr/apps/<appId>/
3. 打开结果：调用 app_render({ appId }) 挂到右侧"应用"面板（不写文件）

应用规范：

• 多文件拆分：index.html 只做骨架，样式进 css/theme.css，逻辑按职责拆进 js/*.js（原生 ES module，不要构建链）
• 通过 CDN 引用图表库（D3、ECharts、Mermaid、MapLibre、Leaflet、Three.js 等）
• 在沙箱 iframe 中运行（sandbox="allow-scripts allow-same-origin"）
• 可使用 Papr SDK（window.papr）调用 Agent、存储、HTTP、文件系统
• 看板/画布等需要编程 Agent 推送的应用，在 manifest 声明 inbox 并用 papr.events.on(channel, cb) 订阅——契约会进入会话上下文「已启用插件」，Agent 模式用 app_publish 按 example 推送（不要 app_list）；历史经 papr.db.get('inbox:<channel>') 回放。自刷新小组件不要声明 inbox。
• papr.agent.run 采用 300 秒空闲超时：只要 Agent 持续产出进度事件（流式输出/工具调用）就可运行任意时长，仅连续 300 秒无事件才超时；工具轮数受 maxToolRounds 限制（默认/上限 50，搜索调用计入总轮数）
• appId 必须是 kebab-case；改文件后再次 app_render({ appId }) 刷新——支持迭代改进

会话隔离：

• App 与编码模式（Ask/Plan/Agent）会话级隔离--一旦选定 App，该会话锁定为 App 🔒，不可切到其他模式
• 编码会话中 App 选项被隐藏--已开始编码的会话不能切到 App
• Ask / Plan / Agent 之间可以自由切换，无需新建会话
• App ↔ 编码模式互切换 -> 新建会话

模型策略：始终使用主模型以保证应用生成质量。

应用管理：右侧面板的"应用"Tab 显示所有已注册的 .papr App。绿/红圆点指示运行状态。底部工具栏：▶ 启动 / 打开 / ■ 停止 / 🗑 删除。LLM 可通过 app_list、app_start、app_stop、app_delete 工具管理应用生命周期。完整开发与插件规范详见 App 模式与插件生成 章节。

权限模型：App 用 local（none / read / write）× network（true / false）两轴声明访问档。设置 → App Tab 可收窄全局默认与逐 app 覆盖；保存后正在运行的后端会按新沙箱重启。

App 模式典型场景

• 数据库分析："分析这个 SQLite 的表结构，生成一个 Database Explorer"
• 人物关系图："把人物关系做成 D3 力导向图"
• 股票仪表盘："生成带有 K 线图和龙虎榜的 dashboard"
• 文件分析："分析 paper-map——引用网络、作者关系、Topic Cluster"
• 地域可视化："分析唐朝宰相的地域分布，做成可缩放地图"

如何给出有效任务

CodePapr 的实际表现很依赖任务描述质量。最有效的提示词通常包含：

• 目标是什么
• 改动范围在哪里
• 参考实现在哪
• 不能动什么
• 验证标准是什么

推荐写法

修复 packages/@codepapr/ui 里预览关闭后后台进程未停止的问题。
先找当前预览会话和后台进程的绑定逻辑，再做最小修改。
改完后至少跑受影响范围的验证，如果没有窄验证，再说明原因。

不够好的写法

帮我修一下预览。

界面结构

• 左侧：会话列表和快捷入口
• 中间：聊天区，展示消息、工具调用、状态和执行总结
• 右侧：文件树与代码预览
• 辅助区域：Git 面板、后台进程、网页预览

桌面端完整能力

代码审查面板

顶部 AgentOps 工具栏点击 审查 可打开 Code Review 面板：

• 默认对比 HEAD~1..HEAD 的 diff
• 左侧文件列表展示新增/修改/删除/重命名
• Monaco diff 编辑器展示 original / modified 两侧
• 点击行号边栏可在任意一侧添加行级评论
• 评论可标记为已解决 / 未解决
• 可设置整体审批状态：待审查 / 已批准 / 需修改 / 已评论

对话轮次导航

对话区域右侧有一个紧凑的轮次指示条，每条横线对应一个用户消息：

• 悬停指示条 → 自动展开面板，列出所有对话轮次（#1 编号 + 用户输入首句）
• 当前可视轮次在指示条和面板中同步高亮
• 点击任意轮 → 对话平滑滚动到对应消息位置
• 鼠标移开面板或指示条 → 面板自动关闭（200ms 延迟防误关）

全局搜索

顶部工具栏搜索框，支持对话和文件搜索，通过 对话 | 文件 双 Tab 切换：

• 对话 Tab：搜索当前会话消息，可按角色过滤（全部 / 你 / AI），↑↓ 选择 Enter 跳转
• 文件 Tab — 内容模式：搜索工作区文件内部文本，结果展示文件路径 + 行号 + 匹配行
• 文件 Tab — 文件名模式：搜索文件路径和名称
• 文件结果点击 → 打开文件并跳转到对应行
• 搜索面板视口居中弹出，300ms 防抖，仅文件 Tab 激活时才触发后端搜索

Toast 通知

桌面端使用非阻塞 Toast 替代 alert：

• 四色：info / success / warning / error
• 默认 4.5 秒自动消失，error 默认 8 秒
• 最多同时显示 5 条，超出时丢弃最早的

外部路径权限

当 Agent 请求读取或列出项目外的绝对路径时，桌面端会弹出权限对话框：

• 拒绝：阻断此次访问
• 允许此文件：仅放行该文件
• 允许此文件夹：放行该目录及其子内容

授权结果保存在白名单中，后续同路径不再弹窗。写入、编辑、命令执行仍限制在工作区内。

什么时候优先用桌面端

• 你在做多轮修复或重构
• 你需要一边看文件树一边让代理工作
• 你需要 Git diff、页面预览或页面自动化
• 你希望把会话、文件和验证收拢在一个界面里

Git 集成

• Git 面板：展示 staged/unstaged diff、最近提交历史、分支创建/切换、本地提交、安全擦除本地改动
• 8 个 Agent Git 工具：status、diff、history、branch_checkout、stage、commit、restore、reset（全部通过内置 libgit2 Tauri 命令，不依赖系统 git）
• 自动初始化：如果当前工作区还没有 Git 仓库，面板可直接初始化（通过内置 libgit2，无需系统 Git）

对话重置（Shadow Git 快照）

每条用户消息进入对话历史之前，CodePapr 会通过独立的 Shadow Git 仓库（.CodePapr/git/，基于 libgit2 — 无需系统 Git CLI）抓取代码快照：

• IgnoreResolver 扫描工作区文件树，遵守 .gitignore 并自动排除 node_modules/、dist/、.next/、大文件（>100MB）等
• 通过 index.add_path 逐文件添加，提交为 checkpoint #N · "消息预览"

当你需要回退时：

• Hover 任意用户消息，点击"重置到此点"
• 恢复计划预览：系统先计算哪些文件会变更 — 展示恢复/删除/不变的文件数量，先预览再执行
• 执行：确认后系统回退到快照 checkout
• 自动创建备份引用 refs/codepapr-backup-before-reset，可随时撤销
• 消息列表同步截断，后续对话全部移除

Agent 注册了 全面的工具集，覆盖文件操作、ProjectGraph 分析、Git、预览、浏览器、Shell、LSP 等全部本地开发场景。以下是按能力分组的关键工具。

graph — 项目理解核心

统一的项目语义图工具，通过 action 参数选择操作。同时返回目录树、代码结构骨架和文件/符号关系图，是所有符号查找、依赖分析、影响分析的基础。

文件操作

LSP 语言智能

命令执行

Git 操作

浏览器与预览

应用渲染

网络工具

其他工具

外部路径权限

桌面端对项目外绝对路径的 read / list 操作会触发 PermissionDialog 弹窗授权；写入仍限制在工作区内。根目录直属文件选择「允许此文件夹」时会自动降级为仅授权该文件本身，避免一次点击授予整个文件系统根。

文件大小限制

单次 read / write / edit / patch 操作的上限为 20MB，可覆盖大多数源码和二进制资源文件，但大文件会显著增加 token 消耗。

实验性功能，默认关闭：需在 设置 → 通用 → 实验性功能 中勾选「角色」，工具栏才会出现角色入口。CodePapr 支持创建、导入和管理 AI 角色，让 Agent 以特定人设与你对话。启用角色后，人设进入 Session Bootstrap（由 promptBuilders.ts / characterTypes.ts 组装），不是 core 的 promptSystem.ts，也不进入 ImmutablePrefix。

角色数据模型

每个角色包含以下字段：

角色扮演格式约定（仅「角色扮演」模式）

「角色扮演」模式下，系统提示词会明确以下格式规则，确保 TTS 能正确区分对话和动作；Ask / Plan 模式中角色一律按「编码人设」注入，不适用该格式：

创建角色

1. 点击工具栏的角色按钮（头像图标），打开角色管理面板
2. 点击 "新建角色"
3. 在基础 Tab 中填写名称、描述、个性、场景、开场白、示例对话等信息
4. 可上传头像图片（PNG/JPG）
5. 在语音 Tab 中配置语音合成（可选，详见下节）
6. 点击保存

导入角色卡（CCv3 / SillyTavern 兼容）

CodePapr 兼容 chara-card-v3 规范，可从其他工具导入角色：

1. 点击角色面板中的 "导入角色卡" 按钮
2. 选择 PNG 文件（JSON 嵌入在图片的 tEXt/iTXt chunk 中）或 JSON 文件
3. 角色信息自动解析，PNG 图片自动作为头像
4. 检查并调整导入的字段，点击保存

支持的 PNG chunk 关键字：chara、ccv3、character、character_card

导出角色卡

在角色列表中点击角色的导出按钮，角色将被导出为 PNG 角色卡。PNG 中嵌入完整的 CCv3 JSON，可在 SillyTavern 等工具中使用。语音配置中可跨机移植的参数（语速、采样步数、合并句数、播放模式、语言设置）会写入 extensions.codepapr.voice；本机参考音频与微调模型文件路径不随卡片导出。

启用/切换角色

在角色编辑页点击启用，只对当前会话生效；若面板中有未保存的修改，会先自动保存再启用。列表里点击角色名是进入编辑，不会激活。打开面板时会选中当前会话已启用的角色。空会话中切换角色时，旧角色的开场白会被替换为新角色的开场白。

角色人设放在 Session Bootstrap 中（不在系统提示词的 ImmutablePrefix 中），因此切换角色不会破坏 LLM 前缀缓存。Ask / Plan 模式下角色固定按「编码人设」注入（角色扮演格式仅在 Agent 模式生效）。新会话默认不带角色。

实验性功能，默认关闭：需在 设置 → 通用 → 实验性功能 中勾选「语音」才会显示语音控件；自动朗读还需同时开启「角色」并为已启用角色配置语音。CodePapr 集成了 GPT-SoVITS 语音克隆引擎，可在本地将角色的文字回复合成为语音。只需 3-10 秒的参考音频即可克隆一个角色的声音。

安装 GPT-SoVITS

首次使用语音功能需要安装 GPT-SoVITS。安装入口有两处：

• 点击 ChatPanel 上的 TTS 喇叭按钮，若检测到未安装，会自动弹出安装向导
• 在角色编辑面板的 Voice Tab 中触发安装

安装向导会自动完成 5 步：检查 Python → 克隆 GPT-SoVITS 仓库 → pip 安装依赖 → 下载预训练模型（约 2GB，使用 hf-mirror 源）→ 验证。

需要本机已安装 Python 3.10+。安装过程会写入 ~/.codepapr/gpt-sovits/。

为角色配置语音

1. 点击工具栏的角色头像按钮，打开角色编辑面板
2. 切换到 Voice Tab
3. 上传参考音频：
   • 时长 3-10 秒（推荐 5 秒），太短克隆不准、太长会被截断
   • 格式 WAV / MP3 / M4A / AAC，采样率 16kHz 或更高
   • 内容：清晰人声，无背景音乐、噪声、混响
4. 填写 参考文本：必须与音频内容逐字对应，否则克隆效果会很差
5. 选择 参考音频语言 和 说话语言（支持中文、粤语、英语、日语、韩语及混合模式）
6. 调整参数：
   • 语速：50% - 200%
   • 合成速度：仅 4 / 8 / 16 三档。4=极速、8=均衡、16=最高质量
   • 合并句数：1-5，一次合成合并几句一起推理，减少往返次数
   • 播放模式：默认 ws-batch，可选 streamed-pipeline / streamed-pcm / whole
7. 点击 “试听” 按钮预览效果
8. 打开 “启用语音输出” 开关（未上传参考音频或未填参考文本时开关会拒绝开启），满意后点击 保存

播放模式

角色面板 Voice Tab 提供四种播放模式，默认且推荐 WebSocket 批量流式（ws-batch）：句子先按「合并句数」（默认 3 句）合成 chunk，再经由一条持久 WebSocket 连接逐请求发送、逐条返回，首字延迟约 1-2 秒，句间衔接流畅。

其余三种：streamed-pipeline / streamed-pcm（逐句 HTTP 请求，PCM 直推播放器，兼容性最好）、whole（等整条回复生成完毕后一次性合成播放，启动最慢但整体最连贯）。

语音微调

对音质有更高要求时，可在 Voice Tab 中使用微调功能：

1. 确保参考音频和参考文本已配置并试听通过
2. 点击 “生成训练数据”：LLM 根据角色设定生成约 500 字的台词脚本，GPT-SoVITS 自动合成约 2 分钟训练语音，无需手动录音
3. 点击 “开始微调”：后台训练，通常 30-60 分钟，可关闭窗口
4. 训练完成后勾选 “使用微调模型”：音色更稳定、合成更快，合成速度可降至 4（极速档）

播放控制

• 自动朗读：启用语音的角色在 AI 回复时会自动朗读
• 重播：鼠标悬停在任意 AI 回复上，会出现“重播”按钮，可重新朗读该条内容
• 停止：取消当前 Agent 消息可中断正在进行的朗读
• 服务控制：ChatPanel 上的 TTS 喇叭按钮用于启动 GPT-SoVITS 服务或查看服务日志/状态

.CodePapr/AGENTS.md — 全局项目规则

全项目规则会注入主 Agent 和所有子代理。适合写：

• 代码风格和目录约定
• 构建、测试、发布命令
• 禁止改动的路径或行为
• 项目背景和验收标准

记忆面板 — 跨会话项目记忆

跨会话记忆就是工作区里的一个文件 .CodePapr/MEMORY.md（三节：用户偏好与约束 / 技术栈与环境约束 / 架构与业务已知事实），可读、可 diff、可进 git。它由内置记忆管家（internal 子代理）后台维护，记忆面板就是它的编辑器。分层与时间线见 上下文分层。

• 两个卡点：交付（回合结束，你说「记住 / 必须 / 不要」等线索词或本回合有验证成功的命令才跑）与压缩前（任何压缩提交前无条件跑，20s 超时）。
• 写入边界：管家只看本回合用户原话 + assistant 最终文本（压缩卡点看骨架），绝不含原始工具输出；密钥自动脱敏，注入指令 / 危险命令 / 超限内容 / 「删除过半」的洗记忆操作都会拒写。
• Agent 不写记忆：memory_write / memory_search / memory_list / memory_forget 已退役；Agent 直写 MEMORY.md 会被拦截拒绝，值得记住的事实在回答中说明即可。
• 进模型的时机：每回合直读文件渲染会话引导——文件变了下一回合立即生效（一次性前缀 miss）；面板编辑同理。

/compact — 强制压缩上下文

手动触发 v4 骨架压缩，将更早回合折叠为检查点释放 token 空间：

• 强制模式：不受 90% 触发线限制（无效缩容仍会被拒绝，不留空转检查点）
• 确定性骨架：每回合保留「用户问题 + 最终结论」两行，工具调用/结果折叠为计数注记——零 LLM；最近 5 回合逐字保留。仅当骨架仍超预算时调用一次 Compactor 做二级摘要（失败则按行截断）
• 刷新会话引导：压缩前先跑一次记忆管家（归整将被折叠的内容），再重渲染会话引导——新记忆随 epoch 立刻生效
• 使用场景：接近上下文上限或响应变慢时，压缩即可恢复流畅对话

配置入口

桌面端项目头部的"配置"入口可以：

• 创建/编辑 .CodePapr/AGENTS.md（不存在时生成默认模板）
• 创建/编辑/删除自定义子代理（.CodePapr/agents/*.md）
• 创建/编辑/启用/停用/删除 Skills（.CodePapr/skills/**/SKILL.md）

数据位置总览

Search/Replace Diff（YOLO Diff）

CodePapr 的自动修改不依赖标准 Git diff 行号。多处局部修改会优先生成 Search/Replace 块：

<<<<<<< SEARCH
文件里已经存在的旧代码
=======
替换后的新代码
>>>>>>> REPLACE

应用规则

• SEARCH 必须能在目标文件中精确匹配
• 同一个 SEARCH 如果匹配多处，会被拒绝，避免误改
• 同一次批量修改会先校验所有文件和所有块，任意块失败则不写入任何文件
• 换行会兼容 LF / CRLF
• 失败信息会回到 Agent 上下文，触发重新读取原文件和自愈重试

推荐使用场景

• 跨多个文件但每个文件只是局部修改
• 修复测试、lint、类型错误时需要保持上下文精确
• Agent 模式下需要程序可解析、可校验、可回滚的修改格式

不推荐使用场景

• 新建文件或整文件重写 → 使用写文件工具
• 只改一个很小的局部块 → 普通 patch 更直接

什么是 Skill

Skill 是主 Agent 的可复用操作手册，适合沉淀搜索策略、排错流程、发布检查、审查清单和项目固定工作方法。它不会创建独立子代理，而是作为项目级上下文供模型按需选择。

Skill 文件格式

以目录包为标准，放在 .CodePapr/skills/**/SKILL.md，目录里可放 assets/、references/、scripts/ 等资源。

---
name: search
description: 使用公开网页、官方文档和社区资料进行可验证搜索
---

# 搜索 Skill

当任务需要公开资料、当前事实、第三方 API 用法或报错排查时：

- 官方文档优先，其次 GitHub issue / PR，再看社区答案。
- 精确报错使用双引号，例如 "Cannot find module"。
- 限定站点使用 site:，例如 site:developer.mozilla.org fetch abort。
- 同时带上库名、版本号、运行环境和关键错误码。

Skill 加载机制

• 运行时只把用户启用 Skill 的 name + description 注入稳定上下文
• 模型自行判断是否需要某个 Skill
• 只有选定后才调用 skill 读取完整内容
• 启用状态保存在 .CodePapr/project.sqlite

内置 search Skill

默认 search Skill 包含常用资料源和方法：

• 官方文档：Microsoft Learn、OpenAI、MDN、Node.js、npm、PyPI、Rust、Tauri、Vite、React
• 代码与问题：GitHub repositories、issues、pull requests
• 社区资料：Stack Overflow、包管理器页面、维护者博客
• 搜索方法：site: 限定站点、双引号精确报错、包名加版本号

内置子代理

CodePapr 自带三个内置子代理，主 Agent 可通过 task 工具直接调度，无需额外配置：

* Mentor 默认使用主模型，可在设置中启用独立导师模型（支持独立的 API Key、Base URL 和模型选择；未单独配置 API Key 时回退到主 API Key）。

运行时内部代理（不经 task 工具暴露）

三个内部代理均 internal: true，由运行时直接调用：Verifier 由 GoalRunner 验收循环调用（专属预算：6 轮工具 / 3 分钟墙钟）；Compactor 由压缩管线在骨架超预算时调用；Memory-curator 由记忆管线在交付 / 压缩前两个卡点调用（素材绝不含原始工具输出）。三者均零工具、不注入 skills/memory/project-graph（bootstrap 隔离），墙钟沿用子代理默认 20 分钟。v4 压缩主路径是确定性骨架（零 LLM），Compactor 只在骨架超预算时做一次二级摘要；未启用快速模型或摘要失败时降级为按行截断，绝不递归。

自定义子代理

在 .CodePapr/agents/<name>.md 中用 YAML frontmatter + 正文声明一个子代理，主代理可以把子任务委派给它。同名 Agent 会覆盖内置定义。

---
description: reviewer 负责审查当前改动、定位风险并给出最小修复建议
mode: subagent
model: fast
temperature: 0.2
tools:
  read: true
  grep: true
  diagnostics: true
  git: true
  write: false
  exec: false
---

你是 reviewer，一个只读代码审查子代理。

职责：
- 阅读主代理委派的目标、相关文件和当前 diff。
- 优先找真实 bug、行为回归、边界条件遗漏和缺失验证。
- 给出最小修复建议，指出应修改的文件和验证命令。

边界：
- 默认不直接改文件。
- 不重复总结无关代码风格，只报告影响正确性、可靠性或可维护性的发现。

输出格式：
1. Findings：按严重程度列出问题
2. Suggested Fix：给出最小修改方向
3. Verification：列出建议运行的验证命令

子代理配置说明

• model：覆盖模型，可选 fast（快速模型）或具体模型名
• temperature：温度参数，可选数字
• tools：工具开关，缺省继承全部工具，声明空对象 {} 表示无工具
• 文件名（不含 .md）即子代理名称，与内置 Agent 同名则覆盖
• 改 description 让主代理知道何时调用它
• 改 tools 控制读写/命令权限

子任务机制（两种方式）

子代理运行模型

• 每个子代理拥有独立 Session、ToolRegistry（按 tools 过滤）、Provider
• 最大嵌套深度 2 层（子代理不能再委派子代理给自己）
• 子代理最多执行 50 个内部工具轮次（主代理 500）
• 单次工具调用有 90 秒超时保护，超时返回错误给 LLM 自主决策
• 子代理整体有 5 分钟 wall-clock 超时，超时自动取消
• Explore、Scout 使用快速模型；Mentor 使用独立导师模型或主模型
• 自定义 prompt 可在设置面板的 Mentor 标签页中覆盖

与 AGENTS.md 的区别

.CodePapr/AGENTS.md 是全局项目规则，所有模式、所有子代理都会继承；自定义 Agent 是专职子代理，只有主代理通过 task 工具委派子任务时才启用。前者适合写"所有任务都遵守什么"，后者适合写"某一类任务交给谁做、能用哪些工具"。

内置命令

命令支持 --name（推荐）和 /name（兼容旧版）两种格式。命令的 model 字段决定路由：未声明时使用主模型，声明 fast 时使用快速模型，本地命令不消耗 token。

自定义命令模板与语法

在 .CodePapr/commands/<name>.md 中声明可复用的提示词模板，即可注册为斜杠命令 /<name>：

实战模板示例

示例 1：静态页面与画面渲染诊断（纯前端/零 Git 风险）

---
description: 诊断 index.html 页面结构与画面逻辑
usage: /pagecheck [问题描述]
model: fast
---
请帮我诊断当前静态项目的页面结构与画面逻辑。
页面入口：@index.html
用户关注问题：$ARGUMENTS

示例 2：依赖与脚本分析

---
description: 分析 package.json 依赖与脚本
model: fast
---
请基于项目根配置回答用户问题：
配置内容：@package.json
问题：$ARGUMENTS

示例 3：代码审查与修复（委派 Subagent + 运行状态）

---
description: 审查并修复 lint
agent: code-reviewer
---
请审查 $ARGUMENTS 的改动，并修复其中的 lint 问题。
参考规则见 @.CodePapr/AGENTS.md
当前状态：!`git status -s`

什么是 App 模式与 .papr 应用

在 CodePapr 中，App 模式（应用模式）不仅是写代码的助手，更是交互式应用的即时工厂。只需用自然语言描述需求，Agent 会在几秒钟内完成数据分析、架构设计与前端开发，生成一个开箱即用的 .papr 应用或桌面插件，并挂载到主窗口中运行。

两类产物形态：全屏 App 与 桌面插件（Plugin）

每个 .papr 应用在 manifest.json 中通过 kind 字段声明形态：

.papr 源码结构与强制模块化规范

所有应用与插件均保存在项目的 .CodePapr/apps/<appId>/ 目录下。为了便于后续通过 Agent 进行精确 patch 和持续迭代，CodePapr 强制要求模块化拆分（原生 ES Modules，零构建链，import 必须带 .js 后缀）：

.CodePapr/apps/<appId>/
├── manifest.json       # 应用清单：元数据、kind、surface、权限、inbox 契约、agents
├── index.html          # 骨架页面：只放 DOM 骨架，引入 CSS 与 js/main.js，禁止巨石代码
├── css/
│   └── theme.css       # 样式定义：适配 html[data-mode="dark"] 与 html[data-mode="light"]
├── js/
│   ├── main.js         # 入口模块：初始化、DOM 绑定与事件监听
│   ├── db.js           # 数据持久化封装（papr.db）
│   ├── ui.js           # 视图渲染、Loading 与交互动效
│   ├── api.js          # 外部数据拉取封装（papr.http，可选）
│   └── agent.js        # AI Agent 多轮调用封装（papr.agent.run，可选）
├── data/               # 应用私有沙箱文件存储（papr.fs，运行时自动维护）
└── db.sqlite           # papr.db 键值数据与 inbox 历史（运行时自动生成）

注：对于轻量级插件（kind: "plugin"），推荐遵循三文件结构（index.html + css/theme.css + js/main.js），单文件超过 200 行再做职责拆分。

Papr SDK 全能力（window.papr）

应用运行在安全沙箱 iframe 中，无需安装任何 npm 包，宿主环境会自动注入 window.papr 运行时 SDK：

Agent 推送机制（app_publish + inbox 契约）

在「Agent 负责在终端敲代码/跑测试，悬浮插件负责实时展示任务进展/架构节点」的协同场景中，CodePapr 提供了轻量高效的推送机制：

1. 插件声明契约：在 manifest.json 中定义 inbox 频道和最小数据示例 example。
2. Agent 自动感知：已启用的 inbox 插件会自动注入到 Agent 会话上下文的「已启用插件」列表中。
3. 多模式推送：编程 Agent 在任何可写模式（Agent / Plan / App）下直接调用 app_publish({ appId, channel, payload })。
4. 双通道持久化与回放：推送数据首先原子写入应用的 db.sqlite（保留最新 200 条）；插件已挂载时经 papr://event 实时更新；未挂载时事件短暂排队（约 30 秒），刚打开的实例仍会实时收到；更晚启动则通过 papr.db.get("inbox:<channel>") 无缝回放历史（实时与回放可能重叠，按 seq 去重）。

权限与安全隔离模型

manifest.json 采用 本地访问（local） × 网络访问（network） 两轴安全声明：

应用管理面板（App Dock）

在工作台右侧切到 应用 选项卡，即可浏览项目中所有已生成的 .papr 应用与插件：

• 状态指示：绿色圆点表示「就绪/已显示」，带有 插件 徽章标记悬浮组件。
• 工具栏操作：
  • 打开 / 钉住（Pin/Unpin）：将插件悬浮展示在主窗口中或收起；
  • ▶ 运行 / ■ 停止：管理带后端服务进程的应用生命周期；
  • 🗑 删除：完整清理应用磁盘目录与运行时状态；
  • ⤓ 导出：一键打包导出 .zip 便于分享或备份。
• 设置覆盖：在 设置 → App 选项卡中，可配置未声明应用的默认访问档，或对单个应用进行权限收窄。

实战示例 1：实时股票/数字货币行情悬浮插件（Plugin）

提示词：“帮我生成一个悬浮在右上角的数字货币实时行情小组件，支持 BTC/ETH，每 10 秒自动刷新，高密度小窗展示。”

manifest.json 配置：

{
  "spec": "papr/0.1",
  "name": "加密行情小组件",
  "version": "1.0.0",
  "kind": "plugin",
  "surface": {
    "type": "overlay",
    "width": 300,
    "height": 180,
    "position": "top-right"
  },
  "local": "none",
  "network": true
}

js/main.js 核心逻辑：

async function fetchPrices() {
  try {
    const data = await window.papr.http.get('https://api.coingecko.com/api/v3/simple/price?ids=bitcoin,ethereum&vs_currencies=usd&include_24hr_change=true');
    render(data);
  } catch (err) {
    console.error('行情拉取失败:', err);
  }
}

// 定时轮询与启动拉取
fetchPrices();
setInterval(fetchPrices, 10000);

实战示例 2：任务与架构实时看板插件（支持 Agent 推送）

提示词：“生成一个架构任务看板插件，声明 cards 频道接收你在编码过程中推送的执行步骤和状态。”

manifest.json 配置（含 inbox 契约）：

{
  "spec": "papr/0.1",
  "name": "架构演进看板",
  "kind": "plugin",
  "surface": {
    "type": "overlay",
    "width": 360,
    "height": 260,
    "position": "bottom-right"
  },
  "local": "none",
  "network": false,
  "inbox": {
    "cards": {
      "description": "推送任务状态变更卡片",
      "example": { "id": "task-1", "title": "重构 Auth", "status": "done" }
    }
  }
}

js/main.js 订阅与历史回放：

// 1. 启动时回放历史事件
const history = await window.papr.db.get('inbox:cards') || [];
history.forEach(evt => applyCard(evt.payload));

// 2. 监听 Agent 实时推送
window.papr.events.on('cards', (evt) => {
  applyCard(evt.payload);
});

实战示例 3：全屏 SQLite 数据库探索器（Full App）

提示词：“分析项目中的 stats.sqlite 数据库，生成一个全屏的 Database Explorer 应用，支持表格分页预览与 SQL 查询。”

Agent 会声明 local: "read"，利用多文件拆分构建前端表格组件与 SQL 结果视窗，并在右侧应用面板中无缝挂载全屏交互页面。

什么是 Goal 循环

/goal 是控制命令（与 /compact 同级），启动 Worker + Evaluator 双模型自主循环。它将 AI 编程助手从"一问一答"模式变成一个长周期自主运行代理——直到机器可验证的验收条件通过才结束。

核心机制不是在 prompt 里加"请一直工作到完成为止"，而是建立了一套工程化的自对弈系统：

• Worker（主模型）：拥有全套工具权限，负责规划、写代码、跑测试
• Verifier（快速模型只读子代理，read/grep/glob/list）：阅读 Worker 的执行记录并可亲自核实文件内容，判定是否有伪造成功假象
• 客观条件函数：执行验证命令，用退出码和输出匹配做客观判定

三者协作：条件函数判定 + Verifier 反伪造 = 双保险。只有条件满足且 Verifier 确认 Worker 没有作弊，才判定为 SATISFIED。

基本用法

# 退出码为 0 即满足
/goal exec:npm test

# 退出码 0 且 stdout 匹配正则
/goal exec:npm test match:"\d+ passed"

# 复合条件，全部满足
/goal exec:npm run lint && exec:npm test

# 自然语言目标 + 验收条件（| 分隔）
/goal 修复 auth 测试 | exec:npm test

条件语法

运行机制

1. Worker turn：主 Agent 执行一轮工作（读文件、写代码、跑命令）
2. 客观条件评估：系统自动执行验证命令，获取退出码和输出
3. Verifier 反伪造检查：只读 Verifier 子代理（read/grep/glob/list）阅读 Worker 的执行记录，对关键声称用工具亲自核实，检测是否有"声称测试通过但实际没跑"等完工偏见
4. 判定：条件满足且 Verifier 确认 → SATISFIED，循环结束；否则生成详细反馈注入下一轮
5. 上下文腐烂治理：每 5 个迭代触发自动压缩——与回合末走同一 epoch 提交（插检查点、重渲染并刷新 Bootstrap、就地重建 agent、await 单事务提交），Goal 运行时上下文真正缩小；状态持久化到 .CodePapr/goal-state.md

安全护栏

配置

在设置面板的高级标签页中配置 Goal 循环参数：

• 最大迭代轮数：默认 20，可调 1-100
• 最大运行时间：默认 30 分钟，按分钟配置
• Verifier 模型：默认快速模型（更快更便宜），可切换为主模型（更准确）
• Verifier Token 上限：默认 4000
• Verifier 温度：默认 0.1（越低越确定）

什么是 MCP

Model Context Protocol（MCP）是一种开放协议，允许 Agent 通过外部工具服务器扩展能力。CodePapr 内置 MCP host，可同时连接多个 MCP 服务器，把外部工具透出给主 Agent 调用。

每个 MCP 工具会以 mcp__<serverId>__<toolName> 形式注册，与内置 30 个工具并列出现在 ToolRegistry 中。

三种传输模式

每个 MCP 服务器的字段

预置示例

桌面端默认提供三个开箱可用的 MCP 服务器（默认全部禁用，需手动启用）：

stdio 服务器示例

# 名称
DuckDuckGo Search MCP

# Transport
stdio

# 命令 / 参数
command: npx
args: -y duckduckgo-mcp-server

# 环境变量（每行一个 KEY=value）
env:
HTTP_PROXY=http://127.0.0.1:7890
USER_AGENT=CodePapr/0.1.0

# 工具过滤
allowedTools: duckduckgo_web_search

sse / streamable-http 服务器示例

# 名称
Remote Knowledge Base

# Transport
streamable-http

# URL
url: https://example.com/mcp

# Headers（每行一个 Header-Name: value）
headers:
Authorization: Bearer your-token-here
X-API-Key: your-api-key

权限模式

• read-only：只读工具，调用无需确认（适合搜索、查询）
• read-write：可写工具，配合 requireConfirmation 使用
• dangerous：危险工具（如执行 shell、删除数据），强烈建议开启 requireConfirmation

工具过滤

通过 allowedTools 和 deniedTools 控制每个服务器暴露的工具子集：

• 支持 * 通配符（如 describe*、list_*）
• 逗号分隔多个模式
• 黑名单优先级高于白名单
• 典型场景：Postgres MCP 默认 allowedTools=query,describe*,list* + deniedTools=delete*,drop*,truncate*,update*,insert*，确保只读

全局开关

常用 MCP 服务器推荐

• @modelcontextprotocol/server-filesystem：受限文件系统访问
• @modelcontextprotocol/server-postgres：Postgres 数据库
• @modelcontextprotocol/server-github：GitHub API
• @modelcontextprotocol/server-slack：Slack 集成
• mcp-server-sqlite：SQLite 数据库
• duckduckgo-mcp-server：免费网页搜索

架构概览

包级职责

宿主 / 客户端职责

Tauri 桌面端不是单体后端：src-tauri 保留 GUI 专属能力与薄 RPC 代理；文件系统、Git、Shell、LSP、数据库、MCP、Web 等领域实现位于 codepapr-core，统一由 codepapr-server 通过 JSON-RPC 提供。

• src-tauri/src/commands.rs：Tauri 命令，将 UI 请求代理给 host.rs
• src-tauri/src/host.rs：启动/连接 codepapr-server、发送 JSON-RPC、把通知转发到 Tauri 事件总线
• crates/codepapr-server：RPC 路由、参数校验、事件广播与任务队列
• crates/codepapr-core：workspace_fs、git_operations、shell、lsp、db、mcp_host、web 等领域子系统
• GUI 专属例外：内置/无头浏览器、TTS、Stronghold vault、文件导出与 Papr App 运行时仍由桌面客户端持有

桌面端 Agent 桥接

桌面端不直接调用 core Agent，而是通过 WorkerBackedAgent 将 LLM 聊天循环卸载到 Web Worker 中，确保长任务不阻塞 UI。

Worker 崩溃恢复 & 流式快照

• 崩溃捕获：主线程会捕获 WorkerCrashError，自动清空当前 agent 实例（下次发送会创建新 Worker），并在错误消息前追加"Agent Worker 崩溃。"前缀
• 流式快照：流式响应过程中每约 2 秒（STREAM_SNAPSHOT_INTERVAL_MS）触发一次 onStreamSnapshot，把 in-flight 内容持久化到项目 SQLite
• 掉电恢复：崩溃 / 强退 / 掉电后下次启动可看到崩溃前已写入的对话片段，不会丢失大块进度

技术栈总览

请求怎么叠（缓存视角）

发给模型的不是一锅炖。完整分层与记忆流程见 上下文分层。越靠前越稳，前缀缓存越好用：

缓存命中模式

关键不变量

• 用户自定义提示词进入 session bootstrap 而非每轮 user prompt
• Skills 进入 bootstrap 而非 system prefix
• Workspace 路径只出现在 system prompt，不在 bootstrap 中重复
• Custom guidance 只在 bootstrap 中出现一次
• session bootstrap 由每回合的 promptKey 决定：MEMORY.md / skills / 文件变化时下回合重建一次（保存即生效），否则持续命中
• 每轮 user prompt 的动态内容（日期 / 诊断）置于尾部，不改既有前缀

缓存优先架构：Context Epoch 模型

前缀缓存按字节前缀逐字匹配自动命中（无显式断点）。架构的第一性原则是：epoch 内前缀字节稳定（只追加），epoch 之间通过压缩有意重置。

• epoch = 一个 agent 生命周期内、前缀保持字节稳定的跨度。工具循环每一轮把 assistant 消息与 tool 结果追加到尾部，前缀逐字节复用 → 循环内多次调用天然高命中。
• epoch 边界 = 上下文压缩（v4 骨架引擎）：用量达到窗口 90% 时，把更早回合折叠为确定性骨架（用户问题 + 最终结论，工具细节计数注记；零 LLM）+ 保留最近回合逐字，开启新 epoch（一次性 miss，之后重新稳定累积命中）。checkpoint 按保留边界插入（非追加到末尾；预算压力下边界可落进超长回合内部，早期工具轮折成活动行），其后保留近期尾部原文（含工具调用↔结果配对，不切出孤儿 tool 消息）；checkpoint 在有效上下文中以 user 轮发出，避免压缩后首条 / 连续 assistant，提升跨 provider 正确性。

中途溢出 → 压缩（mid-loop compaction）

工具循环内上下文会随 tool 结果增长。Agent.chat 在每轮构建请求之前估算上下文大小，超过有效阈值时压缩（重置日志开启新 epoch）后继续：

• 仅轮首检查：tool 结果在一轮末尾追加，其导致的超限在下一轮轮首被拦截——任何 LLM 请求都不会用超限上下文发送；任务在压缩后基于"摘要 + 近期尾部"继续。
• 不在工具执行中途压缩：一轮内多个工具调用原子执行完再到轮边界压缩，避免破坏"工具调用↔结果"配对。
• 防死循环：压缩连续无效/失败会熔断（本回合不再空试）；压缩成功后日志已低于阈值，后续轮次不会反复触发。
• 防御纵深：单个 tool 结果先被截断到 ~50KB（或落盘留预览），单轮增长有界。

剪枝已退役（v4）

旧版按保护窗口裁剪工具结果的 prune 层随 v4 移除：工具结果本来就只存在于最近 ≤5 个逐字回合内，更早的已被骨架整体折叠——独立剪枝不再有意义。单条巨型输出由入口护栏约束（工具输出截断与大结果 artifact 外置，模型可用 history_read_artifact 回读），触发器始终只有「窗口 90%」一条线。

有效上下文阈值（单一规则）

maxContextTokens 声明模型输入窗口，默认 200K，对 DeepSeek / OpenAI 兼容 / Claude 统一生效（不按 provider 钳制；兼容端点常是转发大上下文模型的网关）。压缩触发线 = 窗口 × 90%（常量 COMPACT_TRIGGER_RATIO），主会话、mid-loop、Goal、task 子代理全部同源；实测用量（provider usage）与估算取大者参与判定，超限请求仍可走紧急压缩兜底。窗口设得越高 → 压缩越少 → 命中率越高（缓存读取廉价）。

前缀稳定性保障

• 无每请求前缀改动：v4 不再有滑动剪枝；历史只在 epoch 边界被骨架化
• 重建序列化字节一致：对象 tool 结果用 sortedStringify（与实时路径一致）；空助手内容为 ''
• reasoning 回传稳定：reasoning_content 按"是否存在 + 模型能力"回传，与每请求 thinking 开关解耦
• TodoList digest 冻结：checkpoint 生成时冻结当前 digest，重建时复用而非实时重渲染
• 参数冻结：topP / temperature / maxTokens / thinkingEnabled 冻结在 ImmutablePrefix，变化即换 hash

已知限制：LLM 前缀缓存有存活时间，长时间空闲后首次调用会重新 miss 整段前缀（与客户端无关）；压缩是有损的，阈值越高单次压缩覆盖的历史越多。

LSP 桥接架构

桌面端 LSP 采用Tauri 原生宿主 + stdio JSON-RPC 的结构，通过 src-tauri/src/lsp.rs 管理 language server 子进程、stdin 写入、stdout reader 线程和消息队列。

支持的语言族（15 种）

C# LSP 优先级链

C# 的 LSP 有多层回退机制：

1. 系统 PATH 或 ~/.dotnet/tools 中的 csharp-ls
2. 发布包内置的 csharp-ls 二进制（generated/lsp-tools/csharp-ls/bin/）
3. 内置 CodePapr.CSharp.Analyzer（自定义 Roslyn sidecar，支持跨文件和跨 ProjectReference 解析）
4. dotnet run --project CodePapr.CSharp.Analyzer.csproj（开发态 / 源码 fallback）
5. 系统 PATH 上的 omnisharp -lsp 或 OmniSharp -lsp（仅静态候选）
6. 内建 tree-sitter 符号解析（最终兜底）

管理安装（Managed LSP）

桌面端会在运行时按需托管安装缺失的 LSP：

• Node 系（5 个 npm 包，提供 7 种语言服务）：typescript-language-server（TypeScript / JavaScript）、vscode-langservers-extracted（HTML / CSS / JSON）、yaml-language-server、pyright、bash-language-server — 通过 npm 安装，使用内置 Node.js runtime v20.12.2
• 二进制系（6 个）：clangd v22.1.6、rust-analyzer、JDTLS + Temurin JRE 21、sqls、marksman、gopls — 从官方源下载
• C#：通过 dotnet tool install -g csharp-ls 安装，或使用内置 Roslyn sidecar
• 可通过 CODEPAPR_DISABLE_MANAGED_LSP_DOWNLOAD=1 禁用自动托管下载

Tree-sitter 语法解析（16 种语言）

内建 tree-sitter 语法树解析，用于 ProjectGraph 和 fallback 符号提取：TypeScript、JavaScript、Python、Rust、Java、Go、C++、Bash、C#、CSS、HTML、JSON、PHP、Ruby、Kotlin、Swift。

LSP 加载策略

• 工作区启动时不会批量预热 LSP
• 当前文件显示后才异步加载该文件的 LSP
• 生成/修改/保存写盘后异步刷新相关文件的 diagnostics 和符号缓存
• LSP 后端缓存全 workspace diagnostics，跨文件错误也能被检测
• 代码区只有有问题时才显示提示，没有问题时保持干净
• 上层 LSP 不可用时，回退到内建 tree-sitter fallback 符号解析

验证命令矩阵

推荐提交前回归顺序

npm run build
npm run test
npm run test:e2e
npm run test:e2e:ui
npm run verify

首次运行 UI E2E 前需要安装浏览器依赖：

npm run test:e2e:ui:install

桌面端发布

# 开发调试
npm run debug

# 优化后的桌面运行版本（不打包）
npm run release

# 生成安装包（.dmg / .msi）并整理到 Release/
npm run publish

发布辅助脚本

• macOS: ./publish-codepapr.command
• Windows: publish-codepapr.cmd

发布前检查

npm run release:prep
npm run publish:dry-run

1. 先理解再执行

适合第一次接手仓库或需求还不够清晰时：

1. Ask：解释系统结构、定位模块
2. Plan：输出任务清单和验证方案
3. Agent：按清单实施

2. 直接修复问题

适合你已经知道目标，只是不想手动查和改：

修复 packages/@codepapr/api 里缓存统计不正确的问题。
先定位统计汇总逻辑，再做最小修改，最后跑相关测试。

3. 启动前端并在应用内预览

适合 UI 调整、页面行为验证和预览联动：

1. 让 Agent 启动 preview session 或后台命令
2. 在应用内预览中查看页面
3. 如果还要点页面、填表单或截图，继续用浏览器工具

4. 保留终端上下文做连续操作

适合脚本、REPL、交互式 CLI 或多步 shell 流程：

1. 打开 shell session
2. 连续发送命令
3. 按输出继续推进
4. 完成后关闭 session

5. 复盘历史会话与成本

• 查看 session 列表
• 查看指定 session 的 stats（缓存命中/未命中/token 使用）
• 对照当前模型设置判断成本是否合理

DeepSeek 模型参考

在 CodePapr 里怎么选

• 主模型默认是 deepseek-v4-pro——用于 Ask、Plan、Agent、App 主执行流程；App 模式始终使用主模型以确保生成质量
• 快速模型默认是 deepseek-flash——用于上下文压缩、子任务规划、只读轻型子代理
• 思考强度（thinkingEffort）默认为 max（最强推理），可在 LLM 设置 tab 中切换为 high

成本优化建议

• Ask 和轻分析任务优先用更便宜模型
• 大改动前先走 Plan，减少无效执行轮次
• 让任务描述更具体，减少模型反复搜索和修复的轮数
• 保持系统提示与工具边界稳定，最大化前缀缓存命中

1. 启动后提示没有 API key

先检查桌面端设置是否已保存，以及是否设置了对应环境变量（DEEPSEEK_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY）。

2. 安装或 npm 脚本跑不起来 / 找不到

确认是否执行过 npm install 和 npm run build，以及当前仓库是否位于 OneDrive 路径下导致 .bin shim 异常。

3. Agent 遇到 vite、tsc、eslint、模块缺失错误

优先当成依赖未安装或本地包未构建，而不是先怀疑云同步或磁盘问题。

4. 浏览器工具不可用

通常是因为本机没有可检测到的 Chrome 或 Chromium 兼容浏览器。

5. 改完代码后测试还是旧结果

这个仓库里不少包会通过各自的 dist 入口参与测试或引用。改了源文件后，如果结果看起来没变，先重新 build 受影响包，再跑验证。

6. 修改源码后构建原则

重要：改源码 → 先 build → 再跑受影响测试 → 再跑更大范围验证。当结果看起来像"没生效"时，先怀疑 build 没补，而不是先怀疑运行时异常。

7. 如何使用本地模型

在设置中可以接入本地模型 provider（OpenAI 兼容端点），用于离线或私有部署场景。在支持的模型下，可直接向聊天框粘贴或拖入图片作为输入。

8. 为什么读取某些绝对路径会弹窗

这是桌面端的外部路径权限机制。当 Agent 尝试读取或列出项目外的绝对路径时，会请求你显式授权，保证不会未经允许访问系统文件。

9. UI E2E 跑不起来

先确认是否已安装 Playwright 浏览器依赖：

npm run test:e2e:ui:install

UI E2E 使用 Chromium 在无 Tauri webview 的 mock 环境下运行，不需要真实模型配置。

使用建议

新手：先用 Ask 理解系统 → 再用 Plan 看清楚改动范围 → 最后用 Agent 做真正执行。需要数据可视化时切到 App 模式，一句话生成交互式图表。

老手：直接在 Agent 模式里给明确目标 → 明确影响文件和验证要求 → 用桌面端完成对话、Git、预览和浏览器联动。