# heartcode 中文文档

规范地址：https://npmcn.com/package/heartcode/

版本：0\.1\.45
npm 元数据更新时间：2026-11-03T19:26:04.432Z
中文译文更新时间：2026-11-03T20:15:24.755Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/heartcode
原文对照：https://npmcn.com/package/heartcode/?lang=original
项目主页：https://github.com/p32929/HeartCode#readme
源码仓库：https://github.com/p32929/HeartCode

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.2 MB，52 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-10-27T22:47:52.742Z
- 最新版本发布：2026-11-03T19:26:04.298Z
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

用于任何本地或openai兼容模型的编码CLI，包括没有工具调用的小模型。

## 安装

```sh
npm install heartcode
```

也可以使用：`pnpm add heartcode`、`yarn add heartcode`、`bun add heartcode`

## README

# HeartCode

用于终端的编码代理，可与任何openai兼容的模型一起工作。

**零依赖关系。** 中没有 `node_modules`，没有安装脚本，没有导入包 在你背后：只有Node.js（20或更新）和HeartCode自己的代码。你安装的是 你能读到的。

![HeartCode in the terminal](https://res.cloudinary.com/m0jnrul4/image/upload/v1793485425/Screenshot_2026-11-01_at_2.23.35_AM.png)

## 我为什么要这么做

不与其他编码cli竞争。我做它是为了自己用，因为那些我 我做了我需要做的事：

-   **没有依赖，所以没有供应链攻击。** 使用您的文件、密钥和 您的shell。大多数都会拉入数百个npm包，它们中的任何一个，或者它们中的任何一个包 依赖，可以被劫持并在更新中发送恶意软件。HeartCode没有：no `node_modules`，没有安装脚本，只有Node.js和HeartCode自己的代码。没有什么 再给别人下毒，你就能看到你写的所有东西。
-   **我使用过的其他cli都没有这样做**，所以HeartCode做：
    -   **在您的模型中自行旋转，跨提供商。** 给它一个免费的清单 包括)。当一个达到速率限制，下降或失败时，下一个从另一个应答 提供者优先，然后继续工作。状态栏中的一个栏显示何时有回退响应。
    -   **搬到更大的模型，而不是忘记。** 当谈话超出了模特的范围 上下文窗口，它在总结任何内容之前切换到一个有空间的模型。
    -   **在构建之前进行研究。** 它假定记忆的内容已经过期，并读取 首先是当前的官方文档，而不是博客或内存。
    -   **学习，每个项目，并保持它。** 它读取的每个网页都是完整的 `.heartcode/research/`． 当一项任务结束时，它会把值得知道的内容作为笔记保存下来 （`.heartcode/memory/`)，在后台删除垃圾和废弃文件，同时 你继续。它修复的错误变成了 教训是不会重复的。下一个任务从已知的东西开始，而不是再次搜索。
    -   **在调用它完成之前检查它的工作**首先是一个计划，每次改变后都要运行，然后是另一个 根据您的要求对结果进行建模。兜圈子把工作交给 你的下一个型号；只有你（Esc）停止它。
    -   **从薄弱的和本地的模型中得到好的结果。** 不能调用工具的模型是引导步骤 的一步。按行号编辑保存不能完全重复文本的模型。每个模型的 能力来自 [models.dev](https://models.dev/)，所以不需要花时间去寻找答案。
    -   **只发送需要的东西。** MCP工具在使用之前都是名字，旧的工具输出变成一个 指针指向其已保存的文件，并在任务需要时到达指南。
    -   **在电报上告诉你** 当一项任务完成、失败或等待你时，你可以走开。
    -   **从来没有发送 `max_tokens`**，所以没有供应商会在你没有选择的情况下缩短回复时间。

### 剩下的就是你所期望的

-   **任何openai兼容的提供商**比如OpenRouter、Groq、NVIDIA、Gemini、Ollama、 LM工作室，你自己的代理…
-   **设置在网页上** 在您自己的机器上(`/settings`)，而不是通过编辑配置文件。
-   **可由其他工具和AI代理使用**： `heart -p` 无头运行一个任务，比如 `claude -p` (见 [SKILL.md](https://npmcn.com/package/heartcode/SKILL.md)）.
-   **记录你需要的，没有别的**： 7种，每一种都是自己打开的(都是由 默认)：请求、工具和命令、模型选择、代理的决定、错误、 谈话,调试。在设置页面上阅读它们，搜索和生活。
-   **需要技巧，MCP服务器和钩子** 在Claude Code的格式中； `/import` 把你的带过来。
-   **告诉你什么时候有更新的版本** （每次NPM启动时，在状态栏中检查）： `/update` 显示更改的内容，并按照安装HeartCode的方式安装它。把它关掉 `/settings` →将军。
-   **一个精心安排工作的人**将“Pick”设置为“orchestrator hands out”， 每条消息都以您选择的模式开始（快速、便宜的模式就足够了）。它的答案 如果可以，立即执行（“hi”不需要其他模型），否则将工作交给任意一个 它认为你的模型适合它。它知道每个人能做什么，也知道自己在larena的位置 公众的排名。你的模型显示了每个模型的编码、Web应用和视觉得分。
-   **默认情况下有纪律地工作**它的规则(来自Karpathy的指导原则，Grill Me， 超级大国（马尾辫和穴居人）在建造之前会问，首先找到bug的根本原因， 编写最少有效的代码，只更改任务需要的部分，在说完成之前进行验证， 然后停下来，简短地回答。一种技能 `use: always` 为每条消息添加自己的规则。
-   **选项卡** （`Alt+T`)，每个都有自己的会话，并将工作的工作树分开。
-   **后台有服务器和观察者**：模型启动一个并继续工作，读取它的 在需要时输出，并停止它。 `Alt+B` (或 `/background`)显示他们的日志在输入的上方， 每个标签（←/→或点击开关），而你的工作；没有什么能比HeartCode更长久。
-   **`/context`**：内容填充上下文窗口，部分地（系统提示、工具、消息、工具） 结果)和最大的单件。

## 我如何设置和使用它

### 1\. 安装

从npm:

```sh
npm install -g heartcode
```

或者从来源：

```sh
git clone https://github.com/p32929/HeartCode.git
cd HeartCode
npm start
```

`npm start` 链接的 `heart` 命令到那个文件夹，所以a `git pull` 更新它。

### 2\. 运行 `heart`

在你想从事的项目中：

```sh
cd ~/code/my-app
heart
```

### 3\. 打开设置页面

类型 `/settings`． 设置页面将在浏览器中打开。显示的链接是您的机器 网络地址(如 `http://192.168.1.108:43135/?t=…`)，所以它从另一个设备上打开 同样的网络：通过SSH在服务器上的HeartCode，在笔记本电脑上的页面。只有那个链接有效： 它有一个密钥，页面只回应这台机器自己的地址。正在运行的 HeartCode会立刻发现你的改变。

![The settings page](https://res.cloudinary.com/m0jnrul4/image/upload/v1793485584/8396c407-f5f8-48af-a242-0b5cbc1c0331.png)

侧边栏分为四组：

-   **模型**： _你的列表_ （HeartCode使用的模型，按顺序排列）和 _供应商_ (他们 来自)。
-   **一般**： _设置_ (不用问它就能做什么，终端颜色，特征，思维 努力，语音输入，网络搜索：您自己的搜索和引擎的顺序，以及哪些外部工具已经准备好了)和 _状态栏_ (拖放什么的 底线显示，与实时预览)。 **通知**:电报。
-   **技能**， **MCP服务器** 和 **系统提示**： HeartCode可以做什么以及它是如何被告知的。
-   **先进的**： _日志_ （七种，各开或关，一个观看器）和 _文件_ （其余的设置，作为文件）。

### 4\. 添加一个提供者并选择模型

在 **模型→供应商**：

![The settings page](https://res.cloudinary.com/m0jnrul4/image/upload/v1793485944/HeartCode-Settings-11-01-2026_02_28_AM_1.png)

1.  **添加提供者**：它的名称、基础URL和API密钥。选择其中一个预设来填充URL。
2.  **选择要使用的模型**：单击一个模型将其添加到您的列表中。我使用免费模型。

### 5\. 把你的清单按顺序排好

在 **模型→您的列表**：

1.  **按上下文和能力排序。** 单击 _能力_ 列,然后 _上下文_: 能做得最多的模型首先出现，其中最大的上下文窗口首先出现 点击列将打破之前的联系；再按一次可以倒转，第三次可以 下降)。点击 **保存订单** 为了保存它。
2.  **再重新安排一下。** 拖动一行来移动它。#1是HeartCode使用的；其他的是 它的退路，按顺序尝试。
3.  **测试它们** (可选): **测试所有** 发送每个短消息，并显示真正的答案。 每次测试等待10秒； **测试等**上面的列表改变了这一点。
4.  **它们进行过滤** （可选）：按名称、提供商、测试结果（works、doesn't、not tested或一个） 错误如402)，语境，工具，思维，图像或自由。 **测试N** 然后只测试那些 所示, **只使用这N个** 使它们成为HeartCode使用的模型，按照您看到的顺序 请留在“提供者”下)。过滤到工作的，按作品排序？，只使用这些：HeartCode使用您的 工作模型，最快优先。

如果一个模型说 _没有找到_ 在models.dev, **重试** 再查一遍，或者 **设置** 告诉 心脏编码它能做什么。

### 6\. 可选：通知和日志

-   **通知**一项任务完成、失败或等待你完成时的电报信息。制作一个机器人 与 [@BotFather](https://t.me/BotFather)，粘贴其令牌，在bot中按Start，然后 HeartCode找到你的聊天记录。
-   **高级设置→日志**：只打开你需要的类型（请求，工具和命令，模型选择） 代理的决定（错误、对话、调试），并在那里读取它们：通过运行、搜索、实时。 超过3天的日志将被删除（您可以更改）。

### 7\. 回到HeartCode

回到终点站。当设置页面打开时，HeartCode显示一个对话框并等待。 您的更改已经在里面了。

### 8\. 按“Enter”键停止设置界面

**关掉** 选中：按“Enter”。页面停止，心脏代码再次属于你。

![The settings dialog](https://res.cloudinary.com/m0jnrul4/image/upload/v1793486060/Screenshot_2026-11-01_at_2.34.15_AM.png)

### 9\. 发送“Hi”作为测试

类型 `Hi` ，按“Enter”。等待回复：您的模型有效。

### 10\. 开始使用它

使用HeartCode像任何其他编码代理：要求它读取，更改，运行和修复的东西在您的 项目。 `/` 显示每个命令， `Shift+Tab` 无需请求就能改变它的行为， `Esc` 停止 它, `heart --help` 列出所有其他的东西。当它工作时，离开对话的命令 独自一人(`/help`， `/cost`， `/diff`， `/select_model`， `/settings`， `/tab`， `/exit`马上跑；这个 改变它的人(`/compact`， `/rewind`， `/resume`等它做完再说。采摘者，问题和什么 命令显示(`/help`， `/context`， `/diff`…)在对话中打开； `Esc` 关闭它。

## 谢谢

我从其他编码代理和他们遇到的问题中学到了很多HeartCode处理的东西 第一。谢谢 [Reika](https://github.com/alexwkleung/reika) (它的测量结果很小 模型：发送“no, do this instead”作为你自己的消息，诚实地计算代码的令牌， 保留提供商的提示缓存，检查哪些使用了更改后的函数，保存哪些模型 压实前发现)， [OpenCode](https://github.com/anomalyco/opencode)， [克莱因](https://github.com/cline/cline)， [OpenClaw](https://github.com/openclaw/openclaw) 和 [π](https://github.com/earendil-works/pi)，他们向我展示了许多这样的用例。

## 许可证

[麻省理工学院](https://npmcn.com/package/heartcode/LICENSE)

## 常见问题

### heartcode 是什么？

用于任何本地或openai兼容模型的编码CLI，包括没有工具调用的小模型。

### 如何安装 heartcode？

在项目目录运行 npm install heartcode，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 heart、heartcode，可以用 npx heart 直接运行。

### heartcode 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/heartcode 是否存在。

### heartcode 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### heartcode 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### heartcode 可以商用吗？

heartcode 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### heartcode 还在维护吗？

最新版本 0\.1\.45 发布于 2026/11/04（今天）；至今共发布 27 个版本，其中过去 12 个月发布了 27 个；首次发布于 2026/10/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。