@xyagent/cli 0.0.1

package/src-ext/runtime/_shared/todoTranslatorUtils.mjs

@@ -0,0 +1,94 @@
+/**
+ * todoTranslatorUtils.mjs — TODO translator 共享工具函数
+ *
+ * 按 translator-spec.md 实现：
+ *   - splitTitleDescription(text)   按优先级切分 title/description
+ *   - normalizeStatus(raw)          camelCase → snake_case + 兜底 pending
+ *   - buildTodoItems(rawItems)      数组归一化
+ */
+
+// ── splitTitleDescription ────────────────────────────────────────────────────
+
+// 分隔符按优先级排列：全角冒号 > 半角冒号 > 破折号 > 带空格短横线
+const SEPARATORS = [
+  "：", // ：全角冒号 U+FF1A
+  ":",      // 半角冒号 U+003A
+  "—", // — 破折号 U+2014
+  " - ",    // 带空格短横线
+];
+
+/**
+ * 按 translator-spec.md §6 的优先级切分 title/description。
+ *
+ * @param {string} text
+ * @returns {{ title: string, description?: string }}
+ */
+export function splitTitleDescription(text) {
+  if (typeof text !== "string") {
+    return { title: String(text ?? "") };
+  }
+  for (const sep of SEPARATORS) {
+    const idx = text.indexOf(sep);
+    if (idx === -1) continue;
+    const title = text.slice(0, idx).trim();
+    const description = text.slice(idx + sep.length).trim();
+    // 若切分后 title 为空字符串，视为无匹配（规则 §6.3）
+    if (!title) continue;
+    const result = { title };
+    if (description) result.description = description;
+    return result;
+  }
+  return { title: text.trim() };
+}
+
+// ── normalizeStatus ──────────────────────────────────────────────────────────
+
+const VALID_STATUSES = new Set(["pending", "in_progress", "completed", "cancelled"]);
+
+/**
+ * 归一化 status 值：
+ *   - 已是 snake_case 合法值：原样返回
+ *   - camelCase（如 inProgress）→ snake_case
+ *   - 未知值 → "pending"
+ *
+ * @param {string|null|undefined} raw
+ * @returns {"pending"|"in_progress"|"completed"|"cancelled"}
+ */
+export function normalizeStatus(raw) {
+  if (typeof raw !== "string" || !raw) return "pending";
+  // 已是合法 snake_case
+  if (VALID_STATUSES.has(raw)) return raw;
+  // camelCase → snake_case（只处理已知 Codex 值）
+  if (raw === "inProgress") return "in_progress";
+  // 其余未知值兜底
+  return "pending";
+}
+
+// ── buildTodoItems ───────────────────────────────────────────────────────────
+
+/**
+ * 从原始 item 数组构造归一化 TodoItem[]。
+ *
+ * rawItems 中每项支持字段：
+ *   - id?:         string（有则保留，无则生成 td_{idx}）
+ *   - content?:    string（主内容字段，Claude/Hermes 用）
+ *   - step?:       string（Codex/picoclaw 用，作为 content 的 fallback）
+ *   - status?:     string（经 normalizeStatus 归一）
+ *
+ * @param {Array<{id?: string, content?: string, step?: string, status?: string}>} rawItems
+ * @returns {Array<{id: string, title: string, description?: string, status: string, order: number}>}
+ */
+export function buildTodoItems(rawItems) {
+  if (!Array.isArray(rawItems)) return [];
+  return rawItems.map((item, idx) => {
+    const id = typeof item?.id === "string" && item.id ? item.id : `td_${idx}`;
+    const contentText = typeof item?.content === "string"
+      ? item.content
+      : (typeof item?.step === "string" ? item.step : "");
+    const { title, description } = splitTitleDescription(contentText);
+    const status = normalizeStatus(item?.status);
+    const result = { id, title, status, order: idx };
+    if (description !== undefined) result.description = description;
+    return result;
+  });
+}

package/src-ext/runtime/claude/askUserQuestionTranslator.mjs

