Proposal: built-in zcode engine support + two custom-engine adapter pitfalls (working adapter attached)

Aperta
#377 3 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
45/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
javascript, node.js

Direzione di ricerca

Start with docs/design/custom-engine.md and compare its integration checklist and timeout diagnostics with the two adapter pitfalls described here. Then review the qwen_code and qodercli engine integrations as entry points for assessing built-in zcode support. Done means the documentation addresses stdin, interactive approvals, and timeout output, and the project has a clear decision on whether to add a built-in engine.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

背景

在 Windows 10 x64、skill-up v0.14.0 上,我们用 custom engine(local transport)为 ZCode CLI(一个 Claude Code 形态的编码智能体 CLI,具备 -p 无头模式 / --json 结构化输出 / --resume <session_id> 多轮 / --cwd / --mode <mode> 权限档 / --disallowed-tools)写了一个约 110 行的 Node 适配器,成功对一个真实的多文件编排技能(入口分流 + 模式文档路由)跑通 stateful 两轮评测并出判分(1 单轮用例 PASS、1 两轮用例完成 4 项断言判定)。

过程中踩到两个对 custom engine 适配器作者有普适价值的坑,另外提一个功能建议。

坑 1:适配器子进程的 stdin 必须置空(ignore),否则部分 agent CLI 会挂死到超时

Node spawnSync 默认给子进程接 stdin 管道。ZCode 在部分调用路径下会把"stdin 是打开的管道"当作"等待用户输入",一直阻塞直到超时——表现为 spawnSync node ETIMEDOUT、无任何输出,非常难排查。把 stdio 设为 ['ignore', 'pipe', 'pipe'] 后问题消失。

建议:在 docs/design/custom-engine.md 的 integration checklist 里加一条——local 适配器应将子进程 stdin 置空/关闭,除非协议本身需要经 stdin 传帧(如 ACP)。

坑 2:无头环境下 agent 的交互式审批/问询会永久阻塞,且极具迷惑性

被测 agent 处于需要审批的模式时(如 ZCode 的 --mode plan 计划审批、AskUserQuestion 问询框),无头调用没有任何人应答,整轮挂死到超时。迷惑性在于:简单直答的用例能正常通过,只有触发技能流程/审批点的用例才挂,容易误判为"任务太慢"。

建议:文档提示 custom engine 用户在评测时让 agent 跑在最自治的权限档(我们用 --mode yolo + --disallowed-tools AskUserQuestion,配合一次性评测工作区控制风险);并考虑在 custom engine 超时诊断里保留子进程被杀前的 stdout 尾部(我们在适配器里自行实现了,对定位帮助很大)。

功能建议:内置 zcode 引擎

ZCode CLI 的无头能力与内置引擎(qwen_code/qodercli)高度同构,接入成本很低:

能力 ZCode CLI
单轮无头 zcode -p "<prompt>" --json
结构化输出 --json → { sessionId, response, usage: { inputTokens, outputTokens }, ... }
多轮 --resume <sess_xxx>(stateful)
工作目录 --cwd <dir>
权限档 --mode build|edit|plan|yolo|guarded(-p 默认 yolo)
工具裁剪 --disallowed-tools <tools...>

已验证可用的适配器参考实现见下方附录;如有意向,我们可以整理成 PR。

附录:适配器参考实现(zcode-runner.mjs,stateful)

#!/usr/bin/env node
// skill-up 自定义引擎适配器:把 zcode CLI 无头模式包装成 SessionInput/SessionResult 契约。
// 用法:node zcode-runner.mjs --input <input.json> --output <result.json>
// 契约:stateful 模式下每次调用只带一条用户消息;续轮经 input.session_id → zcode --resume。
import fs from 'node:fs';
import path from 'node:path';
import { spawnSync } from 'node:child_process';

function argValue(name) {
  const i = process.argv.indexOf(name);
  return i >= 0 ? process.argv[i + 1] : null;
}

