nolo-cli 0.1.8 → 0.1.10

package/ai/skills/referenceRuntime.ts

@@ -0,0 +1,274 @@
+import { resolvePageSkillMetadata } from "./skillDocProtocol";
+import { canonicalizeToolNames } from "ai/tools/toolNameAliases";
+
+export type SkillRuntimePageLike = {
+  dbKey?: string;
+  title?: string;
+  content?: string | null;
+  meta?: unknown;
+  tools?: string[];
+} | null;
+
+export type PageCapabilityExtraction = {
+  directTools: string[];
+  hardSkillKeys: string[];
+  softSkillKeys: string[];
+  hardSkillTools: string[];
+  softSkillHints: string[];
+  promptPatches: string[];
+  shouldUpgradeReference: boolean;
+};
+
+export type SkillGraphRoot = {
+  identifier: string;
+  mode: "required" | "recommended";
+  sourceLabel?: string;
+};
+
+export type SkillGraphVisit = {
+  dbKey: string;
+  title?: string;
+  mode: "required" | "recommended";
+  sourceLabel?: string;
+  meta?: ReturnType<typeof resolvePageSkillMetadata>;
+};
+
+export type ResolvedSkillGraph = {
+  requiredTools: string[];
+  recommendedTools: string[];
+  recommendedSkillHints: string[];
+  skillPromptPatches: string[];
+  contentByKey: Map<string, SkillRuntimePageLike>;
+  visits: SkillGraphVisit[];
+};
+
+export const joinUniqueStrings = (...groups: Array<string[] | undefined>): string[] =>
+  Array.from(
+    new Set(
+      groups
+        .flatMap((items) => items ?? [])
+        .filter((item): item is string => typeof item === "string" && !!item.trim()),
+    ),
+  );
+
+export const extractRuntimePageCapabilities = (
+  content: SkillRuntimePageLike,
+): PageCapabilityExtraction => {
+  const meta = resolvePageSkillMetadata(content);
+  const directTools = Array.isArray(content?.tools)
+    ? content.tools.filter((tool): tool is string => typeof tool === "string" && !!tool)
+    : [];
+  const skillConfig = meta?.skillConfig;
+  const skillTools = skillConfig?.toolNames ?? [];
+  const softSkillHints = [
+    skillConfig?.name,
+    ...(meta?.recommendedSkills ?? []),
+  ].filter((item): item is string => typeof item === "string" && !!item);
+
+  return {
+    directTools,
+    hardSkillKeys: meta?.requiredSkills ?? [],
+    softSkillKeys: meta?.recommendedSkills ?? [],
+    hardSkillTools: meta?.kind === "skill" ? skillTools : [],
+    softSkillHints,
+    promptPatches: skillConfig?.promptPatch ? [skillConfig.promptPatch] : [],
+    shouldUpgradeReference:
+      directTools.length > 0 || meta?.kind === "skill" || !!skillConfig?.promptPatch,
+  };
+};
+
+export const buildSkillGuidancePromptBlock = (options: {
+  title?: string;
+  recommendedSkillHints?: string[];
+  skillPromptPatches?: string[];
+}): string => {
+  const title = options.title?.trim() || "--- 技能提示 ---";
+  const recommendedSkillHints = joinUniqueStrings(options.recommendedSkillHints);
+  const skillPromptPatches = joinUniqueStrings(options.skillPromptPatches);
+
+  if (recommendedSkillHints.length === 0 && skillPromptPatches.length === 0) {
+    return "";
+  }
+
+  return [
+    title,
+    recommendedSkillHints.length > 0
+      ? `以下技能与当前任务更相关，可优先考虑：${recommendedSkillHints.join("、")}`
+      : "",
+    ...skillPromptPatches,
+  ]
+    .filter(Boolean)
+    .join("\n");
+};
+
+export const buildReferenceRuntimePromptBlock = (visits: SkillGraphVisit[], skillPromptPatches: string[]): string => {
+  const referenceLines: string[] = [];
+  const hardSkillNames = new Set<string>();
+  const softSkillNames = new Set<string>();
+  const promptSections: string[] = [];
+
+  for (const visit of visits) {
+    const line =
+      visit.sourceLabel && visit.sourceLabel !== visit.dbKey
+        ? `${visit.title ?? visit.dbKey} (${visit.dbKey}) <- ${visit.sourceLabel}`
+        : `${visit.title ?? visit.dbKey} (${visit.dbKey})`;
+    if (!referenceLines.includes(line)) {
+      referenceLines.push(line);
+    }
+    const skillName = visit.meta?.skillConfig?.name;
+    if (!skillName) continue;
+    if (visit.mode === "required") hardSkillNames.add(skillName);
+    else softSkillNames.add(skillName);
+  }
+
+  if (referenceLines.length > 0) {
+    promptSections.push(
+      [
+        "你当前挂载了这些 references，可按需直接读取它们的 dbKey：",
+        ...referenceLines.map((line) => `- ${line}`),
+      ].join("\n"),
+    );
+  }
+  if (hardSkillNames.size > 0) {
+    promptSections.push(
+      ["这些技能已硬加载，可直接使用相关能力：", ...Array.from(hardSkillNames).map((name) => `- ${name}`)].join("\n"),
+    );
+  }
+  if (softSkillNames.size > 0) {
+    promptSections.push(
+      ["这些技能只是推荐候选，不是必须执行：", ...Array.from(softSkillNames).map((name) => `- ${name}`)].join("\n"),
+    );
+  }
+
+  const skillGuidanceBlock = buildSkillGuidancePromptBlock({
+    title: "技能补充指令：",
+    skillPromptPatches,
+  });
+  if (skillGuidanceBlock) {
+    promptSections.push(skillGuidanceBlock);
+  }
+
+  return promptSections.length > 0 ? promptSections.join("\n\n") : "";
+};
+
+const buildIdentifierCandidates = (
+  identifier: string,
+  contentByKey: Map<string, SkillRuntimePageLike>,
+): string => {
+  const trimmed = identifier.trim();
+  if (!trimmed || contentByKey.has(trimmed)) return trimmed;
+
+  for (const [key, page] of contentByKey.entries()) {
+    const meta = resolvePageSkillMetadata(page);
+    const candidates = [
+      key,
+      page?.dbKey,
+      page?.title,
+      meta?.skillConfig?.id,
+      meta?.skillConfig?.name,
+    ].filter((value): value is string => typeof value === "string" && !!value.trim());
+    if (candidates.includes(trimmed)) {
+      return key;
+    }
+  }
+
+  return trimmed;
+};
+
+export async function resolveSkillGraphFromRoots(options: {
+  roots: SkillGraphRoot[];
+  loadPage: (identifier: string) => Promise<SkillRuntimePageLike>;
+  contentByKey?: Map<string, SkillRuntimePageLike>;
+}): Promise<ResolvedSkillGraph> {
+  const contentByKey = new Map<string, SkillRuntimePageLike>(options.contentByKey ?? []);
+  const requiredTools = new Set<string>();
+  const recommendedTools = new Set<string>();
+  const recommendedSkillHints = new Set<string>();
+  const skillPromptPatches = new Set<string>();
+  const visits: SkillGraphVisit[] = [];
+  const visited = new Set<string>();
+
+  const loadPageCached = async (identifier: string): Promise<SkillRuntimePageLike> => {
+    const resolvedIdentifier = buildIdentifierCandidates(identifier, contentByKey);
+    if (!resolvedIdentifier) return null;
+    if (contentByKey.has(resolvedIdentifier)) {
+      return contentByKey.get(resolvedIdentifier) ?? null;
+    }
+
+    const page = await options.loadPage(resolvedIdentifier);
+    if (page) {
+      contentByKey.set(resolvedIdentifier, page);
+      if (page.dbKey) {
+        contentByKey.set(page.dbKey, page);
+      }
+    }
+    return page ?? null;
+  };
+
+  const visit = async (
+    identifier: string,
+    mode: "required" | "recommended",
+    sourceLabel?: string,
+  ): Promise<void> => {
+    const page = await loadPageCached(identifier);
+    if (!page?.dbKey) return;
+    const visitKey = `${mode}:${page.dbKey}`;
+    if (visited.has(visitKey)) return;
+    visited.add(visitKey);
+
+    const meta = resolvePageSkillMetadata(page);
+    const directTools = canonicalizeToolNames(page.tools ?? []);
+    const skillTools = canonicalizeToolNames(meta?.skillConfig?.toolNames ?? []);
+    const mergedTools = joinUniqueStrings(directTools, skillTools);
+
+    visits.push({
+      dbKey: page.dbKey,
+      title: page.title,
+      mode,
+      sourceLabel,
+      meta,
+    });
+
+    if (mode === "required") {
+      mergedTools.forEach((toolName) => requiredTools.add(toolName));
+      if (meta?.skillConfig?.promptPatch) {
+        skillPromptPatches.add(meta.skillConfig.promptPatch);
+      }
+    } else {
+      mergedTools.forEach((toolName) => recommendedTools.add(toolName));
+      if (meta?.skillConfig?.name) {
+        recommendedSkillHints.add(meta.skillConfig.name);
+      }
+    }
+
+    const nextHard = meta?.requiredSkills ?? meta?.skillConfig?.requiredSkills ?? [];
+    const nextSoft = meta?.recommendedSkills ?? meta?.skillConfig?.recommendedSkills ?? [];
+
+    if (mode === "required") {
+      for (const childKey of nextHard) {
+        await visit(childKey, "required", page.dbKey);
+      }
+      for (const childKey of nextSoft) {
+        await visit(childKey, "recommended", page.dbKey);
+      }
+      return;
+    }
+
+    for (const childKey of [...nextHard, ...nextSoft]) {
+      await visit(childKey, "recommended", page.dbKey);
+    }
+  };
+
+  for (const root of options.roots) {
+    await visit(root.identifier, root.mode, root.sourceLabel);
+  }
+
+  return {
+    requiredTools: Array.from(requiredTools),
+    recommendedTools: Array.from(recommendedTools),
+    recommendedSkillHints: Array.from(recommendedSkillHints),
+    skillPromptPatches: Array.from(skillPromptPatches),
+    contentByKey,
+    visits,
+  };
+}

