CodePapr 教程

什么是 CodePapr

CodePapr 是一个缓存优先的编码代理（Agent）系统，提供 Tauri 桌面工作台和 CLI 终端入口两种入口。它通过共享 Agent Runtime 为桌面端与终端 CLI 提供能力，使 AI 代理能够在真实项目仓库里完成读取、修改、执行、验证与预览。

CodePapr 不是传统的 AI 聊天工具，也不是 IDE 插件。它是一个在终端/桌面中运行的自主代理，能真正理解你的项目上下文并自动执行开发任务。

核心设计理念

• 本地优先：项目上下文尽量不离开工作区，文件和命令执行都在本地完成
• 单一 Runtime，多入口复用：桌面工作台与 CLI 终端入口共用同一套 Agent、Session、ToolRegistry、Provider 语义
• DeepSeek 缓存优化：稳定内容前置、易变内容后置，最大化前缀缓存命中率以降低 token 成本
• 结构化代码修改：使用 Search/Replace Diff 机制，先校验再写入，避免行号错位
• 可验证执行链路：每一轮请求、响应、工具调用和缓存统计都可追踪

CodePapr 与主流 AI 编程工具对比

2026 年，AI 编程工具已经很成熟。以下对比基于各工具当前公开能力，如实呈现差异。

谁适合使用 CodePapr

• 已掌握至少一门编程语言，能读懂基础语法和项目结构
• 希望借助 AI 大幅提升开发效率的工程师
• 独立开发者或需要长期维护复杂项目的技术负责人
• 习惯在命令行和可视化界面之间切换的开发者
• 关注 token 成本，希望利用 DeepSeek 缓存优化降低开销的团队

需要具备的基础能力

• 基础编程能力（能读懂并编写简单代码）
• 基本的代码阅读与理解能力
• 会使用常见开发工具（编辑器、命令行、Git）
• 具备基本的项目结构认知（目录、模块划分）
• 愿意理解代码，而不是完全依赖 AI

支持的 LLM Provider

环境要求

标准安装

# 克隆仓库后
npm install
npm run build

安装验收

npm run verify

通过这一步，说明当前机器至少满足：Node 依赖正确、workspace 构建正常、workspace 测试正常、CLI E2E 正常、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 兼容端点。

环境变量回退顺序

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

1. DEEPSEEK_API_KEY
2. OPENAI_API_KEY
3. ANTHROPIC_API_KEY

应用级设置项

快速模型路由

三步启动

1. 准备配置：在桌面端设置中填写 API key、provider 和 model
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、预览面板中复核结果

使用入口

注意：CLI 内置 Explore、Scout 两个子代理；Mentor 仅在桌面端的"子Agent"标签页可启用并配置。

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

Ask 分析模式

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

特点：

• 默认不改文件、不跑命令
• 遇到时效性问题时，优先走只读时间/网页工具核实
• 只有你明确要求基于项目核实，它才会进入只读工具链

Plan 规划模式

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

特点：

• 默认先给任务清单
• 会给影响文件、执行顺序、验证方式和风险
• 适合先规划，再切到 Agent 执行

Agent 执行模式

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

特点：

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

App 应用生成模式

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

核心理念：

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

工作流程：

1. 探索数据源：用 workspace_read_file / MCP 工具理解数据结构
2. 生成应用：用 workspace_write_file 写完整 HTML 到 .CodePapr/apps/<appId>/index.html
3. 渲染结果：调用 app_render 工具渲染到右侧"应用"面板

HTML 应用规范：

• 单文件内联 HTML——不需要组件拆分或构建系统
• 通过 CDN 引用图表库（D3、ECharts、Mermaid、MapLibre、Leaflet、Three.js 等）
• 在沙箱 iframe 中运行（sandbox="allow-scripts allow-same-origin"）
• 可使用 Papr SDK（window.papr）调用 Agent、存储、HTTP、文件系统
• appId 必须是 kebab-case，相同 appId 再次调用覆盖更新——支持迭代改进

会话隔离：

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

模型策略：始终使用主模型（deepseek-v4-pro）以保证 HTML 生成质量。

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

权限分级：App 通过 manifest.level 声明权限级别（L0 纯计算 / L1 Runtime / L2 联网 / L3 系统，默认 L1）。设置 → 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 弹窗授权；CLI 的读取边界较宽松，写入仍限制在工作区内。

文件大小限制

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

CodePapr 支持创建、导入和管理 AI 角色，让 Agent 以特定人设与你对话。激活角色后，角色的身份、语气、风格会被注入 LLM 系统提示词，Agent 以角色人设作出回应。

角色数据模型

每个角色包含以下字段：

角色扮演格式约定

激活角色后，系统提示词会明确以下格式规则，确保 TTS 能正确区分对话和动作：

创建角色

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 等工具中使用。

启用/切换角色

在角色列表中点击角色名称即可激活。当前激活的角色会显示"已启用"标记。Agent 的每次回复都会以该角色的人设进行。

角色人设放在 Session Bootstrap 中（不在系统提示词的 ImmutablePrefix 中），因此切换角色不会破坏 DeepSeek 前缀缓存。

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，一次合成合并几句一起推理，减少往返次数
7. 点击 “试听” 按钮预览效果
8. 满意后点击 保存

