本地优先的 AI 编程助手——你提需求、看审批、做验收，AI 负责读代码、生成 patch、执行命令。
Cofree 是一个运行在用户本机的 Tauri 2 桌面端 AI 编程工具，面向独立开发者和小团队。
核心设计原则：
- 本地优先：文件读写、patch 应用、命令执行全部发生在用户机器上，不需要远程代理服务。
- 人工审批在环（HITL）：所有写盘和命令执行默认经过人工确认，AI 不会在没有授权的情况下修改代码或执行命令。
- 用户自带密钥（BYOK）：对接用户自有的模型 API Key 或本地模型网关，应用本身不托管模型请求。
- 可观察、可恢复：所有 LLM 请求和敏感动作写入本地审计日志，patch 应用前自动创建快照，工作流状态通过 SQLite checkpoint 持久化。
- 聊天页支持流式回复、
<think>折叠、工具调用状态展示、错误提示。 - 内置「通用 Agent」角色，可阅读代码、提出编辑、执行命令；用户可在设置页自定义 system prompt、工具权限、模型绑定派生新的 Agent。
- 支持长对话自动压缩与上下文预算管理，结合 SQLite checkpoint 实现中断后继续执行。
- 工具集：
list_files、read_file、grep、glob、git_status、git_diff、diagnostics、fetch。 - 读取工作区文件、目录枚举、内容搜索、Git 状态与差异。
- 支持
.cofreerc配置文件，可声明systemPrompt、ignorePatterns、toolPermissions、contextFiles等。 - 动态工作区刷新：会话过程中自动更新工作区概览和文件结构，确保 AI 始终看到最新的代码变更。
propose_file_edit：结构化编辑请求，生成 unified diff 并展示审批卡片。propose_apply_patch：直接提交 unified diff patch，同样走审批流。- 用户可在 diff 预览视图中批准、拒绝或补充意见，支持批量审批。
- patch 应用前先做预检并创建文件快照，失败时自动回滚至快照状态。
- 审批通过并应用后，系统自动触发工作区诊断。
propose_shell：向用户展示完整 shell 命令与超时设置，用户确认后才执行。- 覆盖构建、测试、git 写操作等所有命令类场景。
- 执行后展示 stdout / stderr / exit code。
- Rust 后端对灾难性命令模式（
rm -rf /、mkfs、shutdown等）做硬性拦截，即使审批通过也不执行。
- 审计日志：LLM 请求元数据与敏感动作日志在本地持久化，可在控制台页导出 JSON / CSV。
- Checkpoint 恢复：SQLite 存储工作流检查点，在中断后可继续执行。
- 文件快照：patch 失败时从
~/.cofree/snapshots/自动回滚，不依赖 Git HEAD。 - 控制台页可查看工作流阶段、工具调用时间线、请求统计。
- 支持协议：
openai-chat-completions、openai-responses、anthropic-messages。 - 支持多供应商、多模型配置，可手动维护或拉取模型列表。
- 可为不同 Agent 绑定固定模型，支持代理配置与"允许云模型"开关。
- API Key 通过 Rust 端加密存储至
~/.cofree/，文件权限0600，不写入localStorage。
| 工具 | 默认权限 | 说明 |
|---|---|---|
list_files |
auto |
列目录 |
read_file |
auto |
读取文件内容 |
grep |
auto |
内容搜索 |
glob |
auto |
文件模式匹配 |
git_status |
auto |
查看工作区状态 |
git_diff |
auto |
查看差异 |
diagnostics |
auto |
运行项目诊断 |
check_shell_job |
auto |
查询后台 shell 任务状态 |
propose_file_edit |
ask |
生成 patch，需审批 |
propose_apply_patch |
ask |
应用 unified diff，需审批 |
propose_shell |
ask |
执行 shell 命令，需审批 |
fetch |
ask |
拉取 URL 内容，需审批 |
update_plan |
内部 | 维护 TODO 计划，无工作区副作用 |
ask_user |
内部 | 暂停执行并向用户提问 |
auto / ask 类工具的默认权限可通过设置页或 .cofreerc 覆盖；内部工具始终可用，不参与权限配置。
在工作区根目录创建 .cofreerc 或 .cofreerc.json 文件可定制项目级别的行为：
{
"systemPrompt": "本项目使用 React 19 + TypeScript + Tauri 2.0",
"ignorePatterns": ["node_modules", "dist", "target"],
"contextFiles": ["README.md", "ARCHITECTURE.md"],
"toolPermissions": {
"propose_file_edit": "auto",
"propose_shell": "ask"
},
"workspaceRefresh": {
"enabled": true,
"turnInterval": 20,
"onFileChange": true
}
}配置项说明：
systemPrompt: 追加到系统提示的自定义指令ignorePatterns: 排除的文件/目录模式（glob 格式）contextFiles: 会话开始时自动加载的关键文件列表toolPermissions: 覆盖默认工具权限workspaceRefresh: 工作区上下文动态刷新配置enabled: 是否启用（默认true）turnInterval: 每隔多少轮次刷新（默认20）onFileChange: 文件修改后是否刷新（默认true）
| 层级 | 技术 |
|---|---|
| 前端框架 | React 19 + TypeScript |
| 桌面运行时 | Tauri 2.0 |
| 后端语言 | Rust |
| 前端构建 | Vite 6 + pnpm |
| 测试工具 | Vitest |
| 本地存储 | localStorage + SQLite (checkpoints) |
前置条件：Node.js、pnpm、Rust 工具链（参见 Tauri 文档）
# 安装依赖
pnpm install
# 本地开发（启动 Tauri 桌面应用）
pnpm tauri:dev
# 仅启动前端（Vite 开发服务器，端口 1420）
pnpm dev
# 运行测试
pnpm test启动后在设置页完成以下配置：
- 选择本地工作区目录。
- 配置模型供应商、API Key（或本地模型网关地址）。
- 按需调整工具权限，或自定义 Agent 的 system prompt 与模型绑定。
# 构建前端
pnpm build
# 构建 macOS 安装包（dmg + app）
pnpm tauri:build:mac
# 构建 Windows 安装包（msi + nsis）
pnpm tauri:build:win发布流通过 GitHub Actions 自动化：推送形如 v0.1.0（或任意 vX.Y.Z）的 tag 即可触发多平台构建矩阵（macOS Apple Silicon、macOS Intel、Windows x64）。若配置了 updater 签名密钥，还会额外上传 latest.json 与 updater 签名工件。
- 文件操作、patch 应用、命令执行均在本地完成，不经过 Cofree 服务端。
- 模型请求会把必要上下文通过 HTTP 发往用户配置的模型端点，不是完全离线。
- 路径边界：后端允许绝对路径和相对路径（含
..），文件操作无工作区边界限制。 - 命令黑名单：Rust 后端硬性拦截一组灾难性命令模式。
sendRelativePathOnly默认关闭（false），允许模型发送绝对路径；maxSnippetLines和maxContextTokens可限制上下文体量。
详见 docs/BUILD.md 和 docs/ARCHITECTURE.md。
| 文档 | 内容 |
|---|---|
| docs/PRD.md | 产品定位、核心页面、主流程、已实现能力 |
| docs/ARCHITECTURE.md | 技术架构、前后端职责、工具调用流程 |
| docs/BUILD.md | 本地开发、构建目标、发布流程 |