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

package/dist/src/multica-provider.js

@@ -2,14 +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';
+/**
+ * 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 = {}) {
@@ -151,7 +170,7 @@ export function scaffoldMulticaWorkspace(start, name, options = {}) {
             },
         };
     }
-    const result = (applied) => ({
+    const result = (applied, createdPaths = []) => ({
         $schema: 'dingtalk-agent/workspace-scaffold@1',
         workspace: name,
         provider: 'multica',
@@ -162,6 +181,7 @@ export function scaffoldMulticaWorkspace(start, name, options = {}) {
         manifest: 'dingtalk-agent.json',
         block,
         envRefs,
+        createdPaths,
         nextSteps: alreadyDeclared
             ? [
                 `Workspace ${name} 已声明（未改写）；以下是它当前真实的配置`,
@@ -178,7 +198,10 @@ export function scaffoldMulticaWorkspace(start, name, options = {}) {
                 `export ${envRefs.expectedUserId}=<dws user id>`,
             ]
             : [
-                applied ? '已写入 dingtalk-agent.json' : '预览（加 --yes 落盘）',
+                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>`,
@@ -219,7 +242,19 @@ export function scaffoldMulticaWorkspace(start, name, options = {}) {
         renameSync(restore, manifestPath);
         throw error;
     }
-    return result(true);
+    // 声明的路径必须原子性地存在：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);
@@ -297,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,
@@ -304,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');
@@ -316,6 +355,7 @@ function executeInspection(start, name, plan, options, persist) {
     }
     const calls = [];
     const failures = [];
+    const failureDetails = [];
     const diff = [];
     let cliVersion = '';
     let principalHash = '';
@@ -328,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);
@@ -364,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)
@@ -389,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,
@@ -409,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');
@@ -428,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,
@@ -468,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,
@@ -557,19 +659,22 @@ function resolveMulticaTarget(start, name, env, cliVersion, agentIdOverride = ''
             blocking.push('agent-id-override.invalid');
         }
     }
-    else if (provider.agentIdFrom) {
+    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.
-        agentId = resolveRef(provider.agentIdFrom, 'agent-id', true);
-    }
-    else if (workspace.state?.binding.agentId) {
-        try {
-            agentId = resourceId(workspace.state.binding.agentId, 'state.agent-id');
-        }
-        catch {
-            blocking.push('state.agent-id.invalid');
+        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 {
@@ -615,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,
@@ -633,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)
@@ -757,6 +879,8 @@ function emptyStatus(workspace) {
         observedHash: workspace.observedHash,
         diff: [],
         failures: ['inspection.missing'],
+        failureDetails: [],
+        observedAgentRuntimeId: '',
         remoteRead: false,
         remoteWrite: false,
         sideEffect: false,