当前播放模式

当前 UI 采用 WebSocket 批量流式（ws-batch）作为默认且唯一实际生效的模式：所有句子通过一条持久 WebSocket 连接批量发送、逐个返回，首字延迟约 1-2 秒，句间衔接流畅。

代码层保留了 whole、streamed-pipeline、streamed-pcm 三种模式，但角色编辑面板暂未开放切换，用户无需关注。

语音微调

对音质有更高要求时，可在 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 — 跨会话项目记忆（自动整理）

Agent 在工作过程中会自动发现项目特有的模式、坑和约定，并将其写入记忆文件。下次会话启动时自动加载，帮助 Agent 避免重复踩坑。文件超过 200 行后会自动整理，避免无限膨胀。

• 自动积累：Agent 发现项目特有知识后，用 write 追加到 .CodePapr/memory.md，每条以 ## YYYY-MM-DD 主题 开头
• 自动加载：每次会话启动时注入到 bootstrap 上下文，不影响系统提示词缓存
• 自动整理：会话启动时若 memory.md > 200 行，或上下文压缩 / /compact 触发，标记为待整理；当前轮 Agent 回复完成后，异步用快速模型对记忆做去重、合并、精简，写回文件
• 不阻塞：整理是 fire-and-forget 异步执行，当前会话用旧记忆，下次启动用整理后的版本；失败时静默降级为规则去重，不影响主流程
• 不新增工具：整理由 store 层后台逻辑触发，模型无感知，不破坏 ImmutablePrefix 缓存
• 记录原则：用户偏好、项目约定、错误模式与解法、架构决策；不记录通用编程知识、临时任务状态、已在 .CodePapr/AGENTS.md 中的规则

/compact — 强制压缩上下文

手动触发对话压缩，将早前消息合并为结构化检查点释放 token 空间：

• 强制模式：不受 maxConversationRounds 和 maxContextTokens 阈值限制
• 本地命令：零 token 消耗，调用现有压缩管线生成检查点
• 顺带触发记忆整理：压缩成功后会标记 memory.md 为待整理，下一轮 agent 回复后异步整理
• 使用场景：接近上下文上限或响应变慢时，压缩即可恢复流畅对话

配置入口

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

• 创建/编辑 .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 工具直接调度（verifier 除外，仅供 Goal 循环内部使用），无需额外配置：

* Mentor 默认使用主模型，可在设置中启用独立导师模型（支持独立的 API Key、Base URL 和模型选择）。
** Verifier 是 Goal 自主循环的内部验收器，不暴露给主 Agent 的 task 工具；默认使用快速模型，可在高级设置中切换为主模型。

自定义子代理

在 .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 中声明可复用的提示词模板：

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

模板语法

什么是 Goal 循环

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

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

• Worker（主模型）：拥有全套工具权限，负责规划、写代码、跑测试
• Verifier（快速模型，无工具）：阅读 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 子代理阅读 Worker 的执行记录，检测是否有"声称测试通过但实际没跑"等完工偏见
4. 判定：条件满足且 Verifier 确认 → SATISFIED，循环结束；否则生成详细反馈注入下一轮
5. 上下文腐烂治理：每 5 轮触发自动压缩；状态持久化到 .CodePapr/goal-state.md

安全护栏

配置

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

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

什么是 MCP

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

每个 MCP 工具会以 mcp__<serverId>__<toolName> 形式注册，与内置 26 个工具并列出现在 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：免费网页搜索

架构概览

包级职责

Rust 后端领域模块

Tauri 后端按职责拆分为多个模块：

• browser：headless Chromium 浏览器自动化
• shell：前台/后台命令、持久 Shell 会话、命令安全守卫
• web：HTTP fetch、网页提取、多引擎搜索（SearXNG 优先，失败自动降级）
• workspace_fs：文件列表、读取、写入、SEARCH/REPLACE diff、搜索
• task_queue：重 I/O 操作串行化队列
• db：应用与项目级 SQLite 持久化
• lsp：LSP server 进程管理
• symbol_provider：tree-sitter fallback 符号提取
• mcp_host：MCP 工具服务器宿主
• shared：路径归一化、workspace 路径解析、通用工具

桌面端 Agent 桥接

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

Worker 崩溃恢复 & 流式快照

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

技术栈总览

三层 Prompt 注入

系统将 prompt 分为三层注入，按稳定度从高到低排列以最大化 DeepSeek 自动前缀缓存命中：

缓存命中模式

关键不变量

• 用户自定义提示词进入 session bootstrap 而非每轮 user prompt
• Skills 进入 bootstrap 而非 system prefix
• Workspace 路径只出现在 system prompt，不在 bootstrap 中重复
• Custom guidance 只在 bootstrap 中出现一次

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-v4-flash——用于上下文压缩、子任务规划、只读轻型子代理
• 思考强度（thinkingEffort）默认为 max（最强推理），可在 LLM 设置 tab 中切换为 high

成本优化建议

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

1. 启动后提示没有 API key

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

2. 安装或 CLI 命令跑不起来 / 找不到

确认是否执行过 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、预览和浏览器联动。