1259 lines
39 KiB
TypeScript
1259 lines
39 KiB
TypeScript
/**
|
||
* 创作流程：编排产物（设计.创作流程）。
|
||
* 可变增量 DAG：有序 steps + 每步 id/中文名 + depends_on；可追加、可同能力多次。
|
||
*
|
||
* 两层内容（作者细写，运行时只搭骨架）：
|
||
* - recipes/：配方方法论（适用、核心思路、设计流程、原则）+ 近期起点 steps
|
||
* - modules/：共用能力池；编排注入 meta 选型字段，执行注入方法全文
|
||
*/
|
||
import { readFile } from "node:fs/promises";
|
||
import path from "node:path";
|
||
import { fileURLToPath } from "node:url";
|
||
import { parse as parseYaml } from "yaml";
|
||
|
||
export const CREATION_FLOW_TAG = "设计.创作流程";
|
||
export const CREATION_CURRENT_STEP_TAG = "创作.当前步骤";
|
||
/** 用户手动选定的初始配方（存 recipe id，或 JSON {id,name}） */
|
||
export const CREATION_SELECTED_RECIPE_TAG = "创作.选用配方";
|
||
export const MODULE_CATALOG_FILENAME = "modules/catalog.yaml";
|
||
export const RECIPE_CATALOG_FILENAME = "recipes/catalog.yaml";
|
||
export const DESIGN_STEP_WORKER_ID = "design-step";
|
||
export const DESIGN_FLOW_WORKER_ID = "design-flow";
|
||
|
||
const DEFAULT_SKILLS_ROOT = path.resolve(
|
||
path.dirname(fileURLToPath(import.meta.url)),
|
||
"../../skills",
|
||
);
|
||
|
||
/** 步骤调用参数（编排期钉死；执行期只读） */
|
||
export type CreationFlowStepParams = Record<string, unknown>;
|
||
|
||
export type CreationFlowStep = {
|
||
/**
|
||
* 本局步骤唯一 id（验收与 depends_on 用这个）。
|
||
* 同能力可多次出现时必须不同；缺省时程序按 name / name#n 补齐。
|
||
*/
|
||
id: string;
|
||
/** 固定中文名，须 ∈ 模块目录（可重复） */
|
||
name: string;
|
||
/** 依赖的其它步骤 id（旧稿若 name 唯一也可写 name） */
|
||
depends_on: string[];
|
||
/**
|
||
* 本步调用参数。有「编排参数」声明的能力必须在进 design-step 前钉齐必填项。
|
||
* 例：生成规则 → target；具体实例 → rule_id。
|
||
*/
|
||
params?: CreationFlowStepParams;
|
||
};
|
||
|
||
export type CreationFlowStatus = "open" | "closed";
|
||
|
||
export type CreationFlow = {
|
||
version: 1;
|
||
/** 可选一句体验复述（给人看） */
|
||
brief?: string;
|
||
/**
|
||
* open = 当前只是近期 horizon，还可增量追加 / 反复编排同能力；
|
||
* closed = 不再扩步（可走收成）。缺省按 closed（兼容旧固定 DAG）。
|
||
*/
|
||
status?: CreationFlowStatus;
|
||
steps: CreationFlowStep[];
|
||
};
|
||
|
||
/** catalog 声明：编排进 DAG 时本步需要哪些调用参数 */
|
||
export type ModuleParamSpec = {
|
||
key: string;
|
||
/** 给人看的中文名 */
|
||
label: string;
|
||
/** 缺省 false；true = validateCreationFlow / 编排必须钉齐 */
|
||
required?: boolean;
|
||
/** 给编排器的短提示（选项从何来、可否其它） */
|
||
hint?: string;
|
||
};
|
||
|
||
export type ModuleCatalogEntry = {
|
||
/** 目录文件夹名，如 aesthetics-interaction */
|
||
id: string;
|
||
name: string;
|
||
/** 给 agent 的短声明：用来决定要不要调度这一步 */
|
||
declaration: string;
|
||
/** 执行期产物 tag（流程 JSON 不写；程序映射） */
|
||
artifact: string;
|
||
/**
|
||
* 可选：默认可反复编排进流程（如生成规则、具体实例）。
|
||
* 程序不硬拦；给编排与校验提示。
|
||
*/
|
||
repeatable?: boolean;
|
||
/**
|
||
* 可选：默认问题（开场白）。优先用 prompt.md 的 ```opening 块；
|
||
* catalog 写了则作覆盖。程序发出，不经 LLM。
|
||
*/
|
||
opening?: string;
|
||
/**
|
||
* 可选：编排期步骤参数声明。
|
||
* 有 required 项时，steps[].params 必须在进执行前钉齐；勿把选型推迟到 design-step。
|
||
*/
|
||
params?: ModuleParamSpec[];
|
||
/** 来自 prompt.md ```meta：何时该选用（编排选型） */
|
||
when?: string;
|
||
/** 来自 prompt.md ```meta：何时不该选用 */
|
||
when_not?: string;
|
||
/** 来自 prompt.md ```meta：与其它能力的边界 */
|
||
boundary?: string;
|
||
};
|
||
|
||
/** 本步程序开场白正文（design-step 发出后写入，供 LLM 看见） */
|
||
export const CREATION_MODULE_OPENING_TAG = "创作.能力开场白";
|
||
/** JSON：{ [步骤中文名]: "shown" | "answered" } */
|
||
export const CREATION_MODULE_OPENING_STATE_TAG = "创作.能力开场状态";
|
||
export const SLOT_CREATION_MODULE_OPENING_STATE = "creationModuleOpeningState";
|
||
|
||
export type ModuleOpeningState = Record<string, "shown" | "answered">;
|
||
|
||
export type ModuleCatalog = {
|
||
modules: ModuleCatalogEntry[];
|
||
};
|
||
|
||
/** 初始配方目录条目（短声明，给选型） */
|
||
export type RecipeCatalogEntry = {
|
||
id: string;
|
||
name: string;
|
||
declaration: string;
|
||
};
|
||
|
||
export type RecipeCatalog = {
|
||
recipes: RecipeCatalogEntry[];
|
||
};
|
||
|
||
/**
|
||
* 单份配方详情。
|
||
* 方法论字段供编排选型；seed = 近期起点 steps（可为空；name 须 ∈ 模块池）。
|
||
*/
|
||
export type RecipeDetail = {
|
||
id: string;
|
||
name: string;
|
||
declaration: string;
|
||
/** 适用什么体验/任务 */
|
||
when?: string;
|
||
/** 整套设计方法的核心思路与最终目标 */
|
||
core?: string;
|
||
/** 设计流程：如何增量选型、何时收成（字符串或条目列表） */
|
||
process?: string | string[];
|
||
/** 配方特有取舍原则 */
|
||
principles?: string | string[];
|
||
/**
|
||
* @deprecated 旧字段；新配方用 core/process/principles。解析仍可读，格式化时作兜底。
|
||
*/
|
||
hint?: string;
|
||
seed: CreationFlow | null;
|
||
};
|
||
|
||
export type CreationFlowValidation = {
|
||
ok: boolean;
|
||
errors: string[];
|
||
};
|
||
|
||
export type CreationFlowUserView = {
|
||
brief?: string;
|
||
status?: CreationFlowStatus;
|
||
steps: Array<{
|
||
order: number;
|
||
id: string;
|
||
name: string;
|
||
depends_on: string[];
|
||
/** 同能力第几次（>1 时 UI 可标「再来」） */
|
||
occurrence?: number;
|
||
/** 目录里的短声明（有则展示） */
|
||
declaration?: string;
|
||
repeatable?: boolean;
|
||
/** 本步调用参数（编排期钉死） */
|
||
params?: CreationFlowStepParams;
|
||
/** 参数缺必填项时的提示（给人看） */
|
||
paramsMissing?: string[];
|
||
}>;
|
||
parseError?: string;
|
||
};
|
||
|
||
/** 从任意正文抽取 JSON 对象 */
|
||
export function extractJsonObject(raw: string): unknown | null {
|
||
const trimmed = raw.trim();
|
||
if (!trimmed) return null;
|
||
try {
|
||
return JSON.parse(trimmed);
|
||
} catch {
|
||
/* try slice */
|
||
}
|
||
const start = trimmed.indexOf("{");
|
||
const end = trimmed.lastIndexOf("}");
|
||
if (start >= 0 && end > start) {
|
||
try {
|
||
return JSON.parse(trimmed.slice(start, end + 1));
|
||
} catch {
|
||
return null;
|
||
}
|
||
}
|
||
return null;
|
||
}
|
||
|
||
/** 规范化 steps[].params：仅接受普通对象 */
|
||
export function normalizeStepParams(
|
||
raw: unknown,
|
||
): CreationFlowStepParams | undefined {
|
||
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
|
||
const out: CreationFlowStepParams = {};
|
||
for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
|
||
const key = k.trim();
|
||
if (!key) continue;
|
||
out[key] = v;
|
||
}
|
||
return Object.keys(out).length > 0 ? out : undefined;
|
||
}
|
||
|
||
/** 目录声明的必填参数中，本步仍缺失的 key（按声明顺序） */
|
||
export function missingRequiredStepParams(
|
||
step: Pick<CreationFlowStep, "params">,
|
||
module: ModuleCatalogEntry | null | undefined,
|
||
): string[] {
|
||
const specs = module?.params ?? [];
|
||
if (specs.length === 0) return [];
|
||
const params = step.params ?? {};
|
||
const missing: string[] = [];
|
||
for (const spec of specs) {
|
||
if (!spec.required) continue;
|
||
const v = params[spec.key];
|
||
if (v == null) {
|
||
missing.push(spec.key);
|
||
continue;
|
||
}
|
||
if (typeof v === "string" && !v.trim()) {
|
||
missing.push(spec.key);
|
||
}
|
||
}
|
||
return missing;
|
||
}
|
||
|
||
/** 给人 / LLM 看的参数摘要 */
|
||
export function formatStepParamsForPrompt(
|
||
params: CreationFlowStepParams | null | undefined,
|
||
): string {
|
||
if (!params || Object.keys(params).length === 0) return "（无）";
|
||
return Object.entries(params)
|
||
.map(([k, v]) => {
|
||
const rendered =
|
||
typeof v === "string" ? v : JSON.stringify(v, null, 0);
|
||
return `- ${k}: ${rendered}`;
|
||
})
|
||
.join("\n");
|
||
}
|
||
|
||
/** 为缺 id 的步骤补齐唯一 id；同 name 多次 → name#2、name#3… */
|
||
export function ensureCreationFlowStepIds(
|
||
steps: Array<{
|
||
id?: string;
|
||
name: string;
|
||
depends_on: string[];
|
||
params?: CreationFlowStepParams;
|
||
}>,
|
||
): CreationFlowStep[] {
|
||
const used = new Set<string>();
|
||
const nameCount = new Map<string, number>();
|
||
const out: CreationFlowStep[] = [];
|
||
|
||
for (const raw of steps) {
|
||
const name = raw.name.trim();
|
||
const n = (nameCount.get(name) ?? 0) + 1;
|
||
nameCount.set(name, n);
|
||
|
||
let id = typeof raw.id === "string" ? raw.id.trim() : "";
|
||
if (!id) {
|
||
id = n === 1 ? name : `${name}#${n}`;
|
||
}
|
||
if (used.has(id)) {
|
||
let i = 2;
|
||
while (used.has(`${id}#${i}`)) i++;
|
||
id = `${id}#${i}`;
|
||
}
|
||
used.add(id);
|
||
out.push({
|
||
id,
|
||
name,
|
||
depends_on: raw.depends_on.map((d) => d.trim()).filter(Boolean),
|
||
...(raw.params ? { params: raw.params } : {}),
|
||
});
|
||
}
|
||
return out;
|
||
}
|
||
|
||
/** 按 id 或（唯一）name 解析步骤引用 */
|
||
export function findStepByRef(
|
||
flow: CreationFlow,
|
||
ref: string,
|
||
): CreationFlowStep | null {
|
||
const key = ref.trim();
|
||
if (!key) return null;
|
||
const byId = flow.steps.find((s) => s.id === key);
|
||
if (byId) return byId;
|
||
const byName = flow.steps.filter((s) => s.name === key);
|
||
return byName.length === 1 ? byName[0]! : null;
|
||
}
|
||
|
||
/** 验收 / 当前步骤用的单位 id（优先 step.id） */
|
||
export function stepUnitId(step: CreationFlowStep): string {
|
||
return step.id || step.name;
|
||
}
|
||
|
||
export function parseCreationFlow(raw: string | undefined | null): CreationFlow | null {
|
||
if (!raw?.trim()) return null;
|
||
const doc = extractJsonObject(raw);
|
||
if (!doc || typeof doc !== "object" || Array.isArray(doc)) return null;
|
||
const row = doc as Record<string, unknown>;
|
||
const stepsRaw = row.steps;
|
||
if (!Array.isArray(stepsRaw) || stepsRaw.length === 0) return null;
|
||
|
||
const drafted: Array<{
|
||
id?: string;
|
||
name: string;
|
||
depends_on: string[];
|
||
params?: CreationFlowStepParams;
|
||
}> = [];
|
||
for (const item of stepsRaw) {
|
||
if (!item || typeof item !== "object" || Array.isArray(item)) return null;
|
||
const s = item as Record<string, unknown>;
|
||
const name = typeof s.name === "string" ? s.name.trim() : "";
|
||
if (!name) return null;
|
||
const id = typeof s.id === "string" && s.id.trim() ? s.id.trim() : undefined;
|
||
const depsRaw = s.depends_on ?? s.dependsOn ?? [];
|
||
const depends_on = Array.isArray(depsRaw)
|
||
? depsRaw.map((d) => String(d).trim()).filter(Boolean)
|
||
: [];
|
||
const params = normalizeStepParams(s.params);
|
||
drafted.push({ id, name, depends_on, ...(params ? { params } : {}) });
|
||
}
|
||
|
||
const steps = ensureCreationFlowStepIds(drafted);
|
||
|
||
const brief =
|
||
typeof row.brief === "string" && row.brief.trim() ? row.brief.trim() : undefined;
|
||
const statusRaw = typeof row.status === "string" ? row.status.trim() : "";
|
||
const status: CreationFlowStatus | undefined =
|
||
statusRaw === "open" || statusRaw === "closed" ? statusRaw : undefined;
|
||
|
||
return { version: 1, brief, status, steps };
|
||
}
|
||
|
||
export function parseModuleCatalog(raw: string): ModuleCatalog | null {
|
||
let doc: unknown;
|
||
try {
|
||
doc = parseYaml(raw);
|
||
} catch {
|
||
return null;
|
||
}
|
||
if (!doc || typeof doc !== "object" || Array.isArray(doc)) return null;
|
||
const modulesRaw = (doc as Record<string, unknown>).modules;
|
||
if (!Array.isArray(modulesRaw)) return null;
|
||
|
||
const modules: ModuleCatalogEntry[] = [];
|
||
for (const item of modulesRaw) {
|
||
if (!item || typeof item !== "object" || Array.isArray(item)) continue;
|
||
const m = item as Record<string, unknown>;
|
||
const name = typeof m.name === "string" ? m.name.trim() : "";
|
||
const declaration =
|
||
typeof m.declaration === "string" ? m.declaration.trim() : "";
|
||
const artifact = typeof m.artifact === "string" ? m.artifact.trim() : "";
|
||
const id =
|
||
typeof m.id === "string" && m.id.trim()
|
||
? m.id.trim()
|
||
: name
|
||
? slugFromName(name)
|
||
: "";
|
||
if (!name || !declaration || !artifact || !id) continue;
|
||
const opening =
|
||
typeof m.opening === "string" && m.opening.trim()
|
||
? m.opening.trim()
|
||
: undefined;
|
||
const repeatable = m.repeatable === true;
|
||
const params = parseModuleParamSpecs(m.params);
|
||
modules.push({
|
||
id,
|
||
name,
|
||
declaration,
|
||
artifact,
|
||
...(repeatable ? { repeatable: true } : {}),
|
||
...(opening ? { opening } : {}),
|
||
...(params ? { params } : {}),
|
||
});
|
||
}
|
||
if (modules.length === 0) return null;
|
||
return { modules };
|
||
}
|
||
|
||
function parseModuleParamSpecs(raw: unknown): ModuleParamSpec[] | undefined {
|
||
if (!Array.isArray(raw) || raw.length === 0) return undefined;
|
||
const out: ModuleParamSpec[] = [];
|
||
for (const item of raw) {
|
||
if (!item || typeof item !== "object" || Array.isArray(item)) continue;
|
||
const row = item as Record<string, unknown>;
|
||
const key = typeof row.key === "string" ? row.key.trim() : "";
|
||
const label = typeof row.label === "string" ? row.label.trim() : "";
|
||
if (!key || !label) continue;
|
||
const hint =
|
||
typeof row.hint === "string" && row.hint.trim()
|
||
? row.hint.trim()
|
||
: undefined;
|
||
out.push({
|
||
key,
|
||
label,
|
||
...(row.required === true ? { required: true } : {}),
|
||
...(hint ? { hint } : {}),
|
||
});
|
||
}
|
||
return out.length > 0 ? out : undefined;
|
||
}
|
||
|
||
/**
|
||
* 能力 prompt.md 可切割块（fence 语言标签 = 块 id）。
|
||
* 标准块见 MODULE_SECTION_IDS；程序只认 ```id … ```，不认散文标题 alone。
|
||
*/
|
||
export const MODULE_SECTION_IDS = [
|
||
"meta",
|
||
"opening",
|
||
"task",
|
||
"principles",
|
||
"probe",
|
||
"output",
|
||
"checklist",
|
||
"examples",
|
||
] as const;
|
||
|
||
export type ModuleSectionId = (typeof MODULE_SECTION_IDS)[number];
|
||
|
||
export type ModulePromptSections = {
|
||
/** 原文 */
|
||
raw: string;
|
||
/** 按 fence 标签切出的块；缺块则为空串 */
|
||
blocks: Partial<Record<ModuleSectionId, string>> & Record<string, string>;
|
||
};
|
||
|
||
/**
|
||
* 切割能力文档：抽取全部 ```lang … ``` 块。
|
||
* 同一 lang 多次出现时拼接（中间空行）。
|
||
*/
|
||
export function parseModulePromptSections(promptMd: string): ModulePromptSections {
|
||
const blocks: Record<string, string> = {};
|
||
if (!promptMd?.trim()) return { raw: promptMd ?? "", blocks };
|
||
const re = /```([a-zA-Z][\w-]*)\s*\r?\n([\s\S]*?)```/g;
|
||
let m: RegExpExecArray | null;
|
||
while ((m = re.exec(promptMd)) !== null) {
|
||
const id = m[1]!.toLowerCase();
|
||
const body = m[2]!.trim();
|
||
if (!body) continue;
|
||
blocks[id] = blocks[id] ? `${blocks[id]}\n\n${body}` : body;
|
||
}
|
||
return { raw: promptMd, blocks };
|
||
}
|
||
|
||
export function getModuleSection(
|
||
sections: ModulePromptSections,
|
||
id: ModuleSectionId | string,
|
||
): string | null {
|
||
const body = sections.blocks[id.toLowerCase()]?.trim();
|
||
return body || null;
|
||
}
|
||
|
||
/** 把 YAML 字段收成可展示的字符串（支持 string / string[]） */
|
||
export function coerceYamlTextField(raw: unknown): string | undefined {
|
||
if (typeof raw === "string" && raw.trim()) return raw.trim();
|
||
if (Array.isArray(raw)) {
|
||
const lines = raw
|
||
.map((x) => (typeof x === "string" ? x.trim() : ""))
|
||
.filter(Boolean);
|
||
return lines.length ? lines.map((l) => `- ${l}`).join("\n") : undefined;
|
||
}
|
||
return undefined;
|
||
}
|
||
|
||
/**
|
||
* 从 prompt.md 的 ```meta 块解析选型字段。
|
||
* catalog 负责索引/params；when/when_not/boundary 以 meta 为准。
|
||
*/
|
||
export function parseModuleMetaFromPrompt(promptMd: string): {
|
||
declaration?: string;
|
||
when?: string;
|
||
when_not?: string;
|
||
boundary?: string;
|
||
} | null {
|
||
const metaRaw = getModuleSection(parseModulePromptSections(promptMd), "meta");
|
||
if (!metaRaw) return null;
|
||
let doc: unknown;
|
||
try {
|
||
doc = parseYaml(metaRaw);
|
||
} catch {
|
||
return null;
|
||
}
|
||
if (!doc || typeof doc !== "object" || Array.isArray(doc)) return null;
|
||
const row = doc as Record<string, unknown>;
|
||
const declaration = coerceYamlTextField(row.declaration);
|
||
const when = coerceYamlTextField(row.when);
|
||
const when_not = coerceYamlTextField(row.when_not);
|
||
const boundary = coerceYamlTextField(row.boundary);
|
||
if (!declaration && !when && !when_not && !boundary) return null;
|
||
return {
|
||
...(declaration ? { declaration } : {}),
|
||
...(when ? { when } : {}),
|
||
...(when_not ? { when_not } : {}),
|
||
...(boundary ? { boundary } : {}),
|
||
};
|
||
}
|
||
|
||
/**
|
||
* 用各能力 prompt.md 的 meta 充实目录条目（编排选型用）。
|
||
* declaration：meta 有则覆盖 catalog；when/when_not/boundary：仅来自 meta。
|
||
*/
|
||
export async function enrichModuleCatalogWithMeta(
|
||
catalog: ModuleCatalog,
|
||
skillPackRoot: string,
|
||
skillsRoot = DEFAULT_SKILLS_ROOT,
|
||
): Promise<ModuleCatalog> {
|
||
const modules = await Promise.all(
|
||
catalog.modules.map(async (m) => {
|
||
const prompt = await loadModulePrompt(skillPackRoot, m.id, skillsRoot);
|
||
if (!prompt) return m;
|
||
const meta = parseModuleMetaFromPrompt(prompt);
|
||
if (!meta) return m;
|
||
return {
|
||
...m,
|
||
...(meta.declaration ? { declaration: meta.declaration } : {}),
|
||
...(meta.when ? { when: meta.when } : {}),
|
||
...(meta.when_not ? { when_not: meta.when_not } : {}),
|
||
...(meta.boundary ? { boundary: meta.boundary } : {}),
|
||
};
|
||
}),
|
||
);
|
||
return { modules };
|
||
}
|
||
|
||
/**
|
||
* 从能力 prompt.md 抽取默认问题（开场白）。
|
||
* 只认 ```opening … ```（能力标准块）。
|
||
*/
|
||
export function extractModuleOpening(promptMd: string): string | null {
|
||
return getModuleSection(parseModulePromptSections(promptMd), "opening");
|
||
}
|
||
|
||
/**
|
||
* 拼给 LLM 的方法正文：标准块按固定顺序；无标准块时回退全文。
|
||
* 不含 opening（开场已由程序发出）。
|
||
*/
|
||
export function formatModulePromptForLlm(promptMd: string): string {
|
||
const { blocks } = parseModulePromptSections(promptMd);
|
||
const order: ModuleSectionId[] = [
|
||
"meta",
|
||
"task",
|
||
"principles",
|
||
"probe",
|
||
"output",
|
||
"checklist",
|
||
"examples",
|
||
];
|
||
const parts: string[] = [];
|
||
for (const id of order) {
|
||
const body = blocks[id]?.trim();
|
||
if (body) parts.push(`## ${id}\n\n\`\`\`${id}\n${body}\n\`\`\``);
|
||
}
|
||
if (parts.length === 0) return promptMd.trim();
|
||
return parts.join("\n\n");
|
||
}
|
||
|
||
export function parseModuleOpeningState(
|
||
raw: string | unknown | null | undefined,
|
||
): ModuleOpeningState {
|
||
if (raw == null) return {};
|
||
const text =
|
||
typeof raw === "string"
|
||
? raw.trim()
|
||
: typeof raw === "object"
|
||
? JSON.stringify(raw)
|
||
: String(raw);
|
||
if (!text) return {};
|
||
try {
|
||
const doc = JSON.parse(text) as unknown;
|
||
if (!doc || typeof doc !== "object" || Array.isArray(doc)) return {};
|
||
const out: ModuleOpeningState = {};
|
||
for (const [k, v] of Object.entries(doc as Record<string, unknown>)) {
|
||
if (v === "shown" || v === "answered") out[k] = v;
|
||
}
|
||
return out;
|
||
} catch {
|
||
return {};
|
||
}
|
||
}
|
||
|
||
export function stringifyModuleOpeningState(state: ModuleOpeningState): string {
|
||
return JSON.stringify(state);
|
||
}
|
||
|
||
/** 无 id 时的兜底（目录仍应显式写 id） */
|
||
function slugFromName(name: string): string {
|
||
const map: Record<string, string> = {
|
||
美学纲领与交互范式: "aesthetics-interaction",
|
||
交互范式: "interaction",
|
||
美学纲领: "aesthetics",
|
||
叙事指南: "narrative",
|
||
实现机制: "mechanism",
|
||
世界蓝图与人文地理: "world-blueprint",
|
||
生成规则: "generation-rules",
|
||
具体实例: "concrete-instances",
|
||
拓扑图谱: "topology",
|
||
设计状态栏: "status-bar",
|
||
变量设计与更新规则: "variable-design",
|
||
变量控制上下文: "variable-context",
|
||
设计回复格式: "reply-format",
|
||
"Worker 规格": "worker-spec",
|
||
细化终稿: "refine",
|
||
};
|
||
return map[name] ?? name;
|
||
}
|
||
|
||
export async function loadModuleCatalog(
|
||
skillPackRoot: string,
|
||
skillsRoot = DEFAULT_SKILLS_ROOT,
|
||
): Promise<ModuleCatalog | null> {
|
||
const fullPath = path.join(skillsRoot, skillPackRoot, MODULE_CATALOG_FILENAME);
|
||
try {
|
||
const raw = await readFile(fullPath, "utf8");
|
||
const catalog = parseModuleCatalog(raw);
|
||
if (!catalog) return null;
|
||
return enrichModuleCatalogWithMeta(catalog, skillPackRoot, skillsRoot);
|
||
} catch {
|
||
return null;
|
||
}
|
||
}
|
||
|
||
/** 注入 design-flow：能力名 + 选型字段（meta）+ 编排参数；非执行全文 */
|
||
export function formatModuleCatalogForAgent(catalog: ModuleCatalog): string {
|
||
const lines = catalog.modules.map((m) => {
|
||
const flags = m.repeatable ? "〔可反复〕" : "";
|
||
const parts: string[] = [`- ${m.name}${flags}：${m.declaration}`];
|
||
if (m.when) parts.push(` 何时用：${indentMultiline(m.when, " ")}`);
|
||
if (m.when_not) parts.push(` 何时不用：${indentMultiline(m.when_not, " ")}`);
|
||
if (m.boundary) parts.push(` 边界：${indentMultiline(m.boundary, " ")}`);
|
||
if (m.params && m.params.length > 0) {
|
||
parts.push(
|
||
` 编排参数：${m.params
|
||
.map((p) => {
|
||
const req = p.required ? "必填" : "可选";
|
||
const hint = p.hint ? `，${p.hint}` : "";
|
||
return `${p.key}（${p.label}，${req}${hint}）`;
|
||
})
|
||
.join("；")}`,
|
||
);
|
||
}
|
||
return parts.join("\n");
|
||
});
|
||
return [
|
||
"【能力 · 可选工序】",
|
||
"按需选用，勿默认全选；步骤名只能从这里选；标〔可反复〕的可多次编入。",
|
||
"选型依据是下方「何时用 / 何时不用 / 边界」（来自各能力 meta）；有「编排参数」的步骤必须在 DAG 里写齐 params，缺参时用 askUser 选项+其它，禁止空壳进执行。",
|
||
"不要把能力执行全文塞进本步；执行由 design-step 注入。",
|
||
lines.join("\n"),
|
||
].join("\n");
|
||
}
|
||
|
||
/** 多行字段：首行接在标签后，续行缩进 */
|
||
function indentMultiline(text: string, indent: string): string {
|
||
const lines = text.split(/\r?\n/);
|
||
if (lines.length <= 1) return text;
|
||
return [lines[0], ...lines.slice(1).map((l) => `${indent}${l}`)].join("\n");
|
||
}
|
||
|
||
export function parseRecipeCatalog(raw: string): RecipeCatalog | null {
|
||
let doc: unknown;
|
||
try {
|
||
doc = parseYaml(raw);
|
||
} catch {
|
||
return null;
|
||
}
|
||
if (!doc || typeof doc !== "object" || Array.isArray(doc)) return null;
|
||
const recipesRaw = (doc as Record<string, unknown>).recipes;
|
||
if (!Array.isArray(recipesRaw)) return null;
|
||
|
||
const recipes: RecipeCatalogEntry[] = [];
|
||
for (const item of recipesRaw) {
|
||
if (!item || typeof item !== "object" || Array.isArray(item)) continue;
|
||
const r = item as Record<string, unknown>;
|
||
const name = typeof r.name === "string" ? r.name.trim() : "";
|
||
const declaration =
|
||
typeof r.declaration === "string" ? r.declaration.trim() : "";
|
||
const id =
|
||
typeof r.id === "string" && r.id.trim()
|
||
? r.id.trim()
|
||
: name
|
||
? slugFromName(name)
|
||
: "";
|
||
if (!name || !declaration || !id) continue;
|
||
recipes.push({ id, name, declaration });
|
||
}
|
||
if (recipes.length === 0) return null;
|
||
return { recipes };
|
||
}
|
||
|
||
export async function loadRecipeCatalog(
|
||
skillPackRoot: string,
|
||
skillsRoot = DEFAULT_SKILLS_ROOT,
|
||
): Promise<RecipeCatalog | null> {
|
||
const fullPath = path.join(skillsRoot, skillPackRoot, RECIPE_CATALOG_FILENAME);
|
||
try {
|
||
const raw = await readFile(fullPath, "utf8");
|
||
return parseRecipeCatalog(raw);
|
||
} catch {
|
||
return null;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 解析单份 recipe.yaml（when / core / process / principles / brief / steps）。
|
||
* 兼容旧字段 hint。steps 空或缺失 → seed 为 null（仍可作选型参考）。
|
||
*/
|
||
export function parseRecipeYaml(
|
||
raw: string,
|
||
meta: RecipeCatalogEntry,
|
||
): RecipeDetail {
|
||
let doc: unknown;
|
||
try {
|
||
doc = parseYaml(raw);
|
||
} catch {
|
||
return {
|
||
id: meta.id,
|
||
name: meta.name,
|
||
declaration: meta.declaration,
|
||
seed: null,
|
||
};
|
||
}
|
||
if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
|
||
return {
|
||
id: meta.id,
|
||
name: meta.name,
|
||
declaration: meta.declaration,
|
||
seed: null,
|
||
};
|
||
}
|
||
const row = doc as Record<string, unknown>;
|
||
const when =
|
||
typeof row.when === "string" && row.when.trim()
|
||
? row.when.trim()
|
||
: undefined;
|
||
const core = coerceYamlTextField(row.core);
|
||
const process = normalizeRecipeListOrText(row.process);
|
||
const principles = normalizeRecipeListOrText(row.principles);
|
||
const hint =
|
||
typeof row.hint === "string" && row.hint.trim()
|
||
? row.hint.trim()
|
||
: undefined;
|
||
const name =
|
||
typeof row.name === "string" && row.name.trim()
|
||
? row.name.trim()
|
||
: meta.name;
|
||
|
||
const seedParsed = parseCreationFlow(JSON.stringify({
|
||
brief: typeof row.brief === "string" ? row.brief : undefined,
|
||
status: "open",
|
||
steps: Array.isArray(row.steps) ? row.steps : [],
|
||
}));
|
||
const seed = seedParsed;
|
||
|
||
return {
|
||
id: meta.id,
|
||
name,
|
||
declaration: meta.declaration,
|
||
when,
|
||
...(core ? { core } : {}),
|
||
...(process ? { process } : {}),
|
||
...(principles ? { principles } : {}),
|
||
...(hint ? { hint } : {}),
|
||
seed,
|
||
};
|
||
}
|
||
|
||
/** process / principles：保留数组，或收成单字符串 */
|
||
function normalizeRecipeListOrText(
|
||
raw: unknown,
|
||
): string | string[] | undefined {
|
||
if (typeof raw === "string" && raw.trim()) return raw.trim();
|
||
if (Array.isArray(raw)) {
|
||
const items = raw
|
||
.map((x) => (typeof x === "string" ? x.trim() : ""))
|
||
.filter(Boolean);
|
||
return items.length ? items : undefined;
|
||
}
|
||
return undefined;
|
||
}
|
||
|
||
export async function loadRecipeDetail(
|
||
skillPackRoot: string,
|
||
entry: RecipeCatalogEntry,
|
||
skillsRoot = DEFAULT_SKILLS_ROOT,
|
||
): Promise<RecipeDetail> {
|
||
const fullPath = path.join(
|
||
skillsRoot,
|
||
skillPackRoot,
|
||
"recipes",
|
||
entry.id,
|
||
"recipe.yaml",
|
||
);
|
||
try {
|
||
const raw = await readFile(fullPath, "utf8");
|
||
return parseRecipeYaml(raw, entry);
|
||
} catch {
|
||
return {
|
||
id: entry.id,
|
||
name: entry.name,
|
||
declaration: entry.declaration,
|
||
seed: null,
|
||
};
|
||
}
|
||
}
|
||
|
||
export async function loadAllRecipeDetails(
|
||
skillPackRoot: string,
|
||
skillsRoot = DEFAULT_SKILLS_ROOT,
|
||
): Promise<RecipeDetail[]> {
|
||
const catalog = await loadRecipeCatalog(skillPackRoot, skillsRoot);
|
||
if (!catalog) return [];
|
||
const out: RecipeDetail[] = [];
|
||
for (const entry of catalog.recipes) {
|
||
out.push(await loadRecipeDetail(skillPackRoot, entry, skillsRoot));
|
||
}
|
||
return out;
|
||
}
|
||
|
||
/**
|
||
* 解析用户选定的配方引用。
|
||
* 接受纯 id / 中文名，或 JSON `{ "id": "…" }` / `{ "name": "…" }`。
|
||
*/
|
||
export function parseSelectedRecipeRef(
|
||
raw: string | null | undefined,
|
||
): string | null {
|
||
if (!raw?.trim()) return null;
|
||
const trimmed = raw.trim();
|
||
try {
|
||
const doc = JSON.parse(trimmed) as unknown;
|
||
if (doc && typeof doc === "object" && !Array.isArray(doc)) {
|
||
const row = doc as Record<string, unknown>;
|
||
const id = typeof row.id === "string" ? row.id.trim() : "";
|
||
const name = typeof row.name === "string" ? row.name.trim() : "";
|
||
return id || name || null;
|
||
}
|
||
} catch {
|
||
/* plain string */
|
||
}
|
||
return trimmed;
|
||
}
|
||
|
||
export function findRecipeCatalogEntry(
|
||
catalog: RecipeCatalog | null | undefined,
|
||
ref: string,
|
||
): RecipeCatalogEntry | null {
|
||
if (!catalog || !ref.trim()) return null;
|
||
const key = ref.trim();
|
||
return (
|
||
catalog.recipes.find((r) => r.id === key || r.name === key) ?? null
|
||
);
|
||
}
|
||
|
||
/** 给人 / API 看的配方目录短列表（不是给 agent 选型） */
|
||
export function formatRecipeCatalogForAgent(catalog: RecipeCatalog): string {
|
||
const lines = catalog.recipes.map(
|
||
(r) => `- ${r.name}：${r.declaration}`,
|
||
);
|
||
return `【可选配方】（须由用户手动选择）\n${lines.join("\n")}`;
|
||
}
|
||
|
||
/** 注入 design-flow：用户已选配方（方法论 + 近期起点） */
|
||
export function formatSelectedRecipeForAgent(detail: RecipeDetail): string {
|
||
const lines: string[] = [
|
||
`【用户已选配方 · ${detail.name}】`,
|
||
"这是用户手动选定的设计方法，不是锁死流水线。",
|
||
"产出**增量工作流计划（DAG）**：只排近期要做的步骤；已验收步保留，可追加同技能多次调用。",
|
||
"按用户表述与配方方法论增删改未验收步骤与依赖；步骤名只能从【能力】选。",
|
||
"能力「何时用 / 何时不用」以【能力 · 可选工序】为准；本配方不重复罗列各能力调用条件。",
|
||
"禁止改选其它配方；若用户要换配方，须等用户重新选定后再编排。",
|
||
];
|
||
if (detail.declaration) lines.push(`简介：${detail.declaration}`);
|
||
if (detail.when) lines.push(`适用：${detail.when}`);
|
||
if (detail.core) {
|
||
lines.push("核心思路：");
|
||
lines.push(detail.core);
|
||
}
|
||
if (detail.process) {
|
||
lines.push("设计流程：");
|
||
lines.push(formatRecipeFieldBlock(detail.process));
|
||
}
|
||
if (detail.principles) {
|
||
lines.push("原则：");
|
||
lines.push(formatRecipeFieldBlock(detail.principles));
|
||
}
|
||
if (!detail.core && !detail.process && !detail.principles && detail.hint) {
|
||
lines.push(`调味提示（旧字段）：${detail.hint}`);
|
||
}
|
||
if (detail.seed?.steps.length) {
|
||
const stepsJson = JSON.stringify(
|
||
{
|
||
brief: detail.seed.brief,
|
||
status: detail.seed.status ?? "open",
|
||
steps: detail.seed.steps,
|
||
},
|
||
null,
|
||
2,
|
||
);
|
||
lines.push("建议近期 steps（增量起点，可改；勿一次排完全程）：");
|
||
lines.push("```json");
|
||
lines.push(stepsJson);
|
||
lines.push("```");
|
||
} else {
|
||
lines.push("建议 steps：（待作者完善 recipe.yaml；可从【能力】自行编排近期 horizon）");
|
||
}
|
||
return lines.join("\n");
|
||
}
|
||
|
||
function formatRecipeFieldBlock(value: string | string[]): string {
|
||
if (Array.isArray(value)) {
|
||
return value.map((l) => `- ${l}`).join("\n");
|
||
}
|
||
return value;
|
||
}
|
||
|
||
/** design-flow 一次注入：已选配方 + 技能池 */
|
||
export function formatDesignFlowContentBlocks(params: {
|
||
selectedRecipe?: RecipeDetail | null;
|
||
modules?: ModuleCatalog | null;
|
||
missingSelection?: boolean;
|
||
}): string[] {
|
||
const blocks: string[] = [];
|
||
if (params.missingSelection) {
|
||
blocks.push(
|
||
[
|
||
"【配方】用户尚未手动选择。",
|
||
"禁止自行猜测或替用户选定配方。",
|
||
"请 askUser 请用户从可用配方中选择，或等待用户在界面选定后再编排。",
|
||
].join("\n"),
|
||
);
|
||
} else if (params.selectedRecipe) {
|
||
blocks.push(formatSelectedRecipeForAgent(params.selectedRecipe));
|
||
}
|
||
if (params.modules) {
|
||
blocks.push(formatModuleCatalogForAgent(params.modules));
|
||
}
|
||
return blocks;
|
||
}
|
||
|
||
/** 解析并加载用户已选配方详情 */
|
||
export async function resolveSelectedRecipeDetail(params: {
|
||
skillPackRoot: string;
|
||
selectedRecipeRef?: string | null;
|
||
skillsRoot?: string;
|
||
}): Promise<RecipeDetail | null> {
|
||
const ref = parseSelectedRecipeRef(params.selectedRecipeRef);
|
||
if (!ref) return null;
|
||
const skillsRoot = params.skillsRoot ?? DEFAULT_SKILLS_ROOT;
|
||
const catalog = await loadRecipeCatalog(params.skillPackRoot, skillsRoot);
|
||
const entry = findRecipeCatalogEntry(catalog, ref);
|
||
if (!entry) return null;
|
||
return loadRecipeDetail(params.skillPackRoot, entry, skillsRoot);
|
||
}
|
||
|
||
export function validateCreationFlow(
|
||
flow: CreationFlow,
|
||
catalog: ModuleCatalog | null,
|
||
): CreationFlowValidation {
|
||
const errors: string[] = [];
|
||
const ids = flow.steps.map((s) => s.id);
|
||
const seenIds = new Set<string>();
|
||
const allowed = catalog
|
||
? new Set(catalog.modules.map((m) => m.name))
|
||
: null;
|
||
const nameCount = new Map<string, number>();
|
||
for (const step of flow.steps) {
|
||
nameCount.set(step.name, (nameCount.get(step.name) ?? 0) + 1);
|
||
}
|
||
|
||
for (let i = 0; i < flow.steps.length; i++) {
|
||
const step = flow.steps[i]!;
|
||
if (seenIds.has(step.id)) {
|
||
errors.push(`步骤 id「${step.id}」重复`);
|
||
}
|
||
seenIds.add(step.id);
|
||
|
||
if (allowed && !allowed.has(step.name)) {
|
||
errors.push(`「${step.name}」不在模块目录中`);
|
||
}
|
||
|
||
const mod = catalog?.modules.find((m) => m.name === step.name);
|
||
if (
|
||
catalog &&
|
||
(nameCount.get(step.name) ?? 0) > 1 &&
|
||
mod &&
|
||
mod.repeatable !== true
|
||
) {
|
||
errors.push(
|
||
`「${step.name}」出现多次，但目录未标 repeatable（仅可反复能力可同名多次）`,
|
||
);
|
||
}
|
||
|
||
for (const dep of step.depends_on) {
|
||
const depStep = findStepByRef(flow, dep);
|
||
if (!depStep) {
|
||
errors.push(`「${step.id}」依赖「${dep}」，但流程中没有该步骤`);
|
||
continue;
|
||
}
|
||
const depIndex = flow.steps.findIndex((s) => s.id === depStep.id);
|
||
if (depIndex >= i) {
|
||
errors.push(
|
||
`「${step.id}」依赖「${depStep.id}」，但「${depStep.id}」未排在其前面`,
|
||
);
|
||
}
|
||
}
|
||
|
||
if (mod?.params?.length) {
|
||
const missing = missingRequiredStepParams(step, mod);
|
||
if (missing.length > 0) {
|
||
const labels = missing
|
||
.map((key) => {
|
||
const spec = mod.params!.find((p) => p.key === key);
|
||
return spec ? `${key}（${spec.label}）` : key;
|
||
})
|
||
.join("、");
|
||
errors.push(
|
||
`「${step.id}」缺少必填编排参数：${labels}（须在 design-flow 钉齐后再执行）`,
|
||
);
|
||
}
|
||
}
|
||
}
|
||
|
||
return { ok: errors.length === 0, errors };
|
||
}
|
||
|
||
export function artifactTagForStep(
|
||
name: string,
|
||
catalog: ModuleCatalog | null,
|
||
): string | null {
|
||
return catalog?.modules.find((m) => m.name === name)?.artifact ?? null;
|
||
}
|
||
|
||
export function formatCreationFlowForUser(
|
||
flow: CreationFlow,
|
||
catalog?: ModuleCatalog | null,
|
||
): CreationFlowUserView {
|
||
const decl = new Map(
|
||
(catalog?.modules ?? []).map((m) => [m.name, m] as const),
|
||
);
|
||
const seenName = new Map<string, number>();
|
||
return {
|
||
brief: flow.brief,
|
||
status: flow.status,
|
||
steps: flow.steps.map((s, i) => {
|
||
const n = (seenName.get(s.name) ?? 0) + 1;
|
||
seenName.set(s.name, n);
|
||
const mod = decl.get(s.name);
|
||
const paramsMissing = missingRequiredStepParams(s, mod);
|
||
return {
|
||
order: i + 1,
|
||
id: s.id,
|
||
name: s.name,
|
||
depends_on: s.depends_on,
|
||
occurrence: n,
|
||
declaration: mod?.declaration,
|
||
repeatable: mod?.repeatable,
|
||
...(s.params ? { params: s.params } : {}),
|
||
...(paramsMissing.length > 0 ? { paramsMissing } : {}),
|
||
};
|
||
}),
|
||
};
|
||
}
|
||
|
||
export function findModuleByName(
|
||
catalog: ModuleCatalog | null | undefined,
|
||
name: string,
|
||
): ModuleCatalogEntry | null {
|
||
if (!catalog) return null;
|
||
return catalog.modules.find((m) => m.name === name) ?? null;
|
||
}
|
||
|
||
/** 已验收步骤名列表（JSON 数组或换行文本） */
|
||
export function parseAcceptedSteps(raw: unknown): string[] {
|
||
if (Array.isArray(raw)) {
|
||
return raw.map((x) => String(x).trim()).filter(Boolean);
|
||
}
|
||
if (typeof raw !== "string" || !raw.trim()) return [];
|
||
try {
|
||
const doc = JSON.parse(raw);
|
||
if (Array.isArray(doc)) {
|
||
return doc.map((x) => String(x).trim()).filter(Boolean);
|
||
}
|
||
} catch {
|
||
/* fall through */
|
||
}
|
||
return raw
|
||
.split(/[\n,]/)
|
||
.map((s) => s.trim())
|
||
.filter(Boolean);
|
||
}
|
||
|
||
/**
|
||
* 某步是否已验收：认 step.id；兼容旧会话只记了中文 name（且当时 name 唯一）。
|
||
*/
|
||
export function isStepAccepted(
|
||
step: CreationFlowStep,
|
||
acceptedStepIds: readonly string[],
|
||
): boolean {
|
||
const done = new Set(acceptedStepIds);
|
||
if (done.has(step.id)) return true;
|
||
// 旧稿：验收列表里是中文名，且 id 就是 name
|
||
if (step.id === step.name && done.has(step.name)) return true;
|
||
return false;
|
||
}
|
||
|
||
/**
|
||
* 流程中下一个待做步骤：未验收，且 depends_on 均已验收。
|
||
*/
|
||
export function nextPendingStep(
|
||
flow: CreationFlow | null,
|
||
acceptedStepIds: readonly string[],
|
||
): CreationFlowStep | null {
|
||
if (!flow?.steps.length) return null;
|
||
for (const step of flow.steps) {
|
||
if (isStepAccepted(step, acceptedStepIds)) continue;
|
||
const depsOk = step.depends_on.every((dep) => {
|
||
const depStep = findStepByRef(flow, dep);
|
||
if (!depStep) return false;
|
||
return isStepAccepted(depStep, acceptedStepIds);
|
||
});
|
||
if (depsOk) return step;
|
||
}
|
||
return null;
|
||
}
|
||
|
||
/** 当前已列出的步骤是否都已验收（不管 status） */
|
||
export function areListedStepsAccepted(
|
||
flow: CreationFlow | null,
|
||
acceptedStepIds: readonly string[],
|
||
): boolean {
|
||
if (!flow?.steps.length) return false;
|
||
return flow.steps.every((s) => isStepAccepted(s, acceptedStepIds));
|
||
}
|
||
|
||
/**
|
||
* 流程是否收束完毕：listed steps 全验收，且 status 非 open。
|
||
* status=open 或缺省但还要扩步 → 应再调 design-flow。
|
||
* 缺省 status：兼容旧固定 DAG，视为 closed。
|
||
*/
|
||
export function isCreationFlowComplete(
|
||
flow: CreationFlow | null,
|
||
acceptedStepIds: readonly string[],
|
||
): boolean {
|
||
if (!areListedStepsAccepted(flow, acceptedStepIds)) return false;
|
||
if (flow?.status === "open") return false;
|
||
return true;
|
||
}
|
||
|
||
/**
|
||
* 当前步骤做完、但 DAG 仍 open → 需要再编排（追加 / 关闭）。
|
||
*/
|
||
export function needsFlowExpansion(
|
||
flow: CreationFlow | null,
|
||
acceptedStepIds: readonly string[],
|
||
): boolean {
|
||
if (!flow?.steps.length) return true;
|
||
if (nextPendingStep(flow, acceptedStepIds)) return false;
|
||
return flow.status === "open";
|
||
}
|
||
|
||
export async function loadModulePrompt(
|
||
skillPackRoot: string,
|
||
moduleId: string,
|
||
skillsRoot = DEFAULT_SKILLS_ROOT,
|
||
): Promise<string | null> {
|
||
const fullPath = path.join(
|
||
skillsRoot,
|
||
skillPackRoot,
|
||
"modules",
|
||
moduleId,
|
||
"prompt.md",
|
||
);
|
||
try {
|
||
return await readFile(fullPath, "utf8");
|
||
} catch {
|
||
return null;
|
||
}
|
||
}
|
||
|
||
/** 依赖步骤 → 产物 tag（执行期注入；按依赖步的能力 name 映射） */
|
||
export function dependencyArtifactTags(
|
||
step: CreationFlowStep,
|
||
catalog: ModuleCatalog | null,
|
||
flow?: CreationFlow | null,
|
||
): string[] {
|
||
if (!catalog) return [];
|
||
const tags: string[] = [];
|
||
for (const dep of step.depends_on) {
|
||
const depName = flow
|
||
? findStepByRef(flow, dep)?.name ?? dep
|
||
: dep;
|
||
const art = artifactTagForStep(depName, catalog);
|
||
if (art) tags.push(art);
|
||
}
|
||
return [...new Set(tags)];
|
||
}
|
||
|
||
export type DesignStepBinding = {
|
||
step: CreationFlowStep;
|
||
module: ModuleCatalogEntry;
|
||
depTags: string[];
|
||
modulePrompt: string;
|
||
/** 程序开场白；无则本步直接调 LLM */
|
||
opening: string | null;
|
||
};
|
||
|
||
/**
|
||
* 解析 design-step 本轮绑定：当前步骤、模块 prompt、依赖 tag、产物 tag。
|
||
*/
|
||
export async function resolveDesignStepBinding(params: {
|
||
skillPackRoot: string;
|
||
flowRaw: string | null | undefined;
|
||
currentStepName?: string | null;
|
||
acceptedStepNames?: readonly string[];
|
||
skillsRoot?: string;
|
||
}): Promise<DesignStepBinding | null> {
|
||
const skillsRoot = params.skillsRoot ?? DEFAULT_SKILLS_ROOT;
|
||
const catalog = await loadModuleCatalog(params.skillPackRoot, skillsRoot);
|
||
const flow = parseCreationFlow(params.flowRaw);
|
||
if (!catalog || !flow) return null;
|
||
|
||
const accepted = params.acceptedStepNames ?? [];
|
||
let step: CreationFlowStep | null = null;
|
||
const named = params.currentStepName?.trim();
|
||
if (named) {
|
||
step = findStepByRef(flow, named);
|
||
}
|
||
if (!step) {
|
||
step = nextPendingStep(flow, accepted);
|
||
}
|
||
if (!step) return null;
|
||
|
||
const module = findModuleByName(catalog, step.name);
|
||
if (!module) return null;
|
||
|
||
const modulePromptRaw =
|
||
(await loadModulePrompt(params.skillPackRoot, module.id, skillsRoot)) ??
|
||
`# ${module.name}\n\n（模块 prompt.md 缺失，请补充 skills/.../modules/${module.id}/prompt.md）`;
|
||
|
||
const opening =
|
||
module.opening?.trim() || extractModuleOpening(modulePromptRaw) || null;
|
||
|
||
return {
|
||
step,
|
||
module,
|
||
depTags: dependencyArtifactTags(step, catalog, flow),
|
||
modulePrompt: formatModulePromptForLlm(modulePromptRaw),
|
||
opening,
|
||
};
|
||
}
|