# @chamba/core 中文文档

规范地址：https://npmcn.com/package/%40chamba/core/

版本：1\.14\.0
npm 元数据更新时间：2026-11-08T01:55:17.910Z
中文译文更新时间：2026-11-09T17:59:59.038Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：603 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-06-09T20:13:41.067Z
- 最新版本发布：2026-11-08T01:55:17.712Z
- 近 30 天下载量：2031（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：45（近 12 个月 45 个）

## 中文简介

Chamba的核心逻辑:工作空间扫描仪,计划+heuristic审查器,git工作树,Obsidian,内存——节点APIs,没有LLM

## 安装

```sh
npm install @chamba/core
```

也可以使用：`pnpm add @chamba/core`、`yarn add @chamba/core`、`bun add @chamba/core`

## README

# @ chamba/ 核心

纯核心逻辑 [香槟](https://github.com/thelord07/chamba):工作空间扫描仪, 计划生成器 + 高压审查器, git 工作树管理器, Obsidian 上下文/上下文 编剧,还有一个文件系统记忆库.

-   **节点 API 直接** ——所有OS访问通过端口(`FilesystemPort`, (中文(简体) ), `ProcessPort`, (中文(简体) ), `ClockPort`),所以可以测试,运行时间不可知.
-   **无 LLM** - chamba从来不叫模特儿.
-   港口的节点实施 [`@chamba/adapters`](https://www.npmjs.com/package/@chamba/adapters)。 。 。 .

大多数用户想要 [`@chamba/mcp`](https://www.npmjs.com/package/@chamba/mcp) 服务器, 而不是直接这个图书馆.

## 保险库同步( protocolo de parche)

在集团成员之间同步 Obsidian 兼容金库的纯策略和逻辑. 没有网络,没有密码,没有fs——从适配器预先计算出hashes到达.

### 主要出口

| 导出 | 说明 |
| --- | --- |
| `hashSchema`, (中文(简体) ), `vaultPathSchema`, (中文(简体) ), `roleSchema` | 柔德原始人(NFC-正统路径,sha256活塞,4-活塞) |
| `changeEntrySchema`, (中文(简体) ), `changesResponseSchema` | 远程更改种子计划 |
| `pushRequestSchema`, (中文(简体) ), `pushResponseSchema` | 优化驱动方案(% 1,% 500 个更改;没有精确的重复路径;没有两个共享的活条目) `pathKey`(中文(简体) ) |
| `joinRequestSchema`, (中文(简体) ), `joinResponseSchema` | 邀请码加入: 请求携带 `{ code, name, email, deviceLabel? }` (编码归正为大写;电子邮件修剪后+小写;响应包括 `user: { id, name }` 财务报告和审定财务报表 `device: { id, label }` |
| `userSchema`, (中文(简体) ), `deviceSchema` | 服务器在成功加入或设备流程批准后返回的身份对象 |
| `deviceAuthStartResponseSchema`, (中文(简体) ), `deviceAuthPollResponseSchema` | 设备流认证; `approved` 变式包括: `user` 财务报告和审定财务报表 `device` |
| `isSyncable(path)` | 返回 true iff 路径应同步( 拒绝列表 + 扩展允许列表) |
| `pathKey(path)` | 条形键 : `path.normalize('NFC').toLowerCase()` macOS/Windows FS的不敏感个案身份 |
| `findCaseCollisions(paths)` | 相撞的路径组 `pathKey` (每组2个不同路径);用于服务器/客户端验证 |
| `conflictCopyPath(path, author, existing)` | D3冲突副本名称 : `dir/stem (conflicto author[ N]).ext`;通过 `pathKey` |
| `addConflictFrontmatter(md, meta)` | 升级 `conflict_of`编号 :`conflict_base` 在 YAML 前题 |
| `readConflictMeta(md)` | 回读 `{ conflictOf, conflictBase }` 无效 |
| `planPush(state, local)` | 计算按键条目(新/已修改/已删除);先删除,再按路径删除其余条目 |
| `planPull(state, local, remote, opts)` | 计算拉动动作( 写/ 删除/ 冲突/ 无) 按( 排序, 路径) 排序 —— 见下文动作顺序 |
| `applyPullPlan(state, plan)` | 从拉出计划衍生出新的同步状态( 纯度, 无突变); 在拉出后关闭假冲突间隙 |
| `applyPushResults(state, request, response)` | 推后提前同步状态; 只 `ok` 推进成果 |
| `ROLE_PERMISSIONS`, (中文(简体) ), `can(role, action, target?)` | 授权表 + 4 个角色的助手 × 7 个动作 |

### 作用

| 作用 | 权限 |
| --- | --- |
| `owner` | 所有行动,包括 `delete_group`. 每个组的独特性. |
| `admin` | `read`, (中文(简体) ), `sync`, (中文(简体) ), `write`, (中文(简体) ), `invite`, (中文(简体) ), `revoke`, (中文(简体) ), `change_role` -但不能瞄准目标 `owner`。 。 。 . |
| `editor` | `read`, (中文(简体) ), `sync`, (中文(简体) ), `write`。 。 。 . |
| `reader` | `read`, (中文(简体) ), `sync` (只弹出). |

### 不区分大小写路径标识

对默认大小写路径进行比较是因为 macOS 和 Windows 文件系统是 大小写不敏感. `pathKey(p)` 在所有地方使用的犬类形式 :

```ts
pathKey('Nota.md')       // → 'nota.md'
pathKey('NOTAS/A.MD')    // → 'notas/a.md'
```

`pushRequestSchema` 当同一路径出现两次或两次时,拒绝推动 **现场直播** 条目(`newHash !== null`(单位:千美元) `pathKey` (例如:. `Nota.md → H1` + 键 `nota.md → H2`) (中文(简体) ). 删除后加上相同的活条目 `pathKey` 是外壳重命名并有效 :

```ts
planPush({ cursor: 0, files: { 'Nota.md': { syncedHash: S1 } } }, { 'nota.md': S1 })
// → [{ path: 'Nota.md', baseHash: S1, newHash: null },
//    { path: 'nota.md', baseHash: null, newHash: S1 }]   // accepted by pushRequestSchema
```

`planPush` 返回删除( e)`newHash: null`)首先,然后是其余部分,按每一部分的路径排列 组合。 服务器按收到的顺序按下一个按键, 因此删除了旧名 在创建新的之前.

`vaultPathSchema` 并拒绝以 `.chamba-sync` 不论情况`.Chamba-Sync/…` 失败).

`findCaseCollisions(['Nota.md', 'nota.md', 'b.md'])` 返回时 `[['Nota.md', 'nota.md']]`。 。 。 .

### 签名和行动令

```ts
planPull(
  state: SyncState,
  local: LocalSnapshot,
  remote: ChangeEntry[],
  opts: { localAuthor: string },   // extensible object
): PullPlan
```

`planPull` 返回动作 **(排名,路径)**数字 :

| 军衔 | 动作类型 | 原因 |
| --- | --- | --- |
| 0 个 | `conflict` | 先写本地副本, 然后在路径上应用远程 |
| 1个 | `delete` | 在可能共享相同大小写文件夹名的任何写入之前删除 |
| 2个 | `write`, (中文(简体) ), `noop` | 冲突和删除完成后安全 |

对于对案件不敏感的财务服务,需要这种命令。 只更改大小写重命名 以 `delete OldCase.md` + 键 `write newcase.md`; 执行写入-删除 a 对大小写不敏感的财务司将默默地删除新编写的文件.

适配器分两个步骤执行冲突行动:

1.  写入 `localHash` 改为 `copyPath` (当地版本保存在那里).
2.  若为 `remoteHash !== null`: 写入 `remoteHash` 改为 `path`。否则删除 `path`。 。 。 .

### 应用 Pull 计划

```ts
applyPullPlan(state: SyncState, plan: PullPlan): SyncState
```

衍生出新的 `SyncState` 由拉出计划而不改变输入:

-   `write` → `files[path] = { syncedHash: hash }`
-   `delete` → `files[path] = { syncedHash: null }`
-   `noop` → `files[path] = { syncedHash: hash }` (汇合——弥合虚假冲突差距)
-   `conflict` → `files[path] = { syncedHash: remoteHash }`· ; `copyPath` 实值 **没有** 添加到状态
-   `cursor` =: `plan.cursor`

`copyPath` 保持状态,以便下一个 `planPush` 用它上传 `baseHash: null` (新文件)而不是把它当作已知的同步路径.

**推先推后推**: 规则 第 4 条( 本地已删除, 远程修改 = 写入) 可以复活 a 如果您在按下前拉出本地删除的文件 。 总是先推后拉. 这是 有意——内容从不丢失.

## 默认同步客户端( PARCHE-004)

`@chamba/core` 船载纯TypeScript金库同步客户端(没有节点导入),该客户端会说 parche 协议。 从中导入 `vault-sync/` 子路径或直接来自 `@chamba/core`。 。 。 .

### 所需端口

| 端口 | 方法 | 说明 |
| --- | --- | --- |
| `HttpPort` | `request(req)` | HTTP 客户端; `HttpRequest` 带有可选 `AbortSignal`。 。 。 . |
| `HashPort` | `sha256(data)` | Async SHA-256返回一个小写十六进制字符串. |
| `FilesystemPort` | `readBytes / writeBytes / rename / stat` | 二进制 I/O; `writeBytes` 接受 `{ mode? }` 用于chmod风格的权限. |
| `ClockPort` | `now() / today() / sleep?()` | 沃尔克和可选的合成睡眠. |

### 主要出口

```ts
// Ports
import type { HttpPort, HttpRequest, HttpResponse } from '@chamba/core';
import type { HashPort } from '@chamba/core';
import type { FileStat, WriteBytesOptions } from '@chamba/core';

// Sync client
import { syncOnce, joinOnce, scanLocal, CaseCollisionError } from '@chamba/core';
import { readState, writeState } from '@chamba/core';
import { CredentialsStore } from '@chamba/core';
import { ParcheClient, ParcheHttpError } from '@chamba/core';
import { parseJoinInput, resolveServerUrl } from '@chamba/core';

// Test doubles (in-memory, no Node)
import { FakeParche, FakeHash } from '@chamba/core';
```

### 同步时间

```ts
const summary = await syncOnce({ fs, http, hash, clock }, {
  vaultDir: '/path/to/vault',
  server: 'https://parche.chamba.tools',
  slug: 'my-group',
  token: 'pch_…',
  localAuthor: 'joys',
  device: 'laptop',
});
// summary: { pushed, pulled, conflicts, movedToTrash, errors }
```

三相相相流: **推动本地修改 = 获取所有远程页面 = 应用拉动计划**。所有远程页面在尝试任何磁盘写入之前都是在内存中累积的(AC13: page-N 失败叶状态不变,没有部分写入).

### 加入时

电话 `POST /api/join`,将设备符号保存到 `~/.chamba/credentials.json` (mode 0600),创建 `.obsidian/`重新编辑 `state.json` 与 `cursor: 0` 和新项目 `groupId` (门决定一:再会从不继承先前同步状态).

### 解决冲突

当本地和远程都从同一碱基修改一个文件时 :

1.  本地版本写入 `a (conflicto joys).md` 带有 YAML 前题(`conflict_of`, (中文(简体) ), `conflict_base`, (中文(简体) ), `conflict_at`) (中文(简体) ).
2.  远程版本替换 `a.md`。 。 。 .
3.  该副本被推入第3阶段(`baseHash: null`,新文件).

**第2号门决定——解禁**:在创建副本之前,跑者扫描了已存在的副本,其前题和字节匹配. 如果找到, 则对现有路径进行再利用( 在崩溃- 当时- 重试时具有独有性) .

### 测试双倍

`FakeParche` 执行 `HttpPort` 包含完整内存的服务器语义 `baseHash` 冲突侦测、blob存在检查、大小写侦测、平滑和可配置的故障接头(`pageLimit`, (中文(简体) ), `failChangesPage`, (中文(简体) ), `corruptBlob`, (中文(简体) ), `rejectPushBlobs`) (中文(简体) ).

`FakeHash` 用途 `globalThis.crypto.subtle` (不导入节点),生产与SHA-256相同的SHA-256 `NodeHash`。 。 。 .

## 许可证

麻省理工学院

## 常见问题

### @chamba/core 是什么？

Chamba的核心逻辑:工作空间扫描仪,计划\+heuristic审查器,git工作树,Obsidian,内存——节点APIs,没有LLM

### 如何安装 @chamba/core？

在项目目录运行 npm install @chamba/core，或使用 pnpm add / yarn add / bun add。

### @chamba/core 支持 TypeScript 吗？

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

### @chamba/core 支持 ESM 还是 CommonJS？

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

### @chamba/core 可以商用吗？

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

### @chamba/core 的下载量有多少？

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

### @chamba/core 还在维护吗？

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