abelien-harness 0.14.0 → 1.0.0

package/skills/abelien-harness/scripts/action-cli.mjs

@@ -0,0 +1,54 @@
+// `ab action` 命令面与 `ab help <action_id>`（P2-05 卡 A）。ab.mjs 只在 COMMAND_HELP 与分发处接线，
+// 域包发现由 ab.mjs 传入，本模块不反向 import ab.mjs。输出遵守单行 JSON 契约：list → data.actions，
+// describe → data.action，manifest → data.manifest + data.execution_manifest_digest。
+import fs from "node:fs";
+import path from "node:path";
+import { loadActionRegistry, buildManifest } from "./action-registry.mjs";
+import { renderActionHelp } from "./action-docs.mjs";
+
+const ACTION_ID = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
+const usage = message => Object.assign(new Error(message), { code: "USAGE" });
+
+function audienceOf(flags) {
+  if (flags.audience === undefined) return "agent";
+  if (flags.audience === "host") return "host";
+  throw usage("--audience only accepts host");
+}
+
+/** 部署 profile：--bindings 优先，其次 AB_BINDINGS_FILE；都没有时只用各包缺省 bindings.json。 */
+function profileFile(flags, env) {
+  const value = flags.bindings ?? env?.AB_BINDINGS_FILE;
+  if (value === undefined || value === "") return undefined;
+  if (typeof value !== "string" || !value) throw usage("--bindings requires a path");
+  const file = path.resolve(value);
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw usage(`bindings profile not found: ${value}`);
+  return file;
+}
+
+export function actionCmd(pos, flags, deps) {
+  const sub = pos[0];
+  const registry = () => loadActionRegistry({ domains: deps.domains(), profileFile: profileFile(flags, deps.env) });
+  if (sub === "list") {
+    const audience = audienceOf(flags);
+    return { actions: registry().list(audience) };
+  }
+  if (sub === "describe") {
+    const id = pos[1];
+    if (!id) throw usage("missing required argument: <action_id>");
+    if (!ACTION_ID.test(id)) throw usage(`not an action id: ${id}`);
+    return { action: registry().describe(id, audienceOf(flags)) };
+  }
+  if (sub === "manifest") {
+    return buildManifest(registry(), { domains: deps.domains(), skillsRoot: deps.skillsRoot, version: deps.version });
+  }
+  throw usage(`unknown action subcommand: ${sub ?? "(none)"}`);
+}
+
+/** 主题像动作名时从注册表生成人读详解；不是动作名或注册表里没有时返回 null，交回原来的用法错误。 */
+export function actionHelpText(topic, deps) {
+  if (!ACTION_ID.test(topic)) return null;
+  const registry = loadActionRegistry({ domains: deps.domains(), profileFile: profileFile({}, deps.env) });
+  const hit = registry.actions.get(topic);
+  if (!hit) return null;
+  return renderActionHelp(hit.effective, registry.schema);
+}

package/skills/abelien-harness/scripts/action-docs.mjs

