@celljs/ta-sync 0.0.0-stage → 4.13.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +55 -0
- package/README.md +54 -2
- package/host/index.mjs +3763 -0
- package/package.json +55 -4
- package/web/index.js +2018 -0
package/README.en.md
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Cell - Ta Sync
|
|
2
|
+
|
|
3
|
+
A pi package that comes with Ta (on by default; turn it off in Settings → Extensions): sync. Your settings, instructions, skills and extensions the same on each of your computers, **without an account**: the computers share a room of the relay that only they are in, sealed end to end, which the relay cannot read. Design record: [docs/design/ta-sync.md](../../docs/design/ta-sync.md).
|
|
4
|
+
|
|
5
|
+
- **Turn it on**: Settings → Sync, Turn on sync. This computer adds the others.
|
|
6
|
+
- **Add a computer**: Add a device gives a link and a QR code (7 days); in Ta on the other computer, Join a sync, paste the link or scan the code; back on the first computer, Allow. The new computer takes what the sync has, keeping aside what it had.
|
|
7
|
+
- **What to sync** (each computer for itself): settings (settings.json but the paths and commands of this computer, and keybindings), instructions (AGENTS.md and the like), skills, prompts and themes, models and MCP (may hold API keys, off by default), extensions (packages from npm or git installed by their source, your own extensions copied whole), data of extensions (the look of Ta, your double, and the keys extensions declare).
|
|
8
|
+
- **When**: a change on one reaches the others online within seconds; one offline catches up when it starts; Sync now does it at once.
|
|
9
|
+
- **Conflicts**: settings merge key by key; a file changed on both takes the later. What a sync replaced or deleted here is kept in `sync/replaced/<time>/` of the agent directory, and the page says so.
|
|
10
|
+
- **Stop**: a computer that stops only stops itself; when the one that turned sync on stops, every computer does. Each keeps what it has. That computer can also remove another.
|
|
11
|
+
|
|
12
|
+
Never synced: sign-ins (`auth.json`), the identity and keys of rooms, sessions, the state of a device or of a directory.
|
|
13
|
+
|
|
14
|
+
## Sync through a folder of a cloud drive (no relay)
|
|
15
|
+
|
|
16
|
+
In Settings → Relays, Sync in iCloud Drive (or another drive; or type a `~/…` path in Add a relay) makes sync go through that folder, **with no relay at all**: the drive keeps the folder the same on your computers, and what Ta writes there is sealed, names included, so the drive sees nothing of it.
|
|
17
|
+
|
|
18
|
+
- Turning on and joining: once on, Add a device gives a `ta-sync://folder#…` link; on the other computer, Join a sync and paste it, nobody need allow it. The link holds the key of the sync for good: show it only to your own computers. The other computer needs the same folder of the drive.
|
|
19
|
+
- How fast depends on the drive bringing the files (iCloud often takes seconds to minutes); Ta watches the folder and looks every 30 seconds too.
|
|
20
|
+
- The folder holds `ta-sync/<space>/`: each computer writes only its own directory, so the drive makes no conflicted copies. The key of the sync is in `sync/folder.json` of the agent directory.
|
|
21
|
+
|
|
22
|
+
## Sync through WebDAV, S3 or a git repository of your own
|
|
23
|
+
|
|
24
|
+
In Settings → Relays, Sync in WebDAV, Sync in S3 or Sync in Git: fill in the address and keys (Jianguoyun, Nextcloud, a NAS, AWS, Cloudflare R2, MinIO, a private repository on GitHub or Gitee…), and once Ta wrote there it syncs there, **with no relay**, content and names sealed first. The `ta-sync://store#…` link of Add a device carries the sign-in of the store, so another computer joins by pasting it: show it only to your own computers. The built-in extension `@celljs/ta-sync-cloud` adds both.
|
|
25
|
+
|
|
26
|
+
## Move to another computer
|
|
27
|
+
|
|
28
|
+
On a new computer or after a reinstall, move everything at once, **the conversations too**, as WeChat moves a chat history: Settings → Move to another computer.
|
|
29
|
+
|
|
30
|
+
- **Over your network**: on the old computer choose what goes and press Start; a QR code shows. On the new one, under To this computer, pick it among the computers nearby, or paste its link, or scan the code with the Ta app; both show the same six digits, and once they match you Allow it on the old computer. Sealed end to end, never through the relay, as fast as your network.
|
|
31
|
+
- **Backup file**: when the two are on different networks, or to keep a copy, back up to one `.tabackup` file (in Downloads by default) and restore it on the new computer. A password seals it; sign-ins and the identity go only with one.
|
|
32
|
+
- **How it merges**: conversations the new computer has stay, never doubled; settings merge key by key, the old computer's winning; the directories of conversations and the paths in the data of extensions become the new computer's. What was replaced is kept in `sync/replaced/<time>/`.
|
|
33
|
+
- **Identity and rooms** (off by default): who you are in rooms, the rooms and your friends go too, so others still see you on the new computer and nobody invites you again. Rooms the new computer was in keep its own identity. Whoever has your identity can pass for you: a backup file needs a password for it.
|
|
34
|
+
|
|
35
|
+
## The same you on several computers
|
|
36
|
+
|
|
37
|
+
Turn on Identity and rooms in device sync (off by default, asked first): your computers are one identity in rooms, with the same rooms, friends and permissions of your double. When someone asks your double, one computer answers, the one you are at first. The identity of the computer that turned it on first holds; rooms a later one was in keep the identity it joined them with. See `docs/design/ta-sync.md` 9.
|
|
38
|
+
|
|
39
|
+
## Data of extensions that goes with the user
|
|
40
|
+
|
|
41
|
+
An extension declares in its package.json which keys of `pi.storage` are the user's (a game's best score, its preferences), and they go to the user's other computers:
|
|
42
|
+
|
|
43
|
+
```json
|
|
44
|
+
{ "pi": { "web": ["./web.js"], "sync": ["best", "settings"] } }
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Declare only small values of the user; nothing of one computer or of a directory (`pi.storage.directory`).
|
|
48
|
+
|
|
49
|
+
## Methods of its host
|
|
50
|
+
|
|
51
|
+
A web extension calls them with `callPackageHost('@celljs/ta-sync', …)`: `status()`, `enable()`, `invite(renew?)`, `join(link)`, `answer(ask, accept)`, `leave()`, `removeDevice(member)`, `setResources({ settings?: boolean, … })`, `syncNow()`; all but `invite` answer the `SyncStatus` as it is now. Moving: `migrateCounts()`, `migrateOpen(categories)`, `migrateAnswer(ask, allow)`, `migrateCloseOut()`, `migrateDiscover()`, `migrateStopDiscovering()`, `migrateReceive(link)`, `migrateCloseIn()`, `migrateExport(categories, password?, dir?)`, `migrateImport(path, password?)`, `migrateBackups()`; the status is in the key `migrate` of the data of the package. The status is also in the key `status` of the data of the package, which the page hears.
|
|
52
|
+
|
|
53
|
+
## Development
|
|
54
|
+
|
|
55
|
+
`bun run build`: compiles and bundles the page (`web/index.js`) and the sync (`host/index.mjs`). `apps/ta/test/sync.spec.ts` starts a relay and two `ta serve`, and tests joining, sync both ways and stopping.
|
package/README.md
CHANGED
|
@@ -1,3 +1,55 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Cell - Ta Sync
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Ta 自带的 pi 包(默认开启,可在 设置 → 扩展 关闭):设备同步。让你的每台电脑都有同样的设置、指令、技能和扩展,**不用登录账号**:几台电脑在中继上共用一个只有它们自己的房间,内容端到端加密,中继读不到。设计记录见 [docs/design/ta-sync.md](../../docs/design/ta-sync.md)。
|
|
4
|
+
|
|
5
|
+
- **开启**:设置 → 设备同步,点"开启同步"。这台电脑负责添加设备。
|
|
6
|
+
- **添加电脑**:点"添加设备"得到链接和二维码(7 天有效);在另一台电脑的 Ta 里点"加入已有的同步",粘贴链接或扫码;回到第一台电脑点"同意"。新电脑以已有的同步为准,原有内容留底。
|
|
7
|
+
- **同步哪些内容**(每台电脑各自设置):设置(settings.json 里本机路径和命令以外的部分、快捷键)、指令(AGENTS.md 等)、技能、提示词和主题、模型与 MCP(可能含 API 密钥,默认关)、扩展(npm / git 来源的包按来源安装,自己做的扩展整体复制)、扩展数据(Ta 的外观设置、分身的样子,以及扩展声明的键)。
|
|
8
|
+
- **什么时候同步**:任何一台改了,其他在线的电脑几秒内跟上;离线的下次启动时补上;也可以点"立即同步"。
|
|
9
|
+
- **冲突**:设置按键合并;同一个文件两边都改了,以较新的为准。被覆盖或删除的本机内容保存在 agent 目录的 `sync/replaced/<时间>/`,同步页上有提示。
|
|
10
|
+
- **停止**:一台电脑停止只影响它自己;开启同步的电脑停止,所有电脑都停止。各自保留现有内容。开启同步的电脑可以移除别的电脑。
|
|
11
|
+
|
|
12
|
+
不同步:登录凭据(`auth.json`)、身份与房间密钥、会话、按设备或按目录的界面状态。
|
|
13
|
+
|
|
14
|
+
## 经网盘文件夹同步(不经过中继)
|
|
15
|
+
|
|
16
|
+
在 设置 → 中继服务 里点"用 iCloud Drive 同步"(或别的网盘,也可以在"添加中继"里填 `~/…` 路径),设备同步就改为经这个文件夹进行,**完全不经过中继**:网盘负责把文件夹在你的几台电脑间保持一致,Ta 写进去的内容和文件名都先加密,网盘看不到。
|
|
17
|
+
|
|
18
|
+
- 开启和加入:开启同步后点"添加设备"得到 `ta-sync://folder#…` 链接,在另一台电脑上"加入已有的同步"粘贴即可,不需要谁同意;链接里有同步密钥且长期有效,只给自己的电脑。另一台电脑要能访问网盘里的同一个文件夹。
|
|
19
|
+
- 速度取决于网盘把文件同步过来的快慢(iCloud 常是几秒到几分钟);Ta 监听文件夹变化,另外每 30 秒检查一次。
|
|
20
|
+
- 文件夹里是 `ta-sync/<空间>/`:每台电脑只写自己的子目录,所以网盘不会出现冲突副本。同步密钥存在本机 agent 目录的 `sync/folder.json`。
|
|
21
|
+
|
|
22
|
+
## 经自己的 WebDAV、S3 或 git 仓库同步
|
|
23
|
+
|
|
24
|
+
设置 → 中继服务 里点"用 WebDAV 同步""用 S3 同步"或"用 Git 同步",填好地址和密钥(坚果云、Nextcloud、NAS、AWS、Cloudflare R2、MinIO,或 GitHub、Gitee 上的私有仓库都可以),Ta 试写成功后就用它同步,同样**不经过中继**,内容和文件名先加密。"添加设备"给出的 `ta-sync://store#…` 链接里带着存储的登录信息,另一台电脑粘贴就能加入,只发给自己的电脑。这几种存储由内置扩展 `@celljs/ta-sync-cloud` 提供。
|
|
25
|
+
|
|
26
|
+
## 迁移到另一台电脑
|
|
27
|
+
|
|
28
|
+
换电脑或重装时,像微信迁移聊天记录一样一次搬完,**包括对话**:设置 → 迁移到另一台电脑。
|
|
29
|
+
|
|
30
|
+
- **局域网直连**:旧电脑选好内容点"开始",出现二维码;新电脑在"迁入到这台电脑"里从附近的电脑中选它,或粘贴链接、用 Ta 手机 App 扫码;两边显示同一串 6 位数字,核对后在旧电脑上点"同意"。端到端加密,不经过中继,速度取决于你的网络。
|
|
31
|
+
- **备份文件**:两台电脑不在同一网络,或者想留一份,就备份成一个 `.tabackup` 文件(默认放在"下载"),带到新电脑上恢复。可以设密码加密;登录凭据和身份只有设了密码才会写进去。
|
|
32
|
+
- **合并方式**:新电脑已有的对话保留,不会重复;设置按键合并,旧电脑的值优先;对话的目录、扩展数据里的路径都换成新电脑的。被替换的原有内容保存在 `sync/replaced/<时间>/`。
|
|
33
|
+
- **身份与房间**(默认不勾):你在房间里的身份、所在的房间和 好友一起带过去,新电脑上别人看到的还是你,不用重新邀请。新电脑原来所在的房间保留原来的身份。拿到身份的人就能冒充你,所以备份文件必须设密码。
|
|
34
|
+
|
|
35
|
+
## 几台电脑是同一个你
|
|
36
|
+
|
|
37
|
+
设备同步里打开"身份与房间"(默认关,打开时会确认):这几台电脑在房间里是同一个身份,房间、好友和分身的授权都一样。别人 @ 你的分身时,只由一台回答:优先是你正在用的那台。先打开的电脑的身份为准,后打开的电脑原来所在的房间保留原来的身份。详见 `docs/design/ta-sync.md` 第 9 节。
|
|
38
|
+
|
|
39
|
+
## 扩展的数据跟着用户走
|
|
40
|
+
|
|
41
|
+
扩展在 package.json 里声明哪些 `pi.storage` 键是用户的(例如游戏的最高分、扩展的偏好),它们就会同步到用户的其他电脑:
|
|
42
|
+
|
|
43
|
+
```json
|
|
44
|
+
{ "pi": { "web": ["./web.js"], "sync": ["best", "settings"] } }
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
只声明属于用户的小值;属于这台电脑或某个目录的(`pi.storage.directory`)不要声明。
|
|
48
|
+
|
|
49
|
+
## 包宿主的方法
|
|
50
|
+
|
|
51
|
+
Web 扩展经 `callPackageHost('@celljs/ta-sync', …)` 调用:`status()`、`enable()`、`invite(renew?)`、`join(link)`、`answer(ask, accept)`、`leave()`、`removeDevice(member)`、`setResources({ settings?: boolean, … })`、`syncNow()`;除 `invite` 外都返回最新的 `SyncStatus`。迁移:`migrateCounts()`、`migrateOpen(categories)`、`migrateAnswer(ask, allow)`、`migrateCloseOut()`、`migrateDiscover()`、`migrateStopDiscovering()`、`migrateReceive(link)`、`migrateCloseIn()`、`migrateExport(categories, password?, dir?)`、`migrateImport(path, password?)`、`migrateBackups()`,状态在包数据的 `migrate` 键里。状态也写在包数据的 `status` 键里,页面据此刷新。
|
|
52
|
+
|
|
53
|
+
## 开发
|
|
54
|
+
|
|
55
|
+
`bun run build`:编译并打包页面(`web/index.js`)和同步服务(`host/index.mjs`)。`apps/ta/test/sync.spec.ts` 起一个本地中继和两个 `ta serve`,测加入、双向同步和停止。
|