@@ -0,0 +1,241 @@
+/**
+ * askUserQuestionTranslator.mjs — AskUserQuestion tool_use 拦截器
+ *
+ * 在 handleRequest.mjs 的 onObject 回调里、todoTranslator.intercept(ev) 之后
+ * 插入此拦截点。
+ *
+ * 拦截逻辑：
+ *   - kind === "tool_use" && name === "AskUserQuestion" → 翻译为 N 个 interrupt block + batch 元信息
+ *   - 同 tool_id 的 tool_use_end → 静默消费
+ *   - 其余事件 → 返回 null（调用方继续走既有翻译链）
+ *
+ * 返回值约定：
+ *   - null                            → 不拦截，调用方自行处理
+ *   - { toolId, questions, batchGroupId, blocks }  → AskUserQuestion 被拦截
+ *   - { consumed: true }              → tool_use_end 被吞噬
+ */
+
+// ULID-style suffix（复用 envelope_builder 风格，但不导入依赖，避免循环引用）
+const CROCKFORD_CHARS = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+function newCrockfordSuffix() {
+  const bytes = new Uint8Array(16);
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    crypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  let n = BigInt(0);
+  for (const b of bytes) n = (n << BigInt(8)) | BigInt(b);
+  const chars = [];
+  for (let i = 0; i < 26; i++) {
+    chars.unshift(CROCKFORD_CHARS[Number(n & BigInt(31))]);
+    n >>= BigInt(5);
+  }
+  return chars.join("");
+}
+
+function newWizId() {
+  return "wiz_" + newCrockfordSuffix();
+}
+
+function newBlockId() {
+  return "blk_" + newCrockfordSuffix();
+}
+
+/**
+ * 将 option label 归一化为稳定的 id slug。
+ * 规则：全小写，非字母数字替换为连字符，合并连续连字符，去首尾。
+ *
+ * @param {string} label
+ * @returns {string}
+ */
+function slugify(label) {
+  return String(label)
+    .toLowerCase()
+    .replace(/[^\w一-鿿]+/g, "-") // 非词字符（保留中文）→ -
+    .replace(/-+/g, "-")                   // 合并连续 -
+    .replace(/^-|-$/g, "");                // 去首尾 -
+}
+
+/**
+ * 将单个 AskUserQuestion question 对象映射为 interrupt block 字段。
+ *
+ * @param {{ question: string, header?: string, options?: Array, multiSelect?: boolean }} q
+ * @param {{ batchGroupId: string, batchIndex: number, batchTotal: number }} batch
+ * @returns {object}  interrupt block（不含 id，由调用方在 buildBlockStarted 时填充）
+ */
+function mapQuestionToBlock(q, { batchGroupId, batchIndex, batchTotal }) {
+  const rawOptions = Array.isArray(q.options) ? q.options : [];
+  const hasOptions = rawOptions.length > 0;
+
+  const options = hasOptions
+    ? rawOptions.map((o) => ({
+        id: slugify(o.label || ""),
+        label: o.label || "",
+        ...(o.description !== undefined ? { description: o.description } : {}),
+      }))
+    : [];
+
+  const selectionMode = q.multiSelect === true ? "multi" : "single";
+
+  const block = {
+    type: "interrupt",
+    subtype: "question",
+    prompt: q.question || "",
+    options,
+    selection_mode: selectionMode,
+    // id 由调用方（handleRequest）在 buildBlockStarted 时确定，这里提前生成
+    id: newBlockId(),
+  };
+
+  // 单问题（batchTotal=1）省略 batch 三字段与 title：App 端快捷路径守卫
+  // （title/batch 均为 null 时）命中 BrandChoiceCard 裸卡，与 /resume 选择卡
+  // 同样式；否则会套标准容器渲染「步骤 1/1」进度条 + 重复 prompt。
+  // 多问题才需要向导式进度与每步标题。
+  if (batchTotal > 1) {
+    block.batch_group_id = batchGroupId;
+    block.batch_index = batchIndex;
+    block.batch_total = batchTotal;
+    if (q.header !== undefined && q.header !== null) {
+      block.title = q.header;
+    }
+  }
+
+  // 无 options → 自由输入模式
+  if (!hasOptions) {
+    block.free_text = { enabled: true, required: true };
+  }
+
+  return block;
+}
+
+/**
+ * 将 resume 决策值数组聚合为 Claude 期望的 answers map。
+ *
+ * answers key 为 question 原文，value 为：
+ *   - free_text_response 非空 → 该文本（优先）
+ *   - option_id → 反查 optionMaps[i] 中对应 label
+ *   - selected_option_ids → label 数组
+ *
+ * @param {Array<{question: string, options?: Array, multiSelect?: boolean}>} questions  原始问题数组
+ * @param {Array<object>} resumeValues  每个 block 的 resume value，与 questions 一一对应
+ * @param {Array<Record<string, string>>} optionMaps  每题的 id→label 映射
+ * @returns {Record<string, string|string[]>}
+ */
+export function aggregateAnswers(questions, resumeValues, optionMaps) {
+  const answers = {};
+  for (let i = 0; i < questions.length; i++) {
+    const q = questions[i];
+    const value = resumeValues[i] ?? {};
+    const map = optionMaps?.[i] ?? {};
+
+    const key = q.question;
+
+    // free_text_response 优先
+    if (value.free_text_response && typeof value.free_text_response === "string" && value.free_text_response.trim()) {
+      answers[key] = value.free_text_response;
+      continue;
+    }
+
+    // 多选：selected_option_ids → label 数组
+    if (Array.isArray(value.selected_option_ids)) {
+      answers[key] = value.selected_option_ids.map((id) => map[id] ?? id);
+      continue;
+    }
+
+    // 单选：option_id → label
+    if (value.option_id && typeof value.option_id === "string") {
+      answers[key] = map[value.option_id] ?? value.option_id;
+      continue;
+    }
+
+    // fallback：空字符串
+    answers[key] = "";
+  }
+  return answers;
+}
+
+/**
+ * 将 blocks 的 option id→label 映射提取为 optionMaps 数组。
+ *
+ * @param {Array<{options?: Array<{id: string, label: string}>}>} blocks
+ * @returns {Array<Record<string, string>>}
+ */
+export function buildOptionMaps(blocks) {
+  return blocks.map((block) => {
+    const map = {};
+    for (const opt of (block.options ?? [])) {
+      if (opt.id && opt.label) map[opt.id] = opt.label;
+    }
+    return map;
+  });
+}
+
+/**
+ * 创建 AskUserQuestion translator 实例。
+ *
+ * @param {{ log: any, runId: string }} opts
+ * @returns {{ intercept(ev: object): object|null }}
+ */
+export function createAskUserQuestionTranslator({ log, runId }) {
+  // 已拦截的 tool_id 集合，用于静默消费对应的 tool_use_end
+  const interceptedIds = new Set();
+
+  return {
+    /**
+     * @param {object} ev  normalized event（kind + payload）
+     * @returns {{ toolId, questions, batchGroupId, blocks } | { consumed: true } | null}
+     */
+    intercept(ev) {
+      if (!ev || typeof ev !== "object") return null;
+
+      // ── 拦截 AskUserQuestion tool_use ───────────────────────────────
+      if (ev.kind === "tool_use" && ev.payload?.name === "AskUserQuestion") {
+        const toolId = ev.payload.tool_id || null;
+        const questions = ev.payload?.input?.questions;
+
+        // 畸形 input：questions 缺失/非数组/空数组 → 不拦截
+        if (!Array.isArray(questions) || questions.length === 0) {
+          return null;
+        }
+
+        if (toolId) interceptedIds.add(toolId);
+
+        const batchGroupId = newWizId();
+        const batchTotal = questions.length;
+
+        const blocks = questions.map((q, idx) =>
+          mapQuestionToBlock(q, {
+            batchGroupId,
+            batchIndex: idx,
+            batchTotal,
+          }),
+        );
+
+        log?.info?.(
+          "claude.ask_user_question.intercepted",
+          "AskUserQuestion intercepted",
+          {
+            tool_id: toolId,
+            question_count: questions.length,
+            batch_group_id: batchGroupId,
+          },
+        );
+
+        return { toolId, questions, batchGroupId, blocks };
+      }
+
+      // ── 静默消费已拦截的 tool_use_end ─────────────────────────────
+      if (ev.kind === "tool_use_end") {
+        const toolId = ev.payload?.tool_id;
+        if (toolId && interceptedIds.has(toolId)) {
+          return { consumed: true };
+        }
+      }
+
+      // 其他事件不拦截
+      return null;
+    },
+  };
+}

