跨端工作使用手册

换台电脑，手上的活接着干。

适用版本：v4.6.1 ｜ 技能名：youchaoyun-cross-device ｜ 作者：有巢数智 www.youchaoyun.com

0. 三十秒看懂

这个技能只做一件事：把你在这台电脑上的工作现场，存进 WorkBuddy 自带的资料库；换一台电脑，说一句话取回来。

它不打包整个硬盘。它只搬两样东西：

• 产物——你写的文档、代码、表格、图片；
• 上下文——AI 记住的你是谁、你们聊过什么、你装过哪些技能。

而且这两样东西，它是分开处理的：

产物如果归 Git 管，就交给 Git；上下文和其余产物，交给同步。

为什么要这么分，见第 6 节。先记住这一句就够了。

日常只有两句话：

你说	什么时候说
「收工」（或”完工""今天到这”）	今天干完了，下班前
「开工」（或”换设备了""新电脑""接着做”）	换机器了，打开先

1. 安装：三步，五分钟

步骤 0：先确认两件事

本技能不读写任何第三方密钥，资料库走客户端托管通道。但有两样东西必须在位，否则命令会直接失败：

条件	不满足时的表现
已登录 WorkBuddy	命令报错退出
资料库里有至少一个空间	报 [E-PERM]——这是权限问题，不是密钥问题

技能市场页上有一个「需配置 API Key」标签，请忽略它。 那是市场自动生成的分类标签，与这个技能的依赖无关。你不需要填任何 Key。

步骤 1：拿到技能本体

技能本身也在同步范围内，所以”用技能去拉技能”不成立——第一块砖得从外面搬进来。但这件事现在不用你亲手做了，两条路选一条。

A. 从技能市场安装（推荐）

把下面这句话原样发给电脑上的 WorkBuddy：

请根据 https://skillhub.cn/install/skillhub.md，安装 @user_d709d9e7/youchaoyun-cross-device

它会自己装好。

市场页地址：https://skillhub.cn/skills/user_d709d9e7/youchaoyun-cross-device

B. 手动下载（兜底）

适合三种情况：市场装不上、想锁定某个版本、内网离线部署。

下载技能包 youchaoyun-cross-device.zip

下载地址固定，升级不换链接。

解压后得到一个 youchaoyun-cross-device/ 文件夹，整个放进技能目录：

~/.workbuddy/skills/youchaoyun-cross-device/

Windows 上是 C:\Users\你的用户名\.workbuddy\skills\youchaoyun-cross-device\。

技能装在电脑上。如果你现在是用手机看这页，别在手机上点下载——把上面那句 prompt 复制到电脑上的 WorkBuddy 里发出去，比下载完再传过去省事。

步骤 2：重启一次会话

技能是按会话加载的。新建一个对话就生效，不用重启整个客户端。

步骤 3：验证

在新会话里说一句 「状态」。

• 能报出”全部已纳管空间 ＋ 账号资产”，说明装好了；
• 报”未纳管”，说明装好了但还没开始用，正常，进入第 2 节。

提示：技能文件改动是热加载的，以后改技能不用重启客户端；只有”首次安装”需要新开会话。

装不上、或者报错看不懂，先别硬试。关注服务号回复 【排障】 看最常见的九个坑，回复 【体检】 做一次三分钟自测。

2. 第一次跑：把自己的一个空间纳管进来

「纳管」是这个工具唯一的入口。没纳管的空间，它一律不碰。

为什么这么设计？因为客户端会随对话自动生成一堆日期空间。如果全部同步，你会得到一堆空镜像。所以要你逐个点头。

纳管之后，云端长这样

图为 v4.6.1 时的界面，按钮位置可能随版本调整。spaces/ 下一个空间一份镜像；memory/ 是长期记忆与日志，sessions/ 是导出成 Markdown 的对话正文——右边那份就是一次真实对话。点图可放大。

流程

① 选一个空间，说「纳管」

比如你有个项目在 D:\Dev\myproject，就说：

