QQ-dsh/vendor/dsh-brain/lib/skill-sync.js

760 lines
34 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

/**
* Bidirectional skill sync between the cloud skill center and the local
* DSH skills directory (`$DSH_HOME/skills` by default).
*
* The cloud center is the hub, the local directory is a working copy, and
* the DSH skills manager keeps owning local management — this module only
* moves files, in both directions:
*
* - DOWN: cloud skills are installed exactly like the platform's own
* `skills-sync` tool does it — bundle hash and per-file checksums are
* verified before anything lands, writes are atomic per file, and a
* per-skill `.manifest.json` records what the cloud delivered.
* - UP: skills that originated locally (installed by the skills manager,
* imported, or written by hand) are published to the center as new
* 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.
* 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.
* 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.
* 5. Only the center's file layout is uploadable (SKILL.md at the root,
* everything else under references/, scripts/ or assets/, with the
* center's extension allowlist). Anything else is reported, never
* silently trimmed.
*/
import { createHash, randomUUID } from 'node:crypto';
import { mkdir, cp, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
import { dirname, join, resolve } from 'node:path';
import { describeError } from "./api.js";
import { dshHome, migrateLegacyFile } from "./store.js";
/** Cloud skill names: lowercase kebab, at most 64 characters. */
export const CLOUD_SKILL_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
/** Layout contract of the cloud skill center (mirrors its store rules). */
const TEXT_EXT = new Set(['.md', '.txt', '.json', '.yaml', '.yml', '.py', '.sh', '.ps1', '.mjs', '.js', '.ts', '.tsx', '.css', '.html', '.csv']);
const BINARY_EXT = new Set(['.docx', '.xlsx', '.pptx', '.pdf', '.png', '.jpg', '.jpeg', '.gif', '.svg', '.zip']);
const SCRIPT_EXT = new Set(['.py', '.sh', '.ps1', '.mjs']);
const SKILL_DIRS = new Set(['references', 'scripts', 'assets']);
const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
const MAX_FILES = 100;
const MAX_FILE_BYTES = 512 * 1024;
const MAX_SKILL_BYTES = 2 * 1024 * 1024;
const MAX_DEPTH = 3;
/** SHA-256 of a buffer or UTF-8 string, hex-encoded. */
export function sha256Hex(data) {
return createHash('sha256').update(data).digest('hex');
}
/**
* The center's linked bundle manifest: one `path\0sha256` line per file,
* sorted, under a version header. Byte-identical to the platform's own
* computation, so locally computed manifests compare directly.
*/
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'));
}
/** 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('//'))
return false;
const segments = rel.split('/');
if (segments.length > MAX_DEPTH)
return false;
for (const segment of segments) {
if (!SEGMENT.test(segment) || segment === '.' || segment === '..')
return false;
}
const dot = rel.lastIndexOf('.');
const ext = dot === -1 ? '' : rel.slice(dot).toLowerCase();
if (!TEXT_EXT.has(ext) && !BINARY_EXT.has(ext))
return false;
const first = segments[0];
if (segments.length === 1)
return rel === 'SKILL.md';
if (first === undefined || !SKILL_DIRS.has(first))
return false;
if (first === 'scripts' && !SCRIPT_EXT.has(ext))
return false;
return true;
}
/** Minimal frontmatter reader for `name` / `description` (plain scalars). */
export function parseSkillFrontmatter(markdown) {
if (!markdown.startsWith('---'))
return {};
const end = markdown.indexOf('\n---', 3);
if (end === -1)
return {};
const out = {};
for (const line of markdown.slice(3, end).split('\n')) {
const match = /^\s*(name|description)\s*:\s*(.+?)\s*$/.exec(line);
if (match === null)
continue;
const value = (match[2] ?? '').replace(/^["']|["']$/g, '');
if (match[1] === 'name' && value !== '')
out.name = value;
if (match[1] === 'description' && value !== '')
out.description = value;
}
return out;
}
/** Sidecar state: `$DSH_HOME/dsh-brain-skills.json` (legacy `cloud-memory-skills.json` migrates on first use). */
/** Absolute sidecar path, carrying the pre-rename file over on first use. */
export function skillsStatePath() {
const target = join(dshHome(), 'dsh-brain-skills.json');
migrateLegacyFile(target, join(dshHome(), 'cloud-memory-skills.json'));
return target;
}
async function isDirectory(path) {
return stat(path).then((value) => value.isDirectory()).catch(() => false);
}
export class SkillSync {
deps;
running = false;
current = {
running: false, downloaded: [], uploaded: [], updated: [], conflicts: [], skipped: 0,
};
constructor(deps) {
this.deps = deps;
}
/** Stats of the latest pass, for the status endpoint. */
stats() {
return this.current;
}
/** The local skills root this engine syncs. */
skillsRoot() {
const dir = this.deps.settings().skillsDir;
return dir !== '' ? resolve(dir) : join(dshHome(), 'skills');
}
/** The parking area where disabled skills wait, outside the root. */
holdingRoot() {
return this.deps.holdingDir?.() ?? join(dshHome(), 'skills-disabled');
}
statePath() {
return skillsStatePath();
}
/**
* Record a cloud-delivered skill. Upload provenance is cleared in the same
* transition: a skill has exactly one source of truth. Keeping both marks
* makes the DOWN pass skip the name (uploaded) while the UP pass skips its
* local folder (delivery manifest), so neither side ever syncs again.
*/
markDelivered(state, name, manifest) {
state.delivered[name] = { manifest };
delete state.uploaded[name];
}
/**
* Record a locally-originated upload. The delivery marker is cleared in the
* same transition, so the next local edit is uploaded again instead of being
* skipped as cloud-origin.
*/
markUploaded(state, name, record) {
state.uploaded[name] = record;
delete state.delivered[name];
}
async loadState() {
const clean = { version: 1, uploaded: {}, delivered: {}, removed: {} };
try {
const parsed = JSON.parse(await readFile(this.statePath(), 'utf8'));
if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
const raw = parsed;
const map = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
return {
version: 1,
uploaded: map(raw.uploaded),
delivered: map(raw.delivered),
removed: map(raw.removed),
};
}
}
catch {
// Missing or corrupt sidecar: start clean; the cloud is the truth.
}
return clean;
}
async saveState(state) {
const path = this.statePath();
await mkdir(dirname(path), { recursive: true });
const temporary = `${path}.tmp-${process.pid}`;
await writeFile(temporary, JSON.stringify(state, null, 2));
await rename(temporary, path);
}
/** Read every syncable file of one skill directory (unsorted walk). */
async readSkillFiles(dir) {
const out = [];
const walk = async (sub) => {
const entries = await readdir(join(dir, sub), { withFileTypes: true });
for (const entry of entries) {
const rel = sub === '' ? entry.name : `${sub}/${entry.name}`;
if (entry.name.startsWith('.'))
continue;
if (entry.isDirectory()) {
await walk(rel);
}
else if (entry.isFile()) {
out.push({ rel, buffer: await readFile(join(dir, rel)) });
}
}
};
await walk('');
return out.sort((a, b) => (a.rel < b.rel ? -1 : 1));
}
/** True when a cloud-delivered directory still matches its manifest. */
async deliveredIntact(dir, delivery) {
const recorded = delivery.files ?? [];
let files;
try {
files = await this.readSkillFiles(dir);
}
catch {
return false;
}
const current = files.filter((file) => file.rel !== '.manifest.json');
if (current.length !== recorded.length)
return false;
const byPath = new Map(current.map((file) => [file.rel, sha256Hex(file.buffer)]));
return recorded.every((file) => byPath.get(file.path) === file.sha256);
}
/** Install or update one cloud skill into the local directory. */
async install(item, bundle, root) {
const dir = join(root, item.name);
const previous = await this.readDelivery(dir);
const keep = new Set(bundle.files.map((file) => file.path));
await mkdir(dir, { recursive: true });
const written = [];
for (const file of bundle.files) {
const buffer = Buffer.from(file.data, 'base64');
if (sha256Hex(buffer) !== file.sha256)
throw new Error(`checksum mismatch for ${file.path}`);
const target = join(dir, ...file.path.split('/'));
await mkdir(dirname(target), { recursive: true });
const temporary = `${target}.tmp-${process.pid}`;
await writeFile(temporary, buffer);
await rename(temporary, target);
written.push({ path: file.path, sha256: file.sha256, size: buffer.length });
}
for (const file of previous?.files ?? []) {
if (!keep.has(file.path))
await rm(join(dir, ...file.path.split('/')), { force: true });
}
const delivery = {
name: item.name,
revision: bundle.revision,
manifest_sha256: bundle.manifest_sha256,
files: written,
synced_at: new Date().toISOString(),
};
await writeFile(join(dir, '.manifest.json'), JSON.stringify(delivery, null, 2));
}
async readDelivery(dir) {
try {
const parsed = JSON.parse(await readFile(join(dir, '.manifest.json'), 'utf8'));
if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
return parsed;
}
}
catch {
// Not a cloud-delivered skill.
}
return undefined;
}
/** One full pass; never throws — outcomes land in the stats. */
async syncOnce() {
if (this.running)
return this.current;
const settings = this.deps.settings();
if (!settings.enabled || !settings.skillsSyncEnabled)
return this.current;
this.running = true;
const stats = {
running: true, downloaded: [], uploaded: [], updated: [], conflicts: [], skipped: 0,
};
this.current = stats;
try {
await this.pass(stats);
stats.lastRunAt = new Date().toISOString();
}
catch (error) {
stats.lastError = error instanceof Error ? error.message : String(error);
this.deps.log(`skill sync failed: ${stats.lastError}`);
}
finally {
stats.running = false;
this.running = false;
this.current = stats;
}
return this.current;
}
/** Record a conflict once per pass, however many rules trip over it. */
conflict(stats, name, reason) {
if (!stats.conflicts.some((item) => item.name === name && item.reason === reason)) {
stats.conflicts.push({ name, reason });
}
}
async pass(stats) {
const client = this.deps.client();
const listing = await client.listSkills();
if (!listing.ok)
throw new Error(`skill listing failed: ${describeError(listing.error)}`);
const items = (listing.data.items ?? []).filter((item) => typeof item.name === 'string' && CLOUD_SKILL_NAME.test(item.name));
const cloudByName = new Map(items.map((item) => [item.name, item]));
const root = this.skillsRoot();
const state = await this.loadState();
let stateDirty = false;
// Self-heal sidecars written before source provenance became exclusive:
// a folder carrying a delivery manifest is cloud-delivered, even if an old
// `uploaded` record survived. Clearing the stale upload marker lets the
// DOWN pass judge local integrity (and surface a conflict) instead of
// skipping both directions forever.
for (const name of Object.keys(state.uploaded)) {
let delivery = undefined;
for (const area of [root, this.holdingRoot()]) {
const dir = join(area, name);
if (!(await isDirectory(dir)))
continue;
delivery = await this.readDelivery(dir);
if (delivery !== undefined)
break;
}
if (delivery !== undefined) {
this.markDelivered(state, name, delivery.manifest_sha256 ?? '');
stateDirty = true;
}
}
if (stateDirty)
await this.saveState(state);
// ---- DOWN: cloud center -> local directory -------------------------
for (const item of items) {
if (item.enabled === false) {
stats.skipped += 1;
continue;
}
// Locally-originated skills belong to the UP pass, even though the
// center lists them too once they are published.
if (state.uploaded[item.name] !== undefined) {
stats.skipped += 1;
continue;
}
const dir = join(root, item.name);
const parkedDir = join(this.holdingRoot(), item.name);
const inRoot = await isDirectory(dir);
const parked = !inRoot && (await isDirectory(parkedDir));
const home = parked ? parkedDir : dir;
const exists = inRoot || parked;
const removed = state.removed[item.name];
if (removed !== undefined && exists) {
// The user put it back by hand; the removal is over.
delete state.removed[item.name];
stateDirty = true;
}
else if (removed !== undefined && item.manifest_sha256 === removed.manifest) {
// Deleted locally at this exact cloud version: keep it deleted.
stats.skipped += 1;
continue;
}
else if (removed !== undefined) {
// The cloud published a different version since the deletion.
delete state.removed[item.name];
stateDirty = true;
}
const delivery = await this.readDelivery(home);
if (exists && delivery !== undefined) {
// Delivered before: local integrity is judged before any download.
if (!(await this.deliveredIntact(home, delivery))) {
this.conflict(stats, item.name, 'locally_modified');
continue;
}
if (delivery.manifest_sha256 === item.manifest_sha256) {
if (state.delivered[item.name]?.manifest !== item.manifest_sha256) {
this.markDelivered(state, item.name, item.manifest_sha256 ?? '');
stateDirty = true;
}
stats.skipped += 1;
continue;
}
// Intact but the cloud moved on: fall through and install the update.
}
if (exists && delivery === undefined) {
this.conflict(stats, item.name, 'name_collision');
continue;
}
if (item.script_changed === true) {
// The listing already carries the review flag; don't even fetch.
this.conflict(stats, item.name, 'script_review_required');
continue;
}
const bundle = await client.skillBundle(item.name);
if (!bundle.ok) {
this.conflict(stats, item.name, `bundle_failed: ${describeError(bundle.error)}`);
continue;
}
if (linkedSkillManifest(bundle.data.files) !== bundle.data.manifest_sha256) {
this.conflict(stats, item.name, 'manifest_mismatch');
continue;
}
if (bundle.data.script_changed === true) {
this.conflict(stats, item.name, 'script_review_required');
continue;
}
await this.install(item, bundle.data, parked ? this.holdingRoot() : root);
this.markDelivered(state, item.name, bundle.data.manifest_sha256);
stateDirty = true;
(exists ? stats.updated : stats.downloaded).push(item.name);
}
// ---- UP: local originals -> cloud center ---------------------------
const folders = await readdir(root, { withFileTypes: true }).catch(() => []);
const seenFolders = new Set();
for (const entry of folders) {
if (!entry.isDirectory() || entry.name.startsWith('.'))
continue;
seenFolders.add(entry.name);
const dir = join(root, entry.name);
if ((await this.readDelivery(dir)) !== undefined)
continue; // cloud-origin: down pass owns it
const skill = await this.readLocalSkill(dir, entry.name);
if (skill === undefined)
continue;
if (typeof skill === 'string') {
this.conflict(stats, entry.name, skill);
continue;
}
const record = state.uploaded[skill.name];
const cloud = cloudByName.get(skill.name);
if (cloud !== undefined && record === undefined) {
this.conflict(stats, skill.name, 'name_collision');
continue;
}
if (record !== undefined && record.manifest === skill.manifest) {
stats.skipped += 1;
continue;
}
const files = skill.files.map((file) => {
const ext = file.rel.slice(file.rel.lastIndexOf('.')).toLowerCase();
return TEXT_EXT.has(ext)
? { path: file.rel, content: file.buffer.toString('utf8') }
: { path: file.rel, base64: file.buffer.toString('base64') };
});
const operationId = `dsh-skill-${randomUUID()}`;
if (record === undefined || cloud === undefined) {
const created = await client.createSkill({
name: skill.name,
description: skill.description,
execution_mode: skill.hasScripts ? 'local-bundle' : 'prompt-only',
files,
expected_revision: 0,
operation_id: operationId,
});
if (!created.ok) {
this.conflict(stats, skill.name, `upload_failed: ${describeError(created.error)}`);
continue;
}
this.markUploaded(state, skill.name, {
folder: entry.name,
revision: created.data.skill?.revision ?? created.data.revision ?? 1,
manifest: skill.manifest,
syncedAt: new Date().toISOString(),
});
stateDirty = true;
stats.uploaded.push(skill.name);
}
else {
if (cloud.revision !== undefined && cloud.revision !== record.revision) {
this.conflict(stats, skill.name, 'cloud_newer');
continue;
}
const updated = await client.updateSkill(skill.name, {
description: skill.description,
files,
expected_revision: record.revision,
operation_id: operationId,
});
if (!updated.ok) {
const reason = updated.error.code === 'revision_conflict' ? 'cloud_newer' : `upload_failed: ${describeError(updated.error)}`;
this.conflict(stats, skill.name, reason);
continue;
}
this.markUploaded(state, skill.name, {
folder: entry.name,
revision: updated.data.skill?.revision ?? updated.data.revision ?? record.revision + 1,
manifest: skill.manifest,
syncedAt: new Date().toISOString(),
});
stateDirty = true;
stats.updated.push(skill.name);
}
}
// Presence counts the parking area too: a parked skill is disabled,
// not deleted. Anything missing from both is a deliberate removal
// (remembered, so it is not resurrected); the cloud copy stays.
const presentFolders = new Set(seenFolders);
for (const entry of await readdir(this.holdingRoot(), { withFileTypes: true }).catch(() => [])) {
if (entry.isDirectory())
presentFolders.add(entry.name);
}
for (const [name, record] of Object.entries(state.uploaded)) {
if (!presentFolders.has(record.folder)) {
state.removed[name] = { manifest: cloudByName.get(name)?.manifest_sha256 ?? record.manifest };
delete state.uploaded[name];
stateDirty = true;
}
}
for (const [name, record] of Object.entries(state.delivered)) {
if (!presentFolders.has(name)) {
state.removed[name] = { manifest: record.manifest };
delete state.delivered[name];
stateDirty = true;
}
}
if (stateDirty)
await this.saveState(state);
const changed = stats.downloaded.length + stats.uploaded.length + stats.updated.length;
if (changed > 0 || stats.conflicts.length > 0) {
this.deps.log(`skill sync: ${stats.downloaded.length} downloaded, ${stats.uploaded.length} uploaded, ` +
`${stats.updated.length} updated, ${stats.conflicts.length} conflict(s)`);
}
}
/**
* Read one locally-originated skill for upload. Returns the skill, a
* conflict reason string, or undefined when the folder is not a skill.
*/
async readLocalSkill(dir, folder) {
let files;
try {
files = await this.readSkillFiles(dir);
}
catch {
return undefined;
}
const markdown = files.find((file) => file.rel === 'SKILL.md');
if (markdown === undefined)
return undefined;
if (files.length > MAX_FILES)
return 'too_many_files';
let total = 0;
for (const file of files) {
if (file.buffer.length > MAX_FILE_BYTES)
return 'file_too_large';
total += file.buffer.length;
if (!isCloudSkillPath(file.rel))
return 'unsupported_layout';
}
if (total > MAX_SKILL_BYTES)
return 'skill_too_large';
const frontmatter = parseSkillFrontmatter(markdown.buffer.toString('utf8'));
const name = frontmatter.name !== undefined && CLOUD_SKILL_NAME.test(frontmatter.name)
? frontmatter.name
: CLOUD_SKILL_NAME.test(folder)
? folder
: undefined;
if (name === undefined)
return 'invalid_name';
const heading = /^#\s+(.+)$/m.exec(markdown.buffer.toString('utf8'))?.[1]?.trim();
const description = (frontmatter.description ?? heading ?? name).slice(0, 500);
const manifest = linkedSkillManifest(files.map((file) => ({ path: file.rel, sha256: sha256Hex(file.buffer) })));
return {
name,
description,
files,
manifest,
hasScripts: files.some((file) => file.rel.startsWith('scripts/')),
};
}
/** Encode local files exactly the way the upload path does. */
toUploadFiles(files) {
return files.map((file) => {
const ext = file.rel.slice(file.rel.lastIndexOf('.')).toLowerCase();
return TEXT_EXT.has(ext)
? { path: file.rel, content: file.buffer.toString('utf8') }
: { path: file.rel, base64: file.buffer.toString('base64') };
});
}
/** Drop one name from the in-memory conflict list after it is resolved. */
dropConflict(name) {
this.current = { ...this.current, conflicts: this.current.conflicts.filter((conflict) => conflict.name !== name) };
}
/**
* Both sides of every conflict from the last pass, so a human can decide.
* Read-only: it never changes a file or uploads anything.
*/
async conflictDetails() {
const conflicts = this.current.conflicts;
if (conflicts.length === 0)
return [];
let cloudItems = [];
try {
const listing = await this.deps.client().listSkills();
if (listing.ok) {
cloudItems = (listing.data.items ?? []).filter((item) => typeof item.name === 'string');
}
}
catch {
// Listing failed: still show the local side with a null cloud side.
}
const byName = new Map(cloudItems.map((item) => [item.name, item]));
const out = [];
for (const conflict of conflicts) {
const rootDir = join(this.skillsRoot(), conflict.name);
const parkedDir = join(this.holdingRoot(), conflict.name);
let location = 'none';
let dir = '';
if (await isDirectory(rootDir)) {
location = 'root';
dir = rootDir;
}
else if (await isDirectory(parkedDir)) {
location = 'holding';
dir = parkedDir;
}
let files = 0;
let bytes = 0;
let modified = false;
if (dir !== '') {
try {
const local = await this.readSkillFiles(dir);
files = local.length;
bytes = local.reduce((sum, file) => sum + file.buffer.length, 0);
const delivery = await this.readDelivery(dir);
modified = delivery === undefined ? true : !(await this.deliveredIntact(dir, delivery));
}
catch {
// Unreadable folder: report zeroed counts, never throw the list away.
}
}
const cloudItem = byName.get(conflict.name);
out.push({
name: conflict.name,
reason: conflict.reason,
local: { exists: location !== 'none', location, files, bytes, modified },
cloud: cloudItem === undefined
? null
: {
...(cloudItem.revision === undefined ? {} : { revision: cloudItem.revision }),
...(cloudItem.manifest_sha256 === undefined ? {} : { manifest: cloudItem.manifest_sha256 }),
...(cloudItem.files === undefined ? {} : { files: cloudItem.files }),
...(cloudItem.bytes === undefined ? {} : { bytes: cloudItem.bytes }),
...(cloudItem.enabled === undefined ? {} : { enabled: cloudItem.enabled }),
},
canKeepLocal: location !== 'none',
canTakeCloud: cloudItem !== undefined,
note: '“保留本地”把本地版本上传成新的云端版本;“采用云端”先备份本地再覆盖;“手动合并”只返回两侧信息,不改文件。',
});
}
return out;
}
/** Resolve one conflict: keep local / take cloud / manual (no write). */
async resolveConflict(nameInput, actionInput) {
const name = typeof nameInput === 'string' ? nameInput : '';
if (name === '' || !CLOUD_SKILL_NAME.test(name))
throw new Error('invalid_name');
const action = actionInput === 'keep_local' || actionInput === 'take_cloud' || actionInput === 'manual' ? actionInput : '';
if (action === '')
throw new Error('invalid_action');
if (this.running)
throw new Error('sync_running');
const root = this.skillsRoot();
const rootDir = join(root, name);
const parkedDir = join(this.holdingRoot(), name);
const inRoot = await isDirectory(rootDir);
const parked = !inRoot && (await isDirectory(parkedDir));
const dir = inRoot ? rootDir : parked ? parkedDir : '';
const client = this.deps.client();
const listing = await client.listSkills();
if (!listing.ok)
throw new Error(`skill listing failed: ${describeError(listing.error)}`);
const cloud = (listing.data.items ?? []).find((item) => item.name === name);
const state = await this.loadState();
if (action === 'manual') {
return {
name,
action,
applied: false,
note: '已返回两侧信息,未改动任何文件;手工编辑后在下次同步前保存即可。',
...(cloud?.revision === undefined ? {} : { revision: cloud.revision }),
};
}
if (action === 'keep_local') {
if (dir === '')
throw new Error('no_local_copy');
const skill = await this.readLocalSkill(dir, name);
if (skill === undefined)
throw new Error('not_a_skill');
if (typeof skill === 'string')
throw new Error(skill);
const files = this.toUploadFiles(skill.files);
const operationId = `dsh-skill-${randomUUID()}`;
if (cloud === undefined) {
const created = await client.createSkill({
name: skill.name,
description: skill.description,
execution_mode: skill.hasScripts ? 'local-bundle' : 'prompt-only',
files,
expected_revision: 0,
operation_id: operationId,
});
if (!created.ok)
throw new Error(`upload_failed: ${describeError(created.error)}`);
const revision = created.data.skill?.revision ?? created.data.revision ?? 1;
// The local copy is now the upload source of truth: drop any stale
// cloud-delivery marker before committing the success state.
await rm(join(dir, '.manifest.json'), { force: true });
this.markUploaded(state, name, { folder: name, revision, manifest: skill.manifest, syncedAt: new Date().toISOString() });
delete state.removed[name];
await this.saveState(state);
this.dropConflict(name);
return { name, action, applied: true, revision, note: '已把本地版本新建到云端。' };
}
const updated = await client.updateSkill(name, {
description: skill.description,
files,
expected_revision: cloud.revision ?? 0,
operation_id: operationId,
});
if (!updated.ok) {
if (updated.error.code === 'revision_conflict')
throw new Error('stale_revision');
throw new Error(`upload_failed: ${describeError(updated.error)}`);
}
const revision = updated.data.skill?.revision ?? updated.data.revision ?? (cloud.revision ?? 0) + 1;
await rm(join(dir, '.manifest.json'), { force: true });
this.markUploaded(state, name, { folder: name, revision, manifest: skill.manifest, syncedAt: new Date().toISOString() });
delete state.removed[name];
await this.saveState(state);
this.dropConflict(name);
return { name, action, applied: true, revision, note: '已用本地版本覆盖云端(revision 已更新)。' };
}
// take_cloud
if (cloud === undefined)
throw new Error('no_cloud_copy');
const bundle = await client.skillBundle(name);
if (!bundle.ok)
throw new Error(`bundle_failed: ${describeError(bundle.error)}`);
if (linkedSkillManifest(bundle.data.files) !== bundle.data.manifest_sha256)
throw new Error('manifest_mismatch');
let backup = '';
if (dir !== '') {
const stamp = new Date().toISOString().replace(/[:.]/g, '-');
backup = join(dshHome(), '.dsh-brain-backups', 'sync', name, stamp);
await mkdir(join(backup, '..'), { recursive: true });
await cp(dir, backup, { recursive: true, filter: (p) => !p.split(/[\\/]/).includes('.git') });
}
await this.install(cloud, bundle.data, parked ? this.holdingRoot() : root);
this.markDelivered(state, name, bundle.data.manifest_sha256);
delete state.removed[name];
await this.saveState(state);
this.dropConflict(name);
return {
name,
action,
applied: true,
revision: bundle.data.revision,
...(backup === '' ? {} : { backup }),
note: '已采用云端版本覆盖本地(本地已备份)。',
};
}
}