package/src-ext/runtime/claude/customCommandsCollector.mjs

@@ -0,0 +1,132 @@
+/**
+ * customCommandsCollector.mjs — claude 自定义命令收集器
+ *
+ * collectCustomCommands({init, cwd, _homeDir?})
+ *   → Promise<Array<{command, description, argumentHint, kind}>>
+ *
+ * 算法：
+ *   1. 取 init.slash_commands 中不在内置命令名集中的条目（差集）
+ *   2. 对差集中每条 bare name 尝试按优先级补充元数据：
+ *      a. <cwd>/.claude/commands/<bare>.md
+ *      b. ~/<.claude>/commands/<bare>.md
+ *      c. ~/<.claude>/skills/<bare>/SKILL.md
+ *   3. 解析失败 / 文件不存在时静默兜底（description=""，argumentHint=null）
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import {
+  CLAUDE_CLI_HANDLED,
+  CLAUDE_PROMPT_REWRITES,
+  CLAUDE_HANDLERS,
+} from "./internalCommandNames.mjs";
+
+// ── 内置命令名集（差集基准）────────────────────────────────────────────────────
+// 这三个集合已从 slashCommandRouter.mjs 同步到独立模块，避免循环依赖。
+function buildBuiltinSet() {
+  const s = new Set();
+  for (const cmd of CLAUDE_CLI_HANDLED) s.add(cmd.replace(/^\//, ""));
+  for (const cmd of Object.keys(CLAUDE_PROMPT_REWRITES)) s.add(cmd.replace(/^\//, ""));
+  for (const cmd of Object.keys(CLAUDE_HANDLERS)) {
+    const bare = cmd.replace(/^\//, "");
+    if (bare && bare !== "__default__") s.add(bare);
+  }
+  return s;
+}
+
+const _builtinNames = buildBuiltinSet();
+
+// ── frontmatter 解析 ─────────────────────────────────────────────────────────
+/**
+ * 从 Markdown 头部 `---\n...\n---` 块提取 YAML-like 的 key: value 字段。
+ * 只支持单行值（不支持多行 YAML），失败不 throw。
+ */
+function parseFrontmatter(content) {
+  if (typeof content !== "string") return {};
+  const m = /^---\n([\s\S]*?)\n---/.exec(content);
+  if (!m) return {};
+  const result = {};
+  for (const line of m[1].split("\n")) {
+    const idx = line.indexOf(":");
+    if (idx < 0) continue;
+    const key = line.slice(0, idx).trim();
+    const val = line.slice(idx + 1).trim();
+    if (key) result[key] = val;
+  }
+  return result;
+}
+
+function safeReadFrontmatter(filePath) {
+  try {
+    const content = readFileSync(filePath, "utf8");
+    return parseFrontmatter(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 从 frontmatter 中提取 description 和 argumentHint。
+ * argument-hint 和 argumentHint 两种写法均识别。
+ */
+function extractMeta(fm) {
+  if (!fm) return null;
+  const description = fm["description"] ?? "";
+  const argumentHint = fm["argument-hint"] ?? fm["argumentHint"] ?? null;
+  return { description: String(description), argumentHint: argumentHint ? String(argumentHint) : null };
+}
+
+// ── 主函数 ────────────────────────────────────────────────────────────────────
+
+/**
+ * @param {{
+ *   init: object|null,
+ *   cwd: string,
+ *   _homeDir?: string,   // 测试注入：替代 homedir()
+ * }} opts
+ * @returns {Promise<Array<{command:string, description:string, argumentHint:string|null, kind:string}>>}
+ */
+export async function collectCustomCommands({ init, cwd, _homeDir } = {}) {
+  if (!init || !Array.isArray(init.slash_commands)) {
+    return [];
+  }
+
+  const home = _homeDir || homedir();
+  const result = [];
+
+  for (const entry of init.slash_commands) {
+    const bare = String(entry).toLowerCase().replace(/^\//, "");
+    if (!bare) continue;
+    // 差集：内置命令跳过
+    if (_builtinNames.has(bare)) continue;
+
+    // 尽力补充元数据（按优先级）
+    const candidates = [
+      join(cwd, ".claude", "commands", `${bare}.md`),
+      join(home, ".claude", "commands", `${bare}.md`),
+      join(home, ".claude", "skills", bare, "SKILL.md"),
+    ];
+
+    let meta = null;
+    for (const candidate of candidates) {
+      if (!existsSync(candidate)) continue;
+      const fm = safeReadFrontmatter(candidate);
+      const extracted = extractMeta(fm);
+      if (extracted) {
+        meta = extracted;
+        break;
+      }
+    }
+
+    result.push({
+      command: `/${bare}`,
+      description: meta?.description ?? "",
+      argumentHint: meta?.argumentHint ?? null,
+      kind: "custom",
+    });
+  }
+
+  return result;
+}