把这个空间也管起来

AI 会先跑一次只读计划，把「同步范围 ＋ 排除项 ＋ 云端落点」讲给你听，然后再动手。

② 首次是全量上传，先干跑一次

第一次纳入跨端，要把整个空间传上去。如果目录很大（比如几百兆），先说一句：

只看清单，先别传

AI 会跑 --dry-run，列出会传哪些、跳过哪些、有没有超限的。看完没问题再让它真跑。

③ 它会自动判定同步范围

看第 6 节。简单说：这个目录里有 .git 吗？ 有 → 只同步记忆和状态，产物归 Git；没有 → 整份带走。

换到新设备时怎么接上

在另一台电脑上，同样先装技能（第 1 节），然后：

① 说「开工」——它会先取回账号资产（你的记忆和技能），再把所有已纳管的空间拉下来。

② 如果那台机器上还没有这个空间，说：

同步 我的项目

AI 会列出云端已有的镜像让你挑，你只要说「第几个」。认领只认内部标识，不靠目录名对齐——所以两台机器的文件夹名不一样也没关系。

3. 日常：两句话

下班：「收工」

AI 依次做四件事：

1. 把每个空间里的对话正文导出成 Markdown（存在 .workbuddy/sessions/，只留人话，工具调用和命令输出会丢掉，密钥自动打码）；
2. 把本机比云端新的文件推上去；
3. 核对一遍，报「推了几个、取了几个、跳过几个、几个冲突」；
4. 把账号资产（身份记忆、你勾选过的自建技能）同步上云。

方向是固定的：收工只推不拉。 云端有更新的东西，它只报告，不会偷偷拉下来覆盖你正在改的。

上班：「开工」

反过来：账号资产取回 → 所有空间拉下来 → 核对。

方向也是固定的：开工只拉不推。

想反着来，明说：「只推」或「只拉」。

一条重要的保险

本地删掉的文件，不会被拉回来。

你在 A 机器上删了一个过时文档，B 机器上还留着。下次 B 拉取时，它不会”因为云端有所以恢复给你”——删除会留下标记，跨设备传播。想恢复得明说「恢复这个文件」。

4. 五条命令（你只需要记住说法）

你不用敲命令，说人话就行。但知道有哪五条，能让你说得更准。

你说	作用范围	方向
收工 / 完工 / 今天到这	整台设备 ＋ 账号资产	只推
开工 / 换设备了 / 新电脑	整台设备 ＋ 账号资产	只拉
同步	当前这一个空间	双向
同步资产	账号级（记忆 / 技能）	双向
状态	整台设备	只读，什么都不动

五个限定语，可以加在命令后面收窄范围：

只推 ／ 只拉 ／ 〈空间名〉 ／ 资产 ／ 记忆·技能

这里是新手最容易搞混的一处：「同步」和「同步资产」只差两个字，一个是空间级（搬文件），一个是账号级（搬记忆和技能）。

不用担心说错——AI 执行时的第一行一定会打印「层级＝设备级／空间级／账号级」，你一眼就能看出它理解成了哪个。

表外的说法，它会先问你。 比如”存一下""保存一下”这种模糊词，它不会自己猜着执行。

5. 它搬什么、不搬什么

会跨端	不会跨端
空间里的产物（默认全带）	凭据、密钥、令牌、连接器授权
长期记忆与日志（.workbuddy/memory/）	缓存、索引、运行时、客户端数据库
空间状态与跨端锚（.workbuddy/state.json）	构建产物、依赖目录、临时文件
自建/私有技能本体	公共技能本体（只记市场标识，换端重装）
身份记忆文件	专家 / 专家团本体（只记三字段标识）
对话正文（.workbuddy/sessions/）	会话列表 / 侧栏本身

凭据为什么不搬？ 不是遗漏，是安全边界。同步工具的云端一旦存了凭据，它的安全性就取决于你最弱的那台设备。换设备重新登录一次就恢复了，不值得冒这个险。