const inputPath = argValue('--input');
const outputPath = argValue('--output');
if (!inputPath || !outputPath) {
  console.error('usage: zcode-runner.mjs --input <file> --output <file>');
  process.exit(2);
}

const request = JSON.parse(fs.readFileSync(path.resolve(inputPath), 'utf8'));
const workspace = path.resolve(String(request.workspace || process.cwd()));
const messages = Array.isArray(request.messages) ? request.messages : [];
const prompt = messages
  .filter((m) => m && m.role === 'user')
  .map((m) => String(m.content ?? ''))
  .join('\n');

const cli = process.env.ZCODE_CLI || 'D:\\Program Files\\ZCode\\resources\\glm\\zcode.cjs';
const nodeBin = process.env.ZCODE_NODE || 'node';
const mode = process.env.ZCODE_MODE || 'plan';
const resumeId = String(request.session_id || '');
const timeoutSec = Number(request.timeout_seconds || 300);

const args = [cli, '-p', prompt, '--json', '--mode', mode, '--cwd', workspace];
if (resumeId) args.push('--resume', resumeId);
// 无头评测没有人在问询框前答题:禁用 AskUserQuestion,逼 AI 用文字提问
const disallow = process.env.ZCODE_DISALLOW !== undefined ? process.env.ZCODE_DISALLOW : 'AskUserQuestion';
if (disallow && disallow !== 'off') args.push('--disallowed-tools', disallow);

const run = spawnSync(nodeBin, args, {
  cwd: workspace,
  encoding: 'utf8',
  timeout: Math.max(10000, timeoutSec * 1000 - 5000),
  windowsHide: true,
  env: process.env,
  // 关键:子进程 stdin 必须为空。默认管道会让 zcode 在部分路径下等输入挂死到超时。
  stdio: ['ignore', 'pipe', 'pipe'],
});

const text = String(run.stdout || '');
let parsed = null;
try {
  parsed = JSON.parse(text.trim());
} catch {
  const s = text.indexOf('{');
  const e = text.lastIndexOf('}');
  if (s >= 0 && e > s) {
    try {
      parsed = JSON.parse(text.slice(s, e + 1));
    } catch {
      parsed = null;
    }
  }
}

const spawnProblem = run.error ? `spawn error: ${run.error.message}` : null;
const stdoutHead = String(run.stdout || '').slice(-600);
const finalMessage =
  parsed && typeof parsed.response === 'string' && parsed.response.length > 0
    ? parsed.response
    : spawnProblem ||
      `zcode runner failed: exit=${run.status} stderr=${String(run.stderr || '').slice(0, 400)} stdout_tail=${stdoutHead}`;

const transcript = [];
let turn = 1;
for (const m of messages) {
  const role = String(m?.role || 'user');
  if (role === 'user' && transcript.length > 0) turn += 1;
  transcript.push({ role, content: String(m?.content ?? ''), turn });
}
transcript.push({ role: 'assistant', content: finalMessage, turn });

const result = {
  exit_code: run.status === 0 && parsed ? 0 : (typeof run.status === 'number' && run.status !== null ? run.status : 1),
  final_message: finalMessage,
  session_id: (parsed && parsed.sessionId) || resumeId || '',
  transcript,
  input_tokens: (parsed && parsed.usage && parsed.usage.inputTokens) || 0,
  output_tokens: (parsed && parsed.usage && parsed.usage.outputTokens) || 0,
  turns: 1,
};

fs.mkdirSync(path.dirname(path.resolve(outputPath)), { recursive: true });
fs.writeFileSync(path.resolve(outputPath), JSON.stringify(result, null, 2), 'utf8');
process.exit(0);
Lingua principale
Go
Stelle
1.5k
Fork
134
Merge medio
1g 22h
PR unite (30g)
61

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di alibaba/skill-up

Tutte le issue di alibaba/skill-up

Issue simili

Altre issue su Go

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.