@xdxer/dingtalk-agent 0.1.4-beta.7 → 0.1.4-beta.9

package/dist/src/agent-enhance.js

@@ -0,0 +1,678 @@
+import { randomUUID } from 'node:crypto';
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { auditAgent } from './agent-audit.js';
+import { loadAgentBindings } from './agent-bindings.js';
+import { inspectAgentProject } from './development-workspace.js';
+import { digest, stableStringify } from './events.js';
+import { resolvePackageRoot } from './package-root.js';
+const NAME = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/;
+const BASIC = 'dingtalk-basic-behavior';
+const BASIC_INSTRUCTION = '.agents/skills/dingtalk-basic-behavior/SKILL.md';
+const DIRECTORY_HASH = digest('dingtalk-agent/directory@1');
+const TEMPLATE_MARKER = /<(?:Agent 名称|岗位\/角色|人群、团队或工作场域|长期目标|主动负责的事项|可观察的交付物|明确不做或必须升级确认的事项|Role Skill names|role-skill-name|Role Skill 名称|岗位职责或工作流|领域判断、输入与交付物|领域输入|领域方法\/SOP|可观察结果 [12]|route)>/u;
+export function planAgentEnhancement(root, options = {}) {
+    return buildEnhancement(root, options).plan;
+}
+export function applyAgentEnhancement(root, options) {
+    if (!options.yes)
+        throw new Error('agent enhance apply 必须显式传 --yes');
+    if (!String(options.planId || '').trim()) {
+        throw new Error('agent enhance apply 必须传当前 dry-run 返回的 --plan-id');
+    }
+    const built = buildEnhancement(root, options);
+    const { plan } = built;
+    if (!plan.ready)
+        throw new Error(`agent enhance plan 被阻塞: ${plan.blockers.join('; ')}`);
+    if (options.planId !== plan.planId) {
+        throw new Error(`agent enhance planId 已过期或不匹配: expected=${plan.planId}`);
+    }
+    const changes = plan.operations.filter((item) => item.kind !== 'preserve');
+    const operationId = `agent_enhance_${Date.now()}_${randomUUID().slice(0, 8)}`;
+    const backupRelative = changes.some((item) => item.backupRequired)
+        ? join('.dingtalk-agent', 'backups', 'agent-enhance', operationId) : '';
+    const backupRoot = backupRelative ? resolve(plan.root, backupRelative) : '';
+    const backedUp = new Set();
+    const created = new Set();
+    let audit;
+    try {
+        if (backupRoot) {
+            for (const operation of changes.filter((item) => item.backupRequired)) {
+                const source = safeTarget(plan.root, operation.path);
+                const destination = resolve(backupRoot, operation.path);
+                copyEntry(source, destination);
+                backedUp.add(operation.path);
+            }
+            writeAtomic(join(backupRoot, 'manifest.json'), JSON.stringify({
+                $schema: 'dingtalk-agent/agent-enhancement-backup@1',
+                operationId, planId: plan.planId,
+                entries: [...backedUp].sort().map((path) => ({
+                    path,
+                    hash: stateHash(safeTarget(plan.root, path)),
+                })),
+            }, null, 2) + '\n');
+        }
+        for (const operation of changes) {
+            const target = safeTarget(plan.root, operation.path);
+            if (!existsSync(target))
+                created.add(operation.path);
+            if (operation.kind === 'create-directory') {
+                mkdirSync(target, { recursive: true });
+            }
+            else if (operation.kind === 'create-file' || operation.kind === 'update-file') {
+                writeAtomic(target, built.files.get(operation.path));
+            }
+            else if (operation.kind === 'replace-directory') {
+                rmSync(target, { recursive: true, force: true });
+                writeTree(target, built.trees.get(operation.path));
+            }
+            const actual = operation.kind === 'create-directory'
+                ? (existsSync(target) && lstatSync(target).isDirectory() && !lstatSync(target).isSymbolicLink()
+                    ? DIRECTORY_HASH : '')
+                : stateHash(target);
+            if (actual !== operation.afterHash) {
+                throw new Error(`写后 hash 不一致: ${operation.path}`);
+            }
+        }
+        const bindingsPath = safeTarget(plan.root, plan.bindings);
+        const loaded = loadAgentBindings(plan.root, relative(plan.root, bindingsPath));
+        audit = auditAgent(plan.root, {
+            bootstrap: { context: loaded.context },
+            bindings: { path: loaded.path, hash: loaded.hash },
+            requiredSkills: plan.roleSkills,
+        });
+    }
+    catch (error) {
+        rollback(plan.root, [...changes].reverse(), backupRoot, backedUp, created);
+        throw new Error(`agent enhance 失败，已按备份回滚: ${error.message}`);
+    }
+    return {
+        $schema: 'dingtalk-agent/agent-enhancement-receipt@1',
+        status: 'applied', operationId, planId: plan.planId,
+        sideEffect: 'local-files-only', dingtalkSideEffect: false, triggerSideEffect: false,
+        root: plan.root,
+        backupRoot: backupRoot ? relative(plan.root, backupRoot).split('\\').join('/') : '',
+        idempotent: changes.length === 0,
+        changes,
+        audit: {
+            status: audit.status, ready: audit.ready, missing: audit.missing,
+            commands: audit.verification.commands,
+        },
+    };
+}
+function buildEnhancement(root, options) {
+    const rootReal = realpathSync(resolve(root));
+    assertDirectory(rootReal, 'Agent root');
+    const packageRoot = resolvePackageRoot(import.meta.url);
+    const bindingsRef = safeRelative(options.bindings || 'agent.bindings.json', 'bindings');
+    const existingProjectPath = join(rootReal, 'dingtalk-agent.json');
+    const existingProject = existsSync(existingProjectPath)
+        ? readValidatedProject(rootReal, options.cliVersion || '') : null;
+    const inferredName = normalizeName(basename(rootReal));
+    const projectName = String(options.projectName || existingProject?.name || inferredName).trim();
+    const blockers = [];
+    const warnings = [];
+    if (!NAME.test(projectName))
+        blockers.push('缺少合法 project name；请传 --project-name <stable-name>');
+    if (!options.projectName && !existingProject) {
+        warnings.push(`project name 由目录名推导为 ${projectName || '(invalid)'}`);
+    }
+    const discovered = discoverRoleSkills(rootReal);
+    const requested = (options.roleSkills || []).map((item) => item.trim()).filter(Boolean);
+    const roleCandidates = [...new Set([...discovered.names, ...requested])].sort();
+    const invalidRoles = roleCandidates.filter((name) => !NAME.test(name) || name === BASIC);
+    const roleSkills = roleCandidates.filter((name) => NAME.test(name) && name !== BASIC);
+    if (invalidRoles.length)
+        blockers.push(`Role Skill name 非法: ${invalidRoles.join(', ')}`);
+    if (!roleSkills.length && !invalidRoles.length) {
+        blockers.push('没有发现 Role Skill；请传 --role-skill <name>');
+    }
+    const files = new Map();
+    const trees = new Map();
+    const directories = new Set();
+    const semanticFiles = [];
+    const bindingsPath = join(rootReal, bindingsRef);
+    const existingBindings = existsSync(bindingsPath)
+        ? loadAgentBindings(rootReal, bindingsRef).value : null;
+    const existingLocalWorkspace = existingProject?.workspaces?.['local-dev'] || null;
+    if (existingLocalWorkspace && existingLocalWorkspace.provider?.kind !== 'opencode') {
+        blockers.push('现有 local-dev 不是 OpenCode workspace；拒绝覆盖其 Provider');
+    }
+    const bindingsValue = {
+        $schema: 'dingtalk-agent/agent-bindings@1',
+        agent: existingBindings?.agent || 'local-dir:.',
+        skills: existingBindings?.skills || 'local-dir:skills',
+        memory: options.memory || existingBindings?.memory ||
+            existingLocalWorkspace?.storage?.memory || 'local-md:MEMORY.md',
+        knowledge: options.knowledge || existingBindings?.knowledge ||
+            existingLocalWorkspace?.storage?.knowledge || 'local-md:knowledge/INDEX.md',
+        artifacts: options.artifacts || existingBindings?.artifacts ||
+            existingLocalWorkspace?.storage?.artifacts || 'local-dir:.dingtalk-agent/artifacts',
+        stateDir: options.stateDir || existingBindings?.stateDir || '.dingtalk-agent',
+        authority: {
+            profile: options.profile ?? existingBindings?.authority.profile ?? '',
+            expectedUserId: options.expectedUserId ?? existingBindings?.authority.expectedUserId ?? '',
+        },
+    };
+    validateBindingsCandidate(rootReal, bindingsValue);
+    const remote = [bindingsValue.memory, bindingsValue.knowledge]
+        .some((item) => item.startsWith('dingtalk-doc:'));
+    if (remote && (!bindingsValue.authority.profile || !bindingsValue.authority.expectedUserId)) {
+        blockers.push('远端 memory/knowledge 需要同时提供 --profile 与 --expected-user-id');
+    }
+    const agentsPath = join(rootReal, 'AGENTS.md');
+    if (!existsSync(agentsPath)) {
+        const body = readAsset(packageRoot, 'AGENTS.template.md')
+            .replace('<Agent 名称>', projectName || '<Agent 名称>')
+            .replace('<Role Skill names>', roleSkills.join(', ') || '<Role Skill names>');
+        files.set('AGENTS.md', body);
+        semanticFiles.push('AGENTS.md');
+    }
+    else {
+        assertRegularFile(agentsPath, 'AGENTS.md');
+        const body = readFileSync(agentsPath, 'utf8');
+        files.set('AGENTS.md', body);
+        if (TEMPLATE_MARKER.test(body))
+            semanticFiles.push('AGENTS.md');
+    }
+    for (const name of roleSkills) {
+        const rolePath = `skills/${name}`;
+        const source = join(rootReal, rolePath);
+        let tree;
+        if (existsSync(source)) {
+            tree = readTree(source, `Role Skill ${name}`);
+            const skillBody = tree.files.get('SKILL.md')?.toString('utf8') || '';
+            const actualName = frontmatterName(skillBody);
+            if (actualName !== name)
+                blockers.push(`Role Skill ${name} frontmatter name=${actualName || '(missing)'}`);
+            if (TEMPLATE_MARKER.test(skillBody))
+                semanticFiles.push(`${rolePath}/SKILL.md`);
+        }
+        else {
+            const body = readAsset(packageRoot, 'role-skill.template.md')
+                .replaceAll('<role-skill-name>', name)
+                .replace('<Role Skill 名称>', name);
+            tree = treeFromFiles(new Map([['SKILL.md', Buffer.from(body)]]));
+            trees.set(rolePath, tree);
+            semanticFiles.push(`${rolePath}/SKILL.md`);
+        }
+        trees.set(`.agents/skills/${name}`, tree);
+    }
+    trees.set(`.agents/skills/${BASIC}`, readTree(join(packageRoot, 'skills', BASIC), 'Canonical Basic Skill'));
+    files.set(bindingsRef, JSON.stringify(bindingsValue, null, 2) + '\n');
+    const project = desiredProject(existingProject, {
+        projectName, roleSkills, model: options.model || 'deepseek/deepseek-chat',
+        modelExplicit: options.model !== undefined,
+        cliVersion: options.cliVersion || '', bindings: bindingsValue,
+    });
+    files.set('dingtalk-agent.json', JSON.stringify(project, null, 2) + '\n');
+    files.set('opencode.json', JSON.stringify(desiredOpenCode(rootReal, roleSkills), null, 2) + '\n');
+    files.set('.gitignore', desiredGitignore(rootReal, bindingsValue.stateDir));
+    for (const [label, route] of Object.entries({
+        memory: bindingsValue.memory, knowledge: bindingsValue.knowledge,
+    })) {
+        if (!route.startsWith('local-md:'))
+            continue;
+        const ref = safeRelative(route.slice('local-md:'.length), `${label} route`);
+        const path = join(rootReal, ref);
+        if (!existsSync(path)) {
+            files.set(ref, `# ${label === 'memory' ? 'Memory' : 'Knowledge'}\n\n`);
+        }
+        else
+            assertRegularFile(path, `${label} route`);
+    }
+    const artifactRef = safeLocalRoute(bindingsValue.artifacts, 'local-dir', 'artifacts');
+    if (resolve(rootReal, artifactRef) === rootReal) {
+        throw new Error('artifacts 必须是 Agent 根目录内的独立目录，不能等于根目录');
+    }
+    directories.add(artifactRef);
+    directories.add(safeRelative(bindingsValue.stateDir, 'stateDir'));
+    const operations = buildOperations(rootReal, files, trees, directories);
+    const baselineHash = digest(stableStringify(operations.map((item) => ({
+        path: item.path, beforeHash: item.beforeHash,
+    }))));
+    const desiredHash = digest(stableStringify(operations.map((item) => ({
+        path: item.path, afterHash: item.afterHash,
+    }))));
+    const source = sourceIdentity(rootReal);
+    const planSeed = {
+        schema: 'dingtalk-agent/agent-enhancement-plan@1', baselineHash, desiredHash,
+        root: rootReal, source, projectName, roleSkills, bindings: bindingsRef,
+        options: {
+            model: options.model || 'deepseek/deepseek-chat',
+            memory: bindingsValue.memory, knowledge: bindingsValue.knowledge,
+            artifacts: bindingsValue.artifacts, stateDir: bindingsValue.stateDir,
+            profileConfigured: Boolean(bindingsValue.authority.profile),
+            expectedUserConfigured: Boolean(bindingsValue.authority.expectedUserId),
+        },
+    };
+    const planId = `aep_${digest(stableStringify(planSeed)).slice(0, 32)}`;
+    const roleArgument = roleSkills.join(',') || '<role-skill>';
+    const common = [
+        ...(options.projectName ? ['--project-name', shellArg(options.projectName)] : []),
+        ...(roleSkills.length ? ['--role-skill', shellArg(roleSkills.join(','))] : []),
+        ...(options.model ? ['--model', shellArg(options.model)] : []),
+        ...(options.memory ? ['--memory', shellArg(options.memory)] : []),
+        ...(options.knowledge ? ['--knowledge', shellArg(options.knowledge)] : []),
+        ...(options.artifacts ? ['--artifacts', shellArg(options.artifacts)] : []),
+        ...(options.stateDir ? ['--state-dir', shellArg(options.stateDir)] : []),
+        ...(options.profile !== undefined ? ['--profile', '"$DTA_DWS_PROFILE"'] : []),
+        ...(options.expectedUserId !== undefined
+            ? ['--expected-user-id', '"$DTA_EXPECTED_USER_ID"'] : []),
+        ...(bindingsRef !== 'agent.bindings.json' ? ['--bindings', shellArg(bindingsRef)] : []),
+    ].join(' ');
+    const applyCommand = `dta agent enhance ${common}${common ? ' ' : ''}--plan-id ${planId} --yes --json`;
+    const plan = {
+        $schema: 'dingtalk-agent/agent-enhancement-plan@1', planId,
+        ready: blockers.length === 0, status: blockers.length ? 'blocked' : 'ready',
+        sideEffect: false, dingtalkSideEffect: false, triggerSideEffect: false,
+        root: rootReal,
+        source, projectName, roleSkills, bindings: bindingsRef,
+        baselineHash, desiredHash, operations, blockers, warnings,
+        semanticReview: {
+            required: semanticFiles.length > 0,
+            files: [...new Set(semanticFiles)].sort(),
+            why: semanticFiles.length
+                ? 'CLI 只补结构，不替开发者虚构身份、职责、交付物或领域 SOP；请由 compose Skill 完成语义评审。'
+                : '现有本体与 Role Skill 未命中模板占位符。',
+        },
+        apply: { command: applyCommand, requiresCurrentPlanId: true },
+        verification: { commands: [
+                `dta bootstrap --bindings ${shellArg(bindingsRef)} --json`,
+                `dta agent audit --bindings ${shellArg(bindingsRef)} --require-skill ${shellArg(roleArgument)} --json`,
+                `dta workspace create local-dev --dry-run --json`,
+            ] },
+    };
+    return { plan, files, trees, directories, bindingsValue };
+}
+function desiredProject(existing, input) {
+    if (existing) {
+        const next = structuredClone(existing);
+        next.name = input.projectName;
+        next.agent.skills = [...new Set([BASIC, ...(next.agent.skills || []), ...input.roleSkills])];
+        const local = next.workspaces['local-dev'];
+        if (!local) {
+            next.workspaces['local-dev'] = localOpenCodeWorkspace(input);
+        }
+        else if (local.provider?.kind === 'opencode') {
+            if (input.modelExplicit)
+                local.provider.model = input.model;
+            local.storage = {
+                ...local.storage,
+                memory: input.bindings.memory,
+                knowledge: input.bindings.knowledge,
+                artifacts: input.bindings.artifacts,
+            };
+            if ([input.bindings.memory, input.bindings.knowledge]
+                .some((item) => item.startsWith('dingtalk-doc:'))) {
+                local.authority = {
+                    dwsProfileFrom: 'env:DTA_DWS_PROFILE',
+                    expectedUserIdFrom: 'env:DTA_EXPECTED_USER_ID',
+                };
+            }
+            else {
+                delete local.authority;
+            }
+        }
+        return next;
+    }
+    const version = input.cliVersion.match(/^(\d+\.\d+\.\d+)/)?.[1] || '0.1.0';
+    return {
+        $schema: 'dingtalk-agent/project@1', name: input.projectName,
+        dtaVersion: `^${version}`,
+        agent: { definition: 'AGENTS.md', skills: [BASIC, ...input.roleSkills] },
+        workspaces: { 'local-dev': localOpenCodeWorkspace(input) },
+    };
+}
+function localOpenCodeWorkspace(input) {
+    const workspace = {
+        stage: 'dev', provider: { kind: 'opencode', model: input.model },
+        storage: {
+            memory: input.bindings.memory, knowledge: input.bindings.knowledge,
+            artifacts: input.bindings.artifacts,
+        },
+    };
+    if ([input.bindings.memory, input.bindings.knowledge]
+        .some((item) => item.startsWith('dingtalk-doc:'))) {
+        workspace.authority = {
+            dwsProfileFrom: 'env:DTA_DWS_PROFILE',
+            expectedUserIdFrom: 'env:DTA_EXPECTED_USER_ID',
+        };
+    }
+    return workspace;
+}
+function desiredOpenCode(root, roles) {
+    const path = join(root, 'opencode.json');
+    let value = { $schema: 'https://opencode.ai/config.json' };
+    if (existsSync(path)) {
+        assertRegularFile(path, 'opencode.json');
+        try {
+            value = JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch (error) {
+            throw new Error(`opencode.json 不是合法 JSON: ${error.message}`);
+        }
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new Error('opencode.json 必须是 JSON object');
+        }
+    }
+    if (value.instructions !== undefined && !Array.isArray(value.instructions)) {
+        throw new Error('opencode.json#instructions 必须是 array；拒绝覆盖未知结构');
+    }
+    if ((value.instructions || []).some((item) => typeof item !== 'string')) {
+        throw new Error('opencode.json#instructions 只能包含字符串；拒绝静默删除未知条目');
+    }
+    const instructions = (value.instructions || []);
+    value.instructions = [...instructions.filter((item) => item !== BASIC_INSTRUCTION), BASIC_INSTRUCTION];
+    const permission = value.permission === undefined ? {} : value.permission;
+    if (!permission || typeof permission !== 'object' || Array.isArray(permission)) {
+        throw new Error('opencode.json#permission 必须是 object；拒绝覆盖未知结构');
+    }
+    const skill = permission.skill === undefined ? {} : permission.skill;
+    if (!skill || typeof skill !== 'object' || Array.isArray(skill)) {
+        throw new Error('opencode.json#permission.skill 必须是 object；拒绝覆盖未知结构');
+    }
+    value.permission = { ...permission, skill: {
+            ...skill, [BASIC]: 'allow', ...Object.fromEntries(roles.map((name) => [name, 'allow'])),
+        } };
+    return value;
+}
+function buildOperations(root, files, trees, directories) {
+    const operations = [];
+    for (const [path, body] of [...files.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        const target = safeTarget(root, path);
+        const beforeHash = stateHash(target);
+        const afterHash = digest(Buffer.from(body).toString('base64'));
+        operations.push({
+            id: `file:${path}`,
+            kind: !existsSync(target) ? 'create-file' : beforeHash === afterHash ? 'preserve' : 'update-file',
+            path, beforeHash, afterHash,
+            backupRequired: existsSync(target) && beforeHash !== afterHash,
+            reason: fileReason(path),
+        });
+    }
+    for (const [path, tree] of [...trees.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        const target = safeTarget(root, path);
+        if (existsSync(target) && (!lstatSync(target).isDirectory() || lstatSync(target).isSymbolicLink())) {
+            throw new Error(`受管 Skill exposure 必须是普通目录，拒绝覆盖: ${path}`);
+        }
+        const beforeHash = stateHash(target);
+        operations.push({
+            id: `tree:${path}`,
+            kind: beforeHash === tree.hash ? 'preserve' : 'replace-directory',
+            path, beforeHash, afterHash: tree.hash,
+            backupRequired: existsSync(target) && beforeHash !== tree.hash,
+            reason: path.startsWith('.agents/') ? '物化目标 Host 的精确 Skill exposure' : '补齐缺失的 Role Skill 模板',
+        });
+    }
+    for (const path of [...directories].sort()) {
+        const target = safeTarget(root, path);
+        if (existsSync(target) && (!lstatSync(target).isDirectory() || lstatSync(target).isSymbolicLink())) {
+            throw new Error(`本地路由必须是普通目录: ${path}`);
+        }
+        operations.push({
+            id: `directory:${path}`, kind: existsSync(target) ? 'preserve' : 'create-directory',
+            path, beforeHash: existsSync(target) ? DIRECTORY_HASH : '', afterHash: DIRECTORY_HASH,
+            backupRequired: false, reason: '建立本地 state/artifact 路由，不投影控制状态到远端',
+        });
+    }
+    return operations.sort((a, b) => a.path.localeCompare(b.path));
+}
+function readValidatedProject(root, cliVersion) {
+    inspectAgentProject(root, cliVersion);
+    return JSON.parse(readFileSync(join(root, 'dingtalk-agent.json'), 'utf8'));
+}
+function discoverRoleSkills(root) {
+    const base = join(root, 'skills');
+    if (!existsSync(base))
+        return { names: [] };
+    if (!lstatSync(base).isDirectory() || lstatSync(base).isSymbolicLink()) {
+        throw new Error('skills 必须是 Agent 根目录内的普通目录');
+    }
+    const names = [];
+    for (const entry of readdirSync(base, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isDirectory() || entry.isSymbolicLink() || entry.name === BASIC)
+            continue;
+        const file = join(base, entry.name, 'SKILL.md');
+        if (!existsSync(file))
+            continue;
+        assertRegularFile(file, `Role Skill ${entry.name}`);
+        const name = frontmatterName(readFileSync(file, 'utf8'));
+        if (name !== entry.name)
+            throw new Error(`Role Skill 目录与 frontmatter name 不一致: ${entry.name}/${name || '(missing)'}`);
+        names.push(name);
+    }
+    return { names };
+}
+function validateBindingsCandidate(root, value) {
+    for (const [label, route] of Object.entries({
+        agent: value.agent, skills: value.skills, memory: value.memory,
+        knowledge: value.knowledge, artifacts: value.artifacts,
+    })) {
+        const separator = route.indexOf(':');
+        if (separator < 1 || !route.slice(separator + 1).trim())
+            throw new Error(`${label} route 非法`);
+        if (!route.startsWith('local-'))
+            continue;
+        safeRelative(route.slice(separator + 1), `${label} route`);
+    }
+    safeRelative(value.stateDir, 'stateDir');
+    if (resolve(root, value.stateDir) === root)
+        throw new Error('stateDir 不能等于 Agent 根目录');
+}
+function desiredGitignore(root, stateDir) {
+    const path = join(root, '.gitignore');
+    const state = safeRelative(stateDir, 'stateDir');
+    const entries = ['.dingtalk-agent/'];
+    if (state !== '.dingtalk-agent' && !state.startsWith('.dingtalk-agent/')) {
+        entries.push(`${state.replace(/\/+$/, '')}/`);
+    }
+    if (!existsSync(path))
+        return `${entries.join('\n')}\n`;
+    assertRegularFile(path, '.gitignore');
+    let body = readFileSync(path, 'utf8');
+    const lines = new Set(body.split(/\r?\n/).map((line) => line.trim().replace(/\/+$/, '')));
+    for (const entry of entries) {
+        if (lines.has(entry.replace(/\/+$/, '')))
+            continue;
+        body = `${body}${body && !body.endsWith('\n') ? '\n' : ''}${entry}\n`;
+        lines.add(entry.replace(/\/+$/, ''));
+    }
+    return body;
+}
+function sourceIdentity(root) {
+    const git = join(root, '.git');
+    if (!existsSync(git))
+        return { kind: 'local-folder', revision: '' };
+    let gitDirectory = git;
+    if (!lstatSync(git).isDirectory()) {
+        const ref = readFileSync(git, 'utf8').trim().match(/^gitdir:\s*(.+)$/)?.[1];
+        if (!ref)
+            return { kind: 'git-checkout', revision: '' };
+        gitDirectory = resolve(root, ref);
+    }
+    if (!gitDirectory || !existsSync(gitDirectory) || !statSync(gitDirectory).isDirectory()) {
+        return { kind: 'git-checkout', revision: '' };
+    }
+    let revision = '';
+    const head = join(gitDirectory, 'HEAD');
+    if (existsSync(head) && statSync(head).isFile()) {
+        const headValue = readFileSync(head, 'utf8').trim();
+        const ref = headValue.match(/^ref:\s*(.+)$/)?.[1] || '';
+        if (!ref)
+            revision = headValue;
+        else {
+            const commonDirFile = join(gitDirectory, 'commondir');
+            const commonDir = existsSync(commonDirFile)
+                ? resolve(gitDirectory, readFileSync(commonDirFile, 'utf8').trim()) : gitDirectory;
+            const refPath = join(commonDir, ref);
+            if (existsSync(refPath))
+                revision = readFileSync(refPath, 'utf8').trim();
+            else {
+                const packed = join(commonDir, 'packed-refs');
+                if (existsSync(packed)) {
+                    revision = readFileSync(packed, 'utf8').split(/\r?\n/)
+                        .find((line) => line.endsWith(` ${ref}`))?.split(' ')[0] || '';
+                }
+            }
+        }
+    }
+    return { kind: 'git-checkout', revision };
+}
+function fileReason(path) {
+    if (path === 'AGENTS.md')
+        return '补齐本体结构；语义内容仍需开发者评审';
+    if (path === 'agent.bindings.json')
+        return '固化本体、语义存储与宿主私有状态路由';
+    if (path === 'dingtalk-agent.json')
+        return '把目录升级为可发现、可版本化的 Agent Project';
+    if (path === 'opencode.json')
+        return '合并唯一 Basic instruction 与 Role Skill permission';
+    if (path === '.gitignore')
+        return '防止私有 state、Receipt 与原始证据进入 Git';
+    return '补齐本地语义介质入口';
+}
+function readAsset(packageRoot, name) {
+    return readFileSync(join(packageRoot, 'skills', 'dingtalk-agent-compose', 'assets', name), 'utf8');
+}
+function readTree(path, label) {
+    if (!existsSync(path) || !lstatSync(path).isDirectory() || lstatSync(path).isSymbolicLink()) {
+        throw new Error(`${label} 必须是普通目录: ${path}`);
+    }
+    const files = new Map();
+    const visit = (directory) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const candidate = join(directory, entry.name);
+            if (entry.isSymbolicLink())
+                throw new Error(`${label} 不允许 symlink: ${candidate}`);
+            if (entry.isDirectory())
+                visit(candidate);
+            else if (entry.isFile())
+                files.set(relative(path, candidate).split('\\').join('/'), readFileSync(candidate));
+        }
+    };
+    visit(path);
+    if (!files.has('SKILL.md'))
+        throw new Error(`${label} 缺少 SKILL.md`);
+    return treeFromFiles(files);
+}
+function treeFromFiles(files) {
+    const index = [...files.entries()].sort(([a], [b]) => a.localeCompare(b))
+        .map(([path, body]) => ({ path, hash: digest(body.toString('base64')) }));
+    return { files, hash: digest(stableStringify(index)) };
+}
+function writeTree(target, tree) {
+    mkdirSync(target, { recursive: true });
+    for (const [path, body] of tree.files) {
+        const out = resolve(target, path);
+        if (!isInside(target, out))
+            throw new Error(`Skill tree path 越界: ${path}`);
+        mkdirSync(dirname(out), { recursive: true });
+        writeFileSync(out, body, { flag: 'wx' });
+    }
+}
+function copyEntry(source, destination) {
+    if (!existsSync(source))
+        throw new Error(`备份源不存在: ${source}`);
+    mkdirSync(dirname(destination), { recursive: true });
+    cpSync(source, destination, {
+        recursive: lstatSync(source).isDirectory(), errorOnExist: true,
+        filter: (path) => {
+            if (lstatSync(path).isSymbolicLink())
+                throw new Error(`备份拒绝 symlink: ${path}`);
+            return true;
+        },
+    });
+}
+function rollback(root, operations, backupRoot, backedUp, created) {
+    for (const operation of operations) {
+        const target = safeTarget(root, operation.path);
+        if (created.has(operation.path))
+            rmSync(target, { recursive: true, force: true });
+        else if (backedUp.has(operation.path)) {
+            rmSync(target, { recursive: true, force: true });
+            copyEntry(resolve(backupRoot, operation.path), target);
+        }
+    }
+}
+function stateHash(path) {
+    if (!existsSync(path))
+        return '';
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink())
+        throw new Error(`受管路径不允许 symlink: ${path}`);
+    if (stat.isFile())
+        return digest(readFileSync(path).toString('base64'));
+    if (!stat.isDirectory())
+        throw new Error(`受管路径类型不支持: ${path}`);
+    const files = new Map();
+    const visit = (directory) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const candidate = join(directory, entry.name);
+            if (entry.isSymbolicLink())
+                throw new Error(`受管目录不允许 symlink: ${candidate}`);
+            if (entry.isDirectory())
+                visit(candidate);
+            else if (entry.isFile())
+                files.set(relative(path, candidate).split('\\').join('/'), readFileSync(candidate));
+        }
+    };
+    visit(path);
+    return treeFromFiles(files).hash;
+}
+function writeAtomic(path, body) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(temporary, body, { flag: 'wx' });
+    renameSync(temporary, path);
+}
+function assertDirectory(path, label) {
+    if (!existsSync(path) || !statSync(path).isDirectory())
+        throw new Error(`${label} 不存在或不是目录`);
+}
+function assertRegularFile(path, label) {
+    if (!existsSync(path) || !lstatSync(path).isFile() || lstatSync(path).isSymbolicLink()) {
+        throw new Error(`${label} 必须是普通文件`);
+    }
+}
+function safeTarget(root, path) {
+    const ref = safeRelative(path, 'managed path');
+    const target = resolve(root, ref);
+    if (!isInside(root, target))
+        throw new Error(`受管路径越出 Agent root: ${path}`);
+    let current = root;
+    for (const part of ref.split('/').slice(0, -1)) {
+        current = join(current, part);
+        if (existsSync(current) && lstatSync(current).isSymbolicLink()) {
+            throw new Error(`受管路径不能穿过 symlink: ${path}`);
+        }
+    }
+    return target;
+}
+function safeRelative(value, label) {
+    const text = String(value || '').trim().split('\\').join('/');
+    if (!text || text.startsWith('/') || text.split('/').some((item) => !item || item === '..')) {
+        throw new Error(`${label} 必须是 Agent 根目录内的相对路径: ${value}`);
+    }
+    return text.replace(/^\.\//, '');
+}
+function safeLocalRoute(route, provider, label) {
+    if (!route.startsWith(`${provider}:`))
+        throw new Error(`${label} 必须使用 ${provider}`);
+    return safeRelative(route.slice(provider.length + 1), label);
+}
+function frontmatterName(body) {
+    const block = body.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1] || '';
+    return block.match(/^name:\s*["']?([^"'\r\n]+)["']?\s*$/m)?.[1]?.trim() || '';
+}
+function normalizeName(value) {
+    return value.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64);
+}
+function shellArg(value) {
+    return /^[A-Za-z0-9_./:=@^+-]+$/.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+function isInside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`));
+}
+//# sourceMappingURL=agent-enhance.js.map