想排除某个文件？ 在工作空间里建 .workbuddy/syncignore，每行一个路径或通配符。

临时脚本、一次性验证脚本，放 .workbuddy/tmp/ 就不会被同步。

6. 最关键的一条：它是怎么分档的

这一节解释”为什么不能全量搬”。

一个目录，可能是两种性质：

• 普通空间（写方案、写文档）→ 整份带走。
• Git 空间（写代码）→ 只同步记忆和状态，产物交给 Git。

判断方式不是”看这个目录下有没有 .git”，而是向上追溯到最近的仓库根，再分三种情况：

情况	判定	同步什么
不在任何仓库里	普通空间	产物 ＋ 记忆 ＋ 状态
仓库根就是这个目录	Git 空间	只同步记忆 ＋ 状态
仓库根是它的上级	再看是否被 ignore	被 ignore → 全带；没被 ignore → 只同步记忆

为什么第三种情况这么绕？

因为家目录里常有一个 dotfiles 仓库，磁盘根目录有时也有仓库。如果不做这层判断，凡是放在它们下面的空间都会被静默判成 Git 空间——产物一个都不上云，而你以为已经存好了。

这是这个工具早期踩过的最深的坑。

7. 三个必须你亲手做的动作

工具做不到这三件事，需要你点一下。这三处没有捷径。

① 新设备上，让空间出现在侧栏

文件拉回来了，但侧栏里看不到——这很常见。

原因：侧栏是按「会话」分组的，读的是会话表，不是工作空间记录表。 脚本不写客户端数据库（写记录表实测无效，伪造会话又会污染列表）。所以只能你来：

在客户端对那个目录点一次「打开文件夹」。

说一句「状态 〈空间名〉」，它会明确告诉你”已在侧栏”还是”需要打开文件夹一次”。

② 召唤专家

专家 / 专家团只记三个字段的标识（市场、名称、ID），不搬本体，工具也没有安装接口。

换设备后，按清单里的标识在客户端专家中心召唤或启用一次即可。

③ 手动拿到技能本体

就是第 1 节的步骤 1。自举环还在，但市场装只需要一句话，不必再手工搬文件夹。

8. 两边都改了怎么办

这是跨端最怕的事：另一台电脑把你正在改的东西盖掉了。

这个工具的做法是：先问。

流程

① 说「冲突了」或「两边都改了」

它会先出一份只读的计划，把每一项摆给你：

• 哪些是”仅本机有”
• 哪些是”仅云端有”
• 哪些”两边都改过”（会报出云端改动时间、本地文件时间）

② 它默认先试着合并

文本和表格类的冲突，会先走一次三方合并。能干净合上的，直接合，不问你。

合不上的，才会拦住让你挑边：取本地 / 取云端 / 合并 / 跳过。

③ 你定完，它一次执行完

不会”跑到一半再问一次”，也不会”问完再从头上跑一遍”。

冲突文件放哪

统一收在 .workbuddy/conflicts/〈时间〉/，里面带一份《冲突说明.md》。

不会往你的工作目录里撒一堆 .local-xxx 副本。

一个判断细节

它判断”谁更新”不看文件时间戳——各电脑的时钟不可信，云端时间也只是上传时间。

它比的是云端节点的版本戳：比对本机上次记下的版本，变了就是云端动过。

所以不会出现”因为时钟不准，把新版判成旧版”。

9. 九个已知限制（挑最可能撞上的说）

完整版见技能包 README。这里只说你会真实遇到的。

① 云端删不掉东西，所以”删除”是软删。 资料库没有硬删接口。本机删掉的文件会被记成”已删标记”，云端对应节点尽量移进 _deleted/ 归档。要彻底清掉，只能在网页端手工删。

② 首次同步会全量上传。 大目录第一次纳入时流量不小。先跑一次”只看清单”的干跑。

③ 全新设备第一次拉取偏保守。 没有可比对的版本记录时，遇到不一致一律按”本地已改”处理，会多出几个待裁决项。这是防误覆盖的代价，跑一次基线补齐就恢复正常。

