feat: 增加 AgentRun Code Agent 调度装配

This commit is contained in:
Codex
2026-06-02 15:40:48 +08:00
parent 08fec46af9
commit 168c74b4ef
4 changed files with 430 additions and 0 deletions
+1
View File
@@ -99,6 +99,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥
- G14 GitOps CI/CD、Tekton/Argo CD、集群内 registry 和无锁镜像化发布:[docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)
- G14 CI/CD 性能基线、根因分析和加速收益估算:[docs/reference/g14-cicd-performance.md](docs/reference/g14-cicd-performance.md)
- Code Agent 对话就绪与真实回复判定:[docs/reference/code-agent-chat-readiness.md](docs/reference/code-agent-chat-readiness.md)
- AgentRun 手动调度装配、UniDesk SSH passthrough 与 GitHub tool credential 边界:[docs/reference/agentrun-code-agent-dispatch.md](docs/reference/agentrun-code-agent-dispatch.md)
- DEV runtime hotfix runbook 与只读审计:[docs/reference/dev-runtime-hotfix-runbook.md](docs/reference/dev-runtime-hotfix-runbook.md)
- Gateway 主动出站 demo、poll/result 和本地 smoke[docs/reference/gateway-outbound-demo.md](docs/reference/gateway-outbound-demo.md)
- Device Pod 旧链接兼容入口:[docs/reference/device-pod.md](docs/reference/device-pod.md)
@@ -0,0 +1,30 @@
# AgentRun Code Agent Dispatch
本文定义 HWLAB Code Agent 通过 AgentRun `v0.1` 手动调度 API 执行时的装配边界。它只描述稳定的 payload、SecretRef 和 credential 归属,不替代当前 G14 DEV `/v1/agent/chat` 的真实 completed 判定。
## 装配入口
- 源码入口是 `internal/agent/agentrun-dispatch.mjs`
- `createHwlabAgentRunDispatchAssembly()` 生成 AgentRun `POST /api/v1/runs``POST /api/v1/runs/:runId/commands``POST /api/v1/runs/:runId/runner-jobs` 三段 payload。
- `dispatchHwlabAgentRun()` 使用同一 assembly 顺序调用 AgentRun manager;调用方可以注入 `fetchImpl` 做合同测试或接入真实 manager。
- 默认 manager URL 是 `http://agentrun-mgr.agentrun-v01.svc.cluster.local:8080`,默认 namespace 是 `agentrun-v01`,默认 providerId 是 `G14`
## Credential 边界
- Provider credential 只通过 `executionPolicy.secretScope.providerCredentials[]` 的 AgentRun provider SecretRef 引用,默认随 `backendProfile` 选择 `agentrun-v01-provider-deepseek``agentrun-v01-provider-codex``agentrun-v01-provider-minimax-m3`
- GitHub PR/issue 能力通过 `toolCredentials[].tool=github` 注入,默认 SecretRef 是 `agentrun-v01-tool-github-pr` key `GH_TOKEN`
- UniDesk SSH passthrough 通过 `toolCredentials[].tool=unidesk-ssh` 注入,默认 SecretRef 是 `agentrun-v01-tool-unidesk-ssh` key `UNIDESK_SSH_CLIENT_TOKEN`
- `UNIDESK_SSH_CLIENT_TOKEN` 只授予 UniDesk frontend `/ws/ssh` scoped client 能力;route allowlist 由 UniDesk frontend 配置控制。HWLAB 不持有 provider token、主 server SSH key 或完整 frontend 登录态。
- `runnerJob.transientEnv` 只能承接短期或非敏感执行上下文,例如 device-pod session token 和 `UNIDESK_MAIN_SERVER_IP`;不得承载 GitHub token、UniDesk SSH client token、provider key、长期 SSH key 或 registry token。
## ResourceBundle
- AgentRun run 必须使用 Git-only `resourceBundleRef`,默认 repo 是 `http://git-mirror-http.devops-infra.svc.cluster.local/pikasTech/HWLAB.git`
- `commitId` 必须是完整 40 字符小写 SHA,不接受 branch、tag、`HEAD` 或短 SHA。
- `workspaceRef` 只描述目标 repo/branch;实际 checkout 身份以 `resourceBundleRef.repoUrl + commitId` 为准。
## 验收
- 源码合同测试:`node --test internal/agent/agentrun-dispatch.test.mjs`
- 语法检查:`node --check internal/agent/agentrun-dispatch.mjs && node --check internal/agent/agentrun-dispatch.test.mjs`
- 合同必须证明 `UNIDESK_SSH_CLIENT_TOKEN` 不出现在 `transientEnv`,且 GitHub/UniDesk SSH 能力都通过 AgentRun `toolCredentials` SecretRef 装配。
+280
View File
@@ -0,0 +1,280 @@
export const DEFAULT_AGENTRUN_NAMESPACE = "agentrun-v01";
export const DEFAULT_AGENTRUN_MANAGER_URL = "http://agentrun-mgr.agentrun-v01.svc.cluster.local:8080";
export const DEFAULT_HWLAB_AGENTRUN_PROJECT_ID = "pikasTech/HWLAB";
export const DEFAULT_HWLAB_AGENTRUN_PROVIDER_ID = "G14";
export const DEFAULT_HWLAB_AGENTRUN_REPO_URL = "http://git-mirror-http.devops-infra.svc.cluster.local/pikasTech/HWLAB.git";
export const DEFAULT_HWLAB_AGENTRUN_BRANCH = "G14";
export const DEFAULT_HWLAB_AGENTRUN_BACKEND_PROFILE = "deepseek";
export const DEFAULT_UNIDESK_MAIN_SERVER_ENV = "UNIDESK_MAIN_SERVER_IP";
export const AGENTRUN_REUSABLE_CREDENTIAL_ENV_NAMES = Object.freeze([
"AUTH_PASSWORD",
"CODEX_API_KEY",
"GH_TOKEN",
"GITHUB_TOKEN",
"OPENAI_API_KEY",
"PROVIDER_TOKEN",
"UNIDESK_AUTH_PASSWORD",
"UNIDESK_PROVIDER_TOKEN",
"UNIDESK_SSH_CLIENT_TOKEN"
]);
const backendProfiles = Object.freeze(["codex", "deepseek", "minimax-m3"]);
const providerSecretKeys = Object.freeze(["auth.json", "config.toml"]);
const reusableCredentialEnvNameSet = new Set(AGENTRUN_REUSABLE_CREDENTIAL_ENV_NAMES);
export function createGithubToolCredential({
namespace = DEFAULT_AGENTRUN_NAMESPACE,
secretName = "agentrun-v01-tool-github-pr",
secretKey = "GH_TOKEN"
} = {}) {
return {
tool: "github",
purpose: "pull-request",
secretRef: { namespace, name: secretName, keys: [secretKey] },
projection: { kind: "env", envName: secretKey, secretKey }
};
}
export function createUnideskSshToolCredential({
namespace = DEFAULT_AGENTRUN_NAMESPACE,
secretName = "agentrun-v01-tool-unidesk-ssh"
} = {}) {
return {
tool: "unidesk-ssh",
purpose: "ssh-passthrough",
secretRef: { namespace, name: secretName, keys: ["UNIDESK_SSH_CLIENT_TOKEN"] },
projection: { kind: "env", envName: "UNIDESK_SSH_CLIENT_TOKEN", secretKey: "UNIDESK_SSH_CLIENT_TOKEN" }
};
}
export function createProviderCredential({
backendProfile = DEFAULT_HWLAB_AGENTRUN_BACKEND_PROFILE,
namespace = DEFAULT_AGENTRUN_NAMESPACE,
secretName = null,
mountPath = "~/.codex"
} = {}) {
const profile = normalizeBackendProfile(backendProfile);
return {
profile,
secretRef: {
namespace,
name: secretName || `agentrun-v01-provider-${profile}`,
keys: providerSecretKeys.slice(),
mountPath
}
};
}
export function createHwlabAgentRunDispatchAssembly(options = {}) {
const env = options.env ?? process.env;
const traceId = nonEmptyString(options.traceId, "traceId");
const prompt = nonEmptyString(options.prompt, "prompt");
const commitId = fullCommitSha(options.commitId);
const backendProfile = normalizeBackendProfile(options.backendProfile ?? DEFAULT_HWLAB_AGENTRUN_BACKEND_PROFILE);
const includeGithubToolCredential = options.includeGithubToolCredential !== false;
const includeUnideskSshToolCredential = options.includeUnideskSshToolCredential !== false;
const namespace = nonEmptyString(options.namespace ?? DEFAULT_AGENTRUN_NAMESPACE, "namespace");
const managerUrl = trimTrailingSlash(nonEmptyString(options.managerUrl ?? DEFAULT_AGENTRUN_MANAGER_URL, "managerUrl"));
const projectId = nonEmptyString(options.projectId ?? DEFAULT_HWLAB_AGENTRUN_PROJECT_ID, "projectId");
const providerId = nonEmptyString(options.providerId ?? DEFAULT_HWLAB_AGENTRUN_PROVIDER_ID, "providerId");
const repoUrl = nonEmptyString(options.repoUrl ?? DEFAULT_HWLAB_AGENTRUN_REPO_URL, "repoUrl");
const branch = nonEmptyString(options.branch ?? DEFAULT_HWLAB_AGENTRUN_BRANCH, "branch");
const timeoutMs = positiveInteger(options.timeoutMs ?? 600000, "timeoutMs");
const unideskMainServerIp = optionalString(options.unideskMainServerIp ?? env.UNIDESK_MAIN_SERVER_IP ?? env.UNIDESK_MAIN_SERVER_HOST);
if (includeUnideskSshToolCredential && !unideskMainServerIp) {
throw new Error("unideskMainServerIp is required when UniDesk SSH passthrough is enabled");
}
const toolCredentials = [
...(includeGithubToolCredential ? [createGithubToolCredential({ namespace })] : []),
...(includeUnideskSshToolCredential ? [createUnideskSshToolCredential({ namespace })] : []),
...normalizeToolCredentials(options.toolCredentials ?? [])
];
const transientEnv = normalizeTransientEnv(transientEnvWithUnideskMainServer(options.transientEnv ?? [], unideskMainServerIp));
const sessionRef = createSessionRef(options);
const resourceBundleRef = {
kind: "git",
repoUrl,
commitId,
...(options.subdir ? { subdir: nonEmptyString(options.subdir, "subdir") } : {}),
...(Array.isArray(options.sparsePaths) ? { sparsePaths: options.sparsePaths.map((item, index) => nonEmptyString(item, `sparsePaths[${index}]`)) } : {}),
...(options.resourceCredentialRef ? { credentialRef: options.resourceCredentialRef } : {})
};
const runPayload = {
tenantId: "hwlab",
projectId,
workspaceRef: {
kind: "git-worktree",
repo: repoUrl,
branch
},
...(sessionRef ? { sessionRef } : { sessionRef: null }),
resourceBundleRef,
providerId,
backendProfile,
executionPolicy: {
sandbox: options.sandbox ?? "workspace-write",
approval: options.approval ?? "never",
timeoutMs,
network: options.network ?? "default",
secretScope: {
allowCredentialEcho: false,
providerCredentials: [createProviderCredential({ backendProfile, namespace })],
...(toolCredentials.length > 0 ? { toolCredentials } : {})
}
},
traceSink: options.traceSink ?? null
};
const commandPayload = {
type: "turn",
payload: {
prompt,
traceId,
projectId,
...(options.conversationId ? { conversationId: nonEmptyString(options.conversationId, "conversationId") } : {}),
...(options.sessionId ? { sessionId: nonEmptyString(options.sessionId, "sessionId") } : {}),
...(options.threadId ? { threadId: nonEmptyString(options.threadId, "threadId") } : {}),
providerProfile: backendProfile,
dispatchSource: "hwlab-code-agent"
},
idempotencyKey: options.commandIdempotencyKey ?? `hwlab:${traceId}:turn`
};
const runnerJobPayload = {
idempotencyKey: options.runnerJobIdempotencyKey ?? `hwlab:${traceId}:runner-job`,
...(options.attemptId ? { attemptId: nonEmptyString(options.attemptId, "attemptId") } : {}),
transientEnv
};
return {
managerUrl,
runPayload,
commandPayload,
runnerJobPayload,
boundaries: {
valuesPrinted: false,
githubCredentialSource: includeGithubToolCredential ? "toolCredentials" : null,
unideskSshCredentialSource: includeUnideskSshToolCredential ? "toolCredentials" : null,
unideskMainServerSource: unideskMainServerIp ? "transientEnv" : null,
transientEnvNames: transientEnv.map((item) => item.name),
forbiddenTransientEnvNames: AGENTRUN_REUSABLE_CREDENTIAL_ENV_NAMES.slice()
}
};
}
export async function dispatchHwlabAgentRun(options = {}) {
const fetchImpl = options.fetchImpl ?? globalThis.fetch;
if (typeof fetchImpl !== "function") throw new Error("dispatchHwlabAgentRun requires fetchImpl or global fetch");
const assembly = options.assembly ?? createHwlabAgentRunDispatchAssembly(options);
const managerUrl = trimTrailingSlash(options.managerUrl ?? assembly.managerUrl);
const run = await postJson(fetchImpl, managerUrl, "/api/v1/runs", assembly.runPayload);
const runId = nonEmptyString(run.id, "run.id");
const command = await postJson(fetchImpl, managerUrl, `/api/v1/runs/${encodeURIComponent(runId)}/commands`, assembly.commandPayload);
const commandId = nonEmptyString(command.id, "command.id");
const runnerJobPayload = { ...assembly.runnerJobPayload, commandId };
const runnerJob = await postJson(fetchImpl, managerUrl, `/api/v1/runs/${encodeURIComponent(runId)}/runner-jobs`, runnerJobPayload);
return {
managerUrl,
run,
command,
runnerJob,
requests: {
runPayload: assembly.runPayload,
commandPayload: assembly.commandPayload,
runnerJobPayload
},
boundaries: assembly.boundaries
};
}
function createSessionRef(options) {
const sessionId = optionalString(options.sessionId);
const conversationId = optionalString(options.conversationId);
const threadId = optionalString(options.threadId);
if (!sessionId && !conversationId && !threadId) return null;
return {
sessionId: sessionId || conversationId || threadId,
...(conversationId ? { conversationId } : {}),
...(threadId ? { threadId } : {}),
metadata: {
source: "hwlab-code-agent",
traceId: optionalString(options.traceId) ?? null
}
};
}
function normalizeTransientEnv(items) {
const seen = new Set();
return items.filter(Boolean).map((item, index) => {
const name = nonEmptyString(item.name, `transientEnv[${index}].name`);
if (!/^[A-Z_][A-Z0-9_]{0,63}$/u.test(name)) throw new Error(`transientEnv[${index}].name must be an uppercase env name`);
if (reusableCredentialEnvNameSet.has(name)) throw new Error(`transientEnv ${name} must use AgentRun tool/provider credential assembly instead`);
if (seen.has(name)) throw new Error(`transientEnv ${name} is duplicated`);
seen.add(name);
return {
name,
value: nonEmptyString(item.value, `transientEnv[${index}].value`),
sensitive: item.sensitive !== false
};
});
}
function transientEnvWithUnideskMainServer(items, unideskMainServerIp) {
if (!unideskMainServerIp) return items;
if (items.some((item) => item?.name === DEFAULT_UNIDESK_MAIN_SERVER_ENV)) return items;
return [...items, { name: DEFAULT_UNIDESK_MAIN_SERVER_ENV, value: unideskMainServerIp, sensitive: false }];
}
function normalizeToolCredentials(items) {
return items.map((item, index) => {
if (!item || typeof item !== "object") throw new Error(`toolCredentials[${index}] must be an object`);
return item;
});
}
async function postJson(fetchImpl, managerUrl, path, payload) {
const response = await fetchImpl(`${managerUrl}${path}`, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify(payload)
});
const text = await response.text();
const body = text ? JSON.parse(text) : null;
if (!response.ok) throw new Error(`AgentRun POST ${path} failed: status=${response.status} body=${JSON.stringify(body).slice(0, 500)}`);
return body;
}
function normalizeBackendProfile(value) {
const profile = nonEmptyString(value, "backendProfile");
if (!backendProfiles.includes(profile)) throw new Error(`unsupported AgentRun backendProfile ${JSON.stringify(profile)}`);
return profile;
}
function fullCommitSha(value) {
const commitId = nonEmptyString(value, "commitId");
if (!/^[0-9a-f]{40}$/u.test(commitId)) throw new Error("commitId must be a full 40-character lowercase git commit sha");
return commitId;
}
function positiveInteger(value, fieldName) {
const parsed = Number(value);
if (!Number.isSafeInteger(parsed) || parsed <= 0) throw new Error(`${fieldName} must be a positive integer`);
return parsed;
}
function nonEmptyString(value, fieldName) {
const text = optionalString(value);
if (!text) throw new Error(`${fieldName} is required`);
return text;
}
function optionalString(value) {
return typeof value === "string" && value.trim() ? value.trim() : null;
}
function trimTrailingSlash(value) {
return nonEmptyString(value, "url").replace(/\/+$/u, "");
}
+119
View File
@@ -0,0 +1,119 @@
import assert from "node:assert/strict";
import test from "node:test";
import {
DEFAULT_UNIDESK_MAIN_SERVER_ENV,
createHwlabAgentRunDispatchAssembly,
dispatchHwlabAgentRun
} from "./agentrun-dispatch.mjs";
const commitId = "8da27c83fa56d87e78e488a819afe898cf97c62b";
test("HWLAB AgentRun assembly grants GitHub and UniDesk SSH through toolCredentials", () => {
const assembly = createHwlabAgentRunDispatchAssembly({
traceId: "trc_hwlab_agentrun_001",
prompt: "检查 HWLAB 工作区并给出状态。",
commitId,
conversationId: "conv_001",
sessionId: "sess_001",
threadId: "thread_001",
unideskMainServerIp: "https://unidesk.example.test"
});
assert.equal(assembly.runPayload.tenantId, "hwlab");
assert.equal(assembly.runPayload.projectId, "pikasTech/HWLAB");
assert.equal(assembly.runPayload.providerId, "G14");
assert.equal(assembly.runPayload.backendProfile, "deepseek");
assert.equal(assembly.runPayload.resourceBundleRef.commitId, commitId);
assert.equal(assembly.commandPayload.payload.traceId, "trc_hwlab_agentrun_001");
assert.equal(assembly.commandPayload.payload.threadId, "thread_001");
const secretScope = assembly.runPayload.executionPolicy.secretScope;
assert.equal(secretScope.allowCredentialEcho, false);
assert.equal(secretScope.providerCredentials[0].profile, "deepseek");
assert.equal(secretScope.providerCredentials[0].secretRef.name, "agentrun-v01-provider-deepseek");
const tools = secretScope.toolCredentials;
assert.equal(tools.some((item) => item.tool === "github" && item.projection.envName === "GH_TOKEN"), true);
assert.equal(tools.some((item) => item.tool === "unidesk-ssh" && item.projection.envName === "UNIDESK_SSH_CLIENT_TOKEN"), true);
const transientEnv = assembly.runnerJobPayload.transientEnv;
assert.equal(transientEnv.find((item) => item.name === DEFAULT_UNIDESK_MAIN_SERVER_ENV)?.value, "https://unidesk.example.test");
assert.equal(transientEnv.some((item) => item.name === "UNIDESK_SSH_CLIENT_TOKEN"), false);
assert.equal(assembly.boundaries.unideskSshCredentialSource, "toolCredentials");
assert.equal(assembly.boundaries.githubCredentialSource, "toolCredentials");
});
test("HWLAB AgentRun assembly rejects reusable credentials in transientEnv", () => {
assert.throws(
() => createHwlabAgentRunDispatchAssembly({
traceId: "trc_hwlab_agentrun_bad_env",
prompt: "bad env",
commitId,
unideskMainServerIp: "https://unidesk.example.test",
transientEnv: [{ name: "UNIDESK_SSH_CLIENT_TOKEN", value: "test-unidesk-ssh-client-token" }]
}),
/must use AgentRun tool\/provider credential assembly/u
);
});
test("HWLAB AgentRun assembly does not duplicate explicit UniDesk main-server env", () => {
const assembly = createHwlabAgentRunDispatchAssembly({
traceId: "trc_hwlab_agentrun_explicit_unidesk",
prompt: "explicit unidesk main server",
commitId,
unideskMainServerIp: "https://unidesk.example.test",
transientEnv: [{ name: DEFAULT_UNIDESK_MAIN_SERVER_ENV, value: "https://explicit.example.test", sensitive: false }]
});
const entries = assembly.runnerJobPayload.transientEnv.filter((item) => item.name === DEFAULT_UNIDESK_MAIN_SERVER_ENV);
assert.equal(entries.length, 1);
assert.equal(entries[0].value, "https://explicit.example.test");
});
test("HWLAB AgentRun assembly requires full commit and main server when UniDesk SSH is enabled", () => {
assert.throws(
() => createHwlabAgentRunDispatchAssembly({ traceId: "trc_bad_commit", prompt: "bad", commitId: "HEAD", unideskMainServerIp: "https://unidesk.example.test" }),
/full 40-character/u
);
assert.throws(
() => createHwlabAgentRunDispatchAssembly({ traceId: "trc_no_unidesk", prompt: "bad", commitId }),
/unideskMainServerIp is required/u
);
});
test("dispatchHwlabAgentRun posts run command and runner job with commandId", async () => {
const requests = [];
const fetchImpl = async (url, init) => {
const request = { url, method: init.method, body: JSON.parse(init.body) };
requests.push(request);
if (url.endsWith("/api/v1/runs")) return jsonResponse({ id: "run_hwlab_001" });
if (url.endsWith("/api/v1/runs/run_hwlab_001/commands")) return jsonResponse({ id: "cmd_hwlab_001" });
if (url.endsWith("/api/v1/runs/run_hwlab_001/runner-jobs")) return jsonResponse({ id: "job_hwlab_001", jobName: "agentrun-v01-runner-selftest" });
return jsonResponse({ error: "unexpected path" }, { status: 404 });
};
const result = await dispatchHwlabAgentRun({
fetchImpl,
traceId: "trc_hwlab_dispatch_001",
prompt: "dispatch smoke",
commitId,
unideskMainServerIp: "https://unidesk.example.test"
});
assert.equal(result.run.id, "run_hwlab_001");
assert.equal(result.command.id, "cmd_hwlab_001");
assert.equal(result.runnerJob.jobName, "agentrun-v01-runner-selftest");
assert.deepEqual(requests.map((item) => new URL(item.url).pathname), [
"/api/v1/runs",
"/api/v1/runs/run_hwlab_001/commands",
"/api/v1/runs/run_hwlab_001/runner-jobs"
]);
assert.equal(requests[2].body.commandId, "cmd_hwlab_001");
assert.equal(requests[2].body.transientEnv.some((item) => item.name === "UNIDESK_SSH_CLIENT_TOKEN"), false);
});
function jsonResponse(body, { status = 200 } = {}) {
return {
ok: status >= 200 && status < 300,
status,
text: async () => JSON.stringify(body)
};
}