系统架构 · CodePapr

进程拓扑

运行时涉及四类可执行体：客户端（codepapr / codepapr-cli）、宿主（codepapr-server）、Node agent sidecar（agent-runtime.mjs，由宿主拉起）、以及宿主管理的各类子进程（LSP server、shell、MCP stdio server）。

桌面客户端 codepapr              CLI codepapr-cli
React+Monaco · @codepapr/core        ping/doctor/status/git/fs/
src-tauri/src/host.rs (RPC client)   shell/lsp/server/chat
        │        JSON-RPC 2.0，行分隔 JSON        │
        │        TCP 127.0.0.1（或 stdio）        │
        └────────────────┬─────────────────────────┘
                          ▼
           codepapr-server（宿主守护进程）
           handler.rs → initialize / ping + 159 个命名空间方法
           tasks.rs  → 串行任务队列
                          ▼
           codepapr-core（领域库，无 Tauri 依赖）
           workspace_fs · git_operations · shell · lsp
           symbols · db(SQLite) · snapshot · mcp_host · web
           agent_runtime → Node agent-runtime.mjs sidecar

启动

attach 或 spawn

设了 CODEPAPR_SERVER_URL → 直连，不拉子进程。否则按 CODEPAPR_SERVER_BIN → 同目录 → resourceDir → target/{debug,release} → PATH 定位二进制，执行 codepapr-server --port 0 --port-file <temp>/codepapr-server-<pid>.port；端口从 port-file 或 stderr 行 [codepapr-server] listening on 拿到（15s 超时、40ms 轮询），随后发 initialize。

关闭

固定顺序

lsp/stopAll → agent/stopAll → fs/stopWatcher → shell/stopAllBackground → mcp/disconnectAll → kill + wait（仅自己拉起的子进程；连外部宿主时不杀）。桌面端退出前先等设置落盘（轮询 db/settingsSaveState）。

层	拥有	不拥有
UI (React)	交互、面板、Agent 循环驱动、提示词组装	任何直接文件 / 进程 / 数据库访问
Tauri 客户端	`host.rs` RPC 客户端、`commands.rs` 代理；GUI 专属：`codepapr-app://` 协议、内置/无头浏览器、TTS、Stronghold 密钥、文件导出、App 安装与端口探测	文件系统、Git、Shell、LSP、MCP、快照、Web、主 SQLite
codepapr-server	方法路由、参数校验、事件广播、内存态密钥、串行任务队列	领域实现（全部委派给 core）
codepapr-core	所有领域实现与子进程生命周期	UI、协议层

两个例外允许桌面端直连 codepapr-core（path 依赖，跳过 RPC）：Papr App 存储（papr_runtime/app_storage.rs 直调 db::papr_storage_*）与密钥（明文只在客户端 Stronghold vault，经 secrets/import 单向推给宿主内存态存储，宿主不落盘密钥）。

JSON-RPC 协议面

行分隔 JSON-RPC 2.0，一行一个对象。--port <N> → TCP（--port 0 内核选端口，--port-file 落盘实际端口）；不传 --port → stdio。带 id 的行按请求/响应处理，无 id 的行当通知处理；连接断开时所有 pending 请求以 codepapr-server closed the connection 失败，当前不做自动重连。

命名空间	方法数	代表方法
`fs/*`	23	readTextFile · writeTextFile · listFiles · search · startWatcher
`git/*`	8	status · diff · log · stage · commit · branchCheckout
`shell/*`	17	execute · startBackground · openSession · sendCommand
`lsp/*`	12	startServer · request · diagnostics · batchSymbols
`symbols/*`	8	definition · references · hover · checkSyntax
`db/*`	45	loadSettings · saveMessageBatch · paprStorage*
`snapshot/*`	11	ensure · create · diff · restorePlan · restoreExecute
`mcp/*`	10	listTools · callTool · updateSettings · disconnectAll
`agent/*`	5	start · send · stop · respondPermission
`web/*`	3	search · fetchUrl · downloadFile
`task/*`	2	enqueue · poll
`secrets/import`	1	写入内存态密钥

共 159 个命名空间方法 + initialize / ping；未命中报 Unknown JSON-RPC method。事件以 {"method":"event","params":{"event","payload"}} 通知回传并原样转发到 Tauri 事件总线，事件名不变：workspace-files-changed、project-stats-progress、codepapr://lsp-managed-status、agent-runtime://frame/exit/permission-request/permission-cancel/workspace-mutated、mcp-confirm-request。

数据流与持久化

一次工具调用

React → invoke() → commands.rs
  → host::call("fs/readTextFile")
  → TCP → handler.rs → 校验
  → codepapr_core::workspace_fs
  → 原路返回 result → UI

一条事件

watcher.emit("workspace-files-changed")
  → server 包装为 event 通知
  → host.rs dispatch_incoming_line
  → app.emit(event, payload)
  → React listen(event, ...)

库	路径	内容
App DB	`~/.codepapr/codepapr.sqlite`	全局设置、provider/model、最近工作区
Project DB	`<workspace>/.CodePapr/project.sqlite`	会话消息、checkpoint、ProjectGraph 缓存
Papr App DB	`<appDir>/db.sqlite`	单个 .papr 应用的键值存储与 inbox

三处均由 codepapr-core::db 打开，即宿主进程在写（App 存储是唯一在客户端进程内直连的例外）。旧版 state.json/project.json 首次打开或保存时自动导入 SQLite。

App / 插件市场与作用域

.papr 应用从官方注册表 mmrqwe/codepapr-apps → registry.json 安装到 global 或 workspace 作用域。

GLOBAL

`~/.codepapr/apps/<appId>/`

跨项目通用工具，全局默认权限。

WORKSPACE

`<workspace>/.CodePapr/apps/<appId>/`

项目专属，可随仓库分发；同 appId 时覆盖全局安装，前端/后端/存储三者始终指向同一目录。

每个应用一个 origin codepapr-app://<appId>/；CSP 由两轴权限（本地访问 × 网络）推导，网络关时 script-src 不放行 https:；db.sqlite（及 wal/shm）永不通过协议输出；一个目录要算应用，需目录名合法、manifest.json 可解析、入口文件存在。

上下文分层（TypeScript 侧）

领域副作用交给宿主之后，提示词组装与缓存分区仍在 @codepapr/core（TS 侧）。完整细节见 docs/adr/ADR-001…016。

层	内容	何时变
01 系统核心	系统提示、工具定义、`AGENTS.md`	会话内冻结
02 会话引导	Skills 目录、插件 inbox 摘要、项目记忆段（MEMORY.md）	MEMORY.md 保存或压缩后下一回合换
03 会话状态	检查点（任务进度）+ 近期对话	压缩时重写
04 本轮对话	当前用户消息、工具结果	只往尾部追加

项目记忆的唯一权威是工作区文件 .CodePapr/MEMORY.md：内置记忆管家在交付 / 压缩前两个卡点维护它，每回合全量注入 02（保存后下一回合生效）；Agent 无记忆工具，直写文件会被拒绝。面板即该文件的编辑器。

CodePapr 不是单体应用，是宿主守护进程 + 多个瘦客户端