# @akasha-book/hooks 中文文档

规范地址：https://npmcn.com/package/%40akasha-book/hooks/

版本：1\.2\.11
npm 元数据更新时间：2026-10-25T13:11:24.597Z
中文译文更新时间：2026-11-07T04:14:20.332Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：20 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：0 个
- peer 依赖：@deepseek-ai/dsh ^0\.2\.0-rc\.2，@deepseek-ai/cordis ^4\.0\.4
- 首次发布：2026-10-08T06:19:04.477Z
- 最新版本发布：2026-10-25T13:11:24.348Z
- 近 30 天下载量：2054（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

\========================================================================================================================================================================================================

## 安装

```sh
npm install @akasha-book/hooks
```

也可以使用：`pnpm add @akasha-book/hooks`、`yarn add @akasha-book/hooks`、`bun add @akasha-book/hooks`

## README

# @akasha-book/akasha-hooks

阿卡夏之书钩子 —— 把宿主的事件流落成 append-only 记录，为「结果计数器 / 失败回查 / 空闲脉冲 / 输出审计」供料。

> **配套系统（Companion systems）**：阿卡夏本体可独立运行（核心零第三方 npm 依赖），但完整形态与三层协作—— **Hindsight**（仓库级记忆：架构/约定/决策/initiative）、**OpenViking**（用户与人格记忆、跨项目上下文）、 以及**宿主自带会话检索**（`session_search` / `session_event_read`：原始事件、逐字引文、精确过滤走官方； 阿卡夏会话层只做结论/决策/教训/跨会话导航）。阿卡夏会跳过前两者的注入块、不写入它们的存储； 缺任一层不报错，只是少了那层交叉记忆。详见仓库 README §配套系统。

## 安装（必读）

1.  `git clone https://github.com/Ersith/akasha-book && cp -r akasha-book/core <目标目录>/core`
2.  把 `cordis.patch.yml` 里所有 `<AKASHA_DIR>` 换成 `<目标目录>/core` 的绝对路径；或删掉路径字段并设 `AKASHA_DIR=<目标目录>/core`
3.  **未替换占位符 / 目录不存在时，插件会明确报错拒绝启动**（fail-closed，不会静默降级）；日志与数据都在 `<AKASHA_DIR>` 内

> 只跑核心库（CLI/MCP）：`cd core && node test.mjs && node akasha.mjs check`。

> **版本（单一真值）**：以本包 `package.json` 的 `version` 为准（2026-10-13 审计 P3 同族：此处曾写死 v1.2 而实际已到 1.2.4-h2）。当前装载版本用 `plugin_manager list_bundles` 查。

-   **v1.2.6-h1（2026-10-14，外部审查修复批 B）**：**`expandHome` 定义前置于使用**（TDZ 修复）——此前它排在 `ENV_AKASHA` 之后，外部按契约设**非空 `AKASHA_DIR`** 时模块导入即 ReferenceError ⇒ hooks 整个装不上（复跑：`loaded`、exit 0 ✓）。
    
-   **v1.2.5-h1（2026-10-13，举一反三批）**：**修两处「工具/子命令表漏项 ⇒ 召回静默漏计」**（与 gate 的 SHELL\_TOOLS 同族）—— ① `SHELL_TOOLS` 补 **`ops_bash`**：dsh-ops 落地后它是最常用 shell 入口，**gate 早就补了、hooks 漏了**（两处不同步）； ② `CLI_RECALL` 从 9 条只读子命令扩到**全部只读面**（`check/stats/audit/metrics/frontier due|list/session lookup|context|tree|node|loopwatch|stats/sleep --plan/evidence`）—— 此前查询走别的只读子命令时召回不计数，直接稀释 recall-miss 指标的分母。反向钉住：`revise`/`add`/`retire` 等写入子命令**不算**召回（自测 +9 条哨兵）。
    
-   **v1.2.4-h2 / h1（2026-10-11/12）**：A/B 开关（`abOff`）与工作窗口相关修订；观测线同前。
    
-   **v1.2（2026-10-07 复查修复）**：输出审计按 `attemptId` **连续累积**——官方 revision 逐帧递增（`nextRevision()` 每 emit 一次），修复前按 revision 重置 ⇒ 每 chunk 清空、审计恒空（output-audit/usage **0 条**实证）；id 跨帧切分现已可还原。自检夹具同步改为宿主真值（逐帧递增 revision + 跨帧切分）。
    
-   记录文件：`<AKASHA_DIR>\logs\hooks.jsonl`（JSONL，一行一事件）
    
-   监听（全部为 contained 的 emit 事件，失败不打断宿主）：
    
    -   `session/event` → `turn/end`：回合结束（`kind:"turn-end"`）
    -   `tools/result` → 每次工具结果（`kind:"tool"`，含 `ok` 与失败 `message`；`logToolResults:false` 可只记失败）
    -   `agent/error` → step / turn 出错（`kind:"agent-error"`）
    -   `agent/status` → running→idle（`kind:"idle"`，去抖 + 计数器快照）
    -   `agent/assistant-stream`（**v1.1 新增**）→ 输出审计：按 attemptId+revision 累积 assistant 文本流，committed 结束时跑核心库 `auditText`——
        -   引用**不存在**的库 id → `kind:"output-audit"` 线（编造引用嫌疑；emit 语义只能审计、不能拦截）；
        -   引用**真实存在**的库 id → `kind:"usage"` 线（条目级使用计数 v0，供 `akasha.mjs metrics` 汇总）。
    -   ⚠️ `auditOutput:false` 可关闭输出审计（默认开）。
-   激活即写一行 `kind:"activated"`——可用它验证插件已加载。
    
-   纪律：只追加、不改行；本插件不注入上下文、不拦截任何调用（v1.1 仍为「记录层」）。
    
-   自测：`node selftest.mjs`（桩 ctx + 临时假库：usage / output-audit 线、abandoned 不落线、revision 重置、无核心降级；不碰真库）。
    

## 打包 / 安装

```powershell
cd <LOCAL_PATH>\dsh-akasha-hooks
npm pack
# 然后：plugin_manager install_bundle <tgz 绝对路径>（首次安装会 HMR 热生效；替换需重启）
```

## 源与许可（Source & License）

-   源仓库：https://github.com/Ersith/akasha-book
-   本版本固定提交（pinned commit）：`5a55099586cfae4e7511ba433eaf202455d81c30`
-   许可证：MIT（见仓库根 LICENSE）

## 常见问题

### @akasha-book/hooks 是什么？

========================================================================================================================================================================================================

### 如何安装 @akasha-book/hooks？

在项目目录运行 npm install @akasha-book/hooks，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/dsh（^0\.2\.0-rc\.2）、@deepseek-ai/cordis（^4\.0\.4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @akasha-book/hooks 支持 TypeScript 吗？

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

### @akasha-book/hooks 支持 ESM 还是 CommonJS？

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

### @akasha-book/hooks 需要什么版本的 Node\.js？

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

### @akasha-book/hooks 可以商用吗？

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

### @akasha-book/hooks 的下载量有多少？

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

### @akasha-book/hooks 还在维护吗？

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