④ 网页（.html）能推上云，但别指望能原样拉回来。 资料库把网页当”可在线编辑的页面”，导入后会被平台改写（注入自己的 id 和脚本）。所以推上去没问题、网页端能看能分享，但拉取时绝不覆盖你本机的原文件——本机是源，云端是发布版。

⑤ 网页里不能留第三方图片外链。 https://某站/x.png 这种，资料库要求先把图片托管成平台内链，工具会检出并拒绝该文件（不会擅自改你的源文件）。

⑥ .zip 不上云。 云端会把它解包成散文件，拉不回原包。换设备时压缩包不会恢复。

⑦ .csv 的数字列会被规范化。 001 会变成 1，1234.50 会变成 1234.5。要原样保留编号列，就别让它走同步。

⑧ 超大文件不会被上传，只会被列出来。 上限：文档/数据表/网页 ≤ 50 MiB，网盘文件 ≤ 100 MiB。超限的会被拦下、单独报给你（哪个文件、多大、超哪个通道），不会静默跳过，也不会自动拆文件——拆了就不是同一个产物。

⑨ 云端可能留着重复节点，要人工清一次。 早期版本对非文档文件每次推送都会另建节点，留下同名重复。现在已止住，但遗留的不会自愈。收工时会把重复项连同更新时间列出来，照着”删旧留新”在网页端删掉。

10. 出错了：认码不认句子

报错信息里，方括号括起来的大写串是稳定错误码。不同版本的文字描述会变，码不会变。

错误码	意思	怎么办
[E-CONFLICT]	两边都改过	说「冲突了」，走第 8 节流程
[E-DELETED]	本地已删，不复活	想恢复就明说「恢复这个文件」
[E-DUP]	云端有同名重复节点	网页端删旧留新
[E-LIMIT]	文件超通道上限	拆小，或改走别的通道
[E-LOCK]	本机文件被占用	关掉占用的程序再重跑
[E-SANDBOX]	沙箱拦截写入	关沙箱后重跑同一条命令即可续传
[E-PERM]	云端权限不足	检查资料库空间权限
[E-CLOUD]	云端读回失败	重试；反复失败就把码和上下文发给 AI
[E-STATE]	状态文件损坏	让 AI 按 README 的方法重建
[E-SELECTION]	清单结构读不懂	通常是版本不匹配，升级技能

两个不用慌的信号：

• 进程退出码 3 不是失败，意思是”有需要你裁决的项”。裁决完再执行即可。
• 所有命令都可以原样重跑。 幂等设计，已经传成功的部分不会重复上传、不会重复改名。

拿不准的时候，把错误码连同上下文一起发给 AI，比描述”它报错了”有用得多。

11. 卸载

删掉技能目录即可：

~/.workbuddy/skills/youchaoyun-cross-device/

云端的数据不会跟着删。 想清空，得在资料库网页端手工处理（脚本没有删节点的接口）。

如果只是不想让某个空间继续同步，删掉该空间目录下的 .workbuddy/state.json 就退出纳管了。

附录：速查卡（建议截图存手机）

日常两句话
  下班 → 收工
  换机 → 开工

五条命令
  收工 / 开工 / 同步 / 同步资产 / 状态

三个手工动作（绕不过）
  ① 新设备：对目录「打开文件夹」一次
  ② 专家：客户端专家中心召唤一次
  ③ 技能本体：第一次必须手动装

三条铁律
  ① 收工只推、开工只拉
  ② 本地删了不复活
  ③ 两边都改先问，绝不静默覆盖

出错了
  看方括号里的错误码，不看句子
  退出码 3 = 等你裁决，不是失败
  所有命令都能原样重跑

本手册为 v4.6.1 版本的人读版，与技能包内的 SKILL.md（机器执行版）可能存在表述差异，以 SKILL.md 为准。 本页随版本更新；公众号等渠道上的版本是发布时的快照，可能滞后，以本页为准。 反馈与排障：关注服务号，回复「排障」。