@ chamba/ 核心
纯核心逻辑 香槟:工作空间扫描仪, 计划生成器 + 高压审查器, git 工作树管理器, Obsidian 上下文/上下文 编剧,还有一个文件系统记忆库.
- 节点 API 直接 ——所有OS访问通过端口(
FilesystemPort, (中文(简体) ),ProcessPort, (中文(简体) ),ClockPort),所以可以测试,运行时间不可知. - 无 LLM - chamba从来不叫模特儿.
- 港口的节点实施
@chamba/adapters。 。 。 .
大多数用户想要 @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) 在所有地方使用的犬类形式 :
pathKey('Nota.md') // → 'nota.md'
pathKey('NOTAS/A.MD') // → 'notas/a.md'
pushRequestSchema 当同一路径出现两次或两次时,拒绝推动
现场直播 条目(newHash !== null(单位:千美元) pathKey (例如:. Nota.md → H1 + 键 nota.md → H2) (中文(简体) ).
删除后加上相同的活条目 pathKey 是外壳重命名并有效 :
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']]。 。 。 .
签名和行动令
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
对大小写不敏感的财务司将默默地删除新编写的文件.
适配器分两个步骤执行冲突行动:
- 写入
localHash改为copyPath(当地版本保存在那里). - 若为
remoteHash !== null: 写入remoteHash改为path。否则删除path。 。 。 .
应用 Pull 计划
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?() | 沃尔克和可选的合成睡眠. |
主要出口
// 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';
同步时间
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 (门决定一:再会从不继承先前同步状态).
解决冲突
当本地和远程都从同一碱基修改一个文件时 :
- 本地版本写入
a (conflicto joys).md带有 YAML 前题(conflict_of, (中文(简体) ),conflict_base, (中文(简体) ),conflict_at) (中文(简体) ). - 远程版本替换
a.md。 。 。 . - 该副本被推入第3阶段(
baseHash: null,新文件).
第2号门决定——解禁:在创建副本之前,跑者扫描了已存在的副本,其前题和字节匹配. 如果找到, 则对现有路径进行再利用( 在崩溃- 当时- 重试时具有独有性) .
测试双倍
FakeParche 执行 HttpPort 包含完整内存的服务器语义 baseHash 冲突侦测、blob存在检查、大小写侦测、平滑和可配置的故障接头(pageLimit, (中文(简体) ), failChangesPage, (中文(简体) ), corruptBlob, (中文(简体) ), rejectPushBlobs) (中文(简体) ).
FakeHash 用途 globalThis.crypto.subtle (不导入节点),生产与SHA-256相同的SHA-256 NodeHash。 。 。 .
许可证
麻省理工学院