# @akasha-book/mcp 中文文档

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

版本：1\.1\.7
npm 元数据更新时间：2026-10-25T13:12:10.433Z
中文译文更新时间：2026-11-09T20:00:05.209Z
软件包许可：MIT

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

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

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

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

## 中文简介

阿卡夏之书 MCP 注册桥（自带 stdio 客户端；不引用任何 @deepseek-ai/\* 包）

## 安装

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

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

## README

# @akasha-book/mcp —— 阿卡夏之书 MCP 注册桥

把**阿卡夏之书**（外置记忆层）的工具以 `mcp__akasha__*` 暴露给模型的 DSH 宿主插件。

> **配套系统（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`；`command` 用 PATH 里的 `node`（或改成本机 node 绝对路径）
3.  `failOnStartupError: true`：占位符未替换 / 目录不存在 / mcp.mjs 缺失时会**明确报错**，不再静默消失

## 它做什么

宿主启动时，本插件：

1.  以 **stdio** 拉起 MCP 服务器（默认 `node <AKASHA_DIR>/mcp.mjs`）；
2.  走 JSON-RPC 握手（`initialize` → `notifications/initialized`）；
3.  `tools/list` 取回工具清单，逐个注册到宿主 ToolRuntime，公开名为 **`mcp__akasha__<工具名>`**（与官方桥同名规则：非法字符→`_`；名被改写或超长（>64）→ 截断 + 12 位 sha256 后缀）；
4.  `tools/call` 时把参数透传给服务器，并按其契约返回 `{ content, structuredContent? }`；服务器报 `isError` → 抛错（让运行时记为失败）。

**自带客户端、零依赖**：本包**不引用任何 `@deepseek-ai/*` 官方包**，也不修改/遮蔽官方组件——这样做是为了满足 DSH-Store 的硬边界（第三方 Bundle Patch 不得以 `name: @deepseek-ai/...` 引用官方包）。

## 配置（`cordis.patch.yml`）

```yaml
- insert:
    - id: mcp-akasha
      name: '@akasha-book/mcp'
      config:
        serverName: akasha            # 公开名前缀 → mcp__akasha__*
        transport: stdio              # 仅支持 stdio
        command: 'node'               # 可执行文件（或用绝对路径的 node）
        args: ['<AKASHA_DIR>/mcp.mjs'] # ← 改成你自己的 core/mcp.mjs 绝对路径
        toolCallTimeoutMs: 600000     # 单次工具调用超时（默认 60000）
        startupTimeoutMs: 20000       # 启动握手超时
        failOnStartupError: false     # false = 连不上就降级为「无工具」，不拖垮宿主
```

## 权限 / 非目标 / 边界（permissions · non-goals · boundaries）

-   **权限**：仅 `spawn` 一个本地子进程（node + `mcp.mjs`），经 stdio 与其通信；不打开网络端口、不读凭据、不写宿主 Profile；工具读写的数据面完全由 MCP 服务器（`core/mcp.mjs`）自己负责。
-   **非目标**：不做 streamable-http 传输；不做图片内容投影（非文本块在**渲染**里降级为 `[type]` 占位符，值仍原样返回、不丢数据）；v1 不做自动重连（`failOnStartupError` 决定抛或降级）。
-   **边界**：本插件只负责「连接 + 注册」，**不代替** MCP 服务器本身；服务器崩了工具即失效（日志可见），重启宿主可恢复。

## 测试

```bash
node selftest.test.mjs
```

覆盖：Bundle Patch 契约（自有入口 ID、不以 `name` 引用官方命名空间、只 `insert`）、公开名规范化（含超长哈希后缀）、文本提取与非文本降级、**端到端**（临时 core 副本 + 真实 MCP 服务器：注册工具、校验前缀与定义形状、**真调 `akasha_check` 并断言返回**）、malformed JSON-RPC 不导致非零退出。

## 兼容与状态（DSH STORE 口径 · 2026-10-10）

**固定源（immutable source）**：本版本源码冻结于仓库固定 Commit（见 Issue 中登记的 commit；对应 `plugins/mcp-akasha/package.json` 的 version）。 兼容声明见 manifest 的 `dsh.compatibility.dshReleases`：`0.2.0-rc.2` / `0.2.1-alpha.1` / `0.2.1-alpha.2` 均 **compatible**（三版 × 一次性 Profile 装-启-卸实跑）。

| 证据层 | 状态 | 依据 |
| --- | --- | --- |
| 静态契约（manifest / Bundle Patch / 许可证 / 入口 ID） | **verified** | 官方 `build-dsh-plugin` 审计；入口 `mcp-akasha` 为插件自有 ID，Patch 只 `insert` 自有包 |
| 单元与边界测试（`npm test`） | **verified** | 含端到端：真实 MCP 服务器 + 18 工具注册 + `akasha_check` 实调 |
| 一次性 Profile 安装·启动·卸载（E3） | **verified** | 三版 DSH 各跑通；证据见同目录 `EVIDENCE.json` |
| 真实 Profile 运行 | **verified（本机）** | 桌面端 0.2.0-rc.2 实跑；他人机器 **unverified** |
| 独立安全审计 / 公开分发（E5） | **unverified** | 未做独立审计 |

**下一道门（next gate）**：① 在 DSH 上测 streamable-http 传输（若需要）；② 若上游暴露公开的注入/工具服务接缝，评估改回"借官方服务"以省掉自研客户端；③ 补图片内容投影。

## 源与许可（Source & License）

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

## 常见问题

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

阿卡夏之书 MCP 注册桥（自带 stdio 客户端；不引用任何 @deepseek-ai/\* 包）

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

在项目目录运行 npm install @akasha-book/mcp，或使用 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/mcp 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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

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

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