package/ai/skills/skillDiagnostics.ts

@@ -0,0 +1,251 @@
+import {
+  parseSkillDocProtocol,
+  resolvePageSkillMetadata,
+  type PageSkillMetadata,
+} from "./skillDocProtocol";
+import { canonicalizeToolNames } from "ai/tools/toolNameAliases";
+
+type PageLike = {
+  dbKey?: string;
+  title?: string;
+  content?: string | null;
+  meta?: unknown;
+  tools?: string[];
+} | null | undefined;
+
+export interface SkillDiagnosticInput {
+  id?: string;
+  title?: string;
+  content?: string;
+  meta?: PageSkillMetadata;
+  tools?: string[];
+}
+
+export interface SkillDoctorResult {
+  ok: boolean;
+  skillId?: string;
+  name?: string;
+  canonicalToolNames: string[];
+  errors: string[];
+  warnings: string[];
+  notes: string[];
+  evalCaseCount: number;
+}
+
+export interface SkillEvalCaseResult {
+  input: string;
+  passed: boolean;
+  expectedTools?: string[];
+  missingTools?: string[];
+  missingSignals?: string[];
+  forbiddenSignalsFound?: string[];
+}
+
+export interface SkillEvalResult {
+  ok: boolean;
+  skillId?: string;
+  name?: string;
+  effectiveTools: string[];
+  missingReferences: string[];
+  cases: SkillEvalCaseResult[];
+}
+
+const hasSkillConfigBlock = (content: string): boolean =>
+  /<!--\s*skill-config\b/i.test(content);
+
+const hasEvalConfigBlock = (content: string): boolean =>
+  /<!--\s*eval-config\b/i.test(content);
+
+const buildPageLike = (input: SkillDiagnosticInput): PageLike => ({
+  dbKey: input.id,
+  title: input.title,
+  content: input.content,
+  meta: input.meta,
+  tools: input.tools,
+});
+
+export const diagnoseSkillDocument = async (
+  input: SkillDiagnosticInput,
+  options?: {
+    getAvailableToolNames?: () => Promise<string[]>;
+  }
+): Promise<SkillDoctorResult> => {
+  const rawContent = input.content ?? "";
+  const pageLike = buildPageLike(input);
+  const parsed = parseSkillDocProtocol(rawContent, input.meta, input.tools);
+  const meta = resolvePageSkillMetadata(pageLike);
+  const skillConfig = meta?.skillConfig;
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const notes: string[] = [];
+
+  if (hasSkillConfigBlock(rawContent) && !skillConfig) {
+    errors.push("检测到 skill-config 块，但内容无效或缺少必填字段。");
+  }
+  if (!hasSkillConfigBlock(rawContent) && !skillConfig) {
+    errors.push("未检测到有效的 skill-config 协议块。");
+  }
+
+  const rawToolNames = skillConfig?.toolNames ?? [];
+  const canonicalToolNames = canonicalizeToolNames(rawToolNames);
+  if (rawToolNames.length > 0 && canonicalToolNames.join("|") !== rawToolNames.join("|")) {
+    notes.push(`工具名已归一化为：${canonicalToolNames.join(", ")}`);
+  }
+
+  if (skillConfig && canonicalToolNames.length === 0) {
+    warnings.push("当前 skill 没有绑定工具；如果它只是说明型 skill 可以保留，否则建议补齐 toolNames。");
+  }
+
+  if (skillConfig && !skillConfig.promptPatch) {
+    notes.push("当前 skill 没有 promptPatch；如果需要运行时行为提示，可以补一个简短 patch。");
+  }
+
+  if (!meta?.evalConfig?.cases?.length) {
+    warnings.push("当前 skill 没有 eval-config；建议至少添加 1 条评估用例。");
+  }
+
+  if (
+    Array.isArray(meta?.requiredSkills) &&
+    Array.isArray(meta?.recommendedSkills)
+  ) {
+    const overlap = meta.requiredSkills.filter((item) =>
+      meta.recommendedSkills?.includes(item)
+    );
+    if (overlap.length > 0) {
+      warnings.push(`这些 skill 同时出现在 required/recommended 中：${overlap.join(", ")}`);
+    }
+  }
+
+  if (/opencli\s+twitter\s+thread\s+--tweet_id\b/i.test(rawContent)) {
+    warnings.push("检测到过期参数 `--tweet_id`，请改为 `--tweet-id`。");
+  }
+
+  if (/opencli\s+twitter/i.test(rawContent) && !/OPENCLI_CDP_ENDPOINT/.test(rawContent)) {
+    notes.push("如果 OpenCLI 遇到 daemon / 19825 端口冲突，可优先复用已有 Chrome CDP：OPENCLI_CDP_ENDPOINT=http://127.0.0.1:19825");
+  }
+
+  if (options?.getAvailableToolNames && canonicalToolNames.length > 0) {
+    const available = new Set(await options.getAvailableToolNames());
+    const unknownTools = canonicalToolNames.filter((toolName) => !available.has(toolName));
+    if (unknownTools.length > 0) {
+      warnings.push(`这些工具当前运行时中不存在：${unknownTools.join(", ")}`);
+    }
+  }
+
+  if (parsed.content && parsed.content.length < 30) {
+    notes.push("当前正文较短；如果这是流程型 skill，建议补充步骤、边界和失败处理。");
+  }
+
+  return {
+    ok: errors.length === 0,
+    skillId: skillConfig?.id,
+    name: skillConfig?.name,
+    canonicalToolNames,
+    errors,
+    warnings,
+    notes,
+    evalCaseCount: meta?.evalConfig?.cases?.length ?? 0,
+  };
+};
+
+const resolveEffectiveTools = async (
+  page: PageLike,
+  options?: {
+    loadPage?: (dbKey: string) => Promise<PageLike | undefined>;
+  },
+  visited?: Set<string>,
+  missingReferences?: Set<string>
+): Promise<string[]> => {
+  const meta = resolvePageSkillMetadata(page);
+  const directTools = canonicalizeToolNames(meta?.skillConfig?.toolNames ?? page?.tools ?? []);
+  const aggregate = new Set<string>(directTools);
+  const nextVisited = visited ?? new Set<string>();
+  const nextMissing = missingReferences ?? new Set<string>();
+
+  if (!meta?.requiredSkills?.length || !options?.loadPage) {
+    return Array.from(aggregate);
+  }
+
+  for (const dbKey of meta.requiredSkills) {
+    if (!dbKey || nextVisited.has(dbKey)) continue;
+    nextVisited.add(dbKey);
+    const linkedPage = await options.loadPage(dbKey);
+    if (!linkedPage) {
+      nextMissing.add(dbKey);
+      continue;
+    }
+    const nestedTools = await resolveEffectiveTools(
+      linkedPage,
+      options,
+      nextVisited,
+      nextMissing
+    );
+    for (const toolName of nestedTools) {
+      aggregate.add(toolName);
+    }
+  }
+
+  return Array.from(aggregate);
+};
+
+export const evaluateSkillDocument = async (
+  input: SkillDiagnosticInput,
+  options?: {
+    loadPage?: (dbKey: string) => Promise<PageLike | undefined>;
+  }
+): Promise<SkillEvalResult> => {
+  const pageLike = buildPageLike(input);
+  const meta = resolvePageSkillMetadata(pageLike);
+  const skillConfig = meta?.skillConfig;
+  const evalCases = meta?.evalConfig?.cases ?? [];
+  const missingReferences = new Set<string>();
+  const effectiveTools = await resolveEffectiveTools(
+    pageLike,
+    options,
+    new Set<string>(),
+    missingReferences
+  );
+  const searchableText = [
+    input.content ?? "",
+    skillConfig?.description ?? "",
+    skillConfig?.promptPatch ?? "",
+  ]
+    .join("\n")
+    .toLowerCase();
+
+  const cases: SkillEvalCaseResult[] = evalCases.map((testCase) => {
+    const missingTools = (testCase.expectedTools ?? []).filter(
+      (toolName) => !effectiveTools.includes(toolName)
+    );
+    const missingSignals = (testCase.expectedSignals ?? []).filter(
+      (signal) => !searchableText.includes(signal.toLowerCase())
+    );
+    const forbiddenSignalsFound = (testCase.forbiddenSignals ?? []).filter(
+      (signal) => searchableText.includes(signal.toLowerCase())
+    );
+    const passed =
+      missingTools.length === 0 &&
+      missingSignals.length === 0 &&
+      forbiddenSignalsFound.length === 0;
+
+    return {
+      input: testCase.input,
+      passed,
+      ...(testCase.expectedTools?.length
+        ? { expectedTools: testCase.expectedTools }
+        : {}),
+      ...(missingTools.length ? { missingTools } : {}),
+      ...(missingSignals.length ? { missingSignals } : {}),
+      ...(forbiddenSignalsFound.length ? { forbiddenSignalsFound } : {}),
+    };
+  });
+
+  return {
+    ok: !!skillConfig && cases.every((item) => item.passed),
+    skillId: skillConfig?.id,
+    name: skillConfig?.name,
+    effectiveTools,
+    missingReferences: Array.from(missingReferences),
+    cases,
+  };
+};

