# @balacode/mental 中文文档

规范地址：https://npmcn.com/package/%40balacode/mental/

版本：0\.14\.0
npm 元数据更新时间：2026-10-30T21:15:44.512Z
中文译文更新时间：2026-11-09T20:58:16.848Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.7 MB，153 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.13\.0
- 运行依赖：0 个
- 首次发布：2026-08-26T18:39:37.978Z
- 最新版本发布：2026-10-30T21:15:44.343Z
- 近 30 天下载量：1733（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 25 个）

## 中文简介

永远不要重建你离开的地方 编码剂的本地第一连续性——恢复、决定和残留物不能看到。 CLI、MCP和特工技能.

## 安装

```sh
npm install @balacode/mental
```

也可以使用：`pnpm add @balacode/mental`、`yarn add @balacode/mental`、`bun add @balacode/mental`

## README

![Mental CLI](https://npmcn.com/package/%40balacode/mental/assets/logo.png)

# 心理辅导

**我打进精神**

永远不要重建你离开的地方.

本地首个续作 你和你的编码代理.  
CLI · MCP · 代理技能 · Cursor, Claude Code, 副驾驶, Codex, OpenCode.

[![npm version](https://img.shields.io/npm/v/@balacode/mental.svg)](https://www.npmjs.com/package/@balacode/mental) [![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/%40balacode/mental/LICENSE) [![zero runtime dependencies](https://img.shields.io/badge/deps-0-brightgreen.svg)](https://npmcn.com/package/%40balacode/mental/package.json) [![Agent Plugins 1.0.0](https://img.shields.io/badge/Agent%20Plugins-1.0.0-111111.svg)](https://agent-plugins.org/specification)

[快开始](https://npmcn.com/package/%40balacode/mental/#readme-quick-start) • 妇女 [文档](https://npmcn.com/package/%40balacode/mental/docs/README.md) • 妇女 [研究](https://npmcn.com/package/%40balacode/mental/docs/research.md) • 妇女 [技能](https://npmcn.com/package/%40balacode/mental/skill/mental/SKILL.md) • 妇女 [财务问题](https://npmcn.com/package/%40balacode/mental/#readme-faq)

Git 记录 **什麽** 换了 精神CLI记录了其他情况:简历、决定无法解释. **是你的探员给你写的.** 您输入 `mental` 当你想要的脉搏.

```text
$ mental
🧠 Ship the pointer, not the dump — open loops: none
Against PLAN.md

Now     Resolver landed  (today)
Git     main (dirty)
        feat: UUID bindings survive a repo move
Hops    2
Needs eyes
  [verify] Resolver tests not reviewed
In the air
  [direction] Tom said ship the pointer
Later
  [thread] Come back to MCP
Unsettled
  [open] Heartbeat only, no standing TUI
Settled
  UUID bindings survive a repo move
```

一发. 然后离开 不是菜单 不是一个拖拉机 可选 `mental dashboard` 在同一文件中打开本地主机页面.

## 快开始

PowerShell, cmd.exe, Windows 终端, Git Bash, macOS, 和 Linux :

```text
npm i -g @balacode/mental
mental install
mental doctor
```

礛 `cd your-repo` 类型 `mental`。 npm 拥有每个 平台; `mental install` 复制代理技能/规则并创建本地数据 骨头 严格 PowerShell 策略: 使用 `npm.cmd` 编号 : `mental.cmd`。 。 。 .

在Windows上从"精神"0.8.1升级还是更高? 运行 `mental-repair.cmd` 一次 之后 `npm i -g`隔离只指印有精神上的发射器 可以阴影npm。 日记留. [升级](https://npmcn.com/package/%40balacode/mental/docs/install.md#upgrade-already-installed)。 。 。 .

安装后,代理在工作时会分录、决定和记录残留物。 你没有第二个日记.

未瞄准的 npm 包 [`mental`](https://www.npmjs.com/package/mental) 是一个不同的项目。 安装 **`@balacode/mental`**二进制是 `mental`。 。 。 .

### 粘贴到您的代理

工作于 Cursor, Claude 代码, Copilot, Codex, 以及任何可以安装插件或运行外壳的:

```text
Install Mental CLI with npm. Do not clone the GitHub repo to install. Do not install from a git clone or plugin cache. Never run a .mjs file — Windows will ask what to open it with.

Fresh install (PowerShell, cmd, Windows Terminal, Git Bash, macOS, Linux):
  npm i -g @balacode/mental
  mental install
  mental doctor

Existing Windows install from Mental 0.8.1 or older (one-time migration):
  npm i -g @balacode/mental
  mental-repair.cmd
  mental install
  mental doctor
  (If PowerShell blocks scripts, use npm.cmd and mental.cmd explicitly.)

Mental CLI is a local-first continuity layer. Git records what changed; Mental records where we left off, why a decision was made, and what is still in the air. After install, you write it on my behalf — I do not journal by hand.

The repo is an Agent Plugins 1.0.0 package (https://agent-plugins.org/specification): plugin.json at the repo root, skills-only. Hosts load skills/mental-setup (install the CLI). The full procedure lives in skill/mental and is copied by `mental install` — not plugin-discovered. Native plugin does not start MCP. Do not start a plugin MCP server.

If this client has a native plugin install, use only that host's flow (do not run other hosts' `/plugin`, `copilot plugin`, or Command Palette steps from this session). npm owns the executable; `mental install` only refreshes the copied skill/rule/config. Run the fresh-install block, or the Windows migration block for an existing 0.8.1-or-older install.

The plugin is discovery. npm is the source of truth for the executable; the install command is the source of truth for the copied procedure. After doctor, re-run `mental doctor --json`. If anything is not ok that `--fix` can repair, run `mental doctor --fix --json` once (home skills/rules + git excludes only — never `--project` or optionals). Then tell me remaining checks. Follow the Mental skill copied by install — not the plugin bootstrap.

Missing Mental must not block my coding task (fail open): continue the task, then tell me to run the fresh-install block. Never execute the package's .mjs file directly.

After doctor, ask whether I want optional hooks or time tracking, and whether MCP is needed for this client. Give a one-liner for each, then wait — never run `mental option … on` until I say yes this turn.

- hooks: session-start snippets so a new chat loads Mental status (default off)
- MCP: register `mental serve` for tool-only agents that cannot shell the CLI (skip if this client can run `mental`)
- time tracking: optional automated project record — wall/billable, private + customer-ready descriptions, dated client export (default off)
```

为每个主机安装插件( 您, 不是代理粘贴) : [文件/安装](https://npmcn.com/package/%40balacode/mental/docs/install.md#install-as-a-plugin-you-this-host)。 。 。 .

### 重放这个

`package.json` `version` 这是真理的来源。 弹出 `node scripts/bump-version.mjs X.Y.Z`,则 `--check`标记 **仅限** `vX.Y.Z`当心 `Release` 工作流程。 发布要到:

```bash
npm view @balacode/mental version
```

等于此数 `package.json` 字符串( 无) `v`) (中文(简体) ). 代理规则 : [`.cursor/rules/release.mdc`](https://npmcn.com/package/%40balacode/mental/.cursor/rules/release.mdc)。 。 。 .

## 要点

-   **代理是文员.** 安装后, 一个技能 + 微小的总是在规则上命令您的编码代理拨打 `mental … --json`并不是每个聊天转弯。 不是隐藏的钩子。 插件只是发现( E)`skills/mental-setup`);该程序由 `mental install`。 。 。 .
-   **脉来而出,非一粪也.** `mental` 编号 : `heartbeat --json` 将恢复 + 最后的结果 + git + 残留 + 开放式决定. [51分钟](https://npmcn.com/package/%40balacode/mental/docs/benchmarks.md) 在一个新的过程.
-   **Markdown是真理的来源.** OKF 文件输入 `~/.mental`。 SQLite 是衍生缓存。 删除 db 将一无所失.
-   **身份能活下来.** UUID 进入 `bindings.json`,而不是文件夹路径。 两个同源的克隆人共享一个大脑 直到你 `split`。 。 。 .
-   **无法打开 。 私人默认.** 缺少的智力CLI 不得屏蔽编码. 永远不要让店铺。 永远不要写秘密.
-   **小时是可选的.** 默认关闭。 代理生成私人 + 客户准备描述, 时钟墙/ 账单,并在任务边界刷新记录 。 真正的模糊性使用一个渲染器安全而单选的问题;否则抓取会自动进行. `--new` 运行另一个时钟; 过时的客户端导出省略私人细节 . [音轨](https://npmcn.com/package/%40balacode/mental/docs/track.md)。 。 。 .

## 谁写

| 你个 | 你的探员 |
| --- | --- |
| 类型 `mental` 脉搏 | 真实任务边界上的日志 |
| 问“我们离开哪里了?” | 记录限制未来的决定 |
| 安装一次 | 记录浮出水面的残留物 |
| 读取收据 | 当另一个特工可能已经写作时进行回推 |

在使用精神CLI的转弯后你可以看到这一点:

```text
🧠 **Mental**
- 📓 **Journal** › *recorded* › Resolver landed
- 🚦 **Attention** › *recorded* › Tom said ship
```

同样的CLI,如果你曾经打它自己。 同样的文件.

## 为什么会这样

周一早上,一个新的代理,另一个回购——有人通过聊天重建意图 `git log`重建就是税 这就是开发者所感受到的心理煎熬: 验证最后的代理,决定下一个代理可以触摸到什么, 并持有残留物跨越跳跃。 精神CLI把它删除.

| 你已经有了 | 心理综合症 |
| --- | --- |
| Git 历史 | 准确的恢复行 |
| `PLAN.md` /问题 | 决定不能解释 |
| 聊天( 下次会议结束) | 注意残留物,已记录(封顶为7) |

后二年量所税. 使用 Cursor 的有经验的开发者相信它们 **转快20%** 并且曾经 **较慢19%** (单位:千美元)[METR 2025 (英语)](https://arxiv.org/abs/2507.09089)) (中文(简体) ). 生产力评级在流动和认知负荷减少时保持([维拉和布兰科 2026年](https://arxiv.org/abs/2605.23135)) AI用户在两年内多切换了窗口—— **74%没有注意到** (单位:千美元)[ICSE 2026 (英语)](https://doi.org/10.1145/3744916.3787811)) (中文(简体) ). `mental` 是跳跃需要的提示.

引用和我们没有声称的: [文件/研究.md](https://npmcn.com/package/%40balacode/mental/docs/research.md)。 。 。 .

## 数字

测量了 可复制. `npm test` • 妇女 `npm run bench`

|  |  |  |
| --- | --- | --- |
| **0 个** | 运行时间 npm 依赖性 | 节点 `>=22.13` |
| **562 (韩语)** | 自动测试 | 身份、搜索、安装、MCP、可选音轨 |
| **51分钟** | `mental heartbeat --json` | p50, 新鲜进程 |
| **11分钟** | 相同的脉冲在进程中 | MCP 之后 `mental serve` |
| **46分钟** | 搜索结束 **2 000个** 说明 | **1.2个毫秒** 正在处理 |

主机和方法 : [文件/基准](https://npmcn.com/package/%40balacode/mental/docs/benchmarks.md)。 。 。 .

## 财务问题

**我必须自己写日记吗?** 没有。 探员代表你写的. **我打进精神** - 您键入 `mental` 当你想要的脉搏. [谁写](https://npmcn.com/package/%40balacode/mental/#readme-who-writes)。 。 。 .

**这是 Mem0 / 聊天内存 / 是向量存储吗 ?** 没有。 精神CLI是项目连续性,而不是对话记忆. Markdown文件是真相的来源. 没有嵌入作为SOT. (别云.

**它是否取代了Git,issues,还是Plan.md?** 没有。 Git仍然记录着变化. `--against PLAN.md` 在计划点。 这些系统看不到的少量是精神上的.

**每次聊天都会自动上报吗?** 没有 任务界限 真正的决定 空气中的残留物 虎克留下来 **关** 直到你运行 `mental hooks on`。 。 。 .

**公园,交接,脉搏——什么时候?** `park` 编码中途中断. `handoff` 是一个计划中的关闭( journal +心跳) . `pulse` 是一个紧凑的跨项目概览。 便宜的中途重载还在 `mental` 编号 : `heartbeat --json`。 。 。 .

**我怎么升级?** 运行 `npm i -g @balacode/mental`, (中文(简体) ), `mental install`,则 `mental doctor`从0.8.1或更早运行中安装的现有视窗 `mental-repair.cmd` 在 npm 更新后一次。 日记留. 搜索索引在下次搜索时重建. 技能副本刷新; 主机插件是第二个信道—— 如果 `doctor` 说在后面 从 git 取出 : `npm run mental -- install`。 。 。 . [升级](https://npmcn.com/package/%40balacode/mental/docs/install.md#upgrade-already-installed)。 。 。 .

**狦 `mental` 未安装 ?** 代理继续编码任务,并提及三命令安装块. 他们从不执行 `.mjs` 直接存档。 无法打开 .

**数据住在哪里?** `~/.mental` (从来没有犯过). 项目 `./.mental` 仅在 `mental local`。未安装则不删除 OKF,除非您输入 `DELETE`。 。 。 . [身份](https://npmcn.com/package/%40balacode/mental/docs/identity.md) • 妇女 [隐私](https://npmcn.com/package/%40balacode/mental/#readme-privacy)

**笔记本电脑和桌面?** `mental backup --out ~/mental-backup` 复制目录,然后 `mental restore --from ~/mental-backup` 在另一个。 添加 `--dry-run` 首先要看看哪些项目将会被采纳或合并,有多少文件会落地,以及你们有多少文件是更新的并留下;它没有写作. 恢复将不会覆盖此 PC 上已经更新的工作 。 不同步或丢弃框 `~/.mental`。 。 。 . `--replace --confirm REPLACE` 只有灾难.

**精神CLI跟踪我的时间吗?** 只要你打开它`mental option track on`) (中文(简体) ). 代理人自动记录私人和客户准备的说明、墙上时间和可收费时间(默认情况下的墙上时间)。 如果真的需要输入,它们会使用一个带有短的单选选择的纯文本草稿来映射到本地主机的问题渲染器并倒回编号文本. 导出含有工作说明和时间的老客户行;它从未重建从git中缺失的时间. [音轨](https://npmcn.com/package/%40balacode/mental/docs/track.md)。 。 。 .

## 文档

|  |  |
| --- | --- |
| [为什么是精神上的CLI](https://npmcn.com/package/%40balacode/mental/docs/why.md) | 合同、非目标、结构 |
| [研究](https://npmcn.com/package/%40balacode/mental/docs/research.md) | 2024-2026年核查工作量、监督工作 |
| [安装精神CLI](https://npmcn.com/package/%40balacode/mental/docs/install.md) | npm, 插件, 克隆, 升级, 医生, 未安装 |
| [可选时间跟踪](https://npmcn.com/package/%40balacode/mental/docs/track.md) | 静坐的钟;可以和不能做什么 |
| [CLI 参考文献](https://npmcn.com/package/%40balacode/mental/docs/cli.md) | 命令、旗帜、退出代码 |
| [制剂的心理CLI](https://npmcn.com/package/%40balacode/mental/docs/agents.md) | `--json`、技能、MCP、收据 |
| [精神上CLI的身份](https://npmcn.com/package/%40balacode/mental/docs/identity.md) | UUID, 重新绘制 / 拆分 / 本地 |
| [CLI 心理障碍基准](https://npmcn.com/package/%40balacode/mental/docs/benchmarks.md) | p50 / p95 以及如何复制 |
| [技能](https://npmcn.com/package/%40balacode/mental/skill/mental/SKILL.md) | 程序代理装入 |
| [光谱](https://npmcn.com/package/%40balacode/mental/PLAN.md) | 完整产品谱 |

## 隐私

### 你的机器还留下什么

| 表面 | 叶子? | 发送什么 | 如何关掉 |
| --- | --- | --- | --- |
| 核心CLI(期刊,搜索,为什么,没有模型的心跳) | 没有 | 没什么 | —— 说 |
| 技能和规则 | 没有 | 没什么 | —— 说 |
| 更新检查 | 仅包名 | `npm view` 联 合 国 `@balacode/mental` 当缓存处于停滞状态时,包括 `--json` | `MENTAL_SKIP_UPDATE_CHECK=1` |
| MCP 磁共振 | 没有 | 这台机器上的stdio | `mental option mcp off` |
| 盘子 | 没有 | 循环 `127.0.0.1`,只获取和头部 | 停下来 `mental dashboard` |
| 决策模式 | 已编辑文本, 只带密钥 | 配置的提供者 | `mental option decide off` |
| 钩子 | 没有 | 没什么 | `mental option hooks off` |
| 时间跟踪 | 没有 | 本地 sqlite, 永远不要给 | `mental option track off` |

没有帐户,没有遥测,也没有精神服务器。 API 密钥存在 `~/.mental/config.json`在 macOS 和 Linux 上,文件是模式 `0600`。在 Windows 上,该模式为无操作模式,所以精神也问 `icacls` 唯一拥有的ACL,当它可以. `mental doctor --json` 包含a `network` 列出这些行.

-   默认存储 : `~/.mental/` (从来没有犯过)
-   项目 `.mental/` 被选入,必须被选中(`mental doctor --fix-ignore`) (中文(简体) ). 代理不能编辑 `.gitignore`
-   点击磁盘前在本地写入明显的证书( R)`[REDACTED:kind]`) (中文(简体) ). `--no-redact` 存储文本并说. `mental doctor --fix` 重写仍然匹配的文件
-   `mental uninstall` 除非输入,否则不删除 OKF `DELETE`

可选 : `mental install --mcp` • 妇女 `mental hooks on` • 妇女 `mental option track on` • 妇女 `mental option decide key <KEY>` ——默认 **关**. 技能+规则是合同. 几个小时从不进城. [音轨](https://npmcn.com/package/%40balacode/mental/docs/track.md)。 。 。 .

### 决策模式(可选)

精神可以使用快速,廉价的决定模型作为打字判断:是/否(概率),选择和得分,每个都有自信. 它不需要一个。 选择提供者 :

| 提供者 | 编号 | 页:1 |
| --- | --- | --- |
| [类型安全 Jev](https://typesafe.ai/) | `typesafe` (默认) | 系统 1 API |
| OpenAI 决定 | `openai` | `POST /v1/decisions`,型号 `gpt-6-luna` (贝塔) |
| 克来夫 | `cloudflare` | 需要账户代码; 模型 `clef` 或者说 `clef-flash` |
| 你自己的终点 | `custom` | TypeSafe 形状的 API, 需要一个 URL |

用钥匙就能恢复零重力 `mental search`,在写入前提示“类似于已有的”,建议链接 `mental show`,并提议 `mental relink` (类型:支持、替换、相矛盾、依赖 on). `mental retag` 为未标记的文件提出主题, `mental brief` 按相关性订购残留物, `mental search --rank` 重新排序点击次数,以及 `mental extract` 将会议记录变成拟议的行动和决定。 写作还配备顾问警卫(`data.guard`: 证书外观文本, 模糊的复行, 属于 `decide`),以及 `show` 指示代理人的旗帜文本。 它没有打开,只有 `relink --apply`, (中文(简体) ), `retag --apply` 财务报告和审定财务报表 `extract --apply` 写,高自信的结果。 被覆盖的笔记和决定可以用 `mental supersede <path> --by <newer>` 或者说 `mental obsolete <path>` (不需要模型):文件被保存,只有其状态变化,从心跳中跳出并排到最后搜索.

键被读取 **仅限** 从 `~/.mental/config.json` (mode 0600),从不来自环境变量,也从不打印或发送到MCP:

```bash
mental option decide key <KEY>                         # key for the active provider
mental option decide key <KEY> --provider openai       # store another provider's key
mental option decide provider openai                   # choose the active provider
mental option decide account <ID> --provider cloudflare
mental option decide model clef-flash --provider cloudflare
mental option decide fallback cloudflare               # used when the active one fails (off to clear)
mental option decide personal off                      # never send personal-slice notes (default: allowed, secrets redacted)
mental option decide off                               # mute (also silences the reminder)
mental option decide budget 200000                     # optional cap on input tokens per day (budget off to clear)
```

`mental option jev …` 仍然作为化名, 和一个更古老的 `jev` 配置密钥自动迁移到 TypeSafe 提供者 。 状况`mental option decide`) 显示提供者,哪些提供者被配置,以及今天的请求和信使.

**单位 `mental doctor`。 。 。 .** 用钥匙,平平 `mental doctor` 也运行内容检查, 全部只警告( 退出代码不变 ) : `jev-stale` (露出看起来已解决或已过期的残留物), `jev-decisions` (可能相互矛盾的决定), `jev-handoff` (最新日记) `Resume:` 缺少或模糊的行), `jev-untagged` (每个未标记文件建议的主题;从未写), `jev-secrets` (可能持有资质的文件;仅路径,且值在发送前被编辑). 包括个人笔记,除非你用 `option decide personal off`。 。 。 . `mental doctor --offline` 跳过它们;花在日常预算上.

支出在当地跟踪 `jev-usage.json` (只计算,无内容),由提供方共享. 请求被拆分以停留在每个提供者的限度下,当模型版本改变时会放弃缓存的答案.

没有钥匙, `heartbeat` 和零击出 `search` 偶尔(最多每3天)会告诉代理商一个决策模型,以便其提及. `MENTAL_NO_HINTS=1` 安静.

* * *

**无 :** [@ balacode/ mental (英语)](https://www.npmjs.com/package/@balacode/mental) • 妇女 **重传 :** [afaraha8403/mental (英语)](https://github.com/afaraha8403/mental) • 妇女 **许可证 :** [麻省理工学院](https://npmcn.com/package/%40balacode/mental/LICENSE)

## 常见问题

### @balacode/mental 是什么？

永远不要重建你离开的地方 编码剂的本地第一连续性——恢复、决定和残留物不能看到。 CLI、MCP和特工技能\.

### 如何安装 @balacode/mental？

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

### @balacode/mental 支持 TypeScript 吗？

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

### @balacode/mental 支持 ESM 还是 CommonJS？

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

### @balacode/mental 需要什么版本的 Node\.js？

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

### @balacode/mental 可以商用吗？

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

### @balacode/mental 的下载量有多少？

根据 npm 官方下载统计，@balacode/mental 在 2026/10/08 – 2026/11/06 这 30 天内被下载 1,733 次，日均约 58 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @balacode/mental 还在维护吗？

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