01
文件操作 File Operations
AST 语法预检写后自动回传 LSP 诊断
读写修改 内容读写与精准补丁
READ
read workspace_read_file文本 + AST
读取项目文件。支持
startLine / endLine 行范围切片与 aroundLine 窗口；支持 symbol 参数按 AST 精确定位符号代码块；大文件全量读取时自动附加符号大纲。调用链路：
read → workspace_read_file（Tauri 命令）→ JSON-RPC fs/readTextFile → codepapr-server → codepapr-core::workspace_fs。传 symbol 时通过 AST 定位行区间再返回；输出经过截断保护（>60k 字符中间折叠，>100k 转存磁盘并返回 2k 预览，150k 硬顶）。WRITE
write workspace_write_file文本 + AST/LSP
创建或全量覆盖文件。写入前执行 AST 语法预检（拦截新增语法错误），写入后立即重读校验，并同步触发 LSP 文档变更，直接随结果返回该文件最新诊断。
调用链路：
write → workspace_write_file（Tauri 命令）→ JSON-RPC fs/writeTextFile → codepapr-server → codepapr-core::workspace_fs。预检对比前后语法错误数，错误增加则拒绝落盘；落盘后重读校验，通过 lsp_open_document 刷新诊断，最后经 JSON-RPC 通知（workspace-files-changed）回传 Tauri 事件总线并清理项目图缓存。EDIT
edit workspace_apply_patch文本 + AST/LSP
单文件精确 SEARCH/REPLACE 替换。严格字面匹配，杜绝模糊偏移；出现多处命中时报错并明确列出每处的行号与所属符号；内置写前 AST 预检与写后 LSP 诊断回传。
调用链路：
edit → workspace_apply_patch。字面 String.indexOf 逐字节命中，歧义时通过 AST 解析所在符号生成富错误提示；写后自动等待 LSP 单文件诊断，单次操作上限 20MB。PATCH
patch workspace_apply_diff文本 + AST/LSP
多文件原子 SEARCH/REPLACE 补丁。所有文件的修改全部匹配成功后才统一落盘，任一处失败则整体回滚。规则与
edit 一致，支持歧义定位、逐文件 AST 预检与 LSP 诊断。调用链路：
patch → workspace_apply_diff。按运行态内容逐文件执行歧义预检 → 顺序应用差异 → 逐文件 AST 校验与写入 → 批量刷新工作区变更。检索与遍历 搜索与目录大纲
GREP
grep workspace_search_text文本 + LSP
代码内容搜索的核心入口（默认使用正则匹配，支持
smart-case 与 contextLines 上下文）。传 semantic: true 时切换为 LSP 工作区符号语义检索，LSP 不可用时自动降级正则。调用链路：默认路由至
workspace_search_text；开启 semantic: true 时路由至 workspace_workspace_symbol。无可用 LSP 时降级正则并标记 degraded: true。GLOB
glob workspace_search_files纯文本
按 glob 通配符搜索项目文件名（如
**/*.test.ts）。分发层自动将通配符转换为正则后进行快速匹配。调用链路：
glob → globToRegex → workspace_search_files。LIST
list workspace_list_files文本 + AST
浏览目录树结构（默认深度 2，最大 6），自动附带每个代码文件的顶层 AST 符号摘要（函数、类、接口等），快速建立项目骨架认知。
调用链路：
list → workspace_list_files（Tauri 命令）→ JSON-RPC fs/listFiles → codepapr-server → codepapr-core 遍历，并发通过 AST 提取顶层符号注入 symbolsByFile。IMG
read_image workspace_read_image多模态
读取本地图片（PNG/JPEG/WebP/GIF）并转为 Base64 供视觉模型解析（大小上限 5MB）。仅在多模态配置开启时对模型可见。
调用链路：
read_image → workspace_read_image（Tauri 命令）→ JSON-RPC fs/readFile → codepapr-server → codepapr-core 原生读取。当前槽位未启用多模态时自动从可见工具集中剥离（显式 profile 配置优先，未配置的已知纯文本模型默认关闭；快速档具备视觉能力时按需回退）。02
代码智能 Code Intelligence
LSP → AST 自动降级标注 source 与 confidence
语义导航与编辑 精确符号操作
LSP
lsp 9 个语义导航 ActionLSP → AST
代码语义只读导航：
goToDefinition、findReferences、hover、documentSymbol、workspaceSymbol、goToImplementation、prepareCallHierarchy、incomingCalls、outgoingCalls。LSP 优先，未就绪时自动降级至 AST 项目图，并标注置信度。调用链路：分发至对应 LSP 处理函数；超时（30s）或服务未启动时自动回退至 AST 项目图做符号级查找，返回标记
source: "ast", confidence: "medium"。LEDIT
lsp_edit rename / code_action / formatLSP 语义
代码语义编辑工具，与字面替换互补：跨文件安全符号重命名（
rename）、执行快速修复与整理导入（code_action，如 source.organizeImports）、批量代码格式化（format）。调用链路：通过 LSP
textDocument/rename 计算 WorkspaceEdit 并落盘，保障跨文件引用的原子一致性。DIAG
diagnostics 单文件复查 / 全项目检查LSP 诊断
按需查询指定文件的 LSP 诊断信息，或传
project: true 触发项目级 Lint/Typecheck。注：常规文件写入已内置诊断回传，本工具主要用于按需复查与全项目检测。调用链路：单文件通过 JSON-RPC
lsp/diagnostics（codepapr-server → codepapr-core::lsp）监听诊断刷新（短路返回，2s 超时防卡死）；全项目则聚合各语言 Provider 的静态检查结果。全局图谱与深度分析 Explore 子代理专属
GRAPH
graph 14 个分析 Action · Explore 专属开放AST 项目图
跨模块依赖与影响面分析工具。包含 8 个架构查询（
overview、lookup、dependency、entrypoints、impact、implementations、smart_context 等）与 6 个静态分析（死代码、循环依赖、类型层级、重构建议、测试影响面等）。主代理软隐藏，委派给 Explore 子代理使用。基于 AST 与 LSP 混合构建全局项目图；具备 60 秒建图缓存与并发去重机制，任意文件修改自动失效。同时作为
lsp 点查询的 AST 兜底后端。03
命令与进程 Command & Process
穿透执行支持工作目录与状态管理
BASH
bash workspace_run_shell_command系统进程
在项目根目录或指定
workdir 下执行终端命令。action: "run" 默认前台阻塞；background: true 启动常驻进程并返回 PID；支持 list / stop / stop_all 管理后台进程。代码搜索请统一使用 grep 工具，避免使用系统 grep/rg。调用链路：前台阻塞走
workspace_run_shell_command；后台常驻走 workspace_start_shell_background_command，具备进程保活与自动资源释放机制。04
版本控制 Git Workspace
安全快照破坏性操作自动备份分支
GIT
git status / diff / log / branch / stage / commit / restore / resetGit 管理
CodePapr 内置 Git 版本控制。提供完整的暂存、提交、差异比较与分支切换能力；执行
reset / restore 等破坏性操作前自动创建安全快照并保留备份分支。分发至各
workspace_git_* 细粒度接口。reset 动作强制要求指定 target 并自动生成 backup 前缀分支，底层提供快照撤销保护机制。05
网络与浏览器 Web & Browser
内置浏览器支持 DOM 交互与页面截图
WEB
webfetch / websearch 网页抓取与搜索网络请求
webfetch：抓取网页正文并转换为清洗后的 Markdown 文本；传
save: true 可将原始资源或二进制文件下载至 .CodePapr/downloads/。websearch：接入聚合搜索引擎提供实时技术检索。webfetch 路由至 web_fetch_url 或 web_download_file；websearch 直接通过后端 SearXNG 引擎发起并发检索。BRWS
browser 9 个交互 Action内置浏览器
桌面端内置沙箱浏览器交互：
open、navigate、reload、close、click、type、read（读取 DOM 结构）、screenshot（页面截图）、get（获取状态）。基于 Tauri 内嵌 Webview 实现，支持选择器点击、表单输入与实时页面截屏，服务于 Web 页面自动化调试与视觉验证。
06
项目记忆 Project Memory
文件 + 管家跨会话记忆，每回合全量注入会话引导
MEM
.CodePapr/MEMORY.md项目记忆文件
工作区内的单一 Markdown 文件（三节：用户偏好与约束 / 技术栈与环境约束 / 架构与业务已知事实），硬上限 120 行 / 约 4000 tokens。内置记忆管家在交付（双信号门）与压缩前（无条件，20s 超时）两个卡点自动维护；密钥脱敏、注入指令 / 危险命令 / 超限 / 洗记忆操作拒写。
Agent 无
memory_* 工具，直写文件会被拦截拒绝；每回合直读文件渲染会话引导（保存后下一回合生效）。面板（上下文检查器 → 记忆）就是该文件的编辑器：预算条 + 保存 + 管家状态行。07
应用与会话辅助 App & Auxiliary
沙箱渲染提供交互式应用能力
APP
app_render / app_list / app_start / app_stop / app_deleteApp 模式
app_render：打开已写入
.CodePapr/apps/<appId>/ 的交互式应用（运行于沙箱 iframe，注入 Papr SDK）；搭配 app_* 系列工具管理常驻微应用的生命周期。文件必须用 write/edit/patch 落盘，app_render 只挂载。app_render 对子代理强制禁用（防止嵌套渲染）；只传 appId。权限、Agent、后端进程都写在 manifest.json 里。app_list 仅 App 模式：创建前查重、查看运行状态。编程 Agent 发现「能推什么」靠会话上下文，不靠 list。PUSH
app_publishAgent→App 推送
app_publish：向应用/插件的频道推送内容（看板、进度面板、画布等）。事件原子追加到应用
db.sqlite 的 inbox:<channel>（并发安全），应用已挂载时经 papr://event 实时送达（应用内 papr.events.on 接收）；未挂载时事件还会进入约 30 秒的短实时队列，应用随后打开（含被推送自动揭开）仍能实时收到，更晚打开则靠历史回放。除 Ask 外所有模式可用。怎么知道推给谁：不要调用
声明 inbox 后只能推已声明频道（传错即报错并列出可用频道）。
app_list。app_list 只在 App 模式可用，用来创建前查重、管后端。编程 Agent 看会话上下文「已启用插件」：只列出已启用且声明了 inbox 的 overlay，以及声明了 inbox 的全屏 App。payload 严格按其中的 description / example。没有 inbox 的自刷新小组件（股票条、时钟）不进上下文，也不要推。声明 inbox 后只能推已声明频道（传错即报错并列出可用频道）。
inbox:* 键只由 app_publish 写入，应用端只读；payload 上限 256KB，每频道保留最近 200 条。example 会截断后抄进上下文，保持说明书短。AUX
skill / question / todo / local_time_now会话控制
skill 加载外部技能规则；question 在 Plan 模式下向用户发起结构化多选提问；todo 维护实时任务进度清单；local_time_now 获取当前本地时间戳。
skill 路由至 skill_load；question 生成带选项卡片的交互式回调；各工具根据当前运行模式（Ask/Plan/Agent）由白名单控制可用性。08
Agent 权限矩阵 Agent Tool Matrix
最小权限原则按角色白名单严格隔离
主代理 任务主控 · 全量读写执行
MAIN
主代理 Main Agent 全量读写执行全功能
拥有除
graph 外的所有读写/执行工具。项目大纲浏览使用 list，符号定位使用 lsp，全局依赖与深层架构分析通过 task 委派给 Explore 子代理。在 Ask 只读模式下自动拦截文件写入与 Shell 执行；在 Plan 模式下开放 question 决策工具。从 LLM 工具定义中软隐藏
graph（保留底层注册供 UI 面板与子代理调用）。Ask 模式下通过 MUTATING_TOOL_NAMES 统一拦截写操作。子代理 独立 Session · 白名单过滤
EXPL
Explore 代码探索与架构分析 · 8 个只读工具只读分析
工具集：
read / read_image / list / graph / glob / lsp / diagnostics / grep。专属开放 graph 项目图谱分析能力，专门处理依赖溯源、影响面评估与符号查找，不具备写权限。注册时声明
exposeGraphToLlm: true 解除图谱软隐藏；多模态关闭时动态剥离 read_image。SCOUT
Scout 网络调研与文档查阅 · 4 个工具联网调研
工具集：
websearch / webfetch / browser / read_image。专注于外部技术文档搜索、网页浏览与参考资料下载，完全不访问本地项目代码。通过
webfetch save: true 将外部资源安全下载至 .CodePapr/downloads/ 目录供主代理引用。MNTR
Mentor 架构与算法决策 · 纯推理无工具
配置零工具（
{}）。完全基于主代理汇报的上下文进行高层架构设计、算法选型与复杂调试决策，不自行搜索代码，避免工具争抢与响应延迟。白名单为空对象
{}，系统自动返回空工具集；信息不足时指示主代理补充上下文。内部代理 系统运行时直接调用 · 不对任务暴露
VRFY
Verifier 目标验收器 · 4 个只读工具只读核验
工具集：
read / grep / glob / list。Goal 循环的自主验收器：核验执行记录并亲自检查产物文件，独立评估目标达成状态，杜绝完工偏差。由 GoalRunner 调度，专属配额：最多 6 轮工具调用、3 分钟超时、独立 Token 预算、关闭 Thinking 模式。
CMPT
Compactor 上下文压缩器 · 纯推理无工具
配置零工具（
{}）。在会话达到阈值时介入，基于完整历史记录提取目标、约束、已完成工作与待办事项，压缩为结构化恢复快照 JSON。隔离 skills 与 memory 注入，支持中途取消信号处理；若未配置快速推理模型，自动回退至规则压缩管道。