橘记（Orange）

Name: orange
Author: ciri667

橘记工作台主界面

橘记是一款面向个人知识工作的本地优先 Agent 笔记应用。它将用户选择的本地目录作为知识库，在桌面工作台中提供检索、问答、改写、草稿生成与知识整理能力。

笔记仍以用户自己的本地文件保存。Agent 默认工作区只读，可切换到工作区修改需审批或两种完全权限档；结构化文件变更支持审阅，真实命令及外部服务遵循独立的操作审批。

桌面端支持 macOS 与 Windows 11。前端开发服务可单独运行于浏览器，但本地目录、索引和 Agent 文件操作需要通过桌面端体验。

文档

完整的使用文档与开发者文档：https://ciri667.github.io/orange/

文档源码在 docs-site/，基于 VitePress，推送到 main 后由 GitHub Actions 自动部署。

功能

将本地文件夹连接为知识库，建立 Markdown 全文索引并浏览目录树。
在知识库根目录使用 AGENTS.md 作为项目级 Agent 说明书；橘记会在每次对话时自动读取（兼容旧的 ORANGE_AGENT.md）。
编辑 Markdown 和 TXT；预览 Markdown；查看、导出、重命名及删除本地文件。
在会话中检索已授权知识库、引用来源、显式附带文件，并按会话控制工具范围。
会话可开启“计划模式”：Agent 只用只读工具探索并先给出编号执行计划，经用户确认后才执行改动；IM 与定时任务不适用。
接入 OpenAI 兼容接口、Ollama 等模型服务；模型密钥存入系统安全存储，而非项目数据库。
结构化文件工具生成文本 diff 或文件管理影响清单，经严格磁盘冲突检查后应用；完全权限无需审批档自动应用本次新变更。真实命令使用独立非交互进程，需审批档逐次确认。
可选飞书/Lark 长连接集成：在 IM 中发起检索或写入请求，待写入变更仍需审批确认。
提供本地审计、分级日志和按知识库管理的跨会话记忆；记忆默认关闭，并会过滤常见敏感信息。

数据与隐私边界

内容	处理方式
笔记文件	保留在用户选择的本地目录，移除知识库授权不会删除原文件。
检索范围	工作区档限会话所选知识库及启用的 Skill 资源，完全档可访问工作区外资源。
模型密钥	保存到操作系统 Keychain/安全存储；界面与日志不回显明文。
云端请求	仅在启用云端模型并发起 Agent 请求时发送给所配置的模型服务。
写入变更	结构化工具校验路径、hash 和目录清单；真实命令及外部服务按操作审批执行，不保证其内部修改逐项 diff 或失败无副作用。

快速开始

前置条件

Node.js 20 或更高版本
Rust stable 与当前平台的 Tauri 构建依赖
Windows 11：安装 Visual Studio 2022 的“使用 C++ 的桌面开发”工作负载和 Microsoft Edge WebView2，并使用 stable-msvc Rust 工具链
仅在使用飞书/Lark 集成时：Go 1.22 或更高版本

安装依赖并启动前端开发服务：

npm install
npm run dev

启动完整桌面开发环境：

npm run desktop:dev

Windows 首次安装 Rust 后需要重启终端或 IDE，使 cargo 加入 PATH。可用以下命令确认环境完整：

rustup default stable-msvc
npx tauri info

首次进入应用后，依次完成：

在“知识库管理”中添加一个本地目录。
在“模型设置”中添加并启用模型服务，保存 API Key 或配置本地 Ollama。
新建会话，确认当前会话的知识库范围后开始提问。

开发与验证

# 前端类型检查和生产构建
npm run build

# Rust 单元测试
npm run rust:test

# 重新生成 macOS App图标
npm run icon:macos:generate

# 构建仅供本机验收的 macOS 应用包（无需证书的 ad-hoc 签名）
npm run desktop:build

# 构建用于本机安装流程验收的 DMG（无需证书的 ad-hoc 签名）
npm run desktop:build:dmg

# 构建正式发布的 macOS 桌面包（必须设置 Apple 发布签名身份）
ORANGE_RELEASE_SIGNING_IDENTITY='Developer ID Application: 名称 (TEAM_ID)' npm run desktop:build:release

在 Windows 上，npm run desktop:build 会使用 src-tauri/tauri.windows.conf.json 构建 NSIS 安装包，不需要 macOS 签名配置。Windows 日常开发只需运行 npm run desktop:dev。

desktop:build 不读取或创建钥匙串证书；Tauri 会使用无需证书的 ad-hoc 签名，并只生成可直接运行的 .app。如需验证安装流程，使用 desktop:build:dmg 生成包含 Applications 快捷方式的本地测试 DMG，将 Orange.app 拖入该快捷方式即可安装。两者均不能用于对外分发。对外发布前须使用 desktop:build:release，该命令会生成 .app 与 .dmg，并要求完成 Apple 签名和公证流程。

Vite 开发服务默认监听 http://localhost:5173/。前端变更请至少执行 npm run build；涉及 Rust 或文件系统行为时，请同时执行 npm run rust:test。

可选：即时通讯集成

IM 网关由独立 sidecar 提供。构建所有已注册 provider：

npm run sidecar:im:build

也可按平台单独构建：

npm run sidecar:feishu:build
npm run sidecar:qq:build
npm run sidecar:weixin:build
npm run sidecar:wecom:build

产物会生成到 src-tauri/sidecars/bin/，该目录不提交到仓库。首次使用 IM 网关或打包前，请先完成构建。

当前支持：

飞书/Lark：长连接订阅 im.message.receive_v1 和 card.action.trigger。
QQ 官方机器人：WebSocket 模式。在 q.qq.com 创建机器人，填写 AppID/Secret；发送 API 可能要求配置出站 IP 白名单。
个人微信：腾讯官方 iLink / OpenClaw 接口，设置页扫码登录。需要较新的手机微信，且客户端包含 ClawBot 插件。
企业微信：智能机器人 WebSocket 长连接。在企业微信后台「管理工具 → 智能机器人」以 API 模式创建，填写 BotId / Secret；无需公网回调。

审批卡片仅飞书可用；QQ、微信和企业微信使用“详情 / 确认 / 取消 <编号>”文字指令。群聊中仅发起变更的用户可以确认或取消。

项目结构

src/
  agent/          Agent 会话面板、工具轨迹与引用
  diff/           写入前的变更审阅
  editor/         Markdown/TXT 编辑与预览
  knowledge-base/ 知识库、目录树与搜索
  settings/       知识库、模型、写入策略、Skills 与 IM 设置
  shared/         共享类型、Tauri API 适配、日志与浏览器 mock runtime
  workspace/      工作台状态与交互编排
src-tauri/
  src/            Tauri commands、Agent runtime、SQLite/FTS5 与安全文件操作
  im/             IM provider 路由与网关接入
  sidecars/       独立 sidecar 源码；构建产物不提交
assets/readme/    README 使用的截图与其他文档资源

贡献

欢迎通过 Issue 报告问题或提出建议，也欢迎提交 Pull Request。提交前请：

说明改动对本地文件、索引、模型请求或写入确认流程的影响。
运行与改动相符的验证命令，至少包括 npm run build；涉及 Rust 时再运行 npm run rust:test。
为可见界面改动附上截图或录屏；不要在 Issue、日志或截图中包含 API Key、笔记正文或个人信息。

贡献流程请参阅 CONTRIBUTING.md。仓库暂未提供独立的行为准则和安全漏洞报告流程；对外发布前建议补齐这些文件并在此处链接。

许可证

本项目采用 Apache License 2.0 开源。