CodePapr 教程

什么是 CodePapr

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

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

核心设计理念

• 本地优先：项目上下文尽量不离开工作区，文件和命令执行都在本地完成
• 单一 Runtime，多入口复用：桌面端与内部自动化宿主共用同一套 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 正常。

支持平台

外部依赖

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

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

三种启动方式

配置存放位置

Provider 模式

DeepSeek 接口参考地址

# OpenAI 格式
https://api.deepseek.com

# Anthropic 格式
https://api.deepseek.com/anthropic

环境变量回退顺序

内部自动化宿主与 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 负责实际执行

最短路径

npm install
npm run build
npm run debug

首次使用流程

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

使用入口

注意：仓库中同时保留 @codepapr/cli 终端入口，支持终端交互和脚本化自动化。CLI 同样内置 Explore、Scout、Mentor 三个子代理，与桌面端功能一致。

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

Ask 分析模式

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

特点：

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

Plan 规划模式

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

特点：

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

Agent 执行模式

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

特点：

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

如何给出有效任务

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

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

推荐写法

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

不够好的写法

帮我修一下预览。

界面结构

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

桌面端完整能力

什么时候优先用桌面端

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

Git 集成

• Git 面板：展示 staged/unstaged diff、最近提交历史、分支创建/切换、本地提交、安全擦除本地改动
• 8 个 Agent Git 工具：status、diff、history、branch_checkout、stage、commit、restore、reset
• 自动初始化：如果当前工作区还不是 Git 仓库，面板可直接执行 git init

对话重置（Git Checkpoint）

每次 Agent 完成一轮对话后，系统自动执行 git add -A && git commit -m "codepapr:checkpoint" 创建快照。当你需要回退时：

• Hover 任意用户消息，点击"重置到此点"
• 系统 git reset --hard 到该消息对应的 checkpoint commit
• 所有文件原子性恢复到对话那一刻的状态
• 消息列表同步截断，后续对话全部移除
• 非 Git 仓库自动降级到逐文件编辑历史撤销

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

CodeGraph — 项目理解核心

CodeGraph 是统一的项目理解图，同时返回目录树、代码骨架摘要和文件/符号关系图。所有符号查找、依赖分析、影响分析均以此为基础。

LSP 语言智能工具

基于 Language Server Protocol，直接调用语言服务。CodeGraph 优先复用 LSP documentSymbol 结果增强符号质量。

文件操作工具

命令执行工具

Git 操作工具（9 个）

预览与浏览器工具

Shell 会话工具

网络工具

诊断与项目存储

实用工具

.CodePapr/AGENTS.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_load 读取完整内容
• 启用状态保存在 .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 和模型选择）。

自定义子代理

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

---
description: reviewer 负责审查当前改动、定位风险并给出最小修复建议
mode: subagent
model: fast
temperature: 0.2
tools:
  workspace_read_file: true
  workspace_search_text: true
  workspace_project_diagnostics: true
  workspace_git_status: true
  workspace_git_diff: true
  workspace_write_file: false
  workspace_run_command: 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）
• Explore、Scout 使用快速模型；Mentor 使用独立导师模型或主模型
• 自定义 prompt 可在设置面板的 Mentor 标签页中覆盖

与 AGENTS.md 的区别

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

内置命令

命令支持 --name（推荐）和 /name（兼容旧版）两种格式。

自定义命令模板

在 .CodePapr/commands/<name>.md 中声明可复用的提示词模板：

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

模板语法

架构概览

包级职责

桌面端 Agent 桥接

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

技术栈总览

三层 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. csharp-ls（dotnet tool，优先从系统 PATH 或 ~/.dotnet/tools 查找）
2. CodePapr.CSharp.Analyzer（内置自定义 Roslyn sidecar，支持跨文件和跨 ProjectReference 解析）
3. omnisharp -lsp（回退）
4. 内建正则 fallback 符号解析

管理安装（Managed LSP）

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

• Node 系（7 个）：typescript-language-server、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 语法树解析，用于 CodeGraph 和 fallback 符号提取：TypeScript、JavaScript、Python、Rust、Java、Go、C++、Bash、C#、CSS、HTML、JSON、PHP、Ruby、Kotlin。

LSP 加载策略

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

验证命令矩阵

推荐提交前回归顺序

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

桌面端发布

# 开发调试
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 主执行流程
• 快速模型默认是 deepseek-v4-flash——用于上下文压缩、子任务规划、只读轻型子代理
• 思考强度（thinkingEffort）默认为 max（最强推理），可在 LLM 设置 tab 中切换为 high

成本优化建议

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

1. 启动后提示没有 API key

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

2. 内部自动化脚本跑不起来或命令找不到

确认是否执行过 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 兼容端点），用于离线或私有部署场景。在支持的模型下，可直接向聊天框粘贴或拖入图片作为输入。

使用建议

新手：先用 Ask 理解系统 → 再用 Plan 看清楚改动范围 → 最后用 Agent 做真正执行。

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