Emerald

Emerald

聊天背后的数据库。 一个本地文件数据库，由你和 AI 模型共同填入；每张表都有真正的类型和约束，因此你们整理出的内容始终准确。 免费软件，采用 AGPL-3.0。仅限桌面端，无服务、无需账户。getemerald.dev

Emerald 是什么

• 文档就是一个文件。 .emd，是存储在你磁盘上的真正 SQLite 数据库，可以按文件选择以 SQLite 字节或文本形式存储。sqlite3 可以打开它，架构有文档说明，普通工具可以读取每张表，包括你声明的表。
• 为你保留的任何内容声明一张表：一笔扣款、一份工资、一册书、一个里程碑。它是一种格式：一张具有真实类型、并为你声明的每条规则设置 CHECK 的真正表，而不是模板。写入时，不符合要求的值会被拒绝，而不是等到之后才发现。
• 格式之间可以关联，并据此计算数据：根据起止时间计算时长，汇总指向此处的各行数据。总计绝不会悄悄跳过无法读取的行。
• 声明是必须成立的规则：收据总额等于刷卡金额，每一小时都已付薪。每条声明都会被证明、判定失败或标记为未检查；若未检查，会说明原因。
• 文件会按格式读取：电子表格、CSV、行数据 JSON 文件、Markdown 笔记或文件夹。列只需映射一次，并保存为读取器，每次都会检查。模型可以提供映射或位置，但绝不能提供值。
• 模型通过 MCP 在其中操作。 服务直接读取和写入文档，并使用结构化工具，而不是通用查询：任何文档都可用 28 个，搭配账本则有 85 个。每次写入在你确认提交前都是试运行；写入前会在文档旁保留副本；如果文档的架构版本早于服务，绝不会迁移，只会报告。
• 它会在对话中绘图。 让它显示工作表、看板或路线图，服务就会像应用一样绘制；支持 MCP Apps 的宿主环境中可见（Claude 桌面应用的 Code 选项卡和 VS Code 的 Copilot Chat 中均可查看）；其他地方则会以文本形式给出相同答案。
• 包是别人已经整理好的格式，并附带相应视图。Emerald 附带两个包：账本和开发包。创建并分享自己的包是下一步计划。
• 无需联网，也无需登录。 应用本身不会发起网络请求——无论是用于 AI 还是遥测；如果它曾发起网络请求，测试就会失败。你可以选择开启唯一例外：更新，默认关闭。开启后，它每天会向 GitHub 查询一次最新版本号；在 Windows 上，还会从其 GitHub 发布页下载较新的版本。帮助 → 立即检查更新会查询一次。你也可以使用这台机器上的本地模型运行时；只有在你点击后才会查找，并通过回环地址进行。

账本

• 为想要管理自己的钱、而不是被钱管理的人设计：把他们拥有的一切放在一个属于自己的地方。
• 读取你已有的文件：信用卡账单、银行导出文件、工资单、基金报告。
• 记录每笔扣款，并区分转账和支出、月度账单和一次性账单。
• 每笔总额都可以展开查看参与汇总的各行数据。
• 读取一整年的助学基金报告：其中一个月基金没有收到任何款项，尽管工资单显示已扣款。
• 不连接你的银行。你只需提供文件。

开发包

• 项目的记忆以行的形式记录：里程碑、单元、决策、待解问题和收件箱。

• 会话从这些行开始，而不是从聊天摘要开始。若请求与已做出的决策相矛盾，就按该决策作答。

• 一个项目的会话会在另一个项目的收件箱中留下一条备注，而该项目的下一次会话会从这条备注开始。

• Emerald 就是用它构建的：docs/memory.emd 是这个项目的记忆，每次处理此仓库的会话都会先询问它。

• 在仓库中设置它只需一条命令，在仓库文件夹中运行即可（从 0.2.0 起）：

  npx -y emerald-mcp init [path/to/document.emd]
  

  它会创建包含开发包的文档（默认为 docs/memory.emd，也可以指定其他名称；以文本形式存储在仓库中，因此会提交并显示差异），在 CLAUDE.md 中写入一个带标记的部分，包含会话开始时要询问的问题和每种格式的列；如果尚未安装 Claude Code 插件，还会写入两个钩子，在会话中打印 start_here 和收件箱。再次运行不会更改任何内容；格式发生变化后，它只会重写对应部分。

安装

目前有三种方式：

• 桌面应用，适用于 Windows 和 macOS，可从 最新版本下载。 .emd 文档会有自己的图标，双击即可打开。它未经代码签名：Windows 会显示 “Windows 已保护你的电脑”（点击 更多信息，然后点击 仍要运行；安装程序仅面向当前用户，不需要管理员密码），macOS 会提示 Apple 无法验证此应用（点击 完成，然后依次点击 系统设置 → 隐私与安全性、仍要打开）。0.1.2 或更早版本的 Mac 副本会改为显示 “Emerald 已损坏”，且没有“仍要打开”选项：在终端中运行一次 xattr -cr /Applications/Emerald.app，或者下载新版。每个版本都由此仓库的 发布工作流根据标签构建并附带证明，旁边还有一个 SHA256SUMS 文件：gh attestation verify <file> --repo kfireliyahu/emerald-emd 会向 GitHub 验证该文件是否由此工作流构建。安装程序的名称不含版本号（Emerald-Setup.exe、Emerald-arm64.dmg、Emerald-x64.dmg），因此 releases/latest/download/<name> 始终指向最新版本。 更新默认关闭：在关于中开启后，应用每天会向 GitHub 查询一次是否有新版本。Windows 上，应用随后会在后台下载更新，根据该版本发布的校验和进行验证，并在窗口顶部安静地显示已就绪；只有在你按下安装并重启后才会安装，并会在重新打开时恢复到你之前打开的文档。Mac 上，应用会提示有更新，点击下载会打开发布页面（Mac 更新程序需要经过签名的应用）。 从 0.1.2 起，手动更新可自动完成；更早的版本需要手动下载一次新版。

