dsh-punky-swarm 0.3.6

package/lib/acps/server.js

@@ -0,0 +1,302 @@
+/*
+Copyright (C) 2025-2026 Punky
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+// 文件 server：ACPs 对外 mTLS 服务端点（lib/acps 域，P1 lane exec-acps-server）
+// 契约：
+//   - 独立 HTTPS 监听器（node:https + node:tls，零新依赖），默认端口 9443、绑定 127.0.0.1（config 可配）；
+//   - TLS：minVersion TLSv1.3 + requestCert + rejectUnauthorized（=CERT_REQUIRED + TLSv1_3 语义，
+//     对齐 registry-server/app/main_mtls.py:14-30）；devInsecure 仅显式开发开关（默认 false）；
+//   - 客户端证书 CN 提取 → req.peerAic（对齐 registry-server/app/core/peer_cert.py:18-38）；
+//     受保护端点 AIC 格式校验（复用 lib/aip/identity.js validateAic，对齐 api_atr.py:82-88）；
+//   - 端点：POST /acps/rpc（AIP JSON-RPC，对齐 acps-sdk aip_rpc_model.py:15-57 +
+//     aip_base_model.py TaskCommand/TaskResult 形态）、GET /.well-known/acs.json（ACS 直取，
+//     复用 lib/aip/agent-descriptor.js，对齐 beijing_food/acs.json:15-40）、GET /health
+//     （对齐 demo-partner/partners/main.py:110-121）；
+//   - 路径前缀 /acps/*——与既有 /api/dsh-punky-swarm/*、/.well-known/aip 不冲突；
+//   - 默认关：装配层 enabled=false 时不实例化本模块（零运行时路径）。
+// 纯工厂 + 纯函数，模块顶层零副作用。
+
+import https from 'node:https';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { validateAic } from '../aip/identity.js';
+import { buildAgentDescriptor } from '../aip/agent-descriptor.js';
+import { DEFAULT_ASSEMBLY } from '../assembly.js';
+import { engineVersion } from '../aip/tool-descriptor.js';
+import { ensureAcpsCerts } from './certs.js';
+import { AIP_COMMAND_TYPES as TASK_COMMAND_TYPES, TASK_STATES } from '../comms/aip-format.js';
+
+// ── AIP RPC 常量（对齐参考实现 aip_base_model.py:23-49 / aip_rpc_model.py:15-57）──
+export const JSONRPC_VERSION = '2.0';
+export const RPC_METHOD = 'rpc';
+// TaskCommandType 枚举 / TaskState 枚举：单一源 = lib/comms/aip-format.js（re-export 别名，禁止再自持定义）
+export { TASK_COMMAND_TYPES, TASK_STATES };
+
+// JSON-RPC 2.0 标准错误码（JSON-RPC 2.0 规范；参考实现 JSONRPCError 形态 aip_rpc_model.py:24-29）
+export const RPC_ERRORS = Object.freeze({
+  PARSE: { code: -32700, message: 'Parse error' },
+  INVALID_REQUEST: { code: -32600, message: 'Invalid Request' },
+  METHOD_NOT_FOUND: { code: -32601, message: 'Method not found' },
+  INVALID_PARAMS: { code: -32602, message: 'Invalid params' },
+  INTERNAL: { code: -32603, message: 'Internal error' },
+});
+
+/**
+ * 解析并校验 AIP JSON-RPC 请求信封（aip_rpc_model.py:15-21,41-51 语义）
+ * @param {any} body 已解析的请求体
+ * @returns {{ ok: true, request: object, command: object } | { ok: false, error: { code, message, data? } }}
+ * 校验链：jsonrpc==="2.0" → method==="rpc" → params.command（TaskCommand）存在且
+ * type==="task-command" → command.command ∈ TaskCommandType 枚举（aip_base_model.py:154-164）。
+ */
+export function parseRpcRequest(body) {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+    return { ok: false, error: { ...RPC_ERRORS.INVALID_REQUEST, data: 'body must be a JSON object' } };
+  }
+  if (body.jsonrpc !== JSONRPC_VERSION) {
+    return { ok: false, error: { ...RPC_ERRORS.INVALID_REQUEST, data: 'jsonrpc must be "2.0"' } };
+  }
+  if (body.method !== RPC_METHOD) {
+    return { ok: false, error: { ...RPC_ERRORS.METHOD_NOT_FOUND, data: 'method must be "rpc"' } };
+  }
+  const command = body?.params?.command;
+  if (command === null || typeof command !== 'object' || Array.isArray(command)) {
+    return { ok: false, error: { ...RPC_ERRORS.INVALID_PARAMS, data: 'params.command (TaskCommand) is required' } };
+  }
+  if (command.type !== 'task-command') {
+    return { ok: false, error: { ...RPC_ERRORS.INVALID_PARAMS, data: 'command.type must be "task-command"' } };
+  }
+  if (typeof command.command !== 'string' || !TASK_COMMAND_TYPES.includes(command.command)) {
+    return { ok: false, error: { ...RPC_ERRORS.INVALID_PARAMS, data: 'command.command must be one of: ' + TASK_COMMAND_TYPES.join(', ') } };
+  }
+  return { ok: true, request: body, command };
+}
+
+/**
+ * JSON-RPC 响应信封（aip_rpc_model.py:32-38,54-57：result 或 error 二选一）
+ */
+export function rpcResponse(id, result, error) {
+  const out = { jsonrpc: JSONRPC_VERSION, id: id ?? null };
+  if (error) out.error = error;
+  else out.result = result;
+  return out;
+}
+
+/**
+ * 默认 RPC handler：TaskCommand → TaskResult（state=accepted，TaskState 链首环）
+ * 对齐 aip_base_model.py:167-181（TaskResult: type/taskId/status{state,stateChangedAt}）。
+ * 端点载体与消息形态校验；桥接注入自实现把 command 转 mailbox。
+ * @param {object} command TaskCommand
+ * @param {object} [ctx] { peerAic? }
+ * @returns {object} TaskResult
+ */
+export function defaultRpcHandler(command, ctx = {}) {
+  const now = new Date().toISOString();
+  const taskId = typeof command?.taskId === 'string' && command.taskId.length > 0
+    ? command.taskId
+    : (typeof command?.id === 'string' ? command.id : 'task-' + Date.now().toString(36));
+  const result = {
+    type: 'task-result',
+    id: typeof command?.id === 'string' ? command.id : taskId,
+    sentAt: now,
+    senderRole: 'partner',
+    senderId: ctx?.peerAic ?? 'dsh-punky-swarm',
+    taskId,
+    status: { state: 'accepted', stateChangedAt: now },
+    commandHistory: [command],
+  };
+  return result;
+}
+
+/**
+ * ACS 直取内容生成（/.well-known/acs.json）——复用 lib/aip/agent-descriptor.js（ACS 14 必填键），
+ * 对齐 beijing_food/acs.json:15-40（securitySchemes.mutualTLS + endPoints JSONRPC + certificate.altNames.dns）。
+ * @param {object} config resolveAcpsConfig 输出（endpoint: { aic, host, port }）
+ * @param {object} [opts] { assembly?, engineInfo? }（测试可注入）
+ */
+export function buildAcs(config = {}, opts = {}) {
+  const endpoint = config?.endpoint ?? {};
+  const host = endpoint.host ?? '127.0.0.1';
+  const port = endpoint.port ?? 9443;
+  const assembly = opts.assembly ?? DEFAULT_ASSEMBLY;
+  const engineInfo = opts.engineInfo ?? {};
+  return buildAgentDescriptor(assembly, 'plan', 'coordinator', {
+    ...engineInfo,
+    version: engineInfo.version ?? engineVersion(),
+    aic: endpoint.aic ?? engineInfo.aic ?? `${assembly.team}.plan.coordinator`, // 派生占位；V3 注册后经 config 覆盖
+    // 对齐参考实现 demo acs.json（beijing_food/acs.json:15-40）：
+    // securitySchemes.mutualTLS + endPoints[{url, transport:'JSONRPC', security:[{mtls:[]}]}] + certificate.altNames.dns
+    securitySchemes: {
+      mtls: { type: 'mutualTLS', description: '智能体间mTLS双向认证' },
+    },
+    endPoints: [{
+      url: `https://${host}:${port}/acps/rpc`,
+      transport: 'JSONRPC',
+      security: [{ mtls: [] }],
+    }],
+    certificate: { altNames: { dns: ['localhost'] } },
+    capabilities: { streaming: false, notification: false, messageQueue: [] },
+  });
+}
+
+// 请求体读取（与 lib/api.js readJsonBody 同形态：兼容流式 req 与预置 body）
+function readBody(req) {
+  if (req && typeof req.body === 'string') return Promise.resolve(req.body ? JSON.parse(req.body) : {});
+  if (req && req.body && typeof req.body === 'object') return Promise.resolve(req.body);
+  if (req && typeof req.on === 'function') {
+    return new Promise((resolve, reject) => {
+      let data = '';
+      req.on('data', (c) => { data += c; });
+      req.on('end', () => {
+        try { resolve(data ? JSON.parse(data) : {}); } catch (e) { reject(e); }
+      });
+      req.on('error', reject);
+    });
+  }
+  return Promise.resolve({});
+}
+
+function sendJson(res, status, data) {
+  const body = JSON.stringify(data);
+  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+  res.end(body);
+}
+
+/**
+ * 创建 ACPs 对外 mTLS 服务端点（纯工厂，不自动 listen）
+ * @param {object} opts { config, logger?, acsProvider?, rpcHandler?, healthProvider?, certDir? }
+ *   config = resolveAcpsConfig 输出（endpoint: { port, host, cert, key, ca, certDir, minVersion, devInsecure, aic }）
+ *   acsProvider 缺省 = buildAcs(config)；rpcHandler 缺省 = defaultRpcHandler；
+ *   healthProvider 缺省 = { agent, status:'online', tasks:{active:0}, groups:{active:0} }（partners/main.py:110-121 形态）
+ * @returns {{ server: import('node:https').Server, listen(port?), close(), address(), getPeerAic(req) }}
+ *   证书缺失/不可用时返回 { error }（装配层告警并保持禁用，不阻塞主进程）
+ */
+export function createAcpsServer({ config = {}, logger, acsProvider, rpcHandler, healthProvider, certDir } = {}) {
+  const endpoint = config?.endpoint ?? {};
+  const agentName = endpoint.agentName ?? 'dsh-punky-swarm';
+
+  // ── 证书加载（cert/key/ca 三路径；缺省从 certDir 自动生成——幂等）──
+  let tls;
+  try {
+    const dir = certDir ?? endpoint.certDir;
+    const ca = endpoint.ca ?? (dir ? join(dir, 'ca.pem') : null);
+    if (!endpoint.cert || !endpoint.key || !ca) {
+      if (!dir) return { error: 'acps endpoint: cert/key/ca 三路径均需配置，或提供 certDir 自动生成' };
+      const generated = ensureAcpsCerts({ dir, aic: endpoint.aic });
+      tls = {
+        cert: endpoint.cert ? readFileSync(endpoint.cert) : readFileSync(generated.certFile),
+        key: endpoint.key ? readFileSync(endpoint.key) : readFileSync(generated.keyFile),
+        ca: readFileSync(generated.caFile),
+      };
+    } else {
+      tls = { cert: readFileSync(endpoint.cert), key: readFileSync(endpoint.key), ca: readFileSync(ca) };
+    }
+  } catch (e) {
+    return { error: 'acps endpoint: 证书加载失败——' + e.message };
+  }
+
+  const devInsecure = endpoint.devInsecure === true;
+  const server = https.createServer({
+    key: tls.key,
+    cert: tls.cert,
+    ca: tls.ca,
+    minVersion: endpoint.minVersion ?? 'TLSv1.3', // TLS 最低版本
+    requestCert: true,                            // CERT_REQUIRED 语义（main_mtls.py:28）
+    rejectUnauthorized: devInsecure ? false : true, // 生产不允许降级；开发模式仅显式开启
+    handshakeTimeout: 10_000,
+  }, (req, res) => {
+    handleRequest(req, res).catch((e) => {
+      logger?.warn?.('[dsh-punky-swarm] acps endpoint error: ' + String(e));
+      sendJson(res, 500, rpcResponse(null, null, { ...RPC_ERRORS.INTERNAL, data: String(e.message) }));
+    });
+  });
+
+  // 客户端证书 CN 提取（peer_cert.py:18-38：握手证书 subject.CN = 对端 AIC）
+  function getPeerAic(req) {
+    try {
+      const peer = req.socket?.getPeerCertificate?.();
+      return peer?.subject?.CN ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  async function handleRequest(req, res) {
+    const peerAic = getPeerAic(req);
+    req.peerAic = peerAic; // 注入请求级身份
+    const url = (req.url ?? '').split('?')[0];
+
+    if (req.method === 'GET' && url === '/.well-known/acs.json') {
+      const acs = (acsProvider ? acsProvider() : buildAcs(config)) ?? buildAcs(config);
+      return sendJson(res, 200, acs);
+    }
+    if (req.method === 'GET' && url === '/health') {
+      const health = healthProvider
+        ? healthProvider({ peerAic })
+        : { agent: agentName, status: 'online', tasks: { active: 0 }, groups: { active: 0 } };
+      return sendJson(res, 200, health);
+    }
+    if (req.method === 'POST' && url === '/acps/rpc') {
+      // 应用层身份校验（TLS 通过后）：peer CN 须为合法 AIC 格式（api_atr.py:82-88 validate_aic 400 语义）
+      if (!peerAic || !validateAic(peerAic)) {
+        return sendJson(res, 400, rpcResponse(null, null, { code: 40001, message: 'Invalid client certificate identity: peer CN must be a valid AIC', data: { peerAic: peerAic ?? null } }));
+      }
+      let body;
+      try {
+        body = await readBody(req);
+      } catch {
+        return sendJson(res, 400, rpcResponse(null, null, { ...RPC_ERRORS.PARSE, data: 'invalid JSON body' }));
+      }
+      const parsed = parseRpcRequest(body);
+      if (!parsed.ok) {
+        // JSON-RPC 消息结构非法 → 应用层 400 + JSON-RPC error body（参考实现 pydantic 校验 422 语义映射，允许 4xx）
+        return sendJson(res, 400, rpcResponse(body?.id ?? null, null, parsed.error));
+      }
+      const handler = rpcHandler ?? defaultRpcHandler;
+      const result = await handler(parsed.command, { peerAic, request: parsed.request });
+      return sendJson(res, 200, rpcResponse(parsed.request.id ?? null, result, null));
+    }
+
+    return sendJson(res, 404, { error: 'not-found', path: url });
+  }
+
+  return {
+    server,
+    getPeerAic,
+    // listen：port 覆盖 config（测试用 0=临时端口）；返回 promise（error 事件拒绝）
+    listen(port) {
+      const p = port ?? endpoint.port ?? 9443;
+      return new Promise((resolve, reject) => {
+        const onError = (e) => { server.off('listening', onListening); reject(e); };
+        const onListening = () => { server.off('error', onError); resolve(server.address()); };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(p, endpoint.host ?? '127.0.0.1');
+      });
+    },
+    close() {
+      return new Promise((resolve) => {
+        if (!server.listening) return resolve();
+        server.close(() => resolve());
+        // 长连接兜底
+        server.closeAllConnections?.();
+      });
+    },
+    address() {
+      return server.address();
+    },
+  };
+}

package/lib/aip/agent-descriptor.js

@@ -0,0 +1,170 @@
+/*
+Copyright (C) 2025-2026 Punky
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+// 文件 agent-descriptor：国标 P4（GB/Z 185.4-2026《智能体描述》）描述生成器
+// 契约：纯函数——输入装配配置（team/layer/role/skills）+ 引擎信息，输出每 role 一份描述 JSON；
+//       零副作用、不消费运行时、可单测。
+// ⚠ 2026-08 校准（覆盖旧 14+8 口径）：字段集以 ACS（Agent Capability Specification）原文为准——
+//   registry-server/app/agent/acsSchema.json（JSON Schema 全文）为逐字字段来源；
+//   旧「14+8 兼容映射层」（toLegacyDescriptor / toLegacySkill + ALL_TOOLS / LAYER_CAPABILITIES）
+//   已移除（P2-06）：ACPs 兼容路径中无调用——ACPs 描述直接消费 buildAgentDescriptor 的 ACS 格式
+//   （server.js:37,136 装配），描述以 ACS 格式为准。
+// 派生值标记：固定值 = 本文件推导；预留 = 后续填充。
+// 仅用内建能力，零新增依赖（红线：不改 node_modules）。
+import { engineVersion } from './tool-descriptor.js';
+
+// ACPs 协议版本（acsSchema.json examples：["02.01"]）
+export const ACS_PROTOCOL_VERSION = '02.01';
+
+// ACS AgentCapabilitySpec 必填 14 键（acsSchema.json required 数组原文）
+export const ACS_REQUIRED_FIELDS = Object.freeze([
+  'aic', 'active', 'lastModifiedTime', 'protocolVersion', 'name', 'description',
+  'version', 'provider', 'securitySchemes', 'endPoints', 'capabilities',
+  'defaultInputModes', 'defaultOutputModes', 'skills',
+]);
+
+// ACS AgentCapabilitySpec 可选键（acsSchema.json properties 全集 − required）
+export const ACS_OPTIONAL_FIELDS = Object.freeze([
+  'iconUrl', 'documentationUrl', 'webAppUrl', 'entityUserId', 'entityMeta', 'certificate',
+]);
+
+// ACS AgentSkill 必填 5 键（acsSchema.json $defs.AgentSkill required 数组原文）
+export const ACS_SKILL_REQUIRED_FIELDS = Object.freeze(['id', 'name', 'description', 'version', 'tags']);
+
+// ACS AgentSkill 可选键
+export const ACS_SKILL_OPTIONAL_FIELDS = Object.freeze(['examples', 'inputModes', 'outputModes']);
+
+/**
+ * 单技能 → ACS AgentSkill（8 字段，逐字名见 acsSchema.json $defs.AgentSkill）
+ * 必填 5 键恒输出；可选 3 键（examples/inputModes/outputModes）仅在提供时输出（对齐参考实现
+ * demo acs.json 风格——真实数据才带，不臆造空数组）。
+ * @param {string} skillName 技能名（= assembly.skills[role] 中的名字，如 'dev-coder'）
+ * @param {object} [meta] SKILL.md front matter 解析子集：
+ *   { description?, version?, tags?, examples?, inputModes?, outputModes?, id? }
+ * @param {object} [engineInfo] { version? } 引擎信息（技能 version 缺省回退用）
+ * @returns {object} ACS AgentSkill
+ */
+export function buildSkillDescriptor(skillName, meta = {}, engineInfo = {}) {
+  const version = meta.version ?? engineInfo.version ?? engineVersion();
+  const skill = {
+    id: meta.id ?? `dsh.skill.${skillName}`, // 派生：与 toolId 同风格（旧口径同规则）；meta.id 可覆盖
+    name: skillName,                          // 透传（= 装配技能名）
+    description: meta.description ?? skillName, // 透传 front matter description
+    version,                                  // front matter version ?? 引擎版本
+    tags: Array.isArray(meta.tags) ? [...meta.tags] : [], // front matter tags ?? 空数组（必填键恒在）
+  };
+  for (const k of ACS_SKILL_OPTIONAL_FIELDS) {
+    if (meta[k] !== undefined && meta[k] !== null) skill[k] = meta[k];
+  }
+  return skill;
+}
+
+/**
+ * 装配角色 → ACS AgentCapabilitySpec（Agent 描述，逐字字段名见 acsSchema.json 根对象）
+ * 必填 14 键恒输出（值取诚实推导默认，可经 engineInfo 覆盖）；可选 6 键仅在提供时输出。
+ * 派生值说明（诚实标注，spec §3.2）：
+ * - aic：注册服务分配的 OID 身份码——本引擎无 ARSP 注册，输出派生占位 `${team}.${layer}.${role}`，
+ *   真实 AIC 需按 spec §3.4（10 级编码 + CRC-16 校验）由注册服务分配后经 engineInfo.aic 覆盖；
+ * - active：默认 true（引擎装配角色即可用），engineInfo.active 可覆盖；
+ * - lastModifiedTime：ISO 8601；engineInfo.lastModifiedTime ?? engineInfo.generatedAt ?? 当前时刻；
+ * - provider：{ countryCode: 'CN', organization: owner ?? 'dsh' }（AgentProvider 全可选字段）；
+ * - securitySchemes：默认 {}（引擎 agent 经本地文件 mailbox 通信、无网络认证声明；接入真实
+ *   端点时经 engineInfo.securitySchemes 注入，如 mutualTLS）；
+ * - endPoints：默认 []（引擎 agent 非网络服务端点；接入时经 engineInfo.endPoints 注入）；
+ * - capabilities：默认 { streaming:false, notification:false, messageQueue:[] }（如实：无 SSE/
+ *   异步推送/MQ），engineInfo.capabilities 可覆盖；
+ * - defaultInputModes / defaultOutputModes：默认 ['text/plain','application/json']（指令文本 +
+ *   JSON 参数/回执，引擎 mailbox/工具层实际承载格式）。
+ * @param {object} assembly 装配配置 { team, layers: { <layer>: { roles: string[], skills: { [role]: string[] } } }, owner? }
+ * @param {string} layer 层名（plan/exec/audit）
+ * @param {string} role 角色名（如 'coder'）
+ * @param {object} [engineInfo] ACS 覆盖 + 引擎信息：
+ *   { version?, owner?, skillMeta?, generatedAt?, aic?, active?, lastModifiedTime?, protocolVersion?,
+ *     iconUrl?, documentationUrl?, webAppUrl?, provider?, securitySchemes?, endPoints?,
+ *     capabilities?, defaultInputModes?, defaultOutputModes?, entityUserId?, entityMeta?, certificate? }
+ *   skillMeta: { [skillName]: { description?, version?, tags?, examples?, inputModes?, outputModes? } }
+ * @returns {object} ACS AgentCapabilitySpec
+ */
+export function buildAgentDescriptor(assembly, layer, role, engineInfo = {}) {
+  const team = assembly.team ?? 'generic';
+  const layerCfg = assembly.layers?.[layer];
+  const skillNames = Array.isArray(layerCfg?.skills?.[role]) ? layerCfg.skills[role] : [];
+  const skillMetaMap = engineInfo.skillMeta ?? {};
+  const skills = skillNames.map((name) => buildSkillDescriptor(name, skillMetaMap[name] ?? {}, engineInfo));
+  // description：取 skills[0] 对应 SKILL.md description；无则用 role 名
+  const description = skills[0]?.description ?? role;
+  const owner = assembly.owner ?? engineInfo.owner ?? 'dsh';
+
+  const descriptor = {
+    aic: engineInfo.aic ?? `${team}.${layer}.${role}`, // 派生占位；真实 AIC 需注册服务分配（见上）
+    active: engineInfo.active ?? true,
+    lastModifiedTime: engineInfo.lastModifiedTime ?? engineInfo.generatedAt ?? new Date().toISOString(),
+    protocolVersion: engineInfo.protocolVersion ?? ACS_PROTOCOL_VERSION,
+    name: role,                                        // 透传（= 角色名）
+    description,                                       // 首技能 SKILL.md description ?? role 名
+    version: engineInfo.version ?? engineVersion(),    // 引擎版本，可被 config 覆盖
+    provider: engineInfo.provider ?? { countryCode: 'CN', organization: owner }, // AgentProvider 派生
+    securitySchemes: engineInfo.securitySchemes ?? {}, // 默认空（如实：无网络认证声明）
+    endPoints: engineInfo.endPoints ?? [],             // 默认空数组（schema default）
+    capabilities: engineInfo.capabilities ?? { streaming: false, notification: false, messageQueue: [] },
+    defaultInputModes: engineInfo.defaultInputModes ?? ['text/plain', 'application/json'],
+    defaultOutputModes: engineInfo.defaultOutputModes ?? ['text/plain', 'application/json'],
+    skills,                                            // assembly.skills[role] 的 ACS AgentSkill 数组
+  };
+  for (const k of ACS_OPTIONAL_FIELDS) {
+    if (engineInfo[k] !== undefined && engineInfo[k] !== null) descriptor[k] = engineInfo[k];
+  }
+  return descriptor;
+}
+
+/**
+ * 装配配置 → 全部角色的 ACS AgentCapabilitySpec 列表（主入口）
+ * 遍历 assembly.layers[*].roles[*]，每 role 生成一份描述
+ * @param {object} assembly 装配配置（见 buildAgentDescriptor）
+ * @param {object} [engineInfo]（见 buildAgentDescriptor）
+ * @returns {Array<object>} 每 role 一份 ACS AgentCapabilitySpec
+ */
+export function buildAgentDescriptors(assembly, engineInfo = {}) {
+  const layers = assembly?.layers ?? {};
+  const descriptors = [];
+  for (const layer of Object.keys(layers)) {
+    const roles = layers[layer]?.roles ?? [];
+    for (const role of roles) {
+      descriptors.push(buildAgentDescriptor(assembly, layer, role, engineInfo));
+    }
+  }
+  return descriptors;
+}
+
+/**
+ * 智能体描述目录快照（对齐 buildToolCatalog 形态）：持有全量 ACS 描述 + 只读 list()；
+ * 供 register.js 按 aip.enabled 门控生成、api.js 挂 /agents 只读端点。
+ * @param {object} assembly 装配配置
+ * @param {object} [engineInfo]（见 buildAgentDescriptor；建议传 generatedAt 固定 lastModifiedTime）
+ * @returns {{ generatedAt: string, descriptors: ReadonlyArray<object>, list(): object[] }}
+ */
+export function buildAgentCatalog(assembly, engineInfo = {}) {
+  const descriptors = buildAgentDescriptors(assembly, engineInfo);
+  return {
+    generatedAt: engineInfo.generatedAt ?? new Date().toISOString(),
+    descriptors: Object.freeze(descriptors),
+    list() {
+      return descriptors.slice();
+    },
+  };
+}
+