package/ai/skills/skillDocBuilder.ts

@@ -0,0 +1,139 @@
+import {
+  buildSkillDocMarkdown,
+  type SkillBudgetTier,
+  type SkillDocConfig,
+  type SkillEvalCase,
+  type SkillEvalConfig,
+  type SkillModality,
+} from "./skillDocProtocol";
+import { canonicalizeToolNames } from "ai/tools/toolNameAliases";
+
+export interface CreateSkillDocArgs {
+  title?: string;
+  name?: string;
+  description: string;
+  body?: string;
+  toolNames?: string[];
+  requiredSkills?: string[];
+  recommendedSkills?: string[];
+  promptPatch?: string;
+  budgetTier?: SkillBudgetTier;
+  dispatchPreferred?: boolean;
+  modalities?: SkillModality[];
+  preferredAgents?: string[];
+  discoverKeywords?: string[];
+  discoverExamples?: string[];
+  evalCases?: SkillEvalCase[];
+}
+
+const slugify = (value: string): string =>
+  value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "skill";
+
+const normalizeStringArray = (value: unknown): string[] | undefined => {
+  if (!Array.isArray(value)) return undefined;
+  const normalized = value
+    .filter((item): item is string => typeof item === "string")
+    .map((item) => item.trim())
+    .filter(Boolean);
+  return normalized.length > 0 ? Array.from(new Set(normalized)) : undefined;
+};
+
+const normalizeEvalCases = (value: unknown): SkillEvalCase[] | undefined => {
+  if (!Array.isArray(value)) return undefined;
+  const normalized = value
+    .filter((item): item is SkillEvalCase => !!item && typeof item === "object")
+    .map((item) => ({
+      input: typeof item.input === "string" ? item.input.trim() : "",
+      expectedTools: normalizeStringArray(item.expectedTools),
+      expectedSignals: normalizeStringArray(item.expectedSignals),
+      forbiddenSignals: normalizeStringArray(item.forbiddenSignals),
+    }))
+    .filter((item) => item.input);
+  return normalized.length > 0 ? normalized : undefined;
+};
+
+const normalizeModalities = (value: unknown): SkillModality[] | undefined => {
+  const normalized = normalizeStringArray(value);
+  if (!normalized) return undefined;
+  const filtered = normalized.filter(
+    (item): item is SkillModality =>
+      item === "text" ||
+      item === "image" ||
+      item === "video" ||
+      item === "audio" ||
+      item === "3d"
+  );
+  return filtered.length > 0 ? filtered : undefined;
+};
+
+const normalizeBudgetTier = (value: unknown): SkillBudgetTier | undefined =>
+  value === "low" || value === "medium" || value === "high" ? value : undefined;
+
+export const buildSkillDocFromArgs = (
+  args: CreateSkillDocArgs
+): {
+  title: string;
+  content: string;
+  skillConfig: SkillDocConfig;
+  evalConfig?: SkillEvalConfig;
+} => {
+  const rawTitle = (args.title ?? "").trim();
+  const rawName = (args.name ?? "").trim();
+  const title = rawTitle || rawName || "New Skill";
+  const name = rawName || title;
+  const description = (args.description ?? "").trim();
+  if (!description) {
+    throw new Error("createSkillDoc 需要 description。");
+  }
+
+  const skillConfig: SkillDocConfig = {
+    version: "0.1",
+    kind: "skill",
+    id: slugify(name),
+    name,
+    description,
+    triggerMode: "explicit",
+    toolNames: canonicalizeToolNames(normalizeStringArray(args.toolNames) ?? []),
+    requiredSkills: normalizeStringArray(args.requiredSkills),
+    recommendedSkills: normalizeStringArray(args.recommendedSkills),
+    promptPatch:
+      typeof args.promptPatch === "string" && args.promptPatch.trim()
+        ? args.promptPatch.trim()
+        : undefined,
+    budgetTier: normalizeBudgetTier(args.budgetTier) ?? "medium",
+    dispatchPreferred: args.dispatchPreferred === true,
+    modalities: normalizeModalities(args.modalities) ?? ["text"],
+    preferredAgents: normalizeStringArray(args.preferredAgents),
+    discover:
+      normalizeStringArray(args.discoverKeywords)?.length ||
+      normalizeStringArray(args.discoverExamples)?.length
+        ? {
+            keywords: normalizeStringArray(args.discoverKeywords),
+            examples: normalizeStringArray(args.discoverExamples),
+          }
+        : undefined,
+  };
+
+  const evalCases = normalizeEvalCases(args.evalCases);
+  const evalConfig = evalCases
+    ? {
+        version: "0.1" as const,
+        cases: evalCases,
+      }
+    : undefined;
+
+  return {
+    title,
+    skillConfig,
+    evalConfig,
+    content: buildSkillDocMarkdown({
+      body: (args.body ?? "").trim(),
+      skillConfig,
+      evalConfig,
+    }),
+  };
+};