feat(skills): auto-resolve sync conflicts by content and newer timestamp (0.9.9)

Same-name skills no longer always stop for a human: identical bytes adopt the delivery marker in place, differing bytes compare local file mtime with the center updated_at and the newer side wins (cloud overwrite backs the local folder up first). Equal or missing timestamps, unsupported upload layouts and script-review flags still surface as per-item conflicts, so there is no batch action.
This commit is contained in:
newbie 2026-11-14 14:24:36 +08:00
parent 881f822c69
commit dbf39339c2
10 changed files with 611 additions and 47 deletions

View File

@ -125,17 +125,19 @@ v1 范围:支持 发现 / 状态 / 搜索 / 浏览 / 写入 / 按 id 读取;
端;之后的修改以新修订发布,带 `expected_revision` 守卫,云端被
别人先改过就报冲突、不强行覆盖。
防事故的规矩:云端交付的技能从不回传,本地改动它只报
`locally_modified` 冲突、原样不动;本地删除不删云端,且同版本不会
被重新拉回(云端出了新版才会再下来);同名技能两边都有时互不抢占,
报 `name_collision`。云端只接受固定布局(根目录只有 `SKILL.md`,
防事故的规矩:先比内容,本地与云端逐字节一致时直接补交付记录,不传
不覆盖;内容不同时按时间自动取较新的一边——云端 `updated_at` 更新就
先备份本地再覆盖,本地文件 mtime 更新就发布新修订;只有时间相同或缺
失时才报冲突(`locally_modified` / `name_collision` / `cloud_newer`),
等面板里逐项确认。本地删除不删云端,且同版本不会被重新拉回(云端出
了新版才会再下来)。云端只接受固定布局(根目录只有 `SKILL.md`,
其余文件进 `references/`、`scripts/`、`assets/`,扩展名有白名单,
单文件 ≤512 KiB、整包 ≤2 MiB、≤100 个文件),不符合的本地技能报
`unsupported_layout`,不会为了迁就而裁剪文件。
验证:`node verify-skills-sync.mjs`(对本地 stub 技能中心跑通
下行安装、上行发布与修订、改云端技能报冲突、同名冲突、脚本待审、
布局拒绝、删除不传播全流程)。
下行安装、上行发布与修订、按时间自动上行/下行、内容一致自动认领、
同名同时间保留冲突、脚本待审、布局拒绝、删除不传播全流程)。
## 技能管理(内置)

View File

