@xdxer/dingtalk-agent 0.1.4 → 0.1.5-beta.10

package/dist/src/multica-provider.js

@@ -2,15 +2,33 @@ import { createHash } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync, } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
-import { WORKSPACE_STATE_ROOT, inspectAgentProject, showDevelopmentWorkspace, } from './development-workspace.js';
+import { RESERVED_MULTICA_ENV, WORKSPACE_STATE_ROOT, inspectAgentProject, multicaAgentIdSource, showDevelopmentWorkspace, } from './development-workspace.js';
 import { digest, stableStringify } from './events.js';
+import { supportedRuntimeProviders, vocabulariesForRuntimeProvider, } from './multica-runtime-vocabulary.js';
 export const MULTICA_EVIDENCE_ROOT = '.dingtalk-agent/development-workspace-evidence';
-export const MULTICA_BOOT_SKILL = 'dingtalk-agent-boot-multica';
+/**
+ * Strip env variables the provider CLI reinterprets as mode switches (see
+ * RESERVED_MULTICA_ENV) from a child-process environment. dta reads manifest env refs from
+ * the raw env *before* this runs, so a ref named after a reserved variable still resolves —
+ * only the multica subprocess stops seeing it.
+ */
+export function sanitizeProviderEnv(env) {
+    const removed = RESERVED_MULTICA_ENV
+        .filter((key) => env[key] !== undefined).sort();
+    if (!removed.length)
+        return { env, removed };
+    const child = { ...env };
+    for (const key of removed)
+        delete child[key];
+    return { env: child, removed };
+}
 class MulticaReadFailure extends Error {
     category;
-    constructor(category) {
+    detail;
+    constructor(category, detail) {
         super(category);
         this.category = category;
+        this.detail = detail;
     }
 }
 export function planMulticaWorkspace(start, name, options = {}) {
@@ -72,6 +90,172 @@ export function planMulticaWorkspace(start, name, options = {}) {
         dingtalkSideEffect: false,
     };
 }
+const SCAFFOLD_STAGES = new Set(['dev', 'test', 'staging', 'prod']);
+const SCAFFOLD_NAME = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/;
+/**
+ * Author a multica-provider Workspace entry into dingtalk-agent.json so callers never hand-copy
+ * the schema. Env-referenced IDs are namespaced by Workspace name; authority is filled in and
+ * `agentIdFrom` deliberately omitted (first deploy creates the Agent and saves its ID). The
+ * written manifest is re-parsed to fail closed on any invalid result.
+ */
+export function scaffoldMulticaWorkspace(start, name, options = {}) {
+    const cliVersion = options.cliVersion || '';
+    if (!SCAFFOLD_NAME.test(name))
+        throw new Error(`Workspace 名不合法: ${name}`);
+    if (options.stage !== undefined && !SCAFFOLD_STAGES.has(options.stage)) {
+        throw new Error(`--stage 只支持 dev/test/staging/prod，收到 ${options.stage}`);
+    }
+    const info = inspectAgentProject(start, cliVersion);
+    const existing = info.workspaces.find((item) => item.name === name);
+    if (existing && existing.provider.kind !== 'multica') {
+        throw new Error(`Workspace ${name} 已声明为 ${existing.provider.kind}，不能改写成 multica`);
+    }
+    const alreadyDeclared = Boolean(existing);
+    let stage;
+    let profile;
+    let envRefs;
+    let block;
+    if (existing) {
+        // Report the REAL declared config, not this call's args: a manually-authored Workspace or one
+        // using non-default env names must not be misrepresented (nor its --profile/--stage silently
+        // "changed" in the output while nothing is written).
+        const stripEnv = (ref) => (ref.startsWith('env:') ? ref.slice(4) : ref);
+        stage = existing.stage;
+        profile = existing.provider.profile || '';
+        envRefs = {
+            workspaceId: stripEnv(existing.provider.workspaceIdFrom || ''),
+            runtimeId: stripEnv(existing.provider.runtimeIdFrom || ''),
+            dwsProfile: stripEnv(existing.authority?.dwsProfileFrom || ''),
+            expectedUserId: stripEnv(existing.authority?.expectedUserIdFrom || ''),
+        };
+        block = {
+            stage: existing.stage,
+            provider: { ...existing.provider },
+            ...(existing.authority ? { authority: { ...existing.authority } } : {}),
+            storage: { ...existing.storage },
+        };
+    }
+    else {
+        stage = options.stage || 'test';
+        profile = String(options.profile || '').trim();
+        if (!profile) {
+            throw new Error('multica Workspace 需要 --profile <multica CLI profile>（profile 不接受 env 引用）');
+        }
+        // Namespace env refs by Workspace name AND a stable hash of the raw name so names differing
+        // only in separators (foo-bar / foo_bar / foo.bar) never collapse to the same env variables.
+        const sanitized = name.replace(/[^a-zA-Z0-9]+/g, '_').toUpperCase();
+        const envPrefix = `DTA_${sanitized}_${digest(name).slice(0, 6).toUpperCase()}`;
+        envRefs = {
+            workspaceId: `${envPrefix}_WORKSPACE_ID`,
+            runtimeId: `${envPrefix}_RUNTIME_ID`,
+            dwsProfile: `${envPrefix}_DWS_PROFILE`,
+            expectedUserId: `${envPrefix}_EXPECTED_USER_ID`,
+        };
+        block = {
+            stage,
+            provider: {
+                kind: 'multica',
+                profile,
+                workspaceIdFrom: `env:${envRefs.workspaceId}`,
+                runtimeIdFrom: `env:${envRefs.runtimeId}`,
+            },
+            authority: {
+                dwsProfileFrom: `env:${envRefs.dwsProfile}`,
+                expectedUserIdFrom: `env:${envRefs.expectedUserId}`,
+            },
+            storage: {
+                memory: 'local-md:MEMORY.md',
+                knowledge: 'local-md:knowledge/INDEX.md',
+                artifacts: `local-dir:.dingtalk-agent/artifacts/${name}`,
+            },
+        };
+    }
+    const result = (applied, createdPaths = []) => ({
+        $schema: 'dingtalk-agent/workspace-scaffold@1',
+        workspace: name,
+        provider: 'multica',
+        stage,
+        profile,
+        applied,
+        alreadyDeclared,
+        manifest: 'dingtalk-agent.json',
+        block,
+        envRefs,
+        createdPaths,
+        nextSteps: alreadyDeclared
+            ? [
+                `Workspace ${name} 已声明（未改写）；以下是它当前真实的配置`,
+                ...(options.profile && options.profile.trim() && options.profile.trim() !== profile
+                    ? [`注意：本次 --profile=${options.profile.trim()} 与已声明 profile=${profile} 不同，未生效；要改请手动编辑 dingtalk-agent.json`]
+                    : []),
+                ...(options.stage && options.stage !== stage
+                    ? [`注意：本次 --stage=${options.stage} 与已声明 stage=${stage} 不同，未生效`]
+                    : []),
+                `设置 4 个 env 后运行 dta workspace doctor ${name}`,
+                `export ${envRefs.workspaceId}=<multica workspace uuid>`,
+                `export ${envRefs.runtimeId}=<multica runtime uuid>`,
+                `export ${envRefs.dwsProfile}=<dws profile 或 corpId>`,
+                `export ${envRefs.expectedUserId}=<dws user id>`,
+            ]
+            : [
+                applied
+                    ? '已写入 dingtalk-agent.json；只改了本地 manifest（含 artifacts 目录），' +
+                        '未创建任何 Multica 远端资源——远端 workspace/runtime 用 ops 技能供给，Agent 由 dta deploy 创建'
+                    : '预览（加 --yes 落盘）；本命令只写本地 manifest，不创建任何 Multica 远端资源',
+                `export ${envRefs.workspaceId}=<multica workspace uuid>`,
+                `export ${envRefs.runtimeId}=<multica runtime uuid>`,
+                `export ${envRefs.dwsProfile}=<dws profile 或 corpId>`,
+                `export ${envRefs.expectedUserId}=<dws user id>`,
+                `dta workspace doctor ${name}`,
+                `dta workspace plan ${name} --json`,
+                `dta workspace inspect ${name} --execute --yes --json   # 代理环境先套 env -u ...PROXY`,
+                `dta deploy --workspace ${name} --dry-run --json`,
+            ],
+        sideEffect: applied ? 'local-manifest' : false,
+        dingtalkSideEffect: false,
+    });
+    if (alreadyDeclared || !options.apply)
+        return result(false);
+    const manifestPath = join(info.root, 'dingtalk-agent.json');
+    if (!existsSync(manifestPath) || lstatSync(manifestPath).isSymbolicLink()) {
+        throw new Error('未找到可写的 dingtalk-agent.json（或它是 symlink）；无法脚手架 Workspace');
+    }
+    const raw = readFileSync(manifestPath, 'utf8');
+    const manifest = JSON.parse(raw);
+    if (!manifest.workspaces || typeof manifest.workspaces !== 'object')
+        manifest.workspaces = {};
+    if (name in manifest.workspaces)
+        return result(false);
+    manifest.workspaces[name] = block;
+    const stamp = `${process.pid}-${digest(raw).slice(0, 8)}`;
+    const staging = `${manifestPath}.tmp-${stamp}`;
+    writeFileSync(staging, `${JSON.stringify(manifest, null, 2)}\n`);
+    renameSync(staging, manifestPath);
+    try {
+        showDevelopmentWorkspace(info.root, name, cliVersion);
+    }
+    catch (error) {
+        // Restore the exact original bytes atomically (staging + rename), never a partial write:
+        // a kill mid-restore must not leave a truncated shared manifest.
+        const restore = `${manifestPath}.restore-${stamp}`;
+        writeFileSync(restore, raw);
+        renameSync(restore, manifestPath);
+        throw error;
+    }
+    // 声明的路径必须原子性地存在：manifest 里写了 artifacts 目录却不创建它，新项目
+    // 第一次 doctor 就挂在 storage.artifacts（E-01）——doctor 不该要求用户补脚手架遗漏。
+    // .gitkeep 让空目录进 git，fresh clone 后 doctor 依然通过。回滚路径不清理该目录
+    // （幂等无害，保持回滚逻辑简单）。
+    const artifactsDir = join(info.root, '.dingtalk-agent', 'artifacts', name);
+    mkdirSync(artifactsDir, { recursive: true });
+    const gitkeep = join(artifactsDir, '.gitkeep');
+    if (!existsSync(gitkeep))
+        writeFileSync(gitkeep, '');
+    return result(true, [
+        relative(info.root, artifactsDir).split('\\').join('/'),
+        relative(info.root, gitkeep).split('\\').join('/'),
+    ]);
+}
 export function inspectMulticaWorkspace(start, name, options = {}) {
     const plan = planMulticaWorkspace(start, name, options);
     if (!options.execute)
@@ -148,6 +332,8 @@ export function statusMulticaWorkspace(start, name, cliVersion = '') {
         observedHash: report.observedHash,
         diff: [...report.diff],
         failures: [...report.failures],
+        failureDetails: Array.isArray(report.failureDetails) ? [...report.failureDetails] : [],
+        observedAgentRuntimeId: report.resources?.agent?.runtimeId || '',
         remoteRead: false,
         remoteWrite: false,
         sideEffect: false,
@@ -155,9 +341,11 @@ export function statusMulticaWorkspace(start, name, cliVersion = '') {
     };
 }
 function executeInspection(start, name, plan, options, persist) {
-    const env = options.env || process.env;
-    const target = resolveMulticaTarget(start, name, env, options.cliVersion || '', options.agentIdOverride);
-    const command = options.command || env.DTA_MULTICA_BIN || 'multica';
+    const rawEnv = options.env || process.env;
+    const target = resolveMulticaTarget(start, name, rawEnv, options.cliVersion || '', options.agentIdOverride);
+    const sanitized = sanitizeProviderEnv(rawEnv);
+    const env = sanitized.env;
+    const command = options.command || rawEnv.DTA_MULTICA_BIN || 'multica';
     const timeoutMs = positiveTimeout(options.timeoutMs);
     if (persist) {
         const plannedEvidence = options.out || join(MULTICA_EVIDENCE_ROOT, safeName(name), 'multica-inspections', 'planned.json');
@@ -167,6 +355,7 @@ function executeInspection(start, name, plan, options, persist) {
     }
     const calls = [];
     const failures = [];
+    const failureDetails = [];
     const diff = [];
     let cliVersion = '';
     let principalHash = '';
@@ -179,12 +368,23 @@ function executeInspection(start, name, plan, options, persist) {
         const parsedConfig = parseConfig(config.stdout, target.profile);
         serverHash = parsedConfig.server ? digest(parsedConfig.server) : '';
         if (parsedConfig.workspaceId && parsedConfig.workspaceId !== target.workspaceId) {
-            throw new MulticaReadFailure('scope.profile-workspace-mismatch');
+            throw new MulticaReadFailure('scope.profile-workspace-mismatch', {
+                code: 'scope.profile-workspace-mismatch',
+                expected: target.workspaceId,
+                actual: safeDisplay(parsedConfig.workspaceId),
+                hint: `profile ${target.profile} 的 workspace_id 指向另一个 Workspace；` +
+                    '为目标 Workspace 建专属具名 profile（复制 config 只改 workspace_id），或修正现有 profile',
+            });
         }
         const auth = runRead(command, profileArgs(target, ['auth', 'status']), 'auth.status', target.root, env, timeoutMs, calls);
         const principal = parseAuth(auth.stdout + '\n' + auth.stderr);
         if (!principal)
-            throw new MulticaReadFailure('auth.not-authenticated');
+            throw new MulticaReadFailure('auth.not-authenticated', {
+                code: 'auth.not-authenticated',
+                hint: `确认 multica --profile ${target.profile} 已登录；` +
+                    'dta 调用 CLI 时已剔除保留变量（MULTICA_AGENT_ID/MULTICA_SERVER_URL/MULTICA_TOKEN），' +
+                    '身份与 endpoint 只认具名 profile',
+            });
         principalHash = digest(principal);
         const workspaceList = jsonArray(runRead(command, profileArgs(target, ['workspace', 'list', '--output', 'json']), 'workspace.list', target.root, env, timeoutMs, calls).stdout, 'workspace list');
         const workspaceMatches = workspaceList.filter((item) => idOf(item) === target.workspaceId);
@@ -215,6 +415,27 @@ function executeInspection(start, name, plan, options, persist) {
             provider: safeDisplay(runtime.provider),
             status: safeDisplay(runtime.status),
         };
+        // Skill 装载合同只在注册过 trace 词汇的 runtime provider 上成立。hermes 上部署会
+        // "成功"、Skill 显示 enabled，agent 一加载却 100% `Skill not found` 且零告警——
+        // 这里 fail-closed，把确定性死局挡在任何远端写入之前。
+        const runtimeProvider = resources.runtime.provider;
+        if (!runtimeProvider) {
+            throw new MulticaReadFailure('scope.runtime-provider-unknown', {
+                code: 'scope.runtime-provider-unknown',
+                expected: supportedRuntimeProviders(),
+                actual: '(empty)',
+                hint: '远端 runtime 未报告 provider 字段；用 multica runtime get 核实后再部署',
+            });
+        }
+        if (!vocabulariesForRuntimeProvider(runtimeProvider).length) {
+            throw new MulticaReadFailure('scope.runtime-provider-unsupported', {
+                code: 'scope.runtime-provider-unsupported',
+                expected: supportedRuntimeProviders(),
+                actual: runtimeProvider,
+                hint: 'dta 的 Skill 装载合同只在这些 runtime provider 上成立' +
+                    '（如 hermes 上 workspace skill 一律加载不到）；换用受支持 provider 的 runtime',
+            });
+        }
         const agents = jsonArray(runRead(command, scopedArgs(target, ['agent', 'list', '--include-archived', '--output', 'json']), 'agent.list', target.root, env, timeoutMs, calls).stdout, 'agent list');
         resources.agentCandidates = agents
             .filter((item) => optionalField(item.name) === target.projectName)
@@ -240,9 +461,26 @@ function executeInspection(start, name, plan, options, persist) {
             const agent = jsonObject(runRead(command, scopedArgs(target, ['agent', 'get', target.agentId, '--output', 'json']), 'agent.get', target.root, env, timeoutMs, calls).stdout, 'agent get');
             const agentWorkspace = optionalField(agent.workspace_id);
             const agentRuntime = optionalField(agent.runtime_id);
-            if (idOf(agent) !== target.agentId || agentWorkspace !== target.workspaceId ||
-                agentRuntime !== target.runtimeId) {
-                throw new MulticaReadFailure('scope.agent-binding-mismatch');
+            if (idOf(agent) !== target.agentId || agentWorkspace !== target.workspaceId) {
+                throw new MulticaReadFailure('scope.agent-binding-mismatch', {
+                    code: 'scope.agent-binding-mismatch',
+                    expected: `workspace=${target.workspaceId}`,
+                    actual: `workspace=${safeDisplay(agentWorkspace) || '(empty)'}`,
+                    hint: 'Agent 不属于目标 Workspace；Workspace 边界不允许跨越',
+                });
+            }
+            // Runtime 归属漂移不再当 inspection 硬失败：那会把 deploy 与 --retire 一起锁死
+            // （retire 被它要解开的锁挡住）。漂移记录成 diff；apply 层负责在没有显式
+            // --rebind-runtime 时拒绝，retire 不受它阻挡。
+            if (agentRuntime !== target.runtimeId) {
+                diff.push('agent.runtime-drift');
+                failureDetails.push({
+                    code: 'agent.runtime-drift',
+                    expected: target.runtimeId,
+                    actual: safeDisplay(agentRuntime) || '(empty)',
+                    hint: '迁移 runtime 用 dta deploy --rebind-runtime（先 --dry-run）；' +
+                        '退役用 deploy --retire，不受漂移阻挡',
+                });
             }
             resources.agent = {
                 id: target.agentId,
@@ -260,7 +498,12 @@ function executeInspection(start, name, plan, options, persist) {
             })).sort(compareNamedResource);
         }
         else if (resources.agentCandidates.length > 0) {
-            throw new MulticaReadFailure('agent.unbound-name-candidates');
+            throw new MulticaReadFailure('agent.unbound-name-candidates', {
+                code: 'agent.unbound-name-candidates',
+                actual: resources.agentCandidates.map((item) => `${item.id}${item.archived ? ' (archived)' : ''}`),
+                hint: '远端已有同名 Agent，dta 不按名字猜绑定；核对候选后在 manifest 声明 ' +
+                    'provider.agentIdFrom 指向正确 ID（或依赖首次 deploy 写入的 state.binding.agentId）',
+            });
         }
         else {
             diff.push('agent.create');
@@ -279,7 +522,13 @@ function executeInspection(start, name, plan, options, persist) {
         }
     }
     catch (error) {
-        failures.push(error instanceof MulticaReadFailure ? error.category : 'provider.read-failed');
+        if (error instanceof MulticaReadFailure) {
+            failures.push(error.category);
+            if (error.detail)
+                failureDetails.push(error.detail);
+        }
+        else
+            failures.push('provider.read-failed');
     }
     const canonical = {
         cliVersion,
@@ -319,6 +568,8 @@ function executeInspection(start, name, plan, options, persist) {
         resources,
         diff: [...diff].sort(),
         failures: [...failures].sort(),
+        failureDetails,
+        envSanitized: sanitized.removed,
         calls,
         evidencePath,
         remoteRead: true,
@@ -408,20 +659,28 @@ function resolveMulticaTarget(start, name, env, cliVersion, agentIdOverride = ''
             blocking.push('agent-id-override.invalid');
         }
     }
-    else if (provider.agentIdFrom)
-        agentId = resolveRef(provider.agentIdFrom, 'agent-id');
-    else if (workspace.state?.binding.agentId) {
-        try {
-            agentId = resourceId(workspace.state.binding.agentId, 'state.agent-id');
-        }
-        catch {
-            blocking.push('state.agent-id.invalid');
+    else {
+        // 来源选择收口到 multicaAgentIdSource（schedule 共用同一份，防两处漂移）。
+        // A declared-but-empty agentIdFrom means "not yet bound" on a workspace whose Agent
+        // has not been created. Treat it like an omitted agentIdFrom (createable, no blocker):
+        // the deploy W4 create path saves the real ID to state, and the run/retire paths add
+        // their own `agent-id.missing` blocker. A malformed (non-empty, invalid) value still blocks.
+        const source = multicaAgentIdSource(workspace);
+        if (source.kind === 'declared')
+            agentId = resolveRef(source.ref, 'agent-id', true);
+        else if (source.kind === 'state') {
+            try {
+                agentId = resourceId(source.agentId, 'state.agent-id');
+            }
+            catch {
+                blocking.push('state.agent-id.invalid');
+            }
         }
     }
     return {
         root: info.root,
         projectName: info.project.displayName,
-        skills: [...new Set([...info.project.skills, MULTICA_BOOT_SKILL])].sort(),
+        skills: [...new Set(info.project.skills)].sort(),
         workspace,
         profile: provider.profile,
         workspaceId,
@@ -461,7 +720,7 @@ function scopedArgs(target, args) {
 function runRead(command, argv, id, cwd, env, timeoutMs, calls) {
     const run = spawnSync(command, argv, {
         cwd,
-        env,
+        env: sanitizeProviderEnv(env).env,
         encoding: 'utf8',
         timeout: timeoutMs,
         maxBuffer: 16 * 1024 * 1024,
@@ -479,10 +738,27 @@ function runRead(command, argv, id, cwd, env, timeoutMs, calls) {
         stderrHash: sha256(stderr),
         passed,
     });
-    if (!passed)
-        throw new MulticaReadFailure(`command.${id}`);
+    if (!passed) {
+        emitProviderDiagnostic(id, exitCode, stderr || stdout);
+        throw new MulticaReadFailure(`command.${id}`, {
+            code: `command.${id}`,
+            actual: `exit=${exitCode}`,
+            hint: 'provider CLI 原始 stderr 已透传到终端（证据文件只存 hash）',
+        });
+    }
     return { stdout, stderr };
 }
+/**
+ * Provider CLI failures used to vanish into a hash: the receipt recorded `stderrHash` and the
+ * user saw only `command.<id>`. The raw text still must never enter evidence files, so it goes
+ * straight to dta's own stderr — visible in the moment, never persisted.
+ */
+export function emitProviderDiagnostic(id, exitCode, output) {
+    const text = output.trim();
+    const body = !text ? '（无 stderr 输出）'
+        : text.length > 2048 ? `${text.slice(0, 2048)}…` : text;
+    process.stderr.write(`[multica ${id}] exit=${exitCode} ${body}\n`);
+}
 function parseMulticaVersion(value) {
     const match = value.match(/\bmultica\s+([0-9]+\.[0-9]+\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?)/i);
     if (!match)
@@ -603,6 +879,8 @@ function emptyStatus(workspace) {
         observedHash: workspace.observedHash,
         diff: [],
         failures: ['inspection.missing'],
+        failureDetails: [],
+        observedAgentRuntimeId: '',
         remoteRead: false,
         remoteWrite: false,
         sideEffect: false,