• MCP 服务，以 npm 包 emerald-mcp 的形式提供：只需在助手的 MCP 配置中添加一行，即可用于任何文档；若也要使用账本工具，请勿省略 --engine-only：

  claude mcp add emerald -- npx -y emerald-mcp --engine-only
  

• Claude Code 插件，包含服务、在对话中呈现的视图、用于与他人声明格式的技能，以及将项目的 start_here 和收件箱引入会话的钩子（它的运行内容）：

  /plugin marketplace add kfireliyahu/emerald-emd
  /plugin install emerald@emerald-emd
  

仓库

构建和运行

git clone https://github.com/kfireliyahu/emerald-emd.git
cd emerald-emd
npm ci                 # npm install works too; this is the reproducible form
npm run dev            # the app, in a browser tab
npm run test           # the whole suite
npm run build          # the app -> dist/, what the desktop shell serves
npm run desktop        # build everything and open the desktop window
npm run build:plugin   # the MCP server -> dist-plugin/server.mjs
npm run build:demo     # Emerald's page and the tours -> dist-demo/
npm run dist:win       # the Windows installer -> release/
npm run dist:mac       # the macOS disk image -> release/   (needs a Mac)

• 使用 Node 24 构建和测试。npm ci 会输出审计提示（来自 MCP SDK 和路由器；已记录）。首次运行任何会打开桌面窗口的程序时，都会下载一次 Electron 二进制文件；构建需要联网的只有这一次。
• 界面包括宽数据页面、列映射器、导入审核和存款表格，并且刻意不支持手机布局。在浏览器中，Chrome 和 Edge 通过 File System Access API 静默保存；Safari 和 Firefox 则通过下载保存。桌面应用在所有环境中都能静默保存。

此检出版本中的 MCP 服务

.mcp.json 指向带有 --engine-only 的 dist-plugin/server.mjs，因此，在此目录启动的 Claude Code 会话会自动发现它，并提示你批准一次。从其他位置启动：

claude mcp add emerald -- node /absolute/path/to/dist-plugin/server.mjs --engine-only

如需使用账本的工具，请不要加上 --engine-only。构建后的文件夹可独立运行——所有软件包都已打包其中，它就是当前的 npm 软件包——因此可在任何能运行 Node 的位置运行。docs/plugin.md 介绍了工具接口、已测试的宿主和相关规则。

目录内容

• docs/：规范、架构、数据模型、引擎和各领域的说明。docs/09-decision-log.md 记录了各项设计背后的原因；docs/memory.emd 则以行的形式记录了构建进度。
• docs/demo.md：页面、演示流程，以及其他页面如何嵌入其中。
• src/domain/ 是引擎，不导入 React、SQLite 或 DOM 中的任何内容；src/data/ 是存储层；src/ui/ 是应用；src/plugin/ 是 MCP 服务；electron/ 是桌面外壳；src/data/packs/ 是两个数据包。

问题与贡献

• 欢迎提交问题和参与讨论。
• 代码贡献需先签署贡献者协议；LICENSING.md 说明了原因。开放贡献后，最需要熟悉相关格式的人员参与的部分是导入映射和语言环境包。
• 切勿加入真实的账单文件。 测试样本均为合成数据，且测试会拒绝其他类型的文件。

免责声明

• 它负责计算，不提供建议。 Emerald 展示的内容均不构成财务、税务、法律或投资建议。它只会汇总你提供的数据，并指出不一致之处；该如何处理由你自行决定，也可以咨询你平时会寻求帮助的人。
• 请核对读取结果。 从工资单、账单、基金报告或收据中读取的数字，无论由代码还是模型读取，都可能有误。原始文档才是真实依据；Emerald 会将读取结果保存在文档旁，供你对照。
• 模型说的话由模型负责。 助手通过 MCP 操作文档时，其回复内容和写入请求均由该助手及其提供方根据各自条款决定，并非由本项目决定。Emerald 负责拒绝不合适的操作，并在每次写入前展示内容。
• 你的文件归你所有。 Emerald 会写入你打开的文档，并在其旁边保存副本，不会在其他任何位置创建副本。请像备份其他文件一样备份它；这里的任何内容都无法恢复丢失的文件。
• 无关联关系。 Emerald 与任何银行、发卡机构、基金、雇主、薪资服务提供商或 AI 服务提供商均无关联，亦未获得其认可，也不代表其行事。账本会读取这些机构提供的文件，无论文件采用何种格式。
• 按原样提供。 本软件不提供任何形式的保证，详见 AGPL-3.0 第 15 和第 16 节。桌面版未经签名，由此仓库的工作流构建；是否使用或从源代码构建，请自行判断。

隐私

Emerald 不收集任何信息。完整隐私政策请见 PRIVACY.md。

许可证

代码采用 AGPL-3.0-only 许可（LICENSE）；笔记和文章采用 CC BY 4.0 许可；格式声明、数据包和合成样例采用 CC0 许可。LICENSING.md 说明了各项内容分别采用何种许可、名称和标志不代表什么，以及如何获取商业许可。桌面应用的“关于”页面也说明了这些内容，点击“帮助”即可查看所有捆绑内容的第三方声明。