@ -974,7 +974,7 @@ window.__ModuleLoader__.load({
),
)
})
return h(Section, { title: '云端同步与冲突', hint: '同步冲突不会被静默覆盖;逐项选择保留本地(上传为新版本)、采用云端(先备份本地)或手动合并。', aside: h(Btn, { label: state.busy === 'run' ? '同步中…' : '立即同步', variant: 'small', disabled: state.busy !== '', onClick: runNow }) },
return h(Section, { title: '云端同步与冲突', hint: '同步先比内容与更新时间:一致直接认领,不同则自动采用较新的一边(覆盖云端前先备份本地);只有时间相同/缺失或目录结构不支持时才逐项询问。', aside: h(Btn, { label: state.busy === 'run' ? '同步中…' : '立即同步', variant: 'small', disabled: state.busy !== '', onClick: runNow }) },
h('div', { style: { display: 'flex', flexDirection: 'column', gap: '10px' } },
state.error === null ? null : h(Banner, { tone: 'bad' }, state.error),
state.notice === null ? null : h(Banner, { tone: state.notice.tone }, state.notice.text),

View File

@ -165,7 +165,7 @@ POST /mcp-connector/api { "method": "status" | "healthCheck" | "toolsList" | "
### 6.3 同步冲突交互
`SkillSync` 仍然只按原策略暂停冲突项,但会暴露两侧信息并允许人工处置:
`SkillSync` 先自动处置:内容一致直接认领,内容不同按「本地文件 mtime vs 云端 `updated_at`」自动采用较新的一边(下行覆盖前备份到 `$DSH_HOME/.dsh-brain-backups/sync/`);只有时间相同/缺失、或本地布局无法上传时才留下冲突,并暴露两侧信息允许人工处置:
| 方法 | 路径 | 说明 |
|---|---|---|
@ -174,7 +174,7 @@ POST /mcp-connector/api { "method": "status" | "healthCheck" | "toolsList" | "
| POST | `/cloud-memory/sync/resolve` | `{name,action}`:`keep_local` / `take_cloud` / `manual` |
- `keep_local`:用本地文件按当前云端 revision 上传为新版本;revision 过期返回 `stale_revision`。
- `take_cloud`:先把本地目录备份到 `$DSH_HOME/.cloud-memory-backups/sync/<name>/<时间>`,再写入云端 bundle。
- `take_cloud`:先把本地目录备份到 `$DSH_HOME/.dsh-brain-backups/sync/<name>/<时间>`,再写入云端 bundle。
- `manual`:只返回两侧信息,不改任何文件。
### 6.4 验证

View File

@ -26,7 +26,7 @@ export const name = 'dsh-brain';
/** Services required before `apply` runs. */
export const inject = ['webServer'];
/** Version reported by the status card. */
const VERSION = '0.9.8';
const VERSION = '0.9.9';
/** How often the skill directory is reconciled with the cloud center. */
const SKILL_SYNC_INTERVAL_MS = 15 * 60_000;
/** How often queued reports are retried. */

View File

@ -15,12 +15,14 @@
* revisions, guarded by the center's `expected_revision` check.
*
* Safety rules (deliberate, in order):
* 1. A cloud-delivered skill is never re-uploaded. If its local files no
* longer match the delivery manifest, the skill is flagged as a
* conflict and left completely alone.
* 1. A cloud-delivered skill is never re-uploaded unless its local copy is
* newer than the center's `updated_at`; before any cloud overwrite the
* local folder is copied to `$DSH_HOME/.dsh-brain-backups/sync/`.
* 2. A local deletion never deletes the cloud copy.
* 3. A name that already exists on the other side is never hijacked;
* it is reported as a conflict for a human to resolve.
* 3. A same-name skill is never hijacked silently: byte-identical copies are
* adopted in place, otherwise the newer side (local file mtime vs center
* `updated_at`) wins; only equal or missing timestamps are reported as a
* conflict for a human to resolve.
* 4. Bundles whose scripts changed on the cloud side are not installed
* until the change is acknowledged in the dashboard, mirroring the
* center's own review flag.
@ -59,6 +61,24 @@ export function linkedSkillManifest(files) {
const lines = files.map((file) => `${file.path}\0${file.sha256}`).sort();
return sha256Hex(Buffer.from(`cloud-memory-skill-v1\n${lines.join('\n')}\n`, 'utf8'));
}
/** Epoch milliseconds from a center timestamp (ISO string or epoch seconds/ms). */
function timestampMs(value) {
if (typeof value === 'number' && Number.isFinite(value))
return value < 1e12 ? value * 1000 : value;
if (typeof value === 'string' && value !== '') {
const parsed = Date.parse(value);
return Number.isFinite(parsed) ? parsed : undefined;
}
return undefined;
}
/** Newest local file mtime in one skill folder (0 when the folder has no files). */
function newestMtime(files) {
let newest = 0;
for (const file of files)
if (file.mtimeMs > newest)
newest = file.mtimeMs;
return newest;
}
/** True when the cloud center would accept this relative file path. */
export function isCloudSkillPath(rel) {
if (rel === '' || rel.length > 200 || rel.startsWith('/') || rel.includes('\\') || rel.includes('//'))
@ -197,7 +217,10 @@ export class SkillSync {
await walk(rel);
}
else if (entry.isFile()) {
out.push({ rel, buffer: await readFile(join(dir, rel)) });
const absolute = join(dir, rel);
const buffer = await readFile(absolute);
const info = await stat(absolute);
out.push({ rel, buffer, mtimeMs: info.mtimeMs });
}
}
};
@ -263,6 +286,145 @@ export class SkillSync {
}
return undefined;
}
/** Center's last-change time for one listed skill (ISO string or epoch). */
cloudUpdatedAt(item) {
return timestampMs(item.updated_at) ?? timestampMs(item.created_at);
}
/** Manifest over every local file, including files the center would reject. */
localManifest(files) {
return linkedSkillManifest(files.map((file) => ({ path: file.rel, sha256: sha256Hex(file.buffer) })));
}
/** Copy a local skill aside before an automatic cloud overwrite. */
async backupLocal(dir, name) {
const stamp = new Date().toISOString().replace(/[:.]/g, '-');
const backup = join(dshHome(), '.dsh-brain-backups', 'sync', name, stamp);
await mkdir(join(backup, '..'), { recursive: true });
await cp(dir, backup, { recursive: true, filter: (path) => !path.split(/[\\/]/).includes('.git') });
return backup;
}
/**
* Local and cloud already carry the same bytes: record the delivery marker
* without a transfer, so the next pass treats the folder as cloud-origin and
* the user is not asked to pick between two identical copies.
*/
async adoptIdenticalDelivery(home, item, files) {
const delivery = {
name: item.name,
...(item.revision === undefined ? {} : { revision: item.revision }),
...(item.manifest_sha256 === undefined ? {} : { manifest_sha256: item.manifest_sha256 }),
files: files.map((file) => ({ path: file.rel, sha256: sha256Hex(file.buffer) })),
synced_at: new Date().toISOString(),
};
await writeFile(join(home, '.manifest.json'), JSON.stringify(delivery, null, 2));
}
/** Fetch, verify and install the cloud copy, backing the local one up first. */
async autoTakeCloud(item, home, installRoot, state, stats, client) {
if (item.script_changed === true) {
this.conflict(stats, item.name, 'script_review_required');
return 'conflict';
}
const bundle = await client.skillBundle(item.name);
if (!bundle.ok) {
this.conflict(stats, item.name, `bundle_failed: ${describeError(bundle.error)}`);
return 'conflict';
}
if (linkedSkillManifest(bundle.data.files) !== bundle.data.manifest_sha256) {
this.conflict(stats, item.name, 'manifest_mismatch');
return 'conflict';
}
if (bundle.data.script_changed === true) {
this.conflict(stats, item.name, 'script_review_required');
return 'conflict';
}
await this.backupLocal(home, item.name);
await this.install(item, bundle.data, installRoot);
this.markDelivered(state, item.name, bundle.data.manifest_sha256);
delete state.removed[item.name];
stats.updated.push(item.name);
return 'resolved';
}
/** Upload the locally-newer copy as the next cloud revision. */
async autoUploadLocal(skill, folder, dir, cloud, state, stats, client) {
const updated = await client.updateSkill(skill.name, {
description: skill.description,
files: this.toUploadFiles(skill.files),
expected_revision: cloud.revision ?? 0,
operation_id: `dsh-skill-${randomUUID()}`,
});
if (!updated.ok) {
const reason = updated.error.code === 'revision_conflict' ? 'cloud_newer' : `upload_failed: ${describeError(updated.error)}`;
this.conflict(stats, skill.name, reason);
return 'conflict';
}
const revision = updated.data.skill?.revision ?? updated.data.revision ?? (cloud.revision ?? 0) + 1;
await rm(join(dir, '.manifest.json'), { force: true });
this.markUploaded(state, skill.name, {
folder,
revision,
manifest: skill.manifest,
syncedAt: new Date().toISOString(),
});
delete state.removed[skill.name];
stats.updated.push(skill.name);
return 'resolved';
}
/**
* Same-name skill on both sides without a delivery record. Identical bytes
* are adopted silently; different bytes go to whichever side is newer;
* equal/missing timestamps stay unresolved for a human decision.
*/
async autoResolveCollision(item, home, installRoot, state, stats, client) {
const localFiles = await this.readSkillFiles(home).catch(() => []);
if (!localFiles.some((file) => file.rel === 'SKILL.md'))
return 'unresolved';
if (item.manifest_sha256 !== undefined && this.localManifest(localFiles) === item.manifest_sha256) {
await this.adoptIdenticalDelivery(home, item, localFiles);
this.markDelivered(state, item.name, item.manifest_sha256);
stats.skipped += 1;
return 'resolved';
}
const cloudAt = this.cloudUpdatedAt(item);
const localAt = newestMtime(localFiles);
if (cloudAt === undefined || localAt === 0 || cloudAt === localAt)
return 'unresolved';
if (cloudAt > localAt)
return this.autoTakeCloud(item, home, installRoot, state, stats, client);
const skill = await this.readLocalSkill(home, item.name);
if (skill === undefined)
return 'unresolved';
if (typeof skill === 'string') {
this.conflict(stats, item.name, skill);
return 'conflict';
}
return this.autoUploadLocal(skill, item.name, home, item, state, stats, client);
}
/**
* Cloud-delivered skill edited locally. Identical bytes refresh the marker;
* otherwise the newer side wins (cloud overwrite is backed up first).
*/
async autoResolveLocalDrift(item, home, state, stats, client, installRoot) {
const localFiles = await this.readSkillFiles(home).catch(() => []);
if (item.manifest_sha256 !== undefined && localFiles.length > 0 && this.localManifest(localFiles) === item.manifest_sha256) {
await this.adoptIdenticalDelivery(home, item, localFiles);
this.markDelivered(state, item.name, item.manifest_sha256);
stats.skipped += 1;
return 'resolved';
}
const cloudAt = this.cloudUpdatedAt(item);
const localAt = newestMtime(localFiles);
if (cloudAt === undefined || localAt === 0 || cloudAt === localAt)
return 'unresolved';
if (cloudAt > localAt)
return this.autoTakeCloud(item, home, installRoot, state, stats, client);
const skill = await this.readLocalSkill(home, item.name);
if (skill === undefined)
return 'unresolved';
if (typeof skill === 'string') {
this.conflict(stats, item.name, skill);
return 'conflict';
}
return this.autoUploadLocal(skill, item.name, home, item, state, stats, client);
}
/** One full pass; never throws — outcomes land in the stats. */
async syncOnce() {
if (this.running)
@ -366,6 +528,11 @@ export class SkillSync {
if (exists && delivery !== undefined) {
// Delivered before: local integrity is judged before any download.
if (!(await this.deliveredIntact(home, delivery))) {
const auto = await this.autoResolveLocalDrift(item, home, state, stats, client, parked ? this.holdingRoot() : root);
if (auto !== 'unresolved') {
stateDirty = true;
continue;
}
this.conflict(stats, item.name, 'locally_modified');
continue;
}
@ -380,6 +547,14 @@ export class SkillSync {
// Intact but the cloud moved on: fall through and install the update.
}
if (exists && delivery === undefined) {
// Same name on both sides with no delivery proof. Identical bytes are
// adopted; otherwise the newer side wins by timestamp. Only an equal
// or missing timestamp becomes a human conflict.
const auto = await this.autoResolveCollision(item, home, parked ? this.holdingRoot() : root, state, stats, client);
if (auto !== 'unresolved') {
stateDirty = true;
continue;
}
this.conflict(stats, item.name, 'name_collision');
continue;
}
@ -407,6 +582,10 @@ export class SkillSync {
(exists ? stats.updated : stats.downloaded).push(item.name);
}
// ---- UP: local originals -> cloud center ---------------------------
// The DOWN pass already had the chance to resolve a same-name folder;
// don't repeat the same skill with a second reason (the panel used to show
// one card per reason for the same name).
const knownConflicts = new Set(stats.conflicts.map((entry) => entry.name));
const folders = await readdir(root, { withFileTypes: true }).catch(() => []);
const seenFolders = new Set();
for (const entry of folders) {
@ -420,12 +599,37 @@ export class SkillSync {
if (skill === undefined)
continue;
if (typeof skill === 'string') {
this.conflict(stats, entry.name, skill);
if (!knownConflicts.has(entry.name))
this.conflict(stats, entry.name, skill);
continue;
}
const record = state.uploaded[skill.name];
const cloud = cloudByName.get(skill.name);
if (cloud !== undefined && record === undefined) {
if (knownConflicts.has(skill.name))
continue;
if (cloud.manifest_sha256 !== undefined && cloud.manifest_sha256 === skill.manifest) {
// Same bytes already in the center: adopt the cloud identity without
// an upload, so the next pass compares revisions instead of names.
this.markUploaded(state, skill.name, {
folder: entry.name,
revision: cloud.revision ?? 1,
manifest: skill.manifest,
syncedAt: new Date().toISOString(),
});
stateDirty = true;
stats.skipped += 1;
continue;
}
const cloudAt = this.cloudUpdatedAt(cloud);
const localAt = newestMtime(skill.files);
if (cloudAt !== undefined && localAt > 0 && localAt > cloudAt) {
const auto = await this.autoUploadLocal(skill, entry.name, dir, cloud, state, stats, client);
if (auto !== 'unresolved') {
stateDirty = true;
continue;
}
}
this.conflict(stats, skill.name, 'name_collision');
continue;
}
@ -464,7 +668,33 @@ export class SkillSync {
}
else {
if (cloud.revision !== undefined && cloud.revision !== record.revision) {
this.conflict(stats, skill.name, 'cloud_newer');
// The center moved on since the last upload. Identical bytes just
// re-pin the revision; otherwise the newer side wins and only an
// equal/missing timestamp stays a conflict.
if (cloud.manifest_sha256 !== undefined && cloud.manifest_sha256 === skill.manifest) {
this.markUploaded(state, skill.name, {
folder: entry.name,
revision: cloud.revision,
manifest: skill.manifest,
syncedAt: new Date().toISOString(),
});
stateDirty = true;
stats.skipped += 1;
continue;
}
const cloudAt = this.cloudUpdatedAt(cloud);
const localAt = newestMtime(skill.files);
if (cloudAt !== undefined && localAt > 0 && cloudAt !== localAt) {
const auto = cloudAt > localAt
? await this.autoTakeCloud(cloud, dir, root, state, stats, client)
: await this.autoUploadLocal(skill, entry.name, dir, cloud, state, stats, client);
if (auto !== 'unresolved') {
stateDirty = true;
continue;
}
}
if (!knownConflicts.has(skill.name))
this.conflict(stats, skill.name, 'cloud_newer');
continue;
}
const updated = await client.updateSkill(skill.name, {
@ -641,7 +871,7 @@ export class SkillSync {
},
canKeepLocal: location !== 'none',
canTakeCloud: cloudItem !== undefined,
note: '“保留本地”把本地版本上传成新的云端版本;“采用云端”先备份本地再覆盖;“手动合并”只返回两侧信息,不改文件。',
note: '同步会先按内容与更新时间自动采用较新的一边(覆盖前备份本地);只有时间相同/缺失、或目录结构不支持时才需要你逐项选择。',
});
}
return out;

View File

@ -1,6 +1,6 @@
{
"name": "dsh-brain",
"version": "0.9.8",
"version": "0.9.9",
"description": "Cloud memory for DSH: report one activity turn per conversation round and expose memory_search / memory_read / memory_add tools against a LongMemory cloud endpoint.",
"type": "module",
"license": "MIT",

View File

@ -118,6 +118,10 @@ export interface SkillSummary {
files?: number
bytes?: number
script_changed?: boolean
/** Center creation time (ISO string; older servers may send epoch seconds). */
created_at?: string | number
/** Center last-change time — the timestamp the sync engine compares against local mtimes. */
updated_at?: string | number
[key: string]: unknown
}

View File

@ -30,7 +30,7 @@ export const name = 'dsh-brain'
export const inject = ['webServer']
/** Version reported by the status card. */
const VERSION = '0.9.8'
const VERSION = '0.9.9'
/** How often the skill directory is reconciled with the cloud center. */
const SKILL_SYNC_INTERVAL_MS = 15 * 60_000

View File

@ -15,12 +15,14 @@
* revisions, guarded by the center's `expected_revision` check.
*
* Safety rules (deliberate, in order):
* 1. A cloud-delivered skill is never re-uploaded. If its local files no
* longer match the delivery manifest, the skill is flagged as a
* conflict and left completely alone.
* 1. A cloud-delivered skill is never re-uploaded unless its local copy is
* newer than the center's `updated_at`; before any cloud overwrite the
* local folder is copied to `$DSH_HOME/.dsh-brain-backups/sync/`.
* 2. A local deletion never deletes the cloud copy.
* 3. A name that already exists on the other side is never hijacked;
* it is reported as a conflict for a human to resolve.
* 3. A same-name skill is never hijacked silently: byte-identical copies are
* adopted in place, otherwise the newer side (local file mtime vs center
* `updated_at`) wins; only equal or missing timestamps are reported as a
* conflict for a human to resolve.
* 4. Bundles whose scripts changed on the cloud side are not installed
* until the change is acknowledged in the dashboard, mirroring the
* center's own review flag.
@ -65,6 +67,23 @@ export function linkedSkillManifest(files: readonly { path: string; sha256: stri
return sha256Hex(Buffer.from(`cloud-memory-skill-v1\n${lines.join('\n')}\n`, 'utf8'))
}
/** Epoch milliseconds from a center timestamp (ISO string or epoch seconds/ms). */
function timestampMs(value: unknown): number | undefined {
if (typeof value === 'number' && Number.isFinite(value)) return value < 1e12 ? value * 1000 : value
if (typeof value === 'string' && value !== '') {
const parsed = Date.parse(value)
return Number.isFinite(parsed) ? parsed : undefined
}
return undefined
}
/** Newest local file mtime in one skill folder (0 when the folder has no files). */
function newestMtime(files: readonly { mtimeMs: number }[]): number {
let newest = 0
for (const file of files) if (file.mtimeMs > newest) newest = file.mtimeMs
return newest
}
/** True when the cloud center would accept this relative file path. */
export function isCloudSkillPath(rel: string): boolean {
if (rel === '' || rel.length > 200 || rel.startsWith('/') || rel.includes('\\') || rel.includes('//')) return false
@ -150,6 +169,8 @@ interface SyncState {
interface LocalFile {
rel: string
buffer: Buffer
/** Last-modified time; the automatic newer-side winner is chosen from these. */
mtimeMs: number
}
/** Dependencies of one sync engine instance. */
@ -173,6 +194,14 @@ interface DeliveryManifest {
files?: { path: string; sha256: string }[]
}
/**
* Result of an automatic two-sided resolution:
* - resolved: the newer side won and the state was updated;
* - conflict: a specific conflict was recorded (e.g. script review);
* - unresolved: timestamps missing/equal — the caller records a conflict.
*/
type AutoResolution = 'resolved' | 'conflict' | 'unresolved'
export class SkillSync {
private running = false
private current: SkillSyncStats = {
@ -262,7 +291,10 @@ export class SkillSync {
if (entry.isDirectory()) {
await walk(rel)
} else if (entry.isFile()) {
out.push({ rel, buffer: await readFile(join(dir, rel)) })
const absolute = join(dir, rel)
const buffer = await readFile(absolute)
const info = await stat(absolute)
out.push({ rel, buffer, mtimeMs: info.mtimeMs })
}
}
}
@ -327,6 +359,175 @@ export class SkillSync {
return undefined
}
/** Center's last-change time for one listed skill (ISO string or epoch). */
private cloudUpdatedAt(item: SkillSummary): number | undefined {
return timestampMs(item.updated_at) ?? timestampMs(item.created_at)
}
/** Manifest over every local file, including files the center would reject. */
private localManifest(files: readonly LocalFile[]): string {
return linkedSkillManifest(files.map((file) => ({ path: file.rel, sha256: sha256Hex(file.buffer) })))
}
/** Copy a local skill aside before an automatic cloud overwrite. */
private async backupLocal(dir: string, name: string): Promise<string> {
const stamp = new Date().toISOString().replace(/[:.]/g, '-')
const backup = join(dshHome(), '.dsh-brain-backups', 'sync', name, stamp)
await mkdir(join(backup, '..'), { recursive: true })
await cp(dir, backup, { recursive: true, filter: (path) => !path.split(/[\\/]/).includes('.git') })
return backup
}
/**
* Local and cloud already carry the same bytes: record the delivery marker
* without a transfer, so the next pass treats the folder as cloud-origin and
* the user is not asked to pick between two identical copies.
*/
private async adoptIdenticalDelivery(home: string, item: SkillSummary, files: readonly LocalFile[]): Promise<void> {
const delivery: DeliveryManifest & { synced_at: string } = {
name: item.name,
...(item.revision === undefined ? {} : { revision: item.revision }),
...(item.manifest_sha256 === undefined ? {} : { manifest_sha256: item.manifest_sha256 }),
files: files.map((file) => ({ path: file.rel, sha256: sha256Hex(file.buffer) })),
synced_at: new Date().toISOString(),
}
await writeFile(join(home, '.manifest.json'), JSON.stringify(delivery, null, 2))
}
/** Fetch, verify and install the cloud copy, backing the local one up first. */
private async autoTakeCloud(
item: SkillSummary,
home: string,
installRoot: string,
state: SyncState,
stats: SkillSyncStats,
client: CloudClient,
): Promise<AutoResolution> {
if (item.script_changed === true) {
this.conflict(stats, item.name, 'script_review_required')
return 'conflict'
}
const bundle = await client.skillBundle(item.name)
if (!bundle.ok) {
this.conflict(stats, item.name, `bundle_failed: ${describeError(bundle.error)}`)
return 'conflict'
}
if (linkedSkillManifest(bundle.data.files) !== bundle.data.manifest_sha256) {
this.conflict(stats, item.name, 'manifest_mismatch')
return 'conflict'
}
if (bundle.data.script_changed === true) {
this.conflict(stats, item.name, 'script_review_required')
return 'conflict'
}
await this.backupLocal(home, item.name)
await this.install(item, bundle.data, installRoot)
this.markDelivered(state, item.name, bundle.data.manifest_sha256)
delete state.removed[item.name]
stats.updated.push(item.name)
return 'resolved'
}
/** Upload the locally-newer copy as the next cloud revision. */
private async autoUploadLocal(
skill: { name: string; description: string; files: LocalFile[]; manifest: string; hasScripts: boolean },
folder: string,
dir: string,
cloud: SkillSummary,
state: SyncState,
stats: SkillSyncStats,
client: CloudClient,
): Promise<AutoResolution> {
const updated = await client.updateSkill(skill.name, {
description: skill.description,
files: this.toUploadFiles(skill.files),
expected_revision: cloud.revision ?? 0,
operation_id: `dsh-skill-${randomUUID()}`,
})
if (!updated.ok) {
const reason = updated.error.code === 'revision_conflict' ? 'cloud_newer' : `upload_failed: ${describeError(updated.error)}`
this.conflict(stats, skill.name, reason)
return 'conflict'
}
const revision = updated.data.skill?.revision ?? updated.data.revision ?? (cloud.revision ?? 0) + 1
await rm(join(dir, '.manifest.json'), { force: true })
this.markUploaded(state, skill.name, {
folder,
revision,
manifest: skill.manifest,
syncedAt: new Date().toISOString(),
})
delete state.removed[skill.name]
stats.updated.push(skill.name)
return 'resolved'
}
/**
* Same-name skill on both sides without a delivery record. Identical bytes
* are adopted silently; different bytes go to whichever side is newer;
* equal/missing timestamps stay unresolved for a human decision.
*/
private async autoResolveCollision(
item: SkillSummary,
home: string,
installRoot: string,
state: SyncState,
stats: SkillSyncStats,
client: CloudClient,
): Promise<AutoResolution> {
const localFiles = await this.readSkillFiles(home).catch(() => [])
if (!localFiles.some((file) => file.rel === 'SKILL.md')) return 'unresolved'
if (item.manifest_sha256 !== undefined && this.localManifest(localFiles) === item.manifest_sha256) {
await this.adoptIdenticalDelivery(home, item, localFiles)
this.markDelivered(state, item.name, item.manifest_sha256)
stats.skipped += 1
return 'resolved'
}
const cloudAt = this.cloudUpdatedAt(item)
const localAt = newestMtime(localFiles)
if (cloudAt === undefined || localAt === 0 || cloudAt === localAt) return 'unresolved'
if (cloudAt > localAt) return this.autoTakeCloud(item, home, installRoot, state, stats, client)
const skill = await this.readLocalSkill(home, item.name)
if (skill === undefined) return 'unresolved'
if (typeof skill === 'string') {
this.conflict(stats, item.name, skill)
return 'conflict'
}
return this.autoUploadLocal(skill, item.name, home, item, state, stats, client)
}
/**
* Cloud-delivered skill edited locally. Identical bytes refresh the marker;
* otherwise the newer side wins (cloud overwrite is backed up first).
*/
private async autoResolveLocalDrift(
item: SkillSummary,
home: string,
state: SyncState,
stats: SkillSyncStats,
client: CloudClient,
installRoot: string,
): Promise<AutoResolution> {
const localFiles = await this.readSkillFiles(home).catch(() => [])
if (item.manifest_sha256 !== undefined && localFiles.length > 0 && this.localManifest(localFiles) === item.manifest_sha256) {
await this.adoptIdenticalDelivery(home, item, localFiles)
this.markDelivered(state, item.name, item.manifest_sha256)
stats.skipped += 1
return 'resolved'
}
const cloudAt = this.cloudUpdatedAt(item)
const localAt = newestMtime(localFiles)
if (cloudAt === undefined || localAt === 0 || cloudAt === localAt) return 'unresolved'
if (cloudAt > localAt) return this.autoTakeCloud(item, home, installRoot, state, stats, client)
const skill = await this.readLocalSkill(home, item.name)
if (skill === undefined) return 'unresolved'
if (typeof skill === 'string') {
this.conflict(stats, item.name, skill)
return 'conflict'
}
return this.autoUploadLocal(skill, item.name, home, item, state, stats, client)
}
/** One full pass; never throws — outcomes land in the stats. */
async syncOnce(): Promise<SkillSyncStats> {
if (this.running) return this.current
@ -420,6 +621,11 @@ export class SkillSync {
if (exists && delivery !== undefined) {
// Delivered before: local integrity is judged before any download.
if (!(await this.deliveredIntact(home, delivery))) {
const auto = await this.autoResolveLocalDrift(item, home, state, stats, client, parked ? this.holdingRoot() : root)
if (auto !== 'unresolved') {
stateDirty = true
continue
}
this.conflict(stats, item.name, 'locally_modified')
continue
}
@ -434,6 +640,14 @@ export class SkillSync {
// Intact but the cloud moved on: fall through and install the update.
}
if (exists && delivery === undefined) {
// Same name on both sides with no delivery proof. Identical bytes are
// adopted; otherwise the newer side wins by timestamp. Only an equal
// or missing timestamp becomes a human conflict.
const auto = await this.autoResolveCollision(item, home, parked ? this.holdingRoot() : root, state, stats, client)
if (auto !== 'unresolved') {
stateDirty = true
continue
}
this.conflict(stats, item.name, 'name_collision')
continue
}
@ -462,6 +676,10 @@ export class SkillSync {
}
// ---- UP: local originals -> cloud center ---------------------------
// The DOWN pass already had the chance to resolve a same-name folder;
// don't repeat the same skill with a second reason (the panel used to show
// one card per reason for the same name).
const knownConflicts = new Set(stats.conflicts.map((entry) => entry.name))
const folders = await readdir(root, { withFileTypes: true }).catch(() => [])
const seenFolders = new Set<string>()
for (const entry of folders) {
@ -472,12 +690,35 @@ export class SkillSync {
const skill = await this.readLocalSkill(dir, entry.name)
if (skill === undefined) continue
if (typeof skill === 'string') {
this.conflict(stats, entry.name, skill)
if (!knownConflicts.has(entry.name)) this.conflict(stats, entry.name, skill)
continue
}
const record = state.uploaded[skill.name]
const cloud = cloudByName.get(skill.name)
if (cloud !== undefined && record === undefined) {
if (knownConflicts.has(skill.name)) continue
if (cloud.manifest_sha256 !== undefined && cloud.manifest_sha256 === skill.manifest) {
// Same bytes already in the center: adopt the cloud identity without
// an upload, so the next pass compares revisions instead of names.
this.markUploaded(state, skill.name, {
folder: entry.name,
revision: cloud.revision ?? 1,
manifest: skill.manifest,
syncedAt: new Date().toISOString(),
})
stateDirty = true
stats.skipped += 1
continue
}
const cloudAt = this.cloudUpdatedAt(cloud)
const localAt = newestMtime(skill.files)
if (cloudAt !== undefined && localAt > 0 && localAt > cloudAt) {
const auto = await this.autoUploadLocal(skill, entry.name, dir, cloud, state, stats, client)
if (auto !== 'unresolved') {
stateDirty = true
continue
}
}
this.conflict(stats, skill.name, 'name_collision')
continue
}
@ -512,7 +753,32 @@ export class SkillSync {
stats.uploaded.push(skill.name)
} else {
if (cloud.revision !== undefined && cloud.revision !== record.revision) {
this.conflict(stats, skill.name, 'cloud_newer')
// The center moved on since the last upload. Identical bytes just
// re-pin the revision; otherwise the newer side wins and only an
// equal/missing timestamp stays a conflict.
if (cloud.manifest_sha256 !== undefined && cloud.manifest_sha256 === skill.manifest) {
this.markUploaded(state, skill.name, {
folder: entry.name,
revision: cloud.revision,
manifest: skill.manifest,
syncedAt: new Date().toISOString(),
})
stateDirty = true
stats.skipped += 1
continue
}
const cloudAt = this.cloudUpdatedAt(cloud)
const localAt = newestMtime(skill.files)
if (cloudAt !== undefined && localAt > 0 && cloudAt !== localAt) {
const auto = cloudAt > localAt
? await this.autoTakeCloud(cloud, dir, root, state, stats, client)
: await this.autoUploadLocal(skill, entry.name, dir, cloud, state, stats, client)
if (auto !== 'unresolved') {
stateDirty = true
continue
}
}
if (!knownConflicts.has(skill.name)) this.conflict(stats, skill.name, 'cloud_newer')
continue
}
const updated = await client.updateSkill(skill.name, {
@ -683,7 +949,7 @@ export class SkillSync {
},
canKeepLocal: location !== 'none',
canTakeCloud: cloudItem !== undefined,
note: '“保留本地”把本地版本上传成新的云端版本;“采用云端”先备份本地再覆盖;“手动合并”只返回两侧信息,不改文件。',
note: '同步会先按内容与更新时间自动采用较新的一边(覆盖前备份本地);只有时间相同/缺失、或目录结构不支持时才需要你逐项选择。',
})
}
return out

View File

@ -4,7 +4,7 @@
// bundles, linked manifest) — no DSH host, no real service, no real token.
import http from 'node:http'
import { createHash } from 'node:crypto'
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, utimesSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
@ -27,16 +27,24 @@ function storeFiles(files) {
return { path: file.path, sha256: sha(buffer), size: buffer.length, encoding: file.content !== undefined ? 'utf8' : 'base64', data: buffer.toString('base64') }
})
}
const DAY = 24 * 60 * 60 * 1000
const CLOUD_OLD = Date.parse('2026-01-01T00:00:00.000Z')
const CLOUD_EQUAL = Date.parse('2026-06-01T00:00:00.000Z')
const iso = (value) => new Date(value).toISOString()
function summaryOf(skill) {
return {
name: skill.name, description: skill.description, execution_mode: skill.execution_mode,
enabled: true, revision: skill.revision, manifest_sha256: linked(skill.files), files: skill.files.length,
script_changed: skill.script_changed,
created_at: iso(skill.created_at ?? CLOUD_OLD), updated_at: iso(skill.updated_at ?? CLOUD_OLD),
}
}
function seed(name, files, extra = {}) {
const stored = storeFiles(files)
center.set(name, { name, description: `${name} desc`, execution_mode: 'prompt-only', revision: 1, files: stored, script_changed: false, ...extra })
center.set(name, {
name, description: `${name} desc`, execution_mode: 'prompt-only', revision: 1, files: stored,
script_changed: false, created_at: CLOUD_OLD, updated_at: CLOUD_OLD, ...extra,
})
}
seed('cloud-one', [
{ path: 'SKILL.md', content: '# cloud-one\n\n云端技能一。' },
@ -73,7 +81,11 @@ const server = http.createServer((req, res) => {
const body = await readBody()
if (body.expected_revision !== 0) return send(400, { error: 'invalid_input', message: '必须提供 expected_revision' })
if (center.has(body.name)) return send(409, { error: 'skill_exists', message: '同名技能已存在' })
const skill = { name: body.name, description: body.description, execution_mode: body.execution_mode ?? 'prompt-only', revision: 1, files: storeFiles(body.files ?? []), script_changed: false }
const skill = {
name: body.name, description: body.description, execution_mode: body.execution_mode ?? 'prompt-only',
revision: 1, files: storeFiles(body.files ?? []), script_changed: false,
created_at: Date.now(), updated_at: Date.now(),
}
center.set(skill.name, skill)
return send(201, { skill: summaryOf(skill), revision: 1, manifest_sha256: linked(skill.files) })
}
@ -86,6 +98,7 @@ const server = http.createServer((req, res) => {
if (body.files) skill.files = storeFiles(body.files)
if (body.description !== undefined) skill.description = body.description
skill.revision += 1
skill.updated_at = Date.now()
return send(200, { skill: summaryOf(skill), revision: skill.revision, manifest_sha256: linked(skill.files) })
}
return send(404, { error: 'unknown_route', path })
@ -106,11 +119,12 @@ const engine = new SkillSync({
})
const root = join(process.env.DSH_HOME, 'skills')
const skillDir = (name) => join(root, name)
const writeLocal = (name, files) => {
const writeLocal = (name, files, mtime = Date.now()) => {
for (const [rel, content] of Object.entries(files)) {
const target = join(skillDir(name), ...rel.split('/'))
mkdirSync(join(target, '..'), { recursive: true })
writeFileSync(target, content)
utimesSync(target, new Date(mtime), new Date(mtime))
}
}
@ -145,23 +159,71 @@ writeLocal('local-one', { 'SKILL.md': '---\nname: local-one\ndescription: 本地
stats = await engine.syncOnce()
check('edited local skill updates the center', stats.updated.includes('local-one') && center.get('local-one')?.revision === 2)
// 4. A locally modified cloud skill is flagged, never overwritten or uploaded.
writeLocal('cloud-one', { 'SKILL.md': '# cloud-one\n\n我改了云端技能。' })
// 4. A local edit newer than the cloud is uploaded automatically.
writeLocal('cloud-one', { 'SKILL.md': '# cloud-one\n\n我改了云端技能。' }, Date.now())
stats = await engine.syncOnce()
check('local edit of a cloud skill becomes a conflict',
stats.conflicts.some((c) => c.name === 'cloud-one' && c.reason === 'locally_modified'), JSON.stringify(stats.conflicts))
check('the local edit is left untouched',
check('local edit newer than cloud auto-uploads',
stats.updated.includes('cloud-one') && center.get('cloud-one')?.revision === 2, JSON.stringify(stats.conflicts))
check('the newer local edit stays on disk',
readFileSync(join(skillDir('cloud-one'), 'SKILL.md'), 'utf8').includes('我改了云端技能'))
check('the center copy is untouched by the conflict',
center.get('cloud-one')?.revision === 1)
check('newer local edit is not a conflict', !stats.conflicts.some((c) => c.name === 'cloud-one'))
// 5. A name collision on both sides is flagged, both copies untouched.
seed('clash', [{ path: 'SKILL.md', content: '# clash cloud' }])
writeLocal('clash', { 'SKILL.md': '# clash local\n' })
// 4b. Cloud newer than a stale local copy: auto-download with a local backup.
{
const cloud = center.get('cloud-one')
cloud.revision += 1
cloud.files = storeFiles([{ path: 'SKILL.md', content: '# cloud-one v3 (cloud newer)' }])
cloud.updated_at = Date.now() + DAY
writeLocal('cloud-one', { 'SKILL.md': '# cloud-one local stale\n' }, Date.now() - DAY)
stats = await engine.syncOnce()
check('cloud newer auto-downloads over a stale local copy',
readFileSync(join(skillDir('cloud-one'), 'SKILL.md'), 'utf8').includes('cloud newer'))
const backupRoot = join(process.env.DSH_HOME, '.dsh-brain-backups', 'sync', 'cloud-one')
check('auto overwrite backs the local copy up', existsSync(backupRoot))
check('cloud newer overwrite is not a conflict', !stats.conflicts.some((c) => c.name === 'cloud-one'))
}
// 5a. Identical bytes on both sides: adopt silently, no transfer, no conflict.
seed('clash-same', [{ path: 'SKILL.md', content: '# clash same' }], { updated_at: CLOUD_OLD })
writeLocal('clash-same', { 'SKILL.md': '# clash same' }, CLOUD_OLD - DAY)
stats = await engine.syncOnce()
check('name collision is flagged', stats.conflicts.some((c) => c.name === 'clash' && c.reason === 'name_collision'))
check('collision leaves local files alone', readFileSync(join(skillDir('clash'), 'SKILL.md'), 'utf8').includes('clash local'))
check('collision leaves the center alone', center.get('clash')?.revision === 1)
check('identical collision auto-adopts without a conflict',
!stats.conflicts.some((c) => c.name === 'clash-same') && existsSync(join(skillDir('clash-same'), '.manifest.json')))
check('identical collision uploads nothing', center.get('clash-same')?.revision === 1)
// 5b. Local newer wins the collision.
seed('clash-local', [{ path: 'SKILL.md', content: '# clash cloud' }], { updated_at: CLOUD_OLD })
writeLocal('clash-local', { 'SKILL.md': '# clash local newer' }, CLOUD_OLD + DAY)
stats = await engine.syncOnce()
check('local newer collision auto-uploads',
center.get('clash-local')?.revision === 2 && stats.updated.includes('clash-local'))
check('local newer collision keeps the local file',
readFileSync(join(skillDir('clash-local'), 'SKILL.md'), 'utf8').includes('local newer'))
// 5c. Cloud newer wins the collision.
seed('clash-cloud', [{ path: 'SKILL.md', content: '# clash cloud newer' }], { updated_at: Date.now() + DAY })
writeLocal('clash-cloud', { 'SKILL.md': '# clash local stale' }, Date.now() - DAY)
stats = await engine.syncOnce()
check('cloud newer collision auto-downloads',
readFileSync(join(skillDir('clash-cloud'), 'SKILL.md'), 'utf8').includes('cloud newer'))
check('cloud newer collision is not a conflict', !stats.conflicts.some((c) => c.name === 'clash-cloud'))
// 5d. Same timestamp on both sides: still a human decision.
seed('clash-equal', [{ path: 'SKILL.md', content: '# clash cloud same-time' }], { updated_at: CLOUD_EQUAL })
writeLocal('clash-equal', { 'SKILL.md': '# clash local same-time' }, CLOUD_EQUAL)
stats = await engine.syncOnce()
check('equal timestamps keep the name collision conflict',
stats.conflicts.some((c) => c.name === 'clash-equal' && c.reason === 'name_collision'))
check('equal-timestamp collision leaves both sides untouched',
readFileSync(join(skillDir('clash-equal'), 'SKILL.md'), 'utf8').includes('same-time') && center.get('clash-equal')?.revision === 1)
// 5e. A same-name conflict is reported once, not once per reason.
seed('bad-clash', [{ path: 'SKILL.md', content: '# bad cloud' }], { updated_at: CLOUD_EQUAL })
writeLocal('bad-clash', { 'SKILL.md': '# bad local', 'README.md': 'root file' }, CLOUD_EQUAL)
stats = await engine.syncOnce()
const badClashConflicts = stats.conflicts.filter((c) => c.name === 'bad-clash')
check('one card per same-name conflict',
badClashConflicts.length === 1 && badClashConflicts[0]?.reason === 'name_collision', JSON.stringify(badClashConflicts))
// 6. Script-changed cloud bundles wait for review.
check('script-changed bundle is not installed',