# @davesheffer/hunch 中文文档

规范地址：https://npmcn.com/package/%40davesheffer/hunch/

版本：1\.53\.0
npm 元数据更新时间：2026-11-11T11:35:42.201Z
中文译文更新时间：2026-11-11T19:48:40.305Z
软件包许可：FSL-1\.1-ALv2

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

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

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

- 包体积（解压后）：13.4 MB，586 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.13\.0
- 运行依赖：12 个
- peer 依赖：@huggingface/transformers \>=3
- 首次发布：2026-06-15T11:02:37.888Z
- 最新版本发布：2026-11-11T11:35:41.799Z
- 近 30 天下载量：4033（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：187（近 12 个月 187 个）

## 中文简介

AI代理商的共同记录:决定、已完成的工作和承诺以及来源。 Git-native Engineering内存和自备的状态服务器.

## 安装

```sh
npm install @davesheffer/hunch
```

也可以使用：`pnpm add @davesheffer/hunch`、`yarn add @davesheffer/hunch`、`bun add @davesheffer/hunch`

## README

# 猎人

## AI特工共享记录:决定了,发生了什么,还需要做什么.

[![npm version](https://img.shields.io/npm/v/@davesheffer/hunch?color=2742ff&label=npm)](https://www.npmjs.com/package/@davesheffer/hunch) [![GitHub stars](https://img.shields.io/github/stars/davesheffer/hunch?color=2742ff&label=%E2%98%85%20star)](https://github.com/davesheffer/hunch) [![license](https://img.shields.io/badge/license-FSL--1.1--ALv2-2742ff)](https://npmcn.com/package/%40davesheffer/hunch/LICENSE)

[![Watch: Hunch Memory in 2 minutes](https://img.youtube.com/vi/m2PM6pV7D9Y/maxresdefault.jpg)](https://www.youtube.com/watch?v=m2PM6pV7D9Y)

▶ **[两分钟后看Hunch记忆](https://www.youtube.com/watch?v=m2PM6pV7D9Y)**,然后是 [7集系列](https://www.youtube.com/playlist?list=PLIXqtdE0LcNI) 在设置,钩子,内存捕捉,交付,规则,漂移和团队.

![Hunch refuses a staged change that imports lodash, citing the blocking rule it breaks](https://npmcn.com/package/%40davesheffer/hunch/site/assets/hunch-blocks-it.gif)

新的代理会议不应意味着再次解释整个项目。 第二代理人应当能够检查有记录的决定,查看已完成工作背后的证据,并找到未履行的承诺.

Hunch把记录保存在Git 并提供给你的特工 开始于 **工程内存**:为什么代码存在,哪个方法之前失败,哪个规则更改必须保留. 它也载着一个 **状态服务器** 用于在授权组织、团队、用户和储存范围之间分享决定、行动记录和承诺.

目标很简单:从同一保存的记录中工作的特工,他们可以检查消息来源。 Hunch提供内存和支票;助手仍然负责工作.

## 从您的编码助理开始

要求数 **22.13+ 节点** 和一个Git仓库.

```bash
npm i -g @davesheffer/hunch
cd your-repo
hunch init
hunch backfill --since 90d   # optional: draft memory from recent history
```

如果炮弹报告 `hunch` 未找到,在未从 仓库目录 : `npx -y @davesheffer/hunch@latest init`。 。 。 .

重新装入你的助手,然后问:

> 为什么这是这样建造的,在改变它时我应该保存什么?

`hunch init` 索引代码,配置所支持的助理集成,并在保存现有设置的同时添加内存指令. 对于 Codex 钩子,审查并信任命令 `/hooks`,然后开始新的会话. **记忆是默认的咨询.** 封锁需要明确信任的规则并严格执行.

Hunch与克洛德代码,Codex,Cursor,VS代码/Copilot,Windsurf,Antigravity等MCP客户端合作. 自动上下文和钩子覆盖因助手而异;一个连接的MCP服务器本身并不能证明它们正在运行. [检查您的整合](https://www.hunchmemory.com/docs#update)。 。 。 .

## 你今天的收获

| 需求 | 汉克帮了大忙 |
| --- | --- |
| 别再解释旧的决定了 | 保存决定,拒绝的选项,错误历史,校正,以及带有其源头的开放式发现. |
| 在做出改变之前先理解一下 | 将内存连接到代码符号和依赖;显示受影响的代码和被记录的建筑意图. |
| 在整个会议期间随时向代理人通报情况 | 通过MCP为一项任务提供重点简报并支助生命周期钩. |
| 检查你的团队选择的规则 | 评价所支持的限制和代码关系,在阻断路径中没有模型. |
| 看看在任务期间发生了什么 | 分离传递了内存,代理机报告了用途,规则结果,并在一份贡献报告中观察到了命令结果. |
| 与队友共享项目内存 | 将寄存器保存在Git中,并设有可选的专用私人内存存储器. |
| 跨代理共享工作状态 | 通过HTTP,MCP,州CLI,并打入TypeScript和Python客户端提供授权记录. |
| 看看特工们知道什么 | 只读浏览器视图显示当前记录、承诺、已完成的工作和作者提供的引用. |
| 明确准入和公约 | 可选的逐个记录受众,密钥约束的证书和来源公约使用相同的州合同. |

例如,一个团队通过在服务器上保留会话来修正一个登出错误. 几个月后,一个特工提议删除那个代码. Hunch可以在编辑前露出原由并拒绝替代. 一个被支持,信任的规则可以标出冲突;严格模式可以屏蔽冲突. 记录教训和配置整合是促成这一点的原因.

## 每日活动

| 命令 | 用它来 |
| --- | --- |
| `hunch context "<task>" --profile builder` | 在开始前获得一个重点突出的简介 |
| `hunch why <file-or-symbol>` | 理解代码后面的决定和过去的错误 |
| `hunch structure [target]` | 检查索引文件和符号 |
| `hunch findings [scope]` | 见已知的尚需要弥补的差距 |
| `hunch impact origin/main` | 看看分支会影响什么 |
| `hunch check --working` | 对照记录的规则检查当前更改 |
| `hunch conform` | 检查所支持的建筑关系 |
| `hunch now` | 阅读最近的决定和记录的路线图 |
| `hunch doctor` | 诊断设置和存储问题 |

审查和信任有关规则后强制执行:

```bash
hunch firmness strict
hunch check --staged --strict
```

生成的笔记、观察的习惯和进口文件不会默默获得阻断权.

## 在不丢失设置的情况下更新

使用 Hunch 的每个寄存器 :

```bash
hunch update
```

如果炮弹报告 `hunch` 找不到, 运行 `npx -y @davesheffer/hunch@latest update` 取而代之的是寄存器.

或者叫你的经纪人 **“更新Hunch”** 该命令安装了最新的发布,对所配置的集成针进行对齐,修复已知的遗产发射命令,并刷新Hunch指令. 它保留了无关的设置和故意被禁用的钩.

已安装的交互式 CLI 命令也可以显示缓存更新通知 。 最多每24小时一次,一个脱产工人 要求npm的包装的公众 `latest` 版本; hooks, MCP, CI, 服务器, 更新器, 非交互命令, 源检出跳过此请求 。 设定 `HUNCH_NO_UPDATE_CHECK=1` 或者说 `NO_UPDATE_NOTIFIER=1` 来禁用它.

-   一个独立的 npm 工程将 Hunch 保留在它现有的依赖部分 精确的版本 。 没有寄存器依赖,全球CLI就会被更新. 添加 `--global` 以更新两者.
-   对于其他软件包管理器或工作空间,用该软件包管理器更新依赖,然后运行 `hunch integrations repair-pins`。 。 。 .
-   重新启动或重新连接活动助理. 在编码中,打开 `/hooks` ,然后开始一个新的会话。 一个已更改的版本指针会改变命令并需要恢复信任.

校验设置 :

```bash
hunch integrations check
hunch integrations check --harness codex --probe --require mcp
hunch integrations check --harness codex --require context
```

首个指令检查配置. 探测器开始一个新的MCP过程并读取内存. 上下文检查需要在预期版本上被观察到的钩子交付,所以在新助手会话开始后运行. `--require` 当命名的能力未被验证时失败; 这些检查都没有证明一个模型遵循了建议 .

## 从仓库中移除 Hunch

```bash
hunch uninstall --dry-run   # show what would change
hunch uninstall             # remove what Hunch installed; keep .hunch/ (your memory)
hunch uninstall --purge     # also delete .hunch/, the derived cache and Hunch's .gitignore blocks
```

它去掉了Hunch安装的指令块,MCP条目,代理和git hooks,并合并了驱动程序,斜线命令和CI工作流程,将你自己的内容留在了这些文件中. 如果需要编辑的文件无法被解析,则它不会改变任何东西并说出哪个文件. 写着 `.hunch-removed`:虽然该文件存在,但是没有Hunch命令在这里再次设置Hunch. 交代它, 所以每个克隆人都会选择退出; 重新安装, 删除并运行 `hunch init`关闭运行 `hunch mcp` 编号 : `hunch serve` 进程首先,所以不能重现文件.

## 看看Hunch的贡献

任务报告回答:什么记忆达到了这个任务,什么是代理说它使用了什么,什么检查实际运行?

通常的代理指令要求填写有当地证据报告链接的完成卡. 您也可直接检查报告:

```bash
hunch task list
hunch report <task-id> --html
```

交付的教训、代理人的主张和通过测试是不同的证据。 Hunch让他们分开 自动显示取决于任务生命周期之后的主机;缺失的证据仍未被验证.

## 与您的团队共享一个活的存储器

一个维护者连接一个专用的私有 Git 寄存器:

```bash
hunch shared --repo git@github.com:acme/project-hunch-memory.git
git add .gitignore .hunch/team.json
git commit -m "chore: connect shared Hunch memory"
git push
```

队友安装Hunch,拉出代码,然后跑 `hunch shared --trust` 每台机器一次: 它显示商店 URL from `.hunch/team.json` 并且只有在明确同意后才能连接。 然后运行 `hunch init`在机器信任商店之前,Hunch拒绝克隆它或者在那里的路由内存. 普通 Git 访问控制共享寄存器 。 身份证明 本地克隆路径 和私人覆盖 远离承诺的指针 使用 `hunch shared --sync` 重试同步; 添加 `--no-auto-commit` 当抓取时,应等待明确的同步.

这分享了一个项目的工程记忆. 下面的状态服务器增加了经过认证的跨多范围访问.

## 决定性组织状态

编码代理需要知道模块存在的原因. 业务代理人可能需要知道客户行动是否已经完成,或谁欠下一个后续行动。 双方都需要一份可以查的有记录.

货船 `hunch serve`:面向组织,团队,用户和寄存器记录的自办HTTP服务. 配置后的身份决定了代理人可访问的范围 。 可选记录受众进一步限制访问;可选的密钥绑定证书需要每个请求所配置的私钥提供证明.

打开 `/operator` 在您的服务器上检查当前记录、完成的工作和只读浏览器视图中的承诺。 由 Writer 提供的引用可以指准确的简要字段或文本段落及其被记录的来源. 它们显示出可追溯性;它们不能证明来源支持索赔.

特工可以通过MCP使用同样的合同, `hunch state read|write|records|subscribe`,则 `@davesheffer/hunch/state` TypeScript客户端,或者Python客户端. Python 包是从此寄存器中构建和测试的;尚未发布到PyPI. 范围公约允许个人记录来源用户、团队或组织的偏好。 这些优惠仍然是咨询性的,不会沉默地成为阻碍规则.

记录可以描述决定、行动结果、承诺、实体、关系以及说明其依赖性的摘要。 行动保持其地位,包括未知或未经核实的结果。 被重复的写作具有稳定的身份,相互矛盾的当前决定被拒绝,经确认的人类记录得到保护,免受代理覆盖. 这些是对结构化记录进行界定的检查; Hunch不能独自确定外界的一切事实.

这就是 **确定状态** 意思是: 明确的规则管理被存储的记录,而不是让每个代理从头重建记录. Git 持有耐用数据; SQLite 是一个可重建的索引. 服务器绑定回回回回回,需要其运营商的部署和代理集成. Hunch 不提供管理下的CRM或电子邮件连接器服务.

见 [完整文档](https://www.hunchmemory.com/docs)。 。 。 .

### 愿景,什么还在测试中

愿景是跨人,工具和代理的连续性:一个业务代理记录客户问题,一个编码代理查找相关决定并修复原因,业务代理使用固定的证据关闭承诺.

今天的内存和状态工具船。 更广泛的主张——不同代理人可靠地使用共同的状态并避免相互矛盾的工作——仍在衡量之中.

**Hunch仍然是产品名称.** 这个 `nuryel.state/1` 礼宾和 `nuryel_*` 工具名称是现有的技术标识符; 未来可能的重命名尚未确定.

## 项目DNA:帮助代理商了解项目如何运作

项目DNA描述了观测到的储存地公约:术语、贡献习惯、审查期望和工程模式。 工程记忆记录决定及其原因. 两者都可以为一项任务提供参考,但频繁的行为并不成为政策.

```bash
hunch dna inspect
hunch dna context
hunch dna diff <older-ref> <newer-ref>
```

概况保留其修订、来源、信心和新鲜度.

## 你的数据和权威

-   仓库使用为本地第一,不需要托管的Hunch账户。 共享内存使用Git访问;可选状态服务器使用已配置的身份和授予.
-   `hunch private --repo <url>` 将敏感的工程推理保留在私人的覆盖中。 公共出口和消费者协会应使用只公开的观点.
-   起草时可以使用所选的编码辅助订阅,本地端点,或者确定后退. 公开的计量吸入器终点需要明确的选入. [综合和计费](https://www.hunchmemory.com/docs#synthesis)。 。 。 .
-   特工负责外部行动和连接器权限. 存储的记录不授权更改电子邮件、部署或客户关系管理.
-   npm和编辑版的发布使用单独的出版门,并带有包的完整性和出处检查.

## 学多点

-   [完整文档](https://www.hunchmemory.com/docs)
-   [复制版烹饪本](https://www.hunchmemory.com/cookbook)
-   [更改日志](https://npmcn.com/package/%40davesheffer/hunch/CHANGELOG.md)
-   [VS 代码扩展](https://npmcn.com/package/%40davesheffer/hunch/vscode-extension/README.md)
-   [捐款](https://npmcn.com/package/%40davesheffer/hunch/CONTRIBUTING.md)

[FSL-1.1-ALv2 (英语)](https://npmcn.com/package/%40davesheffer/hunch/LICENSE) (功能源许可证). 使用、修改和运行它,用于自己的内部或商业工作;你不能在与Hunch竞争的商业产品或服务中向他人提供它或服务,或与Hunch竞争或利用它建立的服务(见允许目的 [自由主义](https://npmcn.com/package/%40davesheffer/hunch/LICENSE)) (中文(简体) ). 每次放出都会在出船两年后转换为Apache-2.0. 变更前的释放 保留着他们携带的执照.

## 常见问题

### @davesheffer/hunch 是什么？

AI代理商的共同记录:决定、已完成的工作和承诺以及来源。 Git-native Engineering内存和自备的状态服务器\.

### 如何安装 @davesheffer/hunch？

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

### @davesheffer/hunch 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @davesheffer/hunch 支持 ESM 还是 CommonJS？

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

### @davesheffer/hunch 需要什么版本的 Node\.js？

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

### @davesheffer/hunch 可以商用吗？

@davesheffer/hunch 使用 FSL-1\.1-ALv2 许可。声明的许可为 FSL-1\.1-ALv2，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @davesheffer/hunch 的下载量有多少？

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

### @davesheffer/hunch 还在维护吗？

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