@@ -0,0 +1,293 @@
+// 动作手册与宿主工具 Schema 的渲染（P2-05 卡 A）：同一份有效动作生成三种视图——
+// 每个包的 references/actions.generated.md（中文参数与错误手册）、contract/host-tools.generated.json（宿主工具 Schema）
+// 与 `ab help <action_id>` 的人读详解。手册只读动作定义与 Schema，不读绑定：换绑定（module ↔ http）不改手册。
+// 手册用带标记的 Schema（registry.schema(id, side, {mark:true})）：具名定义（$defs）只在「共用类型」里写一次。
+import { REF_MARK } from "./action-registry.mjs";
+
+export const MANUAL_FILE = "references/actions.generated.md";
+export const HOST_TOOLS_FILE = "contract/host-tools.generated.json";
+export const HOST_TOOLS_SCHEMA = "abelien.host-tools.v1";
+
+const EFFECTS = {
+  "data.read": "读受控数据，含已存产物",
+  "network.read": "访问外网",
+  "artifact.write": "写不可变产物",
+  "external.submit": "向外部服务提交",
+  "budget.consume": "消耗额度",
+  "product.commit": "提交业务修订",
+};
+const DETERMINISM = {
+  deterministic: "确定：冻结输入下结果相同",
+  nondeterministic: "不确定：同样输入可能得到不同结果",
+  implementation_dependent: "取决于实现，由绑定声明",
+};
+const CATEGORY = {
+  source: "输入错误",
+  design: "设计问题",
+  transient: "暂时故障",
+  config: "配置或授权缺失",
+  integrity: "完整性不一致",
+  terminal: "不可恢复",
+  unknown: "结果未知",
+};
+const DEFAULT_RECOVERY = { source: "correct_input", design: "revise_plan", transient: "retry_same_operation", config: "await_configuration",
+  integrity: "quarantine", terminal: "fail_or_fallback", unknown: "reconcile" };
+const RECOVERY = {
+  correct_input: "修正输入后重新调用",
+  revise_plan: "带证据回到规划修正",
+  retry_same_operation: "按原操作身份有界重试",
+  await_configuration: "停下等待配置或授权",
+  quarantine: "隔离，停止自动推进",
+  fail_or_fallback: "失败收尾或走声明的替代分支",
+  reconcile: "对账原操作，不重发",
+};
+const CHECKS = { output_schema: "输出 Schema", ref_integrity: "引用完整性", postcondition: "领域后置条件" };
+
+const cell = value => String(value ?? "").replace(/\r?\n+/g, " ").replace(/\|/g, "\\|").trim();
+const code = value => `\`${String(value).replace(/`/g, "'")}\``;
+const isObject = value => value !== null && typeof value === "object" && !Array.isArray(value);
+const literal = value => code(JSON.stringify(value));
+const sentence = text => String(text).trim().replace(/[。；;.\s]+$/u, "");
+
+/** 共用类型的收集器：同名不同定义时加序号区分。 */
+function typeCollector() {
+  const byKey = new Map(), names = new Map();
+  return {
+    /** 记下一个具名节点，返回它在手册里的名字；不是具名节点返回 null。 */
+    name(schema) {
+      const mark = isObject(schema) ? schema[REF_MARK] : null;
+      if (!mark) return null;
+      if (byKey.has(mark.key)) return byKey.get(mark.key).name;
+      let name = mark.name;
+      for (let i = 2; names.has(name); i++) name = `${mark.name}${i}`;
+      byKey.set(mark.key, { name, definition: mark.definition });
+      names.set(name, mark.key);
+      return name;
+    },
+    entries: () => [...byKey.values()],
+    size: () => byKey.size,
+  };
+}
+
+/** 展示用：把 allOf 的各支合并成一个对象 Schema（属性合并、required 取并集），其余原样；各支的具名标记不外溢。 */
+export function flatten(schema) {
+  if (!isObject(schema) || !Array.isArray(schema.allOf)) return schema;
+  const { allOf, ...rest } = schema;
+  const out = { ...rest };
+  for (const part of allOf.map(flatten)) {
+    if (!isObject(part)) continue;
+    for (const [key, value] of Object.entries(part)) {
+      if (key === REF_MARK) continue;
+      if (key === "properties") {
+        const merged = { ...(out.properties ?? {}) };
+        for (const [prop, sub] of Object.entries(value)) merged[prop] = merged[prop] && isObject(sub) ? flatten({ allOf: [merged[prop], sub] }) : sub;
+        out.properties = merged;
+      } else if (key === "required") out.required = [...new Set([...(out.required ?? []), ...value])];
+      else if (key === "description") out.description ??= value;
+      else if (!(key in out)) out[key] = value;
+    }
+  }
+  return out;
+}
+
+function cachePolicy(policy) {
+  const mode = { disabled: "不缓存", disabled_by_default: "缺省不缓存，部署或请求显式打开才复用", enabled: "符合条件即复用" }[policy.mode];
+  const parts = [mode, policy.allow_bypass ? "可要求重新计算" : "不能要求绕过缓存"];
+  if (policy.isolation) parts.push(policy.isolation === "work" ? "按作品隔离" : "按租户隔离");
+  return parts.join("；");
+}
+
+function typeLabel(schema, types) {
+  const named = types?.name(schema);
+  if (named) return named;
+  schema = flatten(schema);
+  if (!isObject(schema)) return schema === true ? "任意" : "不允许";
+  if (schema.const !== undefined) return schema.const === null ? "null" : typeof schema.const;
+  const variants = schema.oneOf ?? schema.anyOf;
+  if (Array.isArray(variants)) return [...new Set(variants.map(variant => typeLabel(variant, types)))].join(" / ");
+  const list = [].concat(schema.type ?? (schema.enum ? [...new Set(schema.enum.map(v => v === null ? "null" : typeof v))] : []));
+  if (!list.length) return schema.properties ? "object" : "任意";
+  return list.map(type => type === "array" && isObject(schema.items) ? `array<${typeLabel(schema.items, types)}>` : type).join(" / ");
+}
+
+function constraints(schema) {
+  schema = flatten(schema);
+  if (!isObject(schema)) return [];
+  const out = [];
+  if (schema.const !== undefined) out.push(`固定 ${literal(schema.const)}`);
+  if (Array.isArray(schema.enum)) out.push(`取值 ${schema.enum.map(literal).join(" / ")}`);
+  const range = (min, max, unit) => min !== undefined && max !== undefined ? (min === max ? `${min}${unit}` : `${min}–${max}${unit}`)
+    : min !== undefined ? `至少 ${min}${unit}` : max !== undefined ? `至多 ${max}${unit}` : null;
+  if (schema.minLength === 1 && schema.maxLength === undefined) out.push("非空");
+  else { const length = range(schema.minLength, schema.maxLength, " 字符"); if (length) out.push(`长度 ${length}`); }
+  const items = range(schema.minItems, schema.maxItems, " 项");
+  if (items) out.push(items);
+  const number = range(schema.minimum ?? (schema.exclusiveMinimum !== undefined ? `>${schema.exclusiveMinimum}` : undefined), schema.maximum, "");
+  if (number) out.push(`范围 ${number}`);
+  if (schema.uniqueItems) out.push("不重复");
+  if (schema.pattern) out.push(`格式 ${code(schema.pattern)}`);
+  if (schema.format) out.push(`格式 ${schema.format}`);
+  if (schema.default !== undefined) out.push(`缺省 ${literal(schema.default)}`);
+  if (isObject(schema.items) && !schema.items[REF_MARK]) {
+    const inner = constraints(schema.items).filter(text => !text.startsWith("缺省"));
+    if (inner.length && !flatten(schema.items).properties) out.push(`每项：${inner.join("，")}`);
+  }
+  return out;
+}
+
+const note = (schema, named) => [isObject(schema) && schema.description ? sentence(schema.description) : null,
+  ...(named ? [] : constraints(schema))].filter(Boolean).join("；");
+
+/** 把对象 Schema 摊平成参数行：嵌套对象与对象数组按 `a.b`、`a[].b` 展开（最多 depth 层）；具名类型不展开。 */
+export function parameterRows(schema, { prefix = "", depth = 3, types = null } = {}) {
+  schema = flatten(schema);
+  const rows = [];
+  if (!isObject(schema) || !isObject(schema.properties)) return rows;
+  const required = new Set(schema.required ?? []);
+  for (const [key, prop] of Object.entries(schema.properties)) {
+    const name = `${prefix}${key}`;
+    const named = Boolean(types?.name(prop)) || (isObject(prop) && Boolean(types?.name(prop.items)));
+    rows.push({ name, type: typeLabel(prop, types), required: required.has(key), note: note(prop, named && Boolean(types?.name(prop))) });
+    if (named || depth <= 1) continue;
+    const shown = flatten(prop);
+    if (!isObject(shown)) continue;
+    const items = flatten(shown.items);
+    const object = shown.properties ? shown : isObject(items) && items.properties ? items : null;
+    if (object) rows.push(...parameterRows(object, { prefix: `${name}${object === shown ? "." : "[]."}`, depth: depth - 1, types }));
+  }
+  return rows;
+}
+
+function parameterTable(schema, { depth = 3, empty = "无参数。", types = null } = {}) {
+  schema = flatten(schema);
+  const rows = parameterRows(schema, { depth, types });
+  if (!rows.length) return [isObject(schema) && schema.description ? sentence(schema.description) + "。" : empty];
+  const lines = ["| 参数 | 类型 | 必填 | 说明 |", "| --- | --- | --- | --- |"];
+  for (const row of rows) lines.push(`| ${code(row.name)} | ${cell(row.type)} | ${row.required ? "是" : "否"} | ${cell(row.note) || "—"} |`);
+  if (schema.additionalProperties === false) lines.push("", "不接受表外的字段。");
+  return lines;
+}
+
+function inputSection(schema, types) {
+  schema = flatten(schema);
+  const lines = [];
+  if (schema.description) lines.push(sentence(schema.description) + "。", "");
+  if (Array.isArray(schema.oneOf)) {
+    lines.push("入参是以下几种形态之一：");
+    schema.oneOf.forEach((branch, index) => {
+      const fixed = Object.entries(branch.properties ?? {}).filter(([, prop]) => prop?.const !== undefined).map(([key, prop]) => `${key} = ${literal(prop.const)}`);
+      lines.push("", `形态 ${index + 1}${fixed.length ? `（${fixed.join("，")}）` : ""}：${branch.description ? sentence(branch.description) : ""}`, "",
+        ...parameterTable({ ...branch, description: undefined }, { types }));
+    });
+    return lines;
+  }
+  return [...lines, ...parameterTable({ ...schema, description: undefined }, { types })];
+}
+
+function errorTable(definition) {
+  const entries = Object.entries(definition.errors);
+  if (!entries.length) return ["没有声明本动作专属的错误码。"];
+  const lines = ["| 错误码 | 类别 | 处理 | 说明 |", "| --- | --- | --- | --- |"];
+  for (const [errorCode, decl] of entries.sort(([a], [b]) => a.localeCompare(b))) {
+    const category = typeof decl === "string" ? decl : decl.category;
+    const recovery = (typeof decl === "object" && decl.recovery) || DEFAULT_RECOVERY[category];
+    lines.push(`| ${code(errorCode)} | ${category}（${CATEGORY[category]}） | ${RECOVERY[recovery]} | ${cell(typeof decl === "object" ? decl.description : "") || "—"} |`);
+  }
+  return lines;
+}
+
+/** 单个动作的手册段落（定义与 Schema，不含绑定）。level 是标题级别；types 收集用到的共用类型。 */
+export function renderActionSection(action, inputSchema, outputSchema, { level = 2, types = typeCollector() } = {}) {
+  const definition = action.definition;
+  const h = "#".repeat(level);
+  const effects = definition.effects.length ? definition.effects.map(effect => `${code(effect)} ${EFFECTS[effect]}`).join("；") : "无（纯计算，不读写资源、不联网）";
+  const checks = definition.result_checks.map(check => check.kind === "postcondition" ? `${CHECKS[check.kind]} ${code(`${check.entry.path}#${check.entry.export}`)}` : CHECKS[check.kind]).join("、");
+  const lines = [
+    `${h} ${definition.action_id}`, "",
+    definition.description ? sentence(definition.description) + "。" : "（未写说明）", "",
+    "| 项 | 内容 |", "| --- | --- |",
+    `| 契约版本 | ${definition.contract_version} |`,
+    `| 受众 | ${(definition.audience ?? "agent") === "host" ? "host（只供宿主进程）" : "agent"} |`,
+    `| 效果 | ${cell(effects)} |`,
+    `| 确定性 | ${DETERMINISM[definition.determinism]} |`,
+    `| 缓存 | ${cell(cachePolicy(definition.cache_policy))} |`,
+    `| 完成 | 结果通过校验才算完成：${cell(checks)} |`,
+    "",
+    `${h}# 输入`, "", ...inputSection(inputSchema, types), "",
+    `${h}# 输出`, "", ...parameterTable(outputSchema, { depth: 1, empty: "无字段说明。", types }), "",
+    `${h}# 错误`, "", ...errorTable(definition), "",
+  ];
+  return lines.join("\n");
+}
+
+/** 共用类型：每个具名定义写一次；展开时遇到新的具名定义继续追加，直到收齐。 */
+function sharedTypes(types, level) {
+  const h = "#".repeat(level);
+  const lines = [];
+  for (let i = 0; i < types.size(); i++) {
+    const { name, definition } = types.entries()[i];
+    const flat = flatten(definition);
+    const isRecord = isObject(flat) && (flat.properties || flat.allOf);
+    lines.push(`${h} ${name}`, "");
+    if (isRecord) {
+      if (flat.description) lines.push(sentence(flat.description) + "。", "");
+      lines.push(...parameterTable({ ...flat, description: undefined }, { types, empty: "任意对象。" }), "");
+    } else {
+      const facts = [sentence(flat.description ?? ""), ...constraints(flat)].filter(Boolean);
+      lines.push(`${typeLabel({ ...flat, [REF_MARK]: undefined }, types)}${facts.map(text => `；${text}`).join("")}。`, "");
+    }
+  }
+  return lines;
+}
+
+/** 一个包的中文参数与错误手册。actions 为该包的有效动作（已按 action_id 排序），schemaOf 返回带标记的 Schema。 */
+export function renderManual(pkg, actions, schemaOf) {
+  const types = typeCollector();
+  const lines = [
+    "<!-- 生成物：由 tools/render-actions.mjs 从本包 actions/ 与 schemas/ 生成，勿手改。 -->",
+    `# ${pkg} 动作参数与错误手册`, "",
+    "本文由本包的动作定义与 Schema 生成，参数、取值范围与错误码以此为准；何时使用、如何判断见 SKILL.md 与其他参考文档。类型名（如 `Slot`）的字段见文末「共用类型」。", "",
+    "| 动作 | 说明 |", "| --- | --- |",
+    ...actions.map(action => `| ${code(action.action_id)} | ${cell(action.definition.description ? sentence(action.definition.description) : "") || "—"} |`), "",
+  ];
+  for (const action of actions) lines.push(renderActionSection(action, schemaOf(action.action_id, "input", { mark: true }), schemaOf(action.action_id, "output", { mark: true }), { types }));
+  if (types.size()) lines.push("## 共用类型", "", ...sharedTypes(types, 3));
+  return lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}
+
+/** `ab help <action_id>` 的人读详解：手册段落、用到的共用类型，以及当前绑定与绑定追加的效果。 */
+export function renderActionHelp(action, schemaOf) {
+  const types = typeCollector();
+  const binding = action.binding;
+  const where = !binding ? "未绑定（调用时按配置缺失停下）"
+    : binding.transport === "module" ? `module ${binding.entry.path}#${binding.entry.export}`
+      : binding.transport === "http" ? `http ${binding.entry.endpoint_env}${binding.entry.path ?? ""}`
+        : binding.transport === "subflow" ? `subflow ${binding.entry.workflow}` : `studio_tool ${binding.entry.tool}`;
+  const extra = binding ? binding.effects.filter(effect => !action.definition.effects.includes(effect)) : [];
+  const section = renderActionSection(action, schemaOf(action.action_id, "input", { mark: true }), schemaOf(action.action_id, "output", { mark: true }), { level: 1, types });
+  return [
+    "", section.trimEnd(), "",
+    ...(types.size() ? ["## 共用类型", "", ...sharedTypes(types, 3)] : []),
+    `当前绑定：${where}${binding ? `（${binding.implementation_id}）` : ""}`,
+    ...(extra.length ? [`绑定追加的效果：${extra.join("、")}`] : []),
+    `数据版：ab action describe ${action.action_id}`, "",
+  ].join("\n").replace(/\n{3,}/g, "\n\n");
+}
+
+/** 一个包的宿主工具 Schema：各动作的自包含输入输出 Schema，以及宿主工具到动作的投影。 */
+export function renderHostTools(pkg, actions, schemaOf, tools) {
+  return {
+    schema: HOST_TOOLS_SCHEMA,
+    package: pkg,
+    actions: actions.map(action => ({
+      action_id: action.action_id,
+      contract_version: action.contract_version,
+      definition_digest: action.definition_digest,
+      audience: action.definition.audience ?? "agent",
+      description: action.definition.description ?? null,
+      input_schema: schemaOf(action.action_id, "input"),
+      output_schema: schemaOf(action.action_id, "output"),
+    })),
+    tools: tools.map(({ package: _package, ...tool }) => tool).sort((a, b) => a.tool.localeCompare(b.